mosaic dispatch: codex review fixes (comms repo binding, q lookup, watch help)

- comms: bind comms-send.sh to the SELECTED repository via
  FLEET_COMMS_REPO in the spawned env; without it, --comms-repo chose
  the executable but the tool still operated on the default checkout
  (codex on 9c8b6ebf). Spec asserts the stub observes the binding.
- q: Object.hasOwn subcommand lookup (reserved property names like
  toString must not leak through the record); spec arm added.
- watch: .helpOption(false) — the tool owns help too; --help now passes
  through to agent-watch.sh instead of commander's wrapper help
  (verified against dist).

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

@@ -0,0 +1,106 @@
+import { RequestMethod, type Type } from '@nestjs/common';
+import { describe, expect, it } from 'vitest';
+import { AppModule } from '../app.module.js';
+import { HierarchyModule } from '../hierarchy/hierarchy.module.js';
+
+/**
+ * Hierarchy route-inventory baseline (contract 1 §6.3(a)).
+ *
+ * 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.
+ */
+
+interface RouteEntry {
+  method: string;
+  path: string;
+  controller: string;
+}
+
+/** Module-metadata entry: a module class or a DynamicModule-shaped object. */
+type ModuleEntry =
+  | Type<unknown>
+  | { module: Type<unknown>; imports?: unknown[]; controllers?: Type<unknown>[] };
+
+function collectControllers(root: ModuleEntry): Type<unknown>[] {
+  const visited = new Set<unknown>();
+  const controllers: Type<unknown>[] = [];
+  const walk = (entry: ModuleEntry | undefined | null): void => {
+    if (!entry || visited.has(entry)) return;
+    visited.add(entry);
+    const moduleClass = typeof entry === 'function' ? entry : entry.module;
+    // Entries with no resolvable class (forwardRef wrappers, async dynamic
+    // modules) carry no decorator metadata to read here.
+    if (typeof moduleClass !== 'function') return;
+    if (visited.has(moduleClass) && typeof entry !== 'function') return;
+    visited.add(moduleClass);
+    // 'controllers' / 'imports' are the metadata keys the @Module decorator writes.
+    const declared = (Reflect.getMetadata('controllers', moduleClass) ?? []) as Type<unknown>[];
+    controllers.push(...declared);
+    if (typeof entry !== 'function' && entry.controllers) controllers.push(...entry.controllers);
+    const imports = [
+      ...((Reflect.getMetadata('imports', moduleClass) ?? []) as ModuleEntry[]),
+      ...(typeof entry !== 'function' ? ((entry.imports ?? []) as ModuleEntry[]) : []),
+    ];
+    for (const imported of imports) walk(imported);
+  };
+  walk(root);
+  return controllers;
+}
+
+function routesOf(controller: Type<unknown>): RouteEntry[] {
+  // 'path' on the class is the @Controller prefix; 'path'/'method' on a
+  // handler are written by the @Get/@Post/... route decorators.
+  const base = (Reflect.getMetadata('path', controller) ?? '') as string | string[];
+  const bases = Array.isArray(base) ? base : [base];
+  const routes: RouteEntry[] = [];
+  const prototype = controller.prototype as Record<string, unknown>;
+  for (const name of Object.getOwnPropertyNames(prototype)) {
+    if (name === 'constructor') continue;
+    const handler = Object.getOwnPropertyDescriptor(prototype, name)?.value;
+    if (typeof handler !== 'function') continue;
+    const method = Reflect.getMetadata('method', handler) as number | undefined;
+    if (method === undefined) continue;
+    const sub = (Reflect.getMetadata('path', handler) ?? '/') as string;
+    for (const prefix of bases) {
+      const path = `/${prefix}/${sub}`.replace(/\/+/g, '/').replace(/(.)\/$/, '$1');
+      routes.push({
+        method: RequestMethod[method] ?? String(method),
+        path,
+        controller: controller.name,
+      });
+    }
+  }
+  return routes;
+}
+
+describe('hierarchy route-inventory baseline (§6.3(a))', () => {
+  const inventory = collectControllers(AppModule).flatMap(routesOf);
+
+  it('control: the enumeration sees the known route surface', () => {
+    const paths = inventory.map((r) => `${r.method} ${r.path}`);
+    expect(paths).toContain('GET /health');
+    expect(paths).toContain('POST /api/workspaces');
+    expect(paths).toContain('GET /api/teams');
+    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('HierarchyModule itself declares no controllers', () => {
+    expect((Reflect.getMetadata('controllers', HierarchyModule) ?? []) as unknown[]).toEqual([]);
+    const hierarchyControllers = collectControllers(HierarchyModule);
+    expect(hierarchyControllers).toEqual([]);
+  });
+});

apps/gateway/src/app.module.ts

@@ -24,6 +24,7 @@ import { GCModule } from './gc/gc.module.js';
 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 { QueueModule } from './queue/queue.module.js';
 import { FederationModule } from './federation/federation.module.js';
 import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
@@ -65,6 +66,7 @@ const federationEnabled = loadConfig(resolveGatewayConfigPath()).tier === 'feder
     QueueModule,
     ReloadModule,
     WorkspaceModule,
+    HierarchyModule,
     ...(federationEnabled ? [FederationModule] : []),
   ],
   controllers: [HealthController],

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

@@ -0,0 +1,247 @@
+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,
+  hierarchyOutbox,
+  platformProjects,
+  runPgliteMigrations,
+  type DbHandle,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+import {
+  HierarchyAuditIdempotencyConflictError,
+  HierarchyAuditRepository,
+  HierarchyNodeNotFoundError,
+  type AppendHierarchyEventInput,
+} from './hierarchy-audit.repository.js';
+
+/**
+ * Repository-level §6.4 witnesses for the hierarchy audit machinery
+ * (contract 1 §5.2, REQ-AUD-001): same-transaction atomicity of state +
+ * event + outbox, rollback leaving no residue, idempotent replay, snapshot
+ * parent chains, events surviving target deletion, per-target ordering, and
+ * the outbox claim/complete/release CAS. The schema-level constraints are
+ * witnessed in packages/db/src/hierarchy-audit.witness.test.ts.
+ */
+describe('hierarchy audit repository integration', (): void => {
+  let dataDir: string;
+  let handle: DbHandle;
+  let moduleRef: TestingModule;
+  let repo: HierarchyAuditRepository;
+
+  const input = (
+    overrides: Partial<AppendHierarchyEventInput> = {},
+  ): AppendHierarchyEventInput => ({
+    actorId: 'user-actor',
+    verb: 'create',
+    targetKind: 'company',
+    targetId: randomUUID(),
+    targetSnapshot: { id: 'x', slug: 'x', name: 'x', parentChain: [] },
+    correlationId: 'corr-1',
+    idempotencyKey: `key-${randomUUID()}`,
+    ...overrides,
+  });
+
+  beforeAll(async (): Promise<void> => {
+    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-gateway-hierarchy-audit-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    moduleRef = await Test.createTestingModule({
+      providers: [HierarchyAuditRepository, { provide: DB, useValue: handle.db }],
+    }).compile();
+    repo = moduleRef.get(HierarchyAuditRepository);
+  });
+
+  afterAll(async (): Promise<void> => {
+    await moduleRef.close();
+    await handle.close();
+    await rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('commits state, event, and outbox record atomically in one transaction', async () => {
+    const companyId = randomUUID();
+    const key = `key-${randomUUID()}`;
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Atomic Co', slug: 'atomic-co' });
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      const result = await repo.append(tx, {
+        ...input({ targetId: companyId, idempotencyKey: key }),
+        targetSnapshot: { ...snapshot },
+      });
+      expect(result.replayed).toBe(false);
+      expect(result.event.idempotencyKey).toBe(key);
+    });
+    const events = await handle.db
+      .select()
+      .from(hierarchyAuditEvents)
+      .where(eq(hierarchyAuditEvents.idempotencyKey, key));
+    expect(events).toHaveLength(1);
+    const outbox = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.eventId, events[0]!.id));
+    expect(outbox).toHaveLength(1);
+    expect(outbox[0]).toMatchObject({
+      status: 'pending',
+      idempotencyKey: key,
+      correlationId: 'corr-1',
+    });
+  });
+
+  it('a rolled-back transaction leaves no state, no event, and no outbox record', async () => {
+    const companyId = randomUUID();
+    const key = `key-${randomUUID()}`;
+    await expect(
+      handle.db.transaction(async (tx) => {
+        await tx.insert(companies).values({ id: companyId, name: 'Doomed Co', slug: 'doomed-co' });
+        await repo.append(tx, input({ targetId: companyId, idempotencyKey: key }));
+        throw new Error('deliberate rollback');
+      }),
+    ).rejects.toThrow('deliberate rollback');
+    const [companyRows, eventRows, outboxRows] = await Promise.all([
+      handle.db.select().from(companies).where(eq(companies.id, companyId)),
+      handle.db
+        .select()
+        .from(hierarchyAuditEvents)
+        .where(eq(hierarchyAuditEvents.idempotencyKey, key)),
+      handle.db.select().from(hierarchyOutbox).where(eq(hierarchyOutbox.idempotencyKey, key)),
+    ]);
+    expect(companyRows).toHaveLength(0);
+    expect(eventRows).toHaveLength(0);
+    expect(outboxRows).toHaveLength(0);
+  });
+
+  it('replays a duplicate idempotency key without inserting a second event or outbox record', async () => {
+    const first = input();
+    const original = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    const replay = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(original.replayed).toBe(false);
+    expect(replay.replayed).toBe(true);
+    expect(replay.event.id).toBe(original.event.id);
+    const outbox = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.eventId, original.event.id));
+    expect(outbox).toHaveLength(1);
+  });
+
+  it('throws on a duplicate idempotency key carrying different event content', async () => {
+    const first = input();
+    await handle.db.transaction(async (tx) => repo.append(tx, first));
+    await expect(
+      handle.db.transaction(async (tx) =>
+        repo.append(tx, { ...first, verb: 'rename', targetId: randomUUID() }),
+      ),
+    ).rejects.toThrow(HierarchyAuditIdempotencyConflictError);
+  });
+
+  it('throws on a duplicate idempotency key whose transfer destination differs', async () => {
+    const from = { kind: 'company' as const, id: randomUUID(), slug: 'src-co' };
+    const to = { kind: 'company' as const, id: randomUUID(), slug: 'dst-co' };
+    const first = input({
+      verb: 'transfer',
+      targetKind: 'estate',
+      transferFrom: from,
+      transferTo: to,
+    });
+    const original = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(original.replayed).toBe(false);
+    // Identical retry replays; a retry re-routed to a different destination must conflict.
+    const replay = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(replay.replayed).toBe(true);
+    await expect(
+      handle.db.transaction(async (tx) =>
+        repo.append(tx, { ...first, transferTo: { ...to, id: randomUUID() } }),
+      ),
+    ).rejects.toThrow(HierarchyAuditIdempotencyConflictError);
+  });
+
+  it('builds root-first parent chains and rejects unknown nodes', async () => {
+    const companyId = randomUUID();
+    const estateId = randomUUID();
+    const projectId = randomUUID();
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Chain Co', slug: 'chain-co' });
+      await tx
+        .insert(estates)
+        .values({ id: estateId, name: 'Chain Estate', slug: 'chain-estate', companyId });
+      await tx
+        .insert(platformProjects)
+        .values({ id: projectId, name: 'Chain Project', slug: 'chain-project', estateId });
+    });
+    const snapshot = await repo.snapshot(handle.db, 'platform_project', projectId);
+    expect(snapshot).toMatchObject({ id: projectId, slug: 'chain-project', name: 'Chain Project' });
+    expect(snapshot.parentChain).toEqual([
+      { kind: 'company', id: companyId, slug: 'chain-co' },
+      { kind: 'estate', id: estateId, slug: 'chain-estate' },
+    ]);
+    await expect(repo.snapshot(handle.db, 'estate', randomUUID())).rejects.toThrow(
+      HierarchyNodeNotFoundError,
+    );
+  });
+
+  it('keeps events readable, in per-target seq order, after the target row is deleted', async () => {
+    const companyId = randomUUID();
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Mortal Co', slug: 'mortal-co' });
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      await repo.append(tx, input({ targetId: companyId, targetSnapshot: { ...snapshot } }));
+    });
+    await handle.db.transaction(async (tx) => {
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      await repo.append(tx, {
+        ...input({ verb: 'delete', targetId: companyId }),
+        targetSnapshot: { ...snapshot },
+      });
+      await tx.delete(companies).where(eq(companies.id, companyId));
+    });
+    const events = await repo.eventsForTarget(companyId);
+    expect(events.map((e) => e.verb)).toEqual(['create', 'delete']);
+    expect(events[1]!.seq).toBeGreaterThan(events[0]!.seq);
+    expect((events[1]!.targetSnapshot as { id: string }).id).toBe(companyId);
+  });
+
+  it('claims the oldest pending outbox record exactly once, completes and releases by CAS', async () => {
+    // Drain records left pending by earlier cases so ordering is deterministic.
+    for (;;) {
+      const drained = await repo.claimPendingOutbox();
+      if (!drained) break;
+      await repo.completeOutbox(drained.id);
+    }
+    const older = await handle.db.transaction(async (tx) => repo.append(tx, input()));
+    const newer = await handle.db.transaction(async (tx) => repo.append(tx, input()));
+
+    const claimed = await repo.claimPendingOutbox();
+    expect(claimed).not.toBeNull();
+    expect(claimed!.eventId).toBe(older.event.id);
+    expect(claimed!.status).toBe('processing');
+
+    // Delivery fails: release returns it to pending and it is claimable again.
+    await repo.releaseOutbox(claimed!.id);
+    const reclaimed = await repo.claimPendingOutbox();
+    expect(reclaimed!.id).toBe(claimed!.id);
+
+    await repo.completeOutbox(reclaimed!.id);
+    const done = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.id, reclaimed!.id));
+    expect(done[0]!.status).toBe('delivered');
+    expect(done[0]!.deliveredAt).not.toBeNull();
+    // completeOutbox is CAS-guarded on 'processing': completing again is a no-op.
+    await repo.completeOutbox(reclaimed!.id);
+
+    const second = await repo.claimPendingOutbox();
+    expect(second!.eventId).toBe(newer.event.id);
+    await repo.completeOutbox(second!.id);
+    expect(await repo.claimPendingOutbox()).toBeNull();
+  });
+});

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

@@ -0,0 +1,274 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  asc,
+  companies,
+  eq,
+  estates,
+  hierarchyAuditEvents,
+  hierarchyOutbox,
+  platformProjects,
+  type Db,
+  type HIERARCHY_AUDIT_TARGET_KINDS,
+  type HIERARCHY_AUDIT_VERBS,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+
+/**
+ * Hierarchy audit event + outbox machinery (contract 1 §5.2).
+ *
+ * Every hierarchy mutation writes its semantic audit event AND the event's
+ * outbox record on the caller's transaction, so state, event, and outbox
+ * commit or roll back together. Events reference their target by an
+ * immutable snapshot (id, slug, parent chain at event time), never by a
+ * foreign key into the class tables — append-only events survive the
+ * deletion of their target. This module exposes no update or delete path
+ * for events: append-only is a property of the code surface, witnessed by
+ * the integration tests.
+ *
+ * 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.
+ */
+
+export type HierarchyAuditVerb = (typeof HIERARCHY_AUDIT_VERBS)[number];
+export type HierarchyTargetKind = (typeof HIERARCHY_AUDIT_TARGET_KINDS)[number];
+export type HierarchyNodeKind = Exclude<HierarchyTargetKind, 'grant'>;
+
+export interface ParentChainEntry {
+  readonly kind: HierarchyNodeKind;
+  readonly id: string;
+  readonly slug: string;
+}
+
+/** Immutable node snapshot at event time; parentChain is root-first. */
+export interface HierarchyNodeSnapshot {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  readonly parentChain: readonly ParentChainEntry[];
+}
+
+export interface AppendHierarchyEventInput {
+  readonly actorId: string;
+  readonly verb: HierarchyAuditVerb;
+  readonly targetKind: HierarchyTargetKind;
+  readonly targetId: string;
+  /** Node events: HierarchyNodeSnapshot. Grant events: subject/target/role snapshot (contract 2 §4.4). */
+  readonly targetSnapshot: Record<string, unknown>;
+  /** Present exactly on transfers (CHECK-enforced): source/destination parent { kind, id, slug }. */
+  readonly transferFrom?: ParentChainEntry;
+  readonly transferTo?: ParentChainEntry;
+  readonly correlationId: string;
+  /** Prior event in the causal chain (e.g. the delete event causing cascaded grant_revoke events). */
+  readonly causationId?: string;
+  readonly idempotencyKey: string;
+}
+
+export type HierarchyAuditEventRow = typeof hierarchyAuditEvents.$inferSelect;
+export type HierarchyOutboxRow = typeof hierarchyOutbox.$inferSelect;
+
+export interface AppendHierarchyEventResult {
+  readonly event: HierarchyAuditEventRow;
+  /** True when the idempotency key had already committed an identical event (REQ-AUD-001 duplicate suppression). */
+  readonly replayed: boolean;
+}
+
+type Tx = Pick<Db, 'insert' | 'select'>;
+
+export class HierarchyAuditIdempotencyConflictError extends Error {
+  constructor(idempotencyKey: string) {
+    super(
+      `hierarchy audit idempotency key ${idempotencyKey} already exists with different event content`,
+    );
+    this.name = 'HierarchyAuditIdempotencyConflictError';
+  }
+}
+
+export class HierarchyNodeNotFoundError extends Error {
+  constructor(kind: HierarchyNodeKind, id: string) {
+    super(`hierarchy node not found: ${kind} ${id}`);
+    this.name = 'HierarchyNodeNotFoundError';
+  }
+}
+
+/**
+ * Append one audit event and its outbox record on the caller's transaction.
+ * A duplicate idempotency key with identical semantic content returns the
+ * prior event (replayed: true) without inserting anything; a duplicate key
+ * with different content throws.
+ */
+export async function appendHierarchyEvent(
+  tx: Tx,
+  input: AppendHierarchyEventInput,
+): Promise<AppendHierarchyEventResult> {
+  const inserted = await tx
+    .insert(hierarchyAuditEvents)
+    .values({
+      actorId: input.actorId,
+      verb: input.verb,
+      targetKind: input.targetKind,
+      targetId: input.targetId,
+      targetSnapshot: input.targetSnapshot,
+      transferFrom: input.transferFrom ?? null,
+      transferTo: input.transferTo ?? null,
+      correlationId: input.correlationId,
+      causationId: input.causationId ?? null,
+      idempotencyKey: input.idempotencyKey,
+    })
+    .onConflictDoNothing()
+    .returning();
+  const event = inserted[0];
+  if (event) {
+    await tx.insert(hierarchyOutbox).values({
+      eventId: event.id,
+      idempotencyKey: input.idempotencyKey,
+      correlationId: input.correlationId,
+    });
+    return { event, replayed: false };
+  }
+
+  const prior = await tx
+    .select()
+    .from(hierarchyAuditEvents)
+    .where(eq(hierarchyAuditEvents.idempotencyKey, input.idempotencyKey))
+    .limit(1);
+  const existing = prior[0];
+  if (!existing || !sameEvent(existing, input)) {
+    throw new HierarchyAuditIdempotencyConflictError(input.idempotencyKey);
+  }
+  // Event and outbox committed atomically the first time, so the outbox
+  // record already exists; a replay inserts nothing.
+  return { event: existing, replayed: true };
+}
+
+/** Key-order-independent serialization: jsonb does not preserve key order. */
+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);
+}
+
+function sameEvent(row: HierarchyAuditEventRow, input: AppendHierarchyEventInput): boolean {
+  return (
+    row.actorId === input.actorId &&
+    row.verb === input.verb &&
+    row.targetKind === input.targetKind &&
+    row.targetId === input.targetId &&
+    row.correlationId === input.correlationId &&
+    (row.causationId ?? null) === (input.causationId ?? null) &&
+    canonicalJson(row.targetSnapshot) === canonicalJson(input.targetSnapshot) &&
+    // Transfer source/destination are semantic content (§5.2): a retry with a
+    // different destination must conflict, never silently replay.
+    canonicalJson(row.transferFrom ?? null) === canonicalJson(input.transferFrom ?? null) &&
+    canonicalJson(row.transferTo ?? null) === canonicalJson(input.transferTo ?? null)
+  );
+}
+
+/**
+ * Build the immutable snapshot for a node: its row plus the parent chain up
+ * to the company root, root-first, read on the caller's transaction so the
+ * snapshot is consistent with the mutation it audits.
+ */
+export async function buildNodeSnapshot(
+  tx: Tx,
+  kind: HierarchyNodeKind,
+  id: string,
+): Promise<HierarchyNodeSnapshot> {
+  if (kind === 'company') {
+    const rows = await tx.select().from(companies).where(eq(companies.id, id)).limit(1);
+    const row = rows[0];
+    if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+    return { id: row.id, slug: row.slug, name: row.name, parentChain: [] };
+  }
+  if (kind === 'estate') {
+    const rows = await tx.select().from(estates).where(eq(estates.id, id)).limit(1);
+    const row = rows[0];
+    if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+    const parent = await buildNodeSnapshot(tx, 'company', row.companyId);
+    return {
+      id: row.id,
+      slug: row.slug,
+      name: row.name,
+      parentChain: [...parent.parentChain, { kind: 'company', id: parent.id, slug: parent.slug }],
+    };
+  }
+  const rows = await tx.select().from(platformProjects).where(eq(platformProjects.id, id)).limit(1);
+  const row = rows[0];
+  if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+  const parent = await buildNodeSnapshot(tx, 'estate', row.estateId);
+  return {
+    id: row.id,
+    slug: row.slug,
+    name: row.name,
+    parentChain: [...parent.parentChain, { kind: 'estate', id: parent.id, slug: parent.slug }],
+  };
+}
+
+@Injectable()
+export class HierarchyAuditRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  /** Compose an event+outbox append into a caller-owned transaction. */
+  append(tx: Tx, input: AppendHierarchyEventInput): Promise<AppendHierarchyEventResult> {
+    return appendHierarchyEvent(tx, input);
+  }
+
+  snapshot(tx: Tx, kind: HierarchyNodeKind, id: string): Promise<HierarchyNodeSnapshot> {
+    return buildNodeSnapshot(tx, kind, id);
+  }
+
+  /** Per-target ordered event history (REQ-AUD-001 per-target ordering; read-only). */
+  async eventsForTarget(targetId: string): Promise<HierarchyAuditEventRow[]> {
+    return this.db
+      .select()
+      .from(hierarchyAuditEvents)
+      .where(eq(hierarchyAuditEvents.targetId, targetId))
+      .orderBy(asc(hierarchyAuditEvents.seq));
+  }
+
+  /**
+   * Claim the oldest pending outbox record (claim-by-CAS: the UPDATE is
+   * guarded on status so a lost race returns null and the caller retries).
+   */
+  async claimPendingOutbox(): Promise<HierarchyOutboxRow | null> {
+    const candidates = await this.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.status, 'pending'))
+      .orderBy(asc(hierarchyOutbox.createdAt))
+      .limit(1);
+    const candidate = candidates[0];
+    if (!candidate) return null;
+    const claimed = await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'processing', updatedAt: new Date() })
+      .where(and(eq(hierarchyOutbox.id, candidate.id), eq(hierarchyOutbox.status, 'pending')))
+      .returning();
+    return claimed[0] ?? null;
+  }
+
+  async completeOutbox(id: string): Promise<void> {
+    const now = new Date();
+    await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'delivered', deliveredAt: now, updatedAt: now })
+      .where(and(eq(hierarchyOutbox.id, id), eq(hierarchyOutbox.status, 'processing')));
+  }
+
+  /** Return a claimed record to pending (delivery failed; it stays replayable). */
+  async releaseOutbox(id: string): Promise<void> {
+    await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(and(eq(hierarchyOutbox.id, id), eq(hierarchyOutbox.status, 'processing')));
+  }
+}

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

@@ -0,0 +1,17 @@
+import { Module } from '@nestjs/common';
+import { HierarchyAuditRepository } from './hierarchy-audit.repository.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.
+ */
+@Module({
+  providers: [HierarchyAuditRepository],
+  exports: [HierarchyAuditRepository],
+})
+export class HierarchyModule {}

docs/requirements/hierarchy-schema.md

@@ -72,6 +72,25 @@ example now lists the complete measured set, and the import analysis
 is extended to resolve literal dynamic `import()` routes, which two of
 the four members use.
 
+Amendment 1 (Ruling 4b, 2026-08-28): company visibility classes. The
+directory exists so one shared company can serve many users instead of
+each user creating a duplicate private company (Ruling 4b, webui-audit
+lane, ruled 2026-08-27). §2.1 gains a `visibility` column; §2.8 defines
+the two classes (`private`/`directory`), the directory's existence-only
+disclosure, and the pre-binding invariants for the deferred
+see-and-ask-to-join flow (no join-request surface is authorized here —
+its flow is a follow-up contract); §5.2's mutation
+enumeration gains the visibility change; §5.5 defines who may change
+visibility (platform admins, plus a company-CRUD capability whose
+definition is a follow-up amendment to contract 2 — until it ratifies,
+admin-only); §6.1 and §6.9 add the witnesses; §6.7's existence-oracle
+rule is scoped around the ratified directory carve-out. Top-level
+creation (contract 3 §5.2) is unchanged and always yields a private
+company. Upstream, SOT Amendment A2 (native-kanban-sot.md §9, this PR)
+expressly extends A1 §8.1.2 to admit the visibility column and A1
+§8.1.3 to admit the directory function — this contract relies on that
+amendment, not on a reinterpretation of A1.
+
 Scope: the tenancy/authorization structure record class — companies,
 estates, platform-projects, workspaces, hierarchy grants, their parentage,
 and constraints. Out of scope: the RBAC grant vocabulary and evaluation
@@ -86,8 +105,13 @@ legacy flat data (future work; see §1.3).
    AND `hierarchy_grants` (§3) — A1 includes hierarchy-level access grants
    in the class. Every rule addressed to "the class" in this contract
    (payload prohibition, mutation path, audit) binds all five tables. Class
-   rows carry parentage, naming, grant, and audit-linkage data only — never
-   task, plan, or any business/orchestration payload.
+   rows carry parentage, naming, grant, audit-linkage, and visibility-class
+   data only — never task, plan, or any business/orchestration payload.
+   Visibility (`companies.visibility`, §2.8) is admitted into that
+   enumeration by SOT Amendment A2 §9.1.1, which expressly extends A1
+   §8.1.2 for exactly this one column: it is disclosure data about the
+   class's own nodes — not a payload field, carries no business content,
+   and widens the payload prohibition for nothing else.
    References from business/orchestration rows into the class are limited
    to exactly one form: the canonical `workspace_id` tenancy column that
    REQ-TEN-001 requires on every canonical row, referencing
@@ -116,7 +140,9 @@ MUST NOT merge the two. (A rename of either remains an implementation-PR
 decision under A1; this contract pins only that they stay distinct tables.)
 
 1. `companies` — id (uuid pk), name, slug (unique per deployment),
-   created_at, updated_at. N per deployment (D2).
+   `visibility` (text NOT NULL, DEFAULT `private`, CHECK constrained to
+   exactly `private` | `directory`; semantics §2.8), created_at,
+   updated_at. N per deployment (D2).
 2. `estates` — id, name, slug, `company_id` NOT NULL →
    `companies.id` ON DELETE RESTRICT. Exactly one company per estate; a
    company holds any number of estates.
@@ -142,6 +168,31 @@ decision under A1; this contract pins only that they stay distinct tables.)
    free-form payload field. The columns declared in this section and §3
    are exhaustive: a class table's column set is exactly its declared set
    (verified per §6.2) — nothing else (A1 §8.1.2).
+8. **Company visibility classes (Ruling 4b).** Every company is exactly
+   one of two classes, carried by `visibility`:
+   - `private` (the default): the company is disclosed only to subjects
+     holding a grant on it or on a descendant — the resting state every
+     company is created in. Open creation under contract 3 §5.2
+     (Ruling 4) survives unchanged: it creates private companies.
+   - `directory`: the company is listed in the deployment-wide company
+     directory. Directory listing discloses **existence, name, and slug
+     to every authenticated user — nothing else**: no subtree structure,
+     no roll-up aggregates, no workspace content, no grant or membership
+     information.
+     Visibility is disclosure, not authority. Content and structure access
+     to a directory-listed company still require explicit grants —
+     contract 2 §3.1 deny-by-default is unchanged, and the ownership model
+     (§4.4, contract 2 §4.3) is unchanged. Ruling 4b decision 5 wants a
+     see-and-ask-to-join flow for directory-listed companies. **This
+     contract authorizes no join-request runtime surface**: the flow in
+     its entirety — the ability to submit a request, its transport,
+     storage, and request lifecycle — is a follow-up contract, and until
+     that contract ratifies, the directory's only function is the
+     read-only listing above (A2 §9.1.2 admits nothing more). Two
+     invariants pre-bind that future contract now:
+     a join request confers no authority of any kind, and approval is
+     ordinary grant creation by an effective `owner` under contract 2 §4.1
+     — there is no other acceptance path.
 
 ## 3. Grant attachment points
 
@@ -223,7 +274,8 @@ shape contract 2 attaches to:
 2. **Audit parity.** A1 §8.2 leaves every pre-existing REQ binding, so
    hierarchy mutations get REQ-AUD-001's guarantees, not a weakened
    substitute. Concretely:
-   - Every create, rename, transfer, grant create/change/revoke, and
+   - Every create, rename, transfer, visibility change (§5.5), grant
+     create/change/revoke, and
      delete — including every grant deletion cascaded by a node delete —
      emits a semantic audit event carrying actor, verb, target, and (for
      transfers) source and destination parents, with the correlation,
@@ -248,6 +300,25 @@ shape contract 2 attaches to:
    workspace work. Contract 8 owns projection details but cannot narrow
    this rule. This contract additionally guarantees the chain roll-ups
    aggregate over is unique and non-null (§2.5).
+5. **Visibility administration (Ruling 4b decisions 2–3).** Changing
+   `companies.visibility` is a hierarchy mutation through the §5.1
+   command path, audited per §5.2 (the event carries the old and new
+   visibility values as its semantic content). It is authorized for
+   exactly two actor classes: platform admins (`users.role = 'admin'`)
+   and subjects holding the company-CRUD capability that a follow-up
+   amendment to contract 2 will define — until that amendment ratifies,
+   the capability class is empty and the command is admin-only.
+   A company `owner` as such may NOT change visibility: standard users
+   cannot publish a company into the directory. This is the one
+   hierarchy mutation a platform admin performs without holding a
+   hierarchy grant, and it is ratified here as instance administration
+   (directory curation) in contract 2 §1.1's sense, not tenant access:
+   the command mutates the single `visibility` column, reads no tenant
+   content, and confers no grant — contract 2 §1.1's
+   no-implicit-tenant-access rule is otherwise untouched. Top-level
+   company creation (contract 3 §5.2) always creates
+   `visibility = 'private'`; the creation command cannot set or change
+   visibility.
 
 ## 6. Verification requirements
 
@@ -264,7 +335,10 @@ Binding on the implementing PRs (extends A1 §8.3):
    witnessed (zero and two set → refused). Grant uniqueness: a duplicate
    (subject, target, role) row refused for each of the six subject×target
    forms, proving NULLS-NOT-DISTINCT semantics; NOT NULL on `role`,
-   `granted_by`, and all `name`/`slug` columns witnessed.
+   `granted_by`, and all `name`/`slug` columns witnessed. Company
+   visibility (§2.8): a value outside `private`/`directory` refused with
+   both valid values accepted as the control; an insert omitting the
+   column defaults to `private`.
 2. Column allowlist: an information_schema assertion that each class
    table's column set is exactly the set declared in §2/§3 — the bounded
    observable for no-payload (§2.7) and no-`owner_id` (§4.4).
@@ -346,9 +420,19 @@ Binding on the implementing PRs (extends A1 §8.3):
    static analysis cannot see, and any such evasion found later is
    corrected as a conformance defect, not grandfathered.
 4. Audit witnesses: for each mutation class (create, rename, transfer,
-   grant create/change/revoke, delete) — the event exists after commit
-   with actor/verb/target and same-transaction atomicity; a rolled-back
-   mutation leaves no event (rollback witness); a node delete's cascaded
+   visibility change, grant create/change/revoke, delete) — the event
+   exists after commit
+   with actor/verb/target and same-transaction atomicity, and the
+   event's outbox record exists after the same commit — state row,
+   audit event, and outbox record are witnessed as one transaction
+   (REQ-AUD-001); a rolled-back
+   mutation leaves no event, no outbox record, AND no state effect —
+   a rolled-back create leaves no row, a rolled-back rename, transfer,
+   or visibility change leaves the prior values in place, and a
+   rolled-back delete or grant revoke leaves the row present
+   (rollback witness on all three legs, per REQ-AUD-001's
+   commit-or-roll-back-together acceptance); a
+   node delete's cascaded
    grant deletions are each covered by events; events survive deletion of
    their target (query the events of a deleted node).
 5. Transfer tests: parent-FK update moves the subtree resolution and
@@ -368,10 +452,30 @@ Binding on the implementing PRs (extends A1 §8.3):
    endpoints mutate no canonical state anywhere (assert zero writes across
    hierarchy AND workspace tables, not hierarchy only); readers see
    aggregates only over workspaces they are authorized on, with no
-   cross-tenant existence oracles (A1 §8.3 acceptance 3).
+   cross-tenant existence oracles (A1 §8.3 acceptance 3, as narrowed by
+   A2 §9.1.2) beyond the one
+   ratified carve-out — the §2.8 company directory, witnessed in §6.9.
 8. Real-PostgreSQL coverage for every constraint witness (unique/CHECK/
    RESTRICT/NULLS NOT DISTINCT behavior), using the `ci-postgres` service
    in the `test` CI step; mocked specs cannot witness database constraints.
+9. Visibility witnesses (§2.8, §5.5): the directory read returns exactly
+   the `visibility = 'directory'` companies to any authenticated user,
+   disclosing existence, name, and slug only (closed-field assertion on
+   the response shape); a private company never appears in the directory
+   for a reader without a grant on it (with the control: it appears in
+   that reader's granted-structure reads); a directory-listed company's
+   subtree, aggregates, and content remain refused for a non-granted
+   reader (disclosure ≠ authority); the visibility command is refused
+   for a non-admin actor — including an effective `owner` of the target
+   company — with the platform-admin accept control; top-level creation
+   yields `visibility = 'private'` and accepts no visibility argument;
+   each visibility change emits its §5.2 audit event carrying old and
+   new values — the full audit pattern for the mutation class
+   (same-transaction atomicity of state row, audit event, and outbox
+   record; rollback leaving no state effect, no event, and no outbox
+   record; actor/verb/target) is §6.4's, which enumerates
+   visibility change; this item adds only the old/new-value payload
+   assertion.
 
 ## Ruling request
 

docs/requirements/native-kanban-sot.md

@@ -456,3 +456,61 @@ this line is weakened.
 - Negative tests prove roll-up endpoints cannot mutate state and that a
   reader sees aggregates only over workspaces they are authorized on
   (no cross-tenant existence oracles).
+
+## 9. Amendment A2 — company visibility classes and the company directory
+
+**Status:** amendment to Amendment A1, added by reviewed PR under Ruling 4b
+(operator ruling, 2026-08-27; decision owner Jason; recorded in the webui-audit
+lane RULINGS.md). Everything in §§1–8 remains binding verbatim, with exactly
+the two express modifications below. Nothing else is weakened. The detailed
+contract text lives in the hierarchy schema contract
+(`hierarchy-schema.md` §2.8, §5.5, §6.9); this amendment changes only what A1
+itself permits, so that contract does not stretch A1 by interpretation.
+
+### 9.1 What A2 modifies in A1
+
+1. **Class data (extends §8.1.2's first constraint).** The tenancy/authorization
+   structure record class additionally carries **visibility-class data**: the
+   single column `companies.visibility`, values `private` | `directory`
+   (hierarchy schema §2.8). Visibility is disclosure data about the class's own
+   nodes — what a company row reveals about its own existence — and is part of
+   the class's tenancy/authorization purpose. It is not business or
+   orchestration payload. §8.1.2's payload prohibition is widened for nothing
+   else: hierarchy tables still MUST NOT carry task, plan, or any other
+   business/orchestration payload, and this amendment admits exactly this one
+   column.
+2. **The company directory (extends §8.1.3's function enumeration).** The
+   hierarchy serves one additional, express, narrow runtime function: the
+   **company directory** — a read-only disclosure listing of exactly the
+   companies whose `visibility = 'directory'`, revealing existence, name, and
+   slug to every authenticated user of the deployment and nothing else. It
+   mutates nothing, confers no authority, evaluates no grant down the chain,
+   and aggregates nothing (it is not a roll-up). §8.3's
+   no-cross-tenant-existence-oracle acceptance is narrowed by exactly this one
+   ratified carve-out: the directory is the sole permitted existence
+   disclosure, and it discloses only directory-class companies (witnessed in
+   hierarchy schema §6.7 and §6.9). Private companies remain undisclosed to
+   non-granted subjects everywhere, including the directory.
+
+### 9.2 What A2 explicitly does not change
+
+1. Content access stays grant-only under the RBAC grant model contract:
+   directory listing discloses existence, never content, membership, or any
+   authority (Ruling 3 unchanged; hierarchy schema §2.8).
+2. **No join-request surface is authorized.** Ruling 4b decision 5's
+   see-and-ask-to-join flow is a follow-up contract in its entirety —
+   including the ability to submit a request. A2 admits exactly the
+   read-only listing of §9.1.2 and nothing more; hierarchy schema §2.8
+   states the invariants that pre-bind the future flow contract, and that
+   contract must itself amend this enumeration before any join-request
+   runtime surface exists.
+3. Visibility changes are hierarchy mutations on the existing §8.2.3 audited
+   mutation path — audited maintenance of the class's own structure in
+   §8.1.3's sense, not a further runtime function. Authorization for them is
+   defined in hierarchy schema §5.5 (platform admins plus the future
+   company-CRUD capability; owner-as-such cannot publish).
+4. Company creation is unchanged and always yields `visibility = 'private'`
+   (onboarding wizard §5.2); this amendment adds no creation path and no
+   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.

docs/requirements/onboarding-wizard.md

@@ -397,6 +397,14 @@ seed-workspace-scoped mutant, correctly refusing outside the seed
 set, passes branch (c), so the two branches detect distinct
 mutants. No other change.
 
+Amendment 1 (Ruling 4b, 2026-08-28): §5.2's embedded decision was RULED
+AGREED (Jason, 2026-08-27), and Ruling 4b adds company visibility
+classes (hierarchy schema §2.8): open top-level creation always yields
+a **private** company; publishing a company into the deployment-wide
+directory is a separate, gated visibility mutation (hierarchy schema
+§5.5) that is never part of the creation command. §5.2 is amended to
+state both.
+
 Scope: the Gateway-backed product onboarding wizard. Out of scope: the
 host-local install wizard (`mosaic wizard`, which drives host install and
 gateway bootstrap and is not this artifact — audit REPORT.md layer 3);
@@ -1169,15 +1177,18 @@ collects no sensitive category, so v1 ships no custody surface.
    party, service actor, or wizard-privileged writer exists in this
    flow.
 2. **Post-bootstrap top-level company creation** — the "N companies" flow
-   — is decided by the ruling below: any **eligible platform user** MAY
+   — RULED AGREED (Jason, 2026-08-27): any **eligible platform user** MAY
    create a top-level company and MUST name an initial `owner` grant in
    the same audited operation (contract 2 §4.3); the creator naming
    themselves is the default. Eligible means, in identity-contract
    terms: an authenticated account (identity §2) that is not banned
    (identity §7.1 — deactivation on this platform IS the better-auth
    ban; no separate deactivated state exists). No further role or grant
-   is required. Until that ruling, deny-by-default holds (contract 2
-   §3.1): no implicit creation authority exists.
+   is required. Creation always yields a **private** company
+   (`visibility = 'private'`, hierarchy schema §2.8, Ruling 4b): the
+   creation command accepts no visibility argument, and publishing into
+   the deployment-wide directory is a separate, gated mutation
+   (hierarchy schema §5.5) that standard users cannot perform.
 3. Child-node creation inside the wizard (estate, project, workspace
    under the seeded company) follows contract 2 §4.3: parent
    `owner` authority, no automatic grant needed — for canonical seed
@@ -1932,7 +1943,13 @@ contracts and are not additions:
     suffix at all — each contradicting PRD D4's no-lock-in
     requirement (§4.4).
 
-## Ruling request
+## Ruling request — RULED AGREED (Jason, 2026-08-27; Amendment 1)
+
+The §5.2 decision below was ruled agreed: open eligible-user creation
+stands (yielding private companies per Amendment 1), and the
+"alternative if rejected" did not take effect. The request is retained
+below as historical record of what was put to ruling; it is no longer
+live.
 
 Ratify sections 1–7 as written, with one decision embedded:
 

docs/requirements/rbac-grant-model.md

@@ -0,0 +1,259 @@
+# RBAC Grant Model Contract
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 2 of 9).
+Authority: PRD Part I §4 ("Granular RBAC: admins restrict access per company,
+estate, and project; grants are evaluated down the chain") and the
+native-kanban SOT Amendment A1 (§8.1.3 RBAC evaluation, §8.3 acceptance 2).
+This document defines the grant vocabulary, evaluation semantics, and
+revocation propagation that the hierarchy schema contract
+(`docs/requirements/hierarchy-schema.md`, contract 1) attaches to. Contract 1
+pins the `hierarchy_grants` table shape and defers the `role` vocabulary and
+the meaning of "authority" here; the identity contract
+(`docs/requirements/identity-lifecycle.md` §1.4) pins that account creation
+grants nothing.
+
+Revision 2 (independent review, GLM 5.3): §1.1 consequence analysis
+completed — the two existing platform-admin bypass code paths are named as
+non-conformant and §7.4 retires them; team grant subjects suspended pending
+a team contract (§1.4, §3.3–3.4, §7.5); no-self-escalation restated with
+its true rationale and a constructible observable (§4.2, §7.7);
+node-creation seeding scoped to the bootstrap path, resolving the §7.7/§4.3
+contradiction; A1 quotation corrected; audit-field provenance corrected;
+principal-position consequence named (§1.3); membership-row,
+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".
+
+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
+tables themselves (contract 1), workspace-internal membership and its
+role/capability vocabulary (native-kanban SOT REQ-ID-001 and its implementing
+schema), roll-up projection semantics (contract 8), wizard seeding
+(contract 3), the team model (suspended here; see §1.4).
+
+## 1. Three authority layers, none substitutable
+
+1. **Platform role** (`users.role`, better-auth: `member` | `admin`) governs
+   instance administration — user management, system settings, provider
+   configuration. It is not tenancy authority: holding platform `admin`
+   confers **no implicit hierarchy grant and no workspace authorization**.
+   An operator who should see tenant content holds an explicit, audited
+   grant like anyone else. This is the deny-by-default consequence of A1
+   §8.1.3 ("not a bypass of workspace authorization"). `AdminGuard`'s
+   `role === 'admin'` check on admin endpoints stays the platform role's
+   only meaning. **Two shipped code paths violate this rule today and are
+   implementation defects this contract makes non-conformant:** (a) the
+   command authorization service short-circuits every command scope to
+   allowed for platform admins
+   (`apps/gateway/src/commands/command-authorization.service.ts`,
+   `hasScope` returning true when `role === 'admin'`), and (b) the MCP
+   scope derivation maps platform `admin` to tenant-admin MCP scopes
+   including task create/update
+   (`apps/gateway/src/mcp/mcp.service.ts`,
+   `deriveMcpToolScopesForUser`). Ratifying this contract revokes both;
+   §7.4 names them as the surfaces the deny-by-default test retires.
+2. **Hierarchy grants** (`hierarchy_grants`, contract 1 §3) declare tenancy
+   authority at company, estate, or platform-project scope and evaluate down
+   the chain to workspace-scoped authorization (§3 below).
+3. **Workspace membership** (SOT REQ-ID-001) remains its own mechanism.
+   A chain grant confers command authorization over descendant workspaces;
+   it does not create membership rows, and row-level principal positions
+   (task owner, proposer, decision actor) still require ACTIVE workspace
+   membership exactly as REQ-TEN-001/REQ-ID-001 acceptance states.
+   Consequence, stated so implementing PRs do not weaken REQ-TEN-001 to
+   remove the friction: a chain-granted actor who is not a workspace member
+   may issue the write commands their role implies but cannot occupy a
+   principal position — any command taking a principal argument must name
+   an ACTIVE member of the target workspace (§7.2 enumerates this cell).
+4. **Team grant subjects are suspended.** Contract 1 §3.1 reserves a
+   `team_id` attachment point, but no ratified contract yet defines the
+   team it would bind: the only existing `teams` table is the legacy global
+   Brain table (own authority columns, no workspace binding, not
+   repurposed per contract 1 §1.3), while the SOT's teams are
+   workspace-bound (REQ-ID-001) — and a workspace-bound team holding a
+   company-level grant would be a cross-workspace authority group nothing
+   has ratified. Until a team contract defines the subject (which table,
+   which membership rows, and its relation to D2/REQ-ID-001), creating a
+   grant with a team subject MUST be refused at the command surface (the
+   schema column remains, per contract 1). §3's evaluation semantics for
+   team-conferred grants are specified now so the team contract activates
+   them without amending this one.
+
+## 2. Role vocabulary
+
+One vocabulary at every hierarchy level, totally ordered — a higher role
+includes everything below it:
+
+1. `viewer` — read: sees the node, its subtree structure, and the roll-up
+   aggregates over descendant workspaces (within contract 8's carve-out
+   bounds); read access to descendant workspace content per the SOT's read
+   command families. No mutation of anything.
+2. `member` — work: everything `viewer` has, plus write authorization for
+   business/orchestration command families in descendant workspaces (the
+   concrete command-family mapping is implementation work under SOT
+   REQ-ID-001; this contract pins that `member` maps to the workspace write
+   families and nothing structural).
+3. `owner` — structure: everything `member` has, plus hierarchy mutations on
+   the subtree (create/rename/delete child nodes, transfers per §5), and
+   grant management on the node and its subtree (§4).
+
+No other value is valid in `hierarchy_grants.role`; the column is
+constraint-checked against exactly these three. Extending the vocabulary is a
+contract amendment, not an implementation decision.
+
+## 3. Evaluation semantics
+
+1. **Deny by default.** No grant on any ancestor → no authority. There are
+   no implicit grants: not from platform role (§1.1), not from creating a
+   node (§4.3), not from workspace membership (membership without a chain
+   grant confers exactly what the SOT's own membership rules confer inside
+   that workspace, nothing up the chain).
+2. **Down-the-chain only.** A grant on a node applies to that node and its
+   entire descendant subtree. Nothing evaluates upward or sideways: a grant
+   on an estate says nothing about the parent company or sibling estates.
+3. **Effective role = maximum.** A subject's effective role at any node is
+   the highest role among grants held directly by the subject's user on
+   that node or any ancestor — and, once the team contract activates team
+   subjects (§1.4), grants held by any team the user is a member of on that
+   node or any ancestor. Roles never subtract — there is no negative/deny
+   grant in this model; revocation is deletion (§6).
+4. **Team grants follow live membership** (specified now, active only per
+   §1.4). A team grant confers its role on the team's current members,
+   evaluated at decision time. Leaving the team is loss of the grant with
+   §6's propagation bound.
+5. **Live evaluation, fail closed.** Authorization decisions derive from the
+   live grant and team-membership rows (or from a cache that is invalidated
+   in the same transaction as any grant/membership/hierarchy mutation). A
+   decision path that cannot read grant state denies. No materialized ACL is
+   ever authoritative.
+6. **Tenant context stays derived from authenticated authority**
+   (REQ-TEN-001). The chain adds where grants can be declared; a workspace
+   request is still authorized against that workspace, with the chain
+   contributing the effective role — never letting the chain become what A1
+   §8.1.3 forbids: "a bypass of workspace authorization".
+
+## 4. Grant management
+
+1. Creating, changing, or revoking a grant on a node requires effective
+   `owner` on that node (directly or via any ancestor).
+2. **No self-escalation.** A grant manager cannot create a grant with a role
+   higher than their own effective role on the target node. Under the §2
+   vocabulary this rule is currently implied by §4.1 (managers are `owner`,
+   the top role — no constructible grant exceeds it); it is stated
+   explicitly so it survives any future amendment that decouples
+   grant-management authority from role height. Its observable is the §7.7
+   audit invariant, not a refusal test.
+3. **Bootstrap of authority is explicit; inheritance covers the rest.**
+   Creating the first company (the wizard path, contract 3) and any
+   top-level company creation MUST name the initial `owner` grant in the
+   same audited operation — a top-level node has no ancestor to inherit
+   from, so without this the node would be unownable. Creating a child node
+   (estate, platform-project, workspace) requires effective `owner` on the
+   parent (§2.3) and confers no automatic grant; the creator's authority
+   over the new node already follows from §3.2 down-the-chain evaluation.
+   The creating command MAY additionally name an explicit initial grant for
+   a child node; it is not required to.
+4. Every grant mutation is a semantic audit event under contract 1 §5.2's
+   guarantees, extended by this contract with two further fields: the event
+   carries actor, verb, target, **subject, and role** (subject and role are
+   this contract's addition; contract 1 §5.2 does not enumerate them).
+5. **Role strings are namespaced.** `viewer`/`member` exist at hierarchy
+   level, `member`/`admin` on `users.role`, and the current command layer
+   uses a third `viewer|member|admin` vocabulary — same strings, different
+   meanings. Any serialized role string (audit events per §4.4, API
+   responses, logs) MUST identify its layer (e.g. `hierarchy:owner`,
+   `platform:admin`); a bare role string in a serialized artifact is
+   non-conformant.
+
+## 5. Transfer authority (completes contract 1 §4.2)
+
+"Authority over BOTH the source and the destination parent" means: effective
+`owner` on the current parent node (or an ancestor) AND effective `owner` on
+the destination parent node (or an ancestor), evaluated at transfer time in
+the transfer's own transaction. One subject must hold both; two cooperating
+half-authorized subjects are not a transfer protocol this contract defines.
+
+## 6. Revocation propagation
+
+1. Revoking a grant (deleting the row), removing a user from a team that
+   carries a grant (once team subjects activate, §1.4), or the cascade
+   deletion of a node's grants during node deletion (contract 1 §3.3) all
+   propagate identically: the authority derived from that grant is gone for
+   every descendant workspace.
+2. **Bound:** the next authorization decision on any affected transport
+   decides against the revoked grant. Concretely: no new HTTP/MCP command
+   authorized by the revoked grant after the revoking transaction commits;
+   an open Socket.IO connection whose subscriptions depend on the revoked
+   grant is re-evaluated within 30 seconds or at its next inbound message,
+   whichever comes first (same bound as the identity contract's §7.1
+   deactivation rule; same mechanism may serve both).
+3. Revocation is subtractive only in effect, not in representation: the
+   evaluator never needs tombstones; deletion of the row is the revocation.
+
+## 7. Verification requirements
+
+Binding on the implementing PRs (extends A1 §8.3 acceptance 2–3 and
+contract 1 §6):
+
+1. Vocabulary: the role CHECK constraint rejects any value outside
+   `viewer|member|owner` (real-PostgreSQL witness, `ci-postgres` service in
+   the `test` CI step).
+2. Per-level conferral: for each of the three levels × three roles, a grant
+   yields exactly the implied workspace authorization in a descendant
+   workspace and nothing in a non-descendant workspace (the A1 §8.3
+   "exactly the permissions the chain implies" matrix, enumerated). The
+   matrix includes: a chain grant creates zero workspace-membership rows
+   (assert row counts); a chain-granted non-member is refused as the
+   principal argument of any principal-taking command while their
+   non-principal writes succeed (§1.3); structure reads leak no existence
+   of nodes the reader holds no grant on (no cross-tenant existence
+   oracle, A1 §8.3 acceptance 3).
+3. Ordering: `owner` ⊇ `member` ⊇ `viewer` behaviorally — each higher role
+   passes every lower role's positive cases.
+4. Deny-by-default: platform `admin` with no grant reaches no tenant
+   content — asserted against the two §1.1 non-conformant surfaces after
+   their retirement: the command-authorization admin short-circuit and the
+   MCP tenant-admin scope derivation both gone (a platform admin with no
+   grant is refused workspace commands and receives no tenant MCP scopes);
+   workspace member with no chain grant gains nothing outside SOT
+   membership semantics; fresh account reaches nothing (identity contract
+   §1.4 cross-check).
+5. Team subjects: while suspended (§1.4), creating a team-subject grant is
+   refused at the command surface. On activation by the team contract:
+   user-direct and team-conferred grants combine to the maximum; team-leave
+   drops authority within the §6.2 bound; decision-time evaluation
+   witnessed (grant added → next decision allows; no restart or re-login
+   required).
+6. Revocation: each revocation path in §6.1 denies the next command on
+   every transport; the socket bound is measured; a cached-authorization
+   implementation proves transactional invalidation (grant revoked and
+   decision made on two distinct physical connections). Fail-closed fault
+   witness for §3.5: with grant state unreadable (fault injection), the
+   decision denies.
+7. Grant management: non-`owner` cannot mutate grants; top-level company
+   creation without the named initial `owner` grant is refused, while child
+   node creation under ancestor authority succeeds without one (§4.3 both
+   directions); every mutation produces its audit event with the §4.4
+   fields. Self-escalation observable: over the audit event stream, every
+   grant-create/change event's role is ≤ the acting user's effective role
+   on the target at event time (reconstructable invariant, not a refusal
+   test — see §4.2).
+8. Transfer: both-sides `owner` accepted, each single-side case refused
+   (completing contract 1 §6.5).
+
+## Ruling request
+
+Ratify sections 1–7 as written, with one decision embedded and one
+interpretive resolution named:
+
+- Decision: platform `admin` confers no implicit tenant access — operators
+  see tenant content only through explicit, audited grants (§1.1), which
+  retires the two existing admin bypass paths named there. Say "agreed" or
+  name the implicit access you want platform admins to keep.
+- Interpretive resolution (for visibility, not a separate question): PRD
+  Part I §4 says "admins restrict access per company, estate, and project";
+  this contract resolves "admins" as hierarchy `owner`s (§4.1), not
+  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.

packages/db/drizzle/0019_volatile_killraven.sql

@@ -0,0 +1,40 @@
+CREATE TYPE "public"."hierarchy_outbox_status" AS ENUM('pending', 'processing', 'delivered');--> statement-breakpoint
+CREATE TABLE "hierarchy_audit_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"seq" bigint GENERATED ALWAYS AS IDENTITY (sequence name "hierarchy_audit_events_seq_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 9223372036854775807 START WITH 1 CACHE 1),
+	"actor_id" text NOT NULL,
+	"verb" text NOT NULL,
+	"target_kind" text NOT NULL,
+	"target_id" uuid NOT NULL,
+	"target_snapshot" jsonb NOT NULL,
+	"transfer_from" jsonb,
+	"transfer_to" jsonb,
+	"correlation_id" text NOT NULL,
+	"causation_id" uuid,
+	"idempotency_key" text NOT NULL,
+	"occurred_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "hierarchy_audit_events_verb_check" CHECK (verb IN ('create', 'rename', 'transfer', 'delete', 'grant_create', 'grant_change', 'grant_revoke')),
+	CONSTRAINT "hierarchy_audit_events_target_kind_check" CHECK (target_kind IN ('company', 'estate', 'platform_project', 'grant')),
+	CONSTRAINT "hierarchy_audit_events_transfer_check" CHECK ((verb = 'transfer') = (transfer_from IS NOT NULL AND transfer_to IS NOT NULL))
+);
+--> statement-breakpoint
+CREATE TABLE "hierarchy_outbox" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"event_id" uuid NOT NULL,
+	"idempotency_key" text NOT NULL,
+	"correlation_id" text NOT NULL,
+	"status" "hierarchy_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 "hierarchy_audit_events" ADD CONSTRAINT "hierarchy_audit_events_causation_id_hierarchy_audit_events_id_fk" FOREIGN KEY ("causation_id") REFERENCES "public"."hierarchy_audit_events"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "hierarchy_outbox" ADD CONSTRAINT "hierarchy_outbox_event_id_hierarchy_audit_events_id_fk" FOREIGN KEY ("event_id") REFERENCES "public"."hierarchy_audit_events"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "hierarchy_audit_events_idempotency_idx" ON "hierarchy_audit_events" USING btree ("idempotency_key");--> statement-breakpoint
+CREATE UNIQUE INDEX "hierarchy_audit_events_seq_idx" ON "hierarchy_audit_events" USING btree ("seq");--> statement-breakpoint
+CREATE INDEX "hierarchy_audit_events_target_seq_idx" ON "hierarchy_audit_events" USING btree ("target_id","seq");--> statement-breakpoint
+CREATE INDEX "hierarchy_audit_events_correlation_idx" ON "hierarchy_audit_events" USING btree ("correlation_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "hierarchy_outbox_event_idx" ON "hierarchy_outbox" USING btree ("event_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "hierarchy_outbox_idempotency_idx" ON "hierarchy_outbox" USING btree ("idempotency_key");--> statement-breakpoint
+CREATE INDEX "hierarchy_outbox_status_created_idx" ON "hierarchy_outbox" USING btree ("status","created_at");

packages/db/drizzle/meta/_journal.json

@@ -134,6 +134,13 @@
       "when": 1787862158838,
       "tag": "0018_clean_cobalt_man",
       "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1787880918208,
+      "tag": "0019_volatile_killraven",
+      "breakpoints": true
     }
   ]
 }

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

@@ -0,0 +1,363 @@
+/**
+ * Hierarchy audit event + outbox schema witnesses — contract 1 §5.2 and the
+ * schema-level half of §6.4.
+ *
+ * Witnesses the guarantees the tables themselves carry: verb/target-kind/
+ * transfer CHECK constraints, idempotency uniqueness (REQ-AUD-001 duplicate
+ * suppression at the database level), monotonic append order (`seq`),
+ * deletion-safe linkage (no foreign key from the events table into any class
+ * table — events survive the deletion of their target), the causation
+ * self-FK, and the outbox's FK/uniqueness/status shape. The repository-level
+ * half of §6.4 (same-transaction atomicity, rollback, replay) is witnessed in
+ * apps/gateway/src/hierarchy/hierarchy-audit.integration.test.ts.
+ *
+ * Two legs run the same witness body:
+ *  - PGlite (WASM Postgres): always runs.
+ *  - Real PostgreSQL (§6.8): 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 { companies, hierarchyAuditEvents, hierarchyOutbox } 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 = `hier-a-${randomUUID().slice(0, 8)}`;
+
+/** Minimal valid event row; overrides compose the negative cases. */
+type EventInsert = typeof hierarchyAuditEvents.$inferInsert;
+
+function eventRow(overrides: Partial<EventInsert> = {}): EventInsert {
+  return {
+    actorId: `${T}-actor`,
+    verb: 'create',
+    targetKind: 'company',
+    targetId: randomUUID(),
+    targetSnapshot: { id: 'x', slug: 'x', name: 'x', parentChain: [] },
+    correlationId: `${T}-corr`,
+    idempotencyKey: `${T}-${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 hierarchy_outbox WHERE idempotency_key LIKE ${T + '%'}`);
+    // Caused events first: the causation self-FK is RESTRICT.
+    await d.execute(
+      sql`DELETE FROM hierarchy_audit_events WHERE idempotency_key LIKE ${T + '%'} AND causation_id IS NOT NULL`,
+    );
+    await d.execute(sql`DELETE FROM hierarchy_audit_events WHERE idempotency_key LIKE ${T + '%'}`);
+    await d.execute(sql`DELETE FROM companies WHERE slug LIKE ${T + '%'}`);
+  });
+
+  // ── CHECK constraints ──────────────────────────────────────────────────────
+
+  it('accepts every declared verb and refuses an undeclared one', async () => {
+    for (const verb of [
+      'create',
+      'rename',
+      'delete',
+      'grant_create',
+      'grant_change',
+      'grant_revoke',
+    ]) {
+      await db().insert(hierarchyAuditEvents).values(eventRow({ verb }));
+    }
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ verb: 'update' })),
+      /verb_check|violates check/i,
+      'undeclared verb must be refused',
+    );
+  });
+
+  it('refuses an undeclared target kind', async () => {
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ targetKind: 'workspace' })),
+      /target_kind_check|violates check/i,
+      'workspace is not an audited target kind (workspace mutation is SOT-side)',
+    );
+  });
+
+  it('requires transfer snapshots exactly on transfers', async () => {
+    const parent = { kind: 'company', id: randomUUID(), slug: 'p' };
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(
+        eventRow({
+          verb: 'transfer',
+          targetKind: 'estate',
+          transferFrom: parent,
+          transferTo: { ...parent, id: randomUUID() },
+        }),
+      );
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ verb: 'transfer' })),
+      /transfer_check|violates check/i,
+      'transfer without source/destination snapshots must be refused',
+    );
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ verb: 'transfer', transferFrom: parent })),
+      /transfer_check|violates check/i,
+      'transfer with only the source snapshot must be refused',
+    );
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ verb: 'create', transferFrom: parent, transferTo: parent })),
+      /transfer_check|violates check/i,
+      'non-transfer with transfer snapshots must be refused',
+    );
+  });
+
+  // ── Idempotency and ordering ───────────────────────────────────────────────
+
+  it('refuses a duplicate idempotency key', async () => {
+    const key = `${T}-dup-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ idempotencyKey: key }));
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ idempotencyKey: key })),
+      /duplicate key|unique/i,
+    );
+  });
+
+  it('assigns strictly increasing seq in insert order for one target', async () => {
+    const targetId = randomUUID();
+    const k1 = `${T}-seq-1-${randomUUID()}`;
+    const k2 = `${T}-seq-2-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ targetId, idempotencyKey: k1 }));
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ targetId, verb: 'rename', idempotencyKey: k2 }));
+    const res = rows(
+      await db().execute(
+        sql`SELECT idempotency_key, seq FROM hierarchy_audit_events WHERE target_id = ${targetId} ORDER BY seq ASC`,
+      ),
+    );
+    expect(res.map((r) => r['idempotency_key'])).toEqual([k1, k2]);
+    expect(Number(res[1]!['seq'])).toBeGreaterThan(Number(res[0]!['seq']));
+  });
+
+  // ── Deletion-safe linkage (§5.2) ───────────────────────────────────────────
+
+  it('has no foreign key into any class table, and events survive target 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 = 'hierarchy_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(['hierarchy_audit_events']);
+
+    const companyId = randomUUID();
+    await db()
+      .insert(companies)
+      .values({ id: companyId, name: 'Doomed', slug: `${T}-doomed` });
+    const key = `${T}-survive-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(
+        eventRow({
+          verb: 'delete',
+          targetId: companyId,
+          targetSnapshot: { id: companyId, slug: `${T}-doomed`, name: 'Doomed', parentChain: [] },
+          idempotencyKey: key,
+        }),
+      );
+    await db().execute(sql`DELETE FROM companies WHERE id = ${companyId}`);
+    const after = rows(
+      await db().execute(
+        sql`SELECT target_snapshot FROM hierarchy_audit_events WHERE idempotency_key = ${key}`,
+      ),
+    );
+    expect(after).toHaveLength(1);
+    expect((after[0]!['target_snapshot'] as { id: string }).id).toBe(companyId);
+  });
+
+  it('enforces the causation self-FK and RESTRICTs deleting a cause', async () => {
+    await expectViolation(
+      db()
+        .insert(hierarchyAuditEvents)
+        .values(eventRow({ causationId: randomUUID() })),
+      /foreign key/i,
+      'causation must reference an existing event',
+    );
+    const causeKey = `${T}-cause-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ verb: 'delete', idempotencyKey: causeKey }));
+    const cause = rows(
+      await db().execute(
+        sql`SELECT id FROM hierarchy_audit_events WHERE idempotency_key = ${causeKey}`,
+      ),
+    )[0]!;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(
+        eventRow({ verb: 'grant_revoke', targetKind: 'grant', causationId: cause['id'] as string }),
+      );
+    await expectViolation(
+      db().execute(sql`DELETE FROM hierarchy_audit_events WHERE id = ${cause['id'] as string}`),
+      /foreign key/i,
+      'a cause with dependent events must not be deletable',
+    );
+  });
+
+  // ── Outbox shape ───────────────────────────────────────────────────────────
+
+  it('outbox rows require an existing event, one outbox row per event, unique idempotency', async () => {
+    await expectViolation(
+      db()
+        .insert(hierarchyOutbox)
+        .values({
+          eventId: randomUUID(),
+          idempotencyKey: `${T}-ob-${randomUUID()}`,
+          correlationId: `${T}-corr`,
+        }),
+      /foreign key/i,
+      'outbox must reference an existing event',
+    );
+    const key = `${T}-ob-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ idempotencyKey: key }));
+    const event = rows(
+      await db().execute(sql`SELECT id FROM hierarchy_audit_events WHERE idempotency_key = ${key}`),
+    )[0]!;
+    const eventId = event['id'] as string;
+    await db()
+      .insert(hierarchyOutbox)
+      .values({ eventId, idempotencyKey: key, correlationId: `${T}-corr` });
+    await expectViolation(
+      db()
+        .insert(hierarchyOutbox)
+        .values({ eventId, idempotencyKey: `${T}-ob2-${randomUUID()}`, correlationId: `${T}-c` }),
+      /duplicate key|unique/i,
+      'one outbox record per event',
+    );
+    await expectViolation(
+      db().execute(
+        sql`INSERT INTO hierarchy_outbox (event_id, idempotency_key, correlation_id, status)
+            VALUES (${eventId}, ${`${T}-ob3-${randomUUID()}`}, 'c', '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 key = `${T}-obr-${randomUUID()}`;
+    await db()
+      .insert(hierarchyAuditEvents)
+      .values(eventRow({ idempotencyKey: key }));
+    const event = rows(
+      await db().execute(sql`SELECT id FROM hierarchy_audit_events WHERE idempotency_key = ${key}`),
+    )[0]!;
+    await db()
+      .insert(hierarchyOutbox)
+      .values({
+        eventId: event['id'] as string,
+        idempotencyKey: key,
+        correlationId: `${T}-corr`,
+      });
+    await expectViolation(
+      db().execute(sql`DELETE FROM hierarchy_audit_events WHERE id = ${event['id'] as string}`),
+      /foreign key/i,
+    );
+  });
+}
+
+// ── Leg 1: PGlite (always runs — local witness signal) ───────────────────────
+
+describe('hierarchy audit witnesses — PGlite', () => {
+  let dir: string;
+  let handle: ReturnType<typeof createPgliteDb>;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'hier-audit-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 (§6.8 — binding witness, ci-postgres in CI) ───────
+
+const hasPostgres = Boolean(process.env['DATABASE_URL']);
+
+describe.skipIf(!hasPostgres)('hierarchy audit 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-writer-coverage.test.ts

@@ -123,18 +123,20 @@
  *     tracked for M4-1b consideration); the counterfactual — flagging every
  *     bare identifier call — false-positives on essentially all callback
  *     code. Reviews of modules touching db handles carry this residual.
- *   - The scan perimeter is <root>/<pkg>/src for the three roots; production
- *     TS outside a src/ directory (e.g. packages/mosaic/framework/**) is not
- *     scanned (verified free of db/driver/execute references at review time).
- *     Files excluded from the scan — test files and out-of-src modules — are
- *     also invisible as import-graph CONDUITS: test files are emitted to
- *     dist, so a production module could launder a symbol or capability
- *     through a re-export in one. Importing a test module from production
- *     code is anomalous and review-visible; the blind spot is accepted as a
- *     residual, not closed.
+ *   - The scan perimeter is the full <root>/<pkg> tree for the three roots
+ *     (build output, tool caches, and dot-directories excluded), so
+ *     production TS outside src/ — package configs, e2e helpers,
+ *     packages/mosaic/framework/** — is scanned and conduit-visible
+ *     (widened from src/-only in M4-1b-i; the widened set was measured free
+ *     of every trigger token at the time). Files excluded from the scan —
+ *     test files — are still invisible as import-graph CONDUITS: test files
+ *     are emitted to dist, so a production module could launder a symbol or
+ *     capability through a re-export in one. Importing a test module from
+ *     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) has not landed, so no
+ * empty today: the hierarchy command family (M4-1b-ii) has not landed, so no
  * production module may 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
@@ -179,7 +181,8 @@ const CLASS_TABLES = [
 
 /**
  * Writer allowlist (§6.3b): hierarchy command/repository modules only.
- * EMPTY until the hierarchy command family lands (M4-1b). Adding a module
+ * 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.
@@ -291,20 +294,23 @@ function isTestPath(rel: string): boolean {
   );
 }
 
+/** Directory names excluded from the walk: build output and tool caches only. */
+const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage', 'test-results']);
+
 function collectSources(): string[] {
   const files: string[] = [];
   for (const root of SCAN_ROOTS) {
     const rootDir = join(REPO_ROOT, root);
     if (!existsSync(rootDir)) continue;
     for (const pkg of readdirSync(rootDir)) {
-      const srcDir = join(rootDir, pkg, 'src');
-      if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) continue;
+      const pkgDir = join(rootDir, pkg);
+      if (!statSync(pkgDir).isDirectory()) continue;
       const walk = (dir: string): void => {
         for (const entry of readdirSync(dir)) {
           const full = join(dir, entry);
           const st = statSync(full);
           if (st.isDirectory()) {
-            if (entry === 'node_modules' || entry === 'dist') continue;
+            if (EXCLUDED_DIRS.has(entry) || entry.startsWith('.')) continue;
             walk(full);
           } else if (EXTENSIONS.has(full.slice(full.lastIndexOf('.')))) {
             const rel = relative(REPO_ROOT, full).split(sep).join('/');
@@ -312,7 +318,7 @@ function collectSources(): string[] {
           }
         }
       };
-      walk(srcDir);
+      walk(pkgDir);
     }
   }
   return files.sort();

packages/db/src/schema.ts

@@ -4,6 +4,7 @@
  */
 
 import { sql } from 'drizzle-orm';
+import type { AnyPgColumn } from 'drizzle-orm/pg-core';
 import {
   pgTable,
   pgEnum,
@@ -1152,3 +1153,111 @@ export const hierarchyGrants = pgTable(
     index('hierarchy_grants_granted_by_idx').on(t.grantedBy),
   ],
 );
+
+// ─── Hierarchy audit events + outbox (contract 1 §5.2) ──────────────────────
+// NOT part of the record class (the class is exactly the five tables above).
+// Append-only semantic audit log for hierarchy mutations, with a dedicated
+// transactional outbox — hierarchy events are not workspace-scoped rows and
+// do not ride the workspace outbox. Deletion-safe linkage: events reference
+// their target by an immutable snapshot (id, slug, parent chain at event
+// time), never by a foreign key into the class tables, so append-only events
+// survive the deletion of their target. Append-only is enforced at the
+// application layer (the hierarchy audit repository exposes no update/delete
+// path for events); REQ-AUD-001's INSERT/SELECT-only database role is a
+// deployment concern outside this schema.
+
+export const HIERARCHY_AUDIT_VERBS = [
+  'create',
+  'rename',
+  'transfer',
+  'delete',
+  'grant_create',
+  'grant_change',
+  'grant_revoke',
+] as const;
+
+export const HIERARCHY_AUDIT_TARGET_KINDS = [
+  'company',
+  'estate',
+  'platform_project',
+  'grant',
+] as const;
+
+export const hierarchyAuditEvents = pgTable(
+  'hierarchy_audit_events',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // Global append order; per-target ordering (REQ-AUD-001) is a filter on
+    // target_id ordered by seq.
+    seq: bigint('seq', { mode: 'number' }).notNull().generatedAlwaysAsIdentity(),
+    // No FK: audit events outlive every principal and every target (§5.2).
+    actorId: text('actor_id').notNull(),
+    verb: text('verb').notNull(),
+    targetKind: text('target_kind').notNull(),
+    targetId: uuid('target_id').notNull(),
+    // Immutable snapshot at event time. Node events: { id, slug, name,
+    // parentChain: [{ kind, id, slug }, …] root-first }. Grant events:
+    // { id, subject: { userId | teamId }, target: { kind, id }, role }
+    // (subject and role per contract 2 §4.4).
+    targetSnapshot: jsonb('target_snapshot').notNull(),
+    // Present exactly on transfers: snapshot of the source/destination
+    // parent ({ kind, id, slug }), CHECK-enforced below.
+    transferFrom: jsonb('transfer_from'),
+    transferTo: jsonb('transfer_to'),
+    correlationId: text('correlation_id').notNull(),
+    // Prior event in the causal chain (e.g. cascaded grant_revoke events
+    // caused by a node delete). Self-FK RESTRICT keeps the chain intact.
+    causationId: uuid('causation_id').references((): AnyPgColumn => hierarchyAuditEvents.id, {
+      onDelete: 'restrict',
+    }),
+    idempotencyKey: text('idempotency_key').notNull(),
+    occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    uniqueIndex('hierarchy_audit_events_idempotency_idx').on(t.idempotencyKey),
+    uniqueIndex('hierarchy_audit_events_seq_idx').on(t.seq),
+    index('hierarchy_audit_events_target_seq_idx').on(t.targetId, t.seq),
+    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')`,
+    ),
+    check(
+      'hierarchy_audit_events_target_kind_check',
+      sql`target_kind IN ('company', 'estate', 'platform_project', 'grant')`,
+    ),
+    check(
+      'hierarchy_audit_events_transfer_check',
+      sql`(verb = 'transfer') = (transfer_from IS NOT NULL AND transfer_to IS NOT NULL)`,
+    ),
+  ],
+);
+
+export const hierarchyOutboxStatusEnum = pgEnum('hierarchy_outbox_status', [
+  'pending',
+  'processing',
+  'delivered',
+]);
+
+export const hierarchyOutbox = pgTable(
+  'hierarchy_outbox',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // FK into the append-only events table (not a class table): never
+    // dangles, so RESTRICT is safe and keeps event/outbox integrity.
+    eventId: uuid('event_id')
+      .notNull()
+      .references(() => hierarchyAuditEvents.id, { onDelete: 'restrict' }),
+    idempotencyKey: text('idempotency_key').notNull(),
+    correlationId: text('correlation_id').notNull(),
+    status: hierarchyOutboxStatusEnum('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('hierarchy_outbox_event_idx').on(t.eventId),
+    uniqueIndex('hierarchy_outbox_idempotency_idx').on(t.idempotencyKey),
+    index('hierarchy_outbox_status_created_idx').on(t.status, t.createdAt),
+  ],
+);

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
@@ -32,45 +33,61 @@ ISSUE_NUMBER=""
 COMMENT=""
 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)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             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 ]] || usage_error "option $1 requires a value"
             COMMENT="$2"
             shift 2
             ;;
         -l|--login)
+            [[ $# -ge 2 ]] || usage_error "option $1 requires a value"
             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 "  -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
 
 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 +357,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/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,165 @@
+#!/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 "$desc: 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
+
+# 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"
+
+# 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/quality/test-enumeration-exclusions.txt

@@ -14,7 +14,6 @@
 packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix (git -C scoping)
 packages/mosaic/framework/tools/git/test-issue-create-interactive-auth.sh | resolves real credentials (#1007 census); joins CI after the wrapper-half hermeticity fix
 packages/mosaic/framework/tools/git/test-pr-metadata-gitea.sh | resolves real credentials (#1007 census, fourth entry via family-grep); joins CI after the wrapper-half hermeticity fix
-packages/mosaic/framework/tools/git/test-issue-comment-readback.sh | resolves real credentials (#1007 census, fifth entry); joins CI after the wrapper-half hermeticity fix
 
 # --- tools/git: push guards — measured green locally, CI-image fitness unverified ---
 packages/mosaic/framework/tools/git/test-push-guard.sh | measured green at 826a8b3b (46 passed / 0 failed, one run, 2026-07-31); CI-image fitness unverified; #1017 burndown

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.sh && bash framework/tools/git/test-repo-decl-consumption.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-no-status.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh && bash framework/tools/fleet/test-agent-session-legacy-socket-guard.sh && bash framework/tools/git/test-grant-reviewer.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 framework/tools/quality/scripts/test-framework-drift-check.py && bash framework/tools/quality/scripts/test-framework-drift-doctor.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/lease-broker/revoke_noop_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-edit.sh && bash framework/tools/git/test-pr-create-fallback-default-base.sh && bash framework/tools/git/test-repo-decl-consumption.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-no-status.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-ci-queue-wait-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-no-ci-expected.sh && bash framework/tools/git/test-pr-merge-fork-ci-status.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-issue-comment-usage-contract.sh && bash framework/tools/git/test-issue-comment-readback.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh && bash framework/tools/_scripts/test-brain-home-check.sh && bash framework/tools/_scripts/test-structure-anchor-check.sh && bash framework/tools/fleet/test-agent-session-broker-preflight.sh && bash framework/tools/fleet/test-agent-session-legacy-socket-guard.sh && bash framework/tools/git/test-grant-reviewer.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/cli.ts

@@ -11,6 +11,9 @@ import { registerQualityRails } from '@mosaicstack/quality-rails';
 import { registerQueueCommand } from '@mosaicstack/queue';
 import { registerStorageCommand } from '@mosaicstack/storage';
 import { registerTelemetryCommand } from './commands/telemetry.js';
+import { registerCommsCommand } from './commands/comms.js';
+import { registerQCommand } from './commands/q.js';
+import { registerWatchCommand } from './commands/watch.js';
 import { registerAgentCommand } from './commands/agent.js';
 import { registerInteractionCommand } from './commands/interaction.js';
 import { registerConfigCommand } from './commands/config.js';
@@ -428,6 +431,9 @@ registerSkillCommand(program);
 // ─── telemetry ───────────────────────────────────────────────────────────────
 
 registerTelemetryCommand(program);
+registerWatchCommand(program);
+registerQCommand(program);
+registerCommsCommand(program);
 
 // ─── update ─────────────────────────────────────────────────────────────
 

packages/mosaic/src/commands/brain-dispatch.ts

@@ -0,0 +1,67 @@
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { join } from 'node:path';
+
+import { resolveBrainHome } from '../fleet/brain-home.js';
+
+/**
+ * Shared brain-tool dispatch (fleet CLI integration, Jason ruling
+ * 2026-08-28): the npm package embeds the COMMAND SURFACE; operator-owned
+ * implementations stay in the brain (tools/). Commands resolve the brain
+ * home (MOSAIC_BRAIN_HOME wins — see brain-home.ts) and exec the tool
+ * there. Nothing operator-specific ships inside the package.
+ *
+ * Pass-through contract: arguments, stdout/stderr, and the exit code belong
+ * to the tool. The CLI adds nothing on success; absent tools fail loudly
+ * with the resolved path (127) instead of guessing.
+ */
+
+/** Absolute path of a brain-relative tool. */
+export function resolveBrainTool(mosaicHome: string, relPath: string): string {
+  return join(resolveBrainHome(mosaicHome), ...relPath.split('/'));
+}
+
+/** Map a spawnSync result + tool existence to the CLI exit status. */
+export function exitStatusFor(
+  result: { status: number | null; error?: NodeJS.ErrnoException },
+  toolExists: boolean,
+): number {
+  if (!toolExists) return 127;
+  if (result.status !== null) return result.status;
+  return 125; // killed by signal / could not run
+}
+
+export function brainToolExists(tool: string): boolean {
+  try {
+    accessSync(tool, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Exec a brain tool with full pass-through. `interpreter` runs the tool
+ * through e.g. python3 (renderers); omit it for executable scripts.
+ * Returns the process exit status; callers assign it to process.exitCode.
+ */
+export function execBrainTool(
+  mosaicHome: string,
+  relPath: string,
+  args: string[],
+  interpreter?: string,
+): number {
+  const tool = resolveBrainTool(mosaicHome, relPath);
+  if (!brainToolExists(tool)) {
+    console.error(
+      `mosaic: brain tool not found (expected ${tool}). ` +
+        'Tool suites live in the brain tree under tools/; ' +
+        'check MOSAIC_BRAIN_HOME or the brain checkout.',
+    );
+    return 127;
+  }
+  const result = interpreter
+    ? spawnSync(interpreter, [tool, ...args], { stdio: 'inherit', env: process.env })
+    : spawnSync(tool, args, { stdio: 'inherit', env: process.env });
+  return exitStatusFor(result, true);
+}

packages/mosaic/src/commands/comms.spec.ts

@@ -0,0 +1,143 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  writeFileSync,
+  readFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { Command } from 'commander';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { fleetCommsSendArgs, registerCommsCommand, tmuxSendArgs } from './comms.js';
+
+describe('arg translation', () => {
+  it('tmux path: -s/-C/-L/-f/-m per agent-send.sh getopts', () => {
+    expect(tmuxSendArgs('orch-01', 'hello', {})).toEqual(['-s', 'orch-01', '-m', 'hello']);
+    expect(
+      tmuxSendArgs('orch-01', 'unused', {
+        class: 'actionable',
+        socket: 'mosaic-fleet',
+        file: '/tmp/body.txt',
+      }),
+    ).toEqual(['-s', 'orch-01', '-C', 'actionable', '-L', 'mosaic-fleet', '-f', '/tmp/body.txt']);
+  });
+
+  it('fleet-comms path: -t site/agent and -c class', () => {
+    expect(fleetCommsSendArgs('usc', 'fred', 'hi', {})).toEqual(['-t', 'usc/fred', '-m', 'hi']);
+    expect(fleetCommsSendArgs('usc', 'fred', 'hi', { class: 'human' })).toEqual([
+      '-t',
+      'usc/fred',
+      '-c',
+      'human',
+      '-m',
+      'hi',
+    ]);
+  });
+});
+
+describe('registerCommsCommand routing', () => {
+  const savedBrain = process.env['MOSAIC_BRAIN_HOME'];
+  const savedRepo = process.env['MOSAIC_FLEET_COMMS_REPO'];
+  const savedAgent = process.env['MOSAIC_AGENT_NAME'];
+  afterEach(() => {
+    for (const [k, v] of [
+      ['MOSAIC_BRAIN_HOME', savedBrain],
+      ['MOSAIC_FLEET_COMMS_REPO', savedRepo],
+      ['MOSAIC_AGENT_NAME', savedAgent],
+    ] as const) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    process.exitCode = undefined;
+  });
+
+  function fixture(): { brain: string; repo: string; tmuxLog: string; commsLog: string } {
+    const brain = mkdtempSync(join(tmpdir(), 'comms-brain-'));
+    const repo = mkdtempSync(join(tmpdir(), 'comms-repo-'));
+    mkdirSync(join(brain, 'tools', 'tmux'), { recursive: true });
+    mkdirSync(join(repo, 'tools'), { recursive: true });
+    const tmuxLog = join(brain, 'tmux.log');
+    const commsLog = join(repo, 'comms.log');
+    writeFileSync(
+      join(brain, 'tools', 'tmux', 'agent-send.sh'),
+      `#!/usr/bin/env bash\nprintf '%s\\n' "$*" >> ${JSON.stringify(tmuxLog)}\nexit 7\n`,
+    );
+    writeFileSync(
+      join(repo, 'tools', 'comms-send.sh'),
+      `#!/usr/bin/env bash\nprintf '%s\\n' "$*" >> ${JSON.stringify(commsLog)}\nprintf 'FLEET_COMMS_REPO=%s FLEET_COMMS_SITE=%s\\n' "$FLEET_COMMS_REPO" "$FLEET_COMMS_SITE" >> ${JSON.stringify(commsLog)}\nexit 5\n`,
+    );
+    chmodSync(join(brain, 'tools', 'tmux', 'agent-send.sh'), 0o755);
+    chmodSync(join(repo, 'tools', 'comms-send.sh'), 0o755);
+    process.env['MOSAIC_BRAIN_HOME'] = brain;
+    process.env['MOSAIC_FLEET_COMMS_REPO'] = repo;
+    process.env['MOSAIC_AGENT_NAME'] = 'tester';
+    return { brain, repo, tmuxLog, commsLog };
+  }
+
+  it('default routes same-host via agent-send with translated flags and passes rc through', async () => {
+    const f = fixture();
+    const program = new Command();
+    registerCommsCommand(program);
+    await program.parseAsync(
+      [
+        'comms',
+        'send',
+        'orch-01',
+        '--class',
+        'actionable',
+        '--socket',
+        'mosaic-fleet',
+        'verdict',
+        'landed',
+      ],
+      { from: 'user' },
+    );
+    expect(process.exitCode).toBe(7);
+    expect(readFileSync(f.tmuxLog, 'utf8').trim()).toBe(
+      '-s orch-01 -C actionable -L mosaic-fleet -m verdict landed',
+    );
+    expect(existsSync(f.commsLog)).toBe(false); // inter-site tool never invoked
+  });
+
+  it('--site routes inter-site via comms-send with site-prefixed target and passes rc through', async () => {
+    const f = fixture();
+    const program = new Command();
+    registerCommsCommand(program);
+    await program.parseAsync(
+      ['comms', 'send', 'fred', '--site', 'usc', '--class', 'human', 'hello', 'there'],
+      { from: 'user' },
+    );
+    expect(process.exitCode).toBe(5);
+    expect(readFileSync(f.commsLog, 'utf8').split('\n')[0]?.trim()).toBe(
+      '-t usc/fred -c human -m hello there',
+    );
+    // The sender must bind comms-send.sh to the SELECTED repo (codex 9c8b6ebf).
+    expect(readFileSync(f.commsLog, 'utf8')).toContain(
+      `FLEET_COMMS_REPO=${f.repo} FLEET_COMMS_SITE=usc`,
+    );
+    expect(existsSync(f.tmuxLog)).toBe(false); // same-host tool never invoked
+  });
+
+  it('inter-site without MOSAIC_AGENT_NAME is an invocation defect (exit 2)', async () => {
+    const f = fixture();
+    delete process.env['MOSAIC_AGENT_NAME'];
+    const program = new Command();
+    registerCommsCommand(program);
+    await program.parseAsync(['comms', 'send', 'fred', '--site', 'usc', 'hi'], { from: 'user' });
+    expect(process.exitCode).toBe(2);
+    expect(existsSync(f.commsLog)).toBe(false); // inter-site tool never invoked
+  });
+
+  it('missing fleet-comms repo fails 127 naming the expected path', async () => {
+    fixture();
+    process.env['MOSAIC_FLEET_COMMS_REPO'] = '/nonexistent-comms-repo';
+    const program = new Command();
+    registerCommsCommand(program);
+    await program.parseAsync(['comms', 'send', 'fred', '--site', 'usc', 'hi'], { from: 'user' });
+    expect(process.exitCode).toBe(127);
+  });
+});

packages/mosaic/src/commands/comms.ts

@@ -0,0 +1,135 @@
+import type { Command } from 'commander';
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { DEFAULT_MOSAIC_HOME } from '../constants.js';
+import { execBrainTool } from './brain-dispatch.js';
+
+/**
+ * `mosaic comms send` — routed agent messaging (FLEET-COMMS.md doctrine).
+ *
+ * Same-host (default): brain tools/tmux/agent-send.sh. Inter-site
+ * (--site <site>): the fleet-comms repo's comms-send.sh — never for
+ * local traffic (a git round trip per message; Jason 2026-08-28).
+ *
+ * Exit codes pass through BOTH paths. rc=2 (text in pane, still draft) is
+ * a CONTRACT, not a failure: never retry, confirm with capture-pane.
+ */
+export interface CommsSendOptions {
+  readonly class?: string;
+  readonly file?: string;
+  readonly socket?: string;
+  readonly site?: string;
+  readonly commsRepo?: string;
+}
+
+export function defaultCommsRepo(): string {
+  return process.env['MOSAIC_FLEET_COMMS_REPO'] ?? join(homedir(), 'src', 'fleet-comms');
+}
+
+/** Build the agent-send.sh argv for the same-host path. */
+export function tmuxSendArgs(target: string, message: string, opts: CommsSendOptions): string[] {
+  const args = ['-s', target];
+  if (opts.class) args.push('-C', opts.class);
+  if (opts.socket) args.push('-L', opts.socket);
+  if (opts.file) args.push('-f', opts.file);
+  else args.push('-m', message);
+  return args;
+}
+
+/** Build the comms-send.sh argv for the inter-site path. */
+export function fleetCommsSendArgs(
+  site: string,
+  target: string,
+  message: string,
+  opts: CommsSendOptions,
+): string[] {
+  const args = ['-t', `${site}/${target}`];
+  if (opts.class) args.push('-c', opts.class);
+  args.push('-m', message);
+  return args;
+}
+
+export function registerCommsCommand(program: Command): void {
+  const cmd: Command = program
+    .command('comms')
+    .description(
+      'Routed agent messaging: tmux same-host (default), fleet-comms inter-site (--site)',
+    )
+    .command('send')
+    .description('send <target> [message...] — same-host tmux unless --site is given')
+    .option('--class <class>', 'terminal-log | actionable | human | reaction | digest')
+    .option('--file <path>', 'message body from file (same-host path only)')
+    .option('--socket <name>', 'tmux socket for the same-host send (e.g. mosaic-fleet)')
+    .option('--site <site>', 'route via fleet-comms to <site>/<target>')
+    .option('--comms-repo <path>', 'fleet-comms checkout', defaultCommsRepo())
+    .argument('<target>', 'destination seat (session name)')
+    .argument('[message...]', 'message text (joined; or use --file)')
+    .action(
+      async (
+        target: string,
+        messageWords: string[],
+        opts: CommsSendOptions & Record<string, unknown>,
+        command: Command,
+      ) => {
+        let mosaicHome: string | undefined;
+        for (let anc: Command | null = command; anc; anc = anc.parent) {
+          const v = (anc.opts() as Record<string, string | undefined>)['mosaicHome'];
+          if (v !== undefined) {
+            mosaicHome = v;
+            break;
+          }
+        }
+        const home = mosaicHome ?? DEFAULT_MOSAIC_HOME;
+        const message = messageWords.join(' ');
+
+        if (opts.site) {
+          const repo = opts.commsRepo ?? defaultCommsRepo();
+          const tool = join(repo, 'tools', 'comms-send.sh');
+          try {
+            accessSync(tool, constants.X_OK);
+          } catch {
+            console.error(
+              `mosaic comms: fleet-comms sender not found (expected ${tool}). ` +
+                'Clone the fleet-comms repo or point --comms-repo at it.',
+            );
+            process.exitCode = 127;
+            return;
+          }
+          if (!process.env['MOSAIC_AGENT_NAME']) {
+            console.error(
+              'mosaic comms: inter-site sends require MOSAIC_AGENT_NAME (sending identity).',
+            );
+            process.exitCode = 2; // invocation defect: fixable by the caller
+            return;
+          }
+          // comms-send.sh locates its working repo via FLEET_COMMS_REPO
+          // (default $HOME/src/fleet-comms); without this, --comms-repo
+          // would select the executable but not the repository it operates
+          // on (codex review of 9c8b6ebf).
+          const env = { ...process.env, FLEET_COMMS_SITE: opts.site, FLEET_COMMS_REPO: repo };
+          const result = spawnSync(tool, fleetCommsSendArgs(opts.site, target, message, opts), {
+            stdio: 'inherit',
+            env,
+          });
+          process.exitCode = result.status ?? 125;
+          return;
+        }
+
+        // Same-host: the brain tool owns validation (bad class -> its rc 3)
+        // and absence (execBrainTool -> 127 with the resolved path).
+        process.exitCode = execBrainTool(
+          home,
+          'tools/tmux/agent-send.sh',
+          tmuxSendArgs(target, message, opts),
+        );
+      },
+    );
+
+  cmd.addHelpText(
+    'after',
+    '\nExit codes pass through. rc=2 means the text reached the pane but is still a draft: NEVER retry (double-send); confirm with tmux capture-pane.',
+  );
+}

packages/mosaic/src/commands/q.spec.ts

@@ -0,0 +1,91 @@
+import { mkdirSync, mkdtempSync, writeFileSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { Command } from 'commander';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { registerQCommand, resolveQuestionTool } from './q.js';
+import { exitStatusFor, resolveBrainTool } from './brain-dispatch.js';
+
+describe('resolveBrainTool', () => {
+  const saved = process.env['MOSAIC_BRAIN_HOME'];
+  afterEach(() => {
+    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
+    else process.env['MOSAIC_BRAIN_HOME'] = saved;
+  });
+
+  it('joins brain home with the relative tool path', () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'dispatch-resolve-'));
+    process.env['MOSAIC_BRAIN_HOME'] = tmp;
+    expect(resolveBrainTool('/nonexistent/mosaic-home', 'tools/questions/q-new.sh')).toBe(
+      join(tmp, 'tools', 'questions', 'q-new.sh'),
+    );
+  });
+});
+
+describe('resolveQuestionTool', () => {
+  const saved = process.env['MOSAIC_BRAIN_HOME'];
+  afterEach(() => {
+    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
+    else process.env['MOSAIC_BRAIN_HOME'] = saved;
+  });
+
+  it('maps new/render subcommands to their brain tools', () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'q-resolve-'));
+    process.env['MOSAIC_BRAIN_HOME'] = tmp;
+    expect(resolveQuestionTool(tmp, 'new')).toBe(join(tmp, 'tools', 'questions', 'q-new.sh'));
+    expect(resolveQuestionTool(tmp, 'render')).toBe(join(tmp, 'tools', 'questions', 'render.py'));
+    expect(resolveQuestionTool(tmp, 'bogus')).toBeUndefined();
+  });
+});
+
+describe('registerQCommand usage + dispatch', () => {
+  const saved = process.env['MOSAIC_BRAIN_HOME'];
+  afterEach(() => {
+    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
+    else process.env['MOSAIC_BRAIN_HOME'] = saved;
+    process.exitCode = undefined;
+  });
+
+  it('exit 2 with the subcommand list when no/unknown subcommand', async () => {
+    process.env['MOSAIC_BRAIN_HOME'] = mkdtempSync(join(tmpdir(), 'q-usage-'));
+    const program = new Command();
+    registerQCommand(program);
+    await program.parseAsync(['q'], { from: 'user' });
+    expect(process.exitCode).toBe(2);
+    process.exitCode = undefined;
+    await program.parseAsync(['q', 'bogus'], { from: 'user' });
+    expect(process.exitCode).toBe(2);
+    process.exitCode = undefined;
+    // Reserved property names must not leak through the record lookup.
+    await program.parseAsync(['q', 'toString'], { from: 'user' });
+    expect(process.exitCode).toBe(2);
+  });
+
+  it('execs the brain tool with pass-through args and exit code', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'q-live-'));
+    process.env['MOSAIC_BRAIN_HOME'] = tmp;
+    mkdirSync(join(tmp, 'tools', 'questions'), { recursive: true });
+    const stub = join(tmp, 'tools', 'questions', 'q-new.sh');
+    writeFileSync(stub, '#!/usr/bin/env bash\necho "called with: $*"\nexit 7\n');
+    chmodSync(stub, 0o755);
+
+    const program = new Command();
+    registerQCommand(program);
+    await program.parseAsync(['q', 'new', '--slug', 'x', '--question', 'why'], { from: 'user' });
+    expect(process.exitCode).toBe(7);
+  });
+});
+
+describe('exitStatusFor (shared dispatch contract)', () => {
+  it('maps absent tool to 127', () => {
+    expect(exitStatusFor({ status: 0 }, false)).toBe(127);
+  });
+  it('passes tool status through', () => {
+    expect(exitStatusFor({ status: 7 }, true)).toBe(7);
+  });
+  it('maps signal death to 125', () => {
+    expect(exitStatusFor({ status: null }, true)).toBe(125);
+  });
+});

packages/mosaic/src/commands/q.ts

@@ -0,0 +1,63 @@
+import type { Command } from 'commander';
+
+import { DEFAULT_MOSAIC_HOME } from '../constants.js';
+import { execBrainTool, resolveBrainTool } from './brain-dispatch.js';
+
+/**
+ * `mosaic q` — tracked decision questions (brain tools/questions).
+ * `new` files a question file (one FILE per question, merge-conflict
+ * impossible by construction); `render` regenerates the
+ * docs/OPEN-QUESTIONS.md index (id allocation happens in the renderer).
+ */
+const SUBCOMMANDS: Record<string, { path: string; interpreter?: string; help: string }> = {
+  new: {
+    path: 'tools/questions/q-new.sh',
+    help: 'file a question (--question, --slug, --owed-by, ...)',
+  },
+  render: {
+    path: 'tools/questions/render.py',
+    interpreter: 'python3',
+    help: 'regenerate docs/OPEN-QUESTIONS.md (owns Q-id allocation)',
+  },
+};
+
+export function resolveQuestionTool(mosaicHome: string, sub: string): string | undefined {
+  const entry = SUBCOMMANDS[sub];
+  return entry ? resolveBrainTool(mosaicHome, entry.path) : undefined;
+}
+
+export function registerQCommand(program: Command): void {
+  const cmd: Command = program
+    .command('q')
+    .description('Tracked decision questions: file and render (brain tools/questions)')
+    .allowUnknownOption()
+    .argument('[args...]', 'subcommand + args passed through to the question tools')
+    .action(async (args: string[], _opts: unknown, command: Command) => {
+      let mosaicHome: string | undefined;
+      for (let anc: Command | null = command; anc; anc = anc.parent) {
+        const v = (anc.opts() as Record<string, string | undefined>)['mosaicHome'];
+        if (v !== undefined) {
+          mosaicHome = v;
+          break;
+        }
+      }
+      const home = mosaicHome ?? DEFAULT_MOSAIC_HOME;
+
+      const sub = args[0];
+      if (!sub || !Object.hasOwn(SUBCOMMANDS, sub)) {
+        console.error('mosaic q: expected a subcommand:');
+        for (const [name, entry] of Object.entries(SUBCOMMANDS)) {
+          console.error(`  mosaic q ${name}   ${entry.help}`);
+        }
+        process.exitCode = 2; // usage error contract: invocation defect
+        return;
+      }
+      const entry = SUBCOMMANDS[sub]!;
+      process.exitCode = execBrainTool(home, entry.path, args.slice(1), entry.interpreter);
+    });
+
+  cmd.addHelpText(
+    'after',
+    '\nEverything after the subcommand is passed through verbatim (args, output, exit code).',
+  );
+}

packages/mosaic/src/commands/watch.spec.ts

@@ -0,0 +1,72 @@
+import { mkdirSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { Command } from 'commander';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { exitStatusFor, registerWatchCommand, resolveAgentWatchTool } from './watch.js';
+
+// The dispatch command execs a real process with inherited stdio; the spec
+// covers the pure resolution and exit-mapping surfaces plus the absent-tool
+// path (which exits without spawning). Live pass-through is exercised by the
+// fleet smoke test against the real brain tool.
+
+describe('resolveAgentWatchTool', () => {
+  const saved = process.env['MOSAIC_BRAIN_HOME'];
+  afterEach(() => {
+    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
+    else process.env['MOSAIC_BRAIN_HOME'] = saved;
+  });
+
+  it('honors MOSAIC_BRAIN_HOME over the canonical brain', () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'watch-resolve-'));
+    process.env['MOSAIC_BRAIN_HOME'] = tmp;
+    expect(resolveAgentWatchTool('/nonexistent/mosaic-home')).toBe(
+      join(tmp, 'tools', 'agent-watch', 'agent-watch.sh'),
+    );
+  });
+
+  it('resolves inside the brain tools tree', () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'watch-resolve-'));
+    process.env['MOSAIC_BRAIN_HOME'] = tmp;
+    const tool = resolveAgentWatchTool(tmp);
+    expect(tool.endsWith(join('tools', 'agent-watch', 'agent-watch.sh'))).toBe(true);
+  });
+});
+
+describe('exitStatusFor', () => {
+  it('maps absent tool to 127', () => {
+    expect(exitStatusFor({ status: 0 }, false)).toBe(127);
+  });
+
+  it('passes the tool exit status through', () => {
+    expect(exitStatusFor({ status: 2 }, true)).toBe(2);
+    expect(exitStatusFor({ status: 78 }, true)).toBe(78);
+  });
+
+  it('maps signal death / null status to 125', () => {
+    expect(exitStatusFor({ status: null }, true)).toBe(125);
+  });
+});
+
+describe('registerWatchCommand absent-tool path', () => {
+  const saved = process.env['MOSAIC_BRAIN_HOME'];
+  afterEach(() => {
+    if (saved === undefined) delete process.env['MOSAIC_BRAIN_HOME'];
+    else process.env['MOSAIC_BRAIN_HOME'] = saved;
+    process.exitCode = undefined;
+  });
+
+  it('sets exitCode 127 with the resolved path when the tool is missing', async () => {
+    const tmp = mkdtempSync(join(tmpdir(), 'watch-missing-'));
+    // The suite directory exists but the tool file does not.
+    mkdirSync(join(tmp, 'tools', 'agent-watch'), { recursive: true });
+    process.env['MOSAIC_BRAIN_HOME'] = tmp;
+
+    const program = new Command();
+    registerWatchCommand(program);
+    await program.parseAsync(['watch', 'list'], { from: 'user' });
+    expect(process.exitCode).toBe(127);
+  });
+});

packages/mosaic/src/commands/watch.ts

@@ -0,0 +1,68 @@
+import type { Command } from 'commander';
+
+import { DEFAULT_MOSAIC_HOME } from '../constants.js';
+import {
+  brainToolExists,
+  execBrainTool,
+  exitStatusFor,
+  resolveBrainTool,
+} from './brain-dispatch.js';
+
+export { exitStatusFor };
+
+/**
+ * `mosaic watch` — dispatch to the brain's agent-watch suite.
+ * See brain-dispatch.ts for the architecture and pass-through contract.
+ */
+export function resolveAgentWatchTool(mosaicHome: string): string {
+  return resolveBrainTool(mosaicHome, 'tools/agent-watch/agent-watch.sh');
+}
+
+export function registerWatchCommand(program: Command): void {
+  const cmd: Command = program
+    .command('watch')
+    .description('Wake-me-when watchers (agent-watch): start, list, stop')
+    // allowUnknownOption + variadic = full ordered pass-through: unknown
+    // options (--name, --when, ...) and their values land in args verbatim
+    // (commander 13 measured behavior), so the tool owns its own flag
+    // surface without the CLI needing passThroughOptions (which would
+    // force enablePositionalOptions fleet-wide on the root program).
+    .allowUnknownOption()
+    // The tool owns help too: without this, commander would intercept
+    // --help and answer with wrapper help instead of agent-watch's own
+    // (codex review of 18f3dd49).
+    .helpOption(false)
+    .argument('[args...]', 'args passed through to agent-watch.sh')
+    .action(async (args: string[], _opts: unknown, command: Command) => {
+      // --mosaic-home is not global in this CLI; walk parents for it and
+      // fall back to the default. MOSAIC_BRAIN_HOME (seat launchers export
+      // it) wins inside resolveBrainHome regardless.
+      let mosaicHome: string | undefined;
+      for (let anc: Command | null = command; anc; anc = anc.parent) {
+        const v = (anc.opts() as Record<string, string | undefined>)['mosaicHome'];
+        if (v !== undefined) {
+          mosaicHome = v;
+          break;
+        }
+      }
+      const home = mosaicHome ?? DEFAULT_MOSAIC_HOME;
+
+      const tool = resolveAgentWatchTool(home);
+      if (!brainToolExists(tool)) {
+        console.error(
+          `mosaic watch: agent-watch not found (expected ${tool}). ` +
+            'The watcher suite lives in the brain tree under tools/agent-watch/; ' +
+            'check MOSAIC_BRAIN_HOME or the brain checkout.',
+        );
+        process.exitCode = 127;
+        return;
+      }
+
+      process.exitCode = execBrainTool(home, 'tools/agent-watch/agent-watch.sh', args);
+    });
+
+  cmd.addHelpText(
+    'after',
+    '\nEverything after `mosaic watch` is passed through to agent-watch.sh verbatim (args, output, exit code).',
+  );
+}