@moretea-labs/forge 1.5.0-rc.1 → 1.5.0

package/src/cli/commands/controller.ts

@@ -1,680 +0,0 @@
-import { Command } from 'commander';
-import { createHash } from 'crypto';
-import { readFileSync } from 'fs';
-import { resolve } from 'path';
-import { getAgentJob, getAgentJobEvents, getAgentJobLog, listAgentJobs } from '../agent-jobs/job-manager';
-import { archiveIssue, getIssue, inspectIssueReadiness, projectBoard, restoreIssue } from '../controller/issue-store';
-import { getControllerTimeline, getProjectProgress } from '../controller/progress';
-import { finishEditSession, finishTaskRun, type TaskReviewDecision } from '../controller/completion-orchestrator';
-import { applyCompletionDecision, completionDecisionQueues, finishCompletionBacklog, inspectCompletionBacklog, type CompletionBacklogReport, type CompletionDecisionAction } from '../controller/completion-backlog';
-import { exportControllerWorklog, parseWorklogCategory } from '../controller/worklog';
-import { inspectProjectGovernance, reconcileProjectGovernance } from '../controller/governance';
-import { prepareCodexContinuation } from '../controller/codex-continuation';
-import { applyStuckStateMigration, inspectStuckControllerStates } from '../controller/stuck-state-migration';
-import { assessWorkMode } from '../controller/work-mode';
-import { runControllerCheck, snapshotControllerCheck } from '../controller/check-runner';
-import { finalizeEditSession, getEditSession, getEditSessionDiff, listEditSessions, rollbackEditSession, verifyEditSession } from '../editing/edit-session';
-import { loadControllerProjectState, saveControllerProjectState } from '../controller/project-state';
-import { closeIssueWithGitHubPlugin, getGitHubPluginStatus, publishIssueWithGitHubPlugin, refreshIssueWithGitHubPlugin, saveGitHubPluginConfig } from '../github/plugin';
-import { getGitHubStatus } from '../github/github';
-import { repositoryChangeVerify } from '../controller/composite-operations';
-import { executeLocalBridgeJob } from '../local-bridge/job-store';
-
-const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
-
-function output(value: unknown, json = false): void {
-  if (json) console.log(JSON.stringify(value, null, 2));
-  else console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
-}
-
-function repoRoot(value?: string): string {
-  return resolve(value ?? process.cwd());
-}
-
-function formatBoard(board: ReturnType<typeof projectBoard>): string {
-  const lines = ['forge Controller board', ''];
-  const counts = Object.entries(board.counts).sort(([a], [b]) => a.localeCompare(b));
-  lines.push(`Tasks: ${counts.length ? counts.map(([status, count]) => `${status}=${count}`).join('  ') : 'none'}`);
-  lines.push('');
-  for (const issue of board.issues) {
-    lines.push(`${issue.id}  [${issue.status}]  ${issue.title}${issue.github && typeof issue.github === 'object' && 'url' in issue.github ? `\n  GitHub: ${String((issue.github as { url: unknown }).url)}` : ''}`);
-    const tasks = Array.isArray(issue.tasks) ? issue.tasks as Array<Record<string, unknown>> : [];
-    for (const task of tasks) {
-      const runIds = Array.isArray(task.runIds) ? task.runIds : [];
-      lines.push(`  ${String(task.id)}  [${String(task.status)}]  ${String(task.title)}  agent=${String(task.agent)}${runIds.length ? `  run=${String(runIds.at(-1))}` : ''}`);
-    }
-  }
-  return lines.join('\n');
-}
-
-function formatRuns(runs: ReturnType<typeof listAgentJobs>): string {
-  if (runs.length === 0) return 'No controller Runs.';
-  return runs.map((run) => [
-    `${run.runId}  [${run.status}]  ${run.agent}/${run.provider}`,
-    `  ${run.issueId}/${run.taskId}`,
-    ...(run.github?.url ? [`  Session: ${run.github.url}`] : []),
-    ...(run.github?.pullRequestUrl ? [`  Pull request: ${run.github.pullRequestUrl}`] : []),
-    ...(run.error ? [`  Error: ${run.error}`] : []),
-  ].join('\n')).join('\n\n');
-}
-
-
-function formatCompletionBacklog(report: CompletionBacklogReport): string {
-  const lines = ['forge Completion backlog', ''];
-  lines.push(`Scanned: ${report.scannedAt}`);
-  lines.push(`Counts: ${Object.entries(report.counts).map(([key, count]) => `${key}=${count}`).join('  ')}`);
-  if (report.recommendations.length) {
-    lines.push('', 'Recommendations:');
-    for (const recommendation of report.recommendations) lines.push(`  - ${recommendation}`);
-  }
-  const actionable = report.items.filter((item) => item.action !== 'already_terminal');
-  if (actionable.length) {
-    lines.push('', 'Items:');
-    for (const item of actionable) {
-      lines.push(`  ${item.issueId}/${item.taskId}  [${item.action}]  task=${item.taskStatus}${item.runStatus ? ` run=${item.runStatus}` : ''}${item.runId ? ` ${item.runId}` : ''}`);
-      lines.push(`    ${item.reason}`);
-    }
-  }
-  return lines.join('\n');
-}
-
-async function watchRun(root: string, runId: string, intervalSeconds: number, includeLog: boolean, json: boolean): Promise<void> {
-  let eventCount = -1;
-  let lastStatus = '';
-  let previousLog = '';
-  let logHeaderPrinted = false;
-  let lastLogError = '';
-  while (true) {
-    const run = getAgentJob(root, runId);
-    const events = getAgentJobEvents(root, runId, 1000);
-    if (json) {
-      output({ run, events: events.slice(Math.max(0, eventCount)) }, true);
-    } else if (run.status !== lastStatus || events.length !== eventCount) {
-      console.log(`[${new Date().toISOString()}] ${run.runId} status=${run.status} provider=${run.provider}`);
-      for (const event of events.slice(Math.max(0, eventCount))) {
-        console.log(`  ${event.at}  ${event.type}${event.message ? `  ${event.message}` : ''}`);
-      }
-      if (run.github?.url) console.log(`  Session: ${run.github.url}`);
-      if (run.github?.pullRequestUrl) console.log(`  Pull request: ${run.github.pullRequestUrl}`);
-      if (run.error) console.log(`  Error: ${run.error}`);
-    }
-
-    if (includeLog && !json) {
-      try {
-        const currentLog = getAgentJobLog(root, runId, false).log;
-        if (currentLog !== previousLog) {
-          const addition = currentLog.startsWith(previousLog) ? currentLog.slice(previousLog.length) : currentLog;
-          if (addition) {
-            if (!logHeaderPrinted) {
-              console.log('\n--- Live Run log ---');
-              logHeaderPrinted = true;
-            } else if (!currentLog.startsWith(previousLog)) {
-              console.log('\n[forge] log window reset; showing current retained output');
-            }
-            process.stdout.write(addition.endsWith('\n') ? addition : `${addition}\n`);
-          }
-          previousLog = currentLog;
-        }
-        lastLogError = '';
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message !== lastLogError) {
-          console.log(`  Log not available yet: ${message}`);
-          lastLogError = message;
-        }
-      }
-    }
-
-    eventCount = events.length;
-    lastStatus = run.status;
-    if (TERMINAL.has(run.status)) return;
-    await new Promise((resolvePromise) => setTimeout(resolvePromise, Math.max(1, intervalSeconds) * 1000));
-  }
-}
-
-export function buildControllerCommand(): Command {
-  const command = new Command('controller').description('Inspect forge Issues, Tasks, local Runs, and GitHub cloud sessions');
-
-  command.command('board')
-    .description('Show the durable Issue and Task board')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; json?: boolean }) => {
-      const board = projectBoard(repoRoot(opts.repo));
-      output(opts.json ? board : formatBoard(board), opts.json === true);
-    });
-
-  command.command('runs')
-    .description('List recent local and GitHub cloud Runs')
-    .option('--repo <path>', 'Repository root')
-    .option('--limit <count>', 'Maximum Runs', '25')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; limit?: string; json?: boolean }) => {
-      const runs = listAgentJobs(repoRoot(opts.repo), Math.max(1, Number(opts.limit ?? 25)));
-      output(opts.json ? { runs } : formatRuns(runs), opts.json === true);
-    });
-
-  command.command('watch')
-    .description('Follow one local Run or GitHub Copilot cloud session until it reaches a terminal state')
-    .argument('<run-id>', 'Controller Run ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--interval <seconds>', 'Polling interval', '2')
-    .option('--log', 'Print the final local or GitHub session log')
-    .option('--json', 'Output JSON snapshots')
-    .action(async (runId: string, opts: { repo?: string; interval?: string; log?: boolean; json?: boolean }) => {
-      await watchRun(repoRoot(opts.repo), runId, Number(opts.interval ?? 2), opts.log === true, opts.json === true);
-    });
-
-  command.command('assess')
-    .description('Choose direct_edit, quick_agent, or issue_task for one work request')
-    .argument('<description>', 'Work request description')
-    .option('--repo <path>', 'Repository root')
-    .option('--path <path...>', 'Known target paths')
-    .option('--expected-files <count>', 'Estimated file count')
-    .option('--expected-lines <count>', 'Estimated changed lines')
-    .option('--investigation', 'Root-cause investigation is required')
-    .option('--parallel', 'Parallel work is required')
-    .option('--long-checks', 'Long-running verification is required')
-    .option('--dependencies', 'A durable Task dependency graph is required')
-    .option('--mode <mode>', 'Explicit mode: direct, plan, debug, review, campaign, release, or scale')
-    .option('--risk <risk>', 'readonly, low, medium, high, or destructive', 'low')
-    .option('--json', 'Output JSON')
-    .action((description: string, opts: { path?: string[]; expectedFiles?: string; expectedLines?: string; investigation?: boolean; parallel?: boolean; longChecks?: boolean; dependencies?: boolean; mode?: 'direct' | 'plan' | 'debug' | 'review' | 'campaign' | 'release' | 'scale'; risk?: 'readonly' | 'low' | 'medium' | 'high' | 'destructive'; json?: boolean }) => {
-      const result = assessWorkMode({
-        description,
-        knownPaths: opts.path,
-        expectedFiles: opts.expectedFiles ? Number(opts.expectedFiles) : undefined,
-        expectedChangedLines: opts.expectedLines ? Number(opts.expectedLines) : undefined,
-        requiresInvestigation: opts.investigation,
-        requiresParallelism: opts.parallel,
-        requiresLongRunningChecks: opts.longChecks,
-        needsDependencies: opts.dependencies,
-        explicitMode: opts.mode,
-        risk: opts.risk,
-      });
-      output(result, opts.json === true);
-    });
-
-  command.command('edits')
-    .description('List direct-edit sessions and their file/check evidence')
-    .option('--repo <path>', 'Repository root')
-    .option('--limit <count>', 'Maximum sessions', '50')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; limit?: string; json?: boolean }) => {
-      const sessions = listEditSessions(repoRoot(opts.repo), Number(opts.limit ?? 50));
-      if (opts.json) return output({ sessions }, true);
-      output(sessions.length ? sessions.map((session) => `${session.sessionId}  [${session.status}]  ${session.changedFiles} files / ${session.changedLines} lines / ${session.checksPassed}/${session.checksTotal} checks\n  ${session.purpose}`).join('\n\n') : 'No direct-edit sessions.');
-    });
-
-  command.command('edit')
-    .description('Show one direct-edit session')
-    .argument('<session-id>', 'Edit session ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((sessionId: string, opts: { repo?: string; json?: boolean }) => output(getEditSession(repoRoot(opts.repo), sessionId), opts.json === true));
-
-  command.command('edit-diff')
-    .description('Print the persisted patch for one direct-edit session')
-    .argument('<session-id>', 'Edit session ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((sessionId: string, opts: { repo?: string; json?: boolean }) => {
-      const result = getEditSessionDiff(repoRoot(opts.repo), sessionId);
-      output(opts.json ? result : result.patch || '(no patch)', opts.json === true);
-    });
-
-  command.command('verify-edit')
-    .description('Run named checks and record review evidence for a direct edit')
-    .argument('<session-id>', 'Edit session ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--check <id...>', 'Override named checks')
-    .option('--reviewer <name>', 'Reviewer identity', 'controller-cli-human')
-    .option('--note <text>', 'Review note')
-    .option('--json', 'Output JSON')
-    .action((sessionId: string, opts: { repo?: string; check?: string[]; reviewer?: string; note?: string; json?: boolean }) => output(verifyEditSession(repoRoot(opts.repo), sessionId, { checkIds: opts.check, reviewer: opts.reviewer, note: opts.note }), opts.json === true));
-
-  command.command('finalize-edit')
-    .description('Finalize a verified direct edit')
-    .argument('<session-id>', 'Edit session ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--reviewer <name>', 'Reviewer identity', 'controller-cli-human')
-    .option('--note <text>', 'Final note')
-    .option('--json', 'Output JSON')
-    .action((sessionId: string, opts: { repo?: string; reviewer?: string; note?: string; json?: boolean }) => output(finalizeEditSession(repoRoot(opts.repo), sessionId, { reviewer: opts.reviewer, note: opts.note }), opts.json === true));
-
-  command.command('finish-edit')
-    .description('Verify, finalize, commit, receipt, and complete one direct-edit Task session')
-    .argument('<session-id>', 'Edit session ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--decision <decision>', 'auto, approve_and_finish, request_changes, or discard', 'auto')
-    .option('--reviewer <name>', 'Reviewer identity')
-    .option('--note <text>', 'Review note')
-    .option('--check <id...>', 'Additional named checks')
-    .option('--no-commit', 'Do not create the required selected-path Git commit after successful finish')
-    .option('--json', 'Output JSON')
-    .action((sessionId: string, opts: { repo?: string; decision?: string; reviewer?: string; note?: string; check?: string[]; commit?: boolean; json?: boolean }) => {
-      const decision = String(opts.decision ?? 'auto').replace(/-/g, '_') as TaskReviewDecision;
-      if (!['auto', 'approve_and_finish', 'request_changes', 'discard'].includes(decision)) {
-        throw new Error('decision must be auto, approve_and_finish, request_changes, or discard');
-      }
-      output(finishEditSession(repoRoot(opts.repo), {
-        sessionId,
-        decision,
-        reviewer: opts.reviewer,
-        note: opts.note,
-        checkIds: opts.check,
-        commit: opts.commit !== false,
-      }), opts.json === true);
-    });
-
-  command.command('rollback-edit')
-    .description('Rollback a non-finalized direct edit')
-    .argument('<session-id>', 'Edit session ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((sessionId: string, opts: { repo?: string; json?: boolean }) => output(rollbackEditSession(repoRoot(opts.repo), sessionId), opts.json === true));
-
-  command.command('finish-run')
-    .description('Finish one reviewed Run: integrate if needed, verify, accept when policy allows, and clean the isolated worktree')
-    .argument('<run-id>', 'Controller Run ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--decision <decision>', 'auto, approve_and_finish, request_changes, or discard', 'auto')
-    .option('--reviewer <name>', 'Reviewer identity')
-    .option('--note <text>', 'Review note')
-    .option('--keep-worktree', 'Do not remove the isolated worktree after integration')
-    .option('--no-commit', 'Do not create the required selected-path Git commit after successful finish')
-    .option('--json', 'Output JSON')
-    .action((runId: string, opts: { repo?: string; decision?: string; reviewer?: string; note?: string; keepWorktree?: boolean; commit?: boolean; json?: boolean }) => {
-      const decision = String(opts.decision ?? 'auto').replace(/-/g, '_') as TaskReviewDecision;
-      if (!['auto', 'approve_and_finish', 'request_changes', 'discard'].includes(decision)) {
-        throw new Error('decision must be auto, approve_and_finish, request_changes, or discard');
-      }
-      const finished = finishTaskRun(repoRoot(opts.repo), {
-        runId,
-        decision,
-        reviewer: opts.reviewer,
-        note: opts.note,
-        cleanup: opts.keepWorktree !== true,
-        commit: opts.commit !== false,
-      });
-      output(finished, opts.json === true);
-    });
-
-  command.command('completion-backlog')
-    .description('Show finishable Runs, human-review items, retry-required Tasks, and stale review states')
-    .option('--repo <path>', 'Repository root')
-    .option('--include-terminal', 'Include terminal done/cancelled/superseded Tasks')
-    .option('--limit <count>', 'Maximum items', '500')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; includeTerminal?: boolean; limit?: string; json?: boolean }) => {
-      const report = inspectCompletionBacklog(repoRoot(opts.repo), {
-        includeTerminal: opts.includeTerminal === true,
-        limit: opts.limit ? Number(opts.limit) : undefined,
-      });
-      output(opts.json ? report : formatCompletionBacklog(report), opts.json === true);
-    });
-
-  command.command('finish-ready-runs')
-    .description('Batch-finish low/medium completed Runs; dry-run by default and never approves high-risk work')
-    .option('--repo <path>', 'Repository root')
-    .option('--apply', 'Apply the auto-finish actions instead of dry-running')
-    .option('--limit <count>', 'Maximum auto-finish Runs', '25')
-    .option('--keep-worktree', 'Do not remove isolated worktrees after integration')
-    .option('--no-commit', 'Do not create selected-path Git commits after successful finishes')
-    .option('--reviewer <name>', 'Reviewer identity', 'forge-completion-backlog')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; apply?: boolean; limit?: string; keepWorktree?: boolean; commit?: boolean; reviewer?: string; json?: boolean }) => {
-      const finished = finishCompletionBacklog(repoRoot(opts.repo), {
-        dryRun: opts.apply !== true,
-        limit: opts.limit ? Number(opts.limit) : undefined,
-        cleanup: opts.keepWorktree !== true,
-        commit: opts.commit !== false,
-        reviewer: opts.reviewer,
-      });
-      output(finished, opts.json === true);
-      if (!opts.json && finished.dryRun && finished.attempted > 0) {
-        console.log('Dry run only. Re-run with --apply to finish these low/medium Runs.');
-      }
-    });
-
-  command.command('completion-queues')
-    .description('Show Local-Bridge-friendly completion decision queues')
-    .option('--repo <path>', 'Repository root')
-    .option('--include-terminal', 'Include terminal done/cancelled/superseded Tasks')
-    .option('--limit <count>', 'Maximum items', '500')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; includeTerminal?: boolean; limit?: string; json?: boolean }) => {
-      const queues = completionDecisionQueues(repoRoot(opts.repo), {
-        includeTerminal: opts.includeTerminal === true,
-        limit: opts.limit ? Number(opts.limit) : undefined,
-      });
-      output(queues, opts.json === true);
-    });
-
-  command.command('completion-decision')
-    .description('Apply one explicit completion decision from the queue')
-    .option('--repo <path>', 'Repository root')
-    .requiredOption('--action <action>', 'finish, approve_and_finish, request_changes, discard, mark_inspected, or retry_later')
-    .option('--run-id <runId>', 'Run ID for run decisions')
-    .option('--issue-id <issueId>', 'Issue ID for task decisions')
-    .option('--task-id <taskId>', 'Task ID for task decisions')
-    .option('--reviewer <name>', 'Reviewer identity', 'forge-completion-decision')
-    .option('--note <text>', 'Decision note')
-    .option('--keep-worktree', 'Do not remove isolated worktrees after integration')
-    .option('--no-commit', 'Do not create the required selected-path Git commit after finish')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; action: string; runId?: string; issueId?: string; taskId?: string; reviewer?: string; note?: string; keepWorktree?: boolean; commit?: boolean; json?: boolean }) => {
-      const action = String(opts.action ?? '').replace(/-/g, '_') as CompletionDecisionAction;
-      if (!['finish', 'approve_and_finish', 'request_changes', 'discard', 'mark_inspected', 'retry_later'].includes(action)) {
-        throw new Error('action must be finish, approve_and_finish, request_changes, discard, mark_inspected, or retry_later');
-      }
-      output(applyCompletionDecision(repoRoot(opts.repo), {
-        action,
-        runId: opts.runId,
-        issueId: opts.issueId,
-        taskId: opts.taskId,
-        reviewer: opts.reviewer,
-        note: opts.note,
-        cleanup: opts.keepWorktree !== true,
-        commit: opts.commit !== false,
-      }), opts.json === true);
-    });
-
-  command.command('stuck-states')
-    .description('Inspect stale review, retry-required, missing-run, and blocked completion states')
-    .option('--repo <path>', 'Repository root')
-    .option('--limit <count>', 'Maximum findings', '500')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; limit?: string; json?: boolean }) => {
-      output(inspectStuckControllerStates(repoRoot(opts.repo), { limit: opts.limit ? Number(opts.limit) : undefined }), opts.json === true);
-    });
-
-  command.command('migrate-stuck-states')
-    .description('Safely annotate stale completion states; dry-run by default')
-    .option('--repo <path>', 'Repository root')
-    .option('--apply', 'Apply note-only migration actions')
-    .option('--limit <count>', 'Maximum findings', '100')
-    .option('--mark-retry-required', 'Move retry-required findings to changes_requested')
-    .option('--mark-no-run-evidence', 'Move stale review/running without run evidence to changes_requested')
-    .option('--reviewer <name>', 'Reviewer identity', 'forge-stuck-state-migration')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; apply?: boolean; limit?: string; markRetryRequired?: boolean; markNoRunEvidence?: boolean; reviewer?: string; json?: boolean }) => {
-      output(applyStuckStateMigration(repoRoot(opts.repo), {
-        dryRun: opts.apply !== true,
-        limit: opts.limit ? Number(opts.limit) : undefined,
-        reviewer: opts.reviewer,
-        markRetryRequired: opts.markRetryRequired === true,
-        markNoRunEvidence: opts.markNoRunEvidence === true,
-      }), opts.json === true);
-    });
-
-  command.command('codex-continuation')
-    .description('Prepare a Codex continuation packet; provider startup belongs to Thin Launcher')
-    .option('--repo <path>', 'Repository root')
-    .option('--objective <text>', 'Continuation objective')
-    .option('--max-items <count>', 'Maximum backlog/stuck items', '100')
-    .option('--launch', 'Deprecated: returns a Thin Launcher migration instruction')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; objective?: string; maxItems?: string; launch?: boolean; json?: boolean }) => {
-      output(prepareCodexContinuation(repoRoot(opts.repo), {
-        objective: opts.objective,
-        maxItems: opts.maxItems ? Number(opts.maxItems) : undefined,
-        mode: opts.launch === true ? 'launch' : 'prepare',
-      }), opts.json === true);
-    });
-
-  command.command('progress')
-    .description('Show project, Issue, and Task progress derived from durable controller state')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; json?: boolean }) => {
-      const progress = getProjectProgress(repoRoot(opts.repo));
-      if (opts.json) return output(progress, true);
-      const lines = [
-        `Evidence gates: ${progress.completedGates}/${progress.totalGates} complete`,
-        `Current Issue: ${progress.currentIssueId ?? 'not selected'}`,
-        `Issues: ${progress.activeIssueCount} active / ${progress.archivedIssueCount} archived / ${progress.issueCount} total`,
-        `Tasks: ${progress.completedTaskCount} accepted / ${progress.taskCount} total`,
-        `Active Runs: ${progress.activeRunCount}`,
-        '',
-        ...progress.issues.map((issue) => `${issue.id}  ${issue.completedGates}/${issue.totalGates} gates  [${issue.status}]  ${issue.title}${issue.isCurrent ? '  CURRENT' : ''}${issue.attentionCount ? `  attention=${issue.attentionCount}` : ''}`),
-      ];
-      output(lines.join('\n'));
-    });
-
-  command.command('governance')
-    .description('Inspect execution focus, dead dependencies, retryable failures, review/acceptance backlog, duplicates, and closeout anomalies')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; json?: boolean }) => {
-      const result = inspectProjectGovernance(repoRoot(opts.repo));
-      if (opts.json) return output(result, true);
-      const lines = [
-        `Governance: ${result.health}`,
-        `Current Issue: ${result.currentIssueId ?? 'not selected'}`,
-        `Execution queue: ${result.executionQueue.length}`,
-        `Findings: critical=${result.counts.critical ?? 0} warning=${result.counts.warning ?? 0} info=${result.counts.info ?? 0}`,
-        '',
-        ...result.findings.map((entry) => `${entry.severity.toUpperCase()}  ${entry.code}  ${[entry.issueId, entry.taskId].filter(Boolean).join('/')}\n  ${entry.message}`),
-      ];
-      output(lines.join('\n'));
-    });
-
-  command.command('reconcile')
-    .description('Apply safe project-governance repairs and refresh the execution queue')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; json?: boolean }) => output(reconcileProjectGovernance(repoRoot(opts.repo)), opts.json === true));
-
-  command.command('focus')
-    .description('Select an informational primary Issue without blocking other Tasks')
-    .argument('<issue-id>', 'Controller Issue ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((issueId: string, opts: { repo?: string; json?: boolean }) => {
-      const root = repoRoot(opts.repo);
-      const issue = getIssue(root, issueId);
-      if (issue.archivedAt || ['done', 'cancelled'].includes(issue.status)) throw new Error(`Issue is not active: ${issue.status}`);
-      output(saveControllerProjectState(root, { currentIssueId: issue.id }, 'controller-cli'), opts.json === true);
-    });
-
-  command.command('launch')
-    .description('Deprecated: prepare Task-local launch candidates for an external SuperController')
-    .argument('<issue-id>', 'Controller Issue ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--max-parallel <count>', 'Maximum Tasks to launch', '1')
-    .option('--timeout-ms <milliseconds>', 'Agent timeout')
-    .option('--json', 'Output JSON')
-    .action((issueId: string, opts: { repo?: string; maxParallel?: string; timeoutMs?: string; json?: boolean }) => {
-      const root = repoRoot(opts.repo);
-      const readiness = inspectIssueReadiness(root, issueId);
-      if (!readiness.queueable) throw new Error(`Issue has no queueable Tasks: ${[...readiness.blockers, ...readiness.taskBlockers].map((entry) => entry.code).join(', ') || 'no queueable Tasks'}`);
-      output({
-        accepted: false,
-        code: 'LOCAL_BRIDGE_JOB_RETIRED',
-        readiness,
-        message: 'controller launch no longer creates Local Bridge Jobs. Create or claim WorkContract and start an external Controller through the Thin Launcher.',
-      }, opts.json === true);
-    });
-
-  command.command('archive')
-    .description('Archive a done or cancelled Issue')
-    .argument('<issue-id>', 'Controller Issue ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((issueId: string, opts: { repo?: string; json?: boolean }) => output(archiveIssue(repoRoot(opts.repo), issueId), opts.json === true));
-
-  command.command('restore')
-    .description('Restore an archived Issue')
-    .argument('<issue-id>', 'Controller Issue ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((issueId: string, opts: { repo?: string; json?: boolean }) => output(restoreIssue(repoRoot(opts.repo), issueId), opts.json === true));
-
-  command.command('policy')
-    .description('Read or update Controller execution policy')
-    .option('--repo <path>', 'Repository root')
-    .option('--issue-creation-mode <mode>', 'open, focus_only, or paused')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; issueCreationMode?: string; json?: boolean }) => {
-      const root = repoRoot(opts.repo);
-      const mode = opts.issueCreationMode;
-      if (mode && !['open', 'focus_only', 'paused'].includes(mode)) throw new Error('issue creation mode must be open, focus_only, or paused');
-      const result = mode ? saveControllerProjectState(root, { issueCreationMode: mode as 'open' | 'focus_only' | 'paused' }, 'controller-cli') : loadControllerProjectState(root);
-      output(result, opts.json === true);
-    });
-
-  command.command('timeline')
-    .description('Show the unified controller worklog and Run timeline')
-    .option('--repo <path>', 'Repository root')
-    .option('--issue <id>', 'Filter by Issue ID')
-    .option('--task <id>', 'Filter by Task ID')
-    .option('--run <id>', 'Filter by Run ID')
-    .option('--category <name>', 'Filter by category')
-    .option('--limit <count>', 'Maximum events', '100')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; issue?: string; task?: string; run?: string; category?: string; limit?: string; json?: boolean }) => {
-      const events = getControllerTimeline(repoRoot(opts.repo), {
-        issueId: opts.issue,
-        taskId: opts.task,
-        runId: opts.run,
-        category: parseWorklogCategory(opts.category),
-        limit: Math.max(1, Number(opts.limit ?? 100)),
-      });
-      if (opts.json) return output({ events }, true);
-      output(events.map((event) => `${event.at}  ${event.category}/${event.action}  ${[event.issueId, event.taskId, event.runId].filter(Boolean).join('/')}
-  ${event.summary}`).join('\n'));
-    });
-
-  command.command('export-worklog')
-    .description('Export the controller worklog to a tracked Markdown or JSON report')
-    .option('--repo <path>', 'Repository root')
-    .option('--format <format>', 'markdown or json', 'markdown')
-    .option('--output <path>', 'Repository-relative output path')
-    .option('--issue <id>', 'Filter by Issue ID')
-    .option('--task <id>', 'Filter by Task ID')
-    .option('--run <id>', 'Filter by Run ID')
-    .option('--json', 'Output command result as JSON')
-    .action((opts: { repo?: string; format?: string; output?: string; issue?: string; task?: string; run?: string; json?: boolean }) => {
-      const result = exportControllerWorklog(repoRoot(opts.repo), {
-        format: opts.format === 'json' ? 'json' : 'markdown',
-        outputPath: opts.output,
-        filter: { issueId: opts.issue, taskId: opts.task, runId: opts.run },
-      });
-      output(opts.json ? result : `Exported ${result.eventCount} events to ${result.path}`, opts.json === true);
-    });
-
-  const githubPlugin = command.command('github')
-    .description('Configure and use the optional GitHub Issue/Project plugin');
-
-  githubPlugin.command('status')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; json?: boolean }) => output(getGitHubPluginStatus(repoRoot(opts.repo)), opts.json === true));
-
-  githubPlugin.command('configure')
-    .option('--repo <path>', 'Repository root')
-    .option('--enable', 'Enable the plugin')
-    .option('--disable', 'Disable the plugin')
-    .option('--github-repo <owner/repo>', 'Explicit GitHub repository')
-    .option('--clear-repository', 'Clear the configured GitHub repository')
-    .option('--sync-mode <mode>', 'manual or checkpoint')
-    .option('--include-tasks', 'Mirror Tasks as GitHub sub-issues')
-    .option('--exclude-tasks', 'Do not mirror Tasks')
-    .option('--project-owner <owner>', 'GitHub Project owner')
-    .option('--project-number <number>', 'GitHub Project number')
-    .option('--clear-project', 'Clear GitHub Project owner and number')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; enable?: boolean; disable?: boolean; githubRepo?: string; clearRepository?: boolean; syncMode?: string; includeTasks?: boolean; excludeTasks?: boolean; projectOwner?: string; projectNumber?: string; clearProject?: boolean; json?: boolean }) => {
-      if (opts.enable && opts.disable) throw new Error('choose either --enable or --disable');
-      if (opts.includeTasks && opts.excludeTasks) throw new Error('choose either --include-tasks or --exclude-tasks');
-      const config = saveGitHubPluginConfig(repoRoot(opts.repo), {
-        enabled: opts.enable ? true : opts.disable ? false : undefined,
-        repository: opts.clearRepository ? '' : opts.githubRepo,
-        syncMode: opts.syncMode === 'checkpoint' ? 'checkpoint' : opts.syncMode === 'manual' ? 'manual' : undefined,
-        includeTasks: opts.includeTasks ? true : opts.excludeTasks ? false : undefined,
-        projectOwner: opts.clearProject ? '' : opts.projectOwner,
-        projectNumber: opts.clearProject ? null : opts.projectNumber ? Number(opts.projectNumber) : undefined,
-      });
-      output(config, opts.json === true);
-    });
-
-  githubPlugin.command('publish')
-    .argument('<issue-id>', 'Controller Issue ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((issueId: string, opts: { repo?: string; json?: boolean }) => output(publishIssueWithGitHubPlugin(repoRoot(opts.repo), issueId), opts.json === true));
-
-  githubPlugin.command('refresh')
-    .argument('<issue-id>', 'Controller Issue ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((issueId: string, opts: { repo?: string; json?: boolean }) => output(refreshIssueWithGitHubPlugin(repoRoot(opts.repo), issueId), opts.json === true));
-
-  githubPlugin.command('close')
-    .argument('<issue-id>', 'Controller Issue ID')
-    .option('--repo <path>', 'Repository root')
-    .option('--json', 'Output JSON')
-    .action((issueId: string, opts: { repo?: string; json?: boolean }) => output(closeIssueWithGitHubPlugin(repoRoot(opts.repo), issueId), opts.json === true));
-
-  command.command('github-status')
-    .description('Check gh authentication, repository resolution, Projects access prerequisites, and Copilot agent-task CLI support')
-    .option('--repo <path>', 'Repository root')
-    .option('--github-repo <owner/repo>', 'Explicit GitHub repository')
-    .option('--clear-repository', 'Clear the configured GitHub repository')
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; githubRepo?: string; json?: boolean }) => {
-      output(getGitHubStatus(repoRoot(opts.repo), opts.githubRepo), opts.json === true);
-    });
-
-
-  command.command('change-verify')
-    .description('Composite: verify checkout, apply bounded patch, run checks, return first failure inline')
-    .option('--repo <path>', 'Repository root')
-    .option('--branch <name>', 'Expected branch')
-    .option('--head <sha>', 'Expected HEAD')
-    .option('--patch-file <path>', 'Unified diff to apply')
-    .option('--check <id>', 'Check id to run (repeatable)', (value, previous: string[]) => [...previous, value], [])
-    .option('--json', 'Output JSON')
-    .action((opts: { repo?: string; branch?: string; head?: string; patchFile?: string; check?: string[]; json?: boolean }) => {
-      const patch = opts.patchFile ? readFileSync(opts.patchFile, 'utf8') : undefined;
-      const result = repositoryChangeVerify({
-        repo: opts.repo,
-        expectedBranch: opts.branch,
-        expectedHead: opts.head,
-        patch,
-        checks: opts.check,
-      });
-      output(result, opts.json === true);
-      if (result.status === 'failed') process.exitCode = 1;
-    });
-
-
-  command.command('run-check-process', { hidden: true })
-    .description('Internal persisted check process entry')
-    .requiredOption('--repo <path>', 'Repository root')
-    .requiredOption('--check-id <id>', 'Registered check id')
-    .option('--timeout-ms <ms>', 'Bounded check timeout')
-    .requiredOption('--expected-check-fingerprint <sha256>', 'Expected non-secret check snapshot fingerprint')
-    .action((opts: { repo: string; checkId: string; timeoutMs?: string; expectedCheckFingerprint: string }) => {
-      const requestedTimeout = opts.timeoutMs === undefined ? undefined : Number(opts.timeoutMs);
-      if (requestedTimeout !== undefined && (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0)) {
-        throw new Error('invalid --timeout-ms');
-      }
-      const root = repoRoot(opts.repo);
-      const snapshot = snapshotControllerCheck(root, opts.checkId);
-      const actualFingerprint = createHash('sha256')
-        .update(JSON.stringify(snapshot))
-        .digest('hex');
-      if (actualFingerprint !== opts.expectedCheckFingerprint) {
-        throw new Error('CHECK_SNAPSHOT_CHANGED: registered check changed before Process Runtime execution');
-      }
-      const result = runControllerCheck(root, opts.checkId, requestedTimeout, snapshot);
-      if (result.stdout) process.stdout.write(result.stdout);
-      if (result.stderr) process.stderr.write(result.stderr.endsWith('\n') ? result.stderr : `${result.stderr}\n`);
-      process.exitCode = result.ok ? 0 : Math.max(1, result.status || 1);
-    });
-
-
-  return command;
-}