@etiquekit/etq 1.0.11 → 1.0.13

package/packages/control/src/cli/commands/seat.ts

@@ -0,0 +1,179 @@
+import { resolve } from 'node:path';
+import { optionalString, parseInt32, parseList, requireString } from '../argv';
+import { buildAgentOwnerCard, type AgentOwnerCard } from '../../seat/owner-card';
+import {
+  CAPABILITY_SOURCES,
+  MODEL_TIERS,
+  OPERATIONAL_STATUSES,
+  SEAT_TYPES,
+  evaluateSeatReadiness,
+  heartbeatSeat,
+  readSeatReadiness,
+  reportSeatReadiness,
+  type CapabilitySource,
+  type ModelTier,
+  type OperationalStatus,
+  type SeatType,
+} from '../../seat/readiness';
+
+const SEAT_VERBS = new Set(['readiness', 'heartbeat', 'status', 'owner-card']);
+
+export function isSeatCommand(command: string): boolean {
+  return command === 'seat';
+}
+
+function parseEnum<T extends readonly string[]>(
+  values: T,
+  raw: string | boolean | undefined,
+  key: string,
+  fallback?: T[number],
+): T[number] {
+  if (raw === undefined && fallback !== undefined) return fallback;
+  if (typeof raw !== 'string' || !(values as readonly string[]).includes(raw)) {
+    throw new Error(`--${key} must be one of: ${values.join(', ')}`);
+  }
+  return raw as T[number];
+}
+
+function parseBool(raw: string | boolean | undefined, fallback: boolean): boolean {
+  if (raw === undefined) return fallback;
+  if (raw === true) return true;
+  if (raw === 'true' || raw === '1' || raw === 'yes') return true;
+  if (raw === 'false' || raw === '0' || raw === 'no') return false;
+  throw new Error('boolean flags must be true/false, 1/0, yes/no, or bare flag');
+}
+
+function parseOptionalInt(raw: string | boolean | undefined, key: string): number | undefined {
+  if (raw === undefined) return undefined;
+  return parseInt32(raw, key);
+}
+
+function renderStatus(status: ReturnType<typeof evaluateSeatReadiness>): string {
+  return [
+    `seat: ${status.seat}`,
+    `operational_status: ${status.operational_status}`,
+    `execution_surface: ${status.execution_surface}`,
+    `model_tier: ${status.model_tier}`,
+    `effective_model_tier: ${status.effective_model_tier}`,
+    `capability_source: ${status.capability_source}`,
+    `capability_trusted: ${String(status.capability_trusted)}`,
+    `active_workers: ${status.active_workers}`,
+    `max_recommended_workers: ${status.max_recommended_workers}`,
+    `supports_parallel: ${String(status.supports_parallel)}`,
+    `supported_strategies: ${status.supported_strategies.join(', ') || 'none'}`,
+    `unsupported_strategies: ${status.unsupported_strategies.join(', ') || 'none'}`,
+    `constraints: ${status.constraints.join(', ') || 'none'}`,
+    `last_heartbeat_at: ${status.last_heartbeat_at}`,
+    `stale_after: ${status.stale_after}`,
+    `is_stale: ${String(status.is_stale)}`,
+    `routing_recommendation: ${status.routing_recommendation}`,
+  ].join('\n');
+}
+
+function renderOwnerCard(card: AgentOwnerCard): string {
+  return [
+    'agent_owner_card:',
+    `  seat_id: ${card.seat_id}`,
+    `  job: ${card.job}`,
+    `  owner_principal: ${card.accountability.owner_principal}`,
+    `  maintainer: ${card.accountability.maintainer}`,
+    `  current_occupant: ${card.current_occupant?.model_id ?? card.current_occupant?.execution_surface ?? 'none'}`,
+    `  occupant_readiness_stale: ${String(card.current_occupant?.is_stale ?? true)}`,
+    `  review_stale: ${String(card.review.is_stale)}`,
+    `  last_reviewed_at: ${card.review.last_reviewed_at}`,
+    `  authority_source_ref: ${card.authority.source_ref}`,
+    `  allowed_work: ${card.authority.allowed_work.join(', ')}`,
+    `  forbidden_work: ${card.authority.forbidden_work.join(', ')}`,
+    `  failure_modes: ${card.failure_modes.map((mode) => mode.id).join(', ')}`,
+    `  warnings: ${card.warnings.join(', ') || 'none'}`,
+    `  read_model_only: ${String(card.authority_boundary.read_model_only)}`,
+  ].join('\n');
+}
+
+export async function dispatchSeat(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !SEAT_VERBS.has(verb)) {
+    throw new Error(`seat verb must be one of: ${[...SEAT_VERBS].join(', ')}`);
+  }
+
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+  const statePath = optionalString(flags, 'state');
+  const json = Boolean(flags.json);
+  const at = optionalString(flags, 'at');
+
+  if (verb === 'readiness') {
+    const record = await reportSeatReadiness({
+      projectRoot,
+      statePath,
+      seat: requireString(flags, 'seat'),
+      seatType: parseEnum(SEAT_TYPES, flags['seat-type'], 'seat-type', 'control_seat') as SeatType,
+      executionSurface: optionalString(flags, 'execution-surface') ?? 'generic',
+      declaredBy: parseEnum(['operator_principal', 'config'] as const, flags['declared-by'], 'declared-by', 'operator_principal'),
+      capabilitySource: parseEnum(CAPABILITY_SOURCES, flags['capability-source'], 'capability-source', 'config') as CapabilitySource,
+      operationalStatus: parseEnum(OPERATIONAL_STATUSES, flags['operational-status'], 'operational-status', 'operational') as OperationalStatus,
+      modelTier: parseEnum(MODEL_TIERS, flags['model-tier'], 'model-tier', 'local_unknown') as ModelTier,
+      modelId: optionalString(flags, 'model-id'),
+      activeWorkers: parseOptionalInt(flags['active-workers'], 'active-workers') ?? 0,
+      maxRecommendedWorkers: parseOptionalInt(flags['max-recommended-workers'], 'max-recommended-workers') ?? 1,
+      supportsParallel: parseBool(flags['supports-parallel'], false),
+      supportedStrategies: parseList(flags['supported-strategies']).length > 0
+        ? parseList(flags['supported-strategies'])
+        : ['solo'],
+      unsupportedStrategies: parseList(flags['unsupported-strategies']),
+      constraints: parseList(flags.constraints),
+      at,
+    });
+    console.log(json ? JSON.stringify(record, null, 2) : [
+      'seat_readiness:',
+      `  seat: ${record.seat}`,
+      `  operational_status: ${record.operational_status}`,
+      `  model_tier: ${record.model_tier}`,
+      `  capability_trusted: ${String(record.capability_trusted)}`,
+      `  stale_after: ${record.stale_after}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'heartbeat') {
+    const record = await heartbeatSeat({
+      projectRoot,
+      statePath,
+      seat: optionalString(flags, 'seat'),
+      operationalStatus: flags['operational-status'] === undefined
+        ? undefined
+        : parseEnum(OPERATIONAL_STATUSES, flags['operational-status'], 'operational-status') as OperationalStatus,
+      activeWorkers: parseOptionalInt(flags['active-workers'], 'active-workers'),
+      constraints: flags.constraints === undefined ? undefined : parseList(flags.constraints),
+      at,
+    });
+    console.log(json ? JSON.stringify(record, null, 2) : [
+      'seat_heartbeat:',
+      `  seat: ${record.seat}`,
+      `  operational_status: ${record.operational_status}`,
+      `  active_workers: ${record.active_workers}`,
+      `  last_heartbeat_at: ${record.last_heartbeat_at}`,
+      `  stale_after: ${record.stale_after}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'status') {
+    const record = await readSeatReadiness(projectRoot, statePath);
+    const status = evaluateSeatReadiness(record, at);
+    console.log(json ? JSON.stringify(status, null, 2) : renderStatus(status));
+    return;
+  }
+
+  if (verb === 'owner-card') {
+    const card = await buildAgentOwnerCard({
+      projectRoot,
+      statePath,
+      manifestPath: resolve(requireString(flags, 'manifest')),
+      at,
+    });
+    console.log(json ? JSON.stringify(card, null, 2) : renderOwnerCard(card));
+  }
+}

package/packages/control/src/cli/commands/session.ts

@@ -0,0 +1,127 @@
+import { resolve } from 'node:path';
+import { optionalString, requireString } from '../argv';
+import {
+  appendSessionRunbookNote,
+  createSessionRunbook,
+  migrateSessionProjectBindings,
+  SESSION_NOTE_SECTIONS,
+  type MigrateSessionProjectBindingsResult,
+  type SessionRunbookNoteResult,
+  type SessionRunbookResult,
+  type SessionNoteSection,
+} from '../../session/runbook';
+
+const SESSION_VERBS = new Set(['create', 'note', 'migrate-project']);
+
+export function isSessionCommand(command: string): boolean {
+  return command === 'session';
+}
+
+function parseCreationMode(raw: string | boolean | undefined): 'explicit' | 'dynamic' {
+  if (raw === undefined) return 'explicit';
+  if (raw === 'explicit' || raw === 'dynamic') return raw;
+  throw new Error('--creation-mode must be explicit or dynamic');
+}
+
+function parseSection(raw: string | boolean | undefined): SessionNoteSection {
+  const value = raw === undefined ? 'note' : raw;
+  if (typeof value === 'string' && (SESSION_NOTE_SECTIONS as readonly string[]).includes(value)) {
+    return value as SessionNoteSection;
+  }
+  throw new Error(`--section must be one of: ${SESSION_NOTE_SECTIONS.join(', ')}`);
+}
+
+function renderCreate(result: SessionRunbookResult): string {
+  return [
+    'session_runbook:',
+    `  session_id: ${result.manifest.session_id}`,
+    `  project_id: ${result.manifest.project_id}`,
+    `  task_ref: ${result.manifest.task_ref}`,
+    `  seat: ${result.manifest.seat}`,
+    `  creation_mode: ${result.manifest.creation_mode}`,
+    `  runbook_ref: ${result.manifest.runbook_ref}`,
+    `  manifest_ref: ${result.manifest.manifest_ref}`,
+    `  global_governance_ledger: ${result.manifest.ledger_boundary.global_governance_ledger}`,
+    `  can_authorize: ${String(result.manifest.authority_boundary.can_authorize)}`,
+    `  can_write_global_ledger: ${String(result.manifest.authority_boundary.can_write_global_ledger)}`,
+  ].join('\n');
+}
+
+function renderNote(result: SessionRunbookNoteResult): string {
+  return [
+    'session_runbook_note:',
+    `  session_id: ${result.manifest.session_id}`,
+    `  project_id: ${result.manifest.project_id}`,
+    `  section: ${result.section}`,
+    `  appended_at: ${result.appended_at}`,
+    `  note_count: ${result.manifest.note_count}`,
+    `  runbook_ref: ${result.manifest.runbook_ref}`,
+    `  can_authorize: ${String(result.manifest.authority_boundary.can_authorize)}`,
+    `  can_write_global_ledger: ${String(result.manifest.authority_boundary.can_write_global_ledger)}`,
+  ].join('\n');
+}
+
+function renderMigrate(result: MigrateSessionProjectBindingsResult): string {
+  return [
+    'session_project_binding_migration:',
+    `  project_id: ${result.project_id}`,
+    `  dry_run: ${String(result.dry_run)}`,
+    `  migrated: ${result.migrated.length}`,
+    `  unchanged: ${result.unchanged.length}`,
+    `  can_authorize: ${String(result.authority_boundary.can_authorize)}`,
+    result.migrated.length > 0 ? `  migrated_sessions: ${result.migrated.join(', ')}` : null,
+  ].filter((line): line is string => line !== null).join('\n');
+}
+
+export async function dispatchSession(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !SESSION_VERBS.has(verb)) {
+    throw new Error(`session verb must be one of: ${[...SESSION_VERBS].join(', ')}`);
+  }
+
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+  const json = Boolean(flags.json);
+  const at = optionalString(flags, 'at');
+
+  if (verb === 'create') {
+    const result = await createSessionRunbook({
+      projectRoot,
+      seat: requireString(flags, 'seat'),
+      taskRef: requireString(flags, 'task'),
+      sessionId: optionalString(flags, 'session-id'),
+      operatorPrincipal: optionalString(flags, 'operator'),
+      ownerPrincipal: optionalString(flags, 'owner'),
+      targetRef: optionalString(flags, 'target-ref'),
+      creationMode: parseCreationMode(flags['creation-mode']),
+      at,
+    });
+    console.log(json ? JSON.stringify(result.manifest, null, 2) : renderCreate(result));
+    return;
+  }
+
+  if (verb === 'migrate-project') {
+    const result = await migrateSessionProjectBindings({
+      projectRoot,
+      dryRun: Boolean(flags['dry-run']),
+      at,
+    });
+    console.log(json ? JSON.stringify(result, null, 2) : renderMigrate(result));
+    return;
+  }
+
+  const result = await appendSessionRunbookNote({
+    projectRoot,
+    sessionId: requireString(flags, 'session'),
+    section: parseSection(flags.section),
+    message: requireString(flags, 'message'),
+    at,
+  });
+  console.log(json ? JSON.stringify({
+    ...result.manifest,
+    appended_at: result.appended_at,
+    section: result.section,
+  }, null, 2) : renderNote(result));
+}

package/packages/control/src/cli/commands/supervision.ts

@@ -0,0 +1,246 @@
+import { resolve } from 'node:path';
+import {
+  ActionClassViolation,
+  closeSupervisionTurn,
+  issueSupervisionCommand,
+  loadSeatManifest,
+  openSupervisionSession,
+  openSupervisionTurn,
+  projectSupervisionSession,
+  readSupervisionSession,
+  rebuildSupervisionSession,
+  SeatManifestError,
+  SupervisionRuntimeError,
+} from '../../supervision/index';
+import { supervisionRuntimePaths } from '../../supervision/paths';
+import {
+  optionalString,
+  parseActionClass,
+  parseAllowedCommands,
+  parseInt32,
+  parseList,
+  parseProjectionPolicy,
+  parseSupervisionCommandName,
+  parseTurnResult,
+  requirePositional,
+  requireString,
+} from '../argv';
+import { makeSupervisionDeps, resolveProjectionDir } from '../supervision-deps';
+import { usage } from '../usage';
+
+/**
+ * Supervision CLI dispatcher. Extracted from the former monolithic `cli.ts`.
+ * Behavior is byte-preserving: same command names, same positional/flag
+ * shapes, same stdout/stderr, same exit codes (2/3/4/5 for rejections).
+ */
+export const SUPERVISION_COMMANDS_CLI: ReadonlySet<string> = new Set([
+  'session-open',
+  'session-status',
+  'turn-open',
+  'turn-close',
+  'session-command',
+  'session-project',
+  'session-rebuild',
+  'seat-validate',
+]);
+
+export async function dispatchSupervision(
+  command: string,
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  try {
+    switch (command) {
+      case 'seat-validate': {
+        const override = optionalString(flags, 'manifest');
+        const manifest = await loadSeatManifest(override);
+        if (flags.json === true) {
+          console.log(JSON.stringify(manifest, null, 2));
+        } else {
+          console.log(`seat ${manifest.seatId} (${manifest.runtimeKind}) — manifest OK`);
+          console.log(`  allowedActionClasses: ${manifest.allowedActionClasses.join(', ')}`);
+          console.log(`  canWriteProductRepo: ${manifest.canWriteProductRepo}`);
+          console.log(`  canRunBuilds: ${manifest.canRunBuilds}`);
+          console.log(`  canAcceptMobileSteering: ${manifest.canAcceptMobileSteering}`);
+        }
+        return;
+      }
+
+      case 'session-open': {
+        const sessionId = requirePositional(positionals, 1, 'session-id');
+        const campaignRoot = resolve(requireString(flags, 'campaign-root'));
+        const paths = supervisionRuntimePaths(campaignRoot);
+        const projectionDir = resolveProjectionDir(flags, campaignRoot, sessionId);
+        const deps = makeSupervisionDeps(projectionDir, paths.eventsPath);
+        const session = await openSupervisionSession(
+          {
+            sessionId,
+            campaignRoot,
+            topic: optionalString(flags, 'topic') ?? sessionId,
+            objective: requireString(flags, 'objective'),
+            leadSeat: requireString(flags, 'lead'),
+            responderSeat: requireString(flags, 'responder'),
+            escalationOwner: requireString(flags, 'escalation-owner'),
+            timeCapMinutes: parseInt32(flags['time-cap'], 'time-cap'),
+            turnCap: parseInt32(flags['turn-cap'], 'turn-cap'),
+            sourceRefs: parseList(flags['source-ref']),
+            seatManifestOverride: optionalString(flags, 'seat-manifest'),
+          },
+          deps,
+        );
+        console.log(`opened session ${session.sessionId} (status=${session.status})`);
+        return;
+      }
+
+      case 'session-status': {
+        const sessionId = requirePositional(positionals, 1, 'session-id');
+        const campaignRoot = resolve(requireString(flags, 'campaign-root'));
+        const paths = supervisionRuntimePaths(campaignRoot);
+        const projectionDir = resolveProjectionDir(flags, campaignRoot, sessionId);
+        const deps = makeSupervisionDeps(projectionDir, paths.eventsPath);
+        const projection = await readSupervisionSession(
+          { sessionId, campaignRoot },
+          deps,
+        );
+        if (flags.json === true) {
+          console.log(JSON.stringify(projection, null, 2));
+        } else {
+          const s = projection.sessionSnapshot;
+          console.log(`session ${s.sessionId} — ${s.status}`);
+          console.log(`  topic: ${s.topic}`);
+          console.log(`  lead/responder/escalation: ${s.leadSeat} / ${s.responderSeat} / ${s.escalationOwner}`);
+          console.log(`  current_turn: ${projection.currentTurn?.turnId ?? '(none)'}`);
+          console.log(`  pending_commands: ${projection.pendingCommands.length}`);
+        }
+        return;
+      }
+
+      case 'turn-open': {
+        const sessionId = requirePositional(positionals, 1, 'session-id');
+        const campaignRoot = resolve(requireString(flags, 'campaign-root'));
+        const paths = supervisionRuntimePaths(campaignRoot);
+        const projectionDir = resolveProjectionDir(flags, campaignRoot, sessionId);
+        const deps = makeSupervisionDeps(projectionDir, paths.eventsPath);
+        const turn = await openSupervisionTurn(
+          {
+            sessionId,
+            campaignRoot,
+            ownerSeat: requireString(flags, 'owner'),
+            allowedActionClass: parseActionClass(flags['action-class'], 'action-class'),
+            maxDurationMinutes: parseInt32(flags['max-duration'], 'max-duration'),
+            allowedCommands: parseAllowedCommands(flags['allowed-command'], 'allowed-command'),
+            repoRoots: parseList(flags['repo-root']),
+            ownedPaths: parseList(flags['owned-path']),
+            forbiddenPaths: parseList(flags['forbidden-path']),
+            verifyCommands: parseList(flags['verify-command']),
+            requiresHumanApproval: flags['requires-human-approval'] === true,
+            projectionPolicy: parseProjectionPolicy(flags['projection-policy']),
+            seatManifestOverride: optionalString(flags, 'seat-manifest'),
+          },
+          deps,
+        );
+        console.log(`opened turn ${turn.turnId} (seq=${turn.sequenceNo}, class=${turn.allowedActionClass})`);
+        return;
+      }
+
+      case 'turn-close': {
+        const sessionId = requirePositional(positionals, 1, 'session-id');
+        const campaignRoot = resolve(requireString(flags, 'campaign-root'));
+        const paths = supervisionRuntimePaths(campaignRoot);
+        const projectionDir = resolveProjectionDir(flags, campaignRoot, sessionId);
+        const deps = makeSupervisionDeps(projectionDir, paths.eventsPath);
+        const closed = await closeSupervisionTurn(
+          {
+            sessionId,
+            campaignRoot,
+            turnId: requireString(flags, 'turn'),
+            result: parseTurnResult(flags['result']),
+            summary: requireString(flags, 'summary'),
+            evidenceRefs: parseList(flags['evidence-ref']),
+          },
+          deps,
+        );
+        console.log(`closed turn ${closed.turnId} (result=${closed.result})`);
+        return;
+      }
+
+      case 'session-command': {
+        const sessionId = requirePositional(positionals, 1, 'session-id');
+        const commandName = parseSupervisionCommandName(positionals[2]);
+        const campaignRoot = resolve(requireString(flags, 'campaign-root'));
+        const paths = supervisionRuntimePaths(campaignRoot);
+        const projectionDir = resolveProjectionDir(flags, campaignRoot, sessionId);
+        const deps = makeSupervisionDeps(projectionDir, paths.eventsPath);
+        const record = await issueSupervisionCommand(
+          {
+            sessionId,
+            campaignRoot,
+            command: commandName,
+            actor: optionalString(flags, 'actor') ?? 'operator',
+            payloadJson: optionalString(flags, 'payload') ?? '{}',
+            seatManifestOverride: optionalString(flags, 'seat-manifest'),
+          },
+          deps,
+        );
+        if (record.status === 'rejected') {
+          console.error(`command ${commandName} rejected: ${record.rejectionReason}`);
+          process.exit(3);
+        }
+        console.log(`command ${commandName} applied (id=${record.commandId})`);
+        return;
+      }
+
+      case 'session-project': {
+        const sessionId = requirePositional(positionals, 1, 'session-id');
+        const campaignRoot = resolve(requireString(flags, 'campaign-root'));
+        const paths = supervisionRuntimePaths(campaignRoot);
+        const projectionDir = resolveProjectionDir(flags, campaignRoot, sessionId);
+        const deps = makeSupervisionDeps(projectionDir, paths.eventsPath);
+        const projection = await projectSupervisionSession(
+          { sessionId, campaignRoot },
+          deps,
+        );
+        console.log(`projected session ${projection.sessionId} at ${projection.renderedAt}`);
+        return;
+      }
+
+      case 'session-rebuild': {
+        const sessionId = requirePositional(positionals, 1, 'session-id');
+        const campaignRoot = resolve(requireString(flags, 'campaign-root'));
+        const paths = supervisionRuntimePaths(campaignRoot);
+        const projectionDir = resolveProjectionDir(flags, campaignRoot, sessionId);
+        const deps = makeSupervisionDeps(projectionDir, paths.eventsPath);
+        const projection = await rebuildSupervisionSession(
+          { sessionId, campaignRoot },
+          deps,
+        );
+        console.log(
+          `rebuilt session ${projection.sessionId} (current_status=${projection.sessionSnapshot.status})`,
+        );
+        return;
+      }
+
+      default: {
+        console.error(`unknown supervision command: ${command}`);
+        console.error(usage());
+        process.exit(1);
+      }
+    }
+  } catch (err) {
+    if (err instanceof SeatManifestError) {
+      console.error(`seat manifest invalid (${err.path}):`);
+      for (const issue of err.issues) console.error(`  - ${issue}`);
+      process.exit(2);
+    }
+    if (err instanceof ActionClassViolation) {
+      console.error(`action class violation (${err.actionClass}):`);
+      for (const issue of err.issues) console.error(`  - ${issue}`);
+      process.exit(4);
+    }
+    if (err instanceof SupervisionRuntimeError) {
+      console.error(`supervision error [${err.code}]: ${err.message}`);
+      process.exit(5);
+    }
+    throw err;
+  }
+}

package/packages/control/src/cli/commands/sync.ts

@@ -0,0 +1,119 @@
+import { resolve } from 'node:path';
+import { optionalString, requireString } from '../argv';
+import {
+  DEFAULT_EVENT_LOG_MERGE_DRIVER,
+  inspectEventLogMergeDriver,
+  installEventLogMergeDriver,
+  mergeAppendOnlyEventLogs,
+  type EventLogMergeDriverInstallResult,
+  type EventLogMergeDriverStatus,
+} from '../../sync/event-log-merge-driver';
+import { buildSyncJoinPlan, renderSyncJoinPlan } from '../../sync/join-plan';
+import { stageSyncOutbox, type SyncStageResult } from '../../sync/outbox';
+
+const SYNC_VERBS = new Set(['stage', 'join-plan', 'install-git-merge-driver', 'git-driver-status', 'event-log-merge-driver']);
+
+export function isSyncCommand(command: string): boolean {
+  return command === 'sync';
+}
+
+function renderStage(result: SyncStageResult): string {
+  return [
+    'sync_stage:',
+    `  staged: ${result.staged}`,
+    `  rejected: ${result.rejected.length}`,
+    `  local_only: ${result.local_only.length}`,
+    `  outbox_ref: ${result.outbox_ref}`,
+    `  boundary: local outbox only; no network, no execution, no authorization, no grant attachment`,
+    ...result.envelopes.map((envelope) => (
+      `  - ${envelope.kind} ${envelope.artifact_ref} -> ${envelope.outbox_ref} (${envelope.target_scope})`
+    )),
+    ...result.rejected.map((issue) => (
+      `  rejected: ${issue.kind} ${issue.artifact_ref} - ${issue.reason}`
+    )),
+  ].join('\n');
+}
+
+function renderInstallDriver(result: EventLogMergeDriverInstallResult): string {
+  return [
+    'event_log_merge_driver_install:',
+    `  driver_name: ${result.driver_name}`,
+    `  attributes_ref: ${result.attributes_ref}`,
+    `  attributes_rule: ${result.attributes_rule}`,
+    `  gitattributes_updated: ${String(result.gitattributes_updated)}`,
+    `  git_config_updated: ${String(result.git_config_updated)}`,
+    `  git_config_present: ${String(result.git_config_present)}`,
+    `  warnings: ${result.warnings.join(', ') || 'none'}`,
+    '  boundary: Git config only; no merge, push, grant, close, or ledger mutation',
+  ].join('\n');
+}
+
+function renderDriverStatus(result: EventLogMergeDriverStatus): string {
+  return [
+    'event_log_merge_driver_status:',
+    `  driver_name: ${result.driver_name}`,
+    `  attributes_configured: ${String(result.attributes_configured)}`,
+    `  git_config_present: ${String(result.git_config_present)}`,
+    `  git_config_configured: ${String(result.git_config_configured)}`,
+    `  ready: ${String(result.ready)}`,
+    `  warnings: ${result.warnings.join(', ') || 'none'}`,
+    '  boundary: read-only status; no merge, push, grant, close, or ledger mutation',
+  ].join('\n');
+}
+
+export async function dispatchSync(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !SYNC_VERBS.has(verb)) {
+    throw new Error(`sync verb must be one of: ${[...SYNC_VERBS].join(', ')}`);
+  }
+  if (verb === 'join-plan') {
+    const result = await buildSyncJoinPlan({
+      invitePath: resolve(requireString(flags, 'invite')),
+      joinedBy: requireString(flags, 'joined-by'),
+      claimRef: requireString(flags, 'claim-ref'),
+      at: optionalString(flags, 'at'),
+    });
+    console.log(flags.json ? JSON.stringify(result, null, 2) : renderSyncJoinPlan(result));
+    return;
+  }
+  if (verb === 'install-git-merge-driver') {
+    const result = await installEventLogMergeDriver({
+      projectRoot: resolve(optionalString(flags, 'project') ?? process.cwd()),
+      driverName: optionalString(flags, 'driver-name') ?? DEFAULT_EVENT_LOG_MERGE_DRIVER,
+      configureGit: flags['skip-git-config'] !== true,
+      driverCommand: optionalString(flags, 'driver-command'),
+    });
+    console.log(flags.json ? JSON.stringify(result, null, 2) : renderInstallDriver(result));
+    return;
+  }
+  if (verb === 'git-driver-status') {
+    const result = await inspectEventLogMergeDriver({
+      projectRoot: resolve(optionalString(flags, 'project') ?? process.cwd()),
+      driverName: optionalString(flags, 'driver-name') ?? DEFAULT_EVENT_LOG_MERGE_DRIVER,
+    });
+    console.log(flags.json ? JSON.stringify(result, null, 2) : renderDriverStatus(result));
+    return;
+  }
+  if (verb === 'event-log-merge-driver') {
+    const ancestorPath = positionals[2];
+    const currentPath = positionals[3];
+    const otherPath = positionals[4];
+    if (!ancestorPath || !currentPath || !otherPath) {
+      throw new Error('sync event-log-merge-driver requires <ancestor> <current> <other>');
+    }
+    mergeAppendOnlyEventLogs({ ancestorPath, currentPath, otherPath });
+    return;
+  }
+  const result = await stageSyncOutbox({
+    projectRoot: resolve(optionalString(flags, 'project') ?? process.cwd()),
+    outboxDir: optionalString(flags, 'outbox'),
+    workspaceId: optionalString(flags, 'workspace-id'),
+    orgId: optionalString(flags, 'org-id'),
+    seatId: optionalString(flags, 'seat-id'),
+    at: optionalString(flags, 'at'),
+  });
+  console.log(flags.json ? JSON.stringify(result, null, 2) : renderStage(result));
+}