codex-workflow-v2 2.0.0-beta.13.14 → 2.0.0-beta.13.16

package/src/cli.ts

@@ -0,0 +1,1583 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import type {
+  CorrectivePlanAuditInput,
+  DelegationPolicyInput,
+  GraphKind,
+  GraphMode,
+  GraphRefreshEvidence,
+  GraphRefreshRequest,
+  KnowledgeSelection,
+  MilestonePlanInput,
+  ReviewInput,
+  TaskPlanInput,
+  WorkspaceOwner,
+} from './contracts.js';
+import type { RecordPlanRiskAuditInput } from './alpha6/plan-risk.js';
+import { defaultTaskWorkerActor } from './alpha6/handoff.js';
+import {
+  assertCliSuccessCredentialSafety,
+  projectCliErrorMessage,
+  projectCliErrorValue,
+  UnsafeCredentialOutputError,
+} from './credential-output.js';
+import {
+  assertNoLegacyCredentialArguments,
+  consumeCredentialReference,
+  issueCredentialReference,
+  resolveCredentialReference,
+} from './credential-transport.js';
+import { integrationDiagnostics } from './diagnostics.js';
+import { WorkflowError } from './errors.js';
+import { prepareGraphView } from './graph.js';
+import { migrateState } from './migration.js';
+import { changedFiles, currentBranch, isClean, resolveRepositoryIdentity } from './repository.js';
+import { launchStrictReviewer } from './reviewer.js';
+import type { ExternalStrictStepReviewInput, ExternalStrictTaskReviewInput, ReviewMode } from './reviewer.js';
+import {
+  WorkflowService,
+  type AuditedRemediationMaterializationInput,
+  type DiscoveryInput,
+  type DiscoveryPatch,
+} from './workflow.js';
+import { gatewayHandshake } from './gateway-handshake.js';
+import type {
+  CorrectiveReplanHumanGate,
+  CorrectiveReplanPublicCandidate,
+  CorrectiveReplanPublicCredential,
+} from './state/corrective-replan-public.js';
+import { CLI_ACTIONS } from './cli-actions.js';
+
+interface ParsedArguments {
+  positionals: string[];
+  options: Map<string, string[]>;
+}
+
+interface CliHelpSpec {
+  requiredOptions: string[];
+  optionalOptions: string[];
+  fileInput?: {
+    description: string;
+    requiredTopLevelFields: string[];
+    reviewMode: "ordinary | security";
+    nestedReviewRequiredFields: string[];
+    example: Record<string, unknown>;
+  };
+}
+
+const CLI_HELP_SPECS: Record<string, CliHelpSpec> = {
+  'change explain': { requiredOptions: ['--task', '--file'], optionalOptions: ['--repo', '--json'] },
+  'milestone remediation-materialize': {
+    requiredOptions: ['--id', '--expected-revision', '--task', '--expected-task-revision', '--file'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update pending-review-source-preflight': { requiredOptions: ['--id'], optionalOptions: ['--repo', '--json'] },
+  'update pending-review-dependency-preflight': { requiredOptions: ['--id', '--file'], optionalOptions: ['--repo', '--json'] },
+  'update pending-review-dependency-recover': { requiredOptions: ['--id', '--file', '--expected-revision', '--actor', '--reason'], optionalOptions: ['--repo', '--json'] },
+  'update dependency-provenance-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update corrective-carryover-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json', '--file', '--risk-audit-file'],
+  },
+  'task historical-step-provenance-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task historical-step-provenance-recover': {
+    requiredOptions: ['--id', '--expected-revision', '--commit', '--actor', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update dependency-provenance-recover': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update historical-step-dependency-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update historical-step-dependency-recover': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update downstream-proof-dependency-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update downstream-proof-dependency-recover': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update downstream-proof-replan-update-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update downstream-proof-replan-dependency-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update downstream-proof-replan-dependency-recover': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update plan-integrity-update-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update plan-integrity-dependency-preflight': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'update plan-integrity-dependency-recover': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'milestone progress': {
+    requiredOptions: ['--id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'milestone authorize': {
+    requiredOptions: ['--id', '--expected-revision'],
+    optionalOptions: ['--actor', '--reason', '--delegation-grant', '--repo', '--json'],
+  },
+  'milestone validate': {
+    requiredOptions: ['--id', '--expected-revision'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'milestone accept': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--confirmation-code'],
+    optionalOptions: ['--delegation-grant', '--repo', '--json'],
+  },
+  'task plan-set': {
+    requiredOptions: ['--id', '--expected-revision', '--file', '--risk-audit-file'],
+    optionalOptions: ['--corrective-audit-file', '--repo', '--json'],
+  },
+  'task preexecution-replan': {
+    requiredOptions: [
+      '--id', '--expected-revision', '--actor', '--reason', '--file', '--expected-brief-hash',
+      '--expected-plan-hash', '--expected-plan-risk-audit-event-hash', '--expected-head-commit',
+    ],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task handoff-replace': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--target-actor', '--reason'],
+    optionalOptions: ['--writer-credential-ref', '--delegation-grant', '--expires-at', '--repo', '--json'],
+  },
+  'task handoff': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--target-actor', '--writer-credential-ref', '--delegation-grant', '--expires-at', '--repo', '--json'],
+  },
+  'task handoff-prepare': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--target-actor', '--writer-credential-ref', '--delegation-grant', '--expires-at', '--repo', '--json'],
+  },
+  'task claim': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--claim-credential-ref'],
+    optionalOptions: ['--writer-credential-ref', '--repo', '--json'],
+  },
+  'task writer-credential-replace': {
+    requiredOptions: ['--id', '--expected-revision', '--actor'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task corrective-yield': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--writer-credential-ref', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task plan-integrity-recover': {
+    requiredOptions: ['--id', '--step', '--expected-revision', '--actor'],
+    optionalOptions: ['--writer-credential-ref', '--repo', '--json'],
+  },
+  'task downstream-proof-recover': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--writer-credential-ref', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task downstream-proof-replan-recover': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task stop-override-prepare': {
+    requiredOptions: ['--id', '--step', '--expected-revision', '--actor', '--reason'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task stop-override-apply': {
+    requiredOptions: ['--id', '--step', '--expected-revision', '--actor', '--reason', '--confirmation-code'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task corrective-yield-recover': {
+    requiredOptions: ['--id', '--transaction-id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task corrective-replan-prepare': {
+    requiredOptions: ['--id', '--file'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task corrective-replan-confirm': {
+    requiredOptions: ['--id', '--file', '--gate-file', '--confirmation-code'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task corrective-replan-execute': {
+    requiredOptions: ['--id', '--file', '--credential-file'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task corrective-replan-recover': {
+    requiredOptions: ['--id', '--transaction-id'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task authorize': {
+    requiredOptions: ['--id', '--expected-revision'],
+    optionalOptions: ['--actor', '--reason', '--delegation-grant', '--repo', '--json'],
+  },
+  'task start': {
+    requiredOptions: ['--id', '--expected-revision', '--workspace-owner'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task run': {
+    requiredOptions: ['--id', '--step', '--expected-revision'],
+    optionalOptions: ['--owner', '--writer-credential-ref', '--repo', '--json'],
+  },
+  'task step-complete': {
+    requiredOptions: ['--id', '--step', '--expected-revision', '--writer-credential-ref'],
+    optionalOptions: ['--note', '--actor', '--repo', '--json'],
+  },
+  'task submit': {
+    requiredOptions: ['--id', '--expected-revision', '--writer-credential-ref'],
+    optionalOptions: ['--actor', '--repo', '--json'],
+  },
+  'task review-launch': {
+    requiredOptions: ['--id', '--expected-revision'],
+    optionalOptions: ['--actor', '--writer-credential-ref', '--repo', '--json'],
+  },
+  'task review-packet': {
+    requiredOptions: ['--id', '--expected-revision', '--review-mode'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task review-sealed-record': {
+    requiredOptions: ['--id', '--expected-revision', '--actor', '--file'],
+    optionalOptions: ['--writer-credential-ref', '--repo', '--json'],
+    fileInput: {
+      description: 'Full ExternalStrictTaskReviewInput envelope; reviewMode is a top-level JSON field.',
+      requiredTopLevelFields: ['protocol', 'packetHash', 'repositorySealHash', 'reviewerThreadId', 'reviewMode', 'review'],
+      reviewMode: 'ordinary | security',
+      nestedReviewRequiredFields: ['status', 'reviewer', 'summary', 'findings'],
+      example: {
+        protocol: 'codex-workflow-external-strict-task-review-v1',
+        packetHash: '<packet.packetHash>',
+        repositorySealHash: '<packet.repositorySealHash>',
+        reviewerThreadId: '<separate-reviewer-thread-id>',
+        reviewMode: 'ordinary',
+        review: { status: 'passed', reviewer: '<reviewer>', summary: '<summary>', findings: [] },
+      },
+    },
+  },
+  'task step-review-packet': {
+    requiredOptions: ['--id', '--step', '--expected-revision', '--review-mode'],
+    optionalOptions: ['--repo', '--json'],
+  },
+  'task step-review-record': {
+    requiredOptions: ['--id', '--step', '--expected-revision', '--actor', '--file'],
+    optionalOptions: ['--writer-credential-ref', '--repo', '--json'],
+    fileInput: {
+      description: 'Full ExternalStrictStepReviewInput envelope; reviewMode is a top-level JSON field.',
+      requiredTopLevelFields: ['protocol', 'packetHash', 'repositorySealHash', 'reviewerThreadId', 'reviewMode', 'review'],
+      reviewMode: 'ordinary | security',
+      nestedReviewRequiredFields: ['status', 'reviewer', 'summary', 'findings'],
+      example: {
+        protocol: 'codex-workflow-external-strict-step-review-v1',
+        packetHash: '<packet.packetHash>',
+        repositorySealHash: '<packet.repositorySealHash>',
+        reviewerThreadId: '<separate-reviewer-thread-id>',
+        reviewMode: 'ordinary',
+        review: { status: 'passed', reviewer: '<reviewer>', summary: '<summary>', findings: [] },
+      },
+    },
+  },
+  'task result-set': {
+    requiredOptions: ['--id', '--expected-revision', '--summary', '--writer-credential-ref'],
+    optionalOptions: ['--actor', '--limitation', '--repo', '--json'],
+  },
+  'task accept': {
+    requiredOptions: ['--id', '--expected-revision'],
+    optionalOptions: ['--actor', '--delegation-grant', '--repo', '--json'],
+  },
+  'task merge': {
+    requiredOptions: ['--id', '--expected-revision', '--writer-credential-ref'],
+    optionalOptions: ['--actor', '--repo', '--json'],
+  },
+  'task merge-confirm': {
+    requiredOptions: ['--id', '--expected-revision', '--writer-credential-ref'],
+    optionalOptions: ['--actor', '--repo', '--json'],
+  },
+};
+
+function parseArguments(argv: string[]): ParsedArguments {
+  const positionals: string[] = [];
+  const options = new Map<string, string[]>();
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (!argument) continue;
+    if (!argument.startsWith('--')) {
+      positionals.push(argument);
+      continue;
+    }
+    const equals = argument.indexOf('=');
+    const name = argument.slice(2, equals === -1 ? undefined : equals);
+    const inlineValue = equals === -1 ? null : argument.slice(equals + 1);
+    const next = argv[index + 1];
+    const value = inlineValue ?? (next && !next.startsWith('--') ? next : 'true');
+    if (inlineValue === null && next && !next.startsWith('--')) index += 1;
+    options.set(name, [...(options.get(name) ?? []), value]);
+  }
+  return { positionals, options };
+}
+
+function option(args: ParsedArguments, name: string): string | undefined {
+  return args.options.get(name)?.at(-1);
+}
+
+function reviewMode(args: ParsedArguments): ReviewMode {
+  const value = required(args, 'review-mode');
+  if (value !== 'ordinary' && value !== 'security') {
+    throw new WorkflowError('INVALID_ARGUMENT', '--review-mode must be ordinary or security.');
+  }
+  return value;
+}
+
+function cliHelp(args: ParsedArguments): Record<string, unknown> {
+  const [noun, action] = args.positionals;
+  if (!noun) {
+    return {
+      kind: 'cli-help',
+      readOnly: true,
+      scope: 'top-level',
+      usage: 'codex-workflow <command> [action] [options]',
+      commands: ['doctor', 'status', 'next', ...Object.keys(CLI_ACTIONS)],
+    };
+  }
+  if (!action) {
+    if (['doctor', 'status', 'next'].includes(noun)) {
+      const taskSelector = noun === 'next' ? ['--task'] : [];
+      return {
+        kind: 'cli-help',
+        readOnly: true,
+        scope: 'command',
+        command: noun,
+        usage: noun === 'next'
+          ? 'codex-workflow next [--task <task-id>] [--repo <path>] [--json]'
+          : noun === 'status'
+            ? 'codex-workflow status [--full] [--repo <path>] [--json]'
+            : `codex-workflow ${noun} [--repo <path>] [--json]`,
+        requiredOptions: [],
+        optionalOptions: [...taskSelector, ...(noun === 'status' ? ['--full'] : []), '--repo', '--json'],
+        exactOptionContractAvailable: true,
+      };
+    }
+    return {
+      kind: 'cli-help',
+      readOnly: true,
+      scope: 'command',
+      command: noun,
+      usage: `codex-workflow ${noun} <action> [options]`,
+      actions: CLI_ACTIONS[noun] ?? [],
+    };
+  }
+  const command = `${noun} ${action}`;
+  const spec = CLI_HELP_SPECS[command];
+  return {
+    kind: 'cli-help',
+    readOnly: true,
+    scope: 'action',
+    command,
+    usage: spec
+      ? ['codex-workflow', noun, action, ...spec.requiredOptions.map((name) => `${name} <value>`), '[options]'].join(' ')
+      : `codex-workflow ${noun} ${action} [options]`,
+    requiredOptions: spec?.requiredOptions ?? null,
+    optionalOptions: spec?.optionalOptions ?? null,
+    exactOptionContractAvailable: Boolean(spec),
+    ...(spec?.fileInput ? { fileInput: spec.fileInput } : {}),
+    ...(spec ? {} : { note: 'Consult the packaged protocol for this action option contract.' }),
+  };
+}
+
+function required(args: ParsedArguments, name: string): string {
+  const value = option(args, name)?.trim();
+  if (!value) throw new WorkflowError('INVALID_ARGUMENT', `Missing required option --${name}.`);
+  return value;
+}
+
+function repeated(args: ParsedArguments, name: string): string[] {
+  return (args.options.get(name) ?? []).map((value) => value.trim()).filter(Boolean);
+}
+
+function revision(args: ParsedArguments): number {
+  const value = Number(required(args, 'expected-revision'));
+  if (!Number.isInteger(value) || value < 1) {
+    throw new WorkflowError('INVALID_ARGUMENT', '--expected-revision must be a positive integer.');
+  }
+  return value;
+}
+
+function positiveIntegerOption(args: ParsedArguments, name: string): number {
+  const value = Number(required(args, name));
+  if (!Number.isInteger(value) || value < 1) {
+    throw new WorkflowError('INVALID_ARGUMENT', `--${name} must be a positive integer.`);
+  }
+  return value;
+}
+
+function optionalRevision(args: ParsedArguments): number | null {
+  const raw = option(args, 'expected-revision');
+  if (raw === undefined) return null;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new WorkflowError('INVALID_ARGUMENT', '--expected-revision must be a positive integer.');
+  }
+  return value;
+}
+
+function graphKind(args: ParsedArguments): GraphKind {
+  const value = required(args, 'kind');
+  if (value !== 'product' && value !== 'workflow') {
+    throw new WorkflowError('INVALID_ARGUMENT', '--kind must be product or workflow.');
+  }
+  return value;
+}
+
+function graphMode(args: ParsedArguments): GraphMode {
+  const value = option(args, 'mode') ?? 'moderate';
+  if (value !== 'moderate' && value !== 'full') {
+    throw new WorkflowError('INVALID_ARGUMENT', '--mode must be moderate or full.');
+  }
+  return value;
+}
+
+function jsonFile<T>(args: ParsedArguments, optionName = 'file'): T {
+  const file = path.resolve(required(args, optionName));
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as T;
+  } catch (error) {
+    throw new WorkflowError('INVALID_ARGUMENT', `Cannot read JSON from ${file}.`, {
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function stdinJson<T>(): T {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8')) as T;
+  } catch (error) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Cannot read JSON from stdin.', {
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function repository(args: ParsedArguments): string {
+  return path.resolve(option(args, 'repo') ?? '.');
+}
+
+const WRITER_CREDENTIAL_ACTIONS = [
+  'task run',
+  'task step-complete',
+  'task submit',
+  'task review-record',
+  'task review-launch',
+  'task review-sealed-record',
+  'task step-review',
+  'task step-review-record',
+  'task corrective-decision-recover',
+  'task remediation-mode-recover',
+  'task plan-integrity-recover',
+  'task downstream-proof-recover',
+  'task corrective-decision',
+  'task corrective-yield',
+  'task handoff',
+  'task handoff-prepare',
+  'task handoff-replace',
+  'task claim',
+  'task handback',
+  'task handback-create',
+  'task result-set',
+  'task merge',
+  'task merge-confirm',
+] as const;
+
+function credentialToken(
+  workflow: WorkflowService,
+  repo: string,
+  args: ParsedArguments,
+  kind: 'writer-lease' | 'claim-token',
+  action: string,
+  entityId: string,
+  actor: string | null,
+  requiredReference: boolean,
+): string | null {
+  const optionName = kind === 'writer-lease' ? 'writer-credential-ref' : 'claim-credential-ref';
+  const reference = option(args, optionName);
+  if (!reference) {
+    if (requiredReference) {
+      throw new WorkflowError('INVALID_ARGUMENT', `Missing required option --${optionName}.`);
+    }
+    return null;
+  }
+  const identity = resolveRepositoryIdentity(repo);
+  return resolveCredentialReference({
+    stateRoot: workflow.store.root,
+    projectId: identity.projectId,
+    reference,
+    kind,
+    entityId,
+    actor,
+    action,
+  }).token;
+}
+
+function writerCredentialReceipt(
+  workflow: WorkflowService,
+  repo: string,
+  taskId: string,
+  actor: string,
+  token: string,
+  expiresAt: string,
+) {
+  const identity = resolveRepositoryIdentity(repo);
+  return issueCredentialReference({
+    stateRoot: workflow.store.root,
+    projectId: identity.projectId,
+    entityId: taskId,
+    actor,
+    kind: 'writer-lease',
+    token,
+    allowedActions: WRITER_CREDENTIAL_ACTIONS,
+    expiresAt,
+    oneTime: false,
+  });
+}
+
+function consumeCredentialOption(
+  workflow: WorkflowService,
+  repo: string,
+  args: ParsedArguments,
+  optionName: 'writer-credential-ref' | 'claim-credential-ref',
+): void {
+  const reference = option(args, optionName);
+  if (!reference) return;
+  consumeCredentialReference(workflow.store.root, resolveRepositoryIdentity(repo).projectId, reference);
+}
+
+async function dispatch(args: ParsedArguments): Promise<unknown> {
+  const [noun, action] = args.positionals;
+  if (args.options.has('help')) return cliHelp(args);
+  const repo = repository(args);
+
+  if (noun === 'gateway' && action === 'handshake') {
+    return gatewayHandshake();
+  }
+
+  const workflow = new WorkflowService();
+
+  if (noun === 'doctor') {
+    const identity = resolveRepositoryIdentity(repo);
+    const integration = integrationDiagnostics(identity.repositoryRoot);
+    const nodeSupported = Number(process.versions.node.split('.')[0]) >= 22;
+    return {
+      ok: nodeSupported && integration.localDependency.current,
+      node: process.versions.node,
+      requiredNode: '>=22',
+      repositoryRoot: identity.repositoryRoot,
+      projectId: identity.projectId,
+      stateRoot: workflow.store.root,
+      branch: currentBranch(identity.repositoryRoot),
+      clean: isClean(identity.repositoryRoot),
+      changedFiles: changedFiles(identity.repositoryRoot),
+      integration,
+      limitations: [
+        'CLI diagnostics cannot prove that Codex enforced a role, model, sandbox, or read-only reviewer.',
+        'MCP refresh execution is performed by the personal gateway; the core verifies returned binding evidence.',
+      ],
+    };
+  }
+  if (noun === 'status') return args.options.has('full') ? workflow.status(repo) : workflow.compactStatus(repo);
+  if (noun === 'next') return workflow.next(repo, option(args, 'task') ?? null);
+  if (noun === 'change' && action === 'explain') return workflow.explainChange(repo, required(args, 'task'), jsonFile(args));
+  if (noun === 'update' && action === 'pending-review-source-preflight') {
+    return workflow.pendingReviewUpdatePreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'update' && (action === 'pending-review-dependency-preflight' || action === 'pending-review-dependency-recover')) {
+    const receipt = JSON.parse(readFileSync(required(args, 'file'), 'utf8')) as import('./pending-review-update.js').PendingReviewUpdatePreflight | { ok: true; value: import('./pending-review-update.js').PendingReviewUpdatePreflight };
+    const source = 'value' in receipt && receipt.ok === true ? receipt.value : receipt as import('./pending-review-update.js').PendingReviewUpdatePreflight;
+    if (!source.eligible || !source.binding) throw new WorkflowError('INVALID_ARGUMENT', 'An eligible source preflight receipt is required.');
+    return action === 'pending-review-dependency-preflight'
+      ? workflow.pendingReviewDependencyPreflight(repo, required(args, 'id'), source.binding)
+      : workflow.recoverPendingReviewDependency(repo, required(args, 'id'), revision(args), source.binding, required(args, 'actor'), required(args, 'reason'));
+  }
+  if (noun === 'update' && action === 'preflight') return workflow.updatePreflight(repo);
+  if (noun === 'update' && action === 'rescue-preflight') {
+    return workflow.alpha6StrictReviewRescuePreflight(repo);
+  }
+  if (noun === 'update' && action === 'dependency-provenance-preflight') {
+    return workflow.dependencyProvenanceRecoveryPreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'update' && action === 'corrective-carryover-preflight') {
+    return workflow.correctiveCarryoverUpdatePreflight(
+      repo,
+      required(args, 'id'),
+      option(args, 'file') || option(args, 'risk-audit-file') ? {
+        plan: jsonFile<TaskPlanInput>(args),
+        planRiskAudit: jsonFile<RecordPlanRiskAuditInput>(args, 'risk-audit-file'),
+      } : null,
+    );
+  }
+  if (noun === 'task' && action === 'historical-step-provenance-preflight') {
+    return workflow.historicalStepProvenanceRecoveryPreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'task' && action === 'historical-step-provenance-recover') {
+    return workflow.recoverHistoricalStepProvenance(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'commit'),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'update' && action === 'dependency-provenance-recover') {
+    return workflow.recoverDependencyProvenance(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'update' && action === 'historical-step-dependency-preflight') {
+    return workflow.historicalStepDependencyRecoveryPreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'update' && action === 'historical-step-dependency-recover') {
+    return workflow.recoverHistoricalStepDependencyProvenance(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'update' && action === 'downstream-proof-dependency-preflight') {
+    return workflow.activeDownstreamProofDependencyRecoveryPreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'update' && action === 'downstream-proof-dependency-recover') {
+    return workflow.recoverActiveDownstreamProofDependencyProvenance(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'update' && action === 'downstream-proof-replan-update-preflight') {
+    return workflow.downstreamProofReplanUpdatePreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'update' && action === 'downstream-proof-replan-dependency-preflight') {
+    return workflow.downstreamProofReplanDependencyRecoveryPreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'update' && action === 'downstream-proof-replan-dependency-recover') {
+    return workflow.recoverDownstreamProofReplanDependencyProvenance(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'update' && action === 'plan-integrity-update-preflight') {
+    return workflow.planIntegrityUpdatePreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'update' && action === 'plan-integrity-dependency-preflight') {
+    return workflow.planIntegrityDependencyRecoveryPreflight(repo, required(args, 'id'));
+  }
+  if (noun === 'update' && action === 'plan-integrity-dependency-recover') {
+    return workflow.recoverPlanIntegrityDependencyProvenance(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'delegation' && action === 'prepare') {
+    return workflow.prepareDelegation(repo, jsonFile<DelegationPolicyInput>(args));
+  }
+  if (noun === 'delegation' && action === 'grant') {
+    return workflow.grantDelegation(
+      repo,
+      jsonFile<DelegationPolicyInput>(args),
+      required(args, 'confirmation-code'),
+    );
+  }
+  if (noun === 'delegation' && action === 'list') {
+    const identity = resolveRepositoryIdentity(repo);
+    return workflow.listDelegations(identity.projectId);
+  }
+  if (noun === 'delegation' && action === 'show') {
+    const identity = resolveRepositoryIdentity(repo);
+    return workflow.store.readDelegation(identity.projectId, required(args, 'id'));
+  }
+  if (noun === 'delegation' && action === 'revoke') {
+    return workflow.revokeDelegation(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'project-memory' && action === 'scan') return workflow.scanKnowledgeMap(repo);
+  if (noun === 'project-memory' && action === 'show') return workflow.showKnowledgeMap(repo);
+  if (noun === 'project-memory' && action === 'status') return workflow.knowledgeMapStatus(repo);
+  if (noun === 'project-memory' && action === 'approve') {
+    const input = jsonFile<{ selections: KnowledgeSelection[] }>(args);
+    if (!Array.isArray(input.selections)) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Knowledge approval file requires a selections array.');
+    }
+    return workflow.approveKnowledgeMap(
+      repo,
+      revision(args),
+      input.selections,
+      option(args, 'actor') ?? 'user',
+      option(args, 'delegation-grant') ?? null,
+    );
+  }
+  if (noun === 'project-memory' && action === 'reconcile') {
+    return workflow.reconcileKnowledgeMap(repo, revision(args));
+  }
+  if (noun === 'state' && action === 'migrate') {
+    const dryRun = option(args, 'dry-run') === 'true';
+    const snapshot = option(args, 'snapshot') === 'true';
+    if (dryRun === snapshot) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'state migrate requires exactly one of --dry-run or --snapshot.');
+    }
+    return migrateState(repo, workflow.store, dryRun, snapshot);
+  }
+  if (noun === 'state' && action === 'adoption-prepare') {
+    return workflow.prepareAdoption(repo);
+  }
+  if (noun === 'state' && action === 'adoption-apply') {
+    return workflow.applyAdoption(
+      repo,
+      required(args, 'actor'),
+      required(args, 'confirmation-code'),
+    );
+  }
+  if (noun === 'milestone' && action === 'recover') {
+    return workflow.recoverMilestoneTransactions(repo);
+  }
+  if (noun === 'graph' && action === 'prepare') {
+    return prepareGraphView(option(args, 'target') ? path.resolve(required(args, 'target')) : undefined);
+  }
+  if (noun === 'graph' && action === 'status') {
+    return workflow.graphStatus(repo, graphKind(args), graphMode(args));
+  }
+  if (noun === 'graph' && action === 'refresh-request') {
+    return workflow.graphRefreshRequest(repo, graphKind(args), graphMode(args));
+  }
+  if (noun === 'graph' && action === 'bind') {
+    const input = stdinJson<{ request: GraphRefreshRequest; evidence: GraphRefreshEvidence }>();
+    return workflow.bindGraph(repo, optionalRevision(args), input.request, input.evidence);
+  }
+  if (noun === 'graph' && action === 'fallback') {
+    return workflow.recordGraphFallback(
+      repo,
+      graphKind(args),
+      graphMode(args),
+      optionalRevision(args),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'context') {
+    const role = required(args, 'role');
+    if (role === 'worker' || role === 'scope-lead') {
+      throw new WorkflowError(
+        'INVALID_ARGUMENT',
+        role === 'worker'
+          ? 'Worker context is issued by task run together with a writer lease.'
+          : 'Scope Lead works on Discovery before Task materialization.',
+      );
+    }
+    if (!['technical-planner', 'delivery-coordinator', 'independent-reviewer'].includes(role)) {
+      throw new WorkflowError('INVALID_ARGUMENT', 'Unknown context role.');
+    }
+    return workflow.taskContext(
+      repo,
+      required(args, 'task'),
+      role as 'technical-planner' | 'delivery-coordinator' | 'independent-reviewer',
+    );
+  }
+
+  if (noun === 'discovery' && action === 'start') {
+    const outcome = option(args, 'outcome')?.trim();
+    const input: DiscoveryInput = {
+      goal: required(args, 'goal'),
+      ...(outcome ? { outcome } : {}),
+      facts: repeated(args, 'fact'),
+      decisions: repeated(args, 'decision'),
+      assumptions: repeated(args, 'assumption'),
+      unknowns: repeated(args, 'unknown'),
+      blockingUnknowns: repeated(args, 'blocking-unknown'),
+      scope: repeated(args, 'scope'),
+      outOfScope: repeated(args, 'out-of-scope'),
+      constraints: repeated(args, 'constraint'),
+      acceptance: repeated(args, 'acceptance'),
+    };
+    return workflow.startDiscovery(repo, input);
+  }
+  if (noun === 'discovery' && action === 'update') {
+    const goal = option(args, 'goal')?.trim();
+    const outcome = option(args, 'outcome')?.trim();
+    const patch: DiscoveryPatch = {
+      ...(goal ? { goal } : {}),
+      ...(outcome ? { outcome } : {}),
+      facts: repeated(args, 'fact'),
+      decisions: repeated(args, 'decision'),
+      assumptions: repeated(args, 'assumption'),
+      unknowns: repeated(args, 'unknown'),
+      blockingUnknowns: repeated(args, 'blocking-unknown'),
+      resolveUnknowns: repeated(args, 'resolve-unknown'),
+      scope: repeated(args, 'scope'),
+      outOfScope: repeated(args, 'out-of-scope'),
+      constraints: repeated(args, 'constraint'),
+      acceptance: repeated(args, 'acceptance'),
+    };
+    return workflow.updateDiscovery(repo, required(args, 'id'), revision(args), patch);
+  }
+  if (noun === 'discovery' && action === 'show') {
+    const identity = resolveRepositoryIdentity(repo);
+    return workflow.store.readDiscovery(identity.projectId, required(args, 'id'));
+  }
+  if (noun === 'discovery' && action === 'materialize') {
+    const kind = option(args, 'kind') ?? 'task';
+    if (kind === 'task') {
+      return workflow.materializeTask(
+        repo,
+        required(args, 'id'),
+        revision(args),
+        required(args, 'title'),
+        option(args, 'base') ?? 'main',
+        option(args, 'milestone') ?? null,
+      );
+    }
+    if (kind === 'milestone') {
+      return workflow.materializeMilestone(
+        repo,
+        required(args, 'id'),
+        revision(args),
+        required(args, 'title'),
+        option(args, 'base') ?? 'main',
+      );
+    }
+    throw new WorkflowError('INVALID_ARGUMENT', '--kind must be task or milestone.');
+  }
+
+  if (noun === 'task' && action === 'show') {
+    const identity = resolveRepositoryIdentity(repo);
+    return workflow.store.readTask(identity.projectId, required(args, 'id'));
+  }
+  if (noun === 'task' && action === 'replacement-materialize') {
+    return workflow.replaceSplitRequiredTask(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'discovery'),
+      positiveIntegerOption(args, 'expected-discovery-revision'),
+      positiveIntegerOption(args, 'expected-milestone-revision'),
+      required(args, 'title'),
+      option(args, 'actor') ?? 'user',
+    );
+  }
+  if (noun === 'task' && action === 'preexecution-replan') {
+    return workflow.recordPreExecutionReplan(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+      {
+        expectedBriefHash: required(args, 'expected-brief-hash'),
+        expectedPlanHash: required(args, 'expected-plan-hash'),
+        expectedPlanRiskAuditEventHash: required(args, 'expected-plan-risk-audit-event-hash'),
+        expectedHeadCommit: required(args, 'expected-head-commit'),
+      },
+      jsonFile<RecordPlanRiskAuditInput>(args),
+    );
+  }
+  if (noun === 'task' && action === 'plan-set') {
+    return workflow.setTaskPlan(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      jsonFile<TaskPlanInput>(args),
+      option(args, 'corrective-audit-file')
+        ? jsonFile<CorrectivePlanAuditInput>(args, 'corrective-audit-file')
+        : null,
+      jsonFile<RecordPlanRiskAuditInput>(args, 'risk-audit-file'),
+    );
+  }
+  if (noun === 'task' && action === 'knowledge-rebind') {
+    return workflow.rebindTaskKnowledge(repo, required(args, 'id'), revision(args));
+  }
+  if (noun === 'task' && action === 'context-refresh') {
+    return workflow.refreshTaskContext(
+      repo,
+      required(args, 'id'),
+      positiveIntegerOption(args, 'expected-task-revision'),
+      positiveIntegerOption(args, 'expected-map-revision'),
+      required(args, 'actor'),
+      required(args, 'delegation-grant'),
+    );
+  }
+  if (noun === 'task' && action === 'authorize') {
+    return workflow.authorizeTask(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      option(args, 'actor') ?? 'user',
+      option(args, 'reason') ?? '',
+      option(args, 'delegation-grant') ?? null,
+    );
+  }
+  if (noun === 'task' && action === 'plan-risk-audit') {
+    return workflow.recordPlanRiskAudit(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      jsonFile<RecordPlanRiskAuditInput>(args),
+    );
+  }
+  if (noun === 'task' && action === 'start') {
+    const owner = required(args, 'workspace-owner');
+    if (owner !== 'local' && owner !== 'external') {
+      throw new WorkflowError('INVALID_ARGUMENT', '--workspace-owner must be local or external.');
+    }
+    return workflow.startTask(repo, required(args, 'id'), revision(args), owner as WorkspaceOwner);
+  }
+  if (noun === 'task' && action === 'run') {
+    const taskId = required(args, 'id');
+    const owner = option(args, 'owner') ?? 'worker';
+    const outcome = workflow.runStep(
+      repo,
+      taskId,
+      required(args, 'step'),
+      revision(args),
+      owner,
+      credentialToken(workflow, repo, args, 'writer-lease', 'task run', taskId, owner, false),
+    );
+    const { writerToken, ...envelope } = outcome.envelope;
+    if (outcome.writerCredential.disposition === 'issued' && !writerToken) {
+      throw new WorkflowError('STATE_CORRUPT', 'Fresh task run credential issuance did not return its protocol-v1 writer token.');
+    }
+    if (outcome.writerCredential.disposition === 'renewed' && writerToken !== null) {
+      throw new WorkflowError('STATE_CORRUPT', 'Renewed task run credential unexpectedly returned a writer token.');
+    }
+    return {
+      writerCredential: { disposition: outcome.writerCredential.disposition },
+      ...(writerToken ? {
+        writerCredentialReference: writerCredentialReceipt(
+          workflow, repo, taskId, outcome.lease.owner, writerToken, outcome.lease.expiresAt,
+        ),
+      } : {}),
+      task: outcome.task,
+      lease: outcome.lease,
+      envelope,
+    };
+  }
+  if (noun === 'task' && action === 'step-complete') {
+    const taskId = required(args, 'id');
+    return workflow.completeStep(
+      repo,
+      taskId,
+      required(args, 'step'),
+      revision(args),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task step-complete', taskId, option(args, 'actor') ?? null, true)!,
+      repeated(args, 'note'),
+      option(args, 'actor'),
+    );
+  }
+  if (noun === 'task' && action === 'submit') {
+    const taskId = required(args, 'id');
+    return workflow.submitTask(
+      repo,
+      taskId,
+      revision(args),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task submit', taskId, option(args, 'actor') ?? null, true)!,
+      option(args, 'actor'),
+    );
+  }
+  if (noun === 'task' && action === 'review-record') {
+    const review = jsonFile<ReviewInput>(args);
+    return workflow.recordReview(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      review,
+      option(args, 'actor'),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task review-record', required(args, 'id'), option(args, 'actor') ?? null, false),
+    );
+  }
+  if (noun === 'task' && action === 'review-launch') {
+    const identity = resolveRepositoryIdentity(repo);
+    const id = required(args, 'id');
+    const expectedRevision = revision(args);
+    const task = workflow.store.readTask(identity.projectId, id);
+    if (task.revision !== expectedRevision) {
+      throw new WorkflowError('STATE_CONFLICT', `State revision conflict for ${id}`, {
+        expectedRevision,
+        actualRevision: task.revision,
+      });
+    }
+    const envelope = workflow.taskContext(repo, id, 'independent-reviewer');
+    const launch = launchStrictReviewer(
+      identity.repositoryRoot,
+      task,
+      workflow.store.taskRoot(task.projectId, task.id),
+      envelope,
+    );
+    // The independent reviewer identity belongs to the strict reviewer payload. CLI --actor
+    // remains the lifecycle mutation actor, such as the current C1 claimant.
+    const saved = workflow.recordReview(
+      repo,
+      id,
+      expectedRevision,
+      launch.review,
+      option(args, 'actor'),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task review-launch', id, option(args, 'actor') ?? null, false),
+    );
+    return { launch, task: saved };
+  }
+  if (noun === 'task' && action === 'review-packet') {
+    return workflow.prepareExternalTaskReview(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      reviewMode(args),
+    );
+  }
+  if (noun === 'task' && action === 'review-sealed-record') {
+    return workflow.recordExternalTaskReview(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      jsonFile<ExternalStrictTaskReviewInput>(args),
+      required(args, 'actor'),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task review-sealed-record', required(args, 'id'), required(args, 'actor'), false),
+    );
+  }
+  if (noun === 'task' && action === 'step-review') {
+    // Strict Step Review launches and records the isolated reviewer inside Core. CLI --actor
+    // remains the lifecycle actor from next, typically the active C1 claimant.
+    return workflow.reviewStep(
+      repo,
+      required(args, 'id'),
+      required(args, 'step'),
+      revision(args),
+      undefined,
+      option(args, 'actor'),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task step-review', required(args, 'id'), option(args, 'actor') ?? null, false),
+    );
+  }
+  if (noun === 'task' && action === 'step-review-packet') {
+    return workflow.prepareExternalStepReview(
+      repo,
+      required(args, 'id'),
+      required(args, 'step'),
+      revision(args),
+      reviewMode(args),
+    );
+  }
+  if (noun === 'task' && action === 'step-review-record') {
+    return workflow.recordExternalStepReview(
+      repo,
+      required(args, 'id'),
+      required(args, 'step'),
+      revision(args),
+      jsonFile<ExternalStrictStepReviewInput>(args),
+      required(args, 'actor'),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task step-review-record', required(args, 'id'), required(args, 'actor'), false),
+    );
+  }
+  if (noun === 'task' && action === 'corrective-decision-recover') {
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    return workflow.recoverStepCorrectiveDecision(
+      repo,
+      taskId,
+      required(args, 'step'),
+      revision(args),
+      actor,
+      credentialToken(workflow, repo, args, 'writer-lease', 'task corrective-decision-recover', taskId, actor, false),
+    );
+  }
+  if (noun === 'task' && action === 'remediation-mode-recover') {
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    return workflow.recoverRemediationMode(
+      repo,
+      taskId,
+      required(args, 'step'),
+      revision(args),
+      actor,
+      credentialToken(workflow, repo, args, 'writer-lease', 'task remediation-mode-recover', taskId, actor, false),
+    );
+  }
+  if (noun === 'task' && action === 'plan-integrity-recover') {
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    return workflow.recoverPlanIntegrity(
+      repo,
+      taskId,
+      required(args, 'step'),
+      revision(args),
+      actor,
+      credentialToken(workflow, repo, args, 'writer-lease', 'task plan-integrity-recover', taskId, actor, false),
+    );
+  }
+  if (noun === 'task' && action === 'downstream-proof-recover') {
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    return workflow.recoverDownstreamProof(
+      repo,
+      taskId,
+      revision(args),
+      actor,
+      credentialToken(workflow, repo, args, 'writer-lease', 'task downstream-proof-recover', taskId, actor, true)!,
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'task' && action === 'downstream-proof-replan-recover') {
+    return workflow.recoverDownstreamProofReplan(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'task' && action === 'stop-override-prepare') {
+    return workflow.prepareTaskStopOverride(
+      repo,
+      required(args, 'id'),
+      required(args, 'step'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+    );
+  }
+  if (noun === 'task' && action === 'stop-override-apply') {
+    return workflow.applyTaskStopOverride(
+      repo,
+      required(args, 'id'),
+      required(args, 'step'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'reason'),
+      required(args, 'confirmation-code'),
+    );
+  }
+  if (noun === 'task' && action === 'corrective-decision') {
+    const taskId = required(args, 'id');
+    return workflow.recordStepCorrectiveDecision(
+      repo,
+      taskId,
+      required(args, 'step'),
+      revision(args),
+      jsonFile<CorrectivePlanAuditInput>(args),
+      option(args, 'actor'),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task corrective-decision', taskId, option(args, 'actor') ?? null, false),
+    );
+  }
+  if (noun === 'task' && action === 'corrective-yield') {
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    const outcome = workflow.executeCorrectiveYield(
+      repo,
+      taskId,
+      revision(args),
+      actor,
+      credentialToken(workflow, repo, args, 'writer-lease', 'task corrective-yield', taskId, actor, true)!,
+      required(args, 'reason'),
+    );
+    consumeCredentialOption(workflow, repo, args, 'writer-credential-ref');
+    return outcome;
+  }
+  if (noun === 'task' && action === 'corrective-yield-recover') {
+    return workflow.recoverCorrectiveYield(repo, required(args, 'id'), required(args, 'transaction-id'));
+  }
+  if (noun === 'task' && action === 'corrective-replan-prepare') {
+    return workflow.prepareCorrectiveReplan(
+      repo,
+      required(args, 'id'),
+      jsonFile<CorrectiveReplanPublicCandidate>(args),
+    );
+  }
+  if (noun === 'task' && action === 'corrective-replan-confirm') {
+    return workflow.confirmCorrectiveReplan(
+      repo,
+      required(args, 'id'),
+      jsonFile<CorrectiveReplanPublicCandidate>(args),
+      jsonFile<CorrectiveReplanHumanGate>(args, 'gate-file'),
+      required(args, 'confirmation-code'),
+    );
+  }
+  if (noun === 'task' && action === 'corrective-replan-execute') {
+    return workflow.executeCorrectiveReplan(
+      repo,
+      required(args, 'id'),
+      jsonFile<CorrectiveReplanPublicCandidate>(args),
+      jsonFile<CorrectiveReplanPublicCredential>(args, 'credential-file'),
+    );
+  }
+  if (noun === 'task' && action === 'corrective-replan-recover') {
+    return workflow.recoverCorrectiveReplan(repo, required(args, 'id'), required(args, 'transaction-id'));
+  }
+  if (noun === 'task' && (action === 'handoff' || action === 'handoff-prepare' || action === 'handoff-replace')) {
+    const replacePending = action === 'handoff-replace';
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    const targetActor = replacePending
+      ? required(args, 'target-actor')
+      : option(args, 'target-actor') ?? defaultTaskWorkerActor(taskId);
+    const outcome = workflow.handoffTask(
+      repo,
+      taskId,
+      revision(args),
+      actor,
+      targetActor,
+      required(args, 'reason'),
+      credentialToken(workflow, repo, args, 'writer-lease', `task ${action}`, taskId, actor, false),
+      option(args, 'delegation-grant') ?? null,
+      option(args, 'expires-at') ?? null,
+      replacePending,
+    );
+    consumeCredentialOption(workflow, repo, args, 'writer-credential-ref');
+    const { claimToken, ...bundle } = outcome.bundle;
+    const identity = resolveRepositoryIdentity(repo);
+    return {
+      claimCredentialReference: issueCredentialReference({
+        stateRoot: workflow.store.root,
+        projectId: identity.projectId,
+        entityId: taskId,
+        actor: outcome.bundle.delegate,
+        kind: 'claim-token',
+        token: claimToken,
+        allowedActions: ['task claim'],
+        expiresAt: outcome.bundle.expiresAt,
+        oneTime: true,
+      }),
+      task: outcome.task,
+      event: outcome.event,
+      bundle,
+    };
+  }
+  if (noun === 'task' && action === 'handoff-show') {
+    return workflow.showTaskHandoff(repo, required(args, 'id'));
+  }
+  if (noun === 'task' && action === 'claim') {
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    const claimToken = credentialToken(
+      workflow, repo, args, 'claim-token', 'task claim', taskId, actor, true,
+    )!;
+    const outcome = workflow.claimTask(
+      repo,
+      taskId,
+      revision(args),
+      actor,
+      claimToken,
+      credentialToken(workflow, repo, args, 'writer-lease', 'task claim', taskId, actor, false),
+    );
+    consumeCredentialOption(workflow, repo, args, 'claim-credential-ref');
+    return {
+      writerCredential: { disposition: outcome.writerCredential.disposition },
+      ...(outcome.writerCredential.disposition === 'issued' ? {
+        writerCredentialReference: writerCredentialReceipt(
+          workflow, repo, taskId, outcome.lease.owner, outcome.writerCredential.token, outcome.lease.expiresAt,
+        ),
+      } : {}),
+      task: outcome.task,
+      event: outcome.event,
+      lease: outcome.lease,
+    };
+  }
+  if (noun === 'task' && action === 'writer-credential-replace') {
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    const outcome = workflow.replaceClaimedWriterCredential(
+      repo,
+      taskId,
+      revision(args),
+      actor,
+    );
+    return {
+      writerCredential: { disposition: outcome.writerCredential.disposition },
+      writerCredentialReference: writerCredentialReceipt(
+        workflow, repo, taskId, outcome.lease.owner, outcome.writerCredential.token, outcome.lease.expiresAt,
+      ),
+      task: outcome.task,
+      lease: outcome.lease,
+    };
+  }
+  if (noun === 'task' && (action === 'handback' || action === 'handback-create')) {
+    const taskId = required(args, 'id');
+    const actor = required(args, 'actor');
+    const outcome = workflow.handbackTask(
+      repo,
+      taskId,
+      revision(args),
+      actor,
+      required(args, 'reason'),
+      credentialToken(workflow, repo, args, 'writer-lease', `task ${action}`, taskId, actor, false),
+      repeated(args, 'limitation'),
+      action === 'handback-create'
+        ? required(args, 'recommended-next')
+        : option(args, 'recommended-next') ?? 'Coordinator reviews the terminal Task result and recorded evidence.',
+    );
+    consumeCredentialOption(workflow, repo, args, 'writer-credential-ref');
+    return outcome;
+  }
+  if (noun === 'task' && action === 'result-set') {
+    const taskId = required(args, 'id');
+    const outcome = workflow.setTaskResult(
+      repo,
+      taskId,
+      revision(args),
+      required(args, 'summary'),
+      repeated(args, 'limitation'),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task result-set', taskId, option(args, 'actor') ?? null, true)!,
+      option(args, 'actor'),
+    );
+    consumeCredentialOption(workflow, repo, args, 'writer-credential-ref');
+    return outcome;
+  }
+  if (noun === 'task' && action === 'accept') {
+    return workflow.acceptTask(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      option(args, 'actor') ?? 'user',
+      option(args, 'delegation-grant') ?? null,
+    );
+  }
+  if (noun === 'task' && action === 'sync-base') {
+    return workflow.syncTaskBase(repo, required(args, 'id'), revision(args));
+  }
+  if (noun === 'task' && action === 'merge') {
+    const taskId = required(args, 'id');
+    const outcome = workflow.mergeTask(
+      repo,
+      taskId,
+      revision(args),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task merge', taskId, option(args, 'actor') ?? null, true)!,
+      option(args, 'actor'),
+    );
+    consumeCredentialOption(workflow, repo, args, 'writer-credential-ref');
+    return outcome;
+  }
+  if (noun === 'task' && action === 'merge-confirm') {
+    const taskId = required(args, 'id');
+    const outcome = workflow.confirmExternalMerge(
+      repo,
+      taskId,
+      revision(args),
+      credentialToken(workflow, repo, args, 'writer-lease', 'task merge-confirm', taskId, option(args, 'actor') ?? null, true)!,
+      option(args, 'actor'),
+    );
+    consumeCredentialOption(workflow, repo, args, 'writer-credential-ref');
+    return outcome;
+  }
+
+  if (noun === 'milestone' && action === 'show') {
+    const identity = resolveRepositoryIdentity(repo);
+    return workflow.store.readMilestone(identity.projectId, required(args, 'id'));
+  }
+  if (noun === 'milestone' && action === 'progress') {
+    return workflow.milestoneProgress(repo, required(args, 'id'));
+  }
+  if (noun === 'milestone' && action === 'plan-set') {
+    return workflow.setMilestonePlan(repo, required(args, 'id'), revision(args), jsonFile<MilestonePlanInput>(args));
+  }
+  if (noun === 'milestone' && action === 'remediation-materialize') {
+    return workflow.materializeAuditedRemediationTask(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'task'),
+      positiveIntegerOption(args, 'expected-task-revision'),
+      jsonFile<AuditedRemediationMaterializationInput>(args),
+    );
+  }
+  if (noun === 'milestone' && action === 'scope-change-prepare') {
+    return workflow.prepareMilestoneScopeChange(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      jsonFile<MilestonePlanInput>(args),
+      required(args, 'actor'),
+    );
+  }
+  if (noun === 'milestone' && action === 'scope-change-apply') {
+    return workflow.applyMilestoneScopeChange(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      jsonFile<MilestonePlanInput>(args),
+      required(args, 'actor'),
+      required(args, 'confirmation-code'),
+    );
+  }
+  if (noun === 'milestone' && action === 'autonomy-prepare') {
+    return workflow.prepareMilestoneAutonomy(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'principal'),
+      required(args, 'delegate'),
+      required(args, 'expires-at'),
+    );
+  }
+  if (noun === 'milestone' && action === 'autonomy-grant') {
+    return workflow.grantMilestoneAutonomy(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'principal'),
+      required(args, 'delegate'),
+      required(args, 'expires-at'),
+      required(args, 'confirmation-code'),
+    );
+  }
+  if (noun === 'milestone' && action === 'autonomy-evolve') {
+    return workflow.evolveMilestonePlanAutonomously(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      jsonFile<MilestonePlanInput>(args),
+      required(args, 'actor'),
+    );
+  }
+  if (noun === 'milestone' && action === 'authorize') {
+    return workflow.authorizeMilestone(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      option(args, 'actor') ?? 'user',
+      option(args, 'reason') ?? '',
+      option(args, 'delegation-grant') ?? null,
+    );
+  }
+  if (noun === 'milestone' && action === 'validate') {
+    return workflow.validateMilestone(repo, required(args, 'id'), revision(args));
+  }
+  if (noun === 'milestone' && action === 'accept') {
+    return workflow.acceptMilestone(
+      repo,
+      required(args, 'id'),
+      revision(args),
+      required(args, 'actor'),
+      required(args, 'confirmation-code'),
+      option(args, 'delegation-grant') ?? null,
+    );
+  }
+  if (noun === 'milestone' && action === 'cancel') {
+    return workflow.cancelMilestone(repo, required(args, 'id'), revision(args), required(args, 'reason'));
+  }
+
+  if (noun === 'locks' && (action === 'inspect' || action === 'repair')) {
+    const id = required(args, 'id');
+    if (action === 'repair') return workflow.repairStaleWriterLease(repo, id);
+    const inspection = workflow.inspectWriterLease(repo, id);
+    return inspection ? { ...inspection, repaired: false } : null;
+  }
+
+  throw new WorkflowError('INVALID_ARGUMENT', 'Unknown command.', {
+    command: args.positionals.join(' '),
+    hint: 'Use doctor, status, next, update preflight, state <action>, delegation <action>, project-memory <action>, discovery <action>, task <action>, milestone <action>, or locks <action>.',
+  });
+}
+
+function credentialAllowancesForResult(
+  _args: ParsedArguments,
+  _value: unknown,
+): [] {
+  // Beta 13 has no CLI issuance allowance: the host receives reference metadata only.
+  return [];
+}
+
+function rawCredentialInputs(argv: readonly string[]): string[] {
+  const values: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]!;
+    for (const optionName of ['--writer-token', '--claim-token', '--confirmation-code']) {
+      if (argument === optionName && argv[index + 1]) values.push(argv[index + 1]!);
+      if (argument.startsWith(`${optionName}=`)) values.push(argument.slice(optionName.length + 1));
+    }
+  }
+  return [...new Set(values.filter(Boolean))];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const sensitiveInputs = rawCredentialInputs(argv);
+  try {
+    const args = parseArguments(argv);
+    assertNoLegacyCredentialArguments(new Set(args.options.keys()));
+    const value = await dispatch(args);
+    assertCliSuccessCredentialSafety(value, credentialAllowancesForResult(args, value), sensitiveInputs);
+    process.stdout.write(`${JSON.stringify({ ok: true, value }, null, 2)}\n`);
+  } catch (error) {
+    if (error instanceof UnsafeCredentialOutputError) {
+      process.stderr.write(
+        `${JSON.stringify({
+          ok: false,
+          error: {
+            code: 'STATE_CORRUPT',
+            message: error.message,
+            details: { credentialPaths: error.paths },
+          },
+        }, null, 2)}\n`,
+      );
+      process.exitCode = 2;
+      return;
+    }
+    if (error instanceof WorkflowError) {
+      process.stderr.write(
+        `${JSON.stringify({
+          ok: false,
+          error: {
+            code: error.code,
+            message: projectCliErrorMessage(error.message, sensitiveInputs),
+            details: projectCliErrorValue(error.details, sensitiveInputs),
+          },
+        }, null, 2)}\n`,
+      );
+      process.exitCode = 2;
+      return;
+    }
+    process.stderr.write(
+      `${JSON.stringify({
+        ok: false,
+        error: {
+          code: 'UNEXPECTED',
+          message: projectCliErrorMessage(error instanceof Error ? error.message : String(error), sensitiveInputs),
+        },
+      }, null, 2)}\n`,
+    );
+    process.exitCode = 1;
+  }
+}
+
+await main();