@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/supervision/manifest.ts

@@ -0,0 +1,127 @@
+import { readFile } from 'node:fs/promises';
+import {
+  ACTION_CLASSES,
+  RUNTIME_KINDS,
+  type ActionClass,
+  type RuntimeKind,
+  type SeatCapabilityManifest,
+} from '../../../protocol/src/index';
+import { resolveSeatManifestPath } from './paths';
+
+export class SeatManifestError extends Error {
+  constructor(
+    message: string,
+    readonly path: string,
+    readonly issues: string[],
+  ) {
+    super(`${message}: ${issues.join('; ')}`);
+    this.name = 'SeatManifestError';
+  }
+}
+
+function isString(v: unknown): v is string {
+  return typeof v === 'string';
+}
+
+function isBoolean(v: unknown): v is boolean {
+  return typeof v === 'boolean';
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every(isString);
+}
+
+function isActionClass(v: unknown): v is ActionClass {
+  return isString(v) && (ACTION_CLASSES as readonly string[]).includes(v);
+}
+
+function isRuntimeKind(v: unknown): v is RuntimeKind {
+  return isString(v) && (RUNTIME_KINDS as readonly string[]).includes(v);
+}
+
+/**
+ * Validate a parsed seat manifest object against the schema.
+ * Returns the validated manifest or throws `SeatManifestError` with every issue.
+ */
+export function validateSeatManifest(raw: unknown, path: string): SeatCapabilityManifest {
+  const issues: string[] = [];
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new SeatManifestError('manifest root is not an object', path, [
+      `got ${Array.isArray(raw) ? 'array' : typeof raw}`,
+    ]);
+  }
+  const obj = raw as Record<string, unknown>;
+
+  const required: Array<[string, (v: unknown) => boolean, string]> = [
+    ['schemaVersion', (v) => v === 'discipline-supervision-seat-capabilities.v1', 'must equal "discipline-supervision-seat-capabilities.v1"'],
+    ['seatId', isString, 'must be a non-empty string'],
+    ['displayName', isString, 'must be a string'],
+    ['runtimeKind', isRuntimeKind, `must be one of: ${RUNTIME_KINDS.join(', ')}`],
+    ['canReadHandshake', isBoolean, 'must be a boolean'],
+    ['canWriteHandshake', isBoolean, 'must be a boolean'],
+    ['canReadProductRepo', isBoolean, 'must be a boolean'],
+    ['canRunBuilds', isBoolean, 'must be a boolean'],
+    ['canWriteProductRepo', isBoolean, 'must be a boolean'],
+    ['canLaunchRuntimeTargets', isBoolean, 'must be a boolean'],
+    ['canAcceptMobileSteering', isBoolean, 'must be a boolean'],
+    ['defaultRequiresHumanApprovalForProductMutation', isBoolean, 'must be a boolean'],
+    ['updatedAt', isString, 'must be an ISO-8601 string'],
+  ];
+
+  for (const [key, predicate, msg] of required) {
+    if (!(key in obj)) {
+      issues.push(`${key} missing`);
+      continue;
+    }
+    if (!predicate(obj[key])) {
+      issues.push(`${key} invalid (${msg})`);
+    }
+  }
+
+  if ('seatId' in obj && isString(obj.seatId) && obj.seatId.trim().length === 0) {
+    issues.push('seatId must not be empty');
+  }
+
+  if (!('allowedActionClasses' in obj)) {
+    issues.push('allowedActionClasses missing');
+  } else if (!Array.isArray(obj.allowedActionClasses)) {
+    issues.push('allowedActionClasses must be an array');
+  } else {
+    const bad = obj.allowedActionClasses.filter((v) => !isActionClass(v));
+    if (bad.length > 0) {
+      issues.push(`allowedActionClasses contains unknown values: ${bad.map(String).join(', ')}`);
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new SeatManifestError('seat manifest validation failed', path, issues);
+  }
+
+  return obj as unknown as SeatCapabilityManifest;
+}
+
+/**
+ * Read and validate a seat manifest from disk. The path defaults to the
+ * user-global location (~/.local/share/etiquette/seat-capabilities.json)
+ * unless overridden.
+ */
+export async function loadSeatManifest(override?: string): Promise<SeatCapabilityManifest> {
+  const path = resolveSeatManifestPath(override);
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf-8');
+  } catch (err) {
+    throw new SeatManifestError(
+      'seat manifest could not be read',
+      path,
+      [(err as NodeJS.ErrnoException).code ?? String(err)],
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new SeatManifestError('seat manifest is not valid JSON', path, [String(err)]);
+  }
+  return validateSeatManifest(parsed, path);
+}

package/packages/control/src/supervision/paths.ts

@@ -0,0 +1,49 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const SUPERVISION_RUNTIME_SUBDIR = '.etiquette/runtime/supervision';
+
+export interface SupervisionRuntimePaths {
+  campaignRoot: string;
+  runtimeDir: string;
+  sqlitePath: string;
+  eventsPath: string;
+  latestStatePath: string;
+  latestProjectionPath: string;
+}
+
+/**
+ * Resolve campaign-local supervision runtime paths. Per doctrine
+ * (llm-substrate/governance/shared-live-supervision.md), hot state lives at
+ * <campaign-root>/.etiquette/runtime/supervision/.
+ */
+export function supervisionRuntimePaths(campaignRoot: string): SupervisionRuntimePaths {
+  const root = resolve(campaignRoot);
+  const runtimeDir = join(root, SUPERVISION_RUNTIME_SUBDIR);
+  return {
+    campaignRoot: root,
+    runtimeDir,
+    sqlitePath: join(runtimeDir, 'supervision.sqlite'),
+    eventsPath: join(runtimeDir, 'events.jsonl'),
+    latestStatePath: join(runtimeDir, 'latest-state.json'),
+    latestProjectionPath: join(runtimeDir, 'latest-projection.json'),
+  };
+}
+
+export const DEFAULT_SEAT_MANIFEST_PATH = join(
+  homedir(),
+  '.local',
+  'share',
+  'etiquette',
+  'seat-capabilities.json',
+);
+
+/**
+ * Resolve the seat capability manifest path, honoring an optional override.
+ */
+export function resolveSeatManifestPath(override?: string): string {
+  if (override && override.trim().length > 0) {
+    return resolve(override);
+  }
+  return DEFAULT_SEAT_MANIFEST_PATH;
+}

package/packages/control/src/supervision/projection-adapter.ts

@@ -0,0 +1,274 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import type {
+  SupervisionCommandRecord,
+  SupervisionEvent,
+  SupervisionProjection,
+  SupervisionProjectionAdapter,
+  SupervisionTurn,
+} from '../../../protocol/src/index';
+import { readAllSupervisionEvents } from './events';
+
+/**
+ * File-system projection adapter for a campaign supervision session. This is
+ * intentionally in control so the public package does not need the legacy
+ * handshake adapter just to render local session projections.
+ */
+export interface SupervisionProjectionConfig {
+  projectionDir: string;
+  eventsPath: string;
+  seatsOfInterest?: string[];
+}
+
+export function createSupervisionProjectionAdapter(
+  config: SupervisionProjectionConfig,
+): SupervisionProjectionAdapter {
+  const projectionDir = resolve(config.projectionDir);
+  const eventsPath = resolve(config.eventsPath);
+
+  const statusBoardPath = join(projectionDir, 'STATUS_BOARD.md');
+  const channelPath = (seatId: string): string => {
+    const sanitized = seatId.replace(/[^A-Za-z0-9._@-]/g, '_');
+    return join(projectionDir, `${sanitized}.channel.md`);
+  };
+
+  return {
+    async renderStatusBoard(projection: SupervisionProjection): Promise<void> {
+      const md = renderStatusBoardMarkdown(projection);
+      await mkdir(projectionDir, { recursive: true });
+      await writeFile(statusBoardPath, md, 'utf-8');
+    },
+
+    async renderSeatChannel(projection: SupervisionProjection, seatId: string): Promise<void> {
+      const events = await readAllSupervisionEvents(eventsPath);
+      const md = renderSeatChannelMarkdown(projection, seatId, events);
+      await mkdir(projectionDir, { recursive: true });
+      await writeFile(channelPath(seatId), md, 'utf-8');
+    },
+
+    async writeLatestProjection(
+      projectionPath: string,
+      projection: SupervisionProjection,
+    ): Promise<void> {
+      const canonical = canonicalizeProjection(projection);
+      await mkdir(dirname(projectionPath), { recursive: true });
+      await writeFile(projectionPath, `${JSON.stringify(canonical, null, 2)}\n`, 'utf-8');
+    },
+  };
+}
+
+export function defaultSeatsFromProjection(projection: SupervisionProjection): string[] {
+  const s = projection.sessionSnapshot;
+  return [...new Set([s.leadSeat, s.responderSeat, s.escalationOwner])];
+}
+
+function renderStatusBoardMarkdown(projection: SupervisionProjection): string {
+  const s = projection.sessionSnapshot;
+  const lines: string[] = [];
+  lines.push('# Supervision Status Board');
+  lines.push('');
+  lines.push('> Generated by etiquette supervision sidecar.');
+  lines.push('> Source of truth: `events.jsonl` in the campaign runtime.');
+  lines.push('> If this file and supervision state disagree, regenerate; do not hand-edit.');
+  lines.push('');
+  lines.push('## Session');
+  lines.push('');
+  lines.push(`- **session_id:** \`${s.sessionId}\``);
+  lines.push(`- **topic:** ${s.topic}`);
+  lines.push(`- **objective:** ${s.objective}`);
+  lines.push(`- **status:** \`${s.status}\``);
+  lines.push(`- **lead_seat:** \`${s.leadSeat}\``);
+  lines.push(`- **responder_seat:** \`${s.responderSeat}\``);
+  lines.push(`- **escalation_owner:** \`${s.escalationOwner}\``);
+  lines.push(`- **time_cap_minutes:** ${s.timeCapMinutes}`);
+  lines.push(`- **turn_cap:** ${s.turnCap}`);
+  if (s.nextOwnerHint) {
+    lines.push(`- **next_owner_hint:** \`${s.nextOwnerHint}\``);
+  }
+  if (s.approvedNextTurnJson) {
+    lines.push('- **approved_next_turn:** present (see events.jsonl for payload)');
+  }
+  lines.push(`- **created_at:** ${s.createdAt}`);
+  lines.push(`- **updated_at:** ${s.updatedAt}`);
+  if (s.sourceRefs.length > 0) {
+    lines.push('- **source_refs:**');
+    for (const ref of [...s.sourceRefs].sort()) {
+      lines.push(`  - ${ref}`);
+    }
+  }
+  lines.push('');
+  lines.push('## Current turn');
+  lines.push('');
+  if (projection.currentTurn) {
+    renderTurn(lines, projection.currentTurn);
+  } else {
+    lines.push('_no open turn_');
+  }
+  lines.push('');
+  lines.push('## Pending commands');
+  lines.push('');
+  if (projection.pendingCommands.length === 0) {
+    lines.push('_none_');
+  } else {
+    for (const c of [...projection.pendingCommands].sort((a, b) => a.issuedAt.localeCompare(b.issuedAt))) {
+      renderCommand(lines, c);
+    }
+  }
+  if (s.lastBlockerJson) {
+    lines.push('');
+    lines.push('## Last blocker');
+    lines.push('');
+    lines.push('```json');
+    lines.push(formatJson(s.lastBlockerJson));
+    lines.push('```');
+  }
+  lines.push('');
+  lines.push('---');
+  lines.push(`Rendered at ${projection.renderedAt} by the supervision sidecar.`);
+  lines.push('Divergence rule: patch this file by regenerating, not by hand-edit.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function renderTurn(lines: string[], turn: SupervisionTurn): void {
+  lines.push(`- **turn_id:** \`${turn.turnId}\``);
+  lines.push(`- **sequence_no:** ${turn.sequenceNo}`);
+  lines.push(`- **status:** \`${turn.status}\``);
+  lines.push(`- **owner:** \`${turn.ownerSeat}\``);
+  lines.push(`- **action_class:** \`${turn.allowedActionClass}\``);
+  lines.push(`- **max_duration_minutes:** ${turn.maxDurationMinutes}`);
+  lines.push(`- **allowed_commands:** [${[...turn.allowedCommands].sort().join(', ')}]`);
+  if (turn.repoRoots.length > 0) {
+    lines.push(`- **repo_roots:** [${[...turn.repoRoots].sort().join(', ')}]`);
+  }
+  if (turn.ownedPaths.length > 0) {
+    lines.push(`- **owned_paths:** [${[...turn.ownedPaths].sort().join(', ')}]`);
+  }
+  if (turn.forbiddenPaths.length > 0) {
+    lines.push(`- **forbidden_paths:** [${[...turn.forbiddenPaths].sort().join(', ')}]`);
+  }
+  if (turn.verifyCommands.length > 0) {
+    lines.push(`- **verify_commands:** [${[...turn.verifyCommands].sort().join(', ')}]`);
+  }
+  lines.push(`- **requires_human_approval:** ${turn.requiresHumanApproval}`);
+  lines.push(`- **projection_policy:** \`${turn.projectionPolicy}\``);
+  lines.push(`- **started_at:** ${turn.startedAt}`);
+}
+
+function renderCommand(lines: string[], command: SupervisionCommandRecord): void {
+  lines.push(`- \`${command.command}\` by \`${command.issuedBy}\` at ${command.issuedAt}`);
+}
+
+function renderSeatChannelMarkdown(
+  projection: SupervisionProjection,
+  seatId: string,
+  events: SupervisionEvent[],
+): string {
+  const s = projection.sessionSnapshot;
+  const seatAudience = `seat:${seatId}` as const;
+  const roles: string[] = [];
+  if (s.leadSeat === seatId) roles.push('lead');
+  if (s.responderSeat === seatId) roles.push('responder');
+  if (s.escalationOwner === seatId) roles.push('escalation_owner');
+
+  const metaEventTypes = new Set(['projection.rendered', 'rebuild.completed']);
+  const filtered = events.filter((e) => {
+    if (metaEventTypes.has(e.eventType)) return false;
+    if (e.audience === 'all') return true;
+    if (e.audience === seatAudience) return true;
+    if (e.audience === 'lead' && roles.includes('lead')) return true;
+    if (e.audience === 'responder' && roles.includes('responder')) return true;
+    if (e.audience === 'escalation_owner' && roles.includes('escalation_owner')) return true;
+    return false;
+  });
+
+  const lines: string[] = [];
+  lines.push(`# ${seatId} - Supervision Channel`);
+  lines.push('');
+  lines.push(`- **session_id:** \`${s.sessionId}\``);
+  lines.push(`- **session_topic:** ${s.topic}`);
+  lines.push(`- **seat_roles_in_session:** ${roles.length > 0 ? roles.join(', ') : '_none_'}`);
+  lines.push(`- **generated_at:** ${projection.renderedAt}`);
+  lines.push('');
+  lines.push('> Auto-generated projection. Do not hand-edit.');
+  lines.push('> Authoritative source: `events.jsonl` filtered by seat audience.');
+  lines.push('> Regeneration overwrites this file on every state change.');
+  lines.push('');
+  lines.push(`## Event log (${filtered.length} entries)`);
+  lines.push('');
+  if (filtered.length === 0) {
+    lines.push('_no events addressed to this seat yet_');
+  } else {
+    for (const e of filtered) {
+      lines.push(`- \`${e.at}\` — \`${e.eventType}\` — ${formatEventSummary(e)}`);
+    }
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function formatEventSummary(event: SupervisionEvent): string {
+  switch (event.eventType) {
+    case 'session.opened':
+      return `session opened by ${event.actor}`;
+    case 'session.status_changed': {
+      const p = (event.payload as { from?: string; to?: string }) ?? {};
+      return `status ${p.from ?? '?'} -> ${p.to ?? '?'}`;
+    }
+    case 'session.next_owner_changed': {
+      const p = (event.payload as { from?: string | null; to?: string | null }) ?? {};
+      return `next_owner_hint ${p.from ?? 'null'} -> ${p.to ?? 'null'}`;
+    }
+    case 'turn.opened': {
+      const p = (event.payload as { ownerSeat?: string; allowedActionClass?: string }) ?? {};
+      return `turn opened for ${p.ownerSeat ?? '?'} (${p.allowedActionClass ?? '?'})`;
+    }
+    case 'turn.closed': {
+      const p = (event.payload as { result?: string; summary?: string }) ?? {};
+      return `turn closed (${p.result ?? '?'}): ${p.summary ?? ''}`;
+    }
+    case 'command.queued': {
+      const p = (event.payload as { command?: string; issuedBy?: string }) ?? {};
+      return `${p.command ?? '?'} queued by ${p.issuedBy ?? '?'}`;
+    }
+    case 'command.applied': {
+      const p = (event.payload as { command?: string }) ?? {};
+      return `${p.command ?? '?'} applied`;
+    }
+    case 'command.rejected': {
+      const p = (event.payload as { command?: string; reason?: string }) ?? {};
+      return `${p.command ?? '?'} rejected: ${p.reason ?? ''}`;
+    }
+    case 'projection.rendered':
+      return 'projection rendered';
+    case 'rebuild.completed': {
+      const p = (event.payload as { eventCount?: number }) ?? {};
+      return `rebuild completed (${p.eventCount ?? '?'} events replayed)`;
+    }
+    default:
+      return `(event type ${String(event.eventType)})`;
+  }
+}
+
+function formatJson(raw: string): string {
+  try {
+    return JSON.stringify(JSON.parse(raw), null, 2);
+  } catch {
+    return raw;
+  }
+}
+
+function canonicalizeProjection(projection: SupervisionProjection): SupervisionProjection {
+  const sortedSourceRefs = [...projection.sessionSnapshot.sourceRefs].sort();
+  const sortedPendingCommands = [...projection.pendingCommands].sort((a, b) =>
+    a.issuedAt.localeCompare(b.issuedAt) || a.commandId.localeCompare(b.commandId),
+  );
+  return {
+    ...projection,
+    sessionSnapshot: {
+      ...projection.sessionSnapshot,
+      sourceRefs: sortedSourceRefs,
+    },
+    pendingCommands: sortedPendingCommands,
+  };
+}

package/packages/control/src/supervision/projection.ts

@@ -0,0 +1,75 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type {
+  SupervisionCommandRecord,
+  SupervisionDeps,
+  SupervisionProjection,
+  SupervisionSession,
+  SupervisionTurn,
+} from '../../../protocol/src/index';
+import type { supervisionRuntimePaths } from './paths';
+
+/**
+ * Projection coordination — internal helpers shared by every runtime writer.
+ *
+ * These were previously inline in `session.ts`. Extracted per the Phase D.7
+ * surgical split so the public-entrypoint modules (session-open, turn-open,
+ * turn-close, command-apply, rebuild, session-read) can import a single
+ * shared implementation instead of duplicating coordination logic.
+ *
+ * No public export surface — callers remain the runtime modules within this
+ * directory. Not re-exported from `supervision/index.ts`.
+ */
+
+/**
+ * Write `{ session, currentTurn }` to disk as pretty-printed JSON.
+ *
+ * Used after every state-mutating runtime operation so the latest-state.json
+ * artifact stays in sync with SQLite.
+ */
+export async function writeLatestState(
+  path: string,
+  session: SupervisionSession,
+  currentTurn: SupervisionTurn | null,
+): Promise<void> {
+  const body = JSON.stringify({ session, currentTurn }, null, 2);
+  await mkdir(join(path, '..'), { recursive: true });
+  await writeFile(path, `${body}\n`, 'utf-8');
+}
+
+/**
+ * Build a `SupervisionProjection` snapshot and drive the configured
+ * projection adapter through its three render hooks:
+ *   - `writeLatestProjection` (machine-readable snapshot)
+ *   - `renderStatusBoard` (single STATUS_BOARD.md for the campaign)
+ *   - `renderSeatChannel` for each of lead / responder / escalation_owner
+ *     (de-duplicated; a seat can play multiple roles in the same session)
+ *
+ * Per PHASE1.md § Projection rules, this runs on every state change and is
+ * idempotent — safe to rerun after partial failure.
+ */
+export async function renderProjection(
+  deps: SupervisionDeps,
+  paths: ReturnType<typeof supervisionRuntimePaths>,
+  session: SupervisionSession,
+  currentTurn: SupervisionTurn | null,
+  pendingCommands: SupervisionCommandRecord[],
+): Promise<SupervisionProjection> {
+  const projection: SupervisionProjection = {
+    sessionId: session.sessionId,
+    renderedAt: deps.now().toISOString(),
+    sessionSnapshot: session,
+    currentTurn,
+    pendingCommands,
+  };
+
+  await deps.projectionAdapter.writeLatestProjection(paths.latestProjectionPath, projection);
+  await deps.projectionAdapter.renderStatusBoard(projection);
+
+  const seats = new Set([session.leadSeat, session.responderSeat, session.escalationOwner]);
+  for (const seatId of seats) {
+    await deps.projectionAdapter.renderSeatChannel(projection, seatId);
+  }
+
+  return projection;
+}

package/packages/control/src/supervision/rebuild.ts

@@ -0,0 +1,99 @@
+import { existsSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import type {
+  SupervisionDeps,
+  SupervisionProjection,
+} from '../../../protocol/src/index';
+import {
+  appendSupervisionEvent,
+  buildEvent,
+  readAllSupervisionEvents,
+} from './events';
+import { replayEvent } from './event-replay';
+import { supervisionRuntimePaths } from './paths';
+import { renderProjection, writeLatestState } from './projection';
+import { applySupervisionSchema } from './sqlite';
+import { withSupervisionTransaction } from './sqlite-impl';
+import {
+  insertEventRow,
+  loadCurrentTurn,
+  loadPendingCommands,
+  loadSession,
+} from './store-rows';
+
+export interface SessionRebuildArgs {
+  sessionId: string;
+  campaignRoot: string;
+}
+
+/**
+ * Drop the SQLite mirror (including WAL + SHM siblings), then replay
+ * `events.jsonl` into a fresh schema. All replays for the session run
+ * inside a single transaction so a partial rebuild cannot leave a
+ * half-populated mirror visible to concurrent readers.
+ *
+ * Final step: append a `rebuild.completed` event so history remains
+ * self-describing.
+ *
+ * Per PHASE1.md § Session-rebuild contract: after this call, SQLite state
+ * MUST equal the pre-rebuild state for any durable session.
+ */
+export async function rebuildSupervisionSession(
+  args: SessionRebuildArgs,
+  deps: SupervisionDeps,
+): Promise<SupervisionProjection> {
+  const paths = supervisionRuntimePaths(args.campaignRoot);
+
+  if (existsSync(paths.sqlitePath)) {
+    await rm(paths.sqlitePath, { force: true });
+  }
+  // Remove WAL + SHM siblings too.
+  await rm(`${paths.sqlitePath}-wal`, { force: true });
+  await rm(`${paths.sqlitePath}-shm`, { force: true });
+
+  const events = await readAllSupervisionEvents(paths.eventsPath);
+  const db = deps.openSqlite(paths.sqlitePath);
+  try {
+    applySupervisionSchema(db);
+
+    // Replay is idempotent per event but inserts many rows; group the whole
+    // replay as one atomic bundle so a partial rebuild cannot leave a
+    // half-populated SQLite mirror visible to concurrent readers.
+    const eventCount = withSupervisionTransaction(db, () => {
+      let count = 0;
+      for (const event of events) {
+        if (event.sessionId !== args.sessionId) continue;
+        replayEvent(db, event);
+        count += 1;
+      }
+      return count;
+    });
+
+    const session = loadSession(db, args.sessionId);
+    const currentTurn = loadCurrentTurn(db, session);
+    const pending = loadPendingCommands(db, args.sessionId);
+
+    await writeLatestState(paths.latestStatePath, session, currentTurn);
+    const projection = await renderProjection(deps, paths, session, currentTurn, pending);
+
+    const completedAt = deps.now().toISOString();
+    const completed = buildEvent(deps, {
+      eventType: 'rebuild.completed',
+      sessionId: args.sessionId,
+      turnId: session.currentTurnId,
+      commandId: null,
+      actor: 'system',
+      audience: 'all',
+      at: completedAt,
+      payload: { completedAt, eventCount },
+    });
+    await appendSupervisionEvent(paths.eventsPath, completed);
+    withSupervisionTransaction(db, () => {
+      insertEventRow(db, completed);
+    });
+
+    return projection;
+  } finally {
+    db.close();
+  }
+}