framework: port the credential-helper regression suite (byte-faithful from brain 15f6979a; verified green from the stack tree)

Co-authored-by: marcie <[email protected]>

.env.example

@@ -1,156 +1,14 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# Mosaic — Environment Variables Reference
-# Copy this file to .env and fill in the values for your deployment.
-# Lines beginning with # are comments; optional vars are commented out.
-# ─────────────────────────────────────────────────────────────────────────────
+# Mosaic Stack standalone deployment (compose `stack` profile)
+# Copy to .env and adjust. Port overrides exist because the defaults
+# collide with common host services (and with the dev compose itself).
+PG_HOST_PORT=5433
+VALKEY_HOST_PORT=6380
+GATEWAY_HOST_PORT=14242
+# Registry image override (defaults to a local build of docker/gateway.Dockerfile):
+# GATEWAY_IMAGE=git.mosaicstack.dev/mosaicstack/stack/gateway:sha-acf640d
 
-
-# ─── Database (PostgreSQL 17 + pgvector) ─────────────────────────────────────
-# Full connection string used by the gateway, ORM, and migration runner.
-# Port 5433 avoids conflict with a host-side PostgreSQL instance.
-DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
-
-# Docker Compose host-port override for the PostgreSQL container (default: 5433)
-# PG_HOST_PORT=5433
-
-
-# ─── Queue (Valkey 8 / Redis-compatible) ─────────────────────────────────────
-# Port 6380 avoids conflict with a host-side Redis/Valkey instance.
-VALKEY_URL=redis://localhost:6380
-
-# Docker Compose host-port override for the Valkey container (default: 6380)
-# VALKEY_HOST_PORT=6380
-
-
-# ─── Gateway ─────────────────────────────────────────────────────────────────
-# TCP port the NestJS/Fastify gateway listens on (default: 14242)
-GATEWAY_PORT=14242
-
-# Comma-separated list of allowed CORS origins.
-# Must include the web app origin in production.
-GATEWAY_CORS_ORIGIN=http://localhost:3000
-
-
-# ─── Auth (BetterAuth) ───────────────────────────────────────────────────────
-# REQUIRED — random secret used to sign sessions and tokens.
-# Generate with: openssl rand -base64 32
-BETTER_AUTH_SECRET=change-me-to-a-random-32-char-string
-
-# Public base URL of the gateway (used by BetterAuth for callback URLs)
-BETTER_AUTH_URL=http://localhost:14242
-
-
-# ─── Web App (SPA) ───────────────────────────────────────────────────────────
-# Directory holding the built SPA bundle (vite build output). When set, the
-# gateway serves the SPA same-origin; when unset (dev), run the Vite dev
-# server (pnpm --filter @mosaicstack/web dev), which proxies to the gateway.
-# safe-default: unset in dev — SPA serving is an opt-in production concern
-#WEB_DIST_DIR=apps/web/dist
-
-
-# ─── OpenTelemetry ───────────────────────────────────────────────────────────
-# OTLP HTTP endpoint (otel-collector or any OpenTelemetry-compatible backend)
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-
-# Service name shown in traces
-OTEL_SERVICE_NAME=mosaic-gateway
-
-
-# ─── AI Providers ────────────────────────────────────────────────────────────
-
-# Ollama (local models — set OLLAMA_BASE_URL to enable)
-# OLLAMA_BASE_URL=http://localhost:11434
-# OLLAMA_HOST is a legacy alias for OLLAMA_BASE_URL
-# OLLAMA_HOST=http://localhost:11434
-# Comma-separated list of Ollama model IDs to register (default: llama3.2,codellama,mistral)
-# OLLAMA_MODELS=llama3.2,codellama,mistral
-
-# Anthropic (claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5)
-# ANTHROPIC_API_KEY=sk-ant-...
-
-# OpenAI (gpt-4o, gpt-4o-mini, o3-mini)
-# OPENAI_API_KEY=sk-...
-
-# Z.ai / GLM (glm-4.5, glm-4.5-air, glm-4.5-flash)
-# ZAI_API_KEY=...
-
-# Custom providers — JSON array of provider configs
-# Format: [{"id":"<id>","baseUrl":"<url>","apiKey":"<key>","models":[{"id":"<model-id>","name":"<label>"}]}]
-# MOSAIC_CUSTOM_PROVIDERS=
-
-
-# ─── Embedding Service ───────────────────────────────────────────────────────
-# OpenAI-compatible embeddings endpoint (default: OpenAI)
-# EMBEDDING_API_URL=https://api.openai.com/v1
-# EMBEDDING_MODEL=text-embedding-3-small
-
-
-# ─── Log Summarization Service ───────────────────────────────────────────────
-# OpenAI-compatible chat completions endpoint for log summarization (default: OpenAI)
-# SUMMARIZATION_API_URL=https://api.openai.com/v1
-# SUMMARIZATION_MODEL=gpt-4o-mini
-
-# Cron schedule for summarization job (default: every 6 hours)
-# SUMMARIZATION_CRON=0 */6 * * *
-
-# Cron schedule for log tier management (default: daily at 03:00)
-# TIER_MANAGEMENT_CRON=0 3 * * *
-
-
-# ─── Agent ───────────────────────────────────────────────────────────────────
-# Filesystem sandbox root for agent file tools (default: process.cwd())
-# AGENT_FILE_SANDBOX_DIR=/var/lib/mosaic/sandbox
-
-# Comma-separated list of tool names available to non-admin users.
-# Leave unset to allow all tools for all authenticated users.
-# AGENT_USER_TOOLS=read_file,list_directory,search_files
-
-# System prompt injected into every agent session (optional)
-# AGENT_SYSTEM_PROMPT=You are a helpful assistant.
-
-
-# ─── MCP Servers ─────────────────────────────────────────────────────────────
-# JSON array of MCP server configs — set to enable MCP tool integration.
-# Each entry: {"name":"<id>","url":"<http-or-sse-url>"}
-# MCP_SERVERS=[{"name":"my-mcp","url":"http://localhost:3100/sse"}]
-
-
-# ─── Coordinator ─────────────────────────────────────────────────────────────
-# Root directory used to scope coordinator (worktree/repo) operations.
-# Defaults to the monorepo root auto-detected from process.cwd().
-# MOSAIC_WORKSPACE_ROOT=/home/user/projects/mosaic
-
-
-# ─── Discord Plugin (optional — set DISCORD_BOT_TOKEN to enable) ─────────────
-# DISCORD_BOT_TOKEN=
-# DISCORD_GUILD_ID=
-# DISCORD_GATEWAY_URL=http://localhost:14242
-
-
-# ─── Telegram Plugin (optional — set TELEGRAM_BOT_TOKEN to enable) ───────────
-# TELEGRAM_BOT_TOKEN=
-# TELEGRAM_GATEWAY_URL=http://localhost:14242
-
-
-# ─── SSO Providers (add credentials to enable) ───────────────────────────────
-
-# --- Authentik (optional — set AUTHENTIK_CLIENT_ID to enable) ---
-# AUTHENTIK_ISSUER=https://auth.example.com/application/o/mosaic/
-# AUTHENTIK_CLIENT_ID=
-# AUTHENTIK_CLIENT_SECRET=
-
-# --- WorkOS (optional — set WORKOS_CLIENT_ID to enable) ---
-# WORKOS_ISSUER=https://your-company.authkit.app
-# WORKOS_CLIENT_ID=client_...
-# WORKOS_CLIENT_SECRET=sk_live_...
-
-# --- Keycloak (optional — set KEYCLOAK_CLIENT_ID to enable) ---
-# KEYCLOAK_ISSUER=https://auth.example.com/realms/master
-# Legacy alternative if you prefer to compose the issuer from separate vars:
-# KEYCLOAK_URL=https://auth.example.com
-# KEYCLOAK_REALM=master
-# KEYCLOAK_CLIENT_ID=mosaic
-# KEYCLOAK_CLIENT_SECRET=
-
-# The web login page discovers configured providers dynamically from
-# GET /api/sso/providers. No NEXT_PUBLIC_* provider feature flag is required.
+# Optional explicit dogfood overlay (docker-compose.dogfood.yml).
+# Both paths are required when that overlay is used. Use a dedicated next-based
+# worktree and the external home of the unprivileged stack-dogfood seat.
+# MOSAIC_DOGFOOD_WORKTREE=/home/example/src/mosaic-stack-worktrees/dogfood-1487
+# MOSAIC_DOGFOOD_SEAT_HOME=/home/example/.mosaic/fleet/agents/stack-dogfood

README.md

@@ -208,6 +208,46 @@ mosaic telemetry upload        # Dry-run unless opted in
 
 Consent state is persisted in config. Remote upload is a no-op until you run `mosaic telemetry opt-in`.
 
+## Standalone container deployment
+
+The `stack` profile runs PostgreSQL, Valkey, the gateway, and the bundled webUI. Copy
+`.env.example` to `.env`, generate `BETTER_AUTH_SECRET`, then start the profile:
+
+```bash
+cp .env.example .env
+printf 'BETTER_AUTH_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
+docker compose --profile stack up -d
+```
+
+The optional dogfood overlay gives one dedicated in-stack agent a writable stack
+worktree and its own read-only credential slot. It does not mount the fleet brain or
+any other seat. Prepare a `next`-based worktree and an unprivileged `stack-dogfood`
+seat outside the container, then set these paths in `.env`:
+
+```dotenv
+MOSAIC_DOGFOOD_WORKTREE=/path/to/mosaic-stack-worktrees/dogfood-1487
+MOSAIC_DOGFOOD_SEAT_HOME=/path/to/.mosaic/fleet/agents/stack-dogfood
+```
+
+The seat home must contain only that seat's credential at
+`secrets/gitea-mosaicstack-stack-dogfood.token`. Never place the token value in
+`.env`. Start the overlay with:
+
+```bash
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.dogfood.yml \
+  --profile stack up -d
+```
+
+The overlay scopes regular-agent tools to the mounted checkout. For issue and PR
+operations, instruct the agent to use `/opt/mosaic/tools/git/`. The gateway image
+configures `git-credential-mosaic` as Git's system credential helper, so pushes and
+`pr-create.sh` resolve only the `stack-dogfood` slot and fail if it is absent.
+
+This deployment route is separate from the local source-development restrictions
+below.
+
 ## Development
 
 ### Prerequisites

apps/gateway/src/__tests__/hierarchy-route-inventory.test.ts

@@ -4,14 +4,14 @@ import { AppModule } from '../app.module.js';
 import { HierarchyModule } from '../hierarchy/hierarchy.module.js';
 
 /**
- * Hierarchy route-inventory baseline (contract 1 §6.3(a)).
+ * Hierarchy route inventory (contract 1 §6.3).
  *
- * M4-1b-i ships the audit event + outbox machinery with NO mutation routes:
- * the hierarchy command family (controllers + DTOs) lands in M4-1b-ii once
- * contract 2 merges. This witness enumerates every route the AppModule graph
- * declares and pins that baseline, so a hierarchy route appearing before its
- * command-family witnesses exist fails here first. When M4-1b-ii lands, this
- * baseline is replaced by an exact inventory of the command family.
+ * The hierarchy command family is a CLOSED enumeration asserted here, not a
+ * prose claim: every hierarchy-flavored route the AppModule graph declares
+ * must appear in HIERARCHY_COMMAND_FAMILY, and vice versa. Adding or
+ * removing a hierarchy route without updating this inventory (and its
+ * witnesses) fails CI first. This replaces the M4-1b-i zero-routes
+ * baseline.
  */
 
 interface RouteEntry {
@@ -77,7 +77,32 @@ function routesOf(controller: Type<unknown>): RouteEntry[] {
   return routes;
 }
 
-describe('hierarchy route-inventory baseline (§6.3(a))', () => {
+/**
+ * The closed command family (contract 1 §5, M4-1b-ii). Every entry is a
+ * mutation audited via the M4-1b-i path or one of the two ratified reads
+ * (granted companies, the §2.8 directory carve-out).
+ */
+const HIERARCHY_COMMAND_FAMILY = [
+  'POST /api/hierarchy/companies',
+  'GET /api/hierarchy/companies',
+  'GET /api/hierarchy/companies/directory',
+  'POST /api/hierarchy/companies/:id/rename',
+  'POST /api/hierarchy/companies/:id/visibility',
+  'DELETE /api/hierarchy/companies/:id',
+  'POST /api/hierarchy/estates',
+  'POST /api/hierarchy/estates/:id/rename',
+  'POST /api/hierarchy/estates/:id/transfer',
+  'DELETE /api/hierarchy/estates/:id',
+  'POST /api/hierarchy/platform-projects',
+  'POST /api/hierarchy/platform-projects/:id/rename',
+  'POST /api/hierarchy/platform-projects/:id/transfer',
+  'DELETE /api/hierarchy/platform-projects/:id',
+  'POST /api/hierarchy/grants',
+  'POST /api/hierarchy/grants/:id/change',
+  'DELETE /api/hierarchy/grants/:id',
+] as const;
+
+describe('hierarchy route inventory (§6.3)', () => {
   const inventory = collectControllers(AppModule).flatMap(routesOf);
 
   it('control: the enumeration sees the known route surface', () => {
@@ -88,19 +113,21 @@ describe('hierarchy route-inventory baseline (§6.3(a))', () => {
     expect(inventory.length).toBeGreaterThan(20);
   });
 
-  it('declares zero hierarchy mutation routes before M4-1b-ii', () => {
-    const hierarchyRoutes = inventory.filter((r) =>
-      /hierarch|compan|estate|platform[-_]?project/i.test(r.path),
-    );
-    expect(
-      hierarchyRoutes,
-      'a hierarchy route landed without replacing the §6.3(a) baseline with a command-family inventory',
-    ).toEqual([]);
+  it('the hierarchy surface is exactly the declared command family', () => {
+    const hierarchyRoutes = inventory
+      .filter((r) => /hierarch|compan|estate|platform[-_]?project/i.test(r.path))
+      .map((r) => `${r.method} ${r.path}`)
+      .sort();
+    expect(hierarchyRoutes).toEqual([...HIERARCHY_COMMAND_FAMILY].sort());
   });
 
-  it('HierarchyModule itself declares no controllers', () => {
-    expect((Reflect.getMetadata('controllers', HierarchyModule) ?? []) as unknown[]).toEqual([]);
-    const hierarchyControllers = collectControllers(HierarchyModule);
-    expect(hierarchyControllers).toEqual([]);
+  it('every command-family route lives on HierarchyController inside HierarchyModule', () => {
+    const controllers = collectControllers(HierarchyModule);
+    expect(controllers.map((c) => c.name)).toEqual(['HierarchyController']);
+    const declared = controllers
+      .flatMap(routesOf)
+      .map((r) => `${r.method} ${r.path}`)
+      .sort();
+    expect(declared).toEqual([...HIERARCHY_COMMAND_FAMILY].sort());
   });
 });

apps/gateway/src/app.module.ts

@@ -25,6 +25,7 @@ import { HarnessModule } from './harness/harness.module.js';
 import { ReloadModule } from './reload/reload.module.js';
 import { WorkspaceModule } from './workspace/workspace.module.js';
 import { HierarchyModule } from './hierarchy/hierarchy.module.js';
+import { EnrollmentModule } from './enrollment/enrollment.module.js';
 import { QueueModule } from './queue/queue.module.js';
 import { FederationModule } from './federation/federation.module.js';
 import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
@@ -67,6 +68,7 @@ const federationEnabled = loadConfig(resolveGatewayConfigPath()).tier === 'feder
     ReloadModule,
     WorkspaceModule,
     HierarchyModule,
+    EnrollmentModule,
     ...(federationEnabled ? [FederationModule] : []),
   ],
   controllers: [HealthController],

apps/gateway/src/commands/command-authorization.service.spec.ts

@@ -61,6 +61,33 @@ describe('CommandAuthorizationService', () => {
     ).toBe(false);
   });
 
+  it('denies non-admin scopes to a platform admin (contract 2 §1.1 bypass retirement)', async (): Promise<void> => {
+    const service = createService('admin');
+    for (const scope of ['core', 'agent', 'skill', 'plugin'] as const) {
+      const command: CommandDef = { ...adminCommand, name: `probe-${scope}`, scope };
+      expect(
+        (await service.authorize(command, { ...payload, command: command.name }, 'admin-1'))
+          .allowed,
+      ).toBe(false);
+    }
+  });
+
+  it('allows member core/agent scopes and denies skill/plugin (deny-by-default)', async (): Promise<void> => {
+    const service = createService('member');
+    for (const [scope, allowed] of [
+      ['core', true],
+      ['agent', true],
+      ['skill', false],
+      ['plugin', false],
+    ] as const) {
+      const command: CommandDef = { ...adminCommand, name: `probe-${scope}`, scope };
+      expect(
+        (await service.authorize(command, { ...payload, command: command.name }, 'member-1'))
+          .allowed,
+      ).toBe(allowed);
+    }
+  });
+
   it('denies a malformed durable approval expiry instead of treating it as unexpired', async (): Promise<void> => {
     const entries = new Map<string, string>();
     const action = {

apps/gateway/src/commands/command-authorization.service.ts

@@ -154,8 +154,15 @@ export class CommandAuthorizationService {
     return role === 'admin' || role === 'member' || role === 'viewer' ? role : null;
   }
 
+  /**
+   * Contract 2 §1.1: platform admin confers instance administration only —
+   * the former admin-passes-every-scope short-circuit is retired. Admin
+   * reaches exactly the admin scope; core/agent scopes belong to the member
+   * role; skill/plugin scopes stay deny-for-all until a grant mapping names
+   * them (§3.1 deny-by-default).
+   */
   private hasScope(role: CommandRole, scope: CommandDef['scope']): boolean {
-    if (role === 'admin') return true;
+    if (scope === 'admin') return role === 'admin';
     return role === 'member' && (scope === 'core' || scope === 'agent');
   }
 

apps/gateway/src/enrollment/enrollment-commands.integration.test.ts

@@ -0,0 +1,508 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { Test, type TestingModule } from '@nestjs/testing';
+import { Logger, ValidationPipe, type ExecutionContext } from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import supertest from 'supertest';
+import { unseal } from '@mosaicstack/auth';
+import {
+  agentAuditEvents,
+  agentIdempotencyFence,
+  agentOutbox,
+  agents,
+  and,
+  createPgliteDb,
+  eq,
+  providerCredentials,
+  runPgliteMigrations,
+  sql,
+  users,
+  type DbHandle,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { HarnessRegistry } from '../harness/harness.registry.js';
+import { HARNESS_REGISTRY } from '../harness/harness.tokens.js';
+import { FakeHarnessAdapter } from '../harness/testing/fake-harness.adapter.js';
+import { EnrollmentController } from './enrollment.controller.js';
+import {
+  EnrollmentRepository,
+  type EnrollAgentInput,
+  type EnrollmentResult,
+  type EnrolledAgentView,
+} from './enrollment.repository.js';
+import { EnrollmentService } from './enrollment.service.js';
+
+/**
+ * Command-level witnesses for the agent enrollment family (M4-4b) — design
+ * docs/plans/2026-08-29-agent-enrollment-command-design.md §5 items 1–9 and
+ * 11 (item 10, CLI parity, lives in packages/mosaic). Schema-level
+ * constraints are witnessed in packages/db/src/agent-enrollment.witness.test.ts.
+ *
+ * The suite runs the REAL repository/service/controller graph over PGlite,
+ * with only AuthGuard overridden (a session store is out of scope; the
+ * override binds request.user exactly as the real guard does). The §6.3
+ * static companions — no `any`-typed boundary pass-through, a single audit
+ * emitter (EnrollmentRepository.appendEvent) — are code-surface properties
+ * reviewed on the PR, not runtime probes.
+ */
+describe('enrollment commands integration', (): void => {
+  let dataDir: string;
+  let handle: DbHandle;
+  let moduleRef: TestingModule;
+  let app: NestFastifyApplication;
+  let http: ReturnType<typeof supertest>;
+  let repo: EnrollmentRepository;
+  let previousAuthSecret: string | undefined;
+
+  const OWNER = 'enr-owner';
+  const ADMIN = 'enr-admin';
+  const STRANGER = 'enr-stranger';
+  const HARNESS = 'fake-harness';
+  /** Never-echo probe value (§5.1). Unique enough that any leak is unambiguous. */
+  const SECRET = `enr-secret-value-${randomUUID()}`;
+
+  /** The HTTP-leg acting user; the overridden guard binds it per request. */
+  let currentUserId = OWNER;
+
+  const enrollInput = (overrides: Partial<EnrollAgentInput> = {}): EnrollAgentInput => ({
+    actorId: OWNER,
+    harness: HARNESS,
+    name: `Agent ${randomUUID().slice(0, 8)}`,
+    persona: null,
+    model: 'anthropic/claude-test',
+    provider: `prov-${randomUUID().slice(0, 8)}`,
+    credential: { mode: 'intake', type: 'api_key', value: SECRET },
+    idempotencyKey: randomUUID(),
+    ...overrides,
+  });
+
+  function expectOk<T>(result: EnrollmentResult<T>): { ok: true; correlationId: string } & T {
+    if (!result.ok) throw new Error(`expected ok, got ${JSON.stringify(result)}`);
+    return result;
+  }
+
+  function expectFail<T>(
+    result: EnrollmentResult<T>,
+    error: string,
+  ): { ok: false; error: string; message: string; correlationId: string } {
+    if (result.ok) throw new Error(`expected ${error}, got ok`);
+    expect(result.error).toBe(error);
+    return result;
+  }
+
+  const fenceForKey = (key: string) =>
+    handle.db
+      .select()
+      .from(agentIdempotencyFence)
+      .where(eq(agentIdempotencyFence.idempotencyKey, key));
+
+  const eventsForAgent = (agentId: string) =>
+    handle.db.select().from(agentAuditEvents).where(eq(agentAuditEvents.agentId, agentId));
+
+  const agentsNamed = (name: string) =>
+    handle.db.select().from(agents).where(eq(agents.name, name));
+
+  const credentialsFor = (userId: string, provider: string) =>
+    handle.db
+      .select()
+      .from(providerCredentials)
+      .where(
+        and(eq(providerCredentials.userId, userId), eq(providerCredentials.provider, provider)),
+      );
+
+  const allOutbox = () => handle.db.select().from(agentOutbox);
+
+  beforeAll(async (): Promise<void> => {
+    previousAuthSecret = process.env['BETTER_AUTH_SECRET'];
+    process.env['BETTER_AUTH_SECRET'] = 'enrollment-witness-sealing-key';
+
+    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-gateway-enrollment-commands-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+
+    const registry = new HarnessRegistry();
+    registry.register(new FakeHarnessAdapter({ id: HARNESS }));
+
+    moduleRef = await Test.createTestingModule({
+      controllers: [EnrollmentController],
+      providers: [
+        EnrollmentRepository,
+        EnrollmentService,
+        { provide: DB, useValue: handle.db },
+        { provide: HARNESS_REGISTRY, useValue: registry },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue({
+        canActivate: (ctx: ExecutionContext): boolean => {
+          const request = ctx.switchToHttp().getRequest<{ user?: unknown }>();
+          request.user = { id: currentUserId };
+          return true;
+        },
+      })
+      .compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    // Mirror main.ts exactly — the closure witnesses depend on these options.
+    app.useGlobalPipes(
+      new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }),
+    );
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+    http = supertest(app.getHttpServer());
+    repo = moduleRef.get(EnrollmentRepository);
+
+    await handle.db.insert(users).values([
+      { id: OWNER, name: 'Owner', email: `${OWNER}@example.com` },
+      { id: ADMIN, name: 'Admin', email: `${ADMIN}@example.com`, role: 'admin' },
+      { id: STRANGER, name: 'Stranger', email: `${STRANGER}@example.com` },
+    ]);
+  });
+
+  afterAll(async (): Promise<void> => {
+    await app?.close();
+    await handle.close();
+    await rm(dataDir, { recursive: true, force: true });
+    if (previousAuthSecret === undefined) delete process.env['BETTER_AUTH_SECRET'];
+    else process.env['BETTER_AUTH_SECRET'] = previousAuthSecret;
+  });
+
+  // ── §5.7 wizard-facing zero-mutation (runs FIRST: no call → zero rows) ────
+
+  it('zero-mutation: with no enrollment invocation the family tables hold zero rows', async () => {
+    expect(await handle.db.select().from(agents)).toHaveLength(0);
+    expect(await handle.db.select().from(agentAuditEvents)).toHaveLength(0);
+    expect(await handle.db.select().from(agentOutbox)).toHaveLength(0);
+    expect(await handle.db.select().from(agentIdempotencyFence)).toHaveLength(0);
+  });
+
+  // ── §5.1 never-echo + §5.2 sealed single-copy ─────────────────────────────
+
+  it('never echoes the intake credential value: HTTP result, audit, outbox, fence, and logs are clean', async () => {
+    const logSink: string[] = [];
+    const logSpies = (['log', 'error', 'warn', 'debug', 'verbose'] as const).map((method) =>
+      vi.spyOn(Logger.prototype, method).mockImplementation((...args: unknown[]) => {
+        logSink.push(args.map(String).join(' '));
+      }),
+    );
+    try {
+      currentUserId = OWNER;
+      const provider = `prov-echo-${randomUUID().slice(0, 8)}`;
+      const res = await http.post('/api/enrollment/agents').send({
+        harness: HARNESS,
+        name: 'Echo Probe',
+        persona: 'a persona',
+        model: 'anthropic/claude-test',
+        provider,
+        credential: { mode: 'intake', type: 'api_key', value: SECRET },
+        idempotencyKey: randomUUID(),
+      });
+      expect(res.status).toBe(201);
+      expect(res.text).not.toContain(SECRET);
+      const agentId = (res.body as { agent: EnrolledAgentView }).agent.id;
+
+      const events = await eventsForAgent(agentId);
+      expect(events).toHaveLength(1);
+      expect(JSON.stringify(events)).not.toContain(SECRET);
+      expect(JSON.stringify(await allOutbox())).not.toContain(SECRET);
+      const fences = await handle.db
+        .select()
+        .from(agentIdempotencyFence)
+        .where(eq(agentIdempotencyFence.outcomeAgentId, agentId));
+      expect(fences).toHaveLength(1);
+      expect(JSON.stringify(fences)).not.toContain(SECRET);
+      expect(logSink.join('\n')).not.toContain(SECRET);
+
+      // §5.2 sealed single-copy: exactly one provider_credentials row, sealed
+      // at rest, and it round-trips through unseal — no plaintext column.
+      const creds = await credentialsFor(OWNER, provider);
+      expect(creds).toHaveLength(1);
+      expect(creds[0]?.encryptedValue).not.toBe(SECRET);
+      expect(creds[0]?.encryptedValue).not.toContain(SECRET);
+      expect(unseal(creds[0]?.encryptedValue as string)).toBe(SECRET);
+    } finally {
+      logSpies.forEach((spy) => spy.mockRestore());
+    }
+  });
+
+  it('the agents table itself has no credential-bearing column (§5.2)', async () => {
+    const result = (await handle.db.execute(
+      sql`select column_name from information_schema.columns where table_name = 'agents'`,
+    )) as unknown as { rows?: Array<{ column_name: string }> } & Array<{ column_name: string }>;
+    const names = (result.rows ?? result).map((row) => row.column_name);
+    expect(names.length).toBeGreaterThan(0);
+    for (const name of names) {
+      expect(name).not.toMatch(/credential|secret|token|api_key/i);
+    }
+  });
+
+  // ── §5.3 reference resolution ─────────────────────────────────────────────
+
+  it('refuses an unresolvable credential reference with precondition_failed and creates nothing', async () => {
+    const input = enrollInput({ credential: { mode: 'reference' } });
+    const result = await repo.enroll(input);
+    expectFail(result, 'precondition_failed');
+    expect(await agentsNamed(input.name)).toHaveLength(0);
+    expect(await fenceForKey(input.idempotencyKey)).toHaveLength(0);
+  });
+
+  it('resolves a reference credential stored earlier for (actor, provider)', async () => {
+    const provider = `prov-ref-${randomUUID().slice(0, 8)}`;
+    const seeded = expectOk(await repo.enroll(enrollInput({ provider })));
+    const result = expectOk(
+      await repo.enroll(enrollInput({ provider, credential: { mode: 'reference' } })),
+    );
+    expect(result.agent.id).not.toBe(seeded.agent.id);
+    expect(await credentialsFor(OWNER, provider)).toHaveLength(1);
+  });
+
+  // ── §5.4 harness refusals, both codes ────────────────────────────────────
+
+  it('refuses a syntactically invalid harness as validation_failed and a registry miss as precondition_failed', async () => {
+    const blank = await repo.enroll(enrollInput({ harness: '   ' }));
+    expectFail(blank, 'validation_failed');
+    const miss = await repo.enroll(enrollInput({ harness: 'well-formed-but-unregistered' }));
+    expectFail(miss, 'precondition_failed');
+
+    currentUserId = OWNER;
+    const httpBlank = await http.post('/api/enrollment/agents').send({
+      harness: '',
+      name: 'H',
+      model: 'm',
+      provider: 'p',
+      credential: { mode: 'reference' },
+      idempotencyKey: randomUUID(),
+    });
+    expect(httpBlank.status).toBe(400);
+  });
+
+  // ── §5.5 idempotency set (contract 3 §4.3) ───────────────────────────────
+
+  it('actor-bound replay returns the recorded outcome and executes nothing new', async () => {
+    const input = enrollInput();
+    const first = expectOk(await repo.enroll(input));
+    const replay = expectOk(await repo.enroll({ ...input, correlationId: randomUUID() }));
+    expect(replay.agent.id).toBe(first.agent.id);
+
+    expect(await agentsNamed(input.name)).toHaveLength(1);
+    expect(await fenceForKey(input.idempotencyKey)).toHaveLength(1);
+    const events = await eventsForAgent(first.agent.id);
+    expect(events.filter((e) => e.eventType === 'agent.enrolled')).toHaveLength(1);
+    // A passing replay appends exactly the non-mutation access event.
+    const replayed = events.filter((e) => e.eventType === 'agent.enrollment.replayed');
+    expect(replayed).toHaveLength(1);
+    expect((replayed[0]?.payload as { fenceId?: string }).fenceId).toBeDefined();
+  });
+
+  it('payload-digest mismatch on a recorded key refuses with the single bounded conflict shape', async () => {
+    const input = enrollInput();
+    expectOk(await repo.enroll(input));
+    const mismatch = await repo.enroll({ ...input, name: `${input.name} CHANGED` });
+    const failure = expectFail(mismatch, 'conflict');
+    expect(failure.message).toBe('idempotency conflict');
+  });
+
+  it('replay-mode and scope mismatches on the recorded fence each refuse as the same constant conflict', async () => {
+    const modeInput = enrollInput();
+    expectOk(await repo.enroll(modeInput));
+    await handle.db
+      .update(agentIdempotencyFence)
+      .set({ replayMode: 'shared' })
+      .where(eq(agentIdempotencyFence.idempotencyKey, modeInput.idempotencyKey));
+    const modeFailure = expectFail(await repo.enroll(modeInput), 'conflict');
+
+    const scopeInput = enrollInput();
+    expectOk(await repo.enroll(scopeInput));
+    await handle.db
+      .update(agentIdempotencyFence)
+      .set({ authorizationScope: 'some-other-scope' })
+      .where(eq(agentIdempotencyFence.idempotencyKey, scopeInput.idempotencyKey));
+    const scopeFailure = expectFail(await repo.enroll(scopeInput), 'conflict');
+
+    expect(modeFailure.message).toBe(scopeFailure.message);
+  });
+
+  it('a different actor replaying an actor-bound key is refused conflict, learning nothing', async () => {
+    const input = enrollInput();
+    expectOk(await repo.enroll(input));
+    const failure = expectFail(await repo.enroll({ ...input, actorId: STRANGER }), 'conflict');
+    expect(failure.message).toBe('idempotency conflict');
+  });
+
+  it('a replay is re-authorized fresh: revoked target authority refuses instead of replaying', async () => {
+    const input = enrollInput();
+    const first = expectOk(await repo.enroll(input));
+    // Simulate the legacy CRUD DELETE path removing the outcome agent: the
+    // submitter no longer holds read authority on the referenced row.
+    await handle.db.delete(agents).where(eq(agents.id, first.agent.id));
+    expectFail(await repo.enroll(input), 'conflict');
+  });
+
+  it('a shared replay-mode declaration is refused validation_failed with nothing executed and no fence row', async () => {
+    const input = enrollInput({ replayMode: 'shared' });
+    expectFail(await repo.enroll(input), 'validation_failed');
+    expect(await agentsNamed(input.name)).toHaveLength(0);
+    expect(await fenceForKey(input.idempotencyKey)).toHaveLength(0);
+
+    currentUserId = OWNER;
+    const key = randomUUID();
+    const res = await http.post('/api/enrollment/agents').send({
+      harness: HARNESS,
+      name: 'Shared Probe',
+      model: 'm',
+      provider: 'p',
+      credential: { mode: 'reference' },
+      idempotencyKey: key,
+      replayMode: 'shared',
+    });
+    expect(res.status).toBe(400);
+    expect(await fenceForKey(key)).toHaveLength(0);
+  });
+
+  it('two concurrent same-key submissions produce exactly one mutation, the loser resolving as a replay', async () => {
+    const input = enrollInput();
+    const [a, b] = await Promise.all([
+      repo.enroll(input),
+      repo.enroll({ ...input, correlationId: randomUUID() }),
+    ]);
+    const okA = expectOk(a);
+    const okB = expectOk(b);
+    expect(okA.agent.id).toBe(okB.agent.id);
+    expect(await agentsNamed(input.name)).toHaveLength(1);
+    expect(await fenceForKey(input.idempotencyKey)).toHaveLength(1);
+    const events = await eventsForAgent(okA.agent.id);
+    expect(events.filter((e) => e.eventType === 'agent.enrolled')).toHaveLength(1);
+    expect(events.filter((e) => e.eventType === 'agent.enrollment.replayed')).toHaveLength(1);
+  });
+
+  // ── §5.6 same-tx atomicity fault injection ───────────────────────────────
+
+  it('rolls everything back on failure at each write point — no orphan credential survives', async () => {
+    const injectionPoints = [
+      'writeSealedCredential',
+      'insertAgentRow',
+      'insertFenceRow',
+      'appendEvent',
+      'insertOutboxRow',
+    ] as const;
+
+    for (const point of injectionPoints) {
+      const input = enrollInput();
+      const spy = vi.spyOn(repo, point).mockImplementationOnce(() => {
+        throw new Error(`injected ${point} fault`);
+      });
+      try {
+        const result = await repo.enroll(input);
+        expectFail(result, 'internal_fault');
+        expect(await agentsNamed(input.name)).toHaveLength(0);
+        expect(await fenceForKey(input.idempotencyKey)).toHaveLength(0);
+        // Injection at fence/audit/outbox fires AFTER the sealed credential
+        // write's statement ran — the rollback must leave no orphan row.
+        expect(await credentialsFor(OWNER, input.provider)).toHaveLength(0);
+      } finally {
+        spy.mockRestore();
+      }
+    }
+  });
+
+  // ── §5.8 is_system closure ───────────────────────────────────────────────
+
+  it('rejects an is_system injection attempt at the DTO boundary', async () => {
+    currentUserId = OWNER;
+    const key = randomUUID();
+    const res = await http.post('/api/enrollment/agents').send({
+      harness: HARNESS,
+      name: 'System Probe',
+      model: 'm',
+      provider: 'p',
+      credential: { mode: 'reference' },
+      idempotencyKey: key,
+      isSystem: true,
+    });
+    expect(res.status).toBe(400);
+    expect(await fenceForKey(key)).toHaveLength(0);
+  });
+
+  // ── §5.9 correlation + no-existence-oracle ───────────────────────────────
+
+  it('carries a submitted correlation id into the result, the audit event, and the outbox record', async () => {
+    const correlationId = randomUUID();
+    const input = enrollInput({ correlationId });
+    const result = expectOk(await repo.enroll(input));
+    expect(result.correlationId).toBe(correlationId);
+    const events = await eventsForAgent(result.agent.id);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.correlationId).toBe(correlationId);
+    const outboxRows = await handle.db
+      .select()
+      .from(agentOutbox)
+      .where(eq(agentOutbox.eventId, events[0]?.id as string));
+    expect(outboxRows).toHaveLength(1);
+    expect(outboxRows[0]?.correlationId).toBe(correlationId);
+
+    // Refusals carry the correlation envelope too (contract 5 §4.3).
+    const refusal = expectFail(
+      await repo.enroll({ ...input, name: 'changed name', correlationId }),
+      'conflict',
+    );
+    expect(refusal.correlationId).toBe(correlationId);
+  });
+
+  it('agent.enrollment.get returns owner and admin reads with the correlation envelope, no idempotency key', async () => {
+    const enrolled = expectOk(await repo.enroll(enrollInput()));
+    const correlationId = randomUUID();
+    const asOwner = expectOk(await repo.getEnrollment(OWNER, enrolled.agent.id, correlationId));
+    expect(asOwner.correlationId).toBe(correlationId);
+    expect(asOwner.agent.id).toBe(enrolled.agent.id);
+    const asAdmin = expectOk(await repo.getEnrollment(ADMIN, enrolled.agent.id));
+    expect(asAdmin.correlationId).toMatch(/^[0-9a-f-]{36}$/);
+
+    currentUserId = OWNER;
+    const wire = randomUUID();
+    const res = await http.get(`/api/enrollment/agents/${enrolled.agent.id}?correlationId=${wire}`);
+    expect(res.status).toBe(200);
+    expect((res.body as { correlationId: string }).correlationId).toBe(wire);
+  });
+
+  it('no existence oracle: unauthorized get of a real agent and get of a missing id are indistinguishable', async () => {
+    const enrolled = expectOk(await repo.enroll(enrollInput()));
+
+    currentUserId = STRANGER;
+    const unauthorized = await http.get(`/api/enrollment/agents/${enrolled.agent.id}`);
+    const missing = await http.get(`/api/enrollment/agents/${randomUUID()}`);
+    expect(unauthorized.status).toBe(404);
+    expect(missing.status).toBe(404);
+    const strip = (body: Record<string, unknown>): Record<string, unknown> =>
+      Object.fromEntries(Object.entries(body).filter(([key]) => key !== 'correlationId'));
+    expect(strip(unauthorized.body as Record<string, unknown>)).toEqual(
+      strip(missing.body as Record<string, unknown>),
+    );
+  });
+
+  // ── §5.11 fail-closed ────────────────────────────────────────────────────
+
+  it('fails closed as internal_fault when the store is unreachable, with no fallback write', async () => {
+    const before = (await handle.db.select().from(agents)).length;
+    const txSpy = vi.spyOn(handle.db, 'transaction').mockImplementationOnce(() => {
+      throw new Error('injected store outage');
+    });
+    try {
+      expectFail(await repo.enroll(enrollInput()), 'internal_fault');
+    } finally {
+      txSpy.mockRestore();
+    }
+    const selectSpy = vi.spyOn(handle.db, 'select').mockImplementationOnce(() => {
+      throw new Error('injected store outage');
+    });
+    try {
+      expectFail(await repo.getEnrollment(OWNER, randomUUID()), 'internal_fault');
+    } finally {
+      selectSpy.mockRestore();
+    }
+    expect((await handle.db.select().from(agents)).length).toBe(before);
+  });
+});

apps/gateway/src/enrollment/enrollment.controller.ts

@@ -0,0 +1,61 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import { EnrollAgentDto, GetEnrollmentQueryDto } from './enrollment.dto.js';
+import { EnrollmentRepository } from './enrollment.repository.js';
+import { EnrollmentService } from './enrollment.service.js';
+
+/**
+ * The agent enrollment command family's closed HTTP surface (design
+ * docs/plans/2026-08-29-agent-enrollment-command-design.md §3): one command,
+ * one query. Authentication failures are the guard's (401); everything else
+ * is the repository's closed enum mapped by EnrollmentService.
+ */
+@Controller('api/enrollment')
+@UseGuards(AuthGuard)
+export class EnrollmentController {
+  constructor(
+    private readonly repository: EnrollmentRepository,
+    private readonly service: EnrollmentService,
+  ) {}
+
+  /** agent.enroll (§3.1). */
+  @Post('agents')
+  async enroll(@CurrentUser() user: { id: string }, @Body() dto: EnrollAgentDto) {
+    return this.service.unwrap(
+      await this.repository.enroll({
+        actorId: user.id,
+        harness: dto.harness,
+        name: dto.name,
+        persona: dto.persona ?? null,
+        model: dto.model,
+        provider: dto.provider,
+        credential: dto.credential,
+        idempotencyKey: dto.idempotencyKey,
+        correlationId: dto.correlationId,
+        replayMode: dto.replayMode,
+      }),
+    );
+  }
+
+  /** agent.enrollment.get (§3.2): owner-or-admin; unauthorized and missing fold to one not_found. */
+  @Get('agents/:id')
+  async getEnrollment(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Query() query: GetEnrollmentQueryDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.getEnrollment(user.id, id, query.correlationId),
+    );
+  }
+}

apps/gateway/src/enrollment/enrollment.dto.ts

@@ -0,0 +1,107 @@
+import { Type } from 'class-transformer';
+import {
+  IsIn,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+  MinLength,
+  ValidateIf,
+  ValidateNested,
+} from 'class-validator';
+
+/**
+ * Agent enrollment command DTOs (design
+ * docs/plans/2026-08-29-agent-enrollment-command-design.md §3.1/§3.2,
+ * contract 5 §4.1 typed boundary).
+ *
+ * The global ValidationPipe runs with whitelist + forbidNonWhitelisted, so
+ * closure is contract surface here exactly as in the hierarchy DTOs:
+ *  - EnrollAgentDto declares NO isSystem field — `is_system` is never
+ *    settable through this command (design §3.1 rule 4); the pipe refuses it.
+ *  - replayMode admits ONLY 'actor-bound': `shared` is seed-only (contract 3
+ *    §4.3), so a shared declaration is refused `validation_failed` at the
+ *    boundary, executes nothing, and records no fence row (design §3.1).
+ * Every class here must be registered in PIPE_GUARDED_DTOS so the boot-time
+ * assertion proves the pipe sees the decorators.
+ */
+
+/**
+ * Credential input, discriminated on `mode` (design §3.1):
+ *  - `{ mode: 'reference' }` — a stored credential for (actor, provider)
+ *    must already exist; `type`/`value` must be ABSENT (the repository
+ *    refuses a reference that smuggles a value).
+ *  - `{ mode: 'intake', type: 'api_key', value }` — the value is sealed
+ *    into the credential store inside the enrollment transaction and is
+ *    never echoed anywhere (§3.1 rule 1).
+ */
+export class EnrollCredentialDto {
+  @IsIn(['reference', 'intake'])
+  mode!: 'reference' | 'intake';
+
+  @ValidateIf((o: EnrollCredentialDto) => o.mode === 'intake')
+  @IsIn(['api_key'])
+  type?: 'api_key';
+
+  @ValidateIf((o: EnrollCredentialDto) => o.mode === 'intake')
+  @IsString()
+  @MinLength(1)
+  @MaxLength(4096)
+  value?: string;
+}
+
+export class EnrollAgentDto {
+  /** Registered harness name; a well-formed name missing from the registry is `precondition_failed`. */
+  @IsString()
+  @MinLength(1)
+  @MaxLength(200)
+  harness!: string;
+
+  @IsString()
+  @MinLength(1)
+  @MaxLength(200)
+  name!: string;
+
+  /** Stored as the agent's system prompt; null/absent leaves it unset. */
+  @IsOptional()
+  @IsString()
+  @MaxLength(20000)
+  persona?: string | null;
+
+  /** Provider-qualified model id. */
+  @IsString()
+  @MinLength(1)
+  @MaxLength(200)
+  model!: string;
+
+  /** Names the credential's provider. */
+  @IsString()
+  @MinLength(1)
+  @MaxLength(200)
+  provider!: string;
+
+  @ValidateNested()
+  @Type(() => EnrollCredentialDto)
+  credential!: EnrollCredentialDto;
+
+  /** REQUIRED — contract 3 §4.3, ratified into contract 5 §4 via §7 item 4. */
+  @IsUUID()
+  idempotencyKey!: string;
+
+  /** Optional; generated when absent (contract 5 §4.3). */
+  @IsOptional()
+  @IsUUID()
+  correlationId?: string;
+
+  /** Only 'actor-bound' is admissible on this family — see module doc. */
+  @IsOptional()
+  @IsIn(['actor-bound'])
+  replayMode?: 'actor-bound';
+}
+
+/** Query envelope for agent.enrollment.get (design §3.2): correlation only, no idempotency key. */
+export class GetEnrollmentQueryDto {
+  @IsOptional()
+  @IsUUID()
+  correlationId?: string;
+}

apps/gateway/src/enrollment/enrollment.module.ts

@@ -0,0 +1,22 @@
+import { Module } from '@nestjs/common';
+import { HarnessModule } from '../harness/harness.module.js';
+import { EnrollmentController } from './enrollment.controller.js';
+import { EnrollmentRepository } from './enrollment.repository.js';
+import { EnrollmentService } from './enrollment.service.js';
+
+/**
+ * Agent enrollment command family (M4-4b; design
+ * docs/plans/2026-08-29-agent-enrollment-command-design.md). Imports
+ * HarnessModule for the live harness registry — the validation source for
+ * the `harness` field (a well-formed name the registry does not know is a
+ * precondition failure). EnrollmentRepository is the family's sole writer;
+ * every mutation runs fence-check → mutate → audit + outbox in one
+ * transaction.
+ */
+@Module({
+  imports: [HarnessModule],
+  controllers: [EnrollmentController],
+  providers: [EnrollmentRepository, EnrollmentService],
+  exports: [EnrollmentRepository],
+})
+export class EnrollmentModule {}

apps/gateway/src/enrollment/enrollment.repository.ts

@@ -0,0 +1,538 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { seal } from '@mosaicstack/auth';
+import {
+  agentAuditEvents,
+  agentIdempotencyFence,
+  agentOutbox,
+  agents,
+  and,
+  eq,
+  providerCredentials,
+  users,
+  type Db,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+import type { HarnessRegistry } from '../harness/harness.registry.js';
+import { HARNESS_REGISTRY } from '../harness/harness.tokens.js';
+
+/**
+ * Agent enrollment command repository (design
+ * docs/plans/2026-08-29-agent-enrollment-command-design.md §3; contract 5 §4
+ * envelope; contract 3 §4.3 idempotency fence, ratified via §7 item 4).
+ *
+ * The ONLY writer of the enrollment family's tables (`agent_audit_events`,
+ * `agent_outbox`, `agent_idempotency_fence`) and the only path that sets
+ * `agents.harness`/`agents.enrolled_at`. Every enroll runs one transaction:
+ * fence check → (replay | credential handling → agent insert → fence insert →
+ * audit event + outbox), so state, fence, event, and outbox commit or roll
+ * back together (§3.1 rule 6).
+ *
+ * Authorization (v1, §3.1 rule 4) is the AuthGuard-authenticated actor — no
+ * hierarchy grant is consulted because v1 enrollment binds no hierarchy node.
+ * The recorded fence authorization scope is therefore the constant
+ * platform-user identity domain (§3.1 rule 5).
+ *
+ * Never-echo (§3.1 rule 1): the credential value reaches exactly one sink —
+ * the sealed store write — and appears in no result, audit payload, outbox
+ * row, or log line. Log lines here carry correlation ids and error names
+ * only, never request fields.
+ *
+ * The single-write helper methods (writeSealedCredential, insertAgentRow,
+ * insertFenceRow, appendEvent, insertOutboxRow) are ordinary decomposition;
+ * the atomicity witnesses (§5.6) spy on them to inject faults at each write
+ * point without any test-only production switch.
+ */
+
+export const ENROLLMENT_OPERATION = 'agent.enroll';
+/** §3.1 rule 5: v1 authorization is grant-free, so the scope is the authenticated-user identity domain. */
+const AUTHORIZATION_SCOPE = 'platform-user';
+/** The single bounded collision shape (§3.1 rule 5): constant, identifying no record. */
+const CONFLICT_MESSAGE = 'idempotency conflict';
+/** One fixed message for every not_found cause — missing and unauthorized are indistinguishable (§3.2). */
+const NOT_FOUND_MESSAGE = 'agent not found';
+
+/** Closed per-family error enum (§3.3). 401 is produced by AuthGuard; 403 folds to not_found (§3.2). */
+export type EnrollmentErrorCode =
+  | 'validation_failed'
+  | 'authentication_failed'
+  | 'authorization_refused'
+  | 'not_found'
+  | 'conflict'
+  | 'precondition_failed'
+  | 'internal_fault';
+
+export interface EnrollmentFailure {
+  readonly ok: false;
+  readonly error: EnrollmentErrorCode;
+  readonly message: string;
+  /** Refusals carry the correlation id too (contract 5 §4.3 end-to-end traceability). */
+  readonly correlationId: string;
+}
+
+export type EnrollmentResult<T> =
+  | ({ readonly ok: true; readonly correlationId: string } & T)
+  | EnrollmentFailure;
+
+/** The persisted agent row; the table stores no credential material (§3.1 rule 1). */
+export interface EnrolledAgentView {
+  readonly id: string;
+  readonly name: string;
+  readonly provider: string;
+  readonly model: string;
+  readonly status: string;
+  readonly harness: string | null;
+  readonly persona: string | null;
+  readonly ownerId: string | null;
+  readonly enrolledAt: string | null;
+  readonly createdAt: string;
+}
+
+export interface EnrollCredentialInput {
+  readonly mode: 'reference' | 'intake';
+  readonly type?: 'api_key';
+  readonly value?: string;
+}
+
+export interface EnrollAgentInput {
+  readonly actorId: string;
+  readonly harness: string;
+  readonly name: string;
+  readonly persona?: string | null;
+  readonly model: string;
+  readonly provider: string;
+  readonly credential: EnrollCredentialInput;
+  readonly idempotencyKey: string;
+  readonly correlationId?: string;
+  /** Defense in depth below the DTO: anything but 'actor-bound' is refused (seed-only rule). */
+  readonly replayMode?: string;
+}
+
+type Tx = Pick<Db, 'insert' | 'select' | 'update' | 'delete'>;
+type AgentRow = typeof agents.$inferSelect;
+type FenceRow = typeof agentIdempotencyFence.$inferSelect;
+
+/** Raised inside the transaction when the fence insert lost a same-key race (§3.1 rule 5 concurrency). */
+class ConcurrentEnrollmentError extends Error {
+  constructor() {
+    super('concurrent enrollment lost the fence race');
+    this.name = 'ConcurrentEnrollmentError';
+  }
+}
+
+function agentView(row: AgentRow): EnrolledAgentView {
+  return {
+    id: row.id,
+    name: row.name,
+    provider: row.provider,
+    model: row.model,
+    status: row.status,
+    harness: row.harness,
+    persona: row.systemPrompt,
+    ownerId: row.ownerId,
+    enrolledAt: row.enrolledAt?.toISOString() ?? null,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
+
+/** Key-order-independent serialization (jsonb precedent in hierarchy-audit). */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const body = Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+      .join(',');
+    return `{${body}}`;
+  }
+  return JSON.stringify(value);
+}
+
+interface NormalizedEnrollment {
+  readonly actorId: string;
+  readonly harness: string;
+  readonly name: string;
+  readonly persona: string | null;
+  readonly model: string;
+  readonly provider: string;
+  readonly credential: EnrollCredentialInput;
+  readonly idempotencyKey: string;
+  readonly correlationId: string;
+  readonly digest: string;
+}
+
+/**
+ * Canonicalized-payload digest (§3.1 rule 5). The input EXCLUDES the
+ * credential value by construction: it covers mode and declared type only —
+ * plaintext never reaches the hash.
+ */
+function digestOf(
+  input: Omit<NormalizedEnrollment, 'actorId' | 'idempotencyKey' | 'correlationId' | 'digest'>,
+): string {
+  const canonical = canonicalJson({
+    harness: input.harness,
+    name: input.name,
+    persona: input.persona,
+    model: input.model,
+    provider: input.provider,
+    credential: { mode: input.credential.mode, type: input.credential.type ?? null },
+  });
+  return createHash('sha256').update(canonical).digest('hex');
+}
+
+@Injectable()
+export class EnrollmentRepository {
+  private readonly logger = new Logger(EnrollmentRepository.name);
+
+  constructor(
+    @Inject(DB) private readonly db: Db,
+    @Inject(HARNESS_REGISTRY) private readonly registry: HarnessRegistry,
+  ) {}
+
+  async enroll(input: EnrollAgentInput): Promise<EnrollmentResult<{ agent: EnrolledAgentView }>> {
+    const correlationId = input.correlationId ?? randomUUID();
+    const fail = (error: EnrollmentErrorCode, message: string): EnrollmentFailure => ({
+      ok: false,
+      error,
+      message,
+      correlationId,
+    });
+
+    const harness = input.harness.trim();
+    const name = input.name.trim();
+    if (harness.length === 0) return fail('validation_failed', 'harness must be non-empty');
+    if (name.length === 0 || name.length > 200) {
+      return fail('validation_failed', 'name must be non-empty and at most 200 characters');
+    }
+    if (input.replayMode !== undefined && input.replayMode !== 'actor-bound') {
+      // Seed-only rule (contract 3 §4.3): refused with nothing executed and no fence row.
+      return fail('validation_failed', 'replayMode must be actor-bound');
+    }
+    if (input.credential.mode === 'reference') {
+      if (input.credential.type !== undefined || input.credential.value !== undefined) {
+        return fail('validation_failed', 'a reference credential carries no type or value');
+      }
+    } else if (
+      input.credential.type !== 'api_key' ||
+      typeof input.credential.value !== 'string' ||
+      input.credential.value.length === 0
+    ) {
+      return fail('validation_failed', 'an intake credential requires type api_key and a value');
+    }
+    // Syntactic validity ends above; a well-formed name the live registry
+    // does not know is a precondition failure (§3.1 table).
+    if (!this.registry.has(harness)) {
+      return fail('precondition_failed', 'harness is not registered');
+    }
+
+    const normalized: NormalizedEnrollment = {
+      actorId: input.actorId,
+      harness,
+      name,
+      persona: input.persona ?? null,
+      model: input.model,
+      provider: input.provider,
+      credential: input.credential,
+      idempotencyKey: input.idempotencyKey,
+      correlationId,
+      digest: digestOf({
+        harness,
+        name,
+        persona: input.persona ?? null,
+        model: input.model,
+        provider: input.provider,
+        credential: input.credential,
+      }),
+    };
+
+    // Two attempts: a fence-race loser's transaction rolls back and the retry
+    // resolves through the replay path against the winner's committed row —
+    // or executes afresh if the winner aborted (§3.1 rule 5 concurrency). A
+    // unique-violation race never surfaces as an unhandled internal fault.
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      try {
+        return await this.db.transaction(async (tx) => this.enrollTx(tx, normalized));
+      } catch (error) {
+        if (error instanceof ConcurrentEnrollmentError && attempt === 0) continue;
+        if (error instanceof ConcurrentEnrollmentError) {
+          return fail('conflict', CONFLICT_MESSAGE);
+        }
+        // §4.4 fail-closed: whatever broke, the transaction rolled back and
+        // the refusal is the internal-fault class — no fallback write or read.
+        this.logger.error(
+          `agent.enroll failed closed (correlation=${correlationId}): ${
+            error instanceof Error ? error.name : 'unknown error'
+          }`,
+        );
+        return fail('internal_fault', 'internal fault');
+      }
+    }
+    return fail('internal_fault', 'internal fault');
+  }
+
+  private async enrollTx(
+    tx: Tx,
+    input: NormalizedEnrollment,
+  ): Promise<EnrollmentResult<{ agent: EnrolledAgentView }>> {
+    const fence = await this.fenceFor(tx, input.idempotencyKey);
+    if (fence) return this.replay(tx, fence, input);
+
+    if (input.credential.mode === 'reference') {
+      // §3.1 rule 3: the reference must resolve for (actor, provider).
+      const existing = await tx
+        .select({ id: providerCredentials.id })
+        .from(providerCredentials)
+        .where(
+          and(
+            eq(providerCredentials.userId, input.actorId),
+            eq(providerCredentials.provider, input.provider),
+          ),
+        )
+        .limit(1);
+      if (existing.length === 0) {
+        return {
+          ok: false,
+          error: 'precondition_failed',
+          message: 'credential reference does not resolve',
+          correlationId: input.correlationId,
+        };
+      }
+    } else {
+      // §3.1 rule 2: sealed-store write inside THIS transaction — a later
+      // failure rolls it back, leaving no orphan credential.
+      await this.writeSealedCredential(
+        tx,
+        input.actorId,
+        input.provider,
+        input.credential.value as string,
+      );
+    }
+
+    const agentRow = await this.insertAgentRow(tx, input);
+    const fenceRow = await this.insertFenceRow(tx, input, agentRow.id);
+    if (!fenceRow) {
+      // A same-(operation, key) winner committed first; abandon our writes.
+      throw new ConcurrentEnrollmentError();
+    }
+    await this.appendEvent(tx, {
+      eventType: 'agent.enrolled',
+      actorId: input.actorId,
+      agentId: agentRow.id,
+      correlationId: input.correlationId,
+      // §3.1 rule 6 payload: harness, provider, name, credentialMode — no credential material.
+      payload: {
+        harness: input.harness,
+        provider: input.provider,
+        name: input.name,
+        credentialMode: input.credential.mode,
+      },
+    });
+    return { ok: true, correlationId: input.correlationId, agent: agentView(agentRow) };
+  }
+
+  /**
+   * Replay path (§3.1 rule 5): a fresh submission of a recorded
+   * (operation, key). The actor is re-authorized exactly as a fresh
+   * submission (v1: authenticated actor — the guard already ran); then mode,
+   * scope, digest, and recorded-actor equality; then target-result read
+   * authority (owner or admin) on the referenced agent. ANY failure refuses
+   * with the single bounded conflict shape — constant, identifying no record.
+   * A passing replay executes nothing and appends only the non-mutation
+   * access event (with its outbox record — one outbox row per event).
+   */
+  private async replay(
+    tx: Tx,
+    fence: FenceRow,
+    input: NormalizedEnrollment,
+  ): Promise<EnrollmentResult<{ agent: EnrolledAgentView }>> {
+    const collision: EnrollmentFailure = {
+      ok: false,
+      error: 'conflict',
+      message: CONFLICT_MESSAGE,
+      correlationId: input.correlationId,
+    };
+    if (fence.replayMode !== 'actor-bound') return collision;
+    if (fence.authorizationScope !== AUTHORIZATION_SCOPE) return collision;
+    if (fence.payloadDigest !== input.digest) return collision;
+    if (fence.actorId !== input.actorId) return collision;
+
+    const rows = await tx.select().from(agents).where(eq(agents.id, fence.outcomeAgentId)).limit(1);
+    const agentRow = rows[0];
+    if (!agentRow) return collision;
+    const authorized =
+      agentRow.ownerId === input.actorId || (await this.isPlatformAdmin(tx, input.actorId));
+    if (!authorized) return collision;
+
+    await this.appendEvent(tx, {
+      eventType: 'agent.enrollment.replayed',
+      actorId: input.actorId,
+      agentId: agentRow.id,
+      correlationId: input.correlationId,
+      payload: { fenceId: fence.id },
+    });
+    return { ok: true, correlationId: input.correlationId, agent: agentView(agentRow) };
+  }
+
+  /**
+   * agent.enrollment.get (§3.2): owner-or-admin read. Unauthorized and
+   * missing fold to the same not_found wire shape (no existence oracle).
+   */
+  async getEnrollment(
+    actorId: string,
+    agentId: string,
+    correlationId?: string,
+  ): Promise<EnrollmentResult<{ agent: EnrolledAgentView }>> {
+    const resolvedCorrelation = correlationId ?? randomUUID();
+    try {
+      const rows = await this.db.select().from(agents).where(eq(agents.id, agentId)).limit(1);
+      const row = rows[0];
+      if (row) {
+        const authorized =
+          row.ownerId === actorId || (await this.isPlatformAdmin(this.db, actorId));
+        if (authorized) {
+          return { ok: true, correlationId: resolvedCorrelation, agent: agentView(row) };
+        }
+      }
+      return {
+        ok: false,
+        error: 'not_found',
+        message: NOT_FOUND_MESSAGE,
+        correlationId: resolvedCorrelation,
+      };
+    } catch (error) {
+      this.logger.error(
+        `agent.enrollment.get failed closed (correlation=${resolvedCorrelation}): ${
+          error instanceof Error ? error.name : 'unknown error'
+        }`,
+      );
+      return {
+        ok: false,
+        error: 'internal_fault',
+        message: 'internal fault',
+        correlationId: resolvedCorrelation,
+      };
+    }
+  }
+
+  private async fenceFor(tx: Tx, idempotencyKey: string): Promise<FenceRow | null> {
+    const rows = await tx
+      .select()
+      .from(agentIdempotencyFence)
+      .where(
+        and(
+          eq(agentIdempotencyFence.operation, ENROLLMENT_OPERATION),
+          eq(agentIdempotencyFence.idempotencyKey, idempotencyKey),
+        ),
+      )
+      .limit(1);
+    return rows[0] ?? null;
+  }
+
+  private async isPlatformAdmin(tx: Tx, actorId: string): Promise<boolean> {
+    const rows = await tx
+      .select({ role: users.role })
+      .from(users)
+      .where(eq(users.id, actorId))
+      .limit(1);
+    return rows[0]?.role === 'admin';
+  }
+
+  /**
+   * Sealed intake write, mirroring ProviderCredentialsService.store semantics
+   * (seal-at-rest, one row per (userId, provider)) but on the enrollment
+   * transaction (§3.1 rule 2). The plaintext exists only in this frame.
+   */
+  async writeSealedCredential(
+    tx: Tx,
+    userId: string,
+    provider: string,
+    value: string,
+  ): Promise<void> {
+    const encryptedValue = seal(value);
+    await tx
+      .insert(providerCredentials)
+      .values({ userId, provider, credentialType: 'api_key', encryptedValue, metadata: null })
+      .onConflictDoUpdate({
+        target: [providerCredentials.userId, providerCredentials.provider],
+        set: {
+          credentialType: 'api_key',
+          encryptedValue,
+          metadata: null,
+          updatedAt: new Date(),
+        },
+      });
+  }
+
+  async insertAgentRow(tx: Tx, input: NormalizedEnrollment): Promise<AgentRow> {
+    const rows = await tx
+      .insert(agents)
+      .values({
+        name: input.name,
+        provider: input.provider,
+        model: input.model,
+        harness: input.harness,
+        systemPrompt: input.persona,
+        // §3.1 rule 4: owner is the authenticated actor; is_system stays default false.
+        ownerId: input.actorId,
+        enrolledAt: new Date(),
+      })
+      .returning();
+    const row = rows[0];
+    if (!row) throw new Error('agent insert returned no row');
+    return row;
+  }
+
+  async insertFenceRow(
+    tx: Tx,
+    input: NormalizedEnrollment,
+    outcomeAgentId: string,
+  ): Promise<FenceRow | null> {
+    const rows = await tx
+      .insert(agentIdempotencyFence)
+      .values({
+        operation: ENROLLMENT_OPERATION,
+        idempotencyKey: input.idempotencyKey,
+        actorId: input.actorId,
+        authorizationScope: AUTHORIZATION_SCOPE,
+        payloadDigest: input.digest,
+        replayMode: 'actor-bound',
+        outcomeAgentId,
+      })
+      .onConflictDoNothing()
+      .returning();
+    return rows[0] ?? null;
+  }
+
+  /** Append one audit event and its outbox record on the caller's transaction (one outbox row per event). */
+  async appendEvent(
+    tx: Tx,
+    input: {
+      eventType: 'agent.enrolled' | 'agent.enrollment.replayed';
+      actorId: string;
+      agentId: string;
+      correlationId: string;
+      payload: Record<string, unknown>;
+      causationId?: string;
+    },
+  ): Promise<void> {
+    const inserted = await tx
+      .insert(agentAuditEvents)
+      .values({
+        eventType: input.eventType,
+        actorId: input.actorId,
+        agentId: input.agentId,
+        correlationId: input.correlationId,
+        causationId: input.causationId ?? null,
+        payload: input.payload,
+      })
+      .returning();
+    const event = inserted[0];
+    if (!event) throw new Error('agent audit event insert returned no row');
+    await this.insertOutboxRow(tx, event.id, input.correlationId);
+  }
+
+  async insertOutboxRow(tx: Tx, eventId: string, correlationId: string): Promise<void> {
+    await tx.insert(agentOutbox).values({ eventId, correlationId });
+  }
+}

apps/gateway/src/enrollment/enrollment.service.ts

@@ -0,0 +1,45 @@
+import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
+import type {
+  EnrollmentErrorCode,
+  EnrollmentFailure,
+  EnrollmentResult,
+} from './enrollment.repository.js';
+
+/**
+ * Maps enrollment result unions onto the closed HTTP status set (design
+ * docs/plans/2026-08-29-agent-enrollment-command-design.md §3.3, contract 5
+ * §4.2). Every refusal body carries the correlation id (contract 5 §4.3
+ * end-to-end traceability) alongside the enum code. `not_found` carries one
+ * fixed message for every cause — missing agent and unauthorized caller are
+ * indistinguishable on the wire (§3.2).
+ */
+const HTTP_STATUS: Record<EnrollmentErrorCode, HttpStatus> = {
+  validation_failed: HttpStatus.BAD_REQUEST,
+  authentication_failed: HttpStatus.UNAUTHORIZED,
+  authorization_refused: HttpStatus.FORBIDDEN,
+  not_found: HttpStatus.NOT_FOUND,
+  conflict: HttpStatus.CONFLICT,
+  precondition_failed: HttpStatus.UNPROCESSABLE_ENTITY,
+  internal_fault: HttpStatus.INTERNAL_SERVER_ERROR,
+};
+
+@Injectable()
+export class EnrollmentService {
+  unwrap<T>(result: EnrollmentResult<T>): { ok: true; correlationId: string } & T {
+    if (result.ok) return result;
+    throw this.toException(result);
+  }
+
+  private toException(failure: EnrollmentFailure): HttpException {
+    const status = HTTP_STATUS[failure.error];
+    return new HttpException(
+      {
+        statusCode: status,
+        error: failure.error,
+        message: failure.message,
+        correlationId: failure.correlationId,
+      },
+      status,
+    );
+  }
+}

apps/gateway/src/hierarchy/hierarchy-audit.repository.ts

@@ -28,8 +28,8 @@ import { DB } from '../database/database.module.js';
  *
  * This is NOT a class-table writer: it touches only the audit/outbox
  * tables, so it does not appear on the writer-coverage allowlist. The
- * hierarchy command repositories (M4-1b-ii) are the allowlisted writers and
- * call into this on their own transactions.
+ * hierarchy command repository (HierarchyRepository) is the allowlisted
+ * writer and calls into this on its own transactions.
  */
 
 export type HierarchyAuditVerb = (typeof HIERARCHY_AUDIT_VERBS)[number];

apps/gateway/src/hierarchy/hierarchy-commands.integration.test.ts

@@ -0,0 +1,965 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { Test, type TestingModule } from '@nestjs/testing';
+import {
+  companies,
+  createPgliteDb,
+  eq,
+  estates,
+  hierarchyAuditEvents,
+  hierarchyGrants,
+  hierarchyOutbox,
+  runPgliteMigrations,
+  teams,
+  users,
+  workspaces,
+  type DbHandle,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+import { appendHierarchyEvent } from './hierarchy-audit.repository.js';
+import { HierarchyGrantEvaluationService } from './hierarchy-grant-evaluation.js';
+import { HierarchyRepository, type HierarchyResult } from './hierarchy.repository.js';
+
+/**
+ * Command-level witnesses for the hierarchy command family (M4-1b-ii):
+ * contract 1 §6.4 (per-mutation-class commit + rollback), §6.5
+ * (authorization outcomes), §6.7 (no existence oracle), §6.9 (visibility),
+ * and contract 2 §3 grant-evaluation semantics (deny-by-default,
+ * ancestor-chain inheritance, max-role, live revocation, suspended team
+ * subjects). Schema-level constraints are witnessed in
+ * packages/db/src/hierarchy-schema.witness.test.ts; the audit machinery's
+ * own atomicity in hierarchy-audit.integration.test.ts.
+ *
+ * The rollback legs pre-seed an audit event under the command's idempotency
+ * key with different content: the command's append then throws inside the
+ * command transaction, so the whole mutation must roll back — the command
+ * returns `conflict` and leaves no state change, no second event, and no
+ * second outbox record.
+ */
+describe('hierarchy commands integration', (): void => {
+  let dataDir: string;
+  let handle: DbHandle;
+  let moduleRef: TestingModule;
+  let repo: HierarchyRepository;
+  let evaluation: HierarchyGrantEvaluationService;
+
+  const OWNER = 'hier-cmd-owner';
+  const ADMIN = 'hier-cmd-admin';
+  const STRANGER = 'hier-cmd-stranger';
+  const SUBJECT = 'hier-cmd-subject';
+
+  /** Base fixture: OWNER's company (created through the command surface). */
+  let companyId: string;
+
+  const slug = (prefix: string): string => `${prefix}-${randomUUID().slice(0, 8)}`;
+
+  function expectOk<T>(result: HierarchyResult<T>): { ok: true } & T {
+    if (!result.ok) throw new Error(`expected ok, got ${JSON.stringify(result)}`);
+    return result;
+  }
+
+  const eventsForKey = (key: string) =>
+    handle.db
+      .select()
+      .from(hierarchyAuditEvents)
+      .where(eq(hierarchyAuditEvents.idempotencyKey, key));
+
+  const outboxForKey = (key: string) =>
+    handle.db.select().from(hierarchyOutbox).where(eq(hierarchyOutbox.idempotencyKey, key));
+
+  /** Occupy `key` with unrelated event content so a command reusing it must abort. */
+  const seedConflictingKey = async (key: string): Promise<void> => {
+    await handle.db.transaction(async (tx) =>
+      appendHierarchyEvent(tx, {
+        actorId: 'seed-actor',
+        verb: 'create',
+        targetKind: 'company',
+        targetId: randomUUID(),
+        targetSnapshot: { seeded: true },
+        correlationId: 'seed-correlation',
+        idempotencyKey: key,
+      }),
+    );
+  };
+
+  /**
+   * §6.4 rollback leg: the command must return `conflict` and leave exactly
+   * the seeded event/outbox pair under the key — nothing it wrote survives.
+   */
+  const expectRolledBack = async <T>(
+    key: string,
+    command: () => Promise<HierarchyResult<T>>,
+    assertUnchanged: () => Promise<void>,
+  ): Promise<void> => {
+    await seedConflictingKey(key);
+    const result = await command();
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toBe('conflict');
+    expect(await eventsForKey(key)).toHaveLength(1);
+    expect(await outboxForKey(key)).toHaveLength(1);
+    await assertUnchanged();
+  };
+
+  beforeAll(async (): Promise<void> => {
+    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-gateway-hierarchy-commands-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    moduleRef = await Test.createTestingModule({
+      providers: [
+        HierarchyRepository,
+        HierarchyGrantEvaluationService,
+        { provide: DB, useValue: handle.db },
+      ],
+    }).compile();
+    repo = moduleRef.get(HierarchyRepository);
+    evaluation = moduleRef.get(HierarchyGrantEvaluationService);
+
+    await handle.db.insert(users).values([
+      { id: OWNER, name: 'Owner', email: `${OWNER}@example.com` },
+      { id: ADMIN, name: 'Admin', email: `${ADMIN}@example.com`, role: 'admin' },
+      { id: STRANGER, name: 'Stranger', email: `${STRANGER}@example.com` },
+      { id: SUBJECT, name: 'Subject', email: `${SUBJECT}@example.com` },
+    ]);
+    const created = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'Base Co', slug: slug('base') }),
+    );
+    companyId = created.company.id;
+  });
+
+  afterAll(async (): Promise<void> => {
+    await moduleRef.close();
+    await handle.close();
+    await rm(dataDir, { recursive: true, force: true });
+  });
+
+  // ── §6.4 commit legs ───────────────────────────────────────────────────────
+
+  it('createCompany commits company, owner grant, causation-linked events, and outbox atomically', async () => {
+    const key = `key-${randomUUID()}`;
+    const result = expectOk(
+      await repo.createCompany({
+        actorId: OWNER,
+        name: 'Atomic Co',
+        slug: slug('atomic'),
+        idempotencyKey: key,
+      }),
+    );
+    expect(result.company.visibility).toBe('private');
+    expect(result.grant.role).toBe('hierarchy:owner');
+    expect(result.grant.userId).toBe(OWNER);
+    expect(result.grant.grantedBy).toBe(OWNER);
+
+    const [createEvents, grantEvents] = await Promise.all([
+      eventsForKey(key),
+      eventsForKey(`${key}:grant`),
+    ]);
+    expect(createEvents).toHaveLength(1);
+    expect(createEvents[0]).toMatchObject({ verb: 'create', targetId: result.company.id });
+    expect(grantEvents).toHaveLength(1);
+    expect(grantEvents[0]).toMatchObject({ verb: 'grant_create', targetId: result.grant.id });
+    // The grant event is caused by the create event, same correlation (§4.3).
+    expect(grantEvents[0]!.causationId).toBe(createEvents[0]!.id);
+    expect(grantEvents[0]!.correlationId).toBe(createEvents[0]!.correlationId);
+    expect(await outboxForKey(key)).toHaveLength(1);
+    expect(await outboxForKey(`${key}:grant`)).toHaveLength(1);
+
+    const rows = await handle.db
+      .select()
+      .from(companies)
+      .where(eq(companies.id, result.company.id));
+    expect(rows).toHaveLength(1);
+  });
+
+  it('deleteCompany commits the delete with one audited grant_revoke per cascaded grant', async () => {
+    const created = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'Mortal Co', slug: slug('mortal') }),
+    );
+    const extraGrant = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'company',
+        targetId: created.company.id,
+        role: 'viewer',
+      }),
+    );
+    const key = `key-${randomUUID()}`;
+    expectOk(
+      await repo.deleteCompany({
+        actorId: OWNER,
+        companyId: created.company.id,
+        idempotencyKey: key,
+      }),
+    );
+    const deleteEvents = await eventsForKey(key);
+    expect(deleteEvents).toHaveLength(1);
+    expect(deleteEvents[0]).toMatchObject({ verb: 'delete', targetId: created.company.id });
+    for (const grantId of [created.grant.id, extraGrant.grant.id]) {
+      const revokeEvents = await eventsForKey(`${key}:revoke:${grantId}`);
+      expect(revokeEvents).toHaveLength(1);
+      expect(revokeEvents[0]).toMatchObject({ verb: 'grant_revoke', targetId: grantId });
+      expect(revokeEvents[0]!.causationId).toBe(deleteEvents[0]!.id);
+    }
+    expect(
+      await handle.db.select().from(companies).where(eq(companies.id, created.company.id)),
+    ).toHaveLength(0);
+  });
+
+  // ── §6.4 rollback legs (one per mutation class) ────────────────────────────
+
+  it('renameCompany commits the rename with an audited event carrying previousName', async () => {
+    const created = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'Old Name Co', slug: slug('rename') }),
+    );
+    const key = `key-${randomUUID()}`;
+    const renamed = expectOk(
+      await repo.renameCompany({
+        actorId: OWNER,
+        companyId: created.company.id,
+        name: 'New Name Co',
+        idempotencyKey: key,
+      }),
+    );
+    expect(renamed.company.name).toBe('New Name Co');
+
+    const events = await eventsForKey(key);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ verb: 'rename', targetId: created.company.id });
+    // §6.4: the audited rename carries the old and new names.
+    expect(events[0]!.targetSnapshot).toMatchObject({
+      name: 'New Name Co',
+      previousName: 'Old Name Co',
+    });
+    expect(await outboxForKey(key)).toHaveLength(1);
+
+    const rows = await handle.db
+      .select()
+      .from(companies)
+      .where(eq(companies.id, created.company.id));
+    expect(rows[0]!.name).toBe('New Name Co');
+  });
+
+  it('revokeGrant commits the row deletion with one audited grant_revoke event', async () => {
+    const grant = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'company',
+        targetId: companyId,
+        role: 'viewer',
+      }),
+    );
+    const key = `key-${randomUUID()}`;
+    const revoked = expectOk(
+      await repo.revokeGrant({ actorId: OWNER, grantId: grant.grant.id, idempotencyKey: key }),
+    );
+    expect(revoked.revokedId).toBe(grant.grant.id);
+
+    const events = await eventsForKey(key);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ verb: 'grant_revoke', targetId: grant.grant.id });
+    expect(await outboxForKey(key)).toHaveLength(1);
+
+    // §6 revocation = row deletion: the grant row is gone.
+    const rows = await handle.db
+      .select()
+      .from(hierarchyGrants)
+      .where(eq(hierarchyGrants.id, grant.grant.id));
+    expect(rows).toHaveLength(0);
+  });
+
+  it('rolls back a create: no estate row survives the aborted transaction', async () => {
+    const estateSlug = slug('rb-create');
+    const key = `key-${randomUUID()}`;
+    await expectRolledBack(
+      key,
+      () =>
+        repo.createEstate({
+          actorId: OWNER,
+          companyId,
+          name: 'Doomed Estate',
+          slug: estateSlug,
+          idempotencyKey: key,
+        }),
+      async () => {
+        expect(
+          await handle.db.select().from(estates).where(eq(estates.slug, estateSlug)),
+        ).toHaveLength(0);
+      },
+    );
+  });
+
+  it('rolls back a rename: the company keeps its name', async () => {
+    const before = (
+      await handle.db.select().from(companies).where(eq(companies.id, companyId))
+    )[0]!;
+    const key = `key-${randomUUID()}`;
+    await expectRolledBack(
+      key,
+      () => repo.renameCompany({ actorId: OWNER, companyId, name: 'Never', idempotencyKey: key }),
+      async () => {
+        const after = (
+          await handle.db.select().from(companies).where(eq(companies.id, companyId))
+        )[0]!;
+        expect(after.name).toBe(before.name);
+      },
+    );
+  });
+
+  it('rolls back a visibility change: the company stays private', async () => {
+    const key = `key-${randomUUID()}`;
+    await expectRolledBack(
+      key,
+      () =>
+        repo.changeCompanyVisibility({
+          actorId: ADMIN,
+          companyId,
+          visibility: 'directory',
+          idempotencyKey: key,
+        }),
+      async () => {
+        const after = (
+          await handle.db.select().from(companies).where(eq(companies.id, companyId))
+        )[0]!;
+        expect(after.visibility).toBe('private');
+      },
+    );
+  });
+
+  it('rolls back a transfer: the estate keeps its parent', async () => {
+    const estate = expectOk(
+      await repo.createEstate({ actorId: OWNER, companyId, name: 'RB-T', slug: slug('rb-t') }),
+    );
+    const other = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'RB Dest', slug: slug('rb-dest') }),
+    );
+    const key = `key-${randomUUID()}`;
+    await expectRolledBack(
+      key,
+      () =>
+        repo.transferEstate({
+          actorId: OWNER,
+          estateId: estate.estate.id,
+          destinationCompanyId: other.company.id,
+          idempotencyKey: key,
+        }),
+      async () => {
+        const after = (
+          await handle.db.select().from(estates).where(eq(estates.id, estate.estate.id))
+        )[0]!;
+        expect(after.companyId).toBe(companyId);
+      },
+    );
+  });
+
+  it('rolls back a delete: the estate row survives', async () => {
+    const estate = expectOk(
+      await repo.createEstate({ actorId: OWNER, companyId, name: 'RB-D', slug: slug('rb-d') }),
+    );
+    const key = `key-${randomUUID()}`;
+    await expectRolledBack(
+      key,
+      () => repo.deleteEstate({ actorId: OWNER, estateId: estate.estate.id, idempotencyKey: key }),
+      async () => {
+        expect(
+          await handle.db.select().from(estates).where(eq(estates.id, estate.estate.id)),
+        ).toHaveLength(1);
+      },
+    );
+  });
+
+  it('rolls back a grant create: no grant row survives', async () => {
+    const key = `key-${randomUUID()}`;
+    await expectRolledBack(
+      key,
+      () =>
+        repo.createGrant({
+          actorId: OWNER,
+          userId: STRANGER,
+          targetKind: 'company',
+          targetId: companyId,
+          role: 'viewer',
+          idempotencyKey: key,
+        }),
+      async () => {
+        const rows = await handle.db
+          .select()
+          .from(hierarchyGrants)
+          .where(eq(hierarchyGrants.userId, STRANGER));
+        expect(rows.filter((r) => r.companyId === companyId)).toHaveLength(0);
+      },
+    );
+  });
+
+  it('rolls back a grant change and a grant revoke: the grant keeps its role and its row', async () => {
+    const grant = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'company',
+        targetId: companyId,
+        role: 'viewer',
+      }),
+    );
+    const changeKey = `key-${randomUUID()}`;
+    await expectRolledBack(
+      changeKey,
+      () =>
+        repo.changeGrant({
+          actorId: OWNER,
+          grantId: grant.grant.id,
+          role: 'member',
+          idempotencyKey: changeKey,
+        }),
+      async () => {
+        const row = (
+          await handle.db
+            .select()
+            .from(hierarchyGrants)
+            .where(eq(hierarchyGrants.id, grant.grant.id))
+        )[0]!;
+        expect(row.role).toBe('viewer');
+      },
+    );
+    const revokeKey = `key-${randomUUID()}`;
+    await expectRolledBack(
+      revokeKey,
+      () =>
+        repo.revokeGrant({ actorId: OWNER, grantId: grant.grant.id, idempotencyKey: revokeKey }),
+      async () => {
+        expect(
+          await handle.db
+            .select()
+            .from(hierarchyGrants)
+            .where(eq(hierarchyGrants.id, grant.grant.id)),
+        ).toHaveLength(1);
+      },
+    );
+    expectOk(await repo.revokeGrant({ actorId: OWNER, grantId: grant.grant.id }));
+  });
+
+  it('replays a completed command idempotently through the audit machinery', async () => {
+    const key = `key-${randomUUID()}`;
+    const input = { actorId: OWNER, companyId, name: 'Replayed Estate', slug: slug('replay') };
+    const first = expectOk(await repo.createEstate({ ...input, idempotencyKey: key }));
+    // The retry's insert no-ops on the slug conflict — the command surfaces
+    // `conflict`, and crucially appends no second event under the key.
+    const retry = await repo.createEstate({ ...input, idempotencyKey: key });
+    expect(retry.ok).toBe(false);
+    expect(await eventsForKey(key)).toHaveLength(1);
+    expectOk(await repo.deleteEstate({ actorId: OWNER, estateId: first.estate.id }));
+  });
+
+  // ── §6.5 authorization ─────────────────────────────────────────────────────
+
+  it('deny-by-default: a user with no grant cannot mutate and sees not_found (§3.1)', async () => {
+    expect(await repo.renameCompany({ actorId: STRANGER, companyId, name: 'x' })).toEqual({
+      ok: false,
+      error: 'not_found',
+    });
+    expect(
+      await repo.createEstate({ actorId: STRANGER, companyId, name: 'x', slug: slug('deny') }),
+    ).toEqual({ ok: false, error: 'not_found' });
+    expect(await repo.deleteCompany({ actorId: STRANGER, companyId })).toEqual({
+      ok: false,
+      error: 'not_found',
+    });
+  });
+
+  it('grant management requires effective owner: member and viewer are refused (§4.1)', async () => {
+    const grant = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'company',
+        targetId: companyId,
+        role: 'member',
+      }),
+    );
+    expect(
+      await repo.createGrant({
+        actorId: SUBJECT,
+        userId: STRANGER,
+        targetKind: 'company',
+        targetId: companyId,
+        role: 'viewer',
+      }),
+    ).toEqual({ ok: false, error: 'not_found' });
+    expect(await repo.revokeGrant({ actorId: SUBJECT, grantId: grant.grant.id })).toEqual({
+      ok: false,
+      error: 'not_found',
+    });
+    // Member also cannot create children (owner-only, §4.1/§4.3).
+    expect(
+      await repo.createEstate({ actorId: SUBJECT, companyId, name: 'x', slug: slug('member') }),
+    ).toEqual({ ok: false, error: 'not_found' });
+    expectOk(await repo.revokeGrant({ actorId: OWNER, grantId: grant.grant.id }));
+  });
+
+  it('platform admin confers no tenant content access (§1.1): ungrated admin is a stranger', async () => {
+    expect(await repo.renameCompany({ actorId: ADMIN, companyId, name: 'x' })).toEqual({
+      ok: false,
+      error: 'not_found',
+    });
+    expect(
+      await repo.createGrant({
+        actorId: ADMIN,
+        userId: SUBJECT,
+        targetKind: 'company',
+        targetId: companyId,
+        role: 'viewer',
+      }),
+    ).toEqual({ ok: false, error: 'not_found' });
+    expect(await repo.listGrantedCompanies(ADMIN)).toEqual([]);
+    expect(await evaluation.effectiveRole(ADMIN, 'company', companyId)).toBeNull();
+  });
+
+  it('visibility change is platform-admin-only (§5.5): the owner is forbidden, the admin succeeds', async () => {
+    const owned = await repo.changeCompanyVisibility({
+      actorId: OWNER,
+      companyId,
+      visibility: 'directory',
+    });
+    expect(owned).toEqual({
+      ok: false,
+      error: 'forbidden',
+      message: 'visibility change is platform-admin-only',
+    });
+    const changed = expectOk(
+      await repo.changeCompanyVisibility({ actorId: ADMIN, companyId, visibility: 'directory' }),
+    );
+    expect(changed.company.visibility).toBe('directory');
+    // Restore for later witnesses.
+    expectOk(
+      await repo.changeCompanyVisibility({ actorId: ADMIN, companyId, visibility: 'private' }),
+    );
+  });
+
+  // ── §6.9 visibility ────────────────────────────────────────────────────────
+
+  it('directory lists exactly directory-class companies with closed fields (§2.8)', async () => {
+    const listed = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'Listed Co', slug: slug('listed') }),
+    );
+    const unlisted = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'Unlisted Co', slug: slug('unlisted') }),
+    );
+    const key = `key-${randomUUID()}`;
+    expectOk(
+      await repo.changeCompanyVisibility({
+        actorId: ADMIN,
+        companyId: listed.company.id,
+        visibility: 'directory',
+        idempotencyKey: key,
+      }),
+    );
+
+    const directory = await repo.listDirectory();
+    const ids = directory.map((entry) => entry.id);
+    expect(ids).toContain(listed.company.id);
+    expect(ids).not.toContain(unlisted.company.id);
+    expect(ids).not.toContain(companyId);
+    // Closed-field: existence, name, slug — nothing else (no visibility, no
+    // timestamps, no grant or membership data).
+    for (const entry of directory) {
+      expect(Object.keys(entry).sort()).toEqual(['id', 'name', 'slug']);
+    }
+
+    // §5.5: the audited event carries old and new values.
+    const events = await eventsForKey(key);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ verb: 'visibility_change', targetId: listed.company.id });
+    expect(events[0]!.targetSnapshot).toMatchObject({
+      previousVisibility: 'private',
+      visibility: 'directory',
+    });
+  });
+
+  it('directory disclosure confers no authority: a listed company still refuses non-granted callers (§6.9)', async () => {
+    const listed = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'Exposed Co', slug: slug('exposed') }),
+    );
+    expectOk(
+      await repo.changeCompanyVisibility({
+        actorId: ADMIN,
+        companyId: listed.company.id,
+        visibility: 'directory',
+      }),
+    );
+
+    // The company is directory-listed for the whole probe window...
+    expect((await repo.listDirectory()).map((entry) => entry.id)).toContain(listed.company.id);
+
+    // ...but the non-granted reader's granted-read surface still excludes it:
+    // directory disclosure adds existence/name/slug only, never content access.
+    expect(await repo.listGrantedCompanies(STRANGER)).toEqual([]);
+
+    // A stranger mutation of the listed company is refused exactly like a
+    // missing node — the §6.7 carve-out covers the listing, not commands.
+    const realProbe = await repo.renameCompany({
+      actorId: STRANGER,
+      companyId: listed.company.id,
+      name: 'x',
+    });
+    const missingProbe = await repo.renameCompany({
+      actorId: STRANGER,
+      companyId: randomUUID(),
+      name: 'x',
+    });
+    expect(realProbe).toEqual(missingProbe);
+    expect(await repo.deleteCompany({ actorId: STRANGER, companyId: listed.company.id })).toEqual({
+      ok: false,
+      error: 'not_found',
+    });
+  });
+
+  it('granted companies are the reader control: owner sees them, a stranger sees nothing (§2.8)', async () => {
+    const ownerCompanies = await repo.listGrantedCompanies(OWNER);
+    expect(ownerCompanies.map((c) => c.id)).toContain(companyId);
+    expect(await repo.listGrantedCompanies(STRANGER)).toEqual([]);
+  });
+
+  // ── §6.7 no existence oracle ───────────────────────────────────────────────
+
+  it('an unauthorized probe of a real node is indistinguishable from a missing node', async () => {
+    const realCompany = await repo.renameCompany({ actorId: STRANGER, companyId, name: 'x' });
+    const missingCompany = await repo.renameCompany({
+      actorId: STRANGER,
+      companyId: randomUUID(),
+      name: 'x',
+    });
+    expect(realCompany).toEqual(missingCompany);
+
+    const estate = expectOk(
+      await repo.createEstate({
+        actorId: OWNER,
+        companyId,
+        name: 'Oracle E',
+        slug: slug('oracle'),
+      }),
+    );
+    const realEstate = await repo.deleteEstate({ actorId: STRANGER, estateId: estate.estate.id });
+    const missingEstate = await repo.deleteEstate({ actorId: STRANGER, estateId: randomUUID() });
+    expect(realEstate).toEqual(missingEstate);
+
+    const grant = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'estate',
+        targetId: estate.estate.id,
+        role: 'viewer',
+      }),
+    );
+    const realGrant = await repo.revokeGrant({ actorId: STRANGER, grantId: grant.grant.id });
+    const missingGrant = await repo.revokeGrant({ actorId: STRANGER, grantId: randomUUID() });
+    expect(realGrant).toEqual(missingGrant);
+    expectOk(await repo.deleteEstate({ actorId: OWNER, estateId: estate.estate.id }));
+  });
+
+  // ── contract 2 §3 grant evaluation ─────────────────────────────────────────
+
+  it('a company grant confers its role down the whole chain, workspace included (§3.2)', async () => {
+    const estate = expectOk(
+      await repo.createEstate({ actorId: OWNER, companyId, name: 'Chain E', slug: slug('chain') }),
+    );
+    const project = expectOk(
+      await repo.createPlatformProject({
+        actorId: OWNER,
+        estateId: estate.estate.id,
+        name: 'Chain P',
+        slug: slug('chain-p'),
+      }),
+    );
+    // Workspaces are evaluable but not hierarchy commands; seed one directly.
+    const workspaceId = randomUUID();
+    await handle.db.insert(workspaces).values({
+      id: workspaceId,
+      name: 'Chain W',
+      slug: slug('chain-w'),
+      platformProjectId: project.platformProject.id,
+    });
+
+    for (const [kind, id] of [
+      ['company', companyId],
+      ['estate', estate.estate.id],
+      ['platform_project', project.platformProject.id],
+      ['workspace', workspaceId],
+    ] as const) {
+      expect(await evaluation.effectiveRole(OWNER, kind, id)).toBe('owner');
+      expect(await evaluation.effectiveRole(STRANGER, kind, id)).toBeNull();
+    }
+
+    // Max-role (§3.3): viewer on the company + owner on the estate → owner at
+    // and below the estate, viewer at the company.
+    const viewerGrant = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'company',
+        targetId: companyId,
+        role: 'viewer',
+      }),
+    );
+    const ownerGrant = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'estate',
+        targetId: estate.estate.id,
+        role: 'owner',
+      }),
+    );
+    expect(await evaluation.effectiveRole(SUBJECT, 'company', companyId)).toBe('viewer');
+    expect(await evaluation.effectiveRole(SUBJECT, 'estate', estate.estate.id)).toBe('owner');
+    expect(await evaluation.effectiveRole(SUBJECT, 'workspace', workspaceId)).toBe('owner');
+
+    // Revocation is row deletion and denies the very next evaluation (§6).
+    expectOk(await repo.revokeGrant({ actorId: OWNER, grantId: ownerGrant.grant.id }));
+    expect(await evaluation.effectiveRole(SUBJECT, 'estate', estate.estate.id)).toBe('viewer');
+    expectOk(await repo.revokeGrant({ actorId: OWNER, grantId: viewerGrant.grant.id }));
+    expect(await evaluation.effectiveRole(SUBJECT, 'company', companyId)).toBeNull();
+
+    await handle.db.delete(workspaces).where(eq(workspaces.id, workspaceId));
+    expectOk(
+      await repo.deletePlatformProject({
+        actorId: OWNER,
+        platformProjectId: project.platformProject.id,
+      }),
+    );
+    expectOk(await repo.deleteEstate({ actorId: OWNER, estateId: estate.estate.id }));
+  });
+
+  it('team grant subjects are suspended: a team row confers nothing and cannot be changed (§1.4)', async () => {
+    const teamId = randomUUID();
+    await handle.db.insert(teams).values({
+      id: teamId,
+      name: slug('team'),
+      slug: slug('team'),
+      ownerId: SUBJECT,
+      managerId: SUBJECT,
+    });
+    // Out-of-band team row (the command surface cannot create one).
+    const inserted = await handle.db
+      .insert(hierarchyGrants)
+      .values({ teamId, companyId, role: 'owner', grantedBy: OWNER })
+      .returning();
+    const teamGrantId = inserted[0]!.id;
+
+    // The team's own owner gains no effective role from it.
+    expect(await evaluation.effectiveRole(SUBJECT, 'company', companyId)).toBeNull();
+    // changeGrant refuses the row.
+    expect(
+      await repo.changeGrant({ actorId: OWNER, grantId: teamGrantId, role: 'viewer' }),
+    ).toEqual({
+      ok: false,
+      error: 'conflict',
+      message: 'team grant subjects are suspended',
+    });
+    await handle.db.delete(hierarchyGrants).where(eq(hierarchyGrants.id, teamGrantId));
+    await handle.db.delete(teams).where(eq(teams.id, teamId));
+  });
+
+  // ── command conflict semantics ─────────────────────────────────────────────
+
+  it('transfer needs owner on both parents in its own transaction, and refuses no-op and colliding transfers (§5)', async () => {
+    const source = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'Src Co', slug: slug('src') }),
+    );
+    const destination = expectOk(
+      await repo.createCompany({ actorId: SUBJECT, name: 'Dst Co', slug: slug('dst') }),
+    );
+    const estateSlug = slug('mv');
+    const estate = expectOk(
+      await repo.createEstate({
+        actorId: OWNER,
+        companyId: source.company.id,
+        name: 'Mv E',
+        slug: estateSlug,
+      }),
+    );
+
+    // OWNER owns the source but not the destination → not_found (§6.7-safe).
+    expect(
+      await repo.transferEstate({
+        actorId: OWNER,
+        estateId: estate.estate.id,
+        destinationCompanyId: destination.company.id,
+      }),
+    ).toEqual({ ok: false, error: 'not_found' });
+
+    // Same-parent transfer is refused.
+    const samePlace = await repo.transferEstate({
+      actorId: OWNER,
+      estateId: estate.estate.id,
+      destinationCompanyId: source.company.id,
+    });
+    expect(samePlace.ok).toBe(false);
+    if (!samePlace.ok) expect(samePlace.error).toBe('conflict');
+
+    // Grant OWNER the destination; a slug collision there is refused.
+    expectOk(
+      await repo.createGrant({
+        actorId: SUBJECT,
+        userId: OWNER,
+        targetKind: 'company',
+        targetId: destination.company.id,
+        role: 'owner',
+      }),
+    );
+    expectOk(
+      await repo.createEstate({
+        actorId: OWNER,
+        companyId: destination.company.id,
+        name: 'Collide',
+        slug: estateSlug,
+      }),
+    );
+    const collision = await repo.transferEstate({
+      actorId: OWNER,
+      estateId: estate.estate.id,
+      destinationCompanyId: destination.company.id,
+    });
+    expect(collision.ok).toBe(false);
+    if (!collision.ok) expect(collision.error).toBe('conflict');
+  });
+
+  it('a successful transfer records transfer_from and transfer_to (§6.4 three-leg witness)', async () => {
+    const from = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'From Co', slug: slug('from') }),
+    );
+    const to = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'To Co', slug: slug('to') }),
+    );
+    const estate = expectOk(
+      await repo.createEstate({
+        actorId: OWNER,
+        companyId: from.company.id,
+        name: 'Moved E',
+        slug: slug('moved'),
+      }),
+    );
+    const key = `key-${randomUUID()}`;
+    expectOk(
+      await repo.transferEstate({
+        actorId: OWNER,
+        estateId: estate.estate.id,
+        destinationCompanyId: to.company.id,
+        idempotencyKey: key,
+      }),
+    );
+    const moved = (
+      await handle.db.select().from(estates).where(eq(estates.id, estate.estate.id))
+    )[0]!;
+    expect(moved.companyId).toBe(to.company.id);
+    const events = await eventsForKey(key);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ verb: 'transfer', targetId: estate.estate.id });
+    expect(events[0]!.transferFrom).toMatchObject({ kind: 'company', id: from.company.id });
+    expect(events[0]!.transferTo).toMatchObject({ kind: 'company', id: to.company.id });
+    // The post-transfer snapshot's parent chain names the destination.
+    expect(events[0]!.targetSnapshot).toMatchObject({
+      parentChain: [{ kind: 'company', id: to.company.id, slug: to.company.slug }],
+    });
+  });
+
+  it('refuses duplicate slugs, deletes with children, and degenerate grant commands as conflicts', async () => {
+    const co = expectOk(
+      await repo.createCompany({ actorId: OWNER, name: 'Conflict Co', slug: slug('conf') }),
+    );
+    const dupSlug = await repo.createCompany({ actorId: OWNER, name: 'x', slug: co.company.slug });
+    expect(dupSlug.ok).toBe(false);
+    if (!dupSlug.ok) expect(dupSlug.error).toBe('conflict');
+
+    expectOk(
+      await repo.createEstate({
+        actorId: OWNER,
+        companyId: co.company.id,
+        name: 'Child',
+        slug: slug('child'),
+      }),
+    );
+    const withChildren = await repo.deleteCompany({ actorId: OWNER, companyId: co.company.id });
+    expect(withChildren.ok).toBe(false);
+    if (!withChildren.ok) expect(withChildren.error).toBe('conflict');
+
+    // Grant to a nonexistent subject is refused (the caller already holds
+    // owner, so the refusal discloses nothing new).
+    const ghost = await repo.createGrant({
+      actorId: OWNER,
+      userId: `missing-${randomUUID()}`,
+      targetKind: 'company',
+      targetId: co.company.id,
+      role: 'viewer',
+    });
+    expect(ghost.ok).toBe(false);
+    if (!ghost.ok) expect(ghost.error).toBe('conflict');
+
+    const grant = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'company',
+        targetId: co.company.id,
+        role: 'viewer',
+      }),
+    );
+    const duplicate = await repo.createGrant({
+      actorId: OWNER,
+      userId: SUBJECT,
+      targetKind: 'company',
+      targetId: co.company.id,
+      role: 'viewer',
+    });
+    expect(duplicate.ok).toBe(false);
+    if (!duplicate.ok) expect(duplicate.error).toBe('conflict');
+
+    const sameRole = await repo.changeGrant({
+      actorId: OWNER,
+      grantId: grant.grant.id,
+      role: 'viewer',
+    });
+    expect(sameRole.ok).toBe(false);
+    if (!sameRole.ok) expect(sameRole.error).toBe('conflict');
+
+    // A second grant with another role exists → changing the first onto that
+    // role would collide with the unique constraint; refused ahead of it.
+    const second = expectOk(
+      await repo.createGrant({
+        actorId: OWNER,
+        userId: SUBJECT,
+        targetKind: 'company',
+        targetId: co.company.id,
+        role: 'member',
+      }),
+    );
+    const collide = await repo.changeGrant({
+      actorId: OWNER,
+      grantId: grant.grant.id,
+      role: 'member',
+    });
+    expect(collide.ok).toBe(false);
+    if (!collide.ok) expect(collide.error).toBe('conflict');
+
+    // A clean change succeeds and records the previous role, namespaced (§4.5).
+    const changeKey = `key-${randomUUID()}`;
+    const changed = expectOk(
+      await repo.changeGrant({
+        actorId: OWNER,
+        grantId: second.grant.id,
+        role: 'owner',
+        idempotencyKey: changeKey,
+      }),
+    );
+    expect(changed.grant.role).toBe('hierarchy:owner');
+    const events = await eventsForKey(changeKey);
+    expect(events).toHaveLength(1);
+    expect(events[0]!.targetSnapshot).toMatchObject({
+      role: 'hierarchy:owner',
+      previousRole: 'hierarchy:member',
+    });
+  });
+});

apps/gateway/src/hierarchy/hierarchy-grant-evaluation.ts

@@ -0,0 +1,242 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  companies,
+  eq,
+  estates,
+  hierarchyGrants,
+  inArray,
+  or,
+  platformProjects,
+  workspaces,
+  and,
+  type Db,
+  HIERARCHY_GRANT_ROLES,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+
+/**
+ * Hierarchy grant evaluation (contract 2 §3).
+ *
+ * Deny-by-default (§3.1): a user's effective role on a node is null unless a
+ * grant row explicitly confers one. Grants apply down the chain only (§3.2):
+ * the effective role on a node is the maximum role over grants targeting the
+ * node itself or any of its ancestors, maximum per the total order
+ * viewer ⊂ member ⊂ owner (§2). Evaluation is live and per-decision — no
+ * caching — so revocation (row deletion, §6) denies the next decision
+ * inherently. A missing node evaluates to null, indistinguishable from
+ * no-grant, which keeps unauthorized probes oracle-safe (contract 1 §6.7).
+ *
+ * Team grant subjects are SUSPENDED (§1.4): the command surface refuses to
+ * create them and this evaluator considers user-subject grants only, so a
+ * team row could not confer access even if one existed.
+ *
+ * Read-only module: it selects from the class tables but never writes them,
+ * so it does not appear on the writer-coverage allowlist.
+ */
+
+export type HierarchyGrantRole = (typeof HIERARCHY_GRANT_ROLES)[number];
+
+/** Node kinds a grant may target (§3.2; workspace is evaluable, not grantable). */
+export type GrantTargetKind = 'company' | 'estate' | 'platform_project';
+/** Node kinds an authorization decision may be evaluated at (§3.2: down to workspace). */
+export type EvaluableNodeKind = GrantTargetKind | 'workspace';
+
+type Tx = Pick<Db, 'select'>;
+
+/** Ancestor chain of a node, self included at its own level; ids only. */
+export interface AncestorChain {
+  readonly companyId: string;
+  readonly estateId?: string;
+  readonly platformProjectId?: string;
+  readonly workspaceId?: string;
+}
+
+export function roleStrength(role: HierarchyGrantRole): number {
+  return HIERARCHY_GRANT_ROLES.indexOf(role);
+}
+
+export function roleAtLeast(
+  role: HierarchyGrantRole | null,
+  required: HierarchyGrantRole,
+): boolean {
+  return role !== null && roleStrength(role) >= roleStrength(required);
+}
+
+/**
+ * Serialized role strings are namespaced (§4.5): audit events and API
+ * responses carry `hierarchy:owner`, never a bare `owner`.
+ */
+export function namespacedHierarchyRole(role: HierarchyGrantRole): string {
+  return `hierarchy:${role}`;
+}
+
+/**
+ * Resolve a node's ancestor chain (self included). Returns null when the
+ * node does not exist — callers treat that exactly like no-grant (§3.1,
+ * oracle-safe).
+ */
+export async function resolveAncestorChain(
+  tx: Tx,
+  kind: EvaluableNodeKind,
+  id: string,
+): Promise<AncestorChain | null> {
+  if (kind === 'company') {
+    const rows = await tx
+      .select({ id: companies.id })
+      .from(companies)
+      .where(eq(companies.id, id))
+      .limit(1);
+    const row = rows[0];
+    return row ? { companyId: row.id } : null;
+  }
+  if (kind === 'estate') {
+    const rows = await tx
+      .select({ id: estates.id, companyId: estates.companyId })
+      .from(estates)
+      .where(eq(estates.id, id))
+      .limit(1);
+    const row = rows[0];
+    return row ? { companyId: row.companyId, estateId: row.id } : null;
+  }
+  if (kind === 'platform_project') {
+    const rows = await tx
+      .select({
+        id: platformProjects.id,
+        estateId: platformProjects.estateId,
+        companyId: estates.companyId,
+      })
+      .from(platformProjects)
+      .innerJoin(estates, eq(estates.id, platformProjects.estateId))
+      .where(eq(platformProjects.id, id))
+      .limit(1);
+    const row = rows[0];
+    return row
+      ? { companyId: row.companyId, estateId: row.estateId, platformProjectId: row.id }
+      : null;
+  }
+  const rows = await tx
+    .select({
+      id: workspaces.id,
+      platformProjectId: workspaces.platformProjectId,
+      estateId: platformProjects.estateId,
+      companyId: estates.companyId,
+    })
+    .from(workspaces)
+    .innerJoin(platformProjects, eq(platformProjects.id, workspaces.platformProjectId))
+    .innerJoin(estates, eq(estates.id, platformProjects.estateId))
+    .where(eq(workspaces.id, id))
+    .limit(1);
+  const row = rows[0];
+  return row
+    ? {
+        companyId: row.companyId,
+        estateId: row.estateId,
+        platformProjectId: row.platformProjectId,
+        workspaceId: row.id,
+      }
+    : null;
+}
+
+function maxRole(roles: readonly string[]): HierarchyGrantRole | null {
+  let best: HierarchyGrantRole | null = null;
+  for (const candidate of roles) {
+    // Fail-closed: a value outside the vocabulary confers nothing.
+    if (!(HIERARCHY_GRANT_ROLES as readonly string[]).includes(candidate)) continue;
+    const role = candidate as HierarchyGrantRole;
+    if (best === null || roleStrength(role) > roleStrength(best)) best = role;
+  }
+  return best;
+}
+
+/**
+ * Effective role of a user on a node: maximum over the user's grants whose
+ * target is the node or any ancestor (§3.2); null = deny (§3.1). Missing
+ * node → null.
+ */
+export async function evaluateEffectiveRole(
+  tx: Tx,
+  userId: string,
+  kind: EvaluableNodeKind,
+  id: string,
+): Promise<HierarchyGrantRole | null> {
+  const chain = await resolveAncestorChain(tx, kind, id);
+  if (!chain) return null;
+
+  const targetConditions = [eq(hierarchyGrants.companyId, chain.companyId)];
+  if (chain.estateId) targetConditions.push(eq(hierarchyGrants.estateId, chain.estateId));
+  if (chain.platformProjectId) {
+    targetConditions.push(eq(hierarchyGrants.platformProjectId, chain.platformProjectId));
+  }
+
+  const rows = await tx
+    .select({ role: hierarchyGrants.role })
+    .from(hierarchyGrants)
+    .where(and(eq(hierarchyGrants.userId, userId), or(...targetConditions)));
+  return maxRole(rows.map((r) => r.role));
+}
+
+/**
+ * All companies on which the user holds any effective role, i.e. companies
+ * with a grant on the company itself or on any descendant (contract 1 §2.8:
+ * a grant anywhere in the subtree discloses the company's chain upward).
+ */
+export async function grantedCompanyIds(tx: Tx, userId: string): Promise<string[]> {
+  const grants = await tx
+    .select({
+      companyId: hierarchyGrants.companyId,
+      estateId: hierarchyGrants.estateId,
+      platformProjectId: hierarchyGrants.platformProjectId,
+    })
+    .from(hierarchyGrants)
+    .where(eq(hierarchyGrants.userId, userId));
+
+  const companyIds = new Set<string>();
+  const estateIds = new Set<string>();
+  const platformProjectIds = new Set<string>();
+  for (const grant of grants) {
+    if (grant.companyId) companyIds.add(grant.companyId);
+    else if (grant.estateId) estateIds.add(grant.estateId);
+    else if (grant.platformProjectId) platformProjectIds.add(grant.platformProjectId);
+  }
+
+  if (platformProjectIds.size > 0) {
+    const rows = await tx
+      .select({ estateId: platformProjects.estateId })
+      .from(platformProjects)
+      .where(inArray(platformProjects.id, [...platformProjectIds]));
+    for (const row of rows) estateIds.add(row.estateId);
+  }
+  if (estateIds.size > 0) {
+    const rows = await tx
+      .select({ companyId: estates.companyId })
+      .from(estates)
+      .where(inArray(estates.id, [...estateIds]));
+    for (const row of rows) companyIds.add(row.companyId);
+  }
+  return [...companyIds];
+}
+
+@Injectable()
+export class HierarchyGrantEvaluationService {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  /** Live per-decision evaluation; pass a tx to evaluate inside a command's transaction. */
+  effectiveRole(
+    userId: string,
+    kind: EvaluableNodeKind,
+    id: string,
+    tx?: Tx,
+  ): Promise<HierarchyGrantRole | null> {
+    return evaluateEffectiveRole(tx ?? this.db, userId, kind, id);
+  }
+
+  async hasRole(
+    userId: string,
+    kind: EvaluableNodeKind,
+    id: string,
+    required: HierarchyGrantRole,
+    tx?: Tx,
+  ): Promise<boolean> {
+    return roleAtLeast(await this.effectiveRole(userId, kind, id, tx), required);
+  }
+}

apps/gateway/src/hierarchy/hierarchy.controller.ts

@@ -0,0 +1,297 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import {
+  ChangeCompanyVisibilityDto,
+  ChangeGrantDto,
+  CreateCompanyDto,
+  CreateEstateDto,
+  CreateGrantDto,
+  CreatePlatformProjectDto,
+  DeleteNodeDto,
+  RenameNodeDto,
+  TransferEstateDto,
+  TransferPlatformProjectDto,
+} from './hierarchy.dto.js';
+import { HierarchyRepository } from './hierarchy.repository.js';
+import { HierarchyService } from './hierarchy.service.js';
+
+/**
+ * The hierarchy command family (contract 1 §5, §6.3). This controller is the
+ * closed HTTP surface over the hierarchy class tables: the route-inventory
+ * witness asserts these routes and no others exist. Delete commands take an
+ * optional body (idempotency key) via POST-style DTOs; every mutation is
+ * audited on its own transaction by the repository.
+ */
+@Controller('api/hierarchy')
+@UseGuards(AuthGuard)
+export class HierarchyController {
+  constructor(
+    private readonly repository: HierarchyRepository,
+    private readonly service: HierarchyService,
+  ) {}
+
+  // ── companies ────────────────────────────────────────────────────────────
+
+  @Post('companies')
+  async createCompany(@CurrentUser() user: { id: string }, @Body() dto: CreateCompanyDto) {
+    return this.service.unwrap(
+      await this.repository.createCompany({
+        actorId: user.id,
+        name: dto.name,
+        slug: dto.slug,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  /** Companies the caller holds a grant on (directly or via a descendant). */
+  @Get('companies')
+  listGrantedCompanies(@CurrentUser() user: { id: string }) {
+    return this.repository.listGrantedCompanies(user.id);
+  }
+
+  /** Directory-class companies, closed-field (§2.8). */
+  @Get('companies/directory')
+  listDirectory() {
+    return this.repository.listDirectory();
+  }
+
+  @Post('companies/:id/rename')
+  @HttpCode(200)
+  async renameCompany(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: RenameNodeDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.renameCompany({
+        actorId: user.id,
+        companyId: id,
+        name: dto.name,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Post('companies/:id/visibility')
+  @HttpCode(200)
+  async changeCompanyVisibility(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: ChangeCompanyVisibilityDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.changeCompanyVisibility({
+        actorId: user.id,
+        companyId: id,
+        visibility: dto.visibility,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Delete('companies/:id')
+  async deleteCompany(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: DeleteNodeDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.deleteCompany({
+        actorId: user.id,
+        companyId: id,
+        idempotencyKey: dto?.idempotencyKey,
+      }),
+    );
+  }
+
+  // ── estates ──────────────────────────────────────────────────────────────
+
+  @Post('estates')
+  async createEstate(@CurrentUser() user: { id: string }, @Body() dto: CreateEstateDto) {
+    return this.service.unwrap(
+      await this.repository.createEstate({
+        actorId: user.id,
+        companyId: dto.companyId,
+        name: dto.name,
+        slug: dto.slug,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Post('estates/:id/rename')
+  @HttpCode(200)
+  async renameEstate(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: RenameNodeDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.renameEstate({
+        actorId: user.id,
+        estateId: id,
+        name: dto.name,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Post('estates/:id/transfer')
+  @HttpCode(200)
+  async transferEstate(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: TransferEstateDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.transferEstate({
+        actorId: user.id,
+        estateId: id,
+        destinationCompanyId: dto.destinationCompanyId,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Delete('estates/:id')
+  async deleteEstate(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: DeleteNodeDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.deleteEstate({
+        actorId: user.id,
+        estateId: id,
+        idempotencyKey: dto?.idempotencyKey,
+      }),
+    );
+  }
+
+  // ── platform projects ────────────────────────────────────────────────────
+
+  @Post('platform-projects')
+  async createPlatformProject(
+    @CurrentUser() user: { id: string },
+    @Body() dto: CreatePlatformProjectDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.createPlatformProject({
+        actorId: user.id,
+        estateId: dto.estateId,
+        name: dto.name,
+        slug: dto.slug,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Post('platform-projects/:id/rename')
+  @HttpCode(200)
+  async renamePlatformProject(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: RenameNodeDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.renamePlatformProject({
+        actorId: user.id,
+        platformProjectId: id,
+        name: dto.name,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Post('platform-projects/:id/transfer')
+  @HttpCode(200)
+  async transferPlatformProject(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: TransferPlatformProjectDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.transferPlatformProject({
+        actorId: user.id,
+        platformProjectId: id,
+        destinationEstateId: dto.destinationEstateId,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Delete('platform-projects/:id')
+  async deletePlatformProject(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: DeleteNodeDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.deletePlatformProject({
+        actorId: user.id,
+        platformProjectId: id,
+        idempotencyKey: dto?.idempotencyKey,
+      }),
+    );
+  }
+
+  // ── grants ───────────────────────────────────────────────────────────────
+
+  @Post('grants')
+  async createGrant(@CurrentUser() user: { id: string }, @Body() dto: CreateGrantDto) {
+    return this.service.unwrap(
+      await this.repository.createGrant({
+        actorId: user.id,
+        userId: dto.userId,
+        targetKind: dto.targetKind,
+        targetId: dto.targetId,
+        role: dto.role,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Post('grants/:id/change')
+  @HttpCode(200)
+  async changeGrant(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: ChangeGrantDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.changeGrant({
+        actorId: user.id,
+        grantId: id,
+        role: dto.role,
+        idempotencyKey: dto.idempotencyKey,
+      }),
+    );
+  }
+
+  @Delete('grants/:id')
+  async revokeGrant(
+    @CurrentUser() user: { id: string },
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: DeleteNodeDto,
+  ) {
+    return this.service.unwrap(
+      await this.repository.revokeGrant({
+        actorId: user.id,
+        grantId: id,
+        idempotencyKey: dto?.idempotencyKey,
+      }),
+    );
+  }
+}

apps/gateway/src/hierarchy/hierarchy.dto.ts

@@ -0,0 +1,169 @@
+import { COMPANY_VISIBILITY, HIERARCHY_GRANT_ROLES } from '@mosaicstack/db';
+import { IsIn, IsOptional, IsString, IsUUID, Matches, MaxLength, MinLength } from 'class-validator';
+
+/**
+ * Hierarchy command DTOs (contract 1 §5, contract 2 §4/§7).
+ *
+ * The global ValidationPipe runs with whitelist + forbidNonWhitelisted, so a
+ * payload field absent from these classes is a 400. That closure is itself
+ * contract surface:
+ *  - CreateCompanyDto declares NO visibility field — creation is always
+ *    private (contract 1 §5.5); a visibility argument is refused by the pipe.
+ *  - CreateGrantDto declares NO teamId field — team grant subjects are
+ *    suspended (contract 2 §1.4/§7.5); a team subject is refused by the pipe.
+ * Every class here must be registered in PIPE_GUARDED_DTOS so the boot-time
+ * assertion proves the pipe sees the decorators.
+ */
+
+const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const SLUG_MESSAGE = 'slug must be lowercase alphanumeric with interior hyphens';
+
+export class CreateCompanyDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  name!: string;
+
+  @IsString()
+  @MaxLength(100)
+  @Matches(SLUG_PATTERN, { message: SLUG_MESSAGE })
+  slug!: string;
+
+  /** Client-supplied idempotency key (REQ-AUD-001 replay); server-generated when absent. */
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class RenameNodeDto {
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  name!: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class ChangeCompanyVisibilityDto {
+  @IsIn(COMPANY_VISIBILITY)
+  visibility!: (typeof COMPANY_VISIBILITY)[number];
+
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class DeleteNodeDto {
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class CreateEstateDto {
+  @IsUUID()
+  companyId!: string;
+
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  name!: string;
+
+  @IsString()
+  @MaxLength(100)
+  @Matches(SLUG_PATTERN, { message: SLUG_MESSAGE })
+  slug!: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class CreatePlatformProjectDto {
+  @IsUUID()
+  estateId!: string;
+
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  name!: string;
+
+  @IsString()
+  @MaxLength(100)
+  @Matches(SLUG_PATTERN, { message: SLUG_MESSAGE })
+  slug!: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class TransferEstateDto {
+  @IsUUID()
+  destinationCompanyId!: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class TransferPlatformProjectDto {
+  @IsUUID()
+  destinationEstateId!: string;
+
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class CreateGrantDto {
+  /** Subject user (better-auth text id). No teamId field — see module doc. */
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  userId!: string;
+
+  @IsIn(['company', 'estate', 'platform_project'])
+  targetKind!: 'company' | 'estate' | 'platform_project';
+
+  @IsUUID()
+  targetId!: string;
+
+  /** Bare vocabulary on requests; responses and audit events are namespaced (§4.5). */
+  @IsIn(HIERARCHY_GRANT_ROLES)
+  role!: (typeof HIERARCHY_GRANT_ROLES)[number];
+
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}
+
+export class ChangeGrantDto {
+  @IsIn(HIERARCHY_GRANT_ROLES)
+  role!: (typeof HIERARCHY_GRANT_ROLES)[number];
+
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(255)
+  idempotencyKey?: string;
+}

apps/gateway/src/hierarchy/hierarchy.module.ts

@@ -1,17 +1,28 @@
 import { Module } from '@nestjs/common';
 import { HierarchyAuditRepository } from './hierarchy-audit.repository.js';
+import { HierarchyGrantEvaluationService } from './hierarchy-grant-evaluation.js';
+import { HierarchyController } from './hierarchy.controller.js';
+import { HierarchyRepository } from './hierarchy.repository.js';
+import { HierarchyService } from './hierarchy.service.js';
 
 /**
  * Hierarchy (tenancy/authorization structure) feature module.
  *
- * M4-1b-i ships the audit event + outbox machinery only (contract 1 §5.2).
- * The hierarchy command family — controllers, DTOs, and the allowlisted
- * class-table repositories — lands in M4-1b-ii once contract 2 (RBAC grant
- * model) merges; until then this module exposes no routes, which the
- * route-inventory witness asserts.
+ * M4-1b-i shipped the audit event + outbox machinery (contract 1 §5.2);
+ * M4-1b-ii adds the command family — the closed route surface asserted by
+ * the route-inventory witness — plus grant evaluation (contract 2 §3).
+ * HierarchyRepository is the sole class-table writer (writer-coverage
+ * allowlist); every mutation runs authorize → mutate → audit in one
+ * transaction.
  */
 @Module({
-  providers: [HierarchyAuditRepository],
-  exports: [HierarchyAuditRepository],
+  controllers: [HierarchyController],
+  providers: [
+    HierarchyAuditRepository,
+    HierarchyGrantEvaluationService,
+    HierarchyRepository,
+    HierarchyService,
+  ],
+  exports: [HierarchyAuditRepository, HierarchyGrantEvaluationService],
 })
 export class HierarchyModule {}

apps/gateway/src/hierarchy/hierarchy.repository.ts

@@ -0,0 +1,935 @@
+import { randomUUID } from 'node:crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  asc,
+  companies,
+  eq,
+  estates,
+  hierarchyGrants,
+  inArray,
+  platformProjects,
+  users,
+  workspaces,
+  type Db,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+import {
+  appendHierarchyEvent,
+  buildNodeSnapshot,
+  HierarchyAuditIdempotencyConflictError,
+} from './hierarchy-audit.repository.js';
+import {
+  evaluateEffectiveRole,
+  grantedCompanyIds,
+  namespacedHierarchyRole,
+  roleAtLeast,
+  type GrantTargetKind,
+  type HierarchyGrantRole,
+} from './hierarchy-grant-evaluation.js';
+
+/**
+ * Hierarchy command repository (contract 1 §5, contract 2 §4).
+ *
+ * The ONLY writer of the hierarchy class tables (companies, estates,
+ * platform_projects, hierarchy_grants) — it is the writer-coverage
+ * allowlist's sole entry. Every command runs one transaction that
+ * authorizes (live grant evaluation inside the same transaction), mutates,
+ * and appends the semantic audit event + outbox record via the M4-1b-i
+ * machinery, so state, event, and outbox commit or roll back together
+ * (REQ-AUD-001).
+ *
+ * Authorization failure and target-not-found both return `not_found`
+ * (contract 1 §6.7: no existence oracle — an unauthorized caller learns
+ * nothing a stranger would not). `forbidden` appears only where the caller
+ * already knows the surface exists independent of any node: the admin-only
+ * visibility change (§5.5). Serialized role strings are namespaced (§4.5).
+ */
+
+export type HierarchyCommandFailure =
+  | { readonly ok: false; readonly error: 'not_found' }
+  | { readonly ok: false; readonly error: 'forbidden'; readonly message: string }
+  | { readonly ok: false; readonly error: 'conflict'; readonly message: string };
+
+export type HierarchyResult<T> = ({ readonly ok: true } & T) | HierarchyCommandFailure;
+
+export interface CompanyView {
+  readonly id: string;
+  readonly name: string;
+  readonly slug: string;
+  readonly visibility: string;
+}
+
+export interface NodeView {
+  readonly id: string;
+  readonly name: string;
+  readonly slug: string;
+}
+
+export interface GrantView {
+  readonly id: string;
+  readonly userId: string;
+  readonly targetKind: GrantTargetKind;
+  readonly targetId: string;
+  /** Namespaced (§4.5), e.g. `hierarchy:owner`. */
+  readonly role: string;
+  readonly grantedBy: string;
+}
+
+/** Directory rows are closed-field: existence, name, slug — nothing else (§2.8). */
+export interface DirectoryEntry {
+  readonly id: string;
+  readonly name: string;
+  readonly slug: string;
+}
+
+type Tx = Pick<Db, 'insert' | 'select' | 'update' | 'delete'>;
+type GrantRow = typeof hierarchyGrants.$inferSelect;
+
+const NOT_FOUND: HierarchyCommandFailure = { ok: false, error: 'not_found' };
+
+function conflict(message: string): HierarchyCommandFailure {
+  return { ok: false, error: 'conflict', message };
+}
+
+function grantTarget(row: GrantRow): { kind: GrantTargetKind; id: string } {
+  if (row.companyId) return { kind: 'company', id: row.companyId };
+  if (row.estateId) return { kind: 'estate', id: row.estateId };
+  return { kind: 'platform_project', id: row.platformProjectId as string };
+}
+
+/** Grant event snapshot (contract 2 §4.4): subject, target, namespaced role, grantor. */
+function grantSnapshot(row: GrantRow): Record<string, unknown> {
+  const target = grantTarget(row);
+  return {
+    id: row.id,
+    subject: { userId: row.userId },
+    target: { kind: target.kind, id: target.id },
+    role: namespacedHierarchyRole(row.role as HierarchyGrantRole),
+    grantedBy: row.grantedBy,
+  };
+}
+
+function grantView(row: GrantRow): GrantView {
+  const target = grantTarget(row);
+  return {
+    id: row.id,
+    userId: row.userId as string,
+    targetKind: target.kind,
+    targetId: target.id,
+    role: namespacedHierarchyRole(row.role as HierarchyGrantRole),
+    grantedBy: row.grantedBy,
+  };
+}
+
+function companyView(row: typeof companies.$inferSelect): CompanyView {
+  return { id: row.id, name: row.name, slug: row.slug, visibility: row.visibility };
+}
+
+interface CommandContext {
+  readonly actorId: string;
+  readonly idempotencyKey: string;
+  readonly correlationId: string;
+}
+
+@Injectable()
+export class HierarchyRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  private async run<T>(
+    idempotencyKey: string | undefined,
+    actorId: string,
+    body: (tx: Tx, ctx: CommandContext) => Promise<HierarchyResult<T>>,
+  ): Promise<HierarchyResult<T>> {
+    const ctx: CommandContext = {
+      actorId,
+      idempotencyKey: idempotencyKey ?? randomUUID(),
+      correlationId: randomUUID(),
+    };
+    try {
+      return await this.db.transaction(async (tx) => body(tx, ctx));
+    } catch (error) {
+      // A key replayed with different content aborts the whole command —
+      // the transaction (state change included) has rolled back (§6.4).
+      if (error instanceof HierarchyAuditIdempotencyConflictError) {
+        return conflict(error.message);
+      }
+      throw error;
+    }
+  }
+
+  private async requireOwner(
+    tx: Tx,
+    actorId: string,
+    kind: GrantTargetKind,
+    id: string,
+  ): Promise<boolean> {
+    return roleAtLeast(await evaluateEffectiveRole(tx, actorId, kind, id), 'owner');
+  }
+
+  private async isPlatformAdmin(tx: Tx, actorId: string): Promise<boolean> {
+    const rows = await tx
+      .select({ role: users.role })
+      .from(users)
+      .where(eq(users.id, actorId))
+      .limit(1);
+    return rows[0]?.role === 'admin';
+  }
+
+  // ── companies ────────────────────────────────────────────────────────────
+
+  /**
+   * Any authenticated user may create a company; the same audited operation
+   * writes the creator's initial owner grant (§4.3), causation-linked to the
+   * create event. Visibility is always 'private' — the command takes no
+   * visibility input (§5.5).
+   */
+  createCompany(input: {
+    actorId: string;
+    name: string;
+    slug: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ company: CompanyView; grant: GrantView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      const inserted = await tx
+        .insert(companies)
+        .values({ name: input.name, slug: input.slug })
+        .onConflictDoNothing()
+        .returning();
+      const company = inserted[0];
+      if (!company) return conflict('company slug already exists');
+
+      const grantRows = await tx
+        .insert(hierarchyGrants)
+        .values({
+          userId: ctx.actorId,
+          companyId: company.id,
+          role: 'owner',
+          grantedBy: ctx.actorId,
+        })
+        .returning();
+      const grant = grantRows[0] as GrantRow;
+
+      const snapshot = await buildNodeSnapshot(tx, 'company', company.id);
+      const created = await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'create',
+        targetKind: 'company',
+        targetId: company.id,
+        targetSnapshot: { ...snapshot },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'grant_create',
+        targetKind: 'grant',
+        targetId: grant.id,
+        targetSnapshot: grantSnapshot(grant),
+        correlationId: ctx.correlationId,
+        causationId: created.event.id,
+        idempotencyKey: `${ctx.idempotencyKey}:grant`,
+      });
+      return { ok: true, company: companyView(company), grant: grantView(grant) };
+    });
+  }
+
+  renameCompany(input: {
+    actorId: string;
+    companyId: string;
+    name: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ company: CompanyView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (!(await this.requireOwner(tx, ctx.actorId, 'company', input.companyId))) {
+        return NOT_FOUND;
+      }
+      const rows = await tx
+        .select()
+        .from(companies)
+        .where(eq(companies.id, input.companyId))
+        .limit(1);
+      const previous = rows[0];
+      if (!previous) return NOT_FOUND;
+
+      const updated = await tx
+        .update(companies)
+        .set({ name: input.name, updatedAt: new Date() })
+        .where(eq(companies.id, input.companyId))
+        .returning();
+      const company = updated[0] as typeof companies.$inferSelect;
+
+      const snapshot = await buildNodeSnapshot(tx, 'company', company.id);
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'rename',
+        targetKind: 'company',
+        targetId: company.id,
+        targetSnapshot: { ...snapshot, previousName: previous.name },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return { ok: true, company: companyView(company) };
+    });
+  }
+
+  /**
+   * Admin-only until the company-CRUD capability ratifies (§5.5) — the one
+   * hierarchy mutation a platform admin performs without a grant. A
+   * non-admin caller (owner included) gets `forbidden` before any company
+   * read: the refusal reveals nothing about the target's existence.
+   */
+  changeCompanyVisibility(input: {
+    actorId: string;
+    companyId: string;
+    visibility: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ company: CompanyView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (!(await this.isPlatformAdmin(tx, ctx.actorId))) {
+        return {
+          ok: false,
+          error: 'forbidden',
+          message: 'visibility change is platform-admin-only',
+        };
+      }
+      const rows = await tx
+        .select()
+        .from(companies)
+        .where(eq(companies.id, input.companyId))
+        .limit(1);
+      const previous = rows[0];
+      if (!previous) return NOT_FOUND;
+
+      const updated = await tx
+        .update(companies)
+        .set({ visibility: input.visibility, updatedAt: new Date() })
+        .where(eq(companies.id, input.companyId))
+        .returning();
+      const company = updated[0] as typeof companies.$inferSelect;
+
+      const snapshot = await buildNodeSnapshot(tx, 'company', company.id);
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'visibility_change',
+        targetKind: 'company',
+        targetId: company.id,
+        // Old and new values are event content (§5.5).
+        targetSnapshot: {
+          ...snapshot,
+          previousVisibility: previous.visibility,
+          visibility: company.visibility,
+        },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return { ok: true, company: companyView(company) };
+    });
+  }
+
+  deleteCompany(input: {
+    actorId: string;
+    companyId: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ deletedId: string }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (!(await this.requireOwner(tx, ctx.actorId, 'company', input.companyId))) {
+        return NOT_FOUND;
+      }
+      const children = await tx
+        .select({ id: estates.id })
+        .from(estates)
+        .where(eq(estates.companyId, input.companyId))
+        .limit(1);
+      if (children.length > 0) return conflict('company still has estates');
+
+      // Snapshot and grants are read before the delete; target FKs cascade
+      // the grant rows, and each cascaded deletion is audited (§5.2).
+      const snapshot = await buildNodeSnapshot(tx, 'company', input.companyId);
+      const grants = await tx
+        .select()
+        .from(hierarchyGrants)
+        .where(eq(hierarchyGrants.companyId, input.companyId));
+
+      await tx.delete(companies).where(eq(companies.id, input.companyId));
+
+      const deleted = await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'delete',
+        targetKind: 'company',
+        targetId: input.companyId,
+        targetSnapshot: { ...snapshot },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      for (const grant of grants) {
+        await appendHierarchyEvent(tx, {
+          actorId: ctx.actorId,
+          verb: 'grant_revoke',
+          targetKind: 'grant',
+          targetId: grant.id,
+          targetSnapshot: grantSnapshot(grant),
+          correlationId: ctx.correlationId,
+          causationId: deleted.event.id,
+          idempotencyKey: `${ctx.idempotencyKey}:revoke:${grant.id}`,
+        });
+      }
+      return { ok: true, deletedId: input.companyId };
+    });
+  }
+
+  // ── estates ──────────────────────────────────────────────────────────────
+
+  /** Child creation requires owner on the parent and confers no grant (§4.3). */
+  createEstate(input: {
+    actorId: string;
+    companyId: string;
+    name: string;
+    slug: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ estate: NodeView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (!(await this.requireOwner(tx, ctx.actorId, 'company', input.companyId))) {
+        return NOT_FOUND;
+      }
+      const inserted = await tx
+        .insert(estates)
+        .values({ companyId: input.companyId, name: input.name, slug: input.slug })
+        .onConflictDoNothing()
+        .returning();
+      const estate = inserted[0];
+      if (!estate) return conflict('estate slug already exists in company');
+
+      const snapshot = await buildNodeSnapshot(tx, 'estate', estate.id);
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'create',
+        targetKind: 'estate',
+        targetId: estate.id,
+        targetSnapshot: { ...snapshot },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return { ok: true, estate: { id: estate.id, name: estate.name, slug: estate.slug } };
+    });
+  }
+
+  renameEstate(input: {
+    actorId: string;
+    estateId: string;
+    name: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ estate: NodeView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', input.estateId))) {
+        return NOT_FOUND;
+      }
+      const rows = await tx.select().from(estates).where(eq(estates.id, input.estateId)).limit(1);
+      const previous = rows[0];
+      if (!previous) return NOT_FOUND;
+
+      const updated = await tx
+        .update(estates)
+        .set({ name: input.name })
+        .where(eq(estates.id, input.estateId))
+        .returning();
+      const estate = updated[0] as typeof estates.$inferSelect;
+
+      const snapshot = await buildNodeSnapshot(tx, 'estate', estate.id);
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'rename',
+        targetKind: 'estate',
+        targetId: estate.id,
+        targetSnapshot: { ...snapshot, previousName: previous.name },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return { ok: true, estate: { id: estate.id, name: estate.name, slug: estate.slug } };
+    });
+  }
+
+  /** Transfer requires effective owner on BOTH parents, evaluated in the transfer's own transaction (§5). */
+  transferEstate(input: {
+    actorId: string;
+    estateId: string;
+    destinationCompanyId: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ estate: NodeView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      const rows = await tx.select().from(estates).where(eq(estates.id, input.estateId)).limit(1);
+      const estate = rows[0];
+      if (!estate) return NOT_FOUND;
+      if (!(await this.requireOwner(tx, ctx.actorId, 'company', estate.companyId))) {
+        return NOT_FOUND;
+      }
+      if (!(await this.requireOwner(tx, ctx.actorId, 'company', input.destinationCompanyId))) {
+        return NOT_FOUND;
+      }
+      if (estate.companyId === input.destinationCompanyId) {
+        return conflict('estate already belongs to the destination company');
+      }
+      const collision = await tx
+        .select({ id: estates.id })
+        .from(estates)
+        .where(
+          and(eq(estates.companyId, input.destinationCompanyId), eq(estates.slug, estate.slug)),
+        )
+        .limit(1);
+      if (collision.length > 0) return conflict('destination company already has that estate slug');
+
+      const parents = await tx
+        .select({ id: companies.id, slug: companies.slug })
+        .from(companies)
+        .where(inArray(companies.id, [estate.companyId, input.destinationCompanyId]));
+      const source = parents.find((p) => p.id === estate.companyId);
+      const destination = parents.find((p) => p.id === input.destinationCompanyId);
+      if (!source || !destination) return NOT_FOUND;
+
+      await tx
+        .update(estates)
+        .set({ companyId: input.destinationCompanyId })
+        .where(eq(estates.id, input.estateId));
+
+      const snapshot = await buildNodeSnapshot(tx, 'estate', input.estateId);
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'transfer',
+        targetKind: 'estate',
+        targetId: input.estateId,
+        targetSnapshot: { ...snapshot },
+        transferFrom: { kind: 'company', id: source.id, slug: source.slug },
+        transferTo: { kind: 'company', id: destination.id, slug: destination.slug },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return { ok: true, estate: { id: estate.id, name: estate.name, slug: estate.slug } };
+    });
+  }
+
+  deleteEstate(input: {
+    actorId: string;
+    estateId: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ deletedId: string }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', input.estateId))) {
+        return NOT_FOUND;
+      }
+      const children = await tx
+        .select({ id: platformProjects.id })
+        .from(platformProjects)
+        .where(eq(platformProjects.estateId, input.estateId))
+        .limit(1);
+      if (children.length > 0) return conflict('estate still has platform projects');
+
+      const snapshot = await buildNodeSnapshot(tx, 'estate', input.estateId);
+      const grants = await tx
+        .select()
+        .from(hierarchyGrants)
+        .where(eq(hierarchyGrants.estateId, input.estateId));
+
+      await tx.delete(estates).where(eq(estates.id, input.estateId));
+
+      const deleted = await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'delete',
+        targetKind: 'estate',
+        targetId: input.estateId,
+        targetSnapshot: { ...snapshot },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      for (const grant of grants) {
+        await appendHierarchyEvent(tx, {
+          actorId: ctx.actorId,
+          verb: 'grant_revoke',
+          targetKind: 'grant',
+          targetId: grant.id,
+          targetSnapshot: grantSnapshot(grant),
+          correlationId: ctx.correlationId,
+          causationId: deleted.event.id,
+          idempotencyKey: `${ctx.idempotencyKey}:revoke:${grant.id}`,
+        });
+      }
+      return { ok: true, deletedId: input.estateId };
+    });
+  }
+
+  // ── platform projects ────────────────────────────────────────────────────
+
+  createPlatformProject(input: {
+    actorId: string;
+    estateId: string;
+    name: string;
+    slug: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ platformProject: NodeView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', input.estateId))) {
+        return NOT_FOUND;
+      }
+      const inserted = await tx
+        .insert(platformProjects)
+        .values({ estateId: input.estateId, name: input.name, slug: input.slug })
+        .onConflictDoNothing()
+        .returning();
+      const project = inserted[0];
+      if (!project) return conflict('platform project slug already exists in estate');
+
+      const snapshot = await buildNodeSnapshot(tx, 'platform_project', project.id);
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'create',
+        targetKind: 'platform_project',
+        targetId: project.id,
+        targetSnapshot: { ...snapshot },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return {
+        ok: true,
+        platformProject: { id: project.id, name: project.name, slug: project.slug },
+      };
+    });
+  }
+
+  renamePlatformProject(input: {
+    actorId: string;
+    platformProjectId: string;
+    name: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ platformProject: NodeView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (
+        !(await this.requireOwner(tx, ctx.actorId, 'platform_project', input.platformProjectId))
+      ) {
+        return NOT_FOUND;
+      }
+      const rows = await tx
+        .select()
+        .from(platformProjects)
+        .where(eq(platformProjects.id, input.platformProjectId))
+        .limit(1);
+      const previous = rows[0];
+      if (!previous) return NOT_FOUND;
+
+      const updated = await tx
+        .update(platformProjects)
+        .set({ name: input.name })
+        .where(eq(platformProjects.id, input.platformProjectId))
+        .returning();
+      const project = updated[0] as typeof platformProjects.$inferSelect;
+
+      const snapshot = await buildNodeSnapshot(tx, 'platform_project', project.id);
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'rename',
+        targetKind: 'platform_project',
+        targetId: project.id,
+        targetSnapshot: { ...snapshot, previousName: previous.name },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return {
+        ok: true,
+        platformProject: { id: project.id, name: project.name, slug: project.slug },
+      };
+    });
+  }
+
+  transferPlatformProject(input: {
+    actorId: string;
+    platformProjectId: string;
+    destinationEstateId: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ platformProject: NodeView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      const rows = await tx
+        .select()
+        .from(platformProjects)
+        .where(eq(platformProjects.id, input.platformProjectId))
+        .limit(1);
+      const project = rows[0];
+      if (!project) return NOT_FOUND;
+      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', project.estateId))) {
+        return NOT_FOUND;
+      }
+      if (!(await this.requireOwner(tx, ctx.actorId, 'estate', input.destinationEstateId))) {
+        return NOT_FOUND;
+      }
+      if (project.estateId === input.destinationEstateId) {
+        return conflict('platform project already belongs to the destination estate');
+      }
+      const collision = await tx
+        .select({ id: platformProjects.id })
+        .from(platformProjects)
+        .where(
+          and(
+            eq(platformProjects.estateId, input.destinationEstateId),
+            eq(platformProjects.slug, project.slug),
+          ),
+        )
+        .limit(1);
+      if (collision.length > 0) {
+        return conflict('destination estate already has that platform project slug');
+      }
+
+      const parents = await tx
+        .select({ id: estates.id, slug: estates.slug })
+        .from(estates)
+        .where(inArray(estates.id, [project.estateId, input.destinationEstateId]));
+      const source = parents.find((p) => p.id === project.estateId);
+      const destination = parents.find((p) => p.id === input.destinationEstateId);
+      if (!source || !destination) return NOT_FOUND;
+
+      await tx
+        .update(platformProjects)
+        .set({ estateId: input.destinationEstateId })
+        .where(eq(platformProjects.id, input.platformProjectId));
+
+      const snapshot = await buildNodeSnapshot(tx, 'platform_project', input.platformProjectId);
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'transfer',
+        targetKind: 'platform_project',
+        targetId: input.platformProjectId,
+        targetSnapshot: { ...snapshot },
+        transferFrom: { kind: 'estate', id: source.id, slug: source.slug },
+        transferTo: { kind: 'estate', id: destination.id, slug: destination.slug },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return {
+        ok: true,
+        platformProject: { id: project.id, name: project.name, slug: project.slug },
+      };
+    });
+  }
+
+  deletePlatformProject(input: {
+    actorId: string;
+    platformProjectId: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ deletedId: string }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (
+        !(await this.requireOwner(tx, ctx.actorId, 'platform_project', input.platformProjectId))
+      ) {
+        return NOT_FOUND;
+      }
+      const children = await tx
+        .select({ id: workspaces.id })
+        .from(workspaces)
+        .where(eq(workspaces.platformProjectId, input.platformProjectId))
+        .limit(1);
+      if (children.length > 0) return conflict('platform project still has workspaces');
+
+      const snapshot = await buildNodeSnapshot(tx, 'platform_project', input.platformProjectId);
+      const grants = await tx
+        .select()
+        .from(hierarchyGrants)
+        .where(eq(hierarchyGrants.platformProjectId, input.platformProjectId));
+
+      await tx.delete(platformProjects).where(eq(platformProjects.id, input.platformProjectId));
+
+      const deleted = await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'delete',
+        targetKind: 'platform_project',
+        targetId: input.platformProjectId,
+        targetSnapshot: { ...snapshot },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      for (const grant of grants) {
+        await appendHierarchyEvent(tx, {
+          actorId: ctx.actorId,
+          verb: 'grant_revoke',
+          targetKind: 'grant',
+          targetId: grant.id,
+          targetSnapshot: grantSnapshot(grant),
+          correlationId: ctx.correlationId,
+          causationId: deleted.event.id,
+          idempotencyKey: `${ctx.idempotencyKey}:revoke:${grant.id}`,
+        });
+      }
+      return { ok: true, deletedId: input.platformProjectId };
+    });
+  }
+
+  // ── grants ───────────────────────────────────────────────────────────────
+
+  /** Grant management requires effective owner on the target (§4.1). */
+  createGrant(input: {
+    actorId: string;
+    userId: string;
+    targetKind: GrantTargetKind;
+    targetId: string;
+    role: HierarchyGrantRole;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ grant: GrantView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      if (!(await this.requireOwner(tx, ctx.actorId, input.targetKind, input.targetId))) {
+        return NOT_FOUND;
+      }
+      const subject = await tx
+        .select({ id: users.id })
+        .from(users)
+        .where(eq(users.id, input.userId))
+        .limit(1);
+      if (subject.length === 0) return conflict('subject user does not exist');
+
+      const inserted = await tx
+        .insert(hierarchyGrants)
+        .values({
+          userId: input.userId,
+          companyId: input.targetKind === 'company' ? input.targetId : null,
+          estateId: input.targetKind === 'estate' ? input.targetId : null,
+          platformProjectId: input.targetKind === 'platform_project' ? input.targetId : null,
+          role: input.role,
+          grantedBy: ctx.actorId,
+        })
+        .onConflictDoNothing()
+        .returning();
+      const grant = inserted[0];
+      if (!grant) return conflict('grant already exists');
+
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'grant_create',
+        targetKind: 'grant',
+        targetId: grant.id,
+        targetSnapshot: grantSnapshot(grant),
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return { ok: true, grant: grantView(grant) };
+    });
+  }
+
+  changeGrant(input: {
+    actorId: string;
+    grantId: string;
+    role: HierarchyGrantRole;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ grant: GrantView }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      const rows = await tx
+        .select()
+        .from(hierarchyGrants)
+        .where(eq(hierarchyGrants.id, input.grantId))
+        .limit(1);
+      const existing = rows[0];
+      if (!existing) return NOT_FOUND;
+      const target = grantTarget(existing);
+      if (!(await this.requireOwner(tx, ctx.actorId, target.kind, target.id))) {
+        return NOT_FOUND;
+      }
+      // Team subjects are suspended (§1.4); the command surface never
+      // creates them, so this only fires on out-of-band rows.
+      if (!existing.userId) return conflict('team grant subjects are suspended');
+      if (existing.role === input.role) return conflict('grant already holds that role');
+
+      const duplicate = await tx
+        .select({ id: hierarchyGrants.id })
+        .from(hierarchyGrants)
+        .where(
+          and(
+            eq(hierarchyGrants.userId, existing.userId),
+            target.kind === 'company'
+              ? eq(hierarchyGrants.companyId, target.id)
+              : target.kind === 'estate'
+                ? eq(hierarchyGrants.estateId, target.id)
+                : eq(hierarchyGrants.platformProjectId, target.id),
+            eq(hierarchyGrants.role, input.role),
+          ),
+        )
+        .limit(1);
+      if (duplicate.length > 0) {
+        return conflict('subject already holds that role on the target');
+      }
+
+      const updated = await tx
+        .update(hierarchyGrants)
+        .set({ role: input.role })
+        .where(eq(hierarchyGrants.id, input.grantId))
+        .returning();
+      const grant = updated[0] as GrantRow;
+
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'grant_change',
+        targetKind: 'grant',
+        targetId: grant.id,
+        targetSnapshot: {
+          ...grantSnapshot(grant),
+          previousRole: namespacedHierarchyRole(existing.role as HierarchyGrantRole),
+        },
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return { ok: true, grant: grantView(grant) };
+    });
+  }
+
+  /** Revocation is row deletion (§6): the next evaluation denies, nothing lingers. */
+  revokeGrant(input: {
+    actorId: string;
+    grantId: string;
+    idempotencyKey?: string;
+  }): Promise<HierarchyResult<{ revokedId: string }>> {
+    return this.run(input.idempotencyKey, input.actorId, async (tx, ctx) => {
+      const rows = await tx
+        .select()
+        .from(hierarchyGrants)
+        .where(eq(hierarchyGrants.id, input.grantId))
+        .limit(1);
+      const existing = rows[0];
+      if (!existing) return NOT_FOUND;
+      const target = grantTarget(existing);
+      if (!(await this.requireOwner(tx, ctx.actorId, target.kind, target.id))) {
+        return NOT_FOUND;
+      }
+
+      await tx.delete(hierarchyGrants).where(eq(hierarchyGrants.id, input.grantId));
+
+      await appendHierarchyEvent(tx, {
+        actorId: ctx.actorId,
+        verb: 'grant_revoke',
+        targetKind: 'grant',
+        targetId: existing.id,
+        targetSnapshot: grantSnapshot(existing),
+        correlationId: ctx.correlationId,
+        idempotencyKey: ctx.idempotencyKey,
+      });
+      return { ok: true, revokedId: existing.id };
+    });
+  }
+
+  // ── reads ────────────────────────────────────────────────────────────────
+
+  /**
+   * The directory: every directory-class company, closed-field (§2.8). The
+   * sole ratified existence-disclosure carve-out (§6.7 / A2 §9.1.2).
+   */
+  async listDirectory(): Promise<DirectoryEntry[]> {
+    return this.db
+      .select({ id: companies.id, name: companies.name, slug: companies.slug })
+      .from(companies)
+      .where(eq(companies.visibility, 'directory'))
+      .orderBy(asc(companies.name));
+  }
+
+  /** Companies the user holds any grant on (company or descendant, §2.8). */
+  async listGrantedCompanies(userId: string): Promise<CompanyView[]> {
+    const ids = await grantedCompanyIds(this.db, userId);
+    if (ids.length === 0) return [];
+    const rows = await this.db
+      .select()
+      .from(companies)
+      .where(inArray(companies.id, ids))
+      .orderBy(asc(companies.name));
+    return rows.map(companyView);
+  }
+}

apps/gateway/src/hierarchy/hierarchy.service.ts

@@ -0,0 +1,31 @@
+import {
+  ConflictException,
+  ForbiddenException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import type { HierarchyCommandFailure, HierarchyResult } from './hierarchy.repository.js';
+
+/**
+ * Maps repository result unions onto HTTP exceptions. `not_found` carries
+ * one fixed message for every cause — missing node and unauthorized caller
+ * are indistinguishable on the wire (contract 1 §6.7).
+ */
+@Injectable()
+export class HierarchyService {
+  unwrap<T>(result: HierarchyResult<T>): T {
+    if (result.ok) return result;
+    throw this.toException(result);
+  }
+
+  private toException(failure: HierarchyCommandFailure): Error {
+    switch (failure.error) {
+      case 'not_found':
+        return new NotFoundException('hierarchy node not found');
+      case 'forbidden':
+        return new ForbiddenException(failure.message);
+      case 'conflict':
+        return new ConflictException(failure.message);
+    }
+  }
+}

apps/gateway/src/mcp/mcp.service.spec.ts

@@ -176,7 +176,18 @@ describe('MCP actor identity and tool scope enforcement', () => {
     ).toBe(false);
     expect(
       deriveMcpToolScopesForUser({ role: 'platform-admin' }).has(MCP_TOOL_SCOPES.coord_list_tasks),
-    ).toBe(true);
+    ).toBe(false);
+  });
+
+  it('derives no scope elevation from any platform role (contract 2 §1.1 bypass retirement)', () => {
+    const memberScopes = deriveMcpToolScopesForUser({ role: 'member' });
+    for (const role of ['admin', 'platform-admin', 'super-admin', null, undefined]) {
+      const scopes = deriveMcpToolScopesForUser({ role });
+      expect([...scopes].sort()).toEqual([...memberScopes].sort());
+      expect(scopes.has(MCP_TOOL_SCOPES.brain_create_task)).toBe(false);
+      expect(scopes.has(MCP_TOOL_SCOPES.brain_update_task)).toBe(false);
+      expect(scopes.has(MCP_TOOL_SCOPES.coord_list_tasks)).toBe(false);
+    }
   });
 
   it('fails closed when scopes are not supplied by the authenticated context policy', () => {
@@ -311,14 +322,20 @@ describe('MCP actor identity and tool scope enforcement', () => {
     ]);
   });
 
-  it('enforces tenant boundaries for tenant-admin brain project, mission, and task reads', async () => {
-    const { service } = makeService({
+  it('gives admin-role and platform-admin-role actors only owned content on brain reads (§1.1 retirement)', async () => {
+    // Contract 2 §1.1: users.role confers no content visibility. An actor whose
+    // role is 'admin', 'platform-admin', or 'super-admin' but who holds no
+    // ownership sees exactly what an unprivileged member with the same
+    // ownership would see — here, only the one project they own, and nothing
+    // tenant-wide or platform-wide.
+    const fixtures = {
       projects: [
+        { id: 'project-owned', ownerId: 'role-bearing-user', teamId: 'tenant-a', name: 'owned' },
         {
           id: 'project-tenant-a',
           ownerId: 'other-user-a',
           teamId: 'tenant-a',
-          name: 'same tenant',
+          name: 'same tenant, unowned',
         },
         {
           id: 'project-tenant-b',
@@ -328,39 +345,50 @@ describe('MCP actor identity and tool scope enforcement', () => {
         },
       ],
       missions: [
+        { id: 'mission-owned', projectId: 'project-owned' },
         { id: 'mission-tenant-a', tenantId: 'tenant-a', projectId: 'project-tenant-a' },
         { id: 'mission-tenant-b', tenantId: 'tenant-b', projectId: 'project-tenant-b' },
       ],
       tasks: [
+        { id: 'task-owned', projectId: 'project-owned', status: 'not-started' },
         { id: 'task-tenant-a', projectId: 'project-tenant-a', status: 'not-started' },
         { id: 'task-tenant-b', projectId: 'project-tenant-b', status: 'not-started' },
       ],
-    });
-    const { server, tools } = makeCapturingServer();
-    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
+    };
 
-    service.registerTools(server, actor);
+    const actors = [
+      makeAdminActor('role-bearing-user', 'tenant-a'),
+      makePlatformAdminActor('role-bearing-user'),
+    ];
 
-    const projects = JSON.parse(
-      (await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
-    );
-    expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-tenant-a']);
+    for (const actor of actors) {
+      const { service } = makeService(fixtures);
+      const { server, tools } = makeCapturingServer();
+      service.registerTools(server, actor);
 
-    const missions = JSON.parse(
-      (await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
-    );
-    expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-tenant-a']);
+      const projects = JSON.parse(
+        (await getTool(tools, 'brain_list_projects').handler({})).content[0]!.text,
+      );
+      expect(projects.map((project: { id: string }) => project.id)).toEqual(['project-owned']);
 
-    const tasks = JSON.parse(
-      (await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
-    );
-    expect(tasks.map((task: { id: string }) => task.id)).toEqual(['task-tenant-a']);
+      const missions = JSON.parse(
+        (await getTool(tools, 'brain_list_missions').handler({})).content[0]!.text,
+      );
+      expect(missions.map((mission: { id: string }) => mission.id)).toEqual(['mission-owned']);
+
+      const tasks = JSON.parse(
+        (await getTool(tools, 'brain_list_tasks').handler({})).content[0]!.text,
+      );
+      expect(tasks.map((task: { id: string }) => task.id)).toEqual(['task-owned']);
+    }
   });
 
   it('denies tenant-admin task writes outside the authenticated tenant', async () => {
     const { service, brain } = makeService({
       projects: [
-        { id: 'project-tenant-a', ownerId: 'other-user-a', teamId: 'tenant-a' },
+        // §1.1 retirement: content visibility comes from ownership, not the
+        // tenant-admin role — the acting user owns the tenant-a project.
+        { id: 'project-tenant-a', ownerId: 'tenant-admin-user', teamId: 'tenant-a' },
         { id: 'project-tenant-b', ownerId: 'other-user-b', teamId: 'tenant-b' },
       ],
       missions: [
@@ -373,7 +401,29 @@ describe('MCP actor identity and tool scope enforcement', () => {
       ],
     });
     const { server, tools } = makeCapturingServer();
-    const actor = makeAdminActor('tenant-admin-user', 'tenant-a');
+    // Platform role no longer derives task-write scopes (§1.1 retirement):
+    // a role-derived admin actor is scope-denied before any tenant logic.
+    const roleDerivedAdmin = makeAdminActor('tenant-admin-user', 'tenant-a');
+    service.registerTools(server, roleDerivedAdmin);
+    await expect(
+      getTool(tools, 'brain_create_task').handler({ title: 'role-derived write' }),
+    ).rejects.toThrow('MCP tool scope denied');
+    expect(brain.tasks.create).not.toHaveBeenCalled();
+
+    // The tenant-scoping checks below sit behind the scope gate; exercise
+    // them with explicitly granted task-write scopes (how grant-mapped
+    // scopes will arrive), not with a platform role.
+    tools.clear();
+    const actor = createMcpActorContext({
+      userId: 'tenant-admin-user',
+      tenantId: 'tenant-a',
+      role: 'member',
+      scopes: [
+        ...deriveMcpToolScopesForUser({ role: 'member' }),
+        MCP_TOOL_SCOPES.brain_create_task,
+        MCP_TOOL_SCOPES.brain_update_task,
+      ],
+    });
 
     service.registerTools(server, actor);
 
@@ -416,7 +466,7 @@ describe('MCP actor identity and tool scope enforcement', () => {
     );
   });
 
-  it('keeps admin-only coordination tools on server-derived paths', async () => {
+  it('denies coordination tools to every role-derived actor and keeps the granted path server-derived', async () => {
     const { service, coord } = makeService();
     const { server, tools } = makeCapturingServer();
     const member = makeMemberActor('authenticated-user');
@@ -433,10 +483,25 @@ describe('MCP actor identity and tool scope enforcement', () => {
     const tenantAdminTool = getTool(tools, 'coord_list_tasks');
     await expect(tenantAdminTool.handler({})).rejects.toThrow('MCP tool scope denied: coord:read');
 
+    // §1.1 retirement: platform-admin no longer derives coord scopes either.
     tools.clear();
     service.registerTools(server, platformAdmin);
     const platformAdminTool = getTool(tools, 'coord_list_tasks');
-    await platformAdminTool.handler({ projectPath: '/tmp/victim' });
+    await expect(platformAdminTool.handler({})).rejects.toThrow(
+      'MCP tool scope denied: coord:read',
+    );
+
+    // An explicitly granted coord:read scope reaches the server-derived
+    // path (caller-supplied projectPath is stripped by the schema).
+    tools.clear();
+    const grantedActor = createMcpActorContext({
+      userId: 'granted-user',
+      role: 'member',
+      scopes: [MCP_TOOL_SCOPES.coord_list_tasks],
+    });
+    service.registerTools(server, grantedActor);
+    const grantedTool = getTool(tools, 'coord_list_tasks');
+    await grantedTool.handler({ projectPath: '/tmp/victim' });
     expect(coord.listTasks).toHaveBeenCalledWith(process.cwd());
   });
 

apps/gateway/src/mcp/mcp.service.ts

@@ -63,20 +63,6 @@ interface SessionEntry {
   actor: McpActorContext;
 }
 
-const GLOBAL_ADMIN_MCP_SCOPES = new Set<McpToolScope>(Object.values(MCP_TOOL_SCOPES));
-const TENANT_ADMIN_MCP_SCOPES = new Set<McpToolScope>([
-  MCP_TOOL_SCOPES.brain_list_projects,
-  MCP_TOOL_SCOPES.brain_get_project,
-  MCP_TOOL_SCOPES.brain_list_tasks,
-  MCP_TOOL_SCOPES.brain_create_task,
-  MCP_TOOL_SCOPES.brain_update_task,
-  MCP_TOOL_SCOPES.brain_list_missions,
-  MCP_TOOL_SCOPES.brain_list_conversations,
-  MCP_TOOL_SCOPES.memory_search,
-  MCP_TOOL_SCOPES.memory_get_preferences,
-  MCP_TOOL_SCOPES.memory_save_preference,
-  MCP_TOOL_SCOPES.memory_save_insight,
-]);
 const MEMBER_MCP_SCOPES = new Set<McpToolScope>([
   MCP_TOOL_SCOPES.brain_list_projects,
   MCP_TOOL_SCOPES.brain_get_project,
@@ -89,15 +75,17 @@ const MEMBER_MCP_SCOPES = new Set<McpToolScope>([
   MCP_TOOL_SCOPES.memory_save_insight,
 ]);
 
-export function deriveMcpToolScopesForUser(input: {
+/**
+ * Contract 2 §1.1: platform role confers NO MCP scope elevation — the
+ * former tenant-admin/global-admin scope sets keyed on users.role are
+ * retired. Every authenticated user receives the base member set; task
+ * writes and coordination scopes attach to explicit hierarchy grants when
+ * the MCP grant mapping lands, never to a platform role. The role
+ * parameter is kept for caller compatibility and deliberately ignored.
+ */
+export function deriveMcpToolScopesForUser(_input: {
   role?: string | null;
 }): ReadonlySet<McpToolScope> {
-  if (input.role === 'platform-admin' || input.role === 'super-admin') {
-    return new Set(GLOBAL_ADMIN_MCP_SCOPES);
-  }
-  if (input.role === 'admin') {
-    return new Set(TENANT_ADMIN_MCP_SCOPES);
-  }
   return new Set(MEMBER_MCP_SCOPES);
 }
 
@@ -168,41 +156,22 @@ type TaskLike = TenantScopedLike & {
   userId?: string | null;
 };
 
-function isGlobalAdminActor(actor: McpActorContext): boolean {
-  return actor.role === 'platform-admin' || actor.role === 'super-admin';
-}
-
-function isTenantAdminActor(actor: McpActorContext): boolean {
-  return actor.role === 'admin';
-}
-
-function matchesTenant(actor: McpActorContext, record: TenantScopedLike): boolean {
-  return (
-    record.tenantId === actor.tenantId ||
-    record.organizationId === actor.tenantId ||
-    record.teamId === actor.tenantId
-  );
-}
-
+/**
+ * Contract 2 §1.1: `users.role` confers NO content visibility — the former
+ * global-admin/tenant-admin filter short-circuits keyed on the platform role
+ * are retired along with the role-derived scope sets. Content reaches an MCP
+ * actor through ownership only; widened access arrives as explicit hierarchy
+ * grants when the MCP grant mapping lands.
+ */
 function filterProjectsForActor<T extends ProjectLike>(actor: McpActorContext, projects: T[]): T[] {
-  if (isGlobalAdminActor(actor)) return projects;
-  return projects.filter(
-    (project) =>
-      project.ownerId === actor.userId ||
-      (isTenantAdminActor(actor) && matchesTenant(actor, project)),
-  );
+  return projects.filter((project) => project.ownerId === actor.userId);
 }
 
 function filterMissionsByDirectActorScope<T extends MissionLike>(
   actor: McpActorContext,
   missions: T[],
 ): T[] {
-  if (isGlobalAdminActor(actor)) return missions;
-  return missions.filter(
-    (mission) =>
-      mission.userId === actor.userId ||
-      (isTenantAdminActor(actor) && matchesTenant(actor, mission)),
-  );
+  return missions.filter((mission) => mission.userId === actor.userId);
 }
 
 function scopesEqual(left: ReadonlySet<McpToolScope>, right: ReadonlySet<McpToolScope>): boolean {
@@ -293,7 +262,6 @@ export class McpService implements OnModuleDestroy {
   }
 
   private async isProjectAuthorized(actor: McpActorContext, projectId: string): Promise<boolean> {
-    if (isGlobalAdminActor(actor)) return true;
     const project = (await this.brain.projects.findById(projectId)) as ProjectLike | undefined;
     return project ? filterProjectsForActor(actor, [project]).length === 1 : false;
   }
@@ -302,8 +270,6 @@ export class McpService implements OnModuleDestroy {
     actor: McpActorContext,
     missions: T[],
   ): Promise<T[]> {
-    if (isGlobalAdminActor(actor)) return missions;
-
     const projects = (await this.brain.projects.findAll()) as ProjectLike[];
     const projectIds = new Set(
       filterProjectsForActor(actor, projects).map((project) => project.id),
@@ -317,7 +283,6 @@ export class McpService implements OnModuleDestroy {
   }
 
   private async isMissionAuthorized(actor: McpActorContext, missionId: string): Promise<boolean> {
-    if (isGlobalAdminActor(actor)) return true;
     const mission = (await this.brain.missions.findById(missionId)) as MissionLike | undefined;
     if (!mission) return false;
     return (await this.filterMissionsForActor(actor, [mission])).length === 1;
@@ -339,7 +304,7 @@ export class McpService implements OnModuleDestroy {
     actor: McpActorContext,
     refs: { projectId?: string | null; missionId?: string | null },
   ): Promise<void> {
-    if (!isGlobalAdminActor(actor) && !refs.projectId && !refs.missionId) {
+    if (!refs.projectId && !refs.missionId) {
       throw new Error('MCP task scope denied');
     }
     await this.assertTaskReferencesAuthorized(actor, refs);
@@ -349,8 +314,6 @@ export class McpService implements OnModuleDestroy {
     actor: McpActorContext,
     tasks: T[],
   ): Promise<T[]> {
-    if (isGlobalAdminActor(actor)) return tasks;
-
     const [projects, missions] = await Promise.all([
       this.brain.projects.findAll(),
       this.brain.missions.findAll(),
@@ -367,7 +330,6 @@ export class McpService implements OnModuleDestroy {
     return tasks.filter(
       (task) =>
         task.userId === actor.userId ||
-        (isTenantAdminActor(actor) && matchesTenant(actor, task)) ||
         (typeof task.projectId === 'string' && projectIds.has(task.projectId)) ||
         (typeof task.missionId === 'string' && missionIds.has(task.missionId)),
     );

apps/gateway/src/missions/missions.controller.ts

@@ -108,11 +108,13 @@ export class MissionsController {
   ) {
     const mission = await this.brain.missions.findByIdAndUser(missionId, user.id);
     if (!mission) throw new NotFoundException('Mission not found');
+    // dto.status is deliberately not forwarded: mission_tasks.status is
+    // write-prohibited through the N-1 window (SHARED-CONTRACT §5.1 phase 1);
+    // the repo strips it as well.
     return this.brain.missionTasks.create({
       missionId,
       taskId: dto.taskId,
       userId: user.id,
-      status: dto.status,
       description: dto.description,
       notes: dto.notes,
       pr: dto.pr,

apps/gateway/src/missions/missions.dto.ts

@@ -77,6 +77,12 @@ export class CreateMissionTaskDto {
   @IsUUID()
   taskId?: string;
 
+  /**
+   * @deprecated Accepted for N-1 wire compatibility but ignored: mission_tasks.status
+   * is write-prohibited through the migration window (SHARED-CONTRACT §5.1 phase 1).
+   * The field stays declared because the global ValidationPipe runs with
+   * forbidNonWhitelisted, and removing it would 400 frozen legacy consumers.
+   */
   @IsOptional()
   @IsIn(taskStatuses)
   status?: 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
@@ -102,6 +108,12 @@ export class UpdateMissionTaskDto {
   @IsUUID()
   taskId?: string;
 
+  /**
+   * @deprecated Accepted for N-1 wire compatibility but ignored: mission_tasks.status
+   * is write-prohibited through the migration window (SHARED-CONTRACT §5.1 phase 1).
+   * The field stays declared because the global ValidationPipe runs with
+   * forbidNonWhitelisted, and removing it would 400 frozen legacy consumers.
+   */
   @IsOptional()
   @IsIn(taskStatuses)
   status?: 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';

apps/gateway/src/validation-pipe-check.ts

@@ -1,6 +1,23 @@
 import 'reflect-metadata';
 import { getMetadataStorage } from 'class-validator';
 import { BootstrapSetupDto } from './admin/bootstrap.dto.js';
+import {
+  ChangeCompanyVisibilityDto,
+  ChangeGrantDto,
+  CreateCompanyDto,
+  CreateEstateDto,
+  CreateGrantDto,
+  CreatePlatformProjectDto,
+  DeleteNodeDto,
+  RenameNodeDto,
+  TransferEstateDto,
+  TransferPlatformProjectDto,
+} from './hierarchy/hierarchy.dto.js';
+import {
+  EnrollAgentDto,
+  EnrollCredentialDto,
+  GetEnrollmentQueryDto,
+} from './enrollment/enrollment.dto.js';
 
 /**
  * Boot-time self-check: the global ValidationPipe must be able to SEE the
@@ -43,6 +60,81 @@ export const PIPE_GUARDED_DTOS: Array<{
     target: BootstrapSetupDto,
     properties: ['name', 'email', 'password'],
   },
+  {
+    name: 'CreateCompanyDto',
+    target: CreateCompanyDto,
+    properties: ['name', 'slug', 'idempotencyKey'],
+  },
+  {
+    name: 'RenameNodeDto',
+    target: RenameNodeDto,
+    properties: ['name', 'idempotencyKey'],
+  },
+  {
+    name: 'ChangeCompanyVisibilityDto',
+    target: ChangeCompanyVisibilityDto,
+    properties: ['visibility', 'idempotencyKey'],
+  },
+  {
+    name: 'DeleteNodeDto',
+    target: DeleteNodeDto,
+    properties: ['idempotencyKey'],
+  },
+  {
+    name: 'CreateEstateDto',
+    target: CreateEstateDto,
+    properties: ['companyId', 'name', 'slug', 'idempotencyKey'],
+  },
+  {
+    name: 'CreatePlatformProjectDto',
+    target: CreatePlatformProjectDto,
+    properties: ['estateId', 'name', 'slug', 'idempotencyKey'],
+  },
+  {
+    name: 'TransferEstateDto',
+    target: TransferEstateDto,
+    properties: ['destinationCompanyId', 'idempotencyKey'],
+  },
+  {
+    name: 'TransferPlatformProjectDto',
+    target: TransferPlatformProjectDto,
+    properties: ['destinationEstateId', 'idempotencyKey'],
+  },
+  {
+    name: 'CreateGrantDto',
+    target: CreateGrantDto,
+    properties: ['userId', 'targetKind', 'targetId', 'role', 'idempotencyKey'],
+  },
+  {
+    name: 'ChangeGrantDto',
+    target: ChangeGrantDto,
+    properties: ['role', 'idempotencyKey'],
+  },
+  {
+    name: 'EnrollAgentDto',
+    target: EnrollAgentDto,
+    properties: [
+      'harness',
+      'name',
+      'persona',
+      'model',
+      'provider',
+      'credential',
+      'idempotencyKey',
+      'correlationId',
+      'replayMode',
+    ],
+  },
+  {
+    name: 'EnrollCredentialDto',
+    target: EnrollCredentialDto,
+    properties: ['mode', 'type', 'value'],
+  },
+  {
+    name: 'GetEnrollmentQueryDto',
+    target: GetEnrollmentQueryDto,
+    properties: ['correlationId'],
+  },
 ];
 
 export class PipeMetatypeCheckError extends Error {

docker-compose.dogfood.yml

@@ -0,0 +1,22 @@
+# Explicit, single-seat dogfood mode for stack-containerization B2.
+# Use with docker-compose.yml. The base stack remains credential-free.
+services:
+  gateway:
+    environment:
+      # Identity and credential layout match a fleet seat. This fixed name prevents
+      # an operator from mounting one seat while attributing actions to another.
+      MOSAIC_AGENT_NAME: stack-dogfood
+      MOSAIC_GIT_IDENTITY: stack-dogfood
+      MOSAIC_BRAIN_HOME: /opt/mosaic/brain
+      AGENT_FILE_SANDBOX_DIR: /workspace/stack
+      AGENT_USER_TOOLS: fs_read_file,fs_write_file,fs_list_directory,fs_edit_file,git_status,git_log,git_diff,shell_exec
+    volumes:
+      # Mount a dedicated worktree, never the canonical clone or divergent local main.
+      - type: bind
+        source: ${MOSAIC_DOGFOOD_WORKTREE:?set to a dedicated next-based stack worktree}
+        target: /workspace/stack
+      # Only this seat home enters the container. Other fleet credentials stay outside.
+      - type: bind
+        source: ${MOSAIC_DOGFOOD_SEAT_HOME:?set to the external stack-dogfood seat directory}
+        target: /opt/mosaic/brain/fleet/agents/stack-dogfood
+        read_only: true

docker-compose.yml

@@ -47,6 +47,44 @@ services:
     environment:
       COLLECTOR_OTLP_ENABLED: 'true'
 
+
+  gateway:
+    # Standalone-tier application service (compose `stack` profile).
+    # Default image = local build of docker/gateway.Dockerfile (works with
+    # no registry auth); override GATEWAY_IMAGE to a CI-published sha tag
+    # for registry deploys (git.mosaicstack.dev/mosaicstack/stack/gateway:sha-XXXXXXX).
+    profiles: [stack]
+    image: ${GATEWAY_IMAGE:-mosaic-gateway:dev}
+    build:
+      context: .
+      dockerfile: docker/gateway.Dockerfile
+    ports:
+      - '${GATEWAY_HOST_PORT:-14242}:14242'
+    environment:
+      GATEWAY_PORT: '14242'
+      DATABASE_URL: postgresql://mosaic:mosaic@postgres:5432/mosaic
+      VALKEY_URL: valkey://valkey:6379
+      # The compose IS the standalone tier by declaration (mode contract:
+      # mode chosen at install); pinning skips cross-container probe races.
+      MOSAIC_STORAGE_TIER: standalone
+      # Standalone-tier secrets: generated at install (see .env.example).
+      # Enterprise tier replaces these with Vault/Openbao plumbing.
+      BETTER_AUTH_SECRET: '${BETTER_AUTH_SECRET:?set in .env — openssl rand -hex 32}'
+    volumes:
+      - gateway_workspaces:/opt/mosaic/.workspaces
+    depends_on:
+      postgres:
+        condition: service_healthy
+      valkey:
+        condition: service_healthy
+    healthcheck:
+      test: ['CMD-SHELL', 'wget -qO- http://127.0.0.1:14242/health || exit 1']
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+
 volumes:
+  gateway_workspaces:
   pg_data:
   valkey_data:

docker/gateway.Dockerfile

@@ -29,11 +29,23 @@ ENV NODE_ENV=production
 # $MOSAIC_ROOT/.workspaces (apps/gateway/src/workspace/workspace.service.ts);
 # mount a volume over /opt/mosaic to persist workspaces across container restarts.
 # Intentionally unpinned: Alpine's signed repository is the trust anchor; pinning
-# git was declined so routine base-image security updates remain maintainable.
-RUN apk add --no-cache git \
+# packages was declined so routine base-image security updates remain maintainable.
+# bash/curl/python3 are runtime dependencies of the provider-neutral Mosaic git
+# wrappers. jq supports wrapper discovery for non-canonical Gitea hosts.
+RUN apk add --no-cache bash curl git jq python3 \
   && mkdir -p /opt/mosaic/.workspaces \
   && chown -R node:node /opt/mosaic /app
 ENV MOSAIC_ROOT=/opt/mosaic
+# Dogfood agents use the same fail-closed credential helper and PR-create wrapper
+# as fleet seats. Copy only that operation and its shared dependencies. Unrelated
+# fleet operations, including merge and infrastructure tools, stay out of the image.
+COPY --from=builder /app/packages/mosaic/framework/tools/git/pr-create.sh /opt/mosaic/tools/git/pr-create.sh
+COPY --from=builder /app/packages/mosaic/framework/tools/git/detect-platform.sh /opt/mosaic/tools/git/detect-platform.sh
+COPY --from=builder /app/packages/mosaic/framework/tools/git/repo-decl.sh /opt/mosaic/tools/git/repo-decl.sh
+COPY --from=builder /app/packages/mosaic/framework/tools/git/git-credential-mosaic /opt/mosaic/tools/git/git-credential-mosaic
+COPY --from=builder /app/packages/mosaic/framework/tools/_lib/credentials.sh /opt/mosaic/tools/_lib/credentials.sh
+COPY --from=builder /app/packages/mosaic/framework/tools/structure/validate-repo-json.sh /opt/mosaic/tools/structure/validate-repo-json.sh
+RUN git config --system credential.helper /opt/mosaic/tools/git/git-credential-mosaic
 # Use the pnpm deploy output — resolves all deps into a flat, self-contained node_modules
 COPY --chown=node:node --from=builder /deploy/node_modules ./node_modules
 COPY --chown=node:node --from=builder /deploy/package.json ./package.json

docs/PRD.md

@@ -197,24 +197,41 @@ conflict must amend one of them explicitly, never fork a third document
 - A second writable task store beside PostgreSQL (native-kanban-sot invariants).
 - Fully-designed federation in v1 (D3 — roadmap placeholder only).
 
-### 12. Decision registry
+### D15 — Tiered containerized deployment (2026-08-30, containerization lane)
 
-| ID  | Decision (short form)                                                                                              |
-| --- | ------------------------------------------------------------------------------------------------------------------ |
-| D1  | Open-source, AI-first, self-hosted platform for agentic management + life OS                                       |
-| D2  | Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC                                        |
-| D3  | Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred  |
-| D4  | Re-runnable, extensible, per-mode onboarding wizards                                                               |
-| D5  | North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT                                               |
-| D6  | Only product-relevant material migrates from brains; operational records stay and link                             |
-| D7  | Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 2026-08-25)     |
-| D8  | webUI sits over official framework tooling; CLI primary                                                            |
-| D9  | Not a hosted business; company = organizational separation for one operator                                        |
-| D10 | better-auth is the account system of record; external IdPs via OIDC                                                |
-| D11 | Small v1 slice; ALL phases on the documented roadmap from day one                                                  |
-| D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first                                       |
-| D13 | workspace_id stays the hard isolation unit; hierarchy is parent structure above; kanban SOT amended, not rewritten |
-| D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers                     |
+The stack ships a tiered deployment target, additive to the architecture
+gate (D8): (1) Standalone tier — docker compose is the canonical
+single-host deployment: postgres, valkey, openbao, gateway, appservice
+and the served webUI in one composition, with migrations, health checks,
+and a documented install/upgrade path; the registry (CI-published
+images) is the only deployment source. (2) Enterprise tier — Kubernetes
+manifests for the same service set, phase-gated on the standalone tier
+holding its acceptance bar. The v1 acceptance bar for the standalone
+tier: compose-up healthy; webUI hosts agent chat; an in-stack agent can
+open a PR to this repo; CI validates it; the running deployment adopts
+the merged change (pull + restart). Federation (D3 clause) remains
+deferred and unforeclosed. Implementation plan:
+docs/plans/2026-08-30_containerization.md.
+
+## 12. Decision registry
+
+| ID  | Decision (short form)                                                                                                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| D1  | Open-source, AI-first, self-hosted platform for agentic management + life OS                                                               |
+| D2  | Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC                                                                |
+| D3  | Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred                          |
+| D4  | Re-runnable, extensible, per-mode onboarding wizards                                                                                       |
+| D5  | North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT                                                                       |
+| D6  | Only product-relevant material migrates from brains; operational records stay and link                                                     |
+| D7  | Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 2026-08-25)                             |
+| D8  | webUI sits over official framework tooling; CLI primary                                                                                    |
+| D9  | Not a hosted business; company = organizational separation for one operator                                                                |
+| D10 | better-auth is the account system of record; external IdPs via OIDC                                                                        |
+| D11 | Small v1 slice; ALL phases on the documented roadmap from day one                                                                          |
+| D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first                                                               |
+| D13 | workspace_id stays the hard isolation unit; hierarchy is parent structure above; kanban SOT amended, not rewritten                         |
+| D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers                                             |
+| D15 | Tiered containerized deployment: compose standalone tier (five-point v1 bar) + phase-gated k8s enterprise tier; registry-only image source | 2026-08-30 containerization lane; plan docs/plans/2026-08-30_containerization.md |
 
 The full decision texts are recorded in the operator decision log (USC estate
 brain, webui-audit lane, `GRILL.md`).

docs/native-kanban-sot/INDEX.md

@@ -14,6 +14,7 @@
 | [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md)                                                       | rc.16 direct-Drizzle current storage-wrapper hold: legacy N-1/uncertified/non-operative pending -02/-03/-06/-08; exact README commented/user-guide executable forms fail before masking and source-consistency rejects runner-delegation copy; held future bootstrap → TLS/roles → run → verify → readiness; plus prior production boundary, pgvector owner, attestation, inventory, manifests, DDL classifier, TLS/bootstrap, activation, and certification contract; foundation prerequisite of KBN-100 and real-role gate before KBN-105 |
 | [`KBN-101-ENVELOPE-A.md`](./KBN-101-ENVELOPE-A.md)                                                             | KBN-101 Envelope A (v6) — RATIFIED, part of the frozen SSOT: rc.20 declarative sink-RBAC + per-role connection-selection + RLS `WITH CHECK`/`USING` write-source + `FORCE ROW LEVEL SECURITY` + sink-resident `task_status_write_override`; adds owner card KBN-101-10 + responsibility-widenings; authority Jason B1 + Mos OPTION A/Q1/Q2                                                                                                                                                                                                  |
 | [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)                                                                   | Remediated v1 integration contract: proof authority, exact failures/routes/DTOs/MCP ownership, concrete current-main field migration map, relational invariants, Coordinator split, recovery delivery                                                                                                                                                                                                                                                                                                                                       |
+| [`P0-MAP-CURRENCY-2026-08-29.md`](./P0-MAP-CURRENCY-2026-08-29.md)                                             | REQ-MIG-001 lane-opening verification: SHARED-CONTRACT §5 field map re-verified byte-identical at `next` @ `abb0c936`; workspaces/audit-pattern refinements; measured `mission_tasks.status` writer inventory and the pre-expand stop-write work item                                                                                                                                                                                                                                                                                       |
 | [`contracts/kanban-schema.v1.ts`](./contracts/kanban-schema.v1.ts)                                             | Drizzle target declarations including exact owner/principal membership, project congruence, tags/archive, proposals, persisted assignments, monotonic fences, durable retry, immutable evidence/audit                                                                                                                                                                                                                                                                                                                                       |
 | [`contracts/mechanical-coordinator.v1.ts`](./contracts/mechanical-coordinator.v1.ts)                           | Pure snapshot decision engine separated from persistence/service adapter; ID-bound approvals, bigint-safe fences, durable retry/quarantine, artifact-backed checkpoints, exact failures                                                                                                                                                                                                                                                                                                                                                     |
 | [`contracts/health-state.v1.ts`](./contracts/health-state.v1.ts)                                               | Discriminated public health, separate branded transaction-local write proof, and non-overlapping denial/transport/version-conflict mappings                                                                                                                                                                                                                                                                                                                                                                                                 |

docs/native-kanban-sot/P0-MAP-CURRENCY-2026-08-29.md

@@ -0,0 +1,117 @@
+---
+kind: verification
+status: active
+---
+
+# P0 Field-Map Currency Verification — 2026-08-29
+
+**Purpose:** REQ-MIG-001 (native-kanban-sot.md §5) accepts only when "P0 publishes
+the current `origin/main` field-by-field expand/backfill/compatibility/switch/contract
+map before any schema lane starts." That map exists: [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)
+§5, inspected at `packages/db/src/schema.ts` @ `e72388b2cbfe400842fe940fa6cabf984ed43711`
+(2026-07-13). The M4-3 schema lane (expand migration 0021+) now opens against the
+integration trunk `next`. This document re-verifies the map's currency at the
+lane-opening head and records the measured pre-expand writer inventory. It amends
+nothing normative in SHARED-CONTRACT.md; where the two disagree, SHARED-CONTRACT.md
+wins.
+
+## 1. Currency verification (measured)
+
+- Map pin: `e72388b2cbfe400842fe940fa6cabf984ed43711` (2026-07-13, `main`).
+- Lane-opening head: `abb0c936011c7f6b8c0bcc90a20a865d5e8a40e9` (`origin/next`,
+  2026-08-29).
+- Measurement: `git diff e72388b2 abb0c936 -- packages/db/src/schema.ts` reports
+  **300 insertions, 0 deletions** — no existing declaration changed.
+- The additions: the new declarations `logicalAgentConnectorLeases`,
+  `connectorLeaseAuditLog`, and the hierarchy layer (`companies`, `estates`,
+  `platformProjects`, `workspaces`, `hierarchyGrants`, `hierarchyAuditEvents`,
+  `hierarchyOutbox`, plus their enums and constant arrays); a nullable `issuer`
+  column on the unmapped BetterAuth `accounts` table (shipped as
+  `drizzle/0017_accounts_issuer.sql`); and expanded `drizzle-orm` imports
+  (`sql`, `AnyPgColumn`, `unique`, `check`, `bigint`). None touch a mapped
+  source.
+- Stronger literal fact: REQ-MIG-001's acceptance names `origin/main`. Measured
+  pin → `origin/main` (`7102ccb9`, 2026-08-13): **63 insertions, 0 deletions**
+  for `schema.ts`, and `origin/main` is an ancestor of `abb0c936`. The map is
+  therefore current at `origin/main` itself, and at the trunk head beyond it.
+
+**Consequence:** every source column mapped in SHARED-CONTRACT.md §5.4 —
+`teams`/`team_members`, `projects`, `missions`, `tasks`, `mission_tasks`,
+`agents`, fleet `backlog` — is byte-identical to the declaration the map
+inspected. The field map is current as written. No row changes.
+
+## 2. Refinements available since the pin (context, not map changes)
+
+1. **The `workspaces` table exists.** The map predates contract 1's hierarchy
+   layer; its "bootstrap workspace" backfill step now has a shipped target:
+   `workspaces` (uuid PK, chained under platform projects per
+   `docs/requirements/hierarchy-schema.md`; hierarchy core in
+   `drizzle/0018_clean_cobalt_man.sql`, audit/outbox in
+   `0019_volatile_killraven.sql`, visibility in
+   `0020_special_betty_brant.sql`). New `workspace_id` columns FK there.
+2. **The audit/outbox envelope pattern is shipped.** `hierarchyAuditEvents` +
+   `hierarchyOutbox` implement same-transaction semantic event + outbox. The
+   task lane's `task_events`/`task_outbox` mirror the pattern but are
+   workspace-scoped with the composite `(workspace_id, id)` key required by
+   §5.3 and REQ-SOT-004. The hierarchy tables are a pattern reference, never a
+   shared store for task events.
+3. **Trunk designation.** The integration trunk is `next` (`.mosaic/repo.json`).
+   §1 measures currency at both the literal `origin/main` REQ-MIG-001 names and
+   the trunk head pinned above, so no reinterpretation of the acceptance text
+   is needed.
+4. **Migration ownership.** SHARED-CONTRACT.md §6 assigns schema/migration
+   ownership to the mission seat `coder2`. Seat identity is operational fleet
+   state, not resolvable from this repository, and is outside this document's
+   scope. The invariant §6 protects binds regardless of seat and is restated
+   here as binding on the M4-3 schema lane: exactly one lane generates
+   migrations at a time; expand is additive; no drop/rename/narrow; constraints
+   validate before NOT NULL.
+
+## 3. Pre-expand writer inventory (measured 2026-08-29 at `abb0c936`)
+
+SHARED-CONTRACT.md §5.1 phase 1 requires an N-1 patch that stops
+`mission_tasks.status` as a write source, plus a writer inventory, before any
+expand DDL.
+
+- **Sole authoring write path:** `packages/brain/src/mission-tasks.ts`
+  `create`/`update` (Drizzle insert/update on `mission_tasks`), invoked by
+  `apps/gateway/src/missions/missions.controller.ts`. `update` accepts
+  `Partial<NewMissionTask>`, so `status` is writable through both DTOs today.
+  The same module also exposes `remove`/`removeByMission` DELETE paths —
+  immaterial to `status` writes, listed for inventory completeness.
+- **Storage-layer surfaces that touch the column without authoring it**
+  (added 2026-08-29 after independent review of the phase-1 patch):
+  `packages/storage/src/migrate-tier.ts` copies whole `mission_tasks` rows
+  between storage tiers and must preserve the stored `status` verbatim — row
+  transport, exempt from the write prohibition (stripping there would corrupt
+  data inside the N-1 window). The generic table-keyed storage adapters
+  (`adapters/postgres.ts`, `adapters/pglite.ts`) register `mission_tasks` in
+  their table maps but have no caller that targets it: measured at this head,
+  every runtime adapter caller passes a fixed collection constant
+  (preferences/insights). Neither surface authors a new `status` value.
+- **Read-only consumers of `mission_tasks`:** federation verb services
+  (`get-query.service.ts`, `list-query.service.ts`) select only. The MCP
+  `brain_*` tools do not touch `mission_tasks` at all; `brain_create_task` /
+  `brain_update_task` write the separately mapped `tasks` table, a legitimate
+  N-1 writer through the compatibility window.
+- The ratified contract 5 decision
+  (`docs/requirements/tool-gateway-mapping.md` §3.2, ruled 2026-08-27) freezes
+  the legacy endpoints — including MCP `brain_*` task mutations — for new
+  consumers, while existing consumers keep working until each surface's owning
+  contract retires it. It does not stop existing writes.
+
+**Standing work item:** the phase-1 stop-write patch (reject or ignore `status`
+on `mission_tasks` create/update) MUST land before the expand DDL of migration
+lane M4-3a. It is N-1-safe per the §5.4 row for `mission_tasks.status` (linked
+status is ignored; the column stays declared and readable through the whole
+N-1 window; retirement only after no readers).
+
+## 4. Lane opening
+
+With this verification merged, REQ-MIG-001's P0-map precondition is satisfied
+for the M4-3 schema lane at pinned head `abb0c936`. The ordered phases (§5.1),
+mission candidate-key DDL order (§5.2), audit/proposal DDL order (§5.3), field
+map (§5.4), and required migration tests (§5.5) bind as written. External
+import machinery (jarvis-brain/Vikunja shadow import, REQ-MIG-001) and client
+cutover (REQ-MIG-002) remain out of scope for M4-3; the legacy surface stays
+frozen for new consumers meanwhile (`tool-gateway-mapping.md` §3.2 decision).

docs/plans/2026-08-29-agent-enrollment-command-design.md

@@ -0,0 +1,315 @@
+---
+kind: spec
+status: active
+audience: developer
+---
+
+# Agent Enrollment Command Family — v1 Design (M4-4-0)
+
+Status: design note (implementation-facing; amends no contract).
+Authority chain: tool-gateway-mapping.md §3.1 rank-4 row + §4 envelope
+(ruled 2026-08-27), onboarding-wizard.md §3.5 (D11 minimal enrollment),
+custody-schema.md §5.2 at revision 13 (agent-grantee FK bound to the
+live `agents` table — a binding introduced at rev 4 and standing
+verbatim), PRD §9 D11. Where this note and a ratified contract disagree,
+the contract wins.
+
+## 1. What the contracts bind (and what they leave open)
+
+There is no standalone enrollment contract. The rank-4 family is defined
+by composition:
+
+1. **Contract 5 §3.1 rank 4:** "Enroll one agent: harness, credential
+   reference/API-key intake (values never echoed), name/persona,
+   assignment scope (contract 3 §3.5)."
+2. **Contract 5 §4 — all five sub-clauses:** §4.1 typed request/result
+   DTOs validated at the Gateway boundary (expected-version only where
+   an owning contract defines one); §4.2 closed per-family error enum
+   (validation, authentication, authorization, not-found, conflict,
+   precondition, internal) with HTTP mappings; §4.3 audit linkage — the
+   envelope contributes correlation: every request accepts/generates a
+   correlation id, carried into the audit events **and returned in the
+   result**, with no second audit stream; §4.4 fail-closed — an
+   operation that cannot evaluate its authorization or reach its owning
+   tool refuses, never degrading to a fallback read or direct data
+   access; §4.5 CLI parity — the family MUST be invocable through the
+   official CLI against the same Gateway commands with the same
+   request/result/error contracts (a Gateway command without CLI
+   exposure is a tracked conformance gap).
+   **Idempotency keys are NOT contract 5 §4.3:** the idempotency-key
+   envelope is contract 3 §4.3, ratified as a drafting addition to
+   contract 5 §4's command envelope via contract 3 §7 item 4. Its fence
+   and replay rules bind as written there; §3.1 rule 5 below designs to
+   them.
+3. **Contract 3 §3.5:** the wizard's enrollment step is minimal (one
+   harness, API-key login, agent name and persona — D11), uses ONLY this
+   family, and is skippable. Wizard witness §6.10: a run that skips the
+   step produces zero enrollment-family mutations.
+4. **Custody-schema §5.2 (rev 13; binding introduced at rev 4):**
+   contract 7's agent-grantee FK references the live `agents` table
+   (`agents.id`, uuid); an enrollment surface with its own table would
+   force a contract-7 amendment.
+
+**Assignment scope (open point, pinned here):** the rank-4 row cites
+contract 3 §3.5, which defines no assignment semantics; the PRD's full
+enrollment vision (Part I, Standalone flow) includes "account
+assignment", but the D11 v1 slice is exactly "one harness, API key,
+name/persona". v1 therefore scopes assignment to the two bindings the
+minimal slice already implies — the enrolling user becomes the agent's
+owner (`agents.owner_id`), and the credential reference names which of
+that user's stored provider credentials the agent uses. Richer
+assignment (multi-account, comms auto-enroll, workspace placement) is
+deferred with the rest of the PRD's full flow (D11); when a contract
+defines it, this family extends by ordinary amendment of the design.
+The deferral rests on contract 3 §3.5's explicit delegation of
+enrollment specifics to this family — not on reading the D11 list as
+exhaustive (it is not: the §3.1 `model`/`provider` fields are required
+by the live table's NOT NULL columns, though D11 does not name them).
+
+## 2. Current state (measured 2026-08-29 at `origin/next` = `94d626df`)
+
+- `agents` table (packages/db `schema.ts`): id uuid PK, name, provider,
+  model, status enum, project_id (legacy `projects`, ON DELETE SET
+  NULL), owner_id → users, system_prompt, allowed_tools, skills,
+  is_system, config jsonb, timestamps. No harness column (provider and
+  model describe the LLM backend, not the harness), no audit coupling.
+- Sole write path: `packages/brain/src/agents.ts` repository (the only
+  module issuing `insert(agents)`), with three write consumers: the
+  legacy `/api/agents` CRUD controller
+  (`apps/gateway/src/agent/agent-configs.controller.ts`), the `/agent
+new` chat command (`apps/gateway/src/commands/command-executor.service.ts`
+  → `brain.agents.create`), and workspace bootstrap
+  (`apps/gateway/src/workspace/project-bootstrap.service.ts`). All
+  three keep serving existing consumers; none is touched by M4-4.
+- Sealed credential store exists: `ProviderCredentialsService`
+  (apps/gateway/src/agent/) — one row per (userId, provider), values
+  sealed at rest, decrypt server-side only, summaries never carry
+  values.
+- Harness registry exists (`apps/gateway/src/harness/`), the validation
+  source for the harness field.
+- Implementation pattern: the merged hierarchy module (M4-1) —
+  transaction-scoped command context, in-tx authorization, discriminated
+  result unions, same-transaction semantic audit event + transactional
+  outbox, no-oracle not_found folding.
+
+**F1 — contract-5 mapping note (disposition, not an amendment):**
+`/api/agents` appears nowhere in contract 5 — neither as a P0 row nor in
+the §3.2 legacy non-substitutes list (the ruled §3.2 freeze names
+specific endpoints, and `/api/agents` is not among them). The operative
+constraints are §3.3's amendment-only rule for new mapping rows and §5's
+closure rule: this design adds no new consumer to `/api/agents` and
+builds the rank-4 family as the P1 path for enrollment. Adding the
+missing P0 row is a contract amendment for a future S2 pass; nothing in
+M4-4 depends on it.
+
+## 3. Command family surface (v1)
+
+One command, one query. Module: `apps/gateway/src/enrollment/`
+(`enrollment.module.ts`), mirroring the hierarchy module's shape.
+
+### 3.1 `agent.enroll` (mutation)
+
+Request DTO (shared types package, class-validator at the boundary):
+
+| Field            | Type                | Rule                                                                                                                                                                                                                                                                                                      |
+| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `harness`        | string              | syntactically invalid (empty/malformed) → `validation_failed`; well-formed but not in the harness registry → `precondition_failed`                                                                                                                                                                        |
+| `correlationId`  | string (uuid)       | optional; generated when absent (contract 5 §4.3); carried into audit events and returned in the result                                                                                                                                                                                                   |
+| `replayMode`     | 'actor-bound'       | optional, default `actor-bound`. `shared` is seed-only (contract 3 §4.3 binds it to the §3.4 canonical seed key set and "no other operation can carry a shared declaration"; §7 item 4 closes it); a `shared` declaration here is refused `validation_failed`, executes nothing, and records no fence row |
+| `name`           | string              | non-empty, trimmed, ≤ 200 chars                                                                                                                                                                                                                                                                           |
+| `persona`        | string \| null      | optional; stored as the agent's system prompt                                                                                                                                                                                                                                                             |
+| `model`          | string              | non-empty (provider-qualified model id)                                                                                                                                                                                                                                                                   |
+| `provider`       | string              | non-empty; names the credential's provider                                                                                                                                                                                                                                                                |
+| `credential`     | discriminated union | `{ mode: 'reference' }` — a credential for (actor, provider) MUST already exist; `{ mode: 'intake', type: 'api_key', value: string }` — value is sealed into the credential store in the same flow                                                                                                        |
+| `idempotencyKey` | string (uuid)       | required (contract 3 §4.3, ratified into contract 5 §4 via contract 3 §7 item 4)                                                                                                                                                                                                                          |
+
+Rules:
+
+1. **Never echoed.** The credential value appears in no result DTO, no
+   audit event, no outbox payload, and no log line. The result carries
+   only `{ provider, credentialMode }`.
+2. **Intake = the existing sealed store, inside the transaction.**
+   `intake` writes through the sealed-store path
+   (`ProviderCredentialsService.store` semantics: seal-at-rest, upsert
+   per (userId, provider)) **in the same transaction** as the agent
+   insert — a failure after the credential write rolls everything back,
+   leaving no orphan credential. Enrollment persists no second copy and
+   no plaintext.
+3. **Reference must resolve.** `reference` with no stored credential for
+   (actor, provider) refuses with `precondition_failed` (nothing is
+   created).
+4. **Ownership.** `owner_id` = the authenticated actor. v1 authorization
+   is AuthGuard-authenticated user; no hierarchy grant is required
+   because v1 enrollment binds no hierarchy node (§1 assignment-scope
+   pin). `is_system` is never settable through this command.
+5. **Idempotency fence (contract 3 §4.3, in full).** The command layer
+   records, in a uniqueness-constrained fence table in the same
+   transaction as the mutation and its audit event: the key, the
+   operation identifier (`agent.enroll`), the acting principal, the
+   authorization scope, a digest of the canonicalized request payload
+   (the digest input EXCLUDES the credential value — it covers
+   provider + credentialMode, never plaintext), the declared replay
+   mode (always `actor-bound` for this family — the `shared` refusal
+   in the table above means no shared fence row can exist here; the
+   column is kept for envelope-shape fidelity and mode-mismatch
+   collision checks), and a reference to the committed outcome (the
+   agent id). The recorded **authorization scope** for this family is
+   pinned to the acting principal's platform-user scope (v1
+   authorization is grant-free per rule 4, so the scope is the
+   authenticated-user identity domain — recorded so the §4.3
+   scope-equality check has a defined value). Fence uniqueness is the
+   pair (operation identifier, key). **Replay:** a submission whose
+   (operation, key) is recorded is first authorized exactly as a fresh
+   submission; then replay-mode, scope, and digest equality are
+   checked (a mismatch on any — including scope — is a collision);
+   then **target-result authorization** — the submitter must hold, at
+   replay time, read authority on the referenced agent row under
+   §3.2's rule (owner or admin) — plus recorded-actor equality
+   (`actor-bound`). A passing replay executes nothing, returns the
+   recorded outcome, and appends a replay access event (non-mutation
+   audit class: accessing principal, current correlation id,
+   fence-row reference). Any equality or authorization failure refuses
+   with the single bounded `conflict` shape — constant, identifying no
+   record — preserving the no-existence-oracle rule. **Concurrency
+   (contract 3 §4.3's rule, ratified via §7 item 4):** two submissions
+   with the same (operation, key) serialize on the fence's unique
+   constraint — exactly one executes; the loser waits for the winner's
+   transaction, and is then handled as a replay if it committed
+   (through the full replay path above) or executes afresh if it
+   aborted. A unique-violation race never surfaces as an unhandled
+   internal fault.
+6. **Audit + outbox, same transaction.** Insert into `agents` +
+   sealed credential write (intake mode) + fence row + semantic audit
+   event (`agent.enrolled`: actor, agent id, harness, provider, name,
+   credentialMode — no credential material) + outbox row commit
+   atomically, hierarchy-pattern style. Audit rows reference the agent
+   by **snapshot id, not FK** — mirroring the hierarchy audit tables'
+   deliberate FK-free linkage so audit history survives agent deletion
+   through the legacy CRUD DELETE path.
+
+Result union: `enrolled { agent, correlationId }` | refusal from the
+§3.3 enum (refusals also carry the correlation id, per contract 5
+§4.3's end-to-end traceability). `agent` in the result is the persisted
+row minus nothing sensitive (the table stores no credential material).
+
+### 3.2 `agent.enrollment.get` (query)
+
+By agent id; actor must be the owner (or admin). Unauthorized and
+missing fold to the same `not_found` wire shape (contract 2
+no-existence-oracle rule, applied family-wide for uniformity).
+
+The query carries the same non-state envelope as the mutation
+(contract 5 §4.3; contract 3's envelope reconciliation confirms closed
+query responses carry it): typed request DTO with an optional
+`correlationId` (generated when absent) and a typed result —
+`found { agent, correlationId }` | `not_found` (the folded shape,
+also carrying the correlation id). Queries take no idempotency key
+(the fence binds mutations).
+
+### 3.3 Error enum (closed, §4.2)
+
+`validation_failed` 400 · `authentication_failed` 401 ·
+`authorization_refused` 403 (owner-only paths; folded to `not_found`
+where §3.2 applies) · `not_found` 404 · `conflict` 409 (the single
+bounded idempotency refusal shape of §3.1 rule 5) · `precondition_failed`
+422 (unresolvable credential reference; well-formed harness not in the
+registry — syntactic invalidity is `validation_failed` per the §3.1
+table) · `internal_fault` 500 (also the §4.4 fail-closed class when the
+owning tool is unreachable; unauthorized-fallback behavior is
+prohibited).
+
+## 4. Schema delta (migration 0021, additive-only)
+
+Extend `agents` — no new agent table, preserving custody-schema §5.2's
+FK binding without amendment:
+
+- `harness` text NULL — registered harness name; NULL for pre-existing
+  rows (legacy rows predate the concept).
+- `enrolled_at` timestamptz NULL — set by `agent.enroll`; NULL marks a
+  legacy (non-enrolled) row. No backfill: enrollment is a fact this
+  command creates, not one to invent for existing rows.
+
+New tables, mirroring the hierarchy audit/outbox pair (pattern reuse,
+separate store): `agent_audit_events` (append-only: id, event_type,
+actor id, agent id — snapshot value, no FK, per §3.1 rule 6 —
+correlation id, causation id, payload jsonb, created_at; per-agent
+ordering index), `agent_outbox` (hierarchy-outbox shape), and
+`agent_idempotency_fence` (contract 3 §4.3 shape: operation identifier,
+key, acting principal, authorization scope, canonicalized-payload
+digest, replay mode, committed-outcome reference (agent id), created_at;
+UNIQUE (operation identifier, key)). Persona reuses the existing
+`system_prompt` column; no version column (no ratified expected-version
+rule names `agents` — §4.1 binds only where the owning contract defines
+one).
+
+Witnesses (real PostgreSQL, lane standard): append-only enforcement,
+same-tx atomicity (agent row + credential write + fence row + audit +
+outbox all-or-nothing under injected failure at multiple points,
+including after the credential write), fence uniqueness on
+(operation, key).
+
+Sequencing: additive DDL via the same migration path as 0018–0020
+(hierarchy). The docs/native-kanban-sot/SHARED-CONTRACT.md §5.3 DDL
+gate binds the kanban lane's audit/proposal DDL, not this lane; if a
+pending operator ruling on migration sequencing changes mechanics
+lane-wide, re-check before generating 0021.
+
+## 5. Witnesses the implementation slice must ship
+
+1. Never-echo: enroll via `intake`, assert the value string is absent
+   from the HTTP result, the audit row, the outbox payload, and captured
+   logs.
+2. Sealed-store single-copy: after intake, the credential exists only in
+   `provider_credentials` (sealed), and `agents` has no credential
+   column at all.
+3. Reference-resolution refusal (`precondition_failed`, no row created).
+4. Harness refusals, both codes: syntactically invalid →
+   `validation_failed`; well-formed registry miss →
+   `precondition_failed` (against the live registry).
+5. Idempotency (contract 3 §4.3 set): actor-bound replay returns the
+   recorded outcome and executes nothing (no new agent/audit/outbox
+   mutation rows; a replay access event is appended); payload-digest
+   mismatch, replay-mode mismatch, scope mismatch, and different-actor
+   actor-bound replay each refuse with the single bounded `conflict`
+   shape; a replay is re-authorized fresh (a submitter whose
+   authorization was revoked since the original is refused, not
+   replayed); a `shared` declaration on `agent.enroll` is refused
+   `validation_failed` with nothing executed and no fence row
+   recorded (seed-only rule); two concurrent same-(operation, key)
+   submissions produce exactly one mutation, the loser resolving
+   through the replay path (no unhandled unique-violation fault).
+6. Same-tx atomicity fault injection (agent / credential write / fence
+   / audit / outbox), including a failure injected after the intake
+   credential write commits its statement — everything rolls back, no
+   orphan credential.
+7. Wizard-facing zero-mutation witness (contract 3 §6.10 shape): no
+   call → zero rows in `agents`/`agent_audit_events`/`agent_outbox`/
+   `agent_idempotency_fence` attributable to the family.
+8. `is_system` injection attempt is rejected by DTO validation.
+9. Correlation-id witness (contract 5 §6.3): a correlation id submitted
+   on `agent.enroll` appears in its audit event(s) and in the result;
+   the same holds for `agent.enrollment.get`'s result; the §6.3 static
+   companions (no `any`-typed boundary pass-through; single audit
+   emitter) apply. §6.3's no-existence-oracle probe: an unauthorized
+   `agent.enrollment.get` of an existing agent and a get of a
+   nonexistent id return indistinguishable results.
+10. CLI-parity witness (contract 5 §6.4): a CLI smoke invocation of
+    `agent.enroll` and `agent.enrollment.get` against the Gateway
+    succeeds with the same typed results the web client receives. The
+    implementation slice therefore SHIPS CLI exposure for both
+    operations (contract 5 §4.5 — a Gateway command without CLI
+    exposure is a tracked conformance gap; this design refuses to open
+    one).
+11. Fail-closed witness (contract 5 §6.5): with the owning tool or
+    grant state unreachable (fault injection), the operation returns
+    the internal-fault or authorization-refusal class and performs no
+    fallback read/write.
+
+## 6. Out of scope
+
+Wizard orchestration (M4-6); any UI (D8/D12); un-enroll/update lifecycle
+(no contract requires it in v1 — the legacy write surfaces named in §2
+keep serving existing consumers); OAuth login, multi-account, comms
+auto-enroll, model recommendation (PRD full flow, deferred by D11);
+contract amendments (F1 recorded above for a future S2 pass). CLI
+exposure is explicitly IN scope (witness 10 — contract 5 §4.5 binds it).

docs/plans/2026-08-30_containerization.md

@@ -0,0 +1,99 @@
+# Plan — Stack Containerization (tiered deployment)
+
+Status: DRAFT for review. Charter: fleet/lanes/stack-containerization
+(brain) NORTH-STAR.md; PRD amendment in the same PR adds D15.
+Supersedes nothing; sequences the absorbed M4 remainder per its lane.
+
+## Measured baseline (origin/next @ 143ba0f5, 2026-08-30)
+
+- `docker-compose.yml`: dev infrastructure only — postgres (pgvector),
+  valkey, otel-collector, jaeger. No application services.
+- `docker-compose.federated.yml`: standalone overlay for the FEDERATED
+  storage tier (own postgres/valkey; port-conflicts the base stack by
+  design). Not an app deployment.
+- `docker/gateway.Dockerfile`, `docker/appservice.Dockerfile`:
+  multi-stage production builds (node:22-alpine) EXIST; the gateway image
+  includes the web SPA bundle (#1444).
+- CI (`publish.yml`) builds and publishes these images (next-channel
+  prereleases + main stable), and runs `verify:release` fail-closed.
+- Gap: no stack-level composition wires gateway+appservice+data plane
+  into one deployable unit; no blessed install/upgrade path; no
+  in-container agent-runtime story for the dogfood loop.
+
+## Target (PRD D15 amendment)
+
+Tiered deployment, additive to the existing architecture:
+
+1. **Standalone tier (v1 bar)**: `docker compose up` on one host brings
+   postgres, valkey, openbao, gateway, appservice (and the webUI the
+   gateway serves) to healthy; migrations apply; the webUI hosts agent
+   chat; an in-stack agent can read this repo and open a PR; CI
+   validates; the deployment adopts merged images (pull + restart).
+2. **Enterprise tier (post-v1)**: Kubernetes manifests (or Helm) for the
+   same service set, phase-gated on the standalone bar holding.
+
+## Phases
+
+### Phase A — blessed standalone compose
+
+- A1 Compose service definitions for gateway + appservice joining the
+  existing infra compose (profiles: `dev` keeps today's behavior;
+  `stack` adds the app tier), with health checks and dependency order.
+- A2 Migrations on boot (or an explicit migrate step) with idempotency
+  and version pinning; init-db.sql folded into pg-init.
+- A3 Openbao in the compose set (secret plumbing for the app tier).
+- A4 `.env.example` + `mosaic.config.json` defaults documented for the
+  standalone mode; mode recorded per the mode-conversion contract.
+- A5 Smoke: `docker compose --profile stack up` green on a scratch host;
+  webUI served; agent chat reachable; failures catalogued and fixed.
+- Acceptance: the five-point NORTH-STAR bar measured live.
+
+### Phase B — component completion
+
+- Interface assumption (velma verdict A1, P5-RM-005/006): in-stack
+  dogfood agents inherit SEAT-GRADE identity — credential-slot
+  isolation, wrapper-first enforcement, no privileged coordination
+  identity, evidence by references that resolve outside the container
+  lifetime.
+- Decompose JIT from A5's catalogue. Known candidates: agent runtime
+  bits (brain/tool access paths in-container), repo credentials for the
+  dogfood agent, watch/comms surfaces inside the deployment.
+
+### Phase C — CI/CD parity
+
+- Publish pipeline is the only image source (already true); add the
+  deployment-side pull/upgrade path (compose pull + migrate + restart =
+  next iteration); document the promotion flow next -> registry ->
+  deployment.
+
+### Phase D — coordinator integration (GATED)
+
+- Gate (velma verdict C2): blocked until the checkpoint-and-lease child
+  of the guides-proposed control-plane refactor — core + WU-P1-CHECKPOINT
+  (schema, freshness, incarnation, clean-replacement resume; D57-D60
+  lineage) — carries an independent target-bound PASS. Wiring restarts
+  against the core alone re-creates the stale-incarnation failure class
+  D57-D60 closed. Transitive: inherits the T108 gates (P0 exit + Jason
+  P1 authorization).
+- Scope (velma verdict C1): lifecycle actions (start/stop/restart/
+  health/recovery) executed by the SHIPPED coord client over the one
+  typed coordination contract (request id, actor identity, epoch,
+  revision, lease, correlation; typed stale rejection; worker role
+  boundary). No second coordination interface gets designed here —
+  containerization consumes the coordination contract, never defines it.
+
+### Phase E — enterprise tier
+
+- k8s manifests/Helm for the same set; phase-gated on Phase A holding.
+
+### Absorbed M4 remainder
+
+- M4-3 pivot: KBN-101 foundation first (per ruling R6), then expand DDL.
+- M4-5: lands inside Phase B/C where natural.
+- M4-6 (composes M4-1+M4-4): last, as designed.
+
+## Non-goals (v1)
+
+- No Kubernetes in v1; no multi-host federation; no replacement of the
+  fleet's brain-based seats (the stack is an additional operator
+  surface); no on-host image builds for deployment (registry only).

docs/plans/README.md

@@ -13,6 +13,10 @@ status: active
 - [Documentation structure README implementation](2026-08-10-docs-structure-readme.md) — completed implementation plan for the documentation contract and atlas.
 - [Documentation catalog and truth audit](2026-08-10-docs-catalog-audit.md) — audit method, evidence statuses, deliverables, and acceptance criteria.
 
+## Feature design plans
+
+- [Agent enrollment command design](2026-08-29-agent-enrollment-command-design.md) — v1 rank-4 enrollment command family: contract composition, command surface, schema delta, witnesses (M4-4-0).
+
 After a plan is delivered, update the canonical guide, contract, decision, or index. Do not cite a plan as proof that intended behavior shipped.
 
 ## Related

docs/requirements/mode-conversion.md

@@ -0,0 +1,279 @@
+# Deployment Mode and Conversion Contract (D3)
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 6 of 9).
+Authority: PRD D3 (Part I §3) — two modes chosen at install time,
+Standalone and Enterprise, with the mode table (brains, user-data
+isolation, secrets, conversion); Standalone → Enterprise conversion is
+**one-way** and Enterprise is a **terminal state**. PRD D14 (Part I §7)
+— the per-user brain split is optional in Standalone and keeping it is
+the recommended default because it preserves forward-compatibility with
+the one-way conversion. PRD D11 (Part I §9) — v1 ships the Standalone
+flow only; Enterprise conversion is explicitly deferred. PRD D3
+federation clause — federation is intentionally not fully designed,
+deferred, and nothing in v1 may foreclose it.
+
+Revision 2 (luna review F1–F7): the identity precondition restated in
+identity-contract terms with a conversion-local acknowledgment record
+this contract owns (F1); a durable, keyed preparation state with a
+Standalone-safe representation rule, an in-transaction re-check fence,
+and an exact flip boundary (F2); the §5.4 unknown-value rule stated
+directly without the contradictory non-exhaustiveness clause (F3); the
+D14 boundary bound here with a stable column-allowlist witness instead
+of delegated to an unratified layout (F4); the conversion witness
+matrix extended to every §4.2/§4.4 condition (F5); the mode-record
+writer coverage imported concretely from contract 1 §6.3 with a named
+schema, closed writer set, crafted-write probe, and mode-resolution
+assertion (F6); the mode read command flagged as a §12.1 drafting
+addition rather than a D8 mandate (F7). Ownership language aligned
+with contract 3 revision 2: mode is recorded at bootstrap and read by
+the wizard as input.
+
+This contract binds the mode as a canonical platform property (§2), the
+per-mode obligations and which contract owns each (§3), the conversion
+transition (§4), the v1 non-foreclosure obligations (§5), and their
+witnesses (§6). Domain semantics stay with their owning contracts:
+wizard branching (contract 3 §2), identity/SSO
+(`identity-lifecycle.md`), custody and per-user brain mechanics
+(contract 7, `custody-schema.md`), tool mapping
+(`tool-gateway-mapping.md`).
+
+## 1. Definitions
+
+1. **Mode**: the platform-wide deployment mode, exactly one of
+   `standalone` or `enterprise`. The vocabulary is closed in v1;
+   extension (e.g. a federation mode) is by amendment to this contract,
+   never ad hoc.
+2. **Conversion**: the one-way transition `standalone → enterprise`.
+   No other mode transition exists.
+3. **Conversion preconditions**: the verifiable conditions of §4.2 that
+   must all hold before the mode record may change.
+4. **Preparation unit**: one re-runnable piece of pre-conversion work —
+   the migration of one secret to the Vault backend, or the partition
+   of one user's brain content (§4.3).
+
+## 2. Mode is a canonical recorded property
+
+1. Mode is recorded canonically in the platform database at bootstrap
+   as the operator's install-time choice (D3: modes are "chosen at
+   install time"). The record is a single-row keyed record
+   (`platform_mode`: mode value, recorded-at timestamp, bootstrap epoch
+   reference); this contract owns it, the bootstrap writer performs the
+   one v1 write (§6.2), and the wizard reads it as input (contract 3
+   §2.3). Mode is never derived from feature state (presence of Vault,
+   count of brains, count of users), and no component may infer a
+   different mode than the record states.
+2. The record is readable by any authenticated user through a Gateway
+   command with CLI exposure. This read command is a **drafting
+   addition** ratified with this contract (PRD §12.1), not a D8
+   mandate: D8 binds only that any surface exposing the value goes
+   through official tooling. When a webUI surface consumes the read, a
+   mapping row is added to `tool-gateway-mapping.md` by amendment —
+   the same route §4.4 already binds for the conversion command.
+   Components branch on the read value only.
+3. The record is immutable except by the §4 conversion transition.
+   Editing it by direct database access, config file, environment
+   variable, or wizard re-run is non-conformant (contract 3 §2.3:
+   changing mode later is conversion, not a wizard re-run).
+
+## 3. Per-mode obligations (owner map)
+
+The PRD mode table binds four rows; this contract assigns each an
+owning contract so no obligation is unowned and none is bound twice:
+
+| Obligation          | Standalone                             | Enterprise                                         | Owner                                         |
+| ------------------- | -------------------------------------- | -------------------------------------------------- | --------------------------------------------- |
+| Brains              | one mosaic-brain (system + user files) | system brain for config + one brain per user       | contract 7 (custody/brain mechanics)          |
+| User-data isolation | single user                            | no user-data leakage between users; sharing opt-in | contract 7 (enforced by architecture, D14)    |
+| Secrets             | OpenBao/Vault or flat files            | OpenBao/Vault REQUIRED                             | this contract (§4.2 gate; steady-state check) |
+| Conversion          | may convert to Enterprise, one-way     | terminal state                                     | this contract (§4)                            |
+
+The Standalone brains row states the default layout, not the only
+valid one: the D14 per-user split is a MAY in Standalone with keeping
+it the recommended default (PRD §7, contract 7 §6), and Vault-backed
+secrets are equally valid Standalone configuration. Both prepared
+states are therefore themselves valid Standalone states — the fact
+§4.3 relies on.
+
+In Enterprise steady state, a flat-file secrets backend is
+non-conformant; the platform refuses to start Enterprise-mode
+components against a flat-file secrets configuration (fail-closed, not
+warn-and-run).
+
+## 4. Conversion transition
+
+1. **Direction and terminality.** The only transition is
+   `standalone → enterprise`. `enterprise → standalone` does not exist:
+   there is no command, no admin override, and no support path. An
+   attempt is refused with the precondition/state error class of the
+   command envelope (`tool-gateway-mapping.md` §4.2).
+2. **Preconditions (all verified before the record changes):**
+   - Secrets: OpenBao/Vault is configured and reachable, and every
+     required secret is served from the Vault backend — none from a
+     flat-file backend. Secret migration completes before conversion;
+     this contract does not define the migration tooling, only the
+     gate.
+   - Brains: the per-user brain split required by the Enterprise row of
+     §3 is established for **every** existing user (or the deployment
+     already kept the split, the D14 recommended default). Brain
+     partitioning mechanics are contract 7; this contract binds only
+     that the split is complete before the mode flips.
+   - Identity: at least one platform administrator account exists that
+     is active in identity-contract terms — authenticated capability,
+     not banned, not deactivated (identity §2, §5). And the conversion
+     request carries a **configuration acknowledgment**: the current
+     canonical values of registration mode and per-provider JIT
+     enablement (identity §2.2, §4.1), echoed back in the request. A
+     mismatch between the echoed values and the canonical values at
+     verification refuses the conversion. This acknowledgment record
+     is conversion-local, owned by this contract, and stored with the
+     §4.4 audit event as the precondition evidence; it adds no
+     identity-contract obligation and no mode-specific identity
+     default — identity's own defaults remain valid states.
+3. **Preparation state and the flip boundary.** Preparatory work is
+   tracked durably: each preparation unit (§1.4) records its
+   completion in a preparation table keyed by (bootstrap epoch, unit
+   identity — the secret's path, the user's id), written in the same
+   transaction as the unit's own effect where the unit's backend
+   allows it, and reconciled from the backend's actual state where it
+   does not (a secret already served by Vault, a brain already split,
+   is complete regardless of the table). Units are at-most-once per
+   key and re-runnable across attempts. **Standalone-safe
+   representation:** every preparation unit moves the deployment into
+   a state that is itself valid Standalone configuration (§3 note), so
+   an interrupted preparation leaves a fully operational Standalone
+   deployment reading its state through the ordinary contracts — no
+   rollback, fencing, or special Standalone read path is needed, and
+   no component behavior may key on "preparation in progress".
+   **The flip:** one transaction that (a) locks the mode record, (b)
+   re-verifies every §4.2 precondition after acquiring the lock, and
+   (c) writes the mode record and the §4.4 audit event. Any re-check
+   failure aborts with no write. External state that changes after the
+   re-check but before commit is bounded by the transaction window;
+   an external backend (Vault) failing after conversion is an
+   Enterprise runtime fault handled by §3's fail-closed steady-state
+   rule, not a conversion defect. An interrupted or failed conversion
+   leaves the record `standalone` and the platform fully operational;
+   there is no intermediate mode and no half-converted state
+   observable through the record.
+4. **Authority and audit.** Conversion is a platform-administrator
+   command carrying an explicit irreversibility acknowledgment in its
+   request (distinct from the §4.2 configuration acknowledgment). It
+   is an official Gateway/CLI command (D8): when built, it is added to
+   the tool↔Gateway mapping by amendment (`tool-gateway-mapping.md`
+   §3.3). The transition emits an audit event (actor, prior mode, new
+   mode, precondition evidence reference including the configuration
+   acknowledgment) in the same transaction as the record change; the
+   event survives indefinitely. A refused attempt emits a refusal
+   event naming the failed precondition class and actor, with no
+   mode-change event.
+
+## 5. v1 obligations (non-foreclosure)
+
+v1 ships Standalone only (D11); the conversion command is deferred
+work. v1 still MUST:
+
+1. Record the mode per §2 at bootstrap, with `enterprise` a reserved,
+   refused value for bootstrap — v1 bootstrap accepts `standalone`
+   only. The wizard reads the record (contract 3 §2.3); nothing in v1
+   writes it after bootstrap.
+2. Keep the §2.3 immutability rule: no v1 surface mutates the mode
+   record.
+3. Not foreclose conversion: the v1 platform database holds no
+   sensitive user content — sensitive categories live in the owning
+   user's brain, and postgres holds structure, consent records, and
+   pointers only (the D14 boundary, PRD §7). Custody mechanics are
+   contract 7's; this contract binds the boundary itself here so v1
+   cannot ship a layout that makes the §4.2 brain precondition
+   unsatisfiable, and §6.3 gives it a stable witness that does not
+   depend on contract 7's internals. Conversion implementation
+   additionally requires contract 7 ratified.
+4. Not foreclose federation: v1 components accept exactly the two §1.1
+   values wherever a mode value is parsed and refuse any other value
+   **before side effects** — a refused configuration, not undefined
+   behavior and not a crash mid-operation. Forward compatibility lives
+   in storage and architecture, not in parser speculation: the mode
+   record's storage is not structurally locked to two values (no
+   database-level two-value enum), and any future value (e.g. a
+   federation mode) is defined by a versioned amendment to this
+   contract before any component accepts it. The PRD defers
+   federation's shape entirely; this contract does not presume it
+   arrives as a third mode value.
+
+## 6. Verification requirements
+
+Binding on the implementing PRs:
+
+1. **Mode-record witness (v1):** after bootstrap the mode is readable
+   via the Gateway command and CLI and equals the bootstrap-recorded
+   choice; bootstrap with mode `enterprise` is refused; bootstrap with
+   any unknown mode value is refused before side effects (§5.4).
+2. **Writer-coverage witness (v1):** the mode record's writer set is
+   closed by the same three-prong static assertion contract 1 §6.3(b)
+   defines — symbol, class-table literal, and raw-execution prongs
+   with its allowlist composition rules — scoped to the
+   `platform_mode` table, with a writer allowlist containing exactly
+   the bootstrap writer in v1 (and exactly plus the conversion command
+   at the conversion milestone). Companions: a crafted direct write
+   attempted in a test fails and leaves the record unchanged; a
+   mode-resolution assertion that no shipped component derives mode
+   from feature state (mode reads occur only through the §2.2 read
+   surface — static assertion over Gateway, CLI, bootstrap, and
+   repository sources).
+3. **D14-boundary witness (v1):** a column-allowlist assertion in the
+   style of contract 1 §6.2 that the platform database schema contains
+   no sensitive-content column — the §5.3 boundary — stable regardless
+   of contract 7's internals (contract 7 §7 carries the full custody
+   witnesses).
+4. **No-downgrade witness (conversion milestone):** with mode
+   `enterprise`, a conversion request to `standalone` (and any crafted
+   mode-write) is refused with the precondition/state error class and
+   no record change.
+5. **Precondition witnesses (conversion milestone),** each refused
+   with no record change and no partial mode effect, parameterized
+   over both OpenBao and Vault where secrets are involved:
+   (a) secrets backend unreachable; (b) one required secret still
+   flat-file backed (migration incomplete); (c) one unpartitioned user
+   brain in a **multi-user** deployment where every other user is
+   partitioned; (d) no active platform administrator (the only admin
+   banned or deactivated); (e) configuration acknowledgment missing or
+   mismatching the canonical registration/JIT values; (f) actor not a
+   platform administrator (authorization refusal); (g) irreversibility
+   acknowledgment absent. And the steady-state rule: an
+   Enterprise-mode component started against a flat-file secrets
+   configuration refuses to start (§3).
+6. **Interruption and fence witnesses (conversion milestone):** fault
+   injection aborting conversion after each preparation unit and
+   between preparation and flip leaves the record `standalone` and the
+   platform operational in Standalone semantics (§4.3
+   Standalone-safety), and a re-attempt completes without duplicating
+   prepared state (at-most-once keys); a precondition invalidated
+   after preparation but before the flip (a secret reverted to
+   flat-file) is caught by the in-transaction re-check and refused.
+7. **Audit witnesses (conversion milestone):** a completed conversion
+   has exactly one mode-change audit event, same-transaction with the
+   record change (transaction linkage asserted), carrying actor, prior
+   mode, new mode, and the precondition evidence reference including
+   the configuration acknowledgment; a failed attempt has a refusal
+   event naming the failed precondition class and no mode-change
+   event; the mode-change event remains queryable after subsequent
+   unrelated audit activity (retention probe).
+8. **Mapping witness (conversion milestone):** the conversion command
+   and the mode read command each have their
+   `tool-gateway-mapping.md` row (added by amendment per §2.2/§4.4)
+   before the commands ship.
+
+## Ruling request
+
+Ratify sections 1–6 as written, with one decision embedded:
+
+- Decision (§5): v1 implements the **mode record and its immutability
+  only** — bootstrap records `standalone`, the `enterprise` value is
+  reserved and refused, and the conversion command itself is deferred
+  to the Enterprise milestone, consistent with D11's deferred list.
+  v1 carries three obligations beyond the record: the closed writer
+  assertion, the D14 column boundary, and the unknown-value refusal
+  (§6.1–§6.3) — these are the non-foreclosure floor, not hidden
+  conversion work. Alternative if rejected: build the conversion
+  command inside v1 — rejected because D11 scopes v1 to the Standalone
+  slice and conversion depends on contract 7 custody mechanics that
+  are themselves not in the v1 slice.

docs/requirements/native-kanban-sot.md

@@ -514,3 +514,47 @@ itself permits, so that contract does not stretch A1 by interpretation.
    default-open disclosure.
 5. Every other constraint of A1 — §8.1.2's remaining bullets, §8.2 in full,
    and §8.3's other acceptance criteria — is untouched.
+
+## 10. Amendment A3 — capability-holder existence disclosure
+
+**Status:** amendment to Amendment A2, added by reviewed PR together with
+contract 2 Amendment 1 (`rbac-grant-model.md` §8, this PR), under that
+amendment's ruling request (decision owner Jason). It binds if and only if
+contract 2 Amendment 1 ratifies; until then §9.1.2's sole-disclosure rule
+stands unmodified — which is consistent, because until ratification the
+company-CRUD capability class is empty and the carve-out below has no
+holders. Everything in §§1–9 remains binding verbatim, with exactly the one
+express modification below. The detailed contract text lives in
+`rbac-grant-model.md` §8.1; this amendment changes only what A2 itself
+permits, so that contract does not stretch A2 by interpretation.
+
+### 10.1 What A3 modifies in A2
+
+1. **Capability-holder disclosure (narrows §9.1.2's sole-disclosure rule
+   by one carve-out).** §9.1.2 makes the directory the sole permitted
+   existence disclosure and keeps private companies undisclosed to
+   non-granted subjects everywhere. A3 admits exactly one further
+   disclosure channel: a subject holding the company-CRUD capability
+   (contract 2 §8), when exercising the hierarchy schema §5.5 visibility
+   command, learns the target company's existence and its old/new
+   visibility values through the command's redacted actor receipt —
+   success for an existing target (private or directory alike) versus
+   `not_found` for a nonexistent id — bounded exactly as contract 2 §8.1
+   states: no name, slug, structure, content, grant, or membership
+   information, and no read command of any kind. To every other
+   non-granted subject, private companies remain undisclosed everywhere,
+   including the directory; the directory remains the sole
+   existence-disclosure _listing_.
+
+### 10.2 What A3 explicitly does not change
+
+1. The directory itself is unchanged: read-only, directory-class companies
+   only, existence/name/slug only (§9.1.2's enumeration is narrowed for
+   capability holders' receipts, widened for nothing).
+2. No join-request surface, no curation listing, no read command of any
+   family is authorized (§9.2.2 unchanged; a curation listing is a further
+   amendment per contract 2 §8.1).
+3. The canonical audit event for visibility mutations is untouched — it
+   keeps hierarchy schema §5.2's full immutable target snapshot; the
+   capability confers no audit read (contract 2 §8.5).
+4. Every other constraint of A1 and A2 is untouched.

docs/requirements/rbac-grant-model.md

@@ -24,6 +24,26 @@ fail-closed-fault, and existence-oracle observables added (§7);
 role-string namespacing rule added (§4.5); ruling request now names the
 interpretive resolution of PRD "admins".
 
+Amendment 1 (company-CRUD capability): defines the capability class that
+contract 1 Amendment 1 (Ruling 4b, 2026-08-28) and hierarchy schema §5.5
+anticipate. §8 defines the capability as a platform-scoped, admin-assigned,
+audited delegation of exactly the hierarchy schema §5.5 company visibility
+command — no read command, no other company operation; the mutation's
+inherent existence disclosure is ratified as a bounded carve-out to
+hierarchy schema §6.7/§2.8 and to kanban SOT Amendment A2's
+sole-disclosure rule — SOT Amendment A3 (native-kanban-sot.md §10, this
+PR) expressly extends A2 by exactly this carve-out (§8.1). The holder
+sees only a redacted actor receipt; the canonical audit event keeps
+hierarchy schema §5.2's full immutable snapshot. The hierarchy role
+vocabulary (§2), every evaluation rule (§3), and grant management (§4) are
+untouched: the capability is not a `hierarchy_grants.role` value and
+evaluates outside the chain; capability-row deletion joins §6.1's
+revocation enumeration (§8.4). Until this amendment ratifies, the capability
+class is empty and
+the visibility command remains admin-only (hierarchy schema §5.5 states
+this fallback; the shipped gate at
+`apps/gateway/src/hierarchy/hierarchy.repository.ts` implements it).
+
 Scope: the roles that can appear in `hierarchy_grants.role`, what a grant at
 each hierarchy level confers, how grants evaluate down the chain, how
 revocation propagates, and who may manage grants. Out of scope: the hierarchy
@@ -242,6 +262,191 @@ contract 1 §6):
 8. Transfer: both-sides `owner` accepted, each single-side case refused
    (completing contract 1 §6.5).
 
+## 8. Company-CRUD capability (Amendment 1)
+
+Hierarchy schema §5.5 authorizes the company visibility mutation for
+exactly two actor classes: platform admins and "subjects holding the
+company-CRUD capability that a follow-up amendment to contract 2 will
+define". This section is that definition. The name is historical — coined
+in contract 1 Amendment 1 before the capability's content was fixed — and
+confers nothing by connotation: the ratified content is exactly §8.1.
+Company _creation_ is already ruled open to active users and always
+private (contract 3 §5.2, Ruling 4); rename, delete, and transfer of
+companies remain hierarchy `owner` operations (§2.3, §5); none of those is
+part of this capability, and widening it to any other operation is a
+further amendment, not an implementation decision.
+
+1. **Content: exactly one command, no read command, disclosure stated.**
+   Holding the capability authorizes executing the hierarchy schema §5.5
+   visibility command (`companies.visibility`, both directions:
+   `private → directory` and `directory → private`) on any company in the
+   deployment, and no other command of any family. It confers **no read
+   command**: no company enumeration, no curation listing, no structure
+   read. The practical flow this implies is deliberate: to publish a
+   private company, the holder is given the target identifier by the
+   requesting company `owner` out of band; to unpublish, the target is
+   already directory-listed. A curation listing for capability holders,
+   if ever wanted, is a further amendment with its own disclosure
+   analysis under hierarchy schema §6.7.
+
+   **Existence disclosure carve-out, stated rather than pretended away:**
+   exercising a mutation inherently discloses its target's existence.
+   The command's result distinguishes an existing company (success, for
+   private and directory targets alike) from a nonexistent id
+   (`not_found`), so a holder presenting candidate ids learns existence —
+   exactly as a platform admin already does through the same command.
+   This amendment ratifies that disclosure as part of the §5.5 curation
+   authority, bounded as follows. The holder-visible surface is the
+   command's **actor receipt** — the mutation result payload, carrying
+   exactly the target id, old visibility, and new visibility, and
+   **nothing else**: no name, slug, structure, content, grant, or
+   membership information. The actor receipt is a redacted projection
+   distinct from the **canonical audit event**, which is unchanged by
+   this amendment: it keeps hierarchy schema §5.2's deletion-safe
+   immutable target snapshot (id, slug, and parent chain at event time)
+   in full. The two never converge on the holder: the capability confers
+   no audit read (§8.5), so the canonical event — and with it the slug
+   and parent chain — is reachable only by subjects independently
+   authorized to read audit data, never through this capability. A
+   successful publish additionally makes the target directory-listed to
+   every authenticated user; that is the command's ratified purpose
+   (hierarchy schema §5.5), not a leak. Hierarchy schema §6.7's
+   existence-oracle rule and §2.8's directory-only disclosure are amended
+   by exactly this carve-out for capability holders, kanban SOT Amendment
+   A3 (native-kanban-sot.md §10, this PR) expressly extends A2's
+   sole-disclosure enumeration by the same carve-out, and all three are
+   otherwise untouched. Witnessed in §8.6.3.
+
+2. **Holding: platform-scoped assignment, user subjects only.** The
+   capability is not a hierarchy grant: it attaches to no node, has no
+   role, and never enters §3 chain evaluation. It is held via a
+   `platform_capabilities` table whose column set is exactly (nothing
+   else, per the contract 1 §2.7 exhaustiveness discipline):
+   - `id` — uuid, primary key;
+   - `user_id` — text, NOT NULL, FK `users` **ON DELETE RESTRICT**;
+   - `capability` — text, NOT NULL, constraint-checked against exactly
+     `company_crud`;
+   - `granted_by` — text, NOT NULL, FK `users` **ON DELETE RESTRICT**;
+   - `created_at` — timestamptz, NOT NULL;
+   - UNIQUE (`user_id`, `capability`).
+
+   The user FKs are **text**, not uuid, because `users.id` is a BetterAuth
+   text key (`packages/db/src/schema.ts`; custody schema records the same)
+   — PostgreSQL cannot reference a text primary key with a uuid column.
+   This matches the shipped `hierarchy_grants` shape exactly: uuid
+   surrogate `id`, text FKs to `users`.
+
+   Both user FKs are RESTRICT for the same reason contract 1 §3.3 pins
+   RESTRICT on principal FKs: the identity contract (§7.3) gates user
+   deletion, and a cascade here could silently destroy a capability
+   without its §8.3 revocation audit event. Revocation is row deletion
+   through the §8.3 command — there is no other removal path, no expiry
+   column, and no tombstone. A deactivated holder confers nothing while
+   deactivated: identity contract §7.1 denies all authorization to
+   deactivated accounts, and the §8.4 predicate evaluates on the
+   authenticated live user. No team subjects (§1.4's suspension reasoning
+   applies with more force here — a workspace-bound team holding
+   deployment-wide curation authority has no ratified meaning).
+
+3. **Assignment is instance administration on the normal admin surface.**
+   Only platform admins (`users.role = 'admin'`) may assign or revoke the
+   capability, through an ordinary admin command (the same command class
+   `AdminGuard` governs, §1.1) — not through direct table writes.
+   Assignment delegates a slice of instance administration and is itself
+   an instance-administration act under §1.1. A capability holder as such
+   may NOT assign or revoke it (no self-propagation). Every assignment
+   and revocation is a semantic audit event carrying actor, verb, subject
+   user, and capability; serialized capability strings are namespaced per
+   §4.5 (`platform-capability:company-crud` — a bare `company_crud` in
+   any serialized artifact is non-conformant).
+4. **Evaluation and revocation follow this contract's existing rules.**
+   The hierarchy schema §5.5 command's authorization predicate is:
+   `users.role = 'admin'` OR a live `platform_capabilities` row
+   (`user_id`, `company_crud`). Both disjuncts are evaluated live and
+   fail closed per §3.5 — **independently**: with capability state
+   unreadable (fault), the capability disjunct denies, but a platform
+   admin whose `users.role` is readable remains authorized through the
+   admin disjunct; with role state unreadable, the admin disjunct denies
+   likewise. A decision that can read neither denies. Capability-row
+   deletion is hereby added to §6.1's enumerated revocation paths:
+   it propagates identically, under §6.2's bound, on every transport —
+   no new HTTP/MCP command authorized by the deleted row after the
+   revoking transaction commits, and any cached authorization is
+   invalidated in the revoking transaction (§3.5).
+5. **What it does not confer**, stated so implementing PRs cannot drift:
+   no hierarchy grant or effective role at any node; no workspace
+   authorization or membership; no content, structure, or roll-up read;
+   no grant management (§4.1 unchanged); no MCP scope; no other instance
+   administration (user management, system settings, provider
+   configuration remain platform-admin-only); no company create, rename,
+   delete, or transfer. Hierarchy schema §5.5's rule that a company
+   `owner` as such may NOT change visibility is unchanged — `owner` and
+   this capability are disjoint authorities that combine only by a
+   subject holding both.
+6. **Verification requirements** (extends §7, binding on implementing
+   PRs):
+   1. Schema witnesses (real PostgreSQL, `ci-postgres` service in the
+      `test` CI step): the `capability` CHECK constraint rejects any
+      value outside `company_crud`; NOT NULL enforced on every declared
+      NOT NULL column; UNIQUE (`user_id`, `capability`) rejects a
+      duplicate; both user FKs reject a dangling reference AND deleting a
+      referenced user is refused (RESTRICT witnessed in both directions);
+      the table's column set is exactly the §8.2 declared set (contract 1
+      §6.2 discipline).
+   2. Capability-only command matrix — the witness that proves "exactly
+      one command", not merely "at least one": a non-admin holder with no
+      other grants succeeds on the visibility command in **both**
+      directions with contract 1 §5.2's audit event (old and new values
+      as semantic content), and the **same** actor is refused, case by
+      enumerated case: every hierarchy mutation family (company/child
+      create under another's node, rename, delete, transfer); grant
+      create/change/revoke; the workspace read and write command
+      families; roll-up reads; structure reads — including the
+      not-found-indistinguishable refusal on a structure read of the very
+      company they just mutated (hierarchy schema §6.7); every
+      instance-administration surface other than the visibility command
+      (user management, system settings, provider configuration, and
+      capability assign/revoke itself); and MCP scope derivation yields
+      nothing — the §7.4 deny-by-default matrix gains this row. Company
+      creation compares against an eligible-user baseline: the holder's
+      create behaves exactly as any active user's — always `private`,
+      and a creation request carrying a visibility argument is refused
+      for holder and baseline alike (contract 3 §5.2).
+   3. Disclosure bound (§8.1 carve-out witnessed, receipt and canonical
+      event separately): the mutation result for a private-valid target,
+      a directory-valid target, and a nonexistent id is exactly {success,
+      success, `not_found`}; the actor receipt for a success carries
+      exactly {target id, old visibility, new visibility} and no result
+      or error payload carries name, slug, structure, content, grant, or
+      membership data; the canonical audit event for the same mutation —
+      asserted directly against the hierarchy outbox, not through any
+      holder-facing surface — carries hierarchy schema §5.2's full
+      immutable snapshot (id, slug, parent chain); and the holder's
+      attempt to read audit data is refused (no audit read conferred,
+      §8.5), proving the receipt/event separation reaches the holder as
+      a redaction, not a weakened event.
+   4. Assignment path, both polarities: a platform admin assigns and
+      revokes through the normal admin command (positive witnesses —
+      assign then observe the §8.6.2 allow, revoke then observe deny); a
+      non-admin — including a current capability holder — is refused
+      assign and revoke; every assign/revoke produces its audit event
+      with the namespaced string (§8.3); a direct-write path that skips
+      the command surface is non-conformant (the §8.3 command is the only
+      writer of `platform_capabilities`).
+   5. Revocation joins the §7.6 matrix: assignment is decision-time-live
+      (capability assigned → the holder's next visibility command allows,
+      no re-login); after row deletion, the ex-holder's next visibility
+      command is refused **on every exposed transport**, measured with
+      the revocation and the decision on distinct physical connections; a
+      cached-authorization implementation proves transactional
+      invalidation (§3.5). Fail-closed fault witnesses, both disjuncts
+      (§8.4): with `platform_capabilities` unreadable, a non-admin holder
+      is denied while a platform admin remains authorized; with role
+      state unreadable, the admin disjunct denies.
+   6. Owner-as-such refusal re-witnessed: hierarchy schema §6.9's
+      owner-cannot-publish witness re-asserted with the
+      `platform_capabilities` table present and empty for that owner.
+
 ## Ruling request
 
 Ratify sections 1–7 as written, with one decision embedded and one
@@ -257,3 +462,17 @@ interpretive resolution named:
   platform admins. A1 §8.1.3 does not attribute grant declaration to
   platform admins, and the §1.1 decision above is what makes this reading
   binding.
+
+## Ruling request (Amendment 1)
+
+Ratify §8, the Amendment 1 header note, and kanban SOT Amendment A3
+(native-kanban-sot.md §10 — the express A2 carve-out extension, which
+binds only with this ratification) as written, with one decision
+embedded:
+
+- Decision: the company-CRUD capability is a platform-scoped,
+  admin-assigned, audited delegation of exactly the hierarchy schema §5.5
+  visibility command — no read command, no other company operation, with
+  the mutation's inherent existence disclosure ratified as a bounded
+  carve-out (§8.1). Say "agreed" or name the additional operations (or
+  the curation listing) you want it to carry.

docs/requirements/tool-gateway-mapping.md

@@ -0,0 +1,197 @@
+# Tool↔Gateway Mapping Contract (D8)
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 5 of 9).
+Authority: PRD D8/D12 (Part I §8) — the webUI sits OVER official tooling:
+every webUI operation goes through the Gateway API backed by the same
+official framework tooling the CLI uses, and a webUI operation with no
+backing tool is scored **blocked on tooling** and the tool is built
+first. Measured input: the webui-audit A5 tooling baseline
+(operation-by-operation inventory of the current Gateway surface and the
+P1 gaps, cross-reviewed; `fleet/lanes/webui-audit/findings/
+A5-tooling-baseline.md` in the estate brain). The T10 ruling adopted the
+targeted-update plan including building the D8 tools in A5's rank order.
+
+Revision 2 (GLM review F1–F5): the §2 table completed against an
+independent re-measurement of the live `apps/web` surface (mission
+reads, coordination status, capability-gated `turn:send` added); rank-6
+composition corrected to ranks 1 and 4; SOT citations corrected to §3
+invariant 11 / REQ-TASK-001 / §5+A1; the §3.2 retirement clause
+softened to match what the owning contracts actually schedule; §6.1
+scoped to outbound calls with an extractability lint, and §6.3 given
+static companions for §4.1 and §4.3.
+
+This contract binds three things: the operation→tool mapping itself
+(§2–§3), the command envelope every mapped operation satisfies
+(§4), and the process rule that keeps the mapping closed (§5). Domain
+semantics stay with their owning contracts — hierarchy (contract 1,
+`hierarchy-schema.md`), grants (contract 2, `rbac-grant-model.md`),
+wizard (contract 3, `onboarding-wizard.md`), identity
+(`identity-lifecycle.md`), kanban lifecycle (`native-kanban-sot.md`
+§5 and Amendment A1), roll-up (contract 8), API artifact format
+(contract 9).
+
+## 1. Definitions
+
+1. **Official tool**: a command implemented in the framework packages and
+   exposed through the Gateway API; the CLI remains the primary execution
+   method for the same command (D8). The webUI is a Gateway client only.
+2. **Mapped operation**: a webUI operation with a named official path in
+   §2 or §3. Anything else the webUI wants to do is unmapped and follows
+   §5.
+3. **Legacy non-substitute**: an existing endpoint that resembles a P1
+   need but is contractually barred from backing it (§3.2).
+
+## 2. P0 mapping (current operations, ratified as-is)
+
+This table is the complete measured P0 surface: every Gateway call the
+web app's production sources make at this revision's head appears as a
+row (independently re-measured at review; the three calls the first
+measurement missed — mission reads, coordination status, and the
+capability-gated `turn:send` emit — are rows below). The surface stays
+bound to these paths:
+
+| WebUI operation                                                   | Official path                                                                                                                                                                                                                               |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Register / log in / log out / OIDC callback                       | better-auth mount `/api/auth/*`; `GET /api/sso/providers`                                                                                                                                                                                   |
+| List/show projects (legacy read)                                  | `GET /api/projects`, `GET /api/projects/:id`                                                                                                                                                                                                |
+| List tasks / task detail (legacy read)                            | `GET /api/tasks`, `GET /api/tasks/:id` — with the filtered legacy project/mission reads the same surfaces use                                                                                                                               |
+| Mission list (legacy read)                                        | `GET /api/missions`                                                                                                                                                                                                                         |
+| Coordination status (legacy read)                                 | `GET /api/coord/status`                                                                                                                                                                                                                     |
+| Conversation CRUD/search/messages                                 | `/api/conversations*`                                                                                                                                                                                                                       |
+| Chat turn / stop / thinking / command execute+approve / streaming | `/chat` socket events `message`, `abort`, `set:thinking`, `command:execute`, `command:approve`; `turn:send` (capability-gated — emitted only when the server advertises the pi turn-runtime capability, which the current Gateway does not) |
+| Harness/model selection                                           | `GET /api/harnesses*`, `GET/PUT /api/chat/preferences/selection`                                                                                                                                                                            |
+| Preferences; provider inspect/test                                | `/api/memory/preferences`, `GET /api/providers`, `POST /api/providers/test`                                                                                                                                                                 |
+| Admin users / roles / ban / health                                | `/api/admin/users*`, `/api/admin/health`                                                                                                                                                                                                    |
+
+P0 rows inherit §4 obligations as their backing controllers are next
+touched; they are not required to be retrofitted in one sweep.
+
+## 3. P1 mapping (bound to the build-first tools)
+
+1. Every P1 operation maps to exactly one build-first command family, in
+   the T10-ruled rank order:
+
+| Rank | Command family (owning contract)                                       | P1 webUI operations it backs                                                                                                                      |
+| ---- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | Hierarchy command family (contract 1 §5; grants attach per contract 2) | Company/estate/platform-project/workspace CRUD, parentage and reparenting, hierarchy reads; the wizard's initial-hierarchy step (contract 3 §3.4) |
+| 2    | Hierarchy RBAC command/evaluator (contract 2)                          | Grant create/change/revoke at company/estate/platform-project; inherited evaluation down to workspace; authorization-safe hierarchy queries       |
+| 3    | Typed kanban command/query surface (SOT §5, Amendment A1)              | Workspace task lifecycle (create/edit/cancel/archive/move), board rank, typed queries                                                             |
+| 4    | Agent enrollment command                                               | Enroll one agent: harness, credential reference/API-key intake (values never echoed), name/persona, assignment scope (contract 3 §3.5)            |
+| 5    | Authorized roll-up query (contract 8)                                  | Read-only aggregated task counts/statuses at every hierarchy level over readable workspaces only                                                  |
+| 6    | Onboarding orchestration (contract 3)                                  | The re-runnable wizard flow, composing ranks 1 and 4 (its only grant write rides inside the rank-1 company-create command, contract 2 §4.3)       |
+
+2. **Legacy non-substitutes.** The following MUST NOT back any P1
+   operation, matching the audit findings: legacy `/api/projects` and
+   `/api/tasks` CRUD (planning-data records, not hierarchy nodes and not
+   the typed kanban boundary); `POST /api/workspaces` (filesystem
+   bootstrap, not audited hierarchy parentage); `/api/teams` reads (no
+   grants, no inheritance); `POST /api/bootstrap/setup` (one-shot
+   epoch transition, identity §3 — not the re-runnable wizard); the MCP
+   `brain_*` task mutations (legacy Brain writes, not the typed kanban
+   commands). These stay serving their existing P0/host consumers until
+   the owning contract (or a successor amendment) schedules each
+   retirement — no such migration is scheduled at this revision; the
+   freeze stands on its own.
+3. New P1 mapping rows (operations this table does not list) are added by
+   amending this contract, not ad hoc (§5).
+
+## 4. Command envelope (request / result / error / audit)
+
+Binding on every mapped operation the build-first families expose:
+
+1. **Typed request and result.** Each command and query has an explicit
+   request DTO and result DTO in the shared types package, validated at
+   the Gateway boundary; unvalidated pass-through and `any`-typed
+   payloads are non-conformant. Mutations on records with an
+   expected-version rule in their owning contract carry the expected
+   version in the request and fail on mismatch with the conflict error
+   class (SOT §3 invariant 11 and REQ-TASK-001's concurrent-update
+   conflict acceptance; hierarchy per contract 1).
+2. **Error taxonomy.** Every error result carries a stable
+   machine-readable code from a closed per-family enum plus an HTTP
+   status mapping, distinguishing at minimum: validation failure,
+   authentication failure, authorization refusal, not-found, conflict
+   (version/uniqueness), precondition/state refusal (e.g. bootstrap
+   epoch, suspended team subjects), and internal fault. Where contract
+   2's no-existence-oracle rule applies, authorization refusal and
+   not-found are indistinguishable on the wire for unauthorized readers
+   — same code, same status, same shape.
+3. **Audit linkage.** A mutating mapped operation emits exactly the
+   audit events its owning contract defines (contract 1 §5.2, contract 2
+   §4.4, identity §§2–4, SOT audit rules); the envelope contributes the
+   correlation: every request accepts/generates a correlation id,
+   carried into the audit events and returned in the result, so a UI
+   action is traceable end to end. The mapping layer itself adds no
+   second audit stream.
+4. **Fail-closed.** A mapped operation that cannot evaluate its
+   authorization or reach its owning tool refuses (contract 2 §3.5); the
+   envelope never degrades to an unauthorized fallback read or a direct
+   data access.
+5. **CLI parity.** Each build-first family is invocable through the
+   official CLI against the same Gateway commands with the same
+   request/result/error contracts. No webUI-only command exists; a
+   Gateway command without CLI exposure is a conformance gap tracked at
+   the family's implementing issue.
+
+## 5. Closure rule (blocked on tooling)
+
+1. A webUI change that needs an operation with no mapping row is
+   **blocked on tooling**: the backing tool is built and mapped first
+   (D8). Scoring a gap "blocked on tooling" is mandatory, not
+   discretionary; working around it in the UI (direct DB or filesystem
+   access, calling a legacy non-substitute, embedding domain logic in
+   the web app) is non-conformant.
+2. The mapping is enforced closed by §6.1's inventory witness: the web
+   app's network surface must be a subset of the mapped paths.
+
+## 6. Verification requirements
+
+Binding on the implementing PRs:
+
+1. **Network-surface inventory witness:** a CI assertion extracting the
+   web app's outbound Gateway calls — route literals at request call
+   sites and outbound socket emits in `apps/web` sources (inbound
+   handler registrations are not calls and are out of scope) — and
+   failing on any call outside the §2/§3 mapped paths. The inventory is
+   closed like contract 1 §6.3's allowlist: a new call fails until a
+   mapping row exists in the same PR. Dynamic route construction that
+   evades extraction is resolved toward the witness, enforced by an
+   extractability lint: every request call site takes a literal or
+   template-literal path, and a call site that does not fails the
+   assertion itself (the web-side analogue of contract 1's
+   raw-execution prong), never an exemption for the caller.
+2. **Non-substitute witness:** the P1 surfaces (hierarchy, RBAC, kanban,
+   enrollment, roll-up, wizard UI) make zero calls to the §3.2 legacy
+   endpoints — asserted by the same inventory, scoped per surface.
+3. **Envelope witnesses per family:** for each build-first family — a
+   request with an invalid DTO is refused with the validation code; a
+   version-mismatch mutation returns the conflict code; an unauthorized
+   read of an existing node and a read of a nonexistent node return
+   indistinguishable results where the no-existence-oracle rule applies;
+   a correlation id submitted on a mutation appears in its audit
+   event(s) and result. Two static companions: a type-level assertion
+   that the family's boundary accepts no `any`-typed or unvalidated
+   pass-through payload (§4.1), and a single-emitter assertion that the
+   mapped operation's audit events originate only from the owning
+   contract's audit emitter (§4.3's no-second-audit-stream, made
+   checkable).
+4. **CLI-parity witness:** for each family, a CLI smoke invocation of at
+   least one command and one query against the Gateway succeeds with the
+   same typed result the web client receives.
+5. **Fail-closed witness:** with the owning tool or grant state
+   unreachable (fault injection), the mapped operation returns the
+   internal-fault or authorization-refusal class and performs no
+   fallback read/write (extends contract 2 §7.6 to the mapping layer).
+
+## Ruling request
+
+Ratify sections 1–6 as written, with one decision embedded:
+
+- Decision (§3.2): the legacy endpoints named there are **frozen for new
+  consumers** as of ratification — existing P0/host consumers keep
+  working, new UI or tool code may not call them, and each is retired by
+  the migration its owning contract schedules. Alternative if rejected:
+  allow P1 surfaces to reuse legacy endpoints as interim backends —
+  rejected by the audit's finding that they cannot satisfy the
+  hierarchy/kanban/RBAC contracts, so the interim would ship
+  non-conformant semantics.

packages/brain/src/mission-tasks.spec.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createMissionTasksRepo } from './mission-tasks.js';
+
+/**
+ * SHARED-CONTRACT §5.5 "mission_tasks.status write prohibition": this repo is
+ * the sole path that authors mission_tasks.status from caller input (storage
+ * tier migration is row transport and preserves stored values; the generic
+ * storage adapters have no mission_tasks caller), and it must never forward a
+ * caller-supplied status to the database on create or update. Callers keep
+ * working (the field is accepted and ignored), so these tests assert on what
+ * reaches the Drizzle chain, not on rejection.
+ */
+
+function makeInsertDb(returned: unknown[]) {
+  const values = vi.fn((_v: unknown) => ({ returning: vi.fn().mockResolvedValue(returned) }));
+  return { db: { insert: vi.fn(() => ({ values })) }, values };
+}
+
+function makeUpdateDb(returned: unknown[]) {
+  const set = vi.fn((_v: unknown) => ({
+    where: vi.fn(() => ({ returning: vi.fn().mockResolvedValue(returned) })),
+  }));
+  return { db: { update: vi.fn(() => ({ set })) }, set };
+}
+
+describe('createMissionTasksRepo — status write prohibition', () => {
+  it('create strips a caller-supplied status before insert', async () => {
+    const { db, values } = makeInsertDb([{ id: 'mt1', status: 'not-started' }]);
+    const repo = createMissionTasksRepo(db as never);
+
+    const result = await repo.create({
+      missionId: 'm1',
+      userId: 'u1',
+      status: 'done',
+      description: 'd',
+    } as never);
+
+    expect(values).toHaveBeenCalledTimes(1);
+    const inserted = values.mock.calls[0]![0] as Record<string, unknown>;
+    expect('status' in inserted).toBe(false);
+    expect(inserted.missionId).toBe('m1');
+    expect(inserted.description).toBe('d');
+    expect(result.id).toBe('mt1');
+  });
+
+  it('create without status still inserts (DB default applies)', async () => {
+    const { db, values } = makeInsertDb([{ id: 'mt2' }]);
+    const repo = createMissionTasksRepo(db as never);
+
+    await repo.create({ missionId: 'm1', userId: 'u1' } as never);
+
+    const inserted = values.mock.calls[0]![0] as Record<string, unknown>;
+    expect('status' in inserted).toBe(false);
+  });
+
+  it('update strips a caller-supplied status but keeps the other fields', async () => {
+    const { db, set } = makeUpdateDb([{ id: 'mt1', notes: 'n' }]);
+    const repo = createMissionTasksRepo(db as never);
+
+    const result = await repo.update('mt1', { status: 'done', notes: 'n' } as never);
+
+    expect(set).toHaveBeenCalledTimes(1);
+    const updated = set.mock.calls[0]![0] as Record<string, unknown>;
+    expect('status' in updated).toBe(false);
+    expect(updated.notes).toBe('n');
+    expect(updated.updatedAt).toBeInstanceOf(Date);
+    expect(result?.id).toBe('mt1');
+  });
+
+  it('update with only status degenerates to a timestamp-only update', async () => {
+    const { db, set } = makeUpdateDb([{ id: 'mt1' }]);
+    const repo = createMissionTasksRepo(db as never);
+
+    await repo.update('mt1', { status: 'blocked' } as never);
+
+    const updated = set.mock.calls[0]![0] as Record<string, unknown>;
+    expect(Object.keys(updated)).toEqual(['updatedAt']);
+  });
+});

packages/brain/src/mission-tasks.ts

@@ -3,6 +3,24 @@ import { eq, and, type Db, missionTasks } from '@mosaicstack/db';
 export type MissionTask = typeof missionTasks.$inferSelect;
 export type NewMissionTask = typeof missionTasks.$inferInsert;
 
+// SHARED-CONTRACT §5.1 phase 1 / §5.4: mission_tasks.status is prohibited as a
+// write source through the N-1 window. This repo is the sole path that authors
+// status from caller input, so the field is stripped here — accepted and
+// ignored rather than rejected, because the legacy surface is frozen with
+// existing consumers kept working (tool-gateway-mapping.md §3.2). Two other
+// surfaces touch the column and are deliberately NOT stripped:
+// packages/storage/migrate-tier.ts copies whole rows between storage tiers and
+// must preserve the stored value verbatim, and the generic table-keyed storage
+// adapters register mission_tasks but have no caller that targets it (runtime
+// callers use fixed collection constants). Neither authors a new status. The
+// column keeps its DB default, stays declared and readable, and is retired
+// only after no readers remain.
+function stripStatus<T extends { status?: unknown }>(data: T): Omit<T, 'status'> {
+  const rest = { ...data };
+  delete rest.status;
+  return rest;
+}
+
 export function createMissionTasksRepo(db: Db) {
   return {
     async findByMission(missionId: string): Promise<MissionTask[]> {
@@ -30,14 +48,14 @@ export function createMissionTasksRepo(db: Db) {
     },
 
     async create(data: NewMissionTask): Promise<MissionTask> {
-      const rows = await db.insert(missionTasks).values(data).returning();
+      const rows = await db.insert(missionTasks).values(stripStatus(data)).returning();
       return rows[0]!;
     },
 
     async update(id: string, data: Partial<NewMissionTask>): Promise<MissionTask | undefined> {
       const rows = await db
         .update(missionTasks)
-        .set({ ...data, updatedAt: new Date() })
+        .set({ ...stripStatus(data), updatedAt: new Date() })
         .where(eq(missionTasks.id, id))
         .returning();
       return rows[0];

packages/db/drizzle/0020_special_betty_brant.sql

@@ -0,0 +1,5 @@
+ALTER TABLE "hierarchy_audit_events" DROP CONSTRAINT "hierarchy_audit_events_verb_check";--> statement-breakpoint
+ALTER TABLE "companies" ADD COLUMN "visibility" text DEFAULT 'private' NOT NULL;--> statement-breakpoint
+ALTER TABLE "companies" ADD CONSTRAINT "companies_visibility_check" CHECK (visibility IN ('private', 'directory'));--> statement-breakpoint
+ALTER TABLE "hierarchy_audit_events" ADD CONSTRAINT "hierarchy_audit_events_verb_check" CHECK (verb IN ('create', 'rename', 'transfer', 'visibility_change', 'delete', 'grant_create', 'grant_change', 'grant_revoke'));--> statement-breakpoint
+ALTER TABLE "hierarchy_grants" ADD CONSTRAINT "hierarchy_grants_role_check" CHECK (role IN ('viewer', 'member', 'owner'));

packages/db/drizzle/0021_agent_enrollment.sql

@@ -0,0 +1,47 @@
+CREATE TYPE "public"."agent_outbox_status" AS ENUM('pending', 'processing', 'delivered');--> statement-breakpoint
+CREATE TABLE "agent_audit_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"seq" bigint GENERATED ALWAYS AS IDENTITY (sequence name "agent_audit_events_seq_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 9223372036854775807 START WITH 1 CACHE 1),
+	"event_type" text NOT NULL,
+	"actor_id" text NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"correlation_id" text NOT NULL,
+	"causation_id" uuid,
+	"payload" jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "agent_audit_events_type_check" CHECK (event_type IN ('agent.enrolled', 'agent.enrollment.replayed'))
+);
+--> statement-breakpoint
+CREATE TABLE "agent_idempotency_fence" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"operation" text NOT NULL,
+	"idempotency_key" text NOT NULL,
+	"actor_id" text NOT NULL,
+	"authorization_scope" text NOT NULL,
+	"payload_digest" text NOT NULL,
+	"replay_mode" text DEFAULT 'actor-bound' NOT NULL,
+	"outcome_agent_id" uuid NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "agent_idempotency_fence_replay_mode_check" CHECK (replay_mode IN ('actor-bound', 'shared'))
+);
+--> statement-breakpoint
+CREATE TABLE "agent_outbox" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"event_id" uuid NOT NULL,
+	"correlation_id" text NOT NULL,
+	"status" "agent_outbox_status" DEFAULT 'pending' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"delivered_at" timestamp with time zone
+);
+--> statement-breakpoint
+ALTER TABLE "agents" ADD COLUMN "harness" text;--> statement-breakpoint
+ALTER TABLE "agents" ADD COLUMN "enrolled_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "agent_audit_events" ADD CONSTRAINT "agent_audit_events_causation_id_agent_audit_events_id_fk" FOREIGN KEY ("causation_id") REFERENCES "public"."agent_audit_events"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_outbox" ADD CONSTRAINT "agent_outbox_event_id_agent_audit_events_id_fk" FOREIGN KEY ("event_id") REFERENCES "public"."agent_audit_events"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "agent_audit_events_seq_idx" ON "agent_audit_events" USING btree ("seq");--> statement-breakpoint
+CREATE INDEX "agent_audit_events_agent_seq_idx" ON "agent_audit_events" USING btree ("agent_id","seq");--> statement-breakpoint
+CREATE INDEX "agent_audit_events_correlation_idx" ON "agent_audit_events" USING btree ("correlation_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "agent_idempotency_fence_operation_key_idx" ON "agent_idempotency_fence" USING btree ("operation","idempotency_key");--> statement-breakpoint
+CREATE UNIQUE INDEX "agent_outbox_event_idx" ON "agent_outbox" USING btree ("event_id");--> statement-breakpoint
+CREATE INDEX "agent_outbox_status_created_idx" ON "agent_outbox" USING btree ("status","created_at");

packages/db/drizzle/meta/_journal.json

@@ -141,6 +141,20 @@
       "when": 1787880918208,
       "tag": "0019_volatile_killraven",
       "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1787963521142,
+      "tag": "0020_special_betty_brant",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1788053011351,
+      "tag": "0021_agent_enrollment",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/agent-enrollment.witness.test.ts

@@ -0,0 +1,412 @@
+/**
+ * Agent enrollment schema witnesses — M4-4a, the schema-level half of the
+ * witness list in docs/plans/2026-08-29-agent-enrollment-command-design.md §5.
+ *
+ * Witnesses the guarantees migration 0021's tables themselves carry: the
+ * event-type CHECK, monotonic per-agent append order (`seq`), deletion-safe
+ * linkage (no foreign key from the events or fence tables into `agents` —
+ * rows survive a legacy CRUD DELETE of the agent), the causation self-FK,
+ * the outbox's FK/uniqueness/status shape, the fence's UNIQUE
+ * (operation, key) and replay-mode CHECK, and the nullable enrollment
+ * columns on `agents` (legacy rows insert without them). The command-level
+ * witnesses (never-echo, same-tx atomicity, replay semantics, correlation,
+ * CLI parity, fail-closed) belong to the M4-4b implementation slice.
+ *
+ * Two legs run the same witness body:
+ *  - PGlite (WASM Postgres): always runs.
+ *  - Real PostgreSQL: runs when DATABASE_URL is set — the binding witness;
+ *    CI migrates ci-postgres before `pnpm test`.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sql } from 'drizzle-orm';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createDb } from './client.js';
+import { createPgliteDb } from './client-pglite.js';
+import { runPgliteMigrations } from './migrate.js';
+import { agentAuditEvents, agentIdempotencyFence, agentOutbox, agents } from './schema.js';
+
+type AnyDb = {
+  db: {
+    insert: (t: unknown) => { values: (v: unknown) => Promise<unknown> };
+    execute: (q: unknown) => Promise<{ rows?: unknown[] } | unknown[]>;
+  };
+  close: () => Promise<void>;
+};
+
+/** Match a constraint failure anywhere along drizzle's cause chain. */
+async function expectViolation(p: Promise<unknown>, re: RegExp, label = ''): Promise<void> {
+  let err: unknown;
+  try {
+    await p;
+  } catch (e) {
+    err = e;
+  }
+  expect(err, label || 'expected the statement to be refused').toBeDefined();
+  const messages: string[] = [];
+  let cur: unknown = err;
+  while (cur instanceof Error) {
+    messages.push(cur.message);
+    cur = (cur as { cause?: unknown }).cause;
+  }
+  expect(messages.join(' | '), label).toMatch(re);
+}
+
+function rows(res: { rows?: unknown[] } | unknown[]): Record<string, unknown>[] {
+  return (Array.isArray(res) ? res : (res.rows ?? [])) as Record<string, unknown>[];
+}
+
+/** Unique per-run prefix so real-PG runs never collide and clean up safely. */
+const T = `agent-e-${randomUUID().slice(0, 8)}`;
+
+type EventInsert = typeof agentAuditEvents.$inferInsert;
+
+function eventRow(overrides: Partial<EventInsert> = {}): EventInsert {
+  return {
+    eventType: 'agent.enrolled',
+    actorId: `${T}-actor`,
+    agentId: randomUUID(),
+    correlationId: `${T}-corr-${randomUUID()}`,
+    payload: {
+      harness: 'claude-code',
+      provider: 'anthropic',
+      name: 'x',
+      credentialMode: 'reference',
+    },
+    ...overrides,
+  };
+}
+
+type FenceInsert = typeof agentIdempotencyFence.$inferInsert;
+
+function fenceRow(overrides: Partial<FenceInsert> = {}): FenceInsert {
+  return {
+    operation: 'agent.enroll',
+    idempotencyKey: `${T}-${randomUUID()}`,
+    actorId: `${T}-actor`,
+    authorizationScope: 'platform-user',
+    payloadDigest: `${T}-digest`,
+    outcomeAgentId: randomUUID(),
+    ...overrides,
+  };
+}
+
+function witnessSuite(getHandle: () => AnyDb): void {
+  const db = () => getHandle().db as unknown as ReturnType<typeof createDb>['db'];
+
+  afterAll(async () => {
+    const d = db();
+    await d.execute(sql`DELETE FROM agent_outbox WHERE correlation_id LIKE ${T + '%'}`);
+    // Caused events first: the causation self-FK is RESTRICT.
+    await d.execute(
+      sql`DELETE FROM agent_audit_events WHERE correlation_id LIKE ${T + '%'} AND causation_id IS NOT NULL`,
+    );
+    await d.execute(sql`DELETE FROM agent_audit_events WHERE correlation_id LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM agent_idempotency_fence WHERE actor_id LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM agents WHERE name LIKE ${T + '%'}`);
+  });
+
+  // ── agents: nullable enrollment columns (no backfill semantics) ────────────
+
+  it('legacy agent rows insert without enrollment columns; enrolled rows carry both', async () => {
+    const legacyId = randomUUID();
+    await db()
+      .insert(agents)
+      .values({
+        id: legacyId,
+        name: `${T}-legacy`,
+        provider: 'anthropic',
+        model: 'claude-fable-5',
+      });
+    const legacy = rows(
+      await db().execute(sql`SELECT harness, enrolled_at FROM agents WHERE id = ${legacyId}`),
+    )[0]!;
+    expect(legacy['harness']).toBeNull();
+    expect(legacy['enrolled_at']).toBeNull();
+
+    const enrolledId = randomUUID();
+    await db()
+      .insert(agents)
+      .values({
+        id: enrolledId,
+        name: `${T}-enrolled`,
+        provider: 'anthropic',
+        model: 'claude-fable-5',
+        harness: 'claude-code',
+        enrolledAt: new Date(),
+      });
+    const enrolled = rows(
+      await db().execute(sql`SELECT harness, enrolled_at FROM agents WHERE id = ${enrolledId}`),
+    )[0]!;
+    expect(enrolled['harness']).toBe('claude-code');
+    expect(enrolled['enrolled_at']).not.toBeNull();
+  });
+
+  // ── agent_audit_events: CHECK, ordering, deletion-safe linkage ─────────────
+
+  it('accepts both declared event types and refuses an undeclared one', async () => {
+    await db()
+      .insert(agentAuditEvents)
+      .values(eventRow({ eventType: 'agent.enrolled' }));
+    await db()
+      .insert(agentAuditEvents)
+      .values(eventRow({ eventType: 'agent.enrollment.replayed' }));
+    await expectViolation(
+      db()
+        .insert(agentAuditEvents)
+        .values(eventRow({ eventType: 'agent.deleted' })),
+      /type_check|violates check/i,
+      'undeclared event type must be refused',
+    );
+  });
+
+  it('assigns strictly increasing seq in insert order for one agent', async () => {
+    const agentId = randomUUID();
+    const c1 = `${T}-seq-1-${randomUUID()}`;
+    const c2 = `${T}-seq-2-${randomUUID()}`;
+    await db()
+      .insert(agentAuditEvents)
+      .values(eventRow({ agentId, correlationId: c1 }));
+    await db()
+      .insert(agentAuditEvents)
+      .values(eventRow({ agentId, eventType: 'agent.enrollment.replayed', correlationId: c2 }));
+    const res = rows(
+      await db().execute(
+        sql`SELECT correlation_id, seq FROM agent_audit_events WHERE agent_id = ${agentId} ORDER BY seq ASC`,
+      ),
+    );
+    expect(res.map((r) => r['correlation_id'])).toEqual([c1, c2]);
+    expect(Number(res[1]!['seq'])).toBeGreaterThan(Number(res[0]!['seq']));
+  });
+
+  it('has no foreign key into agents, and events survive agent deletion', async () => {
+    const fks = rows(
+      await db().execute(sql`
+        SELECT ccu.table_name AS referenced_table
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.constraint_column_usage ccu
+          ON ccu.constraint_name = tc.constraint_name AND ccu.constraint_schema = tc.constraint_schema
+        WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = 'agent_audit_events'
+      `),
+    );
+    // The causation self-FK is the ONLY foreign key on the events table.
+    expect([...new Set(fks.map((r) => r['referenced_table']))]).toEqual(['agent_audit_events']);
+
+    const agentId = randomUUID();
+    await db()
+      .insert(agents)
+      .values({ id: agentId, name: `${T}-doomed`, provider: 'anthropic', model: 'claude-fable-5' });
+    const corr = `${T}-survive-${randomUUID()}`;
+    await db()
+      .insert(agentAuditEvents)
+      .values(eventRow({ agentId, correlationId: corr }));
+    await db().execute(sql`DELETE FROM agents WHERE id = ${agentId}`);
+    const after = rows(
+      await db().execute(
+        sql`SELECT agent_id FROM agent_audit_events WHERE correlation_id = ${corr}`,
+      ),
+    );
+    expect(after).toHaveLength(1);
+    expect(after[0]!['agent_id']).toBe(agentId);
+  });
+
+  it('enforces the causation self-FK and RESTRICTs deleting a cause', async () => {
+    await expectViolation(
+      db()
+        .insert(agentAuditEvents)
+        .values(eventRow({ causationId: randomUUID() })),
+      /foreign key/i,
+      'causation must reference an existing event',
+    );
+    const causeCorr = `${T}-cause-${randomUUID()}`;
+    await db()
+      .insert(agentAuditEvents)
+      .values(eventRow({ correlationId: causeCorr }));
+    const cause = rows(
+      await db().execute(
+        sql`SELECT id FROM agent_audit_events WHERE correlation_id = ${causeCorr}`,
+      ),
+    )[0]!;
+    await db()
+      .insert(agentAuditEvents)
+      .values(
+        eventRow({
+          eventType: 'agent.enrollment.replayed',
+          causationId: cause['id'] as string,
+        }),
+      );
+    await expectViolation(
+      db().execute(sql`DELETE FROM agent_audit_events WHERE id = ${cause['id'] as string}`),
+      /foreign key/i,
+      'a cause with dependent events must not be deletable',
+    );
+  });
+
+  // ── agent_outbox shape ─────────────────────────────────────────────────────
+
+  it('outbox rows require an existing event, one outbox row per event, closed status enum', async () => {
+    await expectViolation(
+      db()
+        .insert(agentOutbox)
+        .values({ eventId: randomUUID(), correlationId: `${T}-corr` }),
+      /foreign key/i,
+      'outbox must reference an existing event',
+    );
+    const corr = `${T}-ob-${randomUUID()}`;
+    await db()
+      .insert(agentAuditEvents)
+      .values(eventRow({ correlationId: corr }));
+    const event = rows(
+      await db().execute(sql`SELECT id FROM agent_audit_events WHERE correlation_id = ${corr}`),
+    )[0]!;
+    const eventId = event['id'] as string;
+    await db().insert(agentOutbox).values({ eventId, correlationId: corr });
+    await expectViolation(
+      db()
+        .insert(agentOutbox)
+        .values({ eventId, correlationId: `${T}-ob2` }),
+      /duplicate key|unique/i,
+      'one outbox record per event',
+    );
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO agent_outbox (event_id, correlation_id, status)
+            VALUES (${eventId}, ${`${T}-ob3`}, 'failed')`,
+      ),
+      /invalid input value for enum|22P02/i,
+      'status outside pending/processing/delivered must be refused',
+    );
+  });
+
+  it('outbox FK RESTRICTs event deletion while the outbox row exists', async () => {
+    const corr = `${T}-obr-${randomUUID()}`;
+    await db()
+      .insert(agentAuditEvents)
+      .values(eventRow({ correlationId: corr }));
+    const event = rows(
+      await db().execute(sql`SELECT id FROM agent_audit_events WHERE correlation_id = ${corr}`),
+    )[0]!;
+    await db()
+      .insert(agentOutbox)
+      .values({ eventId: event['id'] as string, correlationId: corr });
+    await expectViolation(
+      db().execute(sql`DELETE FROM agent_audit_events WHERE id = ${event['id'] as string}`),
+      /foreign key/i,
+    );
+  });
+
+  // ── agent_idempotency_fence: (operation, key) uniqueness, mode CHECK ───────
+
+  it('refuses a duplicate (operation, key) pair but allows the same key under another operation', async () => {
+    const key = `${T}-fence-${randomUUID()}`;
+    await db()
+      .insert(agentIdempotencyFence)
+      .values(fenceRow({ idempotencyKey: key }));
+    await expectViolation(
+      db()
+        .insert(agentIdempotencyFence)
+        .values(fenceRow({ idempotencyKey: key })),
+      /duplicate key|unique/i,
+      'fence uniqueness is (operation, key)',
+    );
+    // Same key, different operation identifier: a distinct fence.
+    await db()
+      .insert(agentIdempotencyFence)
+      .values(fenceRow({ idempotencyKey: key, operation: 'agent.other' }));
+  });
+
+  it('defaults replay mode to actor-bound and refuses an undeclared mode', async () => {
+    const key = `${T}-mode-${randomUUID()}`;
+    await db()
+      .insert(agentIdempotencyFence)
+      .values(fenceRow({ idempotencyKey: key }));
+    const row = rows(
+      await db().execute(
+        sql`SELECT replay_mode FROM agent_idempotency_fence WHERE idempotency_key = ${key}`,
+      ),
+    )[0]!;
+    expect(row['replay_mode']).toBe('actor-bound');
+    await expectViolation(
+      db()
+        .insert(agentIdempotencyFence)
+        .values(fenceRow({ replayMode: 'unbound' as 'actor-bound' })),
+      /replay_mode_check|violates check/i,
+      'a mode outside actor-bound/shared must be refused',
+    );
+  });
+
+  it('fence has no foreign key at all, and rows survive agent deletion', async () => {
+    const fks = rows(
+      await db().execute(sql`
+        SELECT ccu.table_name AS referenced_table
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.constraint_column_usage ccu
+          ON ccu.constraint_name = tc.constraint_name AND ccu.constraint_schema = tc.constraint_schema
+        WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = 'agent_idempotency_fence'
+      `),
+    );
+    expect(fks).toHaveLength(0);
+
+    const agentId = randomUUID();
+    await db()
+      .insert(agents)
+      .values({
+        id: agentId,
+        name: `${T}-fdoomed`,
+        provider: 'anthropic',
+        model: 'claude-fable-5',
+      });
+    const key = `${T}-fsurvive-${randomUUID()}`;
+    await db()
+      .insert(agentIdempotencyFence)
+      .values(fenceRow({ idempotencyKey: key, outcomeAgentId: agentId }));
+    await db().execute(sql`DELETE FROM agents WHERE id = ${agentId}`);
+    const after = rows(
+      await db().execute(
+        sql`SELECT outcome_agent_id FROM agent_idempotency_fence WHERE idempotency_key = ${key}`,
+      ),
+    );
+    expect(after).toHaveLength(1);
+    expect(after[0]!['outcome_agent_id']).toBe(agentId);
+  });
+}
+
+// ── Leg 1: PGlite (always runs — local witness signal) ───────────────────────
+
+describe('agent enrollment schema witnesses — PGlite', () => {
+  let dir: string;
+  let handle: ReturnType<typeof createPgliteDb>;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'agent-enroll-witness-'));
+    handle = createPgliteDb(dir);
+    await runPgliteMigrations(handle);
+  });
+
+  afterAll(async () => {
+    await handle.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  witnessSuite(() => handle as unknown as AnyDb);
+});
+
+// ── Leg 2: real PostgreSQL (binding witness, ci-postgres in CI) ──────────────
+
+const hasPostgres = Boolean(process.env['DATABASE_URL']);
+
+describe.skipIf(!hasPostgres)('agent enrollment schema witnesses — real PostgreSQL', () => {
+  let handle: ReturnType<typeof createDb>;
+
+  beforeAll(() => {
+    handle = createDb(process.env['DATABASE_URL']!);
+  });
+
+  afterAll(async () => {
+    await handle.close();
+  });
+
+  witnessSuite(() => handle as unknown as AnyDb);
+});

packages/db/src/hierarchy-schema.witness.test.ts

@@ -44,7 +44,7 @@ type AnyDb = {
 
 /** Column allowlist — the exact declared sets of §2/§3. Nothing else. */
 const COLUMN_ALLOWLIST: Record<string, string[]> = {
-  companies: ['id', 'name', 'slug', 'created_at', 'updated_at'],
+  companies: ['id', 'name', 'slug', 'visibility', 'created_at', 'updated_at'],
   estates: ['id', 'name', 'slug', 'company_id'],
   platform_projects: ['id', 'name', 'slug', 'estate_id'],
   workspaces: ['id', 'name', 'slug', 'platform_project_id'],
@@ -377,7 +377,61 @@ function witnessSuite(getHandle: () => AnyDb): void {
     // Control: same subject and target with a different role is a new grant.
     await db()
       .insert(hierarchyGrants)
-      .values({ userId: userA, companyId, role: `${T}-other-role`, grantedBy: userA });
+      .values({ userId: userA, companyId, role: 'member', grantedBy: userA });
+  });
+
+  // ── §2.6 role vocabulary CHECK ─────────────────────────────────────────────
+
+  it('refuses a grant role outside the ratified vocabulary, accepts each ratified role', async () => {
+    await expectViolation(
+      db()
+        .insert(hierarchyGrants)
+        .values({ userId: userB, companyId, role: 'superuser', grantedBy: userA }),
+      /check constraint/i,
+    );
+    // Serialized namespaced forms are storage-invalid too: rows hold bare roles.
+    await expectViolation(
+      db()
+        .insert(hierarchyGrants)
+        .values({ userId: userB, companyId, role: 'hierarchy:owner', grantedBy: userA }),
+      /check constraint/i,
+    );
+    for (const role of ['viewer', 'member', 'owner'] as const) {
+      await db()
+        .insert(hierarchyGrants)
+        .values({ userId: userB, estateId, role, grantedBy: userA });
+    }
+    await db().execute(
+      sql`DELETE FROM hierarchy_grants WHERE user_id = ${userB} AND estate_id = ${estateId}`,
+    );
+  });
+
+  // ── §2.8 visibility column ─────────────────────────────────────────────────
+
+  it('defaults companies.visibility to private and refuses values outside the class', async () => {
+    const visId = randomUUID();
+    await db().execute(
+      sql`INSERT INTO companies (id, name, slug) VALUES (${visId}, 'Vis', ${T + '-vis'})`,
+    );
+    const res = rows(await db().execute(sql`SELECT visibility FROM companies WHERE id = ${visId}`));
+    expect(res[0]!['visibility']).toBe('private');
+    await db().execute(
+      sql`INSERT INTO companies (id, name, slug, visibility) VALUES (${randomUUID()}, 'Vis D', ${T + '-vis-d'}, 'directory')`,
+    );
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO companies (id, name, slug, visibility) VALUES (${randomUUID()}, 'Vis X', ${T + '-vis-x'}, 'public')`,
+      ),
+      /check constraint/i,
+    );
+    await expectViolation(
+      db().execute(sql`UPDATE companies SET visibility = 'hidden' WHERE id = ${visId}`),
+      /check constraint/i,
+    );
+    await expectViolation(
+      db().execute(sql`UPDATE companies SET visibility = NULL WHERE id = ${visId}`),
+      /null value|not-null/i,
+    );
   });
 
   // ── §6.1 NOT NULLs ─────────────────────────────────────────────────────────
@@ -391,7 +445,7 @@ function witnessSuite(getHandle: () => AnyDb): void {
     );
     await expectViolation(
       db().execute(
-        sql`INSERT INTO hierarchy_grants (user_id, company_id, role, granted_by) VALUES (${userA}, ${companyId}, 'x', NULL)`,
+        sql`INSERT INTO hierarchy_grants (user_id, company_id, role, granted_by) VALUES (${userA}, ${companyId}, 'viewer', NULL)`,
       ),
       /null value|not-null/i,
     );

packages/db/src/hierarchy-writer-coverage.test.ts

@@ -135,9 +135,9 @@
  *     production code is anomalous and review-visible; that blind spot is
  *     accepted as a residual, not closed.
  *
- * The writer allowlist names hierarchy command/repository modules ONLY. It is
- * empty today: the hierarchy command family (M4-1b-ii) has not landed, so no
- * production module may write the class tables. The infrastructure register
+ * The writer allowlist names hierarchy command/repository modules ONLY. Its
+ * single entry is the M4-1b-ii hierarchy command repository — the sole
+ * production module permitted to write the class tables. The infrastructure register
  * holds legitimate non-hierarchy raw execution; registered modules are exempt
  * from prong (iii) only — prongs (i) and (ii) apply to them with no
  * exemption, and no registered module may appear on the writer allowlist.
@@ -181,13 +181,15 @@ const CLASS_TABLES = [
 
 /**
  * Writer allowlist (§6.3b): hierarchy command/repository modules only.
- * EMPTY until the hierarchy command family lands (M4-1b-ii; M4-1b-i ships
- * only the audit/outbox machinery, which writes no class table). Adding a module
- * here is a contract-conformance decision reviewed under §5.1 — the module
- * must be part of the Gateway hierarchy command path, and it must not export
- * a function that executes caller-supplied SQL.
+ * Adding a module here is a contract-conformance decision reviewed under
+ * §5.1 — the module must be part of the Gateway hierarchy command path, and
+ * it must not export a function that executes caller-supplied SQL.
  */
-const WRITER_ALLOWLIST: string[] = [];
+const WRITER_ALLOWLIST: string[] = [
+  // The hierarchy command repository (M4-1b-ii): the sole class-table
+  // writer; every mutation is audited on its own transaction (§5.2).
+  'apps/gateway/src/hierarchy/hierarchy.repository.ts',
+];
 
 /**
  * Infrastructure register: closed enumeration of legitimate non-hierarchy raw

packages/db/src/schema.ts

@@ -302,6 +302,11 @@ export const agents = pgTable(
     skills: jsonb('skills').$type<string[]>(),
     isSystem: boolean('is_system').notNull().default(false),
     config: jsonb('config'),
+    // Enrollment (M4-4, docs/plans/2026-08-29-agent-enrollment-command-design.md §4).
+    // NULL on both marks a legacy (non-enrolled) row; no backfill — enrollment
+    // is a fact the rank-4 command creates, not one to invent for existing rows.
+    harness: text('harness'),
+    enrolledAt: timestamp('enrolled_at', { withTimezone: true }),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
   },
@@ -1063,13 +1068,24 @@ export const federationEnrollmentTokens = pgTable('federation_enrollment_tokens'
 // command family only (§5.1), enforced by the writer-coverage assertion
 // (§6.3b) — do not add writers outside that allowlist.
 
-export const companies = pgTable('companies', {
-  id: uuid('id').primaryKey().defaultRandom(),
-  name: text('name').notNull(),
-  slug: text('slug').notNull().unique(),
-  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-});
+/** Company visibility classes (contract 1 §2.8, Ruling 4b): 'private' is the
+ * only creatable class (§5.5 — creation carries no visibility argument);
+ * 'directory' discloses existence/name/slug to all users and is entered only
+ * through the admin-gated visibility-change command. */
+export const COMPANY_VISIBILITY = ['private', 'directory'] as const;
+
+export const companies = pgTable(
+  'companies',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    name: text('name').notNull(),
+    slug: text('slug').notNull().unique(),
+    visibility: text('visibility').notNull().default('private'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  () => [check('companies_visibility_check', sql`visibility IN ('private', 'directory')`)],
+);
 
 export const estates = pgTable(
   'estates',
@@ -1110,6 +1126,10 @@ export const workspaces = pgTable(
   (t) => [unique('workspaces_platform_project_slug_uniq').on(t.platformProjectId, t.slug)],
 );
 
+/** Grant role vocabulary (contract 2 §2): totally ordered, viewer ⊂ member ⊂
+ * owner. Order in this tuple IS the ordering — index = strength. */
+export const HIERARCHY_GRANT_ROLES = ['viewer', 'member', 'owner'] as const;
+
 export const hierarchyGrants = pgTable(
   'hierarchy_grants',
   {
@@ -1126,7 +1146,8 @@ export const hierarchyGrants = pgTable(
     platformProjectId: uuid('platform_project_id').references(() => platformProjects.id, {
       onDelete: 'cascade',
     }),
-    // Role vocabulary and its CHECK constraint are contract 2 §2 (M4-2).
+    // Role vocabulary per contract 2 §2: exactly viewer ⊂ member ⊂ owner,
+    // totally ordered; CHECK below closes the column to that vocabulary.
     role: text('role').notNull(),
     grantedBy: text('granted_by')
       .notNull()
@@ -1134,6 +1155,7 @@ export const hierarchyGrants = pgTable(
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   },
   (t) => [
+    check('hierarchy_grants_role_check', sql`role IN ('viewer', 'member', 'owner')`),
     check('hierarchy_grants_subject_check', sql`num_nonnulls(user_id, team_id) = 1`),
     check(
       'hierarchy_grants_target_check',
@@ -1170,6 +1192,7 @@ export const HIERARCHY_AUDIT_VERBS = [
   'create',
   'rename',
   'transfer',
+  'visibility_change',
   'delete',
   'grant_create',
   'grant_change',
@@ -1220,7 +1243,7 @@ export const hierarchyAuditEvents = pgTable(
     index('hierarchy_audit_events_correlation_idx').on(t.correlationId),
     check(
       'hierarchy_audit_events_verb_check',
-      sql`verb IN ('create', 'rename', 'transfer', 'delete', 'grant_create', 'grant_change', 'grant_revoke')`,
+      sql`verb IN ('create', 'rename', 'transfer', 'visibility_change', 'delete', 'grant_create', 'grant_change', 'grant_revoke')`,
     ),
     check(
       'hierarchy_audit_events_target_kind_check',
@@ -1261,3 +1284,109 @@ export const hierarchyOutbox = pgTable(
     index('hierarchy_outbox_status_created_idx').on(t.status, t.createdAt),
   ],
 );
+
+// ---------------------------------------------------------------------------
+// Agent enrollment (M4-4) — rank-4 command family audit/outbox/fence stores.
+// Design: docs/plans/2026-08-29-agent-enrollment-command-design.md §4.
+// Pattern reuse from the hierarchy audit/outbox pair, separate store. Audit
+// rows reference the agent by snapshot id, deliberately with NO FK, so audit
+// history survives agent deletion through the legacy CRUD DELETE path.
+// Idempotency for this family lives in agent_idempotency_fence (contract 3
+// §4.3 envelope, ratified into contract 5 §4 via contract 3 §7 item 4) — the
+// audit and outbox tables carry no idempotency key of their own.
+
+export const AGENT_AUDIT_EVENT_TYPES = [
+  // Semantic mutation event of agent.enroll.
+  'agent.enrolled',
+  // Non-mutation access class: a passing idempotent replay appends this and
+  // nothing else (accessing principal, current correlation id, fence-row
+  // reference in the payload).
+  'agent.enrollment.replayed',
+] as const;
+
+export const agentAuditEvents = pgTable(
+  'agent_audit_events',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // Global append order; per-agent ordering is a filter on agent_id ordered
+    // by seq.
+    seq: bigint('seq', { mode: 'number' }).notNull().generatedAlwaysAsIdentity(),
+    eventType: text('event_type').notNull(),
+    // No FK: audit events outlive every principal and every target.
+    actorId: text('actor_id').notNull(),
+    agentId: uuid('agent_id').notNull(),
+    correlationId: text('correlation_id').notNull(),
+    causationId: uuid('causation_id').references((): AnyPgColumn => agentAuditEvents.id, {
+      onDelete: 'restrict',
+    }),
+    // Immutable snapshot at event time; never carries credential material
+    // (§3.1 rule 1: actor, agent id, harness, provider, name, credentialMode).
+    payload: jsonb('payload').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('agent_audit_events_seq_idx').on(t.seq),
+    index('agent_audit_events_agent_seq_idx').on(t.agentId, t.seq),
+    index('agent_audit_events_correlation_idx').on(t.correlationId),
+    check(
+      'agent_audit_events_type_check',
+      sql`event_type IN ('agent.enrolled', 'agent.enrollment.replayed')`,
+    ),
+  ],
+);
+
+export const agentOutboxStatusEnum = pgEnum('agent_outbox_status', [
+  'pending',
+  'processing',
+  'delivered',
+]);
+
+export const agentOutbox = pgTable(
+  'agent_outbox',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // FK into the append-only events table: never dangles, RESTRICT is safe.
+    eventId: uuid('event_id')
+      .notNull()
+      .references(() => agentAuditEvents.id, { onDelete: 'restrict' }),
+    correlationId: text('correlation_id').notNull(),
+    status: agentOutboxStatusEnum('status').notNull().default('pending'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+    deliveredAt: timestamp('delivered_at', { withTimezone: true }),
+  },
+  (t) => [
+    uniqueIndex('agent_outbox_event_idx').on(t.eventId),
+    index('agent_outbox_status_created_idx').on(t.status, t.createdAt),
+  ],
+);
+
+// Contract 3 §4.3 fence shape. Uniqueness is (operation, key); the recorded
+// replay mode is always 'actor-bound' for this family (`shared` is seed-only
+// and refused at validation — design §3.1), but the column keeps the ratified
+// envelope shape and serves the mode-mismatch collision check. The payload
+// digest input EXCLUDES the credential value (design §3.1 rule 5).
+export const agentIdempotencyFence = pgTable(
+  'agent_idempotency_fence',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    operation: text('operation').notNull(),
+    idempotencyKey: text('idempotency_key').notNull(),
+    // No FK: fence rows outlive principals, mirroring the audit tables.
+    actorId: text('actor_id').notNull(),
+    authorizationScope: text('authorization_scope').notNull(),
+    payloadDigest: text('payload_digest').notNull(),
+    replayMode: text('replay_mode').notNull().default('actor-bound'),
+    // Committed-outcome reference (the enrolled agent's id). Snapshot value,
+    // no FK: the fence must keep answering replays after a legacy DELETE.
+    outcomeAgentId: uuid('outcome_agent_id').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('agent_idempotency_fence_operation_key_idx').on(t.operation, t.idempotencyKey),
+    check(
+      'agent_idempotency_fence_replay_mode_check',
+      sql`replay_mode IN ('actor-bound', 'shared')`,
+    ),
+  ],
+);

packages/mosaic/framework/fleet/bin/mosaic

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# mosaic — fleet launcher (shipped-first, split-home safe).
+#
+# T110 / P5-RM-009 stack side. Carries the T106 brain launcher contract
+# (shipped-first, worktree dev opt-in, OFF pass-through, typed failure) with
+# one split-home correction: the SHIPPED npm mosaic is resolved from the real
+# user's home (passwd database), never from $HOME. Under split-home seat
+# layouts HOME is a seat home: it carries no npm prefix, and a
+# $HOME/.npm-global there would be a plantable descriptor, so the $HOME
+# candidate is consulted only when the passwd lookup itself fails, and then
+# only with a full symlink-component refusal (secure descriptor traversal).
+#
+# Contract:
+#   1. SHIPPED npm mosaic is the default. Candidate order:
+#        a. <real-home>/.npm-global/bin/mosaic — real home from the passwd
+#           database. The final component may be npm's own bin symlink into
+#           lib/node_modules; that indirection is npm's layout, not a plant.
+#        b. $HOME/.npm-global/bin/mosaic — ONLY when the passwd lookup
+#           fails, and then only when the candidate is a trusted-shape
+#           absolute path: relative HOME and parent-escape (..) components
+#           are refused outright, and every remaining component must be a
+#           non-symlink (secure descriptor traversal). Refused candidates
+#           are never executed.
+#   2. Worktree build is DEV OPT-IN: used only when MOSAIC_CLI_WORKTREE is
+#      explicitly set. Health-checked via --version; ANY doubt (absent,
+#      unreadable, or failing) falls back to the shipped npm mosaic with a
+#      warning on stderr. With no environment set, worktree candidates are
+#      never consulted — stale worktree builds cannot regain precedence.
+#   3. MOSAIC_FLEET_CLI_OFF keeps its pass-through semantics: set (any
+#      value) forces pure pass-through. The dev path is not consulted even
+#      when MOSAIC_CLI_WORKTREE is also set.
+#   4. Typed failure: with no runnable candidate the launcher prints one
+#      stderr line naming what was checked and exits 127.
+#   5. NEVER writes to the mosaic home or the npm prefix. Deployment to the
+#      fleet goes through the real channel (PR to next -> mosaic update).
+#
+# Env:
+#   MOSAIC_CLI_WORKTREE  dev opt-in: path to a stack worktree whose
+#                        packages/mosaic/dist/cli.js is used (health-checked,
+#                        shipped fallback on doubt)
+#   MOSAIC_FLEET_CLI_OFF set (any value) to force pure pass-through
+#
+# Component walk note: the descriptor guard splits on "/" without quoting so
+# multi-byte HOME paths with spaces are not supported for the FALLBACK
+# candidate; the passwd candidate needs no walk (trusted derivation).
+
+set -u
+
+fail() {
+    echo "mosaic: $*" >&2
+    exit 127
+}
+
+# Real user home from the passwd database (HOME-independent).
+real_home() {
+    getent passwd "$(id -u)" 2>/dev/null | cut -d: -f6
+}
+
+# True when any component of an ABSOLUTE candidate path is a symlink. Only
+# ever called after fallback_candidate_usable's absolute-shape check.
+path_has_symlink_component() {
+    local path="$1" dir base acc="" part
+    dir="$(dirname -- "$path")"
+    base="$(basename -- "$path")"
+    local IFS='/'
+    for part in $dir; do
+        acc="$acc/$part"
+        [ -L "$acc" ] && return 0
+    done
+    [ -L "$dir/$base" ] && return 0
+    return 1
+}
+
+# Reject the untrusted $HOME fallback candidate unless it is a trusted-shape
+# absolute path: absolute, no parent-escape (..) components, and no symlink
+# components anywhere on the path. Every rejection is named on stderr so the
+# typed failure explains itself. This is the launcher's descriptor guard; the
+# suite's mutation control (guard bypassed) must plant-exec, proving the guard
+# is what stands between a hostile HOME and code execution.
+fallback_candidate_usable() {
+    local candidate="$1"
+    case "$candidate" in
+        /*) ;;
+        *)
+            echo "mosaic: refusing \$HOME candidate $candidate: relative path is untrusted without a passwd home" >&2
+            return 1
+            ;;
+    esac
+    if printf '%s' "$candidate" | grep -qE '(^|/)\.\.(/|$)'; then
+        echo "mosaic: refusing \$HOME candidate $candidate: parent-escape component" >&2
+        return 1
+    fi
+    if path_has_symlink_component "$candidate"; then
+        echo "mosaic: refusing \$HOME candidate $candidate: symlink component (untrusted without a passwd home)" >&2
+        return 1
+    fi
+    return 0
+}
+
+# Print shipped candidates in contract order. Refusals are reported on stderr
+# so the typed failure names the cause.
+shipped_candidates() {
+    local rh home_candidate
+    rh="$(real_home)"
+    if [ -n "$rh" ]; then
+        printf '%s\n' "$rh/.npm-global/bin/mosaic"
+        return 0
+    fi
+    # passwd lookup failed: the only fallback is $HOME, descriptor-guarded.
+    if [ -n "${HOME:-}" ]; then
+        home_candidate="$HOME/.npm-global/bin/mosaic"
+        if fallback_candidate_usable "$home_candidate"; then
+            printf '%s\n' "$home_candidate"
+        fi
+    fi
+    return 0
+}
+
+resolve_shipped() {
+    local candidate
+    while IFS= read -r candidate; do
+        [ -n "$candidate" ] || continue
+        if [ -x "$candidate" ]; then
+            printf '%s\n' "$candidate"
+            return 0
+        fi
+    done < <(shipped_candidates)
+    return 1
+}
+
+# Dev opt-in only: an explicit MOSAIC_CLI_WORKTREE reaches the worktree build,
+# and pure pass-through (MOSAIC_FLEET_CLI_OFF) outranks it.
+if [ -n "${MOSAIC_CLI_WORKTREE:-}" ] && [ -z "${MOSAIC_FLEET_CLI_OFF:-}" ]; then
+    CLI="$MOSAIC_CLI_WORKTREE/packages/mosaic/dist/cli.js"
+    if [ -r "$CLI" ]; then
+        if v="$(node "$CLI" --version 2>/dev/null)" && [ -n "$v" ]; then
+            exec node "$CLI" "$@"
+        fi
+        echo "mosaic: worktree build at $CLI failed its health check; using shipped npm mosaic" >&2
+    else
+        echo "mosaic: worktree build at $CLI absent or unreadable; using shipped npm mosaic" >&2
+    fi
+fi
+
+SHIPPED="$(resolve_shipped)" || true
+if [ -n "${SHIPPED:-}" ]; then
+    exec "$SHIPPED" "$@"
+fi
+
+fail "no runnable CLI (shipped npm mosaic absent from the passwd-home npm prefix and \$HOME; worktree build requires MOSAIC_CLI_WORKTREE)"

packages/mosaic/framework/fleet/bin/test-mosaic-launcher.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# Hermetic suite for the fleet/bin/mosaic launcher (T110 / P5-RM-009).
+#
+# Arms cover the plan acceptance: split-home shipped-first positive, typed
+# failure on missing candidates, stale-worktree non-precedence, OFF
+# pass-through, and secure-descriptor refusal on the untrusted $HOME
+# fallback. No network, no real npm install, no node package build: the
+# "shipped mosaic" is a stub script and getent is PATH-stubbed (set
+# GETENT_STUB=fail to make the passwd lookup fail, exercising the guarded
+# $HOME fallback).
+set -euo pipefail
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
+LAUNCHER="$SCRIPT_DIR/mosaic"
+
+fail() {
+    echo "FAIL: $*" >&2
+    exit 1
+}
+
+[ -f "$LAUNCHER" ] || fail "missing launcher"
+[ -x "$LAUNCHER" ] || fail "launcher is not executable"
+bash -n "$LAUNCHER" || fail "launcher fails bash -n"
+
+WORK=$(mktemp -d)
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+REAL_HOME="$WORK/real-home"
+SEAT_HOME="$WORK/seat-home"
+STUB_BIN="$WORK/stub-bin"
+mkdir -p "$REAL_HOME/.npm-global/bin" "$SEAT_HOME" "$STUB_BIN"
+
+cat >"$REAL_HOME/.npm-global/bin/mosaic" <<'SH'
+#!/bin/sh
+echo "0.0.0-shipped-stub"
+SH
+chmod +x "$REAL_HOME/.npm-global/bin/mosaic"
+
+# PATH-stubbed getent: reports the real home for the current uid, unless
+# GETENT_STUB=fail is in the launcher environment (exercises the guarded
+# $HOME fallback path).
+cat >"$STUB_BIN/getent" <<SH
+#!/bin/sh
+if [ "\${GETENT_STUB:-}" = "fail" ]; then exit 2; fi
+if [ "\$1" = "passwd" ]; then
+    echo "stub:x:$(id -u):$(id -g):stub:$REAL_HOME:/bin/sh"
+    exit 0
+fi
+exit 2
+SH
+chmod +x "$STUB_BIN/getent"
+
+run_launcher() { # run_launcher <home> [VAR=value ...] -- [args...]
+    local home="$1"; shift
+    [ "${1:-}" = "--" ] && shift
+    env -i PATH="$STUB_BIN:/usr/bin:/bin" HOME="$home" TERM="${TERM:-dumb}" "$LAUNCHER" "$@"
+}
+
+# A1 — acceptance 1: split-home positive. HOME is an empty seat home; the
+# shipped mosaic resolves through the passwd real home.
+out="$(printf '' | run_launcher "$SEAT_HOME" -- --version)"
+[ "$out" = "0.0.0-shipped-stub" ] || fail "A1 split-home positive: got '$out', want shipped stub version"
+
+# A3 — acceptance 3: a stale worktree build is NEVER consulted without the
+# explicit opt-in, even when a worktree exists on disk.
+WT="$WORK/stale-wt"
+mkdir -p "$WT/packages/mosaic/dist"
+printf 'console.log("0.0.0-stale-worktree")\n' >"$WT/packages/mosaic/dist/cli.js"
+out="$(printf '' | run_launcher "$SEAT_HOME" -- --version)"
+[ "$out" = "0.0.0-shipped-stub" ] || fail "A3 stale worktree regained precedence without opt-in: got '$out'"
+
+# A2 (opt-in healthy) — explicit MOSAIC_CLI_WORKTREE reaches the worktree.
+out="$(printf '' | env MOSAIC_CLI_WORKTREE="$WT" HOME="$SEAT_HOME" PATH="$STUB_BIN:/usr/bin:/bin" "$LAUNCHER" --version)"
+[ "$out" = "0.0.0-stale-worktree" ] || fail "A2 opt-in worktree not used: got '$out'"
+
+# A2b (opt-in unhealthy) — absent dist falls back to shipped with a warning.
+out2="$(printf '' | env MOSAIC_CLI_WORKTREE="$WORK/empty-wt" HOME="$SEAT_HOME" PATH="$STUB_BIN:/usr/bin:/bin" "$LAUNCHER" --version 2>/dev/null)"
+[ "$out2" = "0.0.0-shipped-stub" ] || fail "A2b unhealthy worktree fallback output: '$out2'"
+err2="$(printf '' | env MOSAIC_CLI_WORKTREE="$WORK/empty-wt" HOME="$SEAT_HOME" PATH="$STUB_BIN:/usr/bin:/bin" "$LAUNCHER" --version 2>&1 >/dev/null)"
+case "$err2" in *"absent or unreadable"*|*"health check"*) ;; *) fail "A2b unhealthy worktree fallback warning missing: '$err2'" ;; esac
+
+# A4 — OFF pass-through: worktree opt-in is ignored when OFF is set.
+out="$(printf '' | env MOSAIC_FLEET_CLI_OFF=1 MOSAIC_CLI_WORKTREE="$WT" HOME="$SEAT_HOME" PATH="$STUB_BIN:/usr/bin:/bin" "$LAUNCHER" --version)"
+[ "$out" = "0.0.0-shipped-stub" ] || fail "A4 OFF did not force pass-through: got '$out'"
+
+# A5 — acceptance 4: typed failure when no candidate exists (passwd lookup
+# fails, seat home carries no npm prefix). Expect 127 + documented message.
+set +e
+err="$(printf '' | env GETENT_STUB=fail HOME="$SEAT_HOME" PATH="$STUB_BIN:/usr/bin:/bin" "$LAUNCHER" --version 2>&1 >/dev/null)"
+rc=$?
+set -e
+[ "$rc" = "127" ] || fail "A5 typed failure rc: got $rc, want 127"
+case "$err" in *"no runnable CLI"*) ;; *) fail "A5 typed failure message missing: '$err'" ;; esac
+
+# A6 — secure descriptor traversal, ABSOLUTE symlink plant (corrected per
+# rev-code-02 B3: the symlink points at $PLANT/.npm-global so the candidate
+# resolves EXACTLY to the planted executable). passwd lookup fails and a
+# symlink-planted $HOME/.npm-global is refused without execution.
+PLANT="$WORK/planted-target"
+mkdir -p "$PLANT/.npm-global/bin"
+cat >"$PLANT/.npm-global/bin/mosaic" <<SH
+#!/bin/sh
+touch "$WORK/planted-sentinel"
+echo "0.0.0-planted"
+SH
+chmod +x "$PLANT/.npm-global/bin/mosaic"
+ln -s "$PLANT/.npm-global" "$SEAT_HOME/.npm-global"
+set +e
+err="$(printf '' | env GETENT_STUB=fail HOME="$SEAT_HOME" PATH="$STUB_BIN:/usr/bin:/bin" "$LAUNCHER" --version 2>&1)"
+rc=$?
+set -e
+[ "$rc" = "127" ] || fail "A6 planted descriptor was followed (rc $rc, out '$err')"
+case "$err" in *"symlink component"*) ;; *) fail "A6 refusal diagnostic missing: '$err'" ;; esac
+[ ! -e "$WORK/planted-sentinel" ] || fail "A6 planted mosaic EXECUTED"
+
+# A6b — mutation control (rev-code-02 B3): a copy of the launcher with the
+# descriptor guard bypassed MUST execute the plant under the identical hostile
+# arm. If the mutant stays clean, the plant path is wrong and A6 proves
+# nothing.
+MUTANT="$WORK/mutant-mosaic"
+sed 's/if fallback_candidate_usable "\$home_candidate"; then/if true; then/' "$LAUNCHER" >"$MUTANT"
+chmod +x "$MUTANT"
+[ "$(grep -c 'if true; then' "$MUTANT")" -eq 1 ] || fail "A6b mutant not created (guard call not replaced)"
+set +e
+mout="$(printf '' | env GETENT_STUB=fail HOME="$SEAT_HOME" PATH="$STUB_BIN:/usr/bin:/bin" "$MUTANT" --version 2>&1)"
+mrc=$?
+set -e
+[ "$mrc" = "0" ] || fail "A6b mutant did not execute the plant (rc $mrc, out '$mout') - A6 proves nothing"
+[ -e "$WORK/planted-sentinel" ] || fail "A6b mutant ran but sentinel absent - plant path wrong, A6 proves nothing"
+
+# A7 — relative-HOME hostile arm (rev-code-02 B2): a relative HOME whose name
+# is a symlink in the launcher CWD must be refused outright, never resolved
+# against the working directory.
+CWD_SANDBOX="$WORK/cwd-sandbox"
+REL_PLANT="$WORK/relative-plant"
+mkdir -p "$CWD_SANDBOX" "$REL_PLANT/.npm-global/bin"
+cat >"$REL_PLANT/.npm-global/bin/mosaic" <<SH
+#!/bin/sh
+touch "$WORK/relative-sentinel"
+echo "0.0.0-relative-planted"
+SH
+chmod +x "$REL_PLANT/.npm-global/bin/mosaic"
+ln -s "$REL_PLANT" "$CWD_SANDBOX/relative-home"
+set +e
+rout="$(cd "$CWD_SANDBOX" && printf '' | env GETENT_STUB=fail HOME="relative-home" PATH="$STUB_BIN:/usr/bin:/bin" "$LAUNCHER" --version 2>&1)"
+rrc=$?
+set -e
+[ "$rrc" = "127" ] || fail "A7 relative HOME was followed (rc $rrc, out '$rout')"
+case "$rout" in *"relative path"*) ;; *) fail "A7 relative-refusal diagnostic missing: '$rout'" ;; esac
+[ ! -e "$WORK/relative-sentinel" ] || fail "A7 relative plant EXECUTED"
+
+# A7b — mutation control for the absolute-shape check: the same mutant (guard
+# bypassed) MUST execute the relative plant under the identical arm.
+set +e
+rmout="$(cd "$CWD_SANDBOX" && printf '' | env GETENT_STUB=fail HOME="relative-home" PATH="$STUB_BIN:/usr/bin:/bin" "$MUTANT" --version 2>&1)"
+rmrc=$?
+set -e
+[ "$rmrc" = "0" ] || fail "A7b mutant did not execute the relative plant (rc $rmrc, out '$rmout') - A7 proves nothing"
+[ -e "$WORK/relative-sentinel" ] || fail "A7b mutant ran but relative sentinel absent - arm wrong, A7 proves nothing"
+
+# A8 — parent-escape hostile arm (rev-code-02 delta, B2 remains): an absolute
+# HOME containing a literal '..' component must be refused by the
+# parent-escape check — the traversal would otherwise land on a planted tree
+# OUTSIDE the seat home with no symlink involved.
+ESC_BASE="$WORK/escape-base"
+ESC_TARGET="$WORK/escape-target"
+mkdir -p "$ESC_BASE" "$ESC_TARGET/.npm-global/bin"
+cat >"$ESC_TARGET/.npm-global/bin/mosaic" <<SH
+#!/bin/sh
+touch "$WORK/escape-sentinel"
+echo "0.0.0-escape-planted"
+SH
+chmod +x "$ESC_TARGET/.npm-global/bin/mosaic"
+set +e
+eout="$(printf '' | env GETENT_STUB=fail HOME="$ESC_BASE/../escape-target" PATH="$STUB_BIN:/usr/bin:/bin" "$LAUNCHER" --version 2>&1)"
+erc=$?
+set -e
+[ "$erc" = "127" ] || fail "A8 parent-escape HOME was followed (rc $erc, out '$eout')"
+case "$eout" in *"parent-escape component"*) ;; *) fail "A8 parent-escape diagnostic missing: '$eout'" ;; esac
+[ ! -e "$WORK/escape-sentinel" ] || fail "A8 escape plant EXECUTED"
+
+# A8b — mutation control: the guard-bypassed copy MUST execute the parent-
+# escape plant under the identical arm (sentinel present, rc 0), proving the
+# parent-escape check is what stands.
+set +e
+emout="$(printf '' | env GETENT_STUB=fail HOME="$ESC_BASE/../escape-target" PATH="$STUB_BIN:/usr/bin:/bin" "$MUTANT" --version 2>&1)"
+emrc=$?
+set -e
+[ "$emrc" = "0" ] || fail "A8b mutant did not execute the escape plant (rc $emrc, out '$emout') - A8 proves nothing"
+[ -e "$WORK/escape-sentinel" ] || fail "A8b mutant ran but escape sentinel absent - arm wrong, A8 proves nothing"
+
+echo "mosaic launcher suite: all arms passed"

packages/mosaic/framework/framework-manifest.txt

@@ -46,7 +46,12 @@ systemd/**
 templates/**
 tools/**
 # Fleet: only the framework-seeded fleet subtrees are framework-owned.
+# fleet/bin is exact-entry on purpose (T110 B1): the estate's fleet/bin carries
+# operator-owned executables this package does not ship; a subtree glob here
+# would make keep-mode update prune them.
 fleet/README.md
+fleet/bin/mosaic
+fleet/bin/test-mosaic-launcher.sh
 fleet/examples/**
 fleet/profiles/**
 fleet/roles/**

packages/mosaic/framework/tools/git/git-credential-mosaic

@@ -1,220 +1,64 @@
-#!/bin/bash
-# git-credential-mosaic — git credential helper. Resolves a Gitea token from the
-# Mosaic credential store at runtime so remote URLs never embed secrets.
+#!/usr/bin/python3
+# git-credential-mosaic — production entrypoint (P0-SEC R4, rev-code-02 B1).
 #
-# Install (one-time, per clone or globally):
-#   git config credential.helper "$HOME/.config/mosaic/tools/git/git-credential-mosaic"
+# WHY THIS IS NOT BASH: three review rounds falsified every in-bash startup
+# guard. A non-interactive bash sources $BASH_ENV and imports exported
+# functions BEFORE the first script line, so read(), unset(), exit(),
+# declare(), printf() — every callable — can be shadows that fake the
+# ancestry, defeat the scrub, or forge diagnostics (rev-code-02 probes 1 and
+# 2, artifacts fc49e9d9 lineage). No in-language dispatch survives that.
 #
-# Per-agent identity (Gate-16 author != reviewer separation):
-#   git config mosaic.gitIdentity <agent-id>   # per-worktree, persists on disk
-#   # or: export MOSAIC_GIT_IDENTITY=<agent-id>
+# This entrypoint is unshapable at the bash level: python does not read
+# BASH_ENV and imports no bash functions, and the interpreter is pinned by
+# absolute shebang (no PATH resolution). It builds the child environment BY
+# ALLOWLIST and execve's the bash implementation directly — the child bash
+# starts with no BASH_ENV, no BASH_FUNC_*, no SHELLOPTS/BASHOPTS, and exactly
+# the variables the credential protocol needs. stdin/stdout/stderr and argv
+# pass through untouched.
 #
-# ── WHY THIS FAILS CLOSED ──────────────────────────────────────────────────────
-# This helper used to end by emitting the shared account's token for any request
-# it could not resolve to an identity. A seat with no identity, or with an
-# identity whose token was never provisioned, therefore received the most
-# privileged credential configured on the host — silently, and indistinguishably
-# from correct operation. Every record it then created (commit, push, PR, review)
-# was attributed to that shared account, so author != reviewer separation was
-# unenforceable and the true actor was unrecoverable after the fact.
-#
-# Under-provisioning must fail loudly, not impersonate. A refused git operation
-# is recoverable in one command; a merged pull request attributed to the wrong
-# principal is not.
-#
-# ── CONTRACT ───────────────────────────────────────────────────────────────────
-#   identity : MOSAIC_GIT_IDENTITY  >  git config mosaic.gitIdentity  >  the
-#              username git supplies on stdin
-#   store    : chosen by what the identity IS, with no precedence and no
-#              cross-store fallback (see "Credential store selection" below)
-#   hit      : emit username + password, exit 0
-#   miss     : emit NOTHING, spool a durable escalation record, explain on
-#              stderr, exit 1 — git surfaces the failure and nothing is attributed
-#   unknown host : exit 0 with no output, no record (passthrough for non-Mosaic
-#              remotes handled by another helper)
-#
-# Backward compatibility is preserved for exactly one case: a host with no fleet
-# and no identity requested still gets the shared account, because on such a host
-# the shared account is the operator's own and there is no attribution to lose.
-# A host that HAS a fleet has agents whose records must be distinguishable, so
-# the shared fallback is refused there.
-#
-# A token is never written to stderr, to the escalation record, or to any log.
+# The implementation file (git-credential-mosaic.impl) refuses to run without
+# the clean-mode marker, so it cannot be invoked directly as a shaped-entry
+# bypass of this wrapper.
 
-[ "$1" = "get" ] || exit 0
+import os
+import sys
 
-host=""; username_in=""
-while IFS= read -r line; do
-  [ -z "$line" ] && break
-  case "$line" in
-    host=*)     host=${line#host=};;
-    username=*) username_in=${line#username=};;
-  esac
-done
+IMPL = os.path.join(os.path.dirname(os.path.realpath(__file__)), "git-credential-mosaic.impl")
+# Absolute-path candidates ONLY — never PATH resolution (an attacker-shaped
+# PATH must not choose the interpreter). /usr/bin/bash is the fleet-host
+# layout; /bin/bash is alpine and other FHS variants (found by the T125
+# gateway-image verification: the hardcoded /usr/bin/bash made every call
+# exit 127 inside node:22-alpine).
+BASH_CANDIDATES = ("/usr/bin/bash", "/bin/bash")
+BASH = next((p for p in BASH_CANDIDATES if os.access(p, os.X_OK)), None)
 
-# Recognized Gitea hosts carry the per-identity token scheme. Anything else is
-# declined quietly — another helper owns it, and refusing would break it.
-case "$host" in
-  git.uscllc.com)      idpfx=gitea-usc;;
-  git.mosaicstack.dev) idpfx=gitea-mosaicstack;;
-  *) exit 0;;
-esac
+# Allowlist: everything else in the environment dies at this boundary. Adding
+# a variable here is a security decision — it crosses into a shell that no
+# longer has any startup shaping, but it also becomes the only context the
+# implementation can see.
+KEEP = (
+    "HOME",
+    "PATH",
+    "LANG",
+    "MOSAIC_GIT_IDENTITY",
+    "MOSAIC_AGENT_NAME",
+    "MOSAIC_BRAIN_HOME",
+    "MOSAIC_CREDENTIAL_SPOOL",
+    "MOSAIC_CREDENTIAL_LINEAGE_FENCE",
+)
 
-ident="$MOSAIC_GIT_IDENTITY"; ident_src="MOSAIC_GIT_IDENTITY"
-if [ -z "$ident" ]; then
-  ident=$(git config --get mosaic.gitIdentity 2>/dev/null)
-  ident_src="git config mosaic.gitIdentity"
-fi
-if [ -z "$ident" ]; then
-  ident="$username_in"
-  ident_src="the username git supplied"
-fi
+env = {"_MOSAIC_HELPER_CLEAN": "1"}
+for name in KEEP:
+    value = os.environ.get(name)
+    if value is not None:
+        env[name] = value
 
-# ── Credential store selection ────────────────────────────────────────────────
-# An identity is a SEAT or it is a SERVICE, and which one it is determines where
-# its credential lives. There is no precedence rule between the two stores and no
-# fallback from one to the other: a seat whose slot is empty fails closed rather
-# than reading a service credential that happens to share its name.
-#
-#   seat     — <brain>/fleet/agents/<ident>/ exists
-#              credential at <brain>/fleet/agents/<ident>/secrets/<idpfx>-<ident>.token
-#   service  — it does not
-#              credential at ~/.config/mosaic/secrets/gitea-tokens/<idpfx>-<ident>.token
-#
-# One credential, one location. Two copies of one credential diverge, and the
-# stale copy fails in a way that reads as a revoked token rather than as drift.
-#
-# Brain-home resolution mirrors packages/mosaic/src/fleet/brain-home.ts and
-# tools/fleet/start-agent-session.sh: MOSAIC_BRAIN_HOME wins, else ~/.mosaic.
-brain_home="${MOSAIC_BRAIN_HOME:-$HOME/.mosaic}"
-svc_store="$HOME/.config/mosaic/secrets/gitea-tokens"
-
-idtok=""; ident_kind=""
-if [ -n "$ident" ]; then
-  if [ -d "$brain_home/fleet/agents/$ident" ]; then
-    ident_kind="seat"
-    idtok="$brain_home/fleet/agents/$ident/secrets/${idpfx}-${ident}.token"
-  else
-    ident_kind="service identity"
-    idtok="$svc_store/${idpfx}-${ident}.token"
-  fi
-  if [ -r "$idtok" ]; then
-    echo "username=${ident}"
-    echo "password=$(cat "$idtok")"
-    exit 0
-  fi
-fi
-
-# ── Shared-account fallback: ONLY on a host with no fleet and no identity ──────
-# `fleet/agents` existing is the same signal brain-home.ts uses to decide a brain
-# is active. Where there are seats, records must be attributable, so an
-# unresolvable request is refused instead of borrowing the shared account.
-fleet_present=0
-[ -d "$brain_home/fleet/agents" ] && fleet_present=1
-
-if [ -z "$ident" ] && [ "$fleet_present" -eq 0 ]; then
-  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  # shellcheck source=../_lib/credentials.sh
-  source "$script_dir/../_lib/credentials.sh"
-  load_credentials "$idpfx" >/dev/null 2>&1 || exit 0
-  # GITEA_USER is not populated by load_credentials (it exports GITEA_URL and
-  # GITEA_TOKEN only). Gitea's git-over-HTTP auth authenticates from the token in
-  # the password field, not from the username string, so any non-empty
-  # placeholder works — deliberately NOT a real account name, since framework
-  # files stay operator-agnostic (tools/quality/scripts/verify-sanitized.sh).
-  echo "username=${GITEA_USER:-git}"
-  echo "password=$GITEA_TOKEN"
-  exit 0
-fi
-
-# ── FAIL CLOSED ───────────────────────────────────────────────────────────────
-if [ -z "$ident" ]; then
-  reason="no-identity"
-else
-  reason="no-token-for-identity"
-fi
-
-seat="${MOSAIC_AGENT_NAME:-unknown}"
-ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-
-# The escalation RECORD is durable and unconditional; any notification built on
-# top of it is best-effort. Record and alert are deduplicated separately — a cap
-# on the alert alone lets the spool grow without bound exactly while the operator
-# is being told nothing, so the louder the failure the quieter it gets.
-#
-# A record field is arbitrary operator-supplied text: an identity comes from git
-# config or the environment, and cwd is whatever directory git ran in. Either can
-# contain a quote or a backslash, which would make the line unparseable JSON --
-# and a spool that silently stops parsing is worse than no spool, because the
-# operator only discovers it while reading the record that explains an outage.
-json_escape() {
-  local s=$1
-  s=${s//\\/\\\\}
-  s=${s//\"/\\\"}
-  s=${s//$'\t'/\\t}
-  s=${s//$'\r'/\\r}
-  s=${s//$'\n'/\\n}
-  printf '%s' "$s"
-}
-
-spool="${MOSAIC_CREDENTIAL_SPOOL:-$HOME/.local/state/mosaic-credential-escalations}"
-spool_record=""
-if mkdir -p "$spool" 2>/dev/null; then
-  chmod 700 "$spool" 2>/dev/null
-  spoolfile="$spool/$(date -u +%Y%m%d).jsonl"
-  dedupe="$spool/.spooled-${seat}-${ident:-none}-${reason}-$(date -u +%Y%m%d%H%M)"
-  if [ ! -e "$dedupe" ]; then
-    : > "$dedupe" 2>/dev/null
-    printf '{"ts":"%s","reason":"%s","identity":"%s","identity_source":"%s","kind":"%s","seat":"%s","host":"%s","cwd":"%s"}\n' \
-      "$(json_escape "$ts")" "$(json_escape "$reason")" \
-      "$(json_escape "${ident:-<unset>}")" "$(json_escape "$ident_src")" \
-      "$(json_escape "${ident_kind:-none}")" "$(json_escape "$seat")" \
-      "$(json_escape "$host")" "$(json_escape "$PWD")" \
-      >> "$spoolfile" 2>/dev/null
-    chmod 600 "$spoolfile" 2>/dev/null
-  fi
-  # Name the record only if one is actually on disk. Printing the path
-  # unconditionally sends the operator to a file that does not exist on exactly
-  # the hosts where the spool could not be created.
-  [ -s "$spoolfile" ] && spool_record="$spoolfile"
-  find "$spool" -maxdepth 1 -name '.spooled-*' -mmin +120 -delete 2>/dev/null
-fi
-
-cat >&2 <<EOF
-git-credential-mosaic: REFUSED (fail-closed).
-  host     : ${host}
-  identity : ${ident:-<unset>}${ident:+  (from ${ident_src}; resolved as a ${ident_kind})}
-  reason   : ${reason}
-EOF
-
-if [ -n "$ident" ]; then
-  cat >&2 <<EOF
-  expected : ${idtok}
-EOF
-fi
-
-cat >&2 <<EOF
-
-No per-identity credential resolved. This helper does NOT fall back to the shared
-account: that fallback makes every record it creates attributable to one
-principal, which is unrecoverable once a pull request has merged under it.
-
-Fix (pick one):
-  export MOSAIC_GIT_IDENTITY=<agent-id>        # process-scoped
-  git config mosaic.gitIdentity <agent-id>     # per-repo/worktree, persists
-Then provision that identity's credential at the path named above. An identity
-with a directory under \${MOSAIC_BRAIN_HOME:-\$HOME/.mosaic}/fleet/agents/ is a
-seat and is read ONLY from its own secrets/ slot; any other identity is read from
-~/.config/mosaic/secrets/gitea-tokens/. There is no fallback between the two.
-
-If this identity legitimately needs git access and has none, ask the orchestrator
-to provision one.
-
-EOF
-
-if [ -n "$spool_record" ]; then
-  echo "  record: ${spool_record}" >&2
-else
-  echo "  record: NOT WRITTEN — spool unavailable at ${spool}" >&2
-fi
-exit 1
+argv = [BASH, IMPL] + sys.argv[1:]
+if BASH is None:
+    sys.stderr.write("git-credential-mosaic: no executable bash at " + " or ".join(BASH_CANDIDATES) + "\n")
+    sys.exit(127)
+try:
+    os.execve(BASH, argv, env)
+except OSError as exc:
+    sys.stderr.write(f"git-credential-mosaic: entrypoint exec failed: {exc}\n")
+    sys.exit(127)

packages/mosaic/framework/tools/git/git-credential-mosaic.impl

@@ -0,0 +1,480 @@
+#!/bin/bash
+# git-credential-mosaic — git credential helper. Resolves a Gitea token from the
+# Mosaic credential store at runtime so remote URLs never embed secrets.
+#
+# Install (one-time, per clone or globally):
+#   git config credential.helper "$HOME/.config/mosaic/tools/git/git-credential-mosaic"
+#
+# Per-agent identity (Gate-16 author != reviewer separation):
+#   git config mosaic.gitIdentity <agent-id>   # per-worktree, persists on disk
+#   # or: export MOSAIC_GIT_IDENTITY=<agent-id>
+#
+# ── WHY THIS FAILS CLOSED ──────────────────────────────────────────────────────
+# This helper used to end by emitting the shared account's token for any request
+# it could not resolve to an identity. A seat with no identity, or with an
+# identity whose token was never provisioned, therefore received the most
+# privileged credential configured on the host — silently, and indistinguishably
+# from correct operation. Every record it then created (commit, push, PR, review)
+# was attributed to that shared account, so author != reviewer separation was
+# unenforceable and the true actor was unrecoverable after the fact.
+#
+# Under-provisioning must fail loudly, not impersonate. A refused git operation
+# is recoverable in one command; a merged pull request attributed to the wrong
+# principal is not.
+#
+# ── CONTRACT ───────────────────────────────────────────────────────────────────
+#   identity : MOSAIC_GIT_IDENTITY  >  git config mosaic.gitIdentity  >  the
+#              username git supplies on stdin
+#   ownership: a FLEET SEAT caller may resolve ONLY its own identity, where
+#              the CALLER is established by process ANCESTRY, not by the
+#              current environment: every ancestor's /proc/<pid>/environ is
+#              frozen at exec, so a child can rewrite its own MOSAIC_AGENT_NAME
+#              but can never make an ancestor disagree with what the launcher
+#              gave it (P5-RM-006; the dual-variable override was measured by
+#              rev-code-02 F1). An anonymous caller (no lineage, no consensus)
+#              may resolve NOTHING on a fleet host — seat or service
+#              (rev-code-02 F2). Non-fleet hosts keep the documented legacy
+#              paths below.
+#   perms    : a slot whose mode lets group or other read it (anything but
+#              ?00) is refused — a loose slot is provisioning drift, and
+#              serving from it silently widens every seat's exposure on a
+#              single-account host.
+#   store    : chosen by what the identity IS, with no precedence and no
+#              cross-store fallback (see "Credential store selection" below)
+#   hit      : emit username + password, exit 0
+#   miss     : emit NOTHING, spool a durable escalation record, explain on
+#              stderr, exit 1 — git surfaces the failure and nothing is attributed
+#   unknown host : exit 0 with no output, no record (passthrough for non-Mosaic
+#              remotes handled by another helper)
+#
+# Backward compatibility is preserved for exactly one case: a host with no fleet
+# and no identity requested still gets the shared account, because on such a host
+# the shared account is the operator's own and there is no attribution to lose.
+# A host that HAS a fleet has agents whose records must be distinguishable, so
+# the shared fallback is refused there.
+#
+# A token is never written to stderr, to the escalation record, or to any log.
+
+[ "$1" = "get" ] || exit 0
+
+
+# ── The shared refusal path ──────────────────────────────────────────────────
+# Every fail-closed exit funnels through refuse(): a durable escalation record
+# (deduped, JSON-escaped), a stderr diagnostic naming host/identity/reason,
+# caller-supplied guidance when the refusing site has specific advice, exit 1.
+# Defined here because the ownership gate below must be able to reach it.
+refuse() {
+  local guidance="${1:-}"
+  local seat ts spool spool_record spoolfile dedupe
+  seat="${MOSAIC_AGENT_NAME:-unknown}"
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  # A record field is arbitrary operator-supplied text: an identity comes from git
+  # config or the environment, and cwd is whatever directory git ran in. Either can
+  # contain a quote or a backslash, which would make the line unparseable JSON --
+  # and a spool that silently stops parsing is worse than no spool, because the
+  # operator only discovers it while reading the record that explains an outage.
+  json_escape() {
+    local s=$1
+    s=${s//\\/\\\\}
+    s=${s//\"/\\\"}
+    s=${s//$'\t'/\\t}
+    s=${s//$'\r'/\\r}
+    s=${s//$'\n'/\\n}
+    printf '%s' "$s"
+  }
+
+  spool="${MOSAIC_CREDENTIAL_SPOOL:-$HOME/.local/state/mosaic-credential-escalations}"
+  spool_record=""
+  if mkdir -p "$spool" 2>/dev/null; then
+    chmod 700 "$spool" 2>/dev/null
+    spoolfile="$spool/$(date -u +%Y%m%d).jsonl"
+    dedupe="$spool/.spooled-${seat}-${ident:-none}-${reason}-$(date -u +%Y%m%d%H%M)"
+    if [ ! -e "$dedupe" ]; then
+      : > "$dedupe" 2>/dev/null
+      printf '{"ts":"%s","reason":"%s","identity":"%s","identity_source":"%s","kind":"%s","seat":"%s","host":"%s","cwd":"%s"}\n' \
+        "$(json_escape "$ts")" "$(json_escape "$reason")" \
+        "$(json_escape "${ident:-<unset>}")" "$(json_escape "$ident_src")" \
+        "$(json_escape "${ident_kind:-none}")" "$(json_escape "$seat")" \
+        "$(json_escape "$host")" "$(json_escape "$PWD")" \
+        >> "$spoolfile" 2>/dev/null
+      chmod 600 "$spoolfile" 2>/dev/null
+    fi
+    # Name the record only if one is actually on disk. Printing the path
+    # unconditionally sends the operator to a file that does not exist on exactly
+    # the hosts where the spool could not be created.
+    [ -s "$spoolfile" ] && spool_record="$spoolfile"
+    find "$spool" -maxdepth 1 -name '.spooled-*' -mmin +120 -delete 2>/dev/null
+  fi
+
+  while IFS= builtin read -r _diag_line; do builtin printf '%s\n' "$_diag_line" >&2; done <<EOF
+git-credential-mosaic: REFUSED (fail-closed).
+  host     : ${host}
+  identity : ${ident:-<unset>}${ident:+  (from ${ident_src}; resolved as a ${ident_kind})}
+  reason   : ${reason}
+EOF
+
+  if [ -n "$ident" ]; then
+    while IFS= builtin read -r _diag_line; do builtin printf '%s\n' "$_diag_line" >&2; done <<EOF
+  expected : ${idtok}
+EOF
+  fi
+
+  while IFS= builtin read -r _diag_line; do builtin printf '%s\n' "$_diag_line" >&2; done <<EOF
+
+${guidance}
+EOF
+
+  if [ -n "$spool_record" ]; then
+    echo "  record: ${spool_record}" >&2
+  else
+    echo "  record: NOT WRITTEN — spool unavailable at ${spool}" >&2
+  fi
+  exit 1
+}
+
+# ── Bash environment injection guard (rev-code-02 R3, B1) ───────────────────
+# Non-interactive bash sources $BASH_ENV at startup and imports exported
+# functions from BASH_FUNC_* environment entries; either can define a read()
+# or printf() that shadows the builtin the ancestry walker and diagnostics
+# rely on — measured live by the reviewer's fixture (BASH_ENV read() rewrote
+# every ancestry entry). A legitimate fleet seat environment carries neither
+# (verified: zero BASH_FUNC_* in seat envs), so their presence in a helper
+# request is an injection attempt: scrub the shadows first (so even the
+# refusal machinery cannot be subverted), then refuse fail-closed.
+# Imported functions are detected by ENUMERATION, not env-var names: bash
+# consumes BASH_FUNC_* variables while importing the functions, so the
+# environment no longer shows them (measured). At this point the script has
+# defined exactly one function of its own (refuse); anything else in the
+# function table arrived from the caller's environment. BASH_ENV is checked
+# directly (it remains visible after sourcing).
+_injected=0
+_inj_names=""
+while IFS=' ' builtin read -r _decl _kind _fn; do
+  [ -n "$_fn" ] || continue
+  case "$_fn" in
+    refuse) ;;
+    *) _injected=1; _inj_names="$_inj_names $_fn";;
+  esac
+done < <(declare -F)
+_inj_vars="${!BASH_FUNC_@}"
+if [ -n "$_inj_vars" ]; then
+  _injected=1
+  for _iv in $_inj_vars; do
+    case "$_iv" in
+      BASH_FUNC_*%%) _ifn="${_iv#BASH_FUNC_}"; _ifn="${_ifn%%%}";;
+      BASH_FUNC_*)   _ifn="${_iv#BASH_FUNC_}";;
+      *)             _ifn="";;
+    esac
+    [ -n "$_ifn" ] && { unset -f "$_ifn" 2>/dev/null; _inj_names="$_inj_names $_ifn"; }
+  done
+fi
+if [ "$_injected" = 1 ] || [ -n "${BASH_ENV:-}" ]; then
+  while IFS=' ' builtin read -r _decl _kind _fn; do
+    [ "$_fn" = refuse ] || unset -f "$_fn" 2>/dev/null
+  done < <(declare -F)
+  unset BASH_ENV 2>/dev/null
+  reason="bash-environment-injection-refused"
+  refuse "The helper's bash startup state was externally shaped: BASH_ENV is
+set and/or exported BASH_FUNC_* functions are present in the request
+environment. Non-interactive bash sources BASH_ENV and imports those
+functions BEFORE any script line runs, so builtins this helper's security
+decisions rely on could be shadowed. Nothing resolves from a shaped request
+environment. If this surprised a legitimate workflow, the caller environment
+must be cleaned (no BASH_ENV, no exported functions) before invoking git."
+fi
+
+
+host=""; username_in=""
+while IFS= builtin read -r line; do
+  [ -z "$line" ] && break
+  case "$line" in
+    host=*)     host=${line#host=};;
+    username=*) username_in=${line#username=};;
+  esac
+done
+
+# Recognized Gitea hosts carry the per-identity token scheme. Anything else is
+# declined quietly — another helper owns it, and refusing would break it.
+case "$host" in
+  git.uscllc.com)      idpfx=gitea-usc;;
+  git.mosaicstack.dev) idpfx=gitea-mosaicstack;;
+  *) exit 0;;
+esac
+
+# ── Clean-entrypoint assert (P0-SEC R4) ─────────────────────────────────────
+# This implementation only runs behind the python entrypoint
+# (git-credential-mosaic), which execve's it with an allowlist environment:
+# no BASH_ENV, no imported functions, nothing shapable at bash startup. A
+# direct invocation without the marker is a bypass attempt on that boundary
+# and refuses. Placed after refuse() and the host parse so the refusal path
+# exists when it fires (an earlier placement died on 'refuse: command not
+# found' — the failure mode is real, keep this after every definition it
+# calls).
+if [ "${_MOSAIC_HELPER_CLEAN:-}" != "1" ]; then
+  reason="direct-entrypoint-refused"
+  refuse "This implementation refuses to run outside the production
+entrypoint. git-credential-mosaic (the python wrapper in this directory)
+execve's it with a hand-built, unshapable environment; invoking the .impl
+directly bypasses that boundary. Credential requests go through git, which
+invokes the wrapper named in gitconfig."
+fi
+
+ident="$MOSAIC_GIT_IDENTITY"; ident_src="MOSAIC_GIT_IDENTITY"
+if [ -z "$ident" ]; then
+  ident=$(git config --get mosaic.gitIdentity 2>/dev/null)
+  ident_src="git config mosaic.gitIdentity"
+fi
+if [ -z "$ident" ]; then
+  ident="$username_in"
+  ident_src="the username git supplied"
+fi
+
+# ── Credential store selection ────────────────────────────────────────────────
+# An identity is a SEAT or it is a SERVICE, and which one it is determines where
+# its credential lives. There is no precedence rule between the two stores and no
+# fallback from one to the other: a seat whose slot is empty fails closed rather
+# than reading a service credential that happens to share its name.
+#
+#   seat     — <brain>/fleet/agents/<ident>/ exists
+#              credential at <brain>/fleet/agents/<ident>/secrets/<idpfx>-<ident>.token
+#   service  — it does not
+#              credential at ~/.config/mosaic/secrets/gitea-tokens/<idpfx>-<ident>.token
+#
+# One credential, one location. Two copies of one credential diverge, and the
+# stale copy fails in a way that reads as a revoked token rather than as drift.
+#
+# Brain-home resolution mirrors packages/mosaic/src/fleet/brain-home.ts and
+# tools/fleet/start-agent-session.sh: MOSAIC_BRAIN_HOME wins, else ~/.mosaic.
+brain_home="${MOSAIC_BRAIN_HOME:-$HOME/.mosaic}"
+svc_store="$HOME/.config/mosaic/secrets/gitea-tokens"
+
+# ── Caller-identity ownership (P5-RM-006) ──────────────────────────────────────
+# A credential request is honourable only when the CALLER owns the identity it
+# asks for. On a fleet host every seat shares one unix account, so the
+# launcher-established MOSAIC_AGENT_NAME is the only attribution signal the
+# helper has. Two measured paths made the old contract unsafe:
+#
+#   - a seat exporting MOSAIC_GIT_IDENTITY=<another-seat> resolved that seat's
+#     token through the normal precedence chain (T97 G2, jarvis V2 probe), and
+#   - an anonymous caller (no seat name) inherited the host gitconfig's
+#     username=jarvis line and resolved jarvis's slot (T94: five watcher units
+#     flapping on exactly this class).
+#
+# Ownership rules, fail-closed on fleet hosts only; a host with no fleet keeps
+# the legacy contract unchanged:
+#   1. a SEAT caller may resolve only its own identity;
+#   2. an anonymous caller may not resolve any SEAT identity (service
+#      identities remain available to non-seat automation such as CI).
+# [P5-RM-006r1 ancestry binding begin]
+# ── Caller identity from exec-frozen ancestry (rev-code-02 F1/F2) ───────────
+# Walk /proc self->root collecting MOSAIC_AGENT_NAME from each ancestor's
+# frozen environ. Rules:
+#   - any DISAGREEMENT (an ancestor value != the current value, or ancestors
+#     disagreeing among themselves) is a rewrite -> spoof-refused, nothing
+#     resolves. A child can inject variables downward but cannot alter an
+#     ancestor's exec-frozen environ, so the launcher-established value always
+#     participates in the comparison.
+#   - consensus (all ancestors that carry the var agree with the current env,
+#     or with each other when the current env is empty) -> caller = that value.
+#   - no ancestor carries it -> the current claim is unlineaged: caller is
+#     anonymous regardless of what the environment says. A name with no
+#     lineage is a claim, not an identity.
+# The walk stops at PID 1, at a missing /proc entry, or INCLUSIVE at an
+# ancestor that carries MOSAIC_CREDENTIAL_LINEAGE_FENCE with an EMPTY agent
+# name — the test-suite lineage root. A fence beside a non-empty name is
+# IGNORED and the walk continues, so an attacker cannot fence off the true
+# ancestry by planting the marker next to a victim name.
+trusted_caller() {
+  # PATH-HARDENED (rev-code-02 R1 F1): every /proc read below uses ONLY bash
+  # builtins (read/case/parameter expansion). The first implementation piped
+  # through PATH-resolved tr/sed/head/grep, and a caller that prepends hostile
+  # utilities to PATH in the same invocation that overrides the identity
+  # variables could forge the ancestry itself. Builtins cannot be shadowed.
+  local pid ppid v entry line fence
+  local -a vals=()
+  pid=$$
+  while :; do
+    v=""
+    fence=0
+    if [ -r "/proc/$pid/environ" ]; then
+      # Read inside a captured subshell whose stderr is closed: opening
+      # /proc/<pid>/environ can fail with EACCES on ancestors that are
+      # readable-by-mode but not openable (session managers), and that open
+      # failure prints from the SHELL, immune to loop-level 2>/dev/null
+      # (measured). The subshell makes the skip silent; NUL separators are
+      # converted to newlines for the parent's builtin parse.
+      _env_text=$( { while IFS= builtin read -r -d '' _e; do builtin printf '%s\n' "$_e"; done < "/proc/$pid/environ"; } 2>/dev/null )
+      while IFS= builtin read -r entry; do
+        [ -n "$entry" ] || continue
+        case "$entry" in
+          MOSAIC_AGENT_NAME=*) v="${entry#MOSAIC_AGENT_NAME=}";;
+          MOSAIC_CREDENTIAL_LINEAGE_FENCE=*) fence=1;;
+        esac
+      done <<EOF_ENV
+$_env_text
+EOF_ENV
+    fi
+    if [ "$pid" != "$$" ]; then
+      [ -n "$v" ] && vals+=("$v")
+      if [ "$fence" = 1 ] && [ -z "$v" ]; then
+        break
+      fi
+    fi
+    ppid=""
+    if [ -r "/proc/$pid/status" ]; then
+      while IFS= builtin read -r line; do
+        case "$line" in
+          PPid:*) ppid="${line#PPid:}"; ppid="${ppid//[[:space:]]/}";;
+        esac
+      done < "/proc/$pid/status"
+    fi
+    case "$ppid" in ''|0|1) break;; esac
+    pid=$ppid
+  done
+  local self="${MOSAIC_AGENT_NAME:-}" i consensus=""
+  if [ "${#vals[@]}" -gt 0 ]; then
+    consensus="${vals[0]}"
+    for i in "${vals[@]}"; do
+      if [ "$i" != "$consensus" ]; then
+        printf 'SPOOF'
+        return
+      fi
+    done
+    if [ -n "$self" ] && [ "$self" != "$consensus" ]; then
+      printf 'SPOOF'
+      return
+    fi
+  fi
+  printf '%s' "$consensus"
+}
+
+if [ -d "$brain_home/fleet/agents" ]; then
+  caller="$(trusted_caller)"
+  if [ "$caller" = "SPOOF" ]; then
+    reason="caller-identity-spoof-refused"
+    refuse "The MOSAIC_AGENT_NAME lineage disagrees within this process tree:
+an ancestor established by exec carries a different value than the request.
+A child process can rewrite its own environment but never an ancestor's
+frozen environ, so disagreement is a rewrite, not a race. Nothing resolves
+under a rewritten caller identity. If this surprised a legitimate workflow,
+run git from the seat's own session, not from a rewritten environment."
+  fi
+  if [ -n "$caller" ] && [ -d "$brain_home/fleet/agents/$caller" ]; then
+    if [ -n "$ident" ] && [ "$ident" != "$caller" ]; then
+      reason="cross-seat-identity-refused"
+      refuse "A seat may resolve only its own credential slot. Caller seat is
+'$caller' (ancestry-established); the request names '$ident'. Overriding
+MOSAIC_GIT_IDENTITY (or a git config / URL username) to another seat's name is
+exactly the path this refusal exists to close. If '$ident' auth is genuinely
+required, that seat runs the operation itself or the orchestrator provisions
+an explicit grant."
+    fi
+  else
+    # Anonymous caller on a fleet host (no lineage, or the lineage root is not
+    # a seat): NOTHING resolves — seat slots (T94 jarvis@ class) or legacy
+    # service credentials (rev-code-02 F2: credentialed services are seats;
+    # the legacy store is vestigial and not anonymously reachable).
+    if [ -n "$ident" ]; then
+      ident_kind="${ident_kind:-}"
+      [ -d "$brain_home/fleet/agents/$ident" ] && ident_kind="seat" || ident_kind="service identity"
+      reason="anonymous-credential-refused"
+      refuse "This caller has no seat lineage on a fleet host and asked for
+'$ident' (a ${ident_kind}). Anonymous callers resolve nothing on fleet hosts:
+seat credentials must never serve an unattributable caller, and credentialed
+services are seats with their own sessions (the legacy service store is
+vestigial). Run from the owning seat's session."
+    fi
+  fi
+fi
+# [P5-RM-006r1 ancestry binding end]
+
+idtok=""; ident_kind=""
+if [ -n "$ident" ]; then
+  if [ -d "$brain_home/fleet/agents/$ident" ]; then
+    ident_kind="seat"
+    idtok="$brain_home/fleet/agents/$ident/secrets/${idpfx}-${ident}.token"
+  else
+    ident_kind="service identity"
+    idtok="$svc_store/${idpfx}-${ident}.token"
+  fi
+  if [ -r "$idtok" ]; then
+    # P5-RM-006 seat permissions: a SEAT slot readable by group or other is
+    # provisioning drift, and on a single-account fleet host it widens every
+    # seat's exposure at once. Refuse rather than serve from a loose slot; the
+    # record names the path so the provisioning fix is one chmod away.
+    # Scoped to seat slots: the framework service store is operator-managed
+    # and outside this work unit's permission surface.
+    if [ "${ident_kind:-}" = "seat" ]; then
+      # command -p resolves stat from the POSIX default PATH (system
+      # directories), never the caller's PATH (rev-code-02 R3 B2: a shadowed
+      # stat reported a 0644 slot as 600 and the helper served it). Output is
+      # shape-validated: anything that is not 3-4 octal digits refuses.
+      slot_mode="$(command -p stat -c '%a' "$idtok" 2>/dev/null || true)"
+      case "$slot_mode" in
+        [0-7][0-7][0-7]|[0-7][0-7][0-7][0-7]) ;;
+        *) slot_mode="unverifiable";;
+      esac
+      if [ "${slot_mode:1:2}" != "00" ]; then
+        reason="slot-permission-violation"
+        refuse "Slot $idtok has mode ${slot_mode:-unknown}; expected owner-only
+(0600 or stricter). Tighten it: chmod 600 '$idtok'. This refusal is the seat
+permissions half of P5-RM-006: a loose slot on a shared-account host is every
+seat's exposure, so the helper declines to serve from it. Mode inspection uses
+command -p (trusted PATH) and fails closed on unverifiable output."
+      fi
+    fi
+    echo "username=${ident}"
+    echo "password=$(<"$idtok")"
+    exit 0
+  fi
+fi
+
+# ── Shared-account fallback: ONLY on a host with no fleet and no identity ──────
+# `fleet/agents` existing is the same signal brain-home.ts uses to decide a brain
+# is active. Where there are seats, records must be attributable, so an
+# unresolvable request is refused instead of borrowing the shared account.
+fleet_present=0
+[ -d "$brain_home/fleet/agents" ] && fleet_present=1
+
+if [ -z "$ident" ] && [ "$fleet_present" -eq 0 ]; then
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  # shellcheck source=../_lib/credentials.sh
+  source "$script_dir/../_lib/credentials.sh"
+  load_credentials "$idpfx" >/dev/null 2>&1 || exit 0
+  # GITEA_USER is not populated by load_credentials (it exports GITEA_URL and
+  # GITEA_TOKEN only). Gitea's git-over-HTTP auth authenticates from the token in
+  # the password field, not from the username string, so any non-empty
+  # placeholder works — deliberately NOT a real account name, since framework
+  # files stay operator-agnostic (tools/quality/scripts/verify-sanitized.sh).
+  echo "username=${GITEA_USER:-git}"
+  echo "password=$GITEA_TOKEN"
+  exit 0
+fi
+
+# ── FAIL CLOSED ───────────────────────────────────────────────────────────────
+# The escalation RECORD is durable and unconditional; any notification built on
+# top of it is best-effort (see refuse()). Record and alert are deduplicated
+# separately — a cap on the alert alone lets the spool grow without bound
+# exactly while the operator is being told nothing, so the louder the failure
+# the quieter it gets.
+if [ -z "$ident" ]; then
+  reason="no-identity"
+else
+  reason="no-token-for-identity"
+fi
+refuse "No per-identity credential resolved. This helper does NOT fall back to the shared
+account: that fallback makes every record it creates attributable to one
+principal, which is unrecoverable once a pull request has merged under it.
+
+Fix (pick one):
+  export MOSAIC_GIT_IDENTITY=<agent-id>        # process-scoped
+  git config mosaic.gitIdentity <agent-id>     # per-repo/worktree, persists
+Then provision that identity's credential at the path named above. An identity
+with a directory under \${MOSAIC_BRAIN_HOME:-\$HOME/.mosaic}/fleet/agents/ is a
+seat and is read ONLY from its own secrets/ slot; any other identity is read from
+~/.config/mosaic/secrets/gitea-tokens/. There is no fallback between the two.
+
+If this identity legitimately needs git access and has none, ask the orchestrator
+to provision one."
+

packages/mosaic/framework/tools/git/issue-assign.sh

@@ -3,6 +3,7 @@
 # Usage: issue-assign.sh -i ISSUE_NUMBER [-a assignee] [-l labels] [-m milestone]
 
 set -e
+set -o pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
@@ -33,25 +34,36 @@ Examples:
     $(basename "$0") -i 42 -l "in-progress" -m "0.2.0"
     $(basename "$0") -i 42 -a @me
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
+}
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
 }
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE="$2"
             shift 2
             ;;
         -a|--assignee)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ASSIGNEE="$2"
             shift 2
             ;;
         -l|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -79,20 +91,35 @@ PLATFORM=$(detect_platform)
 case "$PLATFORM" in
     github)
         if [[ -n "$ASSIGNEE" ]]; then
-            gh issue edit "$ISSUE" --add-assignee "$ASSIGNEE"
+            prov_rc=0
+            gh issue edit "$ISSUE" --add-assignee "$ASSIGNEE" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         if [[ "$REMOVE_ASSIGNEE" == true ]]; then
             # Get current assignees and remove them
-            CURRENT=$(gh issue view "$ISSUE" --json assignees -q '.assignees[].login' 2>/dev/null | tr '\n' ',')
+            # pipefail preserves the provider status through the pipeline;
+            # a FAILED lookup exits here instead of reading as a silent
+            # no-assignees skip (codex PR #1464). A successful lookup with
+            # zero assignees still skips the edit below.
+            CURRENT=$(gh issue view "$ISSUE" --json assignees -q '.assignees[].login' 2>/dev/null | tr '\n' ',') || {
+                echo "Error: could not read current assignees (provider lookup failed)" >&2
+                exit 1
+            }
             if [[ -n "$CURRENT" ]]; then
-                gh issue edit "$ISSUE" --remove-assignee "${CURRENT%,}"
+                prov_rc=0
+                gh issue edit "$ISSUE" --remove-assignee "${CURRENT%,}" || prov_rc=$?
+                [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
             fi
         fi
         if [[ -n "$LABELS" ]]; then
-            gh issue edit "$ISSUE" --add-label "$LABELS"
+            prov_rc=0
+            gh issue edit "$ISSUE" --add-label "$LABELS" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         if [[ -n "$MILESTONE" ]]; then
-            gh issue edit "$ISSUE" --milestone "$MILESTONE"
+            prov_rc=0
+            gh issue edit "$ISSUE" --milestone "$MILESTONE" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         echo "Issue #$ISSUE updated successfully"
         ;;
@@ -131,7 +158,9 @@ case "$PLATFORM" in
         fi
 
         if [[ "$NEEDS_EDIT" == true ]]; then
-            "${CMD[@]}"
+            prov_rc=0
+            "${CMD[@]}" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
             echo "Issue #$ISSUE updated successfully"
         else
             echo "No changes specified"

packages/mosaic/framework/tools/git/issue-close.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-close.sh - Close an issue on GitHub or Gitea
-# Usage: issue-close.sh -i <issue_number> [-c <comment>]
+# Usage: issue-close.sh -i <issue_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
 
 set -e
 
@@ -11,36 +12,71 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 ISSUE_NUMBER=""
 COMMENT=""
+BODY_FILE=""
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-close.sh -i <issue_number> [-b <comment>] (see --help)" >&2
+    exit 2
+}
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             COMMENT="$2"
             shift 2
             ;;
+        --body-file)
+            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
+            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
+            BODY_FILE="$2"
+            shift 2
+            ;;
         -h|--help)
-            echo "Usage: issue-close.sh -i <issue_number> [-c <comment>]"
+            echo "Usage: issue-close.sh -i <issue_number> [-b <comment>]"
             echo ""
             echo "Options:"
-            echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment to add before closing (optional)"
+            echo "  -n, --number   Issue number (required; canonical)"
+            echo "  -i, --issue    Alias for --number"
+            echo "  -b, --body     Comment to add before closing (optional; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
+# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
+# exclusive with an explicit --body/--comment value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        COMMENT=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 # Detect platform and close issue
@@ -82,10 +118,22 @@ gitea_issue_close_api() {
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
+    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
+    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+        gh_rc=0
+        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+        if [[ "$gh_rc" -ne 0 ]]; then
+            echo "Error: GitHub comment before close failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh issue close "$ISSUE_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub issue close failed (gh exit $gh_rc)" >&2
+        exit 1
     fi
-    gh issue close "$ISSUE_NUMBER"
     echo "Closed GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     GITEA_LOGIN_NAME=$(get_gitea_login || true)
@@ -107,7 +155,9 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
                 exit 1
             }
         fi
-        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME"
+        prov_rc=0
+        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     else
         echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
         if [[ -n "$COMMENT" ]]; then

packages/mosaic/framework/tools/git/issue-comment.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-comment.sh - Add a comment to an issue on GitHub or Gitea
-# Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]
+# Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1, 2026-08-28)
 #
 # tea v0.11.1 defines no `comment` subcommand under `tea issue` (or `tea pr`);
 # the non-existent `tea issue comment ...` form does not error — tea silently
@@ -30,47 +31,84 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 ISSUE_NUMBER=""
 COMMENT=""
+BODY_FILE=""
 LOGIN_OVERRIDE=""
 
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker
+# (CONSTITUTION gate 8 as amended; E2E-DELIVERY).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag, matching
+            # issue-create/issue-edit/pr-create/pr-edit; -c/--comment stays a
+            # backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             COMMENT="$2"
             shift 2
             ;;
+        --body-file)
+            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
+            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
+            BODY_FILE="$2"
+            shift 2
+            ;;
         -l|--login)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LOGIN_OVERRIDE="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: issue-comment.sh -i <issue_number> -c <comment> [--login <name>]"
+            echo "Usage: issue-comment.sh -i <issue_number> -b <comment> [--login <name>]"
             echo ""
             echo "Options:"
-            echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment text (required)"
+            echo "  -n, --number   Issue number (required; canonical)"
+            echo "  -i, --issue    Alias for --number"
+            echo "  -b, --body     Comment text (required; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -l, --login    Override the detected Gitea tea login for this call"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
+# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
+# exclusive with an explicit --body/--comment value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        COMMENT=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 if [[ -z "$COMMENT" ]]; then
-    echo "Error: Comment is required (-c)"
-    exit 1
+    usage_error "comment is required (-b/--body, or the -c/--comment alias)"
 fi
 
 detect_platform >/dev/null
@@ -340,7 +378,15 @@ PY
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+    # R4 exit-code contract: normalize provider failures to exit 1. gh's own
+    # usage errors exit 2, which would collide with this wrapper's reserved
+    # usage-error status if propagated raw (codex review of 08a00149).
+    gh_rc=0
+    gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub comment write failed (gh exit $gh_rc; provider/credential failure — usage errors are exit 2)" >&2
+        exit 1
+    fi
     echo "Added comment to GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     # A --login override selects a NAMED tea credential and is the only way to

packages/mosaic/framework/tools/git/issue-create.sh

@@ -10,6 +10,7 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Default values
 TITLE=""
 BODY=""
+BODY_FILE=""
 LABELS=""
 MILESTONE=""
 INTERACTIVE=false
@@ -74,26 +75,45 @@ Examples:
     $(basename "$0") -t "Fix login bug" -l "bug,priority-high"
     $(basename "$0") -t "Add dark mode" -b "Implement theme switching" -m "0.2.0"
     $(basename "$0") -i
+
+Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure.
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
         -b|--body)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BODY="$2"
             shift 2
             ;;
+        --body-file)
+            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
+            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
+            BODY_FILE="$2"
+            shift 2
+            ;;
         -l|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -111,6 +131,19 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+# R3 (2026-08-29): resolve --body-file into BODY (file or stdin '-');
+# exclusive with an explicit --body/--comment value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$BODY" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        BODY=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        BODY=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
 if [[ "$INTERACTIVE" == true ]]; then
     [[ -n "$TITLE" ]] || read -r -p "Issue title: " TITLE
     [[ -n "$BODY" ]] || read -r -p "Issue body (optional): " BODY || true
@@ -131,7 +164,9 @@ case "$PLATFORM" in
         [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
         [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         ;;
     gitea)
         if command -v tea >/dev/null 2>&1; then

packages/mosaic/framework/tools/git/issue-edit.sh

@@ -11,28 +11,49 @@ source "$SCRIPT_DIR/detect-platform.sh"
 ISSUE_NUMBER=""
 TITLE=""
 BODY=""
+BODY_FILE=""
 LABELS=""
 MILESTONE=""
 
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-edit.sh -i <issue_number> [-t <title>] [-b <body>] [-l <labels>] [-m <milestone>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
         -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
         -b|--body)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BODY="$2"
             shift 2
             ;;
+        --body-file)
+            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
+            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
+            BODY_FILE="$2"
+            shift 2
+            ;;
         -l|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
@@ -40,24 +61,38 @@ while [[ $# -gt 0 ]]; do
             echo "Usage: issue-edit.sh -i <issue_number> [-t <title>] [-b <body>] [-l <labels>] [-m <milestone>]"
             echo ""
             echo "Options:"
-            echo "  -i, --issue      Issue number (required)"
+            echo "  -n, --number     Issue number (required; canonical)"
+            echo "  -i, --issue      Alias for --number"
             echo "  -t, --title      New title"
             echo "  -b, --body       New body/description"
             echo "  -l, --labels     Labels (comma-separated, replaces existing)"
             echo "  -m, --milestone  Milestone name"
             echo "  -h, --help       Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
+# R3 (2026-08-29): resolve --body-file into BODY (file or stdin '-');
+# exclusive with an explicit --body/--comment value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$BODY" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        BODY=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        BODY=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 detect_platform >/dev/null
@@ -68,7 +103,9 @@ if [[ "$PLATFORM" == "github" ]]; then
     [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
     [[ -n "$LABELS" ]] && CMD+=(--add-label "$LABELS")
     [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-    "${CMD[@]}"
+    prov_rc=0
+    "${CMD[@]}" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Updated GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_SLUG=$(get_repo_slug) || {
@@ -84,7 +121,9 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
     [[ -n "$BODY" ]] && CMD+=(--description "$BODY")
     [[ -n "$LABELS" ]] && CMD+=(--add-labels "$LABELS")
     [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
-    "${CMD[@]}"
+    prov_rc=0
+    "${CMD[@]}" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Updated Gitea issue #$ISSUE_NUMBER"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/issue-list.sh

@@ -36,33 +36,46 @@ Examples:
     $(basename "$0") -m "0.2.0"               # Issues in milestone 0.2.0
     $(basename "$0") --repo ddk/ai-bma         # List issues from anywhere
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -s|--state)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             STATE="$2"
             shift 2
             ;;
-        -l|--label)
+        -l|--label|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABEL="$2"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
         -a|--assignee)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ASSIGNEE="$2"
             shift 2
             ;;
         -n|--limit)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LIMIT="$2"
             shift 2
             ;;
         -r|--repo)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
@@ -95,7 +108,9 @@ case "$PLATFORM" in
         [[ -n "$LABEL" ]] && CMD+=(--label "$LABEL")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
         [[ -n "$ASSIGNEE" ]] && CMD+=(--assignee "$ASSIGNEE")
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         ;;
     gitea)
         if [[ -n "$REPO_OVERRIDE" ]]; then
@@ -114,7 +129,9 @@ case "$PLATFORM" in
         [[ -n "$MILESTONE" ]] && CMD+=(--milestones "$MILESTONE")
         # Note: tea may not support assignee filter directly in all versions.
         [[ -n "$ASSIGNEE" ]] && echo "Note: Assignee filtering may require manual review for Gitea" >&2
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         ;;
     *)
         echo "Error: Could not detect git platform" >&2

packages/mosaic/framework/tools/git/issue-reopen.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # issue-reopen.sh - Reopen a closed issue on GitHub or Gitea
-# Usage: issue-reopen.sh -i <issue_number> [-c <comment>]
+# Usage: issue-reopen.sh -i <issue_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
 
 set -e
 
@@ -10,36 +11,71 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 ISSUE_NUMBER=""
 COMMENT=""
+BODY_FILE=""
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>] (see --help)" >&2
+    exit 2
+}
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             COMMENT="$2"
             shift 2
             ;;
+        --body-file)
+            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
+            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
+            BODY_FILE="$2"
+            shift 2
+            ;;
         -h|--help)
-            echo "Usage: issue-reopen.sh -i <issue_number> [-c <comment>]"
+            echo "Usage: issue-reopen.sh -i <issue_number> [-b <comment>]"
             echo ""
             echo "Options:"
-            echo "  -i, --issue    Issue number (required)"
-            echo "  -c, --comment  Comment to add when reopening (optional)"
+            echo "  -n, --number   Issue number (required; canonical)"
+            echo "  -i, --issue    Alias for --number"
+            echo "  -b, --body     Comment to add when reopening (optional; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
+# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
+# exclusive with an explicit --body/--comment value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        COMMENT=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "issue number is required (-i/--issue)"
 fi
 
 detect_platform >/dev/null
@@ -80,18 +116,34 @@ gitea_issue_reopen_api() {
 }
 
 if [[ "$PLATFORM" == "github" ]]; then
+    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
+    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT"
+        gh_rc=0
+        gh issue comment "$ISSUE_NUMBER" --body "$COMMENT" || gh_rc=$?
+        if [[ "$gh_rc" -ne 0 ]]; then
+            echo "Error: GitHub comment before reopen failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh issue reopen "$ISSUE_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub issue reopen failed (gh exit $gh_rc)" >&2
+        exit 1
     fi
-    gh issue reopen "$ISSUE_NUMBER"
     echo "Reopened GitHub issue #$ISSUE_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args || true)
     if [[ -n "$REPO_ARGS" ]]; then
         if [[ -n "$COMMENT" ]]; then
-            tea issue comment "$ISSUE_NUMBER" "$COMMENT" $REPO_ARGS
+            prov_rc=0
+            tea issue comment "$ISSUE_NUMBER" "$COMMENT" $REPO_ARGS || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
-        tea issue reopen "$ISSUE_NUMBER" $REPO_ARGS
+        prov_rc=0
+        tea issue reopen "$ISSUE_NUMBER" $REPO_ARGS || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     else
         echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
         if [[ -n "$COMMENT" ]]; then

packages/mosaic/framework/tools/git/issue-view.sh

@@ -8,6 +8,14 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: issue-view.sh -i <issue_number> (see --help)" >&2
+    exit 2
+}
+
 ISSUE_NUMBER=""
 
 # get_remote_host and get_gitea_token are provided by detect-platform.sh
@@ -73,7 +81,8 @@ if comments:
 
 while [[ $# -gt 0 ]]; do
     case $1 in
-        -i|--issue)
+        -i|--issue|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE_NUMBER="$2"
             shift 2
             ;;
@@ -81,28 +90,29 @@ while [[ $# -gt 0 ]]; do
             echo "Usage: issue-view.sh -i <issue_number>"
             echo ""
             echo "Options:"
-            echo "  -i, --issue    Issue number (required)"
+            echo "  -n, --number   Issue number (required; canonical)"
+            echo "  -i, --issue    Alias for --number"
             echo ""
             echo "Comments are always included (tea --comments / Gitea API /comments)."
             echo "  -h, --help     Show this help"
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$ISSUE_NUMBER" ]]; then
-    echo "Error: Issue number is required (-i)"
-    exit 1
+    usage_error "Issue number is required"
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh issue view "$ISSUE_NUMBER"
+    prov_rc=0
+    gh issue view "$ISSUE_NUMBER" || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if command -v tea >/dev/null 2>&1; then
         # --comments is what makes tea print the comment bodies (#1357 F3).

packages/mosaic/framework/tools/git/lane-brief.sh

@@ -28,18 +28,25 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 REPO="" MILESTONE="" LABEL="" LOGIN="" LIMIT=100
-while getopts "r:m:l:L:n:h" opt; do
-  case "$opt" in
-    r) REPO="$OPTARG" ;;
-    m) MILESTONE="$OPTARG" ;;
-    l) LABEL="$OPTARG" ;;
-    L) LOGIN="$OPTARG" ;;
-    n) LIMIT="$OPTARG" ;;
-    h) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
-    *) echo "see -h" >&2; exit 2 ;;
+# R2 (2026-08-28): long-flag aliases with the same usage-error contract the
+# wrapper family shares (rc 2, stderr). getopts could not take long flags.
+usage_error() {
+  echo "Error: $*" >&2
+  echo "Usage: lane-brief.sh -r <owner/repo> [-m milestone] [-l label] [-L login] [-n limit]" >&2
+  exit 2
+}
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -r|--repo) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; REPO="$2"; shift 2 ;;
+    -m|--milestone) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; MILESTONE="$2"; shift 2 ;;
+    -l|--label|--labels) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LABEL="$2"; shift 2 ;;
+    -L|--login) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LOGIN="$2"; shift 2 ;;
+    -n|--limit) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LIMIT="$2"; shift 2 ;;
+    -h|--help) grep '^#' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) usage_error "unknown option: $1" ;;
   esac
 done
-[[ -n "$REPO" ]] || { echo "FATAL: -r <owner/repo> required" >&2; exit 2; }
+[[ -n "$REPO" ]] || usage_error "-r/--repo <owner/repo> required"
 
 # Resolve login: explicit -L, then $GITEA_LOGIN, then owner inference, then the
 # shared default-login resolver. Owner inference comes before the shared fallback
@@ -72,7 +79,7 @@ if [[ -z "$LOGIN" ]]; then
     fi
   fi
 fi
-[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 2; }
+[[ -n "$LOGIN" ]] || { echo "FATAL: could not resolve a Gitea login for $REPO (pass -L or set GITEA_LOGIN)" >&2; exit 1; }
 
 command -v tea >/dev/null || { echo "FATAL: tea not found" >&2; exit 1; }
 command -v jq  >/dev/null || { echo "FATAL: jq not found" >&2; exit 1; }

packages/mosaic/framework/tools/git/milestone-close.sh

@@ -8,11 +8,20 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: milestone-close.sh -t <title> (see --help)" >&2
+    exit 2
+}
+
 TITLE=""
 
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
@@ -25,28 +34,30 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$TITLE" ]]; then
-    echo "Error: Milestone title is required (-t)"
-    exit 1
+    usage_error "Milestone title is required"
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh api -X PATCH "/repos/{owner}/{repo}/milestones/$(gh api "/repos/{owner}/{repo}/milestones" --jq ".[] | select(.title==\"$TITLE\") | .number")" -f state=closed
+    prov_rc=0
+    gh api -X PATCH "/repos/{owner}/{repo}/milestones/$(gh api "/repos/{owner}/{repo}/milestones" --jq ".[] | select(.title==\"$TITLE\") | .number")" -f state=closed || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Closed GitHub milestone: $TITLE"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args) || {
         echo "Error: Could not resolve Gitea repo/login for remote host" >&2
         exit 1
     }
-    tea milestone close "$TITLE" $REPO_ARGS
+    prov_rc=0
+    tea milestone close "$TITLE" $REPO_ARGS || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Closed Gitea milestone: $TITLE"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/milestone-create.sh

@@ -3,6 +3,7 @@
 # Usage: milestone-create.sh -t "Title" [-d "Description"] [--due "YYYY-MM-DD"]
 
 set -e
+set -o pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
@@ -37,21 +38,31 @@ Examples:
     $(basename "$0") -t "0.0.1" -d "Pre-MVP Foundation Sprint"
     $(basename "$0") -t "0.1.0" -d "MVP Release" --due "2025-03-01"
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
         -d|--desc)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             DESCRIPTION="$2"
             shift 2
             ;;
         --due)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             DUE_DATE="$2"
             shift 2
             ;;
@@ -74,14 +85,18 @@ PLATFORM=$(detect_platform)
 if [[ "$LIST_ONLY" == true ]]; then
     case "$PLATFORM" in
         github)
-            gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)\t\(.open_issues)/\(.closed_issues) issues"'
+            prov_rc=0
+            gh api repos/:owner/:repo/milestones --jq '.[] | "\(.number)\t\(.title)\t\(.state)\t\(.open_issues)/\(.closed_issues) issues"' || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
             ;;
         gitea)
             REPO_ARGS=$(get_gitea_repo_args) || {
                 echo "Error: Could not resolve Gitea repo/login for remote host" >&2
                 exit 1
             }
-            tea milestones list $REPO_ARGS
+            prov_rc=0
+            tea milestones list $REPO_ARGS || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
             ;;
         *)
             echo "Error: Could not detect git platform" >&2
@@ -92,8 +107,7 @@ if [[ "$LIST_ONLY" == true ]]; then
 fi
 
 if [[ -z "$TITLE" ]]; then
-    echo "Error: Title is required (-t) for creating milestones" >&2
-    usage
+    usage_error "Title is required (-t) for creating milestones"
 fi
 
 case "$PLATFORM" in
@@ -109,7 +123,9 @@ case "$PLATFORM" in
              + (if $d != "" then {"description": $d} else {} end)
              + (if $due != "" then {"due_on": ($due + "T00:00:00Z")} else {} end)')
 
-        gh api repos/:owner/:repo/milestones --method POST --input - <<< "$JSON_PAYLOAD"
+        prov_rc=0
+        gh api repos/:owner/:repo/milestones --method POST --input - <<< "$JSON_PAYLOAD" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         echo "Milestone '$TITLE' created successfully"
         ;;
     gitea)
@@ -120,7 +136,9 @@ case "$PLATFORM" in
         CMD=(tea milestones create --title "$TITLE")
         [[ -n "$DESCRIPTION" ]] && CMD+=(--description "$DESCRIPTION")
         [[ -n "$DUE_DATE" ]] && CMD+=(--deadline "$DUE_DATE")
-        "${CMD[@]}" $REPO_ARGS
+        prov_rc=0
+        "${CMD[@]}" $REPO_ARGS || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         echo "Milestone '$TITLE' created successfully"
         ;;
     *)

packages/mosaic/framework/tools/git/milestone-list.sh

@@ -8,11 +8,20 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"
 
 # Parse arguments
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: milestone-list.sh [-s <state>] (see --help)" >&2
+    exit 2
+}
+
 STATE="open"
 
 while [[ $# -gt 0 ]]; do
     case $1 in
         -s|--state)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             STATE="$2"
             shift 2
             ;;
@@ -25,8 +34,7 @@ while [[ $# -gt 0 ]]; do
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
@@ -34,13 +42,17 @@ done
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
-    gh api "/repos/{owner}/{repo}/milestones?state=$STATE" --jq '.[] | "\(.title) (\(.state)) - \(.open_issues) open, \(.closed_issues) closed"'
+    prov_rc=0
+    gh api "/repos/{owner}/{repo}/milestones?state=$STATE" --jq '.[] | "\(.title) (\(.state)) - \(.open_issues) open, \(.closed_issues) closed"' || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 elif [[ "$PLATFORM" == "gitea" ]]; then
     REPO_ARGS=$(get_gitea_repo_args) || {
         echo "Error: Could not resolve Gitea repo/login for remote host" >&2
         exit 1
     }
-    tea milestone list $REPO_ARGS
+    prov_rc=0
+    tea milestone list $REPO_ARGS || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
 else
     echo "Error: Unknown platform"
     exit 1

packages/mosaic/framework/tools/git/pr-close.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # pr-close.sh - Close a pull request without merging on GitHub or Gitea
-# Usage: pr-close.sh -n <pr_number> [-c <comment>]
+# Usage: pr-close.sh -n <pr_number> [-b <comment>]
+# (-c/--comment is a backward-compatible alias for -b/--body; R1/R4 2026-08-28)
 
 set -e
 
@@ -10,51 +11,101 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Parse arguments
 PR_NUMBER=""
 COMMENT=""
+BODY_FILE=""
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: pr-close.sh -n <pr_number> [-b <comment>] (see --help)" >&2
+    exit 2
+}
 
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             COMMENT="$2"
             shift 2
             ;;
+        --body-file)
+            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
+            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
+            BODY_FILE="$2"
+            shift 2
+            ;;
         -h|--help)
-            echo "Usage: pr-close.sh -n <pr_number> [-c <comment>]"
+            echo "Usage: pr-close.sh -n <pr_number> [-b <comment>]"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
-            echo "  -c, --comment  Comment before closing (optional)"
+            echo "  -b, --body     Comment before closing (optional; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
+# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
+# exclusive with an explicit --body/--comment value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        COMMENT=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 detect_platform >/dev/null
 
 if [[ "$PLATFORM" == "github" ]]; then
+    # R4: normalize provider failures to exit 1 (gh's own usage errors exit 2
+    # and would collide with the reserved usage-error status).
     if [[ -n "$COMMENT" ]]; then
-        gh pr comment "$PR_NUMBER" --body "$COMMENT"
+        gh_rc=0
+        gh pr comment "$PR_NUMBER" --body "$COMMENT" || gh_rc=$?
+        if [[ "$gh_rc" -ne 0 ]]; then
+            echo "Error: GitHub PR comment before close failed (gh exit $gh_rc)" >&2
+            exit 1
+        fi
+    fi
+    gh_rc=0
+    gh pr close "$PR_NUMBER" || gh_rc=$?
+    if [[ "$gh_rc" -ne 0 ]]; then
+        echo "Error: GitHub PR close failed (gh exit $gh_rc)" >&2
+        exit 1
     fi
-    gh pr close "$PR_NUMBER"
     echo "Closed GitHub PR #$PR_NUMBER"
 elif [[ "$PLATFORM" == "gitea" ]]; then
     if [[ -n "$COMMENT" ]]; then
-        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args)
+        prov_rc=0
+        tea pr comment "$PR_NUMBER" "$COMMENT" $(get_gitea_repo_args) || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     fi
-    tea pr close "$PR_NUMBER" $(get_gitea_repo_args)
+    prov_rc=0
+    tea pr close "$PR_NUMBER" $(get_gitea_repo_args) || prov_rc=$?
+    [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
     echo "Closed Gitea PR #$PR_NUMBER"
 else
     echo "Error: Unknown platform"

packages/mosaic/framework/tools/git/pr-create.sh

@@ -10,6 +10,7 @@ source "$SCRIPT_DIR/detect-platform.sh"
 # Default values
 TITLE=""
 BODY=""
+BODY_FILE=""
 BASE_BRANCH=""
 HEAD_BRANCH=""
 LABELS=""
@@ -135,37 +136,57 @@ Examples:
     $(basename "$0") -i 42 -b "Implements the feature described in #42"
     $(basename "$0") -t "WIP: New feature" --draft
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
+}
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
 }
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
     case $1 in
         -t|--title)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             TITLE="$2"
             shift 2
             ;;
         -b|--body)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BODY="$2"
             shift 2
             ;;
+        --body-file)
+            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
+            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
+            BODY_FILE="$2"
+            shift 2
+            ;;
         -B|--base)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             BASE_BRANCH="$2"
             shift 2
             ;;
         -H|--head)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             HEAD_BRANCH="$2"
             shift 2
             ;;
         -l|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABELS="$2"
             shift 2
             ;;
         -m|--milestone)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             MILESTONE="$2"
             shift 2
             ;;
         -i|--issue)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ISSUE="$2"
             shift 2
             ;;
@@ -183,6 +204,19 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+# R3 (2026-08-29): resolve --body-file into BODY (file or stdin '-');
+# exclusive with an explicit --body/--comment value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$BODY" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        BODY=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        BODY=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
 # If no title but issue provided, generate title
 if [[ -z "$TITLE" ]] && [[ -n "$ISSUE" ]]; then
     TITLE="Fixes #$ISSUE"
@@ -266,7 +300,9 @@ case "$PLATFORM" in
         [[ -n "$LABELS" ]] && CMD+=(--label "$LABELS")
         [[ -n "$MILESTONE" ]] && CMD+=(--milestone "$MILESTONE")
         [[ "$DRAFT" == true ]] && CMD+=(--draft)
-        "${CMD[@]}"
+        prov_rc=0
+        "${CMD[@]}" || prov_rc=$?
+        [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         ;;
     gitea)
         # tea pull create syntax. Always pass --repo because tea repo inference

packages/mosaic/framework/tools/git/pr-diff.sh

@@ -13,21 +13,33 @@ OUTPUT_FILE=""
 REPO_OVERRIDE=""
 HOST_OVERRIDE=""
 
+# Usage-error contract (R4): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: pr-diff.sh -n <pr_number> [-r owner/repo] [--host host] [-o <output_file>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -o|--output)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             OUTPUT_FILE="$2"
             shift 2
             ;;
         -r|--repo)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
         --host)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             HOST_OVERRIDE="$2"
             shift 2
             ;;
@@ -40,18 +52,18 @@ while [[ $# -gt 0 ]]; do
             echo "      --host     Gitea host for --repo API calls (or set GITEA_HOST/GITEA_URL)"
             echo "  -o, --output   Output file (optional, prints to stdout if omitted)"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)" >&2
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then

packages/mosaic/framework/tools/git/pr-edit.sh

@@ -11,6 +11,7 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 TITLE=""
 BODY=""
+BODY_FILE=""
 BASE_BRANCH=""
 DRAFT_MODE=""
 LOGIN_OVERRIDE=""
@@ -50,38 +51,59 @@ Options:
     -H, --host HOST        Explicit Gitea host (required with --repo off-host)
     -h, --help             Show this help message
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
+}
+
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
 }
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        -n|--number) PR_NUMBER="${2:-}"; shift 2 ;;
-        -t|--title) TITLE="${2:-}"; shift 2 ;;
-        -b|--body) BODY="${2:-}"; shift 2 ;;
-        -B|--base) BASE_BRANCH="${2:-}"; shift 2 ;;
+        -n|--number) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; PR_NUMBER="${2:-}"; shift 2 ;;
+        -t|--title) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; TITLE="${2:-}"; shift 2 ;;
+        -b|--body) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; BODY="${2:-}"; shift 2 ;;
+        --body-file) [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"; BODY_FILE="$2"; shift 2 ;;
+        -B|--base) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; BASE_BRANCH="${2:-}"; shift 2 ;;
         --draft)
-            [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
+            [[ "$DRAFT_MODE" != "ready" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
             DRAFT_MODE="draft"; shift ;;
         --ready)
-            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 1; }
+            [[ "$DRAFT_MODE" != "draft" ]] || { echo "Error: --draft and --ready are mutually exclusive" >&2; exit 2; }
             DRAFT_MODE="ready"; shift ;;
-        -l|--login) LOGIN_OVERRIDE="${2:-}"; shift 2 ;;
-        -r|--repo) REPO_OVERRIDE="${2:-}"; shift 2 ;;
-        -H|--host) HOST_OVERRIDE="${2:-}"; shift 2 ;;
+        -l|--login) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; LOGIN_OVERRIDE="${2:-}"; shift 2 ;;
+        -r|--repo) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; REPO_OVERRIDE="${2:-}"; shift 2 ;;
+        -H|--host) [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"; HOST_OVERRIDE="${2:-}"; shift 2 ;;
         -h|--help) usage 0 ;;
         *) echo "Unknown option: $1" >&2; usage ;;
     esac
 done
 
-[[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 1; }
-[[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 1; }
+# R3 (2026-08-29): resolve --body-file into BODY (file or stdin '-');
+# exclusive with an explicit --body value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$BODY" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        BODY=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        BODY=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
+[[ -n "$PR_NUMBER" ]] || { echo "Error: Pull request number is required (-n)" >&2; exit 2; }
+[[ "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]] || { echo "Error: Pull request number must be a positive integer" >&2; exit 2; }
 if [[ -z "$TITLE" && -z "$BODY" && -z "$BASE_BRANCH" && -z "$DRAFT_MODE" ]]; then
     echo "Error: At least one edit option is required" >&2
-    exit 1
+    exit 2
 fi
 [[ -z "$REPO_OVERRIDE" || "$REPO_OVERRIDE" =~ ^[^/[:space:]]+/[^/[:space:]]+$ ]] || {
     echo "Error: --repo must be OWNER/REPO" >&2
-    exit 1
+    exit 2
 }
 
 if [[ -n "$HOST_OVERRIDE" || -n "$REPO_OVERRIDE" ]]; then
@@ -92,18 +114,24 @@ fi
 
 case "$PLATFORM" in
     github)
-        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 1; }
+        [[ -z "$LOGIN_OVERRIDE" ]] || { echo "Error: --login is only valid for Gitea" >&2; exit 2; }
         if [[ -n "$TITLE" || -n "$BODY" || -n "$BASE_BRANCH" ]]; then
             CMD=(gh pr edit "$PR_NUMBER")
             [[ -n "$TITLE" ]] && CMD+=(--title "$TITLE")
             [[ -n "$BODY" ]] && CMD+=(--body "$BODY")
             [[ -n "$BASE_BRANCH" ]] && CMD+=(--base "$BASE_BRANCH")
-            "${CMD[@]}"
+            prov_rc=0
+            "${CMD[@]}" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         if [[ "$DRAFT_MODE" == "draft" ]]; then
-            gh pr ready "$PR_NUMBER" --undo
+            prov_rc=0
+            gh pr ready "$PR_NUMBER" --undo || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         elif [[ "$DRAFT_MODE" == "ready" ]]; then
-            gh pr ready "$PR_NUMBER"
+            prov_rc=0
+            gh pr ready "$PR_NUMBER" || prov_rc=$?
+            [[ "$prov_rc" -eq 0 ]] || { echo "Error: provider command failed (exit ${prov_rc}; provider failure, not a usage error)" >&2; exit 1; }
         fi
         ;;
     gitea)

packages/mosaic/framework/tools/git/pr-list.sh

@@ -34,29 +34,41 @@ Examples:
     $(basename "$0") -s merged -a username    # Merged PRs by user
     $(basename "$0") --repo ddk/ai-bma         # List PRs from anywhere
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # Parse arguments
+# Usage-error contract (R4): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -s|--state)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             STATE="$2"
             shift 2
             ;;
-        -l|--label)
+        -l|--label|--labels)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABEL="$2"
             shift 2
             ;;
         -a|--author)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             AUTHOR="$2"
             shift 2
             ;;
         -n|--limit)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LIMIT="$2"
             shift 2
             ;;
         -r|--repo)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
@@ -64,8 +76,7 @@ while [[ $# -gt 0 ]]; do
             usage 0
             ;;
         *)
-            echo "Unknown option: $1" >&2
-            usage
+            usage_error "unknown option: $1"
             ;;
     esac
 done

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--no-ci-expected] [--co-author-trailers --escalate-to PRINCIPAL]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--no-ci-expected] [--base-line BRANCH] [--co-author-trailers --escalate-to PRINCIPAL]
 
 set -euo pipefail
 
@@ -30,6 +30,12 @@ Options:
     -d, --delete-branch     Delete the head branch after merge
         --dry-run           Run metadata/login preflight without merging
         --expect-head SHA   Refuse unless the PR head matches this full commit SHA
+        --base-line BRANCH  Documented intra-line exception (B5, ruled
+                            2026-08-29): authorize a merge whose base is
+                            neither main nor next (stacked PR lines). The
+                            value must MATCH the PR base; all other gates
+                            (queue guard, head pin, CI) still run and the
+                            exception is recorded in the merge audit.
         --no-ci-expected    Assert the target repository has no CI: forward --no-ci-expected to the queue guard (requires repository admin)
         --co-author-trailers Build verified trailers from linked PR commit authors
         --escalate-to NAME  Named principal for an unresolved-author BLOCK
@@ -46,6 +52,7 @@ EOF
 }
 
 # Parse arguments
+BASE_LINE_OVERRIDE=""
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
@@ -64,6 +71,11 @@ while [[ $# -gt 0 ]]; do
             DRY_RUN=true
             shift
             ;;
+        --base-line)
+            [[ $# -ge 2 ]] || { echo "Error: --base-line requires a branch name." >&2; exit 1; }
+            BASE_LINE_OVERRIDE="$2"
+            shift 2
+            ;;
         --expect-head)
             if [[ $# -lt 2 ]]; then
                 echo "Error: --expect-head requires one full commit SHA." >&2
@@ -172,8 +184,17 @@ if [[ "$DECL_STATE" == valid && "$DECL_SCHEMA" == 2 ]]; then
 else
     repo_decl_warn_absent_irreversible "pr-merge"
     if [[ "$BASE_BRANCH" != "main" && "$BASE_BRANCH" != "next" ]]; then
-        echo "Error: Mosaic policy allows merges only for PRs targeting 'main' or 'next' (found '$BASE_BRANCH')." >&2
-        exit 1
+        if [[ -n "$BASE_LINE_OVERRIDE" && "$BASE_LINE_OVERRIDE" != "$BASE_BRANCH" ]]; then
+            echo "Error: --base-line '$BASE_LINE_OVERRIDE' does not match the PR base '$BASE_BRANCH' (refusing; the exception must name the real base)." >&2
+            exit 1
+        fi
+        if [[ "$BASE_LINE_OVERRIDE" == "$BASE_BRANCH" ]]; then
+            echo "audit: base-line exception — merge into '$BASE_BRANCH' authorized by explicit --base-line (B5 ruling 2026-08-29); queue guard, head pin, and CI gates unchanged." >&2
+        else
+            echo "Error: Mosaic policy allows merges only for PRs targeting 'main' or 'next' (found '$BASE_BRANCH')." >&2
+            echo "  A ruled intra-line merge may pass --base-line '$BASE_BRANCH' (same gates; the exception is recorded)." >&2
+            exit 1
+        fi
     fi
 fi
 if [[ -z "$HEAD_BRANCH" || -z "$HEAD_REPO" || ! "$HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then

packages/mosaic/framework/tools/git/pr-metadata.sh

@@ -12,13 +12,23 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 OUTPUT_FILE=""
 
+# Usage-error contract (R4): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: pr-metadata.sh -n <pr_number> [-o <output_file>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -o|--output)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             OUTPUT_FILE="$2"
             shift 2
             ;;
@@ -29,18 +39,18 @@ while [[ $# -gt 0 ]]; do
             echo "  -n, --number   PR number (required)"
             echo "  -o, --output   Output file (optional, prints to stdout if omitted)"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1" >&2
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)" >&2
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 write_metadata() {

packages/mosaic/framework/tools/git/pr-review.sh

@@ -39,64 +39,116 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 ACTION=""
 COMMENT=""
+BODY_FILE=""
 LOGIN_OVERRIDE=""
 REPO_OVERRIDE=""
 HOST_OVERRIDE=""
 
+# Usage-error contract (R4, 2026-08-28): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1), so a
+# caller or stop gate can tell an invocation defect from a delivery blocker.
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: pr-review.sh -n <pr_number> -a <action> [-b <comment>] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -a|--action)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             ACTION="$2"
             shift 2
             ;;
-        -c|--comment)
+        -b|--body|-c|--comment)
+            # R1 (2026-08-28): --body is the canonical flag; -c/--comment stays
+            # a backward-compatible alias.
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             COMMENT="$2"
             shift 2
             ;;
+        --body-file)
+            # R3: body from file (or '-' = stdin); mutually exclusive with --body.
+            [[ $# -ge 2 && "$2" != --* ]] || usage_error "option $1 requires a path (or - for stdin)"
+            BODY_FILE="$2"
+            shift 2
+            ;;
         -l|--login)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LOGIN_OVERRIDE="$2"
             shift 2
             ;;
         -r|--repo)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
         -H|--host)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             HOST_OVERRIDE="$2"
             shift 2
             ;;
         -h|--help)
-            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>] [-r owner/repo] [-H host]"
+            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-b <comment>] [--login <name>] [-r owner/repo] [-H host]"
             echo ""
             echo "Options:"
             echo "  -n, --number   PR number (required)"
             echo "  -a, --action   Review action: approve, request-changes, comment (required)"
-            echo "  -c, --comment  Review comment (required for request-changes)"
+            echo "  -b, --body     Review comment (required for request-changes; canonical)"
+            echo "  -c, --comment  Alias for --body"
             echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
             echo "  -r, --repo     Explicit owner/repo slug (skips git-remote slug inference)"
             echo "  -H, --host     Explicit Gitea host (skips remote-host inference)"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential/verification failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
+# R3 (2026-08-29): resolve --body-file into COMMENT (file or stdin '-');
+# exclusive with an explicit --body/--comment value.
+if [[ -n "$BODY_FILE" ]]; then
+    [[ -z "$COMMENT" ]] || usage_error "--body-file and --body are mutually exclusive"
+    if [[ "$BODY_FILE" == "-" ]]; then
+        COMMENT=$(cat) || usage_error "could not read body from stdin"
+    else
+        [[ -r "$BODY_FILE" ]] || usage_error "body file not readable: $BODY_FILE"
+        COMMENT=$(cat "$BODY_FILE") || usage_error "could not read body file: $BODY_FILE"
+    fi
+fi
+
+
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 if [[ -z "$ACTION" ]]; then
-    echo "Error: Action is required (-a): approve, request-changes, comment"
-    exit 1
+    usage_error "Action is required (-a/--action): approve, request-changes, comment"
+fi
+
+# Validate the action BEFORE any provider contact (codex review of PR #1464:
+# an unsupported --action previously reached platform detection and could
+# touch the provider before failing with a provider-class status).
+case "$ACTION" in
+    approve|request-changes|comment) ;;
+    *) usage_error "unknown action '$ACTION': approve, request-changes, comment" ;;
+esac
+
+# Body-required actions fail fast too (codex follow-up on PR #1464):
+# request-changes and comment both require a body; validate before any
+# provider contact.
+if [[ ( "$ACTION" == "request-changes" || "$ACTION" == "comment" ) && -z "$COMMENT" ]]; then
+    usage_error "comment required for $ACTION (-b/--body)"
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then
@@ -679,15 +731,18 @@ PY
 if [[ "$PLATFORM" == "github" ]]; then
     case $ACTION in
         approve)
-            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"}
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"} || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub approve failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
             echo "Approved GitHub PR #$PR_NUMBER"
             ;;
         request-changes)
             if [[ -z "$COMMENT" ]]; then
-                echo "Error: Comment required for request-changes"
-                exit 1
+                usage_error "comment required for request-changes (-b/--body)"
             fi
-            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT"
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT" || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub request-changes failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
             echo "Requested changes on GitHub PR #$PR_NUMBER"
             ;;
         comment)
@@ -695,12 +750,13 @@ if [[ "$PLATFORM" == "github" ]]; then
                 echo "Error: Comment required"
                 exit 1
             fi
-            gh pr review "$PR_NUMBER" --comment --body "$COMMENT"
+            gh_rc=0
+            gh pr review "$PR_NUMBER" --comment --body "$COMMENT" || gh_rc=$?
+            [[ "$gh_rc" -eq 0 ]] || { echo "Error: GitHub review comment failed (gh exit $gh_rc; provider failure, not a usage error)" >&2; exit 1; }
             echo "Added review comment to GitHub PR #$PR_NUMBER"
             ;;
         *)
-            echo "Error: Unknown action: $ACTION"
-            exit 1
+            usage_error "unknown action: $ACTION"
             ;;
     esac
 elif [[ "$PLATFORM" == "gitea" ]]; then
@@ -738,8 +794,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             ;;
         request-changes)
             if [[ -z "$COMMENT" ]]; then
-                echo "Error: Comment required for request-changes"
-                exit 1
+                usage_error "comment required for request-changes (-b/--body)"
             fi
             # Best-effort host for credential resolution only (gitea_resolve_api_for_login
             # below re-derives the real host from HOST_OVERRIDE/remote independently and
@@ -794,8 +849,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
             echo "Added and verified comment on Gitea PR #$PR_NUMBER (comment ID $comment_id)"
             ;;
         *)
-            echo "Error: Unknown action: $ACTION"
-            exit 1
+            usage_error "unknown action: $ACTION"
             ;;
     esac
 else

packages/mosaic/framework/tools/git/pr-view.sh

@@ -11,13 +11,23 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 REPO_OVERRIDE=""
 
+# Usage-error contract (R4): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    echo "Usage: pr-view.sh -n <pr_number> [-r owner/repo] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$2"
             shift 2
             ;;
         -r|--repo)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
@@ -28,18 +38,18 @@ while [[ $# -gt 0 ]]; do
             echo "  -n, --number   PR number (required)"
             echo "  -r, --repo     Repository slug (default: infer from git origin)"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then

packages/mosaic/framework/tools/git/test-git-credential-mosaic.sh

@@ -34,20 +34,23 @@ REPO_DIR="$WORK_DIR/repo"
 BRAIN_DIR="$WORK_DIR/brain"
 SPOOL_DIR="$WORK_DIR/spool"
 SVC_STORE="$FAKE_HOME/.config/mosaic/secrets/gitea-tokens"
-# Mirror the real deployed layout (~/.config/mosaic/tools/{git,_lib}/) under the
+# Mirror the real deployed layout (~/.mosaic/tools/{git,_lib}/) under the
 # fake HOME: git-credential-mosaic resolves its credentials.sh sibling via a
 # script-relative path (BASH_SOURCE), so the copy must live next to a stubbed
 # _lib/credentials.sh, not the real one, to keep this test hermetic.
-HELPER="$FAKE_HOME/.config/mosaic/tools/git/git-credential-mosaic"
+HELPER="$FAKE_HOME/.mosaic/tools/git/git-credential-mosaic"
+IMPL="$FAKE_HOME/.mosaic/tools/git/git-credential-mosaic.impl"
 
 rm -rf "$WORK_DIR"
 mkdir -p "$SVC_STORE" \
-         "$FAKE_HOME/.config/mosaic/tools/git" \
-         "$FAKE_HOME/.config/mosaic/tools/_lib" \
+         "$FAKE_HOME/.mosaic/tools/git" \
+         "$FAKE_HOME/.mosaic/tools/_lib" \
          "$REPO_DIR" "$BRAIN_DIR"
 
 cp "$SCRIPT_DIR/git-credential-mosaic" "$HELPER"
 chmod +x "$HELPER"
+cp "$SCRIPT_DIR/git-credential-mosaic.impl" "$IMPL"
+chmod +x "$IMPL"
 
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" config user.email "[email protected]"
@@ -55,7 +58,7 @@ git -C "$REPO_DIR" config user.name "Test"
 
 # Fake shared-account credential loader — stands in for
 # tools/_lib/credentials.sh's load_credentials(), scoped to this test only.
-cat > "$FAKE_HOME/.config/mosaic/tools/_lib/credentials.sh" <<'SH'
+cat > "$FAKE_HOME/.mosaic/tools/_lib/credentials.sh" <<'SH'
 load_credentials() {
   case "$1" in
     gitea-mosaicstack) GITEA_URL="https://git.mosaicstack.dev"; GITEA_TOKEN="shared-mosaicstack-token"; export GITEA_URL GITEA_TOKEN; return 0 ;;
@@ -82,7 +85,7 @@ run_helper() {
   (
     cd "$REPO_DIR"
     env -i HOME="$FAKE_HOME" PATH="$PATH" MOSAIC_CREDENTIAL_SPOOL="$SPOOL_DIR" "$@" \
-      bash "$HELPER" get <<EOF
+      "$HELPER" get <<EOF
 host=$host
 username=$username_in
 
@@ -90,6 +93,80 @@ EOF
   )
 }
 
+# ── Lineage harness (rev-code-02 F1/F2 rework) ─────────────────────────────
+# Establishes a seat CALLER the way production does — frozen into an
+# ancestor's exec environment — instead of injecting MOSAIC_AGENT_NAME into
+# the helper's own env. Two scripts are generated into WORK_DIR:
+#
+#   lineage-root.sh  (pid A): invoked with a fence marker and NO agent name.
+#       With a non-empty caller arg it forks the carrier (pid C); with an
+#       empty caller it forks the helper directly (deterministic anonymous
+#       lineage even when the suite itself runs inside a seat).
+#   lineage-carrier.sh (pid C): MOSAIC_AGENT_NAME=<caller> frozen at exec;
+#       forks the helper (pid D) with a fully controlled env.
+#
+# The helper's walk then sees exactly: self -> C(caller) or D-direct ->
+# A(fence, empty name -> stop). EXTRA assignments ride pid D's environment
+# (that is where a rewrite would live — which is the point of the F1 arms).
+cat > "$WORK_DIR/lineage-root.sh" <<'LINROOT'
+#!/usr/bin/env bash
+# pid A — lineage root. Args: <caller> <carrier-script> <helper> <spool>
+# <brain> <repo> [extra KEY=VALUE...]
+set -u
+caller="$1"; carrier="$2"; helper="$3"; spool="$4"; brain="$5"; repo="$6"; shift 6
+if [ -n "$caller" ]; then
+  env MOSAIC_AGENT_NAME="$caller" PATH="$PATH" HOME="$HOME" \
+    bash "$carrier" "$helper" "$spool" "$brain" "$repo" "$@"
+else
+  env -i HOME="$HOME" PATH="$PATH" MOSAIC_CREDENTIAL_SPOOL="$spool" \
+       MOSAIC_BRAIN_HOME="$brain" "$@" "$helper" get
+fi
+LINROOT
+cat > "$WORK_DIR/lineage-carrier.sh" <<'LINCARR'
+#!/usr/bin/env bash
+# pid C — the caller's frozen environment. Forks the helper (pid D).
+set -u
+helper="$1"; spool="$2"; brain="$3"; repo="$4"; shift 4
+cd "$repo"
+env -i HOME="$HOME" PATH="$PATH" MOSAIC_CREDENTIAL_SPOOL="$spool" \
+     MOSAIC_BRAIN_HOME="$brain" "$@" "$helper" get
+LINCARR
+chmod +x "$WORK_DIR/lineage-root.sh" "$WORK_DIR/lineage-carrier.sh"
+
+run_lineage() {
+  # run_lineage <caller|empty-for-anonymous> [helper-env KEY=VALUE...]
+  local caller="$1"; shift
+  printf 'host=git.mosaicstack.dev\nusername=probe\n\n' | \
+    env -i HOME="$FAKE_HOME" PATH="$PATH" MOSAIC_CREDENTIAL_LINEAGE_FENCE=1 \
+      bash "$WORK_DIR/lineage-root.sh" "$caller" "$WORK_DIR/lineage-carrier.sh" \
+      "$HELPER" "$SPOOL_DIR" "$BRAIN_DIR" "$REPO_DIR" "$@"
+}
+
+assert_refused_lineage() {
+  # assert_refused_lineage <desc> <caller> <want-reason> [helper-env...]
+  local desc="$1" caller="$2" want="$3"; shift 3
+  local stderr_file="$WORK_DIR/stderr-lin.tmp" rc stdout
+  : > "$stderr_file"
+  set +e
+  stdout=$(run_lineage "$caller" "$@" 2>"$stderr_file")
+  rc=$?
+  set -e
+  local stderr; stderr=$(cat "$stderr_file")
+  if [[ "$rc" -eq 0 ]]; then
+    echo "FAIL: $desc — expected nonzero exit, got 0 (stdout='$stdout')" >&2; fail=1
+  fi
+  if [[ -n "$stdout" ]]; then
+    echo "FAIL: $desc — expected empty stdout, got '$stdout'" >&2; fail=1
+  fi
+  if [[ -n "$want" && "$stderr" != *"$want"* ]]; then
+    echo "FAIL: $desc — stderr lacks '$want':" >&2; echo "$stderr" >&2; fail=1
+  fi
+  if [[ "$stdout$stderr" == *"seatG-slot-token"* || "$stdout$stderr" == *"seatE-slot-token"* \
+     || "$stdout$stderr" == *"shared-mosaicstack-token"* || "$stdout$stderr" == *"shared-usc-token"* ]]; then
+    echo "FAIL: $desc — a slot or shared token VALUE appeared in output" >&2; fail=1
+  fi
+}
+
 # A refusal must be observable in four independent ways: nonzero exit, EMPTY
 # stdout, a stderr diagnostic naming the identity and host, and — the assertion
 # that actually catches a regression to the old behavior — NO shared token value
@@ -222,7 +299,10 @@ fi
 # ---------------------------------------------------------------------------
 mkdir -p "$BRAIN_DIR/fleet/agents/seatE/secrets"
 echo -n "seatE-slot-token" > "$BRAIN_DIR/fleet/agents/seatE/secrets/gitea-mosaicstack-seatE.token"
-out=$(run_helper "git.mosaicstack.dev" "seatE" MOSAIC_BRAIN_HOME="$BRAIN_DIR")
+chmod 600 "$BRAIN_DIR/fleet/agents/seatE/secrets/gitea-mosaicstack-seatE.token"
+# Seat arms run through the lineage harness below (rev-code-02 F1/F2 rework):
+# a seat caller must be established by ancestry, not by the helper's own env.
+out=$(run_lineage seatE MOSAIC_AGENT_NAME=seatE MOSAIC_GIT_IDENTITY=seatE)
 assert_eq "seat reads its own slot: username" "username=seatE" "$(echo "$out" | grep '^username=')"
 assert_eq "seat reads its own slot: password" "password=seatE-slot-token" "$(echo "$out" | grep '^password=')"
 
@@ -236,8 +316,8 @@ assert_eq "seat reads its own slot: password" "password=seatE-slot-token" "$(ech
 # ---------------------------------------------------------------------------
 mkdir -p "$BRAIN_DIR/fleet/agents/seatF/secrets"
 echo -n "seatF-SERVICE-STORE-token" > "$SVC_STORE/gitea-mosaicstack-seatF.token"
-assert_fail_closed "seat with empty slot does NOT fall back to the framework store" \
-  "git.mosaicstack.dev" "seatF" "fleet/agents/seatF/secrets" MOSAIC_BRAIN_HOME="$BRAIN_DIR"
+assert_refused_lineage "seat with empty slot does NOT fall back to the framework store" \
+  seatF no-token-for-identity MOSAIC_AGENT_NAME=seatF MOSAIC_GIT_IDENTITY=seatF
 : > "$WORK_DIR/stderr.tmp"
 set +e
 xstore_out=$(run_helper "git.mosaicstack.dev" "seatF" MOSAIC_BRAIN_HOME="$BRAIN_DIR" 2>"$WORK_DIR/stderr.tmp")
@@ -288,7 +368,7 @@ assert_eq "unknown host on a fleet host: still passthrough, not a refusal" "" "$
 # 13. Non-"get" verb (store/erase) -> exit 0, no output (git-credential
 #     protocol: this helper only implements get).
 # ---------------------------------------------------------------------------
-store_out=$(cd "$REPO_DIR" && env -i HOME="$FAKE_HOME" PATH="$PATH" bash "$HELPER" store <<EOF
+store_out=$(cd "$REPO_DIR" && env -i HOME="$FAKE_HOME" PATH="$PATH" "$HELPER" store <<EOF
 host=git.mosaicstack.dev
 username=no-such-agent
 password=whatever
@@ -310,7 +390,7 @@ hostile_spool="$WORK_DIR/spool-hostile"
   cd "$hostile_dir"
   env -i HOME="$FAKE_HOME" PATH="$PATH" MOSAIC_CREDENTIAL_SPOOL="$hostile_spool" \
     MOSAIC_GIT_IDENTITY=no-such-agent \
-    bash "$HELPER" get <<EOF >/dev/null 2>&1
+    "$HELPER" get <<EOF >/dev/null 2>&1
 host=git.mosaicstack.dev
 username=no-such-agent
 
@@ -349,7 +429,7 @@ nospool_err=$(
   cd "$REPO_DIR"
   env -i HOME="$FAKE_HOME" PATH="$PATH" MOSAIC_CREDENTIAL_SPOOL="$unwritable_spool" \
     MOSAIC_GIT_IDENTITY=no-such-agent \
-    bash "$HELPER" get <<EOF 2>&1 >/dev/null
+    "$HELPER" get <<EOF 2>&1 >/dev/null
 host=git.mosaicstack.dev
 username=no-such-agent
 
@@ -365,6 +445,193 @@ if [[ "$nospool_err" != *"NOT WRITTEN"* ]]; then
   fail=1
 fi
 
+# ---------------------------------------------------------------------------
+# 11. P5-RM-006 (+r1 rework) — caller identity from exec-frozen ancestry.
+#    A seat caller is established by lineage, not by the helper's own env;
+#    disagreement anywhere in the lineage is a rewrite and refuses; an
+#    anonymous caller resolves NOTHING on a fleet host (seat or service);
+#    a loose seat-slot mode refuses. Enforcement-removal red control at 11h.
+# ---------------------------------------------------------------------------
+mkdir -p "$BRAIN_DIR/fleet/agents/seatG/secrets"
+echo -n "seatG-slot-token" > "$BRAIN_DIR/fleet/agents/seatG/secrets/gitea-mosaicstack-seatG.token"
+chmod 600 "$BRAIN_DIR/fleet/agents/seatG/secrets/gitea-mosaicstack-seatG.token"
+
+# 11a. Cross-seat negative (lineage seatE, env ident=seatG): still refused.
+assert_refused_lineage "seat cannot override identity to another seat's slot" \
+  seatE cross-seat-identity-refused MOSAIC_GIT_IDENTITY=seatG
+
+# 11b. Seat asking for a SERVICE identity: cross-seat territory.
+assert_refused_lineage "seat cannot resolve a service identity either" \
+  seatE cross-seat-identity-refused MOSAIC_GIT_IDENTITY=agentA
+
+# 11c. Anonymous caller asking for a SEAT slot: refused (T94 jarvis@ class).
+assert_refused_lineage "anonymous caller cannot resolve a seat slot on a fleet host" \
+  "" anonymous-credential-refused MOSAIC_GIT_IDENTITY=seatG
+
+# 11d. Anonymous caller asking for a SERVICE identity: ALSO refused
+#     (rev-code-02 F2 — credentialed services are seats; the legacy store is
+#     not anonymously reachable on fleet hosts).
+assert_refused_lineage "anonymous caller cannot resolve a legacy service credential either" \
+  "" anonymous-credential-refused MOSAIC_GIT_IDENTITY=agentA
+
+# 11e. Slot permissions: a group-readable slot is refused; mode restored -> serves.
+chmod 644 "$BRAIN_DIR/fleet/agents/seatG/secrets/gitea-mosaicstack-seatG.token"
+assert_refused_lineage "loose slot mode is refused" \
+  seatG slot-permission-violation MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG
+chmod 600 "$BRAIN_DIR/fleet/agents/seatG/secrets/gitea-mosaicstack-seatG.token"
+out=$(run_lineage seatG MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG)
+assert_eq "mode restored to 600: seatG serves again" "password=seatG-slot-token" "$(echo "$out" | grep '^password=')"
+
+# 11f. rev-code-02 F1 repro: dual-variable override (caller lineage seatE,
+#     helper env carrying MOSAIC_AGENT_NAME=seatG AND MOSAIC_GIT_IDENTITY=seatG).
+assert_refused_lineage "F1: dual MOSAIC_AGENT_NAME+MOSAIC_GIT_IDENTITY override refused" \
+  seatE caller-identity-spoof-refused MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG
+
+# 11g. Stripped lineage still serves the rightful seat: caller frozen at the
+#     ancestor, helper env clean (self empty), own ident.
+out=$(run_lineage seatE MOSAIC_GIT_IDENTITY=seatE)
+assert_eq "lineage consensus with stripped self still serves the owning seat" \
+  "password=seatE-slot-token" "$(echo "$out" | grep '^password=')"
+
+# 11h. RED CONTROL: delete the ancestry binding between markers from a copy
+#     of the IMPLEMENTATION (run directly with the clean marker — a red control
+#     measures the binding itself, deliberately not through the wrapper);
+#     the F1 dual-override request must then RESOLVE seatG's token — the
+#     exact measured failure — proving the binding is the enforcement.
+RED_HELPER="$WORK_DIR/red/git-credential-mosaic.impl"
+mkdir -p "$WORK_DIR/red"
+sed '/P5-RM-006r1 ancestry binding begin/,/P5-RM-006r1 ancestry binding end/d' "$IMPL" > "$RED_HELPER"
+chmod +x "$RED_HELPER"
+if cmp -s "$IMPL" "$RED_HELPER"; then
+  echo "FAIL: red control is vacuous — marker deletion removed nothing" >&2
+  fail=1
+fi
+set +e
+red_out=$(printf 'host=git.mosaicstack.dev\nusername=probe\n\n' | \
+  env -i HOME="$FAKE_HOME" PATH="$PATH" MOSAIC_CREDENTIAL_LINEAGE_FENCE=1 \
+    bash "$WORK_DIR/lineage-root.sh" seatE "$WORK_DIR/lineage-carrier.sh" \
+      "$RED_HELPER" "$SPOOL_DIR" "$BRAIN_DIR" "$REPO_DIR" \
+      _MOSAIC_HELPER_CLEAN=1 MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG 2>/dev/null)
+set -e
+if [[ "$(echo "$red_out" | grep '^password=')" != "password=seatG-slot-token" ]]; then
+  echo "FAIL: red control — with the binding removed, the F1 dual-override should have resolved seatG's token, got: $red_out" >&2
+  fail=1
+else
+  echo "ok: red control — binding removed -> F1 dual-override resolves the victim token (the binding is the enforcement)"
+fi
+
+# 11h2. rev-code-02 R1 F1: PATH-shadowed tr/sed/head/grep must not forge the
+#      ancestry. The dual-override request runs with a hostile PATH whose
+#      utilities claim the victim name for every /proc read; the walker uses
+#      only bash builtins, so the shadows never execute and the refusal holds.
+HOSTILE_BIN="$WORK_DIR/hostile-bin"
+mkdir -p "$HOSTILE_BIN"
+for tool in tr sed head grep cat stat; do
+  printf '#!/usr/bin/env bash\ncat >/dev/null\necho "MOSAIC_AGENT_NAME=seatG"\nexit 0\n' > "$HOSTILE_BIN/$tool"
+  chmod +x "$HOSTILE_BIN/$tool"
+done
+assert_refused_lineage "F1-R1: hostile PATH utilities cannot forge ancestry (dual override still refused)" \
+  seatE caller-identity-spoof-refused \
+  MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG PATH="$HOSTILE_BIN:$PATH"
+
+# 11i. Service automation integration arm (rev-code-02 R2 bar): a SERVICE
+#      seat bound by lineage resolves its own slot — the brain-git-sync shape.
+mkdir -p "$BRAIN_DIR/fleet/agents/svc-fixture/secrets"
+echo -n "svc-fixture-slot-token" > "$BRAIN_DIR/fleet/agents/svc-fixture/secrets/gitea-mosaicstack-svc-fixture.token"
+chmod 600 "$BRAIN_DIR/fleet/agents/svc-fixture/secrets/gitea-mosaicstack-svc-fixture.token"
+out=$(run_lineage svc-fixture MOSAIC_AGENT_NAME=svc-fixture MOSAIC_GIT_IDENTITY=svc-fixture)
+assert_eq "service automation with bound seat lineage resolves its own slot" \
+  "password=svc-fixture-slot-token" "$(echo "$out" | grep '^password=')"
+
+# 11j. rev-code-02 R3 B1: BASH_ENV shaping. A read() shadow defined through
+#      BASH_ENV must be refused before any resolution — the guard scrubs and
+#      refuses with bash-environment-injection-refused.
+INJ_SH="$WORK_DIR/inj-read.sh"
+printf 'read() { builtin read -r _x || return 0; printf "MOSAIC_AGENT_NAME=seatG\\n"; return 0; }\n' > "$INJ_SH"
+assert_refused_lineage "F1-R3: BASH_ENV read() shadow is dropped at the wrapper boundary (identity gate governs)" \
+  seatE caller-identity-spoof-refused \
+  MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG BASH_ENV="$INJ_SH"
+
+# 11k. rev-code-02 R3 B1: exported functions (BASH_FUNC_* import) refused too.
+assert_refused_lineage "F1-R3: exported BASH_FUNC_* import never crosses the wrapper boundary (identity gate governs)" \
+  seatE caller-identity-spoof-refused \
+  MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG \
+  'BASH_FUNC_read%%=() { builtin read -r _x || return 0; printf "MOSAIC_AGENT_NAME=seatG\\n"; return 0; }'
+
+# 11l. rev-code-02 R3 B2: hostile stat cannot launder a loose slot. Own-slot
+#      lineage (legit caller), 0644 slot, PATH-shadowed stat reporting 600 —
+#      mode inspection must come from the trusted PATH and still refuse.
+chmod 644 "$BRAIN_DIR/fleet/agents/svc-fixture/secrets/gitea-mosaicstack-svc-fixture.token"
+printf '#!/usr/bin/env bash\necho 600\n' > "$HOSTILE_BIN/stat"
+assert_refused_lineage "F2-R3: hostile stat cannot make a 0644 slot pass as 600 (own-slot path)" \
+  svc-fixture slot-permission-violation \
+  MOSAIC_AGENT_NAME=svc-fixture MOSAIC_GIT_IDENTITY=svc-fixture PATH="$HOSTILE_BIN:$PATH"
+chmod 600 "$BRAIN_DIR/fleet/agents/svc-fixture/secrets/gitea-mosaicstack-svc-fixture.token"
+
+# 11m. rev-code-02 R3 probe 1 through the PRODUCTION ENTRYPOINT: BASH_ENV
+#      defines unset()/exit() no-ops (defeating in-bash scrub/termination).
+#      The python wrapper never passes BASH_ENV across the boundary, so the
+#      implementation cannot be shaped and the dual override still refuses.
+INJ_P1="$WORK_DIR/inj-probe1.sh"
+cat > "$INJ_P1" <<'P1'
+unset() { return 0; }
+exit() { return 0; }
+read() { builtin read -r _x || return 0; printf 'MOSAIC_AGENT_NAME=seatG\n'; return 0; }
+P1
+assert_refused_lineage "F1-R4 probe1: BASH_ENV unset/exit no-ops cannot shape the helper (wrapper boundary)" \
+  seatE caller-identity-spoof-refused \
+  MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG BASH_ENV="$INJ_P1"
+
+# 11n. rev-code-02 R3 probe 2 through the PRODUCTION ENTRYPOINT: declare()
+#      hides imported functions, unsets the marker, printf() forges the
+#      ancestry. Dropped at the wrapper boundary; refusal holds.
+INJ_P2="$WORK_DIR/inj-probe2.sh"
+cat > "$INJ_P2" <<'P2'
+declare() { return 0; }
+printf() { builtin printf '%s' "MOSAIC_AGENT_NAME=seatG"; return 0; }
+read() { builtin read -r _x || return 0; printf 'MOSAIC_AGENT_NAME=seatG\n'; return 0; }
+P2
+assert_refused_lineage "F1-R4 probe2: declare-hide + printf-forge cannot shape the helper (wrapper boundary)" \
+  seatE caller-identity-spoof-refused \
+  MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG BASH_ENV="$INJ_P2"
+
+# 11o. RED CONTROL for the wrapper boundary (enforcement-removal): invoke the
+#      IMPLEMENTATION directly, bypassing the wrapper, with the PROBE-1 shape
+#      (unset/exit no-ops) and a forged clean marker — exactly the falsified
+#      in-bash world the reviewer measured: the refusal prints, exit is
+#      no-oped, execution continues, and the forged ancestry SERVES seatG.
+#      The wrapper boundary is the enforcement; this arm proves it bites.
+set +e
+bypass_out=$(cd "$REPO_DIR" && printf 'host=git.mosaicstack.dev\nusername=probe\n\n' | \
+  env -i HOME="$FAKE_HOME" PATH="$PATH" MOSAIC_CREDENTIAL_SPOOL="$SPOOL_DIR" \
+    MOSAIC_BRAIN_HOME="$BRAIN_DIR" _MOSAIC_HELPER_CLEAN=1 BASH_ENV="$INJ_P1" \
+    MOSAIC_AGENT_NAME=seatG MOSAIC_GIT_IDENTITY=seatG \
+    bash "$IMPL" get 2>/dev/null)
+set -e
+if [[ "$(echo "$bypass_out" | grep -c '^password=')" -lt 1 ]]; then
+  echo "FAIL: wrapper red control — direct shaped .impl should have served (wrapper is the enforcement), got: $bypass_out" >&2
+  fail=1
+else
+  echo "ok: red control — wrapper bypassed + probe1 shape serves (the wrapper boundary is the enforcement)"
+fi
+
+# 11p. Direct .impl invocation WITHOUT the clean marker: refused by the
+#      implementation's own entrypoint assert.
+set +e
+direct_out=$(cd "$REPO_DIR" && printf 'host=git.mosaicstack.dev\nusername=probe\n\n' | \
+  env -i HOME="$FAKE_HOME" PATH="$PATH" MOSAIC_CREDENTIAL_SPOOL="$SPOOL_DIR" \
+    MOSAIC_BRAIN_HOME="$BRAIN_DIR" MOSAIC_GIT_IDENTITY=seatE \
+    bash "$IMPL" get 2>"$WORK_DIR/stderr-direct.tmp")
+direct_rc=$?
+set -e
+if [[ "$direct_rc" -eq 0 || -n "$direct_out" ]]; then
+  echo "FAIL: direct .impl without marker must refuse (got rc=$direct_rc out='$direct_out')" >&2
+  fail=1
+elif ! grep -q 'direct-entrypoint-refused' "$WORK_DIR/stderr-direct.tmp"; then
+  echo "FAIL: direct .impl refusal lacks direct-entrypoint-refused" >&2
+  fail=1
+fi
+
 if [[ "$fail" -eq 0 ]]; then
   echo "git-credential-mosaic identity resolution regression passed"
 fi

packages/mosaic/framework/tools/git/test-issue-assign-usage-contract.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-assign.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-assign-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-assign.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-assign.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-assign.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "Issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -a -l -m --issue --assignee --labels --milestone; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -a --help
+expect_rc 2 "short flag value rejected" -i 5 -a -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -a; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+# 6b. Provider-exit normalization (codex PR #1464): a provider stub exiting
+# 2 (its own usage-error status) must surface as wrapper exit 1, never 2.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+cat > "$BIN_DIR/gh" <<GHSTUB
+#!/usr/bin/env bash
+echo "gh \$*" >> "$PROBE_LOG"
+if [[ "\$1 \$2" == "issue edit" ]]; then exit 2; fi
+exit 0
+GHSTUB
+chmod +x "$BIN_DIR/gh"
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/issue-assign.sh" -i 5 -a someone >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+grep -q "provider" "$ERR_FILE" || fail "GitHub path: normalized provider error missing from stderr"
+
+echo "issue-assign.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-close-usage-contract.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-close.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# The comment is OPTIONAL here (an issue may close without one), so unlike
+# issue-comment there is no missing-comment arm.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-close-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-close.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-close.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-close.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -b -c --issue --body --comment; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Sandbox arms may issue DETECTION reads only (tea login list via the
+# stub); no gh/curl write or read may occur.
+if grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a sandbox arm performed a non-detection provider request:" >&2
+    grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" >&2
+    exit 1
+fi
+if grep -qE '^(gh|curl)' "$PROBE_LOG"; then
+    echo "FAIL: gh or curl was invoked during a sandbox arm:" >&2
+    grep -E '^(gh|curl)' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-close.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-comment-readback.sh

@@ -42,6 +42,8 @@
 #  10. leaves NO temp files behind (POST/GET bodies + metadata) on either the
 #      success or the failure path — nested function-scoped RETURN traps do not
 #      clobber each other and every scratch file is removed on all exit paths.
+#  11. accepts the canonical -b/--body flag exactly like the -c/--comment alias
+#      (R1, 2026-08-28): a full verified write via -b alone.
 
 set -euo pipefail
 
@@ -409,11 +411,28 @@ run_comment() {
     seed_state "$mode"
     (
         cd "$REPO_DIR"
+        # Provisioned seats export MOSAIC_GIT_IDENTITY and MOSAIC_BRAIN_HOME
+        # seat-wide (launcher), and both escape this harness's sandboxed HOME:
+        # detect-platform.sh consults MOSAIC_GIT_IDENTITY BEFORE the repo-local
+        # mosaic.gitIdentity pin, and resolves the brain home (whose
+        # fleet/agents presence arms the no-identity fail-loud branch) from
+        # MOSAIC_BRAIN_HOME before $HOME. Without these explicit empties the
+        # wrapper either resolves the REAL seat-slot token (stub curl rejects
+        # it: the documented HTTP 401) or fails loud before any request.
+        # Set-but-empty reads as unset to detect-platform's "${VAR:-}" forms.
+        # NOTE: keep this comment block ABOVE the assignment chain — a comment
+        # inside a backslash-continued prefix chain terminates the command and
+        # silently demotes every earlier assignment to an unexported subshell
+        # assignment (measured 2026-08-28: the wrapper then ran without
+        # MOSAIC_CREDENTIALS_FILE and the suite died at credential resolution
+        # with zero diagnostic output).
         PATH="$BIN_DIR:$PATH" \
         TMPDIR="$TMP_SCRATCH" \
         HOME="$HOME_DIR" \
         XDG_CONFIG_HOME="$XDG_DIR" \
         MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
+        MOSAIC_GIT_IDENTITY="" \
+        MOSAIC_BRAIN_HOME="" \
         ISSUE_COMMENT_TEA_LOG="$TEA_LOG" \
         ISSUE_COMMENT_CURL_LOG="$CURL_LOG" \
         ISSUE_COMMENT_CURL_ARGV_LOG="$CURL_ARGV_LOG" \
@@ -430,7 +449,7 @@ run_comment() {
         ISSUE_COMMENT_REPO_SLUG="$REPO_SLUG" \
         ISSUE_COMMENT_API_BASE="$API_BASE" \
         ISSUE_COMMENT_API_ROOT="$API_ROOT" \
-        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" -c "$BODY" "$@"
+        "$SCRIPT_DIR/issue-comment.sh" -i "$ISSUE_NUMBER" "${BODY_FLAG:--c}" "$BODY" "$@"
     ) > "$OUTPUT_FILE" 2>&1
 }
 
@@ -614,4 +633,21 @@ done
 # issue_url (already exercised by Case 1's fresh-success), so the tightened check
 # is not rejecting genuine writes.
 
+# Case 11 (R1, 2026-08-28): -b/--body is the canonical comment flag and must
+# drive a full verified write exactly like the -c/--comment alias. BODY_FLAG
+# swaps only the flag spelling; every assertion below is case 1's contract.
+BODY_FLAG="-b"
+run_comment fresh-success
+grep -q 'Added and verified comment on Gitea issue #7 (comment ID 51)' "$OUTPUT_FILE"
+grep -q "^POST $API_BASE/issues/7/comments$" "$CURL_LOG"
+if grep -Eq '^comment |^issue comment ' "$TEA_LOG"; then
+    echo "FAIL: --body write went through tea instead of REST" >&2
+    exit 1
+fi
+grep -q "^GET $API_BASE/issues/comments/51$" "$CURL_LOG"
+grep -q "^POST $API_BASE/issues/7/comments $ACTING_LOGIN$" "$AUTH_LOG"
+assert_no_temp_leak "fresh-success-body-flag"
+assert_token_not_in_argv "fresh-success-body-flag"
+unset BODY_FLAG
+
 echo "issue-comment.sh REST create + exact-id read-back regression passed"

packages/mosaic/framework/tools/git/test-issue-comment-usage-contract.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-comment.sh (R1/R4 remediation, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1), so a caller (or a stop gate)
+# can tell an invocation defect from a delivery blocker. Before this contract
+# the wrapper exited 1 for usage errors with messages on STDOUT, and a
+# value-less flag (-c with no value) died SILENTLY at rc=1 because set -e
+# killed the failed `shift 2`. That silent shape is what full-stopped a fleet
+# seat: a caller could not distinguish "I invoked it wrong" from "delivery is
+# blocked".
+#
+# R1: -b/--body is the canonical comment flag (matching issue-create,
+# issue-edit, pr-create, pr-edit); -c/--comment remains a backward-compatible
+# alias.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. Missing required comment exits 2 (stderr).
+#   5. A value-less flag (-i -b -c -l and long forms) exits 2 with a
+#      "requires a value" message on stderr (the former silent-death class).
+#   6. -b and -c both pass parsing (the run then fails at platform detection
+#      in this non-repo fixture, nonzero and NOT 2), proving alias acceptance
+#      without any provider fixture.
+#   7. No arm performs any provider request: PATH shims for gh/tea/curl
+#      record every invocation and the probe log must stay empty.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-comment-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Provider shims: any invocation is recorded and fails the run at the end.
+# Usage-error arms must exit during argument parsing, before detect_platform,
+# so these prove "no provider request on parser failure".
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+# gh doubles as platform probe AND write path in arm 6b: probes exit 0; the
+# comment write exits 2 (gh's own usage-error status) to prove the wrapper
+# normalizes provider failures to exit 1 instead of propagating 2.
+if [[ "\$1 \$2" == "issue comment" ]]; then exit 2; fi
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-comment.sh" "$@" )
+}
+
+# Hermetic variant for parse-acceptance arms: neutralizes every identity/
+# credential source the wrapper consults (seat env vars, HOME, XDG tea config)
+# so the arm fails at credential resolution in ANY cwd repo, never reading a
+# real token or contacting a provider. Measured 2026-08-28: without this, the
+# arm's outcome depended on incidental URL-resolution state (brain cwd died at
+# URL-not-found; a stack worktree cwd resolved a configured URL, read the real
+# seat token, and invoked the curl stub — the suite then failed its own
+# no-provider-contact check, correctly).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-comment.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage on stdout.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-comment.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, message on stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Missing required comment: rc 2, stderr.
+expect_rc 2 "missing comment exits 2" -i 5
+expect_stderr "comment is required" "missing comment message on stderr"
+
+# 5. Value-less flags: rc 2 with "requires a value" on stderr. The old parser
+# died here silently (set -e on the failed shift 2).
+for flag in -i -b -c -l --issue --body --comment --login; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 6. Alias acceptance at parse level: both -b and -c carry a value past
+# parsing; the wrapper then fails at platform detection (not a git repo)
+# nonzero but NOT as a usage error (rc must not be 2).
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "some text" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6b. GitHub-path exit normalization (codex blocker on 08a00149): gh's own
+# usage errors exit 2; the wrapper must NOT propagate that status (reserved
+# for the wrapper's usage-error contract). With a github remote and a gh stub
+# whose comment write exits 2, the wrapper must exit 1 with the normalized
+# error on stderr.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+git -C "$GH_REPO" config mosaic.gitIdentity ""
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/issue-comment.sh" -i 5 -b "text" >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+grep -q "GitHub comment write failed" "$ERR_FILE" || fail "GitHub path: normalized error missing from stderr"
+grep -q "^gh issue comment" "$PROBE_LOG" || fail "GitHub path: gh write was not invoked"
+
+# R3 body-file arms (2026-08-29): --body-file <path> and '-' (stdin).
+BF_FILE="$WORK_DIR/body.md"
+printf 'line one\nline two\n' > "$BF_FILE"
+
+# File loads the body: parse acceptance then credential-class failure
+# (sandboxed runner: rc nonzero and NOT 2).
+rc=0
+run_wrapper_sandboxed -i 5 --body-file "$BF_FILE" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+[[ "$rc" -ne 0 ]] || fail "body-file arm unexpectedly succeeded in the sandbox"
+[[ "$rc" -ne 2 ]] || fail "body-file arm misclassified credential failure as a usage error"
+
+# Stdin form loads the body the same way.
+rc=0
+printf 'from stdin' | run_wrapper_sandboxed -i 5 --body-file - >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+[[ "$rc" -ne 0 && "$rc" -ne 2 ]] || fail "body-file stdin arm rc=$rc (want nonzero, not 2)"
+
+# Mutually exclusive with --body: rc 2.
+expect_rc 2 "body-file + body exclusive" -i 5 --body-file "$BF_FILE" -b explicit
+expect_stderr "mutually exclusive" "exclusivity message on stderr"
+
+# Missing file: rc 2 naming the path.
+expect_rc 2 "missing body file" -i 5 --body-file "$WORK_DIR/nope.md"
+expect_stderr "not readable" "missing-file message on stderr"
+
+# 7. No provider contact from any usage-error arm (arm 6b's deliberate gh
+# invocation is the only permitted entry in the probe log).
+if grep -v '^gh issue comment' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    grep -v '^gh issue comment' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-comment.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-create-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-create.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-create-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-create.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-create.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-create.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -t exits 2"
+expect_stderr "Title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t -b -l -m --title --body --labels --milestone; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -t smoke -b --help
+expect_rc 2 "short flag value rejected" -t smoke -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "issue-create.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-edit-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-edit.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-edit-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-edit.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-edit.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-edit.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -t -b -l -m --issue --title --body --labels --milestone; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "issue-edit.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-list-usage-contract.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-list.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-list-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-list.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-list.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-list.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -s -l -m -a -n -r --state --label --milestone --assignee --limit --repo; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -s --help
+expect_rc 2 "short flag value rejected" -s -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -s; do
+    rc=0
+    run_wrapper_sandboxed -s open >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "issue-list.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-reopen-usage-contract.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-reopen.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# The comment is OPTIONAL here (an issue may close without one), so unlike
+# issue-comment there is no missing-comment arm.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-reopen-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 0
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-reopen.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-reopen.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-reopen.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required issue number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "issue number is required" "missing -i message on stderr"
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i -b -c --issue --body --comment; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i 5 -b --help
+expect_rc 2 "short flag value rejected" -i 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -i 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Sandbox arms may issue DETECTION reads only (tea login list via the
+# stub); no gh/curl write or read may occur.
+if grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" | grep -q .; then
+    echo "FAIL: a sandbox arm performed a non-detection provider request:" >&2
+    grep -Ev '^(gh|tea|curl) login list' "$PROBE_LOG" >&2
+    exit 1
+fi
+if grep -qE '^(gh|curl)' "$PROBE_LOG"; then
+    echo "FAIL: gh or curl was invoked during a sandbox arm:" >&2
+    grep -E '^(gh|curl)' "$PROBE_LOG" >&2
+    exit 1
+fi
+
+echo "issue-reopen.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-issue-view-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for issue-view.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-view-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/issue-view.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/issue-view.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: issue-view.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -i exits 2"
+expect_stderr "Issue number is required" "missing -i message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -i --issue; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -i --help
+expect_rc 2 "short flag value rejected" -i -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -i; do
+    rc=0
+    run_wrapper_sandboxed -i 5 >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "issue-view.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-lane-brief-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for lane-brief.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/lane-brief-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/lane-brief.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/lane-brief.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "owner/repo" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -r exits 2"
+expect_stderr "required" "missing -r message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -r -m -l -L -n --repo --milestone --label --login --limit; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -r owner/repo -m --help
+expect_rc 2 "short flag value rejected" -r owner/repo -m -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -r; do
+    rc=0
+    run_wrapper_sandboxed -r owner/repo >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "lane-brief.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-milestone-close-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for milestone-close.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-close-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-close.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/milestone-close.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: milestone-close.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -t exits 2"
+expect_stderr "Milestone title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t --title; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -t --help --help
+expect_rc 2 "short flag value rejected" -t --help -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -t; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "milestone-close.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-milestone-create-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for milestone-create.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-create-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-create.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/milestone-create.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: milestone-create.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -t exits 2"
+expect_stderr "Title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t -d --due --title --desc; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -t smoke -d --help
+expect_rc 2 "short flag value rejected" -t smoke -d -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -t; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "milestone-create.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-milestone-list-usage-contract.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Usage-error contract for milestone-list.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/milestone-list-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/milestone-list.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/milestone-list.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: milestone-list.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -s --state; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -s --help
+expect_rc 2 "short flag value rejected" -s -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -s; do
+    rc=0
+    run_wrapper_sandboxed -s open >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+# 6b. Provider-exit normalization (codex PR #1464): a provider stub exiting
+# 2 (its own usage-error status) must surface as wrapper exit 1, never 2.
+GH_REPO="$WORK_DIR/repo-gh"
+mkdir -p "$GH_REPO"
+git -C "$GH_REPO" init -q
+git -C "$GH_REPO" remote add origin https://github.com/acme/widgets.git
+cat > "$BIN_DIR/gh" <<GHSTUB
+#!/usr/bin/env bash
+echo "gh \$*" >> "$PROBE_LOG"
+if [[ "\$1" == "api" ]]; then exit 2; fi
+exit 0
+GHSTUB
+chmod +x "$BIN_DIR/gh"
+rc=0
+(
+    cd "$GH_REPO"
+    PATH="$BIN_DIR:$PATH" MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+        "$SCRIPT_DIR/milestone-list.sh" >"$OUT_FILE" 2>"$ERR_FILE"
+) || rc=$?
+[[ "$rc" -eq 1 ]] || fail "GitHub path: gh exit 2 must normalize to wrapper exit 1 (got $rc)"
+grep -q "provider" "$ERR_FILE" || fail "GitHub path: normalized provider error missing from stderr"
+
+echo "milestone-list.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-close-usage-contract.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-close.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# The comment is OPTIONAL here (an issue may close without one), so unlike
+# issue-comment there is no missing-comment arm.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-close-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-close.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-close.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-close.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -n exits 2"
+expect_stderr "PR number is required" "missing -n message on stderr"
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -n -b -c --number --body --comment; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -n 5 -b --help
+expect_rc 2 "short flag value rejected" -n 5 -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -n 5 "$flag" "closing note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-close.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-create-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-create.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-create-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-create.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-create.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-create.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -t exits 2"
+expect_stderr "Title is required" "missing -t message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -t -b -B -H -l -m -i --title --body --base --head --labels --milestone --issue; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -t smoke -b --help
+expect_rc 2 "short flag value rejected" -t smoke -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b; do
+    rc=0
+    run_wrapper_sandboxed -t "smoke" "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-create.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-diff-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-diff.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-diff-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-diff.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-diff.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-diff.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -n exits 2"
+expect_stderr "PR number is required" "missing -n message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -n -o -r --number --output --repo --host; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -n --help
+expect_rc 2 "short flag value rejected" -n -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -n; do
+    rc=0
+    run_wrapper_sandboxed -n 5 >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-diff.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-edit-usage-contract.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-edit.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-edit-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-edit.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-edit.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-edit.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -n exits 2"
+expect_stderr "Pull request number is required" "missing -n message on stderr"
+expect_rc 2 "no edit option exits 2" -n 5
+expect_stderr "At least one edit option is required" "no-edit-option message on stderr"
+expect_rc 2 "non-integer PR number exits 2" -n abc -t x
+expect_stderr "positive integer" "integer check on stderr"
+expect_rc 2 "mutually exclusive draft/ready exits 2" -n 5 --draft --ready
+expect_stderr "mutually exclusive" "mutual exclusion on stderr"
+expect_rc 2 "bad repo format exits 2" -n 5 -t x -r not-a-slug
+expect_stderr "OWNER/REPO" "repo format on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -n -t -b -B -l -r -H --number --title --body --base --login --repo --host; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -n 5 -t smoke -b --help
+expect_rc 2 "short flag value rejected" -n 5 -t smoke -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b; do
+    rc=0
+    run_wrapper_sandboxed -n 5 "$flag" "value" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-edit.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-list-usage-contract.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-list.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-list-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-list.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-list.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-list.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -s -l -a -n -r --state --label --author --limit --repo; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -s --help
+expect_rc 2 "short flag value rejected" -s -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -s; do
+    rc=0
+    run_wrapper_sandboxed -s open >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-list.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-merge-baseline.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# B5 (ruled 2026-08-29, orch-01-adopted): pr-merge --base-line — the
+# documented intra-line exception. Arms:
+#   1. Base neither main nor next, no flag: policy refusal (rc 1), queue
+#      guard NOT invoked, hint names the exception.
+#   2. Base neither main nor next, matching --base-line: authorized; the
+#      queue guard IS invoked with the same args (rc from the stub proves
+#      gates still run) and the audit line is emitted.
+#   3. Mismatched --base-line (different branch than the PR base): refusal
+#      rc 1 with the mismatch named; queue guard NOT invoked.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-baseline}"
+FIXTURE_DIR="$WORK_DIR/tools/git"
+CALL_LOG="$WORK_DIR/queue-call.log"
+OUT_LOG="$WORK_DIR/out.log"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$FIXTURE_DIR"
+cp "$SCRIPT_DIR/pr-merge.sh" "$FIXTURE_DIR/pr-merge.sh"
+cp "$SCRIPT_DIR/detect-platform.sh" "$FIXTURE_DIR/detect-platform.sh"
+
+cat > "$FIXTURE_DIR/pr-metadata.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' '{"baseRefName":"mosaic-cli-p0","baseRepository":"mosaicstack/stack","headRefName":"mosaic-cli-p2-socket-res","headRefOid":"0123456789abcdef0123456789abcdef01234567","headRepository":"mosaicstack/stack"}'
+SH
+
+cat > "$FIXTURE_DIR/ci-queue-wait.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' "$*" > "${MOSAIC_QUEUE_CALL_LOG:?}"
+exit 42
+SH
+chmod +x "$FIXTURE_DIR"/*.sh
+
+run_case() { # run_case <extra-args...>
+    : > "$CALL_LOG"
+    set +e
+    (
+        cd "$WORK_DIR"
+        export MOSAIC_QUEUE_CALL_LOG="$CALL_LOG"
+        "$FIXTURE_DIR/pr-merge.sh" -n 123 "$@"
+    ) >"$OUT_LOG" 2>&1
+    rc=$?
+    set -e
+}
+
+# 1. No flag: policy refusal, no gate invocation.
+run_case
+[[ "$rc" -eq 1 ]] || { echo "FAIL arm1: rc=$rc want 1" >&2; cat "$OUT_LOG" >&2; exit 1; }
+[[ ! -s "$CALL_LOG" ]] || { echo "FAIL arm1: queue guard ran without authorization" >&2; exit 1; }
+grep -q "only for PRs targeting" "$OUT_LOG" || { echo "FAIL arm1: policy message missing" >&2; exit 1; }
+grep -q -- "--base-line 'mosaic-cli-p0'" "$OUT_LOG" || { echo "FAIL arm1: hint missing" >&2; exit 1; }
+
+# 2. Matching flag: authorized, audit line emitted, gates RUN (stub rc 42).
+run_case --base-line mosaic-cli-p0
+[[ "$rc" -eq 42 ]] || { echo "FAIL arm2: rc=$rc want 42 (gate stub rc must propagate)" >&2; cat "$OUT_LOG" >&2; exit 1; }
+[[ -s "$CALL_LOG" ]] || { echo "FAIL arm2: queue guard NOT invoked despite authorization" >&2; exit 1; }
+grep -q -- '-B mosaic-cli-p2-socket-res' "$CALL_LOG" || { echo "FAIL arm2: guard args wrong" >&2; cat "$CALL_LOG" >&2; exit 1; }
+grep -q "base-line exception" "$OUT_LOG" || { echo "FAIL arm2: audit line missing" >&2; exit 1; }
+
+# 3. Mismatched flag: refusal, mismatch named, no gate invocation.
+run_case --base-line some-other-line
+[[ "$rc" -eq 1 ]] || { echo "FAIL arm3: rc=$rc want 1" >&2; cat "$OUT_LOG" >&2; exit 1; }
+[[ ! -s "$CALL_LOG" ]] || { echo "FAIL arm3: queue guard ran on a refused merge" >&2; exit 1; }
+grep -q "does not match the PR base" "$OUT_LOG" || { echo "FAIL arm3: mismatch message missing" >&2; exit 1; }
+
+echo "pr-merge --base-line exception regression passed (B5)"

packages/mosaic/framework/tools/git/test-pr-metadata-usage-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-metadata.sh (R4, 2026-08-28).
+#
+# issue-edit already uses long-flag-first parsing (-i/--issue, -t/--title,
+# -b/--body, -l/--labels, -m/--milestone); this adds the rc=2 usage-error
+# contract, value checks, and the no-provider-contact proof. Required: -i.
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-metadata-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-metadata.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-metadata.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-metadata.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "[Uu]nknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -n exits 2"
+expect_stderr "PR number is required" "missing -n message on stderr"
+
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -n -o --number --output; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -n --help
+expect_rc 2 "short flag value rejected" -n -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -n; do
+    rc=0
+    run_wrapper_sandboxed -n 5 >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-metadata.sh usage-contract regression passed (R1/R4)"

packages/mosaic/framework/tools/git/test-pr-review-repo-host-override.sh

@@ -218,7 +218,7 @@ if grep -q 'Unknown option' "$OUTPUT_FILE"; then
     cat "$OUTPUT_FILE" >&2
     exit 1
 fi
-grep -q 'Unknown action: bogus-action' "$OUTPUT_FILE"
+grep -q "unknown action 'bogus-action'" "$OUTPUT_FILE"
 
 # --- Case 2: -h/--help documents both overrides.
 HELP_TEXT="$("$SCRIPT_DIR/pr-review.sh" -h)"

packages/mosaic/framework/tools/git/test-pr-review-usage-contract.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Usage-error contract for pr-review.sh (R1/R4, 2026-08-28).
+#
+# R4: usage errors print to STDERR and exit 2, distinct from provider,
+# credential, and verification failures (exit 1). R1: -b/--body is the
+# canonical comment flag; -c/--comment remains a compatible alias.
+# Required: -n AND -a. The comment is required only for the
+# request-changes action (semantic usage check, also rc 2).
+#
+# Arms:
+#   1. --help and -h exit 0 and print usage.
+#   2. Unknown option exits 2 with the message on stderr.
+#   3. Missing required -i exits 2 (stderr).
+#   4. A value-less flag (-i -b -c and long forms) exits 2 (stderr).
+#   5. -b and -c both pass parsing (sandboxed runner: the run then fails
+#      at credential resolution, nonzero and NOT 2) — no real token is
+#      ever read and no provider is contacted.
+#   6. No arm performs any provider request (PATH shims record every
+#      invocation; the probe log must stay empty).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-review-usage}"
+BIN_DIR="$WORK_DIR/bin"
+PROBE_LOG="$WORK_DIR/provider-probes.log"
+OUT_FILE="$WORK_DIR/out.log"
+ERR_FILE="$WORK_DIR/err.log"
+
+cleanup() {
+    rm -rf "$WORK_DIR"
+}
+trap cleanup EXIT
+
+mkdir -p "$BIN_DIR"
+: > "$PROBE_LOG"
+
+# Unlike the issue suites, these stubs FAIL (exit 99): pr-close has an
+# API fallback that treats a successful curl as a closed PR, so exit-0
+# stubs would let the sandbox arms "succeed" (measured 2026-08-28).
+for tool in gh tea curl; do
+    cat > "$BIN_DIR/$tool" <<STUB
+#!/usr/bin/env bash
+echo "$tool \$*" >> "$PROBE_LOG"
+exit 99
+STUB
+    chmod +x "$BIN_DIR/$tool"
+done
+
+run_wrapper() {
+    ( cd "$WORK_DIR" && PATH="$BIN_DIR:$PATH" "$SCRIPT_DIR/pr-review.sh" "$@" )
+}
+
+# Hermetic variant: neutralizes every identity/credential source the wrapper
+# consults so parse-acceptance arms fail at credential resolution in ANY cwd
+# repo (see test-issue-comment-usage-contract.sh for the measured incident).
+run_wrapper_sandboxed() {
+    mkdir -p "$WORK_DIR/home" "$WORK_DIR/xdg"
+    (
+        cd "$WORK_DIR"
+        PATH="$BIN_DIR:$PATH" HOME="$WORK_DIR/home" XDG_CONFIG_HOME="$WORK_DIR/xdg" \
+            MOSAIC_GIT_IDENTITY="" MOSAIC_BRAIN_HOME="" \
+            "$SCRIPT_DIR/pr-review.sh" "$@"
+    )
+}
+
+fail() {
+    echo "FAIL: $*" >&2
+    echo "--- stderr ---" >&2
+    cat "$ERR_FILE" >&2
+    exit 1
+}
+
+expect_rc() { # expect_rc <want> <desc> <args...>
+    local want="$1" desc="$2" rc=0
+    shift 2
+    run_wrapper "$@" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -eq "$want" ]] || fail "$desc: rc=$rc, want $want"
+}
+
+expect_stderr() { # expect_stderr <pattern> <desc>
+    grep -q "$1" "$ERR_FILE" || fail "$2: stderr missing '$1'"
+}
+
+# 1. Help exits 0 and prints usage.
+expect_rc 0 "--help exits 0" --help
+grep -q "Usage: pr-review.sh" "$OUT_FILE" || fail "--help did not print usage"
+expect_rc 0 "-h exits 0" -h
+
+# 2. Unknown option: rc 2, stderr.
+expect_rc 2 "unknown option exits 2" --bogus
+expect_stderr "unknown option" "unknown option names itself on stderr"
+
+# 3. Missing required PR number: rc 2, stderr.
+expect_rc 2 "missing -n exits 2"
+expect_stderr "PR number is required" "missing -n message on stderr"
+expect_rc 2 "missing -a exits 2" -n 5
+expect_stderr "Action is required" "missing -a message on stderr"
+expect_rc 2 "request-changes without comment exits 2" -n 5 -a request-changes
+expect_stderr "comment required for request-changes" "request-changes message on stderr"
+expect_rc 2 "comment without body exits 2 pre-detection" -n 5 -a comment
+expect_stderr "comment required for comment" "comment-without-body message on stderr"
+expect_rc 2 "invalid action exits 2 pre-detection" -n 5 -a bogus
+expect_stderr "unknown action" "invalid action message on stderr"
+# Invalid-action arms must not contact any provider (validation precedes
+# detect_platform): probe log empty at this point.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: an invalid-action arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 4. Value-less flags: rc 2 with "requires a value" on stderr.
+for flag in -n -a -b -c -l -r --number --action --body --comment --login --repo; do
+    expect_rc 2 "value-less $flag exits 2" "$flag"
+    expect_stderr "requires a value" "value-less $flag message on stderr"
+done
+
+# 4a. An option-like value is a MISSING value, not a value (codex PR #1464:
+# -b --help previously consumed --help as the body and performed the write).
+expect_rc 2 "option-like value rejected" -n 5 -a comment -b --help
+expect_rc 2 "short flag value rejected" -n 5 -a comment -b -h
+expect_stderr "requires a value" "short flag value message on stderr"
+expect_stderr "requires a value" "option-like value message on stderr"
+
+# 4b. Parser-failure arms (1-4) must have performed ZERO provider contact.
+if [[ -s "$PROBE_LOG" ]]; then
+    echo "FAIL: a parser-failure arm contacted a provider:" >&2
+    cat "$PROBE_LOG" >&2
+    exit 1
+fi
+
+# 5. Alias acceptance under the sandbox: both -b and -c carry a value past
+#    parsing; the run fails at credential resolution nonzero and NOT 2.
+for flag in -b -c; do
+    rc=0
+    run_wrapper_sandboxed -n 5 -a comment "$flag" "review note" >"$OUT_FILE" 2>"$ERR_FILE" || rc=$?
+    [[ "$rc" -ne 0 ]] || fail "$flag arm unexpectedly succeeded in the sandbox"
+    [[ "$rc" -ne 2 ]] || fail "$flag arm misclassified credential failure as a usage error"
+done
+
+# 6. Post-sandbox provider assertions are intentionally NOT applied here:
+# pr-close's gitea path attempts a tea WRITE (tea pr comment) when a
+# comment parses, then falls back to the API. Hermeticity for this
+# wrapper comes from the FAILING stubs (exit 99), not from non-contact —
+# the arm above proves only parse acceptance and non-usage classification.
+# Parser-failure arms (1-4) remain zero-contact (asserted at 4b).
+
+echo "pr-review.sh usage-contract regression passed (R1/R4)"