@defrex/autobuild 0.8.0

package/packages/core/src/cli/main.ts

@@ -0,0 +1,1399 @@
+/**
+ * `ab` — the only channel between agents and the store, and the enforcement
+ * point of the entire ontology (SPEC §8). This module is pure routing: every
+ * dependency is injected via CliDeps, so the whole surface is testable over
+ * fakes; wiring real deps (resolved env, resolved store, real forge, real
+ * exec, random ids) is `src/cli/binary.ts`'s job.
+ *
+ * Errors go to stderr with exit code 1, formatted as agent feedback (D6):
+ * what was wrong and what would be accepted, so the in-session correction
+ * loop is immediate and cheap.
+ */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { TicketRef } from '../ontology'
+import type { Clock } from '../store/types'
+import type { BuildStore } from '../store/types'
+import { textContent } from '../store/types'
+import type { Forge } from '../ports/types'
+import type { Exec } from '../ports/workspace/git-worktree'
+import type { IdSource } from '../ids'
+import { reduceBuild } from '../kernel/reducer'
+import { artifactDownload, artifactGet, artifactPut } from './artifact'
+import { multiFlag, parseArgs, stringFlag, type ParsedArgs } from './args'
+import { abBuildControl, type BuildControlAction, type BuildControlResult } from './build-control'
+import {
+  abBulkControl,
+  bulkControlLines,
+  bulkFailureLines,
+  BulkWalkError,
+  type BulkDirection,
+} from './bulk-control'
+import { buildContext, type ContextManifest } from './context'
+import { abDispatch } from './dispatch'
+import type { DashboardRendererResolver } from './dashboard/render'
+import type { TerminalInput, TerminalOut } from './terminal'
+import type { CliEnv, HarvestCliEnv } from './env'
+import { abInit } from './init'
+import { validateInitReadiness } from './init-validation'
+import { loadDotEnv } from './dotenv'
+import type { RuntimeRegistry } from '../ports/runner/runtime'
+import type { SetupAgentLauncher } from './init-agent'
+import { abModels } from './models'
+import { recognizeHelpRequest, renderCommandHelp, renderTopLevelHelp } from './help'
+import { observe } from './observe'
+import { abPlugin, type PluginContractSubprocess } from './plugin'
+import { preparePrAttachments } from './pr-attachments'
+import { renderPrSummary } from './pr-summary'
+import { abBuilds, abBuildStatus } from './status'
+import { abRepositoryStatus } from './repository-status'
+import { abWatch, WATCH_USAGE } from './watch'
+import { abWait, WAIT_USAGE } from './wait'
+import { abMcp, AB_MCP_USAGE } from './mcp'
+import type { StoreOpener } from './store-opening'
+import { done, escalate, verdict } from './terminals'
+import { abTicket, openTicketSource } from './ticket'
+import { abUpgrade, type ResolveConflict } from './upgrade'
+import { withUpgradeProgress } from './upgrade-progress'
+import {
+  cleanupUpgradeCommitContext,
+  createUpgradeCommitContext,
+  finishUpgradeCommit,
+  loadUpgradeCommitContext,
+  UPGRADE_COMMIT_CONTEXT_ENV,
+  type UpgradeCommitContext,
+} from './upgrade-commit'
+import { formatInstalledVersion, readDistributionIdentity } from './installation'
+import {
+  selfUpdate,
+  SELF_UPDATE_HANDOFF_ENV,
+  type SelfUpdateCommand,
+  type SelfUpdateOptions,
+  type SelfUpdateResult,
+} from './self-update'
+import {
+  abHarvestStatus,
+  buildHarvestContext,
+  submitHarvestProposals,
+  submitHarvestVerdict,
+  type HarvestCliDeps,
+} from './harvest'
+
+/**
+ * Commands that run OUTSIDE phase sessions (§16.3, §8.8, §3.3). Repository
+ * commands resolve the cwd; durable controls additionally take a target build
+ * slug. None requires the ambient AB_* phase tuple.
+ *
+ * `src/cli/binary.ts` routes through `isSessionlessInvocation` below. This set
+ * owns flat command names; that helper additionally owns the few mixed nested
+ * namespaces (`artifact download`, `harvest status`). The `builds`, `build
+ * status`, and `artifact download` shells remain on this operator-sessionless
+ * route but use their dedicated Store opener to honor a complete ambient phase
+ * identity and reject malformed identity. Everything else first attempts
+ * strict ambient resolution in `binary.ts`. Keeping classification beside the
+ * switch makes it unit-testable.
+ */
+export const SESSIONLESS_COMMANDS = new Set([
+  'init',
+  'upgrade',
+  'update',
+  'ticket',
+  'dispatch',
+  'builds',
+  'build',
+  'watch',
+  'wait',
+  'mcp',
+  'repository',
+  'pause',
+  'resume',
+  'auto-merge',
+  'answer',
+  'abort',
+  'models',
+  'plugin',
+  'help',
+  '--help',
+  '-h',
+  '--version',
+])
+
+/** Nested namespaces can mix operator and phase forms. `artifact download`
+ * uses operator-sessionless routing plus ambient-aware read authority; put/get
+ * remain phase-only. */
+export function isSessionlessInvocation(argv: readonly string[]): boolean {
+  const command = argv[0]
+  return (
+    command === undefined ||
+    recognizeHelpRequest(argv) !== undefined ||
+    SESSIONLESS_COMMANDS.has(command) ||
+    (command === 'artifact' && argv[1] === 'download') ||
+    (command === 'harvest' && argv[1] === 'status')
+  )
+}
+
+export interface CliDeps {
+  store: BuildStore
+  /** Resolved ambient auth (D8) — see resolveCliEnv (src/cli/env.ts). */
+  env: CliEnv
+  workspacePath: string
+  forge: Forge
+  exec: Exec
+  ids: IdSource
+  clock: Clock
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+}
+
+/**
+ * What `runCli` minimally needs. `ab init` and `ab upgrade` run OUTSIDE
+ * build sessions (§16.3) — they take a repo path, not a build, and must
+ * work with no AB_* environment — so the session surface is optional here.
+ * The binary also uses this narrow shape when ambient phase context is absent,
+ * allowing requireSession/requireHarvestSession to return namespace-aware
+ * guidance without constructing a store. Full CliDeps satisfies this
+ * structurally, so wired-up callers are unchanged.
+ */
+export interface SessionlessCliDeps {
+  /** For init/upgrade this is just the cwd — the default target repo. */
+  workspacePath: string
+  stdout: (line: string) => void
+  stderr: (line: string) => void
+  /** Raw process environment for sessionless store selection, operator
+   * provenance/self-control checks, and adapter secrets; distinct from `env`,
+   * the resolved phase-session tuple. */
+  processEnv?: Record<string, string | undefined>
+  /** Stop signal for long-running sessionless commands (`ab dispatch`'s watch
+   * loop); the binary aborts it on SIGINT. */
+  signal?: AbortSignal
+  /** Interactive output seam for live dispatch and upgrade rendering. Absent ⇒
+   * non-interactive ⇒ plain, line-oriented output. */
+  terminal?: TerminalOut
+  /** Raw keyboard seam for interactive dispatch and upgrade controls. */
+  input?: TerminalInput
+  /** True only when both stdin and stdout are interactive terminals. */
+  initInteractive?: boolean
+  /** Injectable direct interactive child-process seam for init tests. */
+  initLauncher?: SetupAgentLauncher
+  /** Injectable init detection registry; production uses shipped registrations. */
+  initRuntimes?: RuntimeRegistry
+  /** Complete readiness seam for CLI routing tests. */
+  initValidation?: typeof validateInitReadiness
+  /** Optional per-paint presentation lookup used only by the repo-local dev
+   * entry. The published binary never supplies it. */
+  resolveDashboardRenderer?: DashboardRendererResolver
+  /** Distribution root overrides are test-only; production resolves relative
+   * to the running module, independent of the current repository. */
+  distributionRoot?: string
+  /** Self-update seams keep release/package-manager orchestration testable. */
+  selfUpdateCommand?: SelfUpdateCommand
+  selfUpdate?: (options: SelfUpdateOptions) => Promise<SelfUpdateResult>
+  /** Production supplies the tool-free upgrade agent; tests inject a fake.
+   * Construction is deferred until a skill actually conflicts. */
+  upgradeResolverFactory?: (opts: {
+    targetRepo: string
+    env: Record<string, string | undefined>
+  }) => ResolveConflict
+  /** Injectable child-process seam for plugin contract CLI tests. */
+  pluginSubprocess?: PluginContractSubprocess
+  /** Injectable store-adapter seam for operator-sessionless commands, including
+   * ambient-authority-aware reads; production composes the real adapter. */
+  openStore?: StoreOpener
+  store?: BuildStore
+  env?: CliEnv
+  harvestEnv?: HarvestCliEnv
+  forge?: Forge
+  exec?: Exec
+  ids?: IdSource
+  clock?: Clock
+}
+
+/** Narrow to full session deps, or fail with agent feedback (D6). */
+function requireHarvestSession(command: string, deps: SessionlessCliDeps): HarvestCliDeps {
+  const { store, harvestEnv: env, ids } = deps
+  if (store === undefined || env === undefined || ids === undefined) {
+    throw new Error(
+      `'ab harvest ${command}' runs inside a harvest agent session — the ` +
+        'runner sets AB_STORE, AB_REPO, AB_HARVEST, AB_PHASE, and AB_SESSION.',
+    )
+  }
+  return { store, env, ids, workspacePath: deps.workspacePath }
+}
+
+function requireSession(command: string, deps: SessionlessCliDeps): CliDeps {
+  const { store, env, forge, exec, ids, clock } = deps
+  if (
+    store === undefined ||
+    env === undefined ||
+    forge === undefined ||
+    exec === undefined ||
+    ids === undefined ||
+    clock === undefined
+  ) {
+    throw new Error(
+      `'ab ${command}' runs inside a build session — the runner sets AB_STORE, ` +
+        'AB_BUILD, AB_PHASE, AB_SESSION for every session (SPEC §8.1, D8). ' +
+        'Use `ab help` for commands that run sessionless.',
+    )
+  }
+  return { ...deps, store, env, forge, exec, ids, clock }
+}
+
+export function buildControlConfirmation(result: BuildControlResult): string {
+  switch (result.kind) {
+    case 'command': {
+      const outcome: Record<typeof result.command, string> = {
+        pause: 'pause requested',
+        resume: 'resume requested',
+        abort: 'abort requested',
+        discard: 'discard requested',
+        'auto-merge-on': 'auto-merge requested',
+        'auto-merge-off': 'auto-merge cancelled',
+      }
+      return `build ${result.slug}: ${outcome[result.command]}`
+    }
+    case 'answered': {
+      const plural = result.count === 1 ? '' : 's'
+      const terminal = result.terminalSignal
+      if (terminal !== undefined) {
+        const ending =
+          terminal.kind === 'terminal-status'
+            ? `the build ${terminal.status === 'done' ? 'completed' : 'aborted'} while the answer was recorded${
+                terminal.outcome !== undefined ? ` (${terminal.outcome})` : ''
+              }; it will not restart`
+            : terminal.kind === 'abort-requested'
+              ? 'abort was requested during the action; the build will be aborted and will not restart'
+              : `the PR ${terminal.state}; build completion is underway and it will not restart`
+        return `build ${result.slug}: answered ${result.count} escalation${plural} with ${result.resolution}; ${ending}`
+      }
+      if (result.reviewRoundCeiling !== undefined) {
+        const ceiling = result.reviewRoundCeiling
+        return `build ${result.slug}: answered ${result.count} open escalation${plural} with ${result.resolution}; ${ceiling.loop} review round ceiling set to ${ceiling.value}${
+          result.resumed ? '; resume requested' : ''
+        }`
+      }
+      if (result.resolution === 'revise-spec') {
+        const revision = result.specRev === undefined ? '' : ` (spec rev ${result.specRev})`
+        if (result.authorizedEarlier === true) {
+          return `build ${result.slug}: completed the spec revision recorded earlier${revision}; the body supplied now was not used${
+            result.resumed ? '; resume requested' : ''
+          }`
+        }
+        return `build ${result.slug}: answered ${result.count} escalation${plural} with revise-spec${revision}; restarting from plan${
+          result.resumed ? '; resume requested' : ''
+        }`
+      }
+      if (result.resolution === 'dismiss-finding' && (result.remainingOpen ?? 0) > 0) {
+        const remaining = result.remainingOpen ?? 0
+        return `build ${result.slug}: dismissed ${result.count} escalation${plural}; ${remaining} blocker${
+          remaining === 1 ? '' : 's'
+        } remains (cites no review findings) — answer with guidance or an empty answer to retry`
+      }
+      return `build ${result.slug}: answered ${result.count} open escalation${plural} with ${result.resolution}${
+        result.resumed ? '; resume requested' : ''
+      }`
+    }
+    case 'answer-required':
+      throw new Error('build-control requested interactive feedback for an explicit CLI command')
+  }
+}
+
+async function runBuildControl(
+  deps: SessionlessCliDeps,
+  slug: string,
+  action: BuildControlAction,
+  storeRef?: string,
+  readTicketBody?: (ref: TicketRef) => Promise<string>,
+): Promise<void> {
+  if (deps.exec === undefined) {
+    throw new Error(
+      'build-control commands need an exec seam — this is a wiring bug in the ab binary',
+    )
+  }
+  const result = await abBuildControl({
+    targetRepo: deps.workspacePath,
+    env: deps.processEnv ?? {},
+    exec: deps.exec,
+    slug,
+    action,
+    ...(storeRef !== undefined ? { storeRef } : {}),
+    ...(readTicketBody !== undefined ? { readTicketBody } : {}),
+    ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+  })
+  deps.stdout(buildControlConfirmation(result))
+}
+
+/**
+ * The repository-wide form. Success renders the walk's summary; a partial walk
+ * is the one failure this route owns rather than delegates — it reports what
+ * did complete on stderr and exits 1, and nothing reaches stdout. Every other
+ * error propagates to `runCli`'s stderr+1 handler.
+ */
+async function runBulkControl(
+  deps: SessionlessCliDeps,
+  direction: BulkDirection,
+  opts: { json: boolean; storeRef?: string },
+): Promise<number> {
+  if (deps.exec === undefined) {
+    throw new Error(
+      'build-control commands need an exec seam — this is a wiring bug in the ab binary',
+    )
+  }
+  try {
+    const summary = await abBulkControl({
+      targetRepo: deps.workspacePath,
+      env: deps.processEnv ?? {},
+      exec: deps.exec,
+      direction,
+      ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
+      ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+    })
+    if (opts.json) deps.stdout(JSON.stringify(summary, null, 2))
+    else for (const line of bulkControlLines(summary)) deps.stdout(line)
+    return 0
+  } catch (error) {
+    if (!(error instanceof BulkWalkError)) throw error
+    if (opts.json) deps.stderr(JSON.stringify({ ...error.progress, error: error.message }, null, 2))
+    else for (const line of bulkFailureLines(error)) deps.stderr(line)
+    return 1
+  }
+}
+
+function listFlag(parsed: ParsedArgs, name: string): string[] | undefined {
+  const value = stringFlag(parsed, name)
+  if (value === undefined) return undefined
+  return value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== '')
+}
+
+function renderManifest(manifest: ContextManifest): string[] {
+  const lines = [
+    `context materialized for ${manifest.build} — ${manifest.phase}@${manifest.round}`,
+    `required deposits: ${manifest.required.join(', ') || '(none)'}`,
+    `allowed terminals: ${manifest.allowedTerminals.join(', ')}`,
+    `manifest: ${manifest.manifestPath}`,
+  ]
+  if (manifest.notesPath !== undefined) lines.push(`notes path: ${manifest.notesPath}`)
+  if (manifest.commitRange !== undefined) {
+    lines.push(`commit range: ${manifest.commitRange.base}..${manifest.commitRange.head}`)
+  }
+  if (manifest.conflict !== undefined) {
+    lines.push(`conflict baseSha: ${manifest.conflict.baseSha}`)
+  }
+  if (manifest.step !== undefined) {
+    lines.push(`verify step: ${manifest.step.name} (kind ${manifest.step.config.kind})`)
+  }
+  lines.push('.ab/ files:')
+  const entries = Object.entries(manifest.materialized)
+  if (entries.length === 0) {
+    lines.push('  (none)')
+  }
+  for (const [relPath, source] of entries) {
+    lines.push(
+      `  ${relPath} — ${source === 'derived' ? 'derived' : `${source.kind}@${source.rev}`}`,
+    )
+  }
+  return lines
+}
+
+export async function runCli(argv: string[], deps: SessionlessCliDeps): Promise<number> {
+  try {
+    return await dispatch(argv, deps)
+  } catch (error) {
+    deps.stderr(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}
+
+async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<number> {
+  const [command, ...rest] = argv
+  const { stdout, stderr } = deps
+  const helpRequest = recognizeHelpRequest(argv)
+
+  // Help is resolved before every command handler. This keeps both detailed
+  // forms byte-identical and prevents config, store, plugin, or session wiring
+  // from becoming a prerequisite for documentation.
+  if (helpRequest?.kind === 'overview') {
+    stdout(renderTopLevelHelp())
+    return 0
+  }
+  if (helpRequest?.kind === 'command') {
+    stdout(renderCommandHelp(helpRequest.command))
+    return 0
+  }
+
+  switch (command) {
+    case undefined: {
+      stderr(renderTopLevelHelp())
+      return 1
+    }
+
+    case 'help':
+    case '--help':
+    case '-h': {
+      throw new Error('usage: ab help [command]\n       ab <command> --help')
+    }
+
+    case '--version': {
+      if (rest.length > 0) throw new Error('usage: ab --version')
+      stdout(formatInstalledVersion(await readDistributionIdentity(deps.distributionRoot)))
+      return 0
+    }
+
+    // init and upgrade run OUTSIDE build sessions (§16.3): they operate on a
+    // repo, not a build, so they route before any store/env requirement.
+    case 'init': {
+      const usage = 'usage: ab init [target] [--force | --validate] (§16.3)'
+      const removed = [
+        '--forge',
+        '--ticket-source',
+        '--workspace-provider',
+        '--role-profile',
+        '--no-interactive',
+      ].find((flag) => rest.some((arg) => arg === flag || arg.startsWith(`${flag}=`)))
+      if (removed !== undefined) {
+        throw new Error(
+          `${removed} was removed — ab init now installs a neutral skeleton and hands setup to a coding agent. ${usage}`,
+        )
+      }
+      const parsed = parseArgs(rest, { force: 'boolean', validate: 'boolean' }, usage)
+      if (parsed.positionals.length > 1) throw new Error(usage)
+      if (parsed.flags.has('force') && parsed.flags.has('validate')) {
+        throw new Error(`--force and --validate cannot be combined — ${usage}`)
+      }
+      const targetRepo = parsed.positionals[0] ?? deps.workspacePath
+      if (parsed.flags.has('validate')) {
+        const env = { ...(deps.processEnv ?? process.env) }
+        loadDotEnv(join(targetRepo, '.env'), env)
+        if (
+          env.VERCEL_OIDC_TOKEN !== undefined &&
+          (deps.processEnv ?? process.env).VERCEL_OIDC_TOKEN === undefined
+        ) {
+          throw new Error(
+            'VERCEL_OIDC_TOKEN loaded only from the target .env is unavailable to the Vercel SDK; export it in the launcher environment or configure VERCEL_TOKEN, VERCEL_TEAM_ID, and VERCEL_PROJECT_ID',
+          )
+        }
+        const report = await (deps.initValidation ?? validateInitReadiness)({
+          targetRepo,
+          env,
+          stdout,
+          ...(deps.exec !== undefined ? { exec: deps.exec } : {}),
+          ...(deps.initRuntimes !== undefined ? { runtimes: deps.initRuntimes } : {}),
+          ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+          ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+        })
+        return report.exitCode
+      }
+      const report = await abInit({
+        targetRepo,
+        force: parsed.flags.has('force'),
+        stdout,
+        interactive: deps.initInteractive === true,
+        ...(deps.initLauncher === undefined ? {} : { launcher: deps.initLauncher }),
+        ...(deps.initRuntimes !== undefined ? { runtimes: deps.initRuntimes } : {}),
+        env: deps.processEnv ?? process.env,
+        ...(deps.signal === undefined ? {} : { signal: deps.signal }),
+      })
+      return report.exitCode
+    }
+
+    case 'upgrade':
+    case 'update': {
+      const usage =
+        'usage: ab upgrade [target] [--no-self-update | --version <semver>] [--no-commit] (§16.3)'
+      const parsed = parseArgs(
+        rest,
+        { 'no-self-update': 'boolean', 'no-commit': 'boolean', version: 'value' },
+        usage,
+      )
+      if (parsed.positionals.length > 1) throw new Error(usage)
+      if (parsed.flags.has('no-self-update') && parsed.flags.has('version')) {
+        throw new Error(`--no-self-update and --version cannot be combined — ${usage}`)
+      }
+      const targetRepo = parsed.positionals[0] ?? deps.workspacePath
+      const noCommit = parsed.flags.has('no-commit')
+      const handoff = deps.processEnv?.[SELF_UPDATE_HANDOFF_ENV] === '1'
+      let commitContext: UpgradeCommitContext | undefined
+      if (!noCommit) {
+        const handoffPath = handoff ? deps.processEnv?.[UPGRADE_COMMIT_CONTEXT_ENV] : undefined
+        if (handoff && handoffPath === undefined) {
+          stderr(
+            'ab upgrade did not commit: automatic commit suppressed for cross-version compatibility because the parent binary did not provide a pre-self-update Git baseline; all upgrade-owned changes remain uncommitted for the operator',
+          )
+        } else {
+          try {
+            commitContext =
+              handoffPath === undefined
+                ? await createUpgradeCommitContext(targetRepo)
+                : await loadUpgradeCommitContext(handoffPath, targetRepo)
+          } catch (error) {
+            stderr(
+              `ab upgrade did not commit: could not capture or restore the pre-upgrade Git baseline: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            )
+          }
+        }
+      }
+
+      try {
+        if (!parsed.flags.has('no-self-update') && !handoff) {
+          const update = await (deps.selfUpdate ?? selfUpdate)({
+            targetRepo,
+            stdout,
+            stderr,
+            env: deps.processEnv ?? {},
+            noCommit: noCommit || commitContext === undefined,
+            ...(commitContext === undefined
+              ? {}
+              : { upgradeCommitContextPath: commitContext.path }),
+            ...(deps.distributionRoot === undefined ? {} : { distRoot: deps.distributionRoot }),
+            ...(deps.selfUpdateCommand === undefined ? {} : { command: deps.selfUpdateCommand }),
+            ...(stringFlag(parsed, 'version') === undefined
+              ? {}
+              : { version: stringFlag(parsed, 'version') }),
+          })
+          if (update.kind === 'handoff') return update.exitCode
+          if (update.kind === 'failed') return 1
+        }
+        const resolverFactory = deps.upgradeResolverFactory
+        let resolver: ResolveConflict | undefined
+        const resolveConflict: ResolveConflict | undefined =
+          resolverFactory === undefined
+            ? undefined
+            : async (input, options) => {
+                // Factory/config/runtime work is lazy: a clean upgrade never
+                // needs agent infrastructure. Throws are caught per skill by
+                // abUpgrade and become the byte-preserving conflicted outcome.
+                resolver ??= resolverFactory({
+                  targetRepo,
+                  env: deps.processEnv ?? {},
+                })
+                return resolver(input, options)
+              }
+        const progressResolver =
+          resolveConflict === undefined || deps.terminal === undefined
+            ? resolveConflict
+            : withUpgradeProgress(resolveConflict, {
+                terminal: deps.terminal,
+                input: deps.input ?? { start: () => () => {} },
+              })
+        const report = await abUpgrade({
+          targetRepo,
+          stdout,
+          ...(deps.distributionRoot !== undefined ? { distRoot: deps.distributionRoot } : {}),
+          ...(deps.exec !== undefined ? { exec: deps.exec } : {}),
+          ...(progressResolver !== undefined ? { resolveConflict: progressResolver } : {}),
+        })
+        if (commitContext !== undefined) {
+          await finishUpgradeCommit(commitContext, report, { stdout, stderr })
+        }
+        return report.exitCode
+      } finally {
+        if (commitContext !== undefined) await cleanupUpgradeCommitContext(commitContext)
+      }
+    }
+
+    // Ticket grooming runs OUTSIDE build sessions (§8.8): command-scoped flag
+    // declarations and one configured-source seam own every pre-build operation.
+    case 'ticket': {
+      if (deps.exec === undefined) {
+        throw new Error("'ab ticket' needs an exec seam — this is a wiring bug in the ab binary")
+      }
+      await abTicket(rest, {
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        stderr,
+      })
+      return 0
+    }
+
+    // dispatch runs OUTSIDE build sessions (§3.3, §12): it serves a repo, not
+    // a build, so it routes before any store/env requirement and does its own
+    // heavy wiring (like ticket create). One dispatcher per repo (§12).
+    case 'dispatch': {
+      const usage =
+        'usage: ab dispatch [--once] [--interval <seconds>] [--store <ref>] [--repository <origin>] [--plain] [--intake | --no-intake] [--auto-merge | --no-auto-merge] (§3.3)'
+      const parsed = parseArgs(
+        rest,
+        {
+          once: 'boolean',
+          interval: 'value',
+          store: 'value',
+          repository: 'value',
+          plain: 'boolean',
+          intake: 'boolean',
+          'no-intake': 'boolean',
+          'auto-merge': 'boolean',
+          'no-auto-merge': 'boolean',
+        },
+        usage,
+      )
+      if (parsed.positionals.length > 0) throw new Error(usage)
+
+      const once = parsed.flags.has('once')
+      const plain = parsed.flags.has('plain')
+      const sawIntake = parsed.flags.has('intake')
+      const sawNoIntake = parsed.flags.has('no-intake')
+      const sawAutoMerge = parsed.flags.has('auto-merge')
+      const sawNoAutoMerge = parsed.flags.has('no-auto-merge')
+      if (sawIntake && sawNoIntake) {
+        throw new Error(`--intake and --no-intake cannot be combined — ${usage}`)
+      }
+      if (sawAutoMerge && sawNoAutoMerge) {
+        throw new Error(`--auto-merge and --no-auto-merge cannot be combined — ${usage}`)
+      }
+
+      const interval = stringFlag(parsed, 'interval')
+      let intervalMs: number | undefined
+      if (interval !== undefined) {
+        const seconds = Number(interval)
+        if (!Number.isFinite(seconds) || seconds <= 0) {
+          throw new Error(`--interval requires a positive number of seconds — ${usage}`)
+        }
+        intervalMs = Math.round(seconds * 1000)
+      }
+      const storeRef = stringFlag(parsed, 'store')
+      const repository = stringFlag(parsed, 'repository') ?? deps.processEnv?.AB_REPOSITORY
+      const intake = sawIntake ? true : sawNoIntake ? false : undefined
+      const defaultAutoMerge = sawAutoMerge ? true : sawNoAutoMerge ? false : undefined
+      if (deps.exec === undefined) {
+        throw new Error("'ab dispatch' needs an exec seam — this is a wiring bug in the ab binary")
+      }
+      await abDispatch({
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        stderr,
+        once,
+        plain,
+        ...(intake !== undefined ? { intake } : {}),
+        ...(defaultAutoMerge !== undefined ? { defaultAutoMerge } : {}),
+        ...(intervalMs !== undefined ? { intervalMs } : {}),
+        ...(storeRef !== undefined ? { storeRef } : {}),
+        ...(repository !== undefined && repository !== '' ? { repository } : {}),
+        ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+        ...(deps.terminal !== undefined ? { terminal: deps.terminal } : {}),
+        ...(deps.input !== undefined ? { input: deps.input } : {}),
+        ...(deps.resolveDashboardRenderer !== undefined
+          ? { resolveDashboardRenderer: deps.resolveDashboardRenderer }
+          : {}),
+      })
+      return 0
+    }
+
+    case 'plugin': {
+      if (deps.exec === undefined) {
+        throw new Error("'ab plugin' needs an exec seam — this is a wiring bug in the ab binary")
+      }
+      return await abPlugin(rest, {
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        stderr,
+        ...(deps.pluginSubprocess !== undefined ? { subprocess: deps.pluginSubprocess } : {}),
+      })
+    }
+
+    // models runs OUTSIDE build sessions (§9): it lists Pi's model catalog so a
+    // human can find the provider-qualified id to paste into autobuild.toml. No
+    // store needed — the local Pi CLI is behind an injectable catalog seam.
+    case 'models': {
+      const usage = 'usage: ab models [query] [--available] (§9)'
+      const parsed = parseArgs(rest, { available: 'boolean' }, usage)
+      await abModels({
+        ...(parsed.positionals.length > 0 ? { query: parsed.positionals.join(' ') } : {}),
+        availableOnly: parsed.flags.has('available'),
+        stdout,
+      })
+      return 0
+    }
+
+    // Read-only status commands run OUTSIDE build sessions (§16.3) like
+    // dispatch: they resolve their own store (--store > AB_STORE > default).
+    case 'repository': {
+      const usage = 'usage: ab repository status [--json] [--store <ref>] (§8.2)'
+      const [sub, ...more] = rest
+      if (sub !== 'status') throw new Error(usage)
+      const parsed = parseArgs(more, { json: 'boolean', store: 'value' }, usage)
+      if (parsed.positionals.length > 0) throw new Error(usage)
+      if (deps.exec === undefined) {
+        throw new Error(
+          "'ab repository status' needs an exec seam — this is a wiring bug in the ab binary",
+        )
+      }
+      const storeRef = stringFlag(parsed, 'store')
+      await abRepositoryStatus({
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        json: parsed.flags.has('json'),
+        ...(storeRef !== undefined ? { storeRef } : {}),
+        ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+      })
+      return 0
+    }
+
+    case 'builds': {
+      const usage = 'usage: ab builds [--queued] [--all] [--json] [--store <ref>] (§8.2)'
+      const parsed = parseArgs(
+        rest,
+        { queued: 'boolean', all: 'boolean', json: 'boolean', store: 'value' },
+        usage,
+      )
+      if (parsed.positionals.length > 0) throw new Error(usage)
+      const storeRef = stringFlag(parsed, 'store')
+      if (deps.exec === undefined) {
+        throw new Error("'ab builds' needs an exec seam — this is a wiring bug in the ab binary")
+      }
+      await abBuilds({
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        queued: parsed.flags.has('queued'),
+        all: parsed.flags.has('all'),
+        json: parsed.flags.has('json'),
+        ...(storeRef !== undefined ? { storeRef } : {}),
+        ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+        ...(deps.clock !== undefined ? { now: deps.clock } : {}),
+      })
+      return 0
+    }
+
+    case 'mcp': {
+      const parsed = parseArgs(rest, { store: 'value', repo: 'value' }, AB_MCP_USAGE)
+      if (parsed.positionals.length > 0) throw new Error(AB_MCP_USAGE)
+      if (deps.exec === undefined) {
+        throw new Error("'ab mcp' needs an exec seam — this is a wiring bug in the ab binary")
+      }
+      const storeRef = stringFlag(parsed, 'store')
+      const repo = stringFlag(parsed, 'repo')
+      return await abMcp({
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        stderr,
+        ...(storeRef !== undefined ? { storeRef } : {}),
+        ...(repo !== undefined ? { repo } : {}),
+        ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+        ...(deps.clock !== undefined ? { clock: deps.clock } : {}),
+      })
+    }
+
+    case 'build': {
+      const usage = 'usage: ab build status <slug> [--events <n>] [--json] [--store <ref>] (§8.2)'
+      const [sub, ...more] = rest
+      // Only `status` today; the subcommand shape keeps room for `ab build <verb>`.
+      if (sub !== 'status') {
+        throw new Error(usage)
+      }
+      const parsed = parseArgs(more, { events: 'value', json: 'boolean', store: 'value' }, usage)
+      const [slug] = parsed.positionals
+      if (slug === undefined || parsed.positionals.length !== 1) {
+        throw new Error(usage)
+      }
+      const eventCount = stringFlag(parsed, 'events')
+      let events: number | undefined
+      if (eventCount !== undefined) {
+        const count = Number(eventCount)
+        if (!Number.isInteger(count) || count <= 0) {
+          throw new Error(`--events requires a positive integer, got "${eventCount}" — ${usage}`)
+        }
+        events = count
+      }
+      const storeRef = stringFlag(parsed, 'store')
+      if (deps.exec === undefined) {
+        throw new Error("'ab build' needs an exec seam — this is a wiring bug in the ab binary")
+      }
+      await abBuildStatus({
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        slug,
+        json: parsed.flags.has('json'),
+        ...(events !== undefined ? { events } : {}),
+        ...(storeRef !== undefined ? { storeRef } : {}),
+        ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+        ...(deps.clock !== undefined ? { now: deps.clock } : {}),
+      })
+      return 0
+    }
+
+    // Read-only streaming runs OUTSIDE build sessions (§16.3) like the other
+    // status commands: it resolves its own store (--store > AB_STORE > default)
+    // and honors a complete ambient identity as a scope restriction (watch.ts).
+    case 'watch': {
+      const parsed = parseArgs(
+        rest,
+        {
+          repository: 'boolean',
+          event: 'multi',
+          since: 'value',
+          timeout: 'value',
+          interval: 'value',
+          count: 'value',
+          json: 'boolean',
+          store: 'value',
+        },
+        WATCH_USAGE,
+      )
+      const countFlag = stringFlag(parsed, 'count')
+      let count: number | undefined
+      if (countFlag !== undefined) {
+        const parsedCount = Number(countFlag)
+        if (!Number.isInteger(parsedCount) || parsedCount <= 0) {
+          throw new Error(
+            `--count requires a positive integer, got "${countFlag}" — ${WATCH_USAGE}`,
+          )
+        }
+        count = parsedCount
+      }
+      const storeRef = stringFlag(parsed, 'store')
+      if (deps.exec === undefined) {
+        throw new Error("'ab watch' needs an exec seam — this is a wiring bug in the ab binary")
+      }
+      await abWatch({
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        stderr,
+        slugs: parsed.positionals,
+        repository: parsed.flags.has('repository'),
+        events: multiFlag(parsed, 'event'),
+        since: stringFlag(parsed, 'since'),
+        timeout: stringFlag(parsed, 'timeout'),
+        interval: stringFlag(parsed, 'interval'),
+        ...(count !== undefined ? { count } : {}),
+        json: parsed.flags.has('json'),
+        ...(storeRef !== undefined ? { storeRef } : {}),
+        ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+        ...(deps.clock !== undefined ? { now: deps.clock } : {}),
+        ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+      })
+      return 0
+    }
+
+    // Read-only blocking runs OUTSIDE build sessions (§16.3) exactly like
+    // `ab watch`: it resolves its own store and honors a complete ambient
+    // identity as a scope restriction. Exit codes 0/2/3/4 are the command's
+    // contract (wait.ts); thrown usage errors exit 1 via runCli.
+    case 'wait': {
+      const parsed = parseArgs(
+        rest,
+        {
+          for: 'multi',
+          event: 'multi',
+          since: 'value',
+          timeout: 'value',
+          interval: 'value',
+          json: 'boolean',
+          store: 'value',
+        },
+        WAIT_USAGE,
+      )
+      if (multiFlag(parsed, 'for').length === 0 && multiFlag(parsed, 'event').length === 0) {
+        throw new Error(WAIT_USAGE)
+      }
+      const storeRef = stringFlag(parsed, 'store')
+      if (deps.exec === undefined) {
+        throw new Error("'ab wait' needs an exec seam — this is a wiring bug in the ab binary")
+      }
+      return await abWait({
+        targetRepo: deps.workspacePath,
+        env: deps.processEnv ?? {},
+        exec: deps.exec,
+        stdout,
+        stderr,
+        slugs: parsed.positionals,
+        forValues: multiFlag(parsed, 'for'),
+        events: multiFlag(parsed, 'event'),
+        since: stringFlag(parsed, 'since'),
+        timeout: stringFlag(parsed, 'timeout'),
+        interval: stringFlag(parsed, 'interval'),
+        json: parsed.flags.has('json'),
+        ...(storeRef !== undefined ? { storeRef } : {}),
+        ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+        ...(deps.clock !== undefined ? { now: deps.clock } : {}),
+        ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+      })
+    }
+
+    case 'abort': {
+      const usage = 'usage: ab abort <slug> [--store <ref>]'
+      const parsed = parseArgs(rest, { store: 'value' }, usage)
+      if (parsed.positionals.length !== 1) throw new Error(usage)
+      await runBuildControl(
+        deps,
+        parsed.positionals[0]!,
+        { kind: 'abort' },
+        stringFlag(parsed, 'store'),
+      )
+      return 0
+    }
+
+    case 'pause':
+    case 'resume': {
+      const usage = `usage: ab ${command} <slug> | --all [--store <ref>] [--json]`
+      const parsed = parseArgs(rest, { store: 'value', all: 'boolean', json: 'boolean' }, usage)
+      const all = parsed.flags.has('all')
+      const json = parsed.flags.has('json')
+      const storeRef = stringFlag(parsed, 'store')
+      if (json && !all) throw new Error(`--json requires --all — ${usage}`)
+      if (all && parsed.positionals.length > 0) {
+        throw new Error(`--all takes no build slug — ${usage}`)
+      }
+      if (all) {
+        return runBulkControl(deps, command, {
+          json,
+          ...(storeRef !== undefined ? { storeRef } : {}),
+        })
+      }
+      if (parsed.positionals.length !== 1) throw new Error(usage)
+      await runBuildControl(deps, parsed.positionals[0]!, { kind: command }, storeRef)
+      return 0
+    }
+
+    case 'auto-merge': {
+      const usage = 'usage: ab auto-merge <slug> <on|off> [--store <ref>]'
+      const parsed = parseArgs(rest, { store: 'value' }, usage)
+      const [slug, setting] = parsed.positionals
+      if (
+        parsed.positionals.length !== 2 ||
+        slug === undefined ||
+        (setting !== 'on' && setting !== 'off')
+      ) {
+        throw new Error(usage)
+      }
+      await runBuildControl(
+        deps,
+        slug,
+        { kind: setting === 'on' ? 'auto-merge-on' : 'auto-merge-off' },
+        stringFlag(parsed, 'store'),
+      )
+      return 0
+    }
+
+    case 'answer': {
+      const usage =
+        'usage: ab answer <slug> [<text>] [--review-round-ceiling <n> | --dismiss | --revise-spec <file> | --revise-spec-from-ticket] [--store <ref>]'
+      const parsed = parseArgs(
+        rest,
+        {
+          store: 'value',
+          dismiss: 'boolean',
+          'revise-spec': 'value',
+          'revise-spec-from-ticket': 'boolean',
+          'review-round-ceiling': 'value',
+        },
+        usage,
+      )
+      const [slug, ...text] = parsed.positionals
+      if (slug === undefined) throw new Error(usage)
+      const resolutionFlags = [
+        parsed.flags.has('dismiss'),
+        parsed.flags.has('revise-spec'),
+        parsed.flags.has('revise-spec-from-ticket'),
+      ].filter(Boolean).length
+      if (resolutionFlags > 1) throw new Error(`resolution flags are mutually exclusive — ${usage}`)
+      const answer = text.join(' ')
+      const storeRef = stringFlag(parsed, 'store')
+      const specPath = stringFlag(parsed, 'revise-spec')
+      const ceilingFlag = stringFlag(parsed, 'review-round-ceiling')
+      let reviewRoundCeiling: number | undefined
+      if (ceilingFlag !== undefined) {
+        const parsedCeiling = Number(ceilingFlag)
+        if (!Number.isInteger(parsedCeiling) || parsedCeiling <= 0) {
+          throw new Error(
+            `--review-round-ceiling requires a positive integer, got "${ceilingFlag}" — ${usage}`,
+          )
+        }
+        if (specPath !== undefined || parsed.flags.has('revise-spec-from-ticket')) {
+          throw new Error(
+            'cannot combine --review-round-ceiling with a spec revision: revision resets the loop round budget on its own',
+          )
+        }
+        if (parsed.flags.has('dismiss')) {
+          throw new Error(
+            'cannot combine --review-round-ceiling with --dismiss; use guidance or a bare retry to answer the review-round-limit escalation',
+          )
+        }
+        reviewRoundCeiling = parsedCeiling
+      }
+      const resolve = parsed.flags.has('dismiss')
+        ? ({ kind: 'dismiss-finding' } as const)
+        : specPath !== undefined
+          ? ({
+              kind: 'revise-spec',
+              body: {
+                kind: 'supplied',
+                origin: `--revise-spec ${specPath}`,
+                read: async (): Promise<string> => {
+                  try {
+                    return await readFile(specPath, 'utf8')
+                  } catch (error) {
+                    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+                      throw new Error(
+                        `--revise-spec ${specPath}: file not found — expected a file holding the replacement spec body`,
+                      )
+                    }
+                    throw error
+                  }
+                },
+              },
+            } as const)
+          : parsed.flags.has('revise-spec-from-ticket')
+            ? ({ kind: 'revise-spec', body: { kind: 'ticket' } } as const)
+            : undefined
+      const readTicketBody =
+        resolve?.kind === 'revise-spec' && resolve.body.kind === 'ticket'
+          ? async (ref: TicketRef): Promise<string> => {
+              const { source } = await openTicketSource(
+                {
+                  targetRepo: deps.workspacePath,
+                  env: deps.processEnv ?? {},
+                  ...(deps.exec !== undefined ? { exec: deps.exec } : {}),
+                  stdout,
+                  ...(storeRef !== undefined ? { storeRef } : {}),
+                },
+                'ab answer --revise-spec-from-ticket',
+              )
+              if (source.name !== ref.source) {
+                throw new Error(
+                  `build ticket source is "${ref.source}", but this repository is configured for "${source.name}"; refusing to read a same-id ticket from a different source`,
+                )
+              }
+              const ticket = await source.get(ref.id)
+              if (ticket === null) {
+                throw new Error(
+                  `ticket "${ref.id}" was not found in the configured ${source.name} source`,
+                )
+              }
+              if (ticket.ref.source !== ref.source || ticket.ref.id !== ref.id) {
+                throw new Error(
+                  `ticket adapter returned ${ticket.ref.source}:${ticket.ref.id}, expected ${ref.source}:${ref.id}`,
+                )
+              }
+              return ticket.body
+            }
+          : undefined
+      await runBuildControl(
+        deps,
+        slug,
+        {
+          kind: 'answer',
+          ...(answer !== '' ? { text: answer } : {}),
+          ...(resolve !== undefined ? { resolve } : {}),
+          ...(reviewRoundCeiling !== undefined ? { reviewRoundCeiling } : {}),
+        },
+        storeRef,
+        readTicketBody,
+      )
+      return 0
+    }
+
+    case 'harvest': {
+      const [sub, ...more] = rest
+      if (sub === 'status') {
+        const usage = 'usage: ab harvest status [--events <n>] [--json] [--store <ref>]'
+        const parsed = parseArgs(more, { events: 'value', json: 'boolean', store: 'value' }, usage)
+        if (parsed.positionals.length > 0) throw new Error(usage)
+        const eventCount = stringFlag(parsed, 'events')
+        let events: number | undefined
+        if (eventCount !== undefined) {
+          const count = Number(eventCount)
+          if (!Number.isInteger(count) || count <= 0) {
+            throw new Error(`--events requires a positive integer — ${usage}`)
+          }
+          events = count
+        }
+        const storeRef = stringFlag(parsed, 'store')
+        if (deps.exec === undefined) {
+          throw new Error(
+            "'ab harvest status' needs an exec seam — this is a wiring bug in the ab binary",
+          )
+        }
+        await abHarvestStatus({
+          repo: deps.workspacePath,
+          env: deps.processEnv ?? {},
+          exec: deps.exec,
+          stdout,
+          json: parsed.flags.has('json'),
+          ...(events !== undefined ? { events } : {}),
+          ...(storeRef !== undefined ? { storeRef } : {}),
+        })
+        return 0
+      }
+      if (sub === 'context') {
+        const usage = 'usage: ab harvest context [--json]'
+        const parsed = parseArgs(more, { json: 'boolean' }, usage)
+        if (parsed.positionals.length > 0) throw new Error(usage)
+        const manifest = await buildHarvestContext(requireHarvestSession('context', deps))
+        if (parsed.flags.get('json') === true) {
+          stdout(JSON.stringify(manifest, null, 2))
+        } else {
+          stdout(
+            `harvest context materialized for ${manifest.run} — ${manifest.phase}@${manifest.round}`,
+          )
+          stdout(`required deposit: ${manifest.required.join(', ')}`)
+          for (const file of manifest.materialized) stdout(`  .ab/${file}`)
+        }
+        return 0
+      }
+      if (sub === 'submit') {
+        const usage = 'usage: ab harvest submit <proposals.json>'
+        const parsed = parseArgs(more, {}, usage)
+        const [file] = parsed.positionals
+        if (file === undefined || parsed.positionals.length !== 1) {
+          throw new Error(usage)
+        }
+        const event = await submitHarvestProposals(requireHarvestSession('submit', deps), file)
+        stdout(`${event.type} recorded (repo seq ${event.seq})`)
+        return 0
+      }
+      if (sub === 'verdict') {
+        const usage =
+          'usage: ab harvest verdict <approve|revise|escalate> --notes <file> ' +
+          '[--findings <json>] [--reason <text>]'
+        const parsed = parseArgs(
+          more,
+          { notes: 'value', findings: 'value', reason: 'value' },
+          usage,
+        )
+        const [kind] = parsed.positionals
+        const notes = stringFlag(parsed, 'notes')
+        if (kind === undefined || parsed.positionals.length !== 1 || notes === undefined) {
+          throw new Error(usage)
+        }
+        const event = await submitHarvestVerdict(requireHarvestSession('verdict', deps), {
+          verdict: kind,
+          notes,
+          ...(stringFlag(parsed, 'findings') !== undefined
+            ? { findings: stringFlag(parsed, 'findings')! }
+            : {}),
+          ...(stringFlag(parsed, 'reason') !== undefined
+            ? { reason: stringFlag(parsed, 'reason')! }
+            : {}),
+        })
+        stdout(`${event.type} recorded (repo seq ${event.seq})`)
+        return 0
+      }
+      throw new Error('usage: ab harvest <status|context|submit|verdict> …')
+    }
+
+    case 'context': {
+      const session = requireSession(command, deps)
+      const usage = 'usage: ab context [--json]'
+      const parsed = parseArgs(rest, { json: 'boolean' }, usage)
+      if (parsed.positionals.length > 0) throw new Error(usage)
+      const manifest = await buildContext(session)
+      if (parsed.flags.get('json') === true) {
+        stdout(JSON.stringify(manifest, null, 2))
+      } else {
+        for (const line of renderManifest(manifest)) stdout(line)
+      }
+      return 0
+    }
+
+    case 'artifact': {
+      const [sub, ...more] = rest
+      if (sub === 'download') {
+        const usage =
+          'usage: ab artifact download <build> <kind>[@rev] --output <file> [--store <ref>] (§8.2)'
+        const parsed = parseArgs(more, { output: 'value', store: 'value' }, usage)
+        const [build, spec] = parsed.positionals
+        const outputPath = stringFlag(parsed, 'output')
+        if (
+          build === undefined ||
+          spec === undefined ||
+          parsed.positionals.length !== 2 ||
+          outputPath === undefined
+        ) {
+          throw new Error(usage)
+        }
+        const storeRef = stringFlag(parsed, 'store')
+        if (deps.exec === undefined) {
+          throw new Error(
+            "'ab artifact download' needs an exec seam — this is a wiring bug in the ab binary",
+          )
+        }
+        const downloaded = await artifactDownload({
+          targetRepo: deps.workspacePath,
+          env: deps.processEnv ?? {},
+          exec: deps.exec,
+          build,
+          spec,
+          outputPath,
+          ...(storeRef !== undefined ? { storeRef } : {}),
+          ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+        })
+        stdout(
+          `downloaded ${downloaded.artifact.meta.kind}@${downloaded.artifact.meta.revision} to ${downloaded.outputPath}`,
+        )
+        return 0
+      }
+
+      const session = requireSession(command, deps)
+      if (sub === 'put') {
+        const usage = 'usage: ab artifact put <kind> <file> [--attach] (§8.2)'
+        const parsed = parseArgs(more, { attach: 'boolean' }, usage)
+        const [kind, file] = parsed.positionals
+        if (kind === undefined || file === undefined || parsed.positionals.length !== 2) {
+          throw new Error(usage)
+        }
+        const attach = parsed.flags.has('attach')
+        const meta = await artifactPut(session, kind, file, { attach })
+
+        // A designation made after the PR exists (verify after reconcile or a
+        // finalize post-step) republishes the same complete projection. Every
+        // external side effect is best-effort after the atomic designation.
+        if (attach) {
+          try {
+            const events = await session.store.getEvents(session.env.build)
+            const pr = reduceBuild(events).pr
+            if (pr !== undefined) {
+              try {
+                await preparePrAttachments(session, events, pr.url)
+              } catch {
+                // A post-upload hosted-fact failure records the exact public
+                // asset identity before throwing. Keep going so its hosting
+                // failure cannot suppress the complete text projection.
+              }
+              try {
+                await session.forge.commentOnPr(
+                  session.workspacePath,
+                  pr.number,
+                  renderPrSummary(session.env, await session.store.getEvents(session.env.build)),
+                )
+              } catch {
+                // The exact artifact and designation are already durable. A
+                // comment refresh cannot turn the agent's deposit into failure.
+              }
+            }
+          } catch {
+            // Reading the optional PR projection is best-effort too.
+          }
+        }
+
+        // The assigned rev is the command's one output (§8.2).
+        stdout(String(meta.revision))
+        return 0
+      }
+      if (sub === 'get') {
+        const usage = 'usage: ab artifact get <kind>[@rev] (§8.2)'
+        const parsed = parseArgs(more, {}, usage)
+        const [spec] = parsed.positionals
+        if (spec === undefined || parsed.positionals.length !== 1) {
+          throw new Error(usage)
+        }
+        const artifact = await artifactGet(session, spec)
+        stdout(textContent(artifact))
+        return 0
+      }
+      throw new Error('usage: ab artifact <put|get|download> … (§8.2)')
+    }
+
+    case 'observe': {
+      const usage =
+        'usage: ab observe --kind <followup|refactor|latent-bug> [--files a,b] [--refs x,y] <summary> (§8.2)'
+      const parsed = parseArgs(rest, { kind: 'value', files: 'value', refs: 'value' }, usage)
+      const kind = stringFlag(parsed, 'kind')
+      if (kind === undefined) {
+        throw new Error("'ab observe' requires --kind <followup|refactor|latent-bug> (§8.2)")
+      }
+      const session = requireSession(command, deps)
+      const summary = parsed.positionals.join(' ')
+      const files = listFlag(parsed, 'files')
+      const refs = listFlag(parsed, 'refs')
+      const event = await observe(session, {
+        kind,
+        summary,
+        ...(files !== undefined ? { files } : {}),
+        ...(refs !== undefined ? { refs } : {}),
+      })
+      stdout(`observation recorded: ${event.payload.id}`)
+      return 0
+    }
+
+    case 'done': {
+      const session = requireSession(command, deps)
+      const usage = 'usage: ab done [--notes <file>] (§8.2)'
+      const parsed = parseArgs(rest, { notes: 'value' }, usage)
+      if (parsed.positionals.length > 0) throw new Error(usage)
+      const notes = stringFlag(parsed, 'notes')
+      const event = await done(session, notes !== undefined ? { notes } : {})
+      stdout(
+        event.type === 'publication.requested'
+          ? `${event.type} recorded (seq ${event.seq}); remote publication is pending — do not run ab done again`
+          : `${event.type} recorded (seq ${event.seq})`,
+      )
+      return 0
+    }
+
+    case 'verdict': {
+      const usage =
+        'usage: ab verdict <approve|revise|escalate|pass|fail|skip> ' +
+        '[--findings <json>] [--notes <file>] [--reason <text>] [--report <file>] (§8.2)'
+      const parsed = parseArgs(
+        rest,
+        {
+          findings: 'value',
+          notes: 'value',
+          reason: 'value',
+          report: 'value',
+        },
+        usage,
+      )
+      const [kind] = parsed.positionals
+      if (kind === undefined || parsed.positionals.length !== 1) {
+        throw new Error(usage)
+      }
+      const session = requireSession(command, deps)
+      const notes = stringFlag(parsed, 'notes')
+      const findings = stringFlag(parsed, 'findings')
+      const reason = stringFlag(parsed, 'reason')
+      const report = stringFlag(parsed, 'report')
+      const events = await verdict(session, {
+        verdict: kind,
+        ...(notes !== undefined ? { notes } : {}),
+        ...(findings !== undefined ? { findings } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+        ...(report !== undefined ? { report } : {}),
+      })
+      for (const event of events) stdout(`${event.type} recorded (seq ${event.seq})`)
+      return 0
+    }
+
+    case 'escalate': {
+      const usage = 'usage: ab escalate <question> [--refs a,b] (§8.2)'
+      const parsed = parseArgs(rest, { refs: 'value' }, usage)
+      const question = parsed.positionals.join(' ')
+      if (question === '') {
+        throw new Error('usage: ab escalate <question> [--refs a,b] (§8.2)')
+      }
+      const session = requireSession(command, deps)
+      const refs = listFlag(parsed, 'refs')
+      const event = await escalate(session, {
+        question,
+        ...(refs !== undefined ? { refs } : {}),
+      })
+      stdout(`escalation raised: ${event.payload.id}`)
+      return 0
+    }
+
+    default: {
+      stderr(`unknown command "${command}"\n\n${renderTopLevelHelp()}`)
+      return 1
+    }
+  }
+}