switchman-dev 0.1.8 → 0.1.9

package/src/cli/index.js

@@ -19,10 +19,10 @@
 import { Help, program } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { dirname, join, posix } from 'path';
-import { execSync, spawn } from 'child_process';
+import { execSync, spawn, spawnSync } from 'child_process';
 
 import { cleanupCrashedLandingTempWorktrees, createGitWorktree, findRepoRoot, getWorktreeBranch, getWorktreeChangedFiles, gitAssessBranchFreshness, gitBranchExists, listGitWorktrees } from '../core/git.js';
 import { matchesPathPatterns } from '../core/ignore.js';
@@ -39,6 +39,7 @@ import {
   claimFiles, releaseFileClaims, getActiveFileClaims, checkFileConflicts, retryTask,
   upsertTaskSpec,
   listAuditEvents, pruneDatabaseMaintenance, verifyAuditTrail,
+  getLeaseExecutionContext, getActiveLeaseForTask,
 } from '../core/db.js';
 import { scanAllWorktrees } from '../core/detector.js';
 import { ensureProjectLocalMcpGitExcludes, getWindsurfMcpConfigPath, upsertAllProjectMcpConfigs, upsertWindsurfMcpConfig } from '../core/mcp.js';
@@ -64,6 +65,16 @@ import {
 import { checkLicence, clearCredentials, FREE_AGENT_LIMIT, getRetentionDaysForCurrentPlan, loginWithGitHub, PRO_PAGE_URL, readCredentials } from '../core/licence.js';
 import { homedir } from 'os';
 import { cleanupOldSyncEvents, pullActiveTeamMembers, pullTeamState, pushSyncEvent } from '../core/sync.js';
+import { registerClaudeCommands } from './commands/claude.js';
+import { registerMcpCommands } from './commands/mcp.js';
+import { registerAuditCommands } from './commands/audit.js';
+import { registerGateCommands } from './commands/gate.js';
+import { registerLeaseCommands } from './commands/lease.js';
+import { registerMonitorCommands } from './commands/monitor.js';
+import { registerQueueCommands } from './commands/queue.js';
+import { registerTaskCommands } from './commands/task.js';
+import { registerTelemetryCommands } from './commands/telemetry.js';
+import { registerWorktreeCommands } from './commands/worktree.js';
 
 const originalProcessEmit = process.emit.bind(process);
 process.emit = function patchedProcessEmit(event, ...args) {
@@ -200,7 +211,7 @@ function summarizeRecentCommitContext(branchGoal, subjects) {
   return `${effectiveCount} recent ${topicLabel}commit${effectiveCount === 1 ? '' : 's'}`;
 }
 
-function collectPlanContext(repoRoot, explicitGoal = null) {
+function collectPlanContext(repoRoot, explicitGoal = null, issueContext = null) {
   const planningFiles = ['CLAUDE.md', 'ROADMAP.md', 'tasks.md', 'TASKS.md', 'TODO.md', 'README.md']
     .map((fileName) => readPlanningFile(repoRoot, fileName))
     .filter(Boolean);
@@ -217,14 +228,19 @@ function collectPlanContext(repoRoot, explicitGoal = null) {
     || planningByName.get('README.md')
     || null;
   const planningSignal = preferredPlanningFile ? extractMarkdownSignal(preferredPlanningFile.text) : null;
-  const title = capitalizeSentence(explicitGoal || branchGoal || planningSignal || 'Plan the next coordinated change');
+  const title = capitalizeSentence(issueContext?.title || explicitGoal || branchGoal || planningSignal || 'Plan the next coordinated change');
   const descriptionParts = [];
+  if (issueContext?.description) descriptionParts.push(issueContext.description);
   if (preferredPlanningFile?.text) descriptionParts.push(preferredPlanningFile.text);
   if (recentCommitSubjects.length > 0) descriptionParts.push(`Recent git history summary: ${recentCommitSubjects.slice(0, 3).join('; ')}.`);
   const description = descriptionParts.join('\n\n').trim() || null;
 
   const found = [];
   const used = [];
+  if (issueContext?.number) {
+    found.push(`issue #${issueContext.number} "${issueContext.title}"`);
+    used.push(`GitHub issue #${issueContext.number}`);
+  }
   if (explicitGoal) {
     used.push('explicit goal');
   }
@@ -250,6 +266,123 @@ function collectPlanContext(repoRoot, explicitGoal = null) {
   };
 }
 
+function fetchGitHubIssueContext(repoRoot, issueNumber, ghCommand = 'gh') {
+  const normalizedIssueNumber = String(issueNumber || '').trim();
+  if (!normalizedIssueNumber) {
+    throw new Error('A GitHub issue number is required.');
+  }
+
+  const result = spawnSync(ghCommand, [
+    'issue',
+    'view',
+    normalizedIssueNumber,
+    '--json',
+    'title,body,comments',
+  ], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+
+  if (result.error) {
+    throw new Error(`Could not run ${ghCommand} to read issue #${normalizedIssueNumber}. ${result.error.message}`);
+  }
+
+  if (result.status !== 0) {
+    const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+    throw new Error(output || `gh issue view failed for issue #${normalizedIssueNumber}. Make sure gh is installed and authenticated.`);
+  }
+
+  let issue;
+  try {
+    issue = JSON.parse(result.stdout || '{}');
+  } catch {
+    throw new Error(`Could not parse GitHub issue #${normalizedIssueNumber}.`);
+  }
+
+  const comments = Array.isArray(issue.comments)
+    ? issue.comments.map((entry) => entry?.body || '').filter(Boolean)
+    : [];
+  const descriptionParts = [
+    `GitHub issue #${normalizedIssueNumber}: ${issue.title || 'Untitled issue'}`,
+    issue.body || '',
+    comments.length > 0 ? `Comments:\n${comments.join('\n---\n')}` : '',
+  ].filter(Boolean);
+
+  return {
+    number: normalizedIssueNumber,
+    title: issue.title || `Issue #${normalizedIssueNumber}`,
+    description: descriptionParts.join('\n\n'),
+    comment_count: comments.length,
+  };
+}
+
+function buildPlanningCommentBody(context, plannedTasks) {
+  const lines = [
+    '## Switchman plan summary',
+    '',
+    `Planned from: **${context.title}**`,
+  ];
+
+  if (context.used.length > 0) {
+    lines.push(`Context used: ${context.used.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push('Proposed parallel tasks:');
+  lines.push('');
+
+  plannedTasks.forEach((task, index) => {
+    const worktreeLabel = task.suggested_worktree || 'unassigned';
+    lines.push(`${index + 1}. ${task.title} (${worktreeLabel})`);
+  });
+
+  lines.push('');
+  lines.push('_Generated by Switchman._');
+  return `${lines.join('\n')}\n`;
+}
+
+function postPlanningSummaryComment(repoRoot, {
+  ghCommand = 'gh',
+  issueNumber = null,
+  prNumber = null,
+  body,
+}) {
+  const targetNumber = prNumber || issueNumber;
+  if (!targetNumber) {
+    throw new Error('A GitHub issue or pull request number is required to post a planning summary.');
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'switchman-plan-comment-'));
+  const bodyPath = join(tempDir, 'plan-summary.md');
+  writeFileSync(bodyPath, body, 'utf8');
+
+  try {
+    const args = prNumber
+      ? ['pr', 'comment', String(prNumber), '--body-file', bodyPath]
+      : ['issue', 'comment', String(issueNumber), '--body-file', bodyPath];
+    const result = spawnSync(ghCommand, args, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    });
+
+    if (result.error) {
+      throw new Error(`Could not run ${ghCommand} to post the planning summary. ${result.error.message}`);
+    }
+
+    if (result.status !== 0) {
+      const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+      throw new Error(output || `gh ${prNumber ? 'pr' : 'issue'} comment failed.`);
+    }
+
+    return {
+      target_type: prNumber ? 'pr' : 'issue',
+      target_number: String(targetNumber),
+    };
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
 function resolvePlanningWorktrees(repoRoot, db = null) {
   if (db) {
     const registered = listWorktrees(db)
@@ -1465,6 +1598,184 @@ function printRepairSummary(report, {
   }
 }
 
+function summarizeRecoveredTaskState({
+  task,
+  lease = null,
+  worktree = null,
+  changedFiles = [],
+  claims = [],
+  boundaryValidation = null,
+  auditEvents = [],
+  recoveryKind,
+  staleAfterMinutes = null,
+}) {
+  const observedWrites = auditEvents.filter((event) => event.event_type === 'write_observed');
+  const latestAuditEvent = auditEvents[0] || null;
+  const nextAction = worktree?.path
+    ? `cd "${worktree.path}" && git status`
+    : `switchman task retry ${task.id}`;
+
+  return {
+    kind: recoveryKind,
+    task_id: task.id,
+    task_title: task.title,
+    worktree: worktree?.name || lease?.worktree || task.worktree || null,
+    worktree_path: worktree?.path || null,
+    lease_id: lease?.id || null,
+    agent: lease?.agent || task.agent || null,
+    stale_after_minutes: staleAfterMinutes,
+    changed_files: changedFiles,
+    claimed_files: claims,
+    observed_write_count: observedWrites.length,
+    latest_audit_event: latestAuditEvent ? {
+      event_type: latestAuditEvent.event_type,
+      status: latestAuditEvent.status,
+      created_at: latestAuditEvent.created_at,
+      reason_code: latestAuditEvent.reason_code || null,
+    } : null,
+    boundary_validation: boundaryValidation ? {
+      status: boundaryValidation.status,
+      missing_task_types: boundaryValidation.missing_task_types || [],
+    } : null,
+    progress_summary: changedFiles.length > 0
+      ? `Observed uncommitted changes in ${changedFiles.length} file(s).`
+      : claims.length > 0
+        ? `Lease held ${claims.length} active claim(s) before recovery.`
+        : observedWrites.length > 0
+          ? `Observed ${observedWrites.length} governed write event(s) before recovery.`
+          : 'No uncommitted changes were detected at recovery time.',
+    next_action: nextAction,
+  };
+}
+
+function buildRecoverReport(db, repoRoot, { staleAfterMinutes = null, reason = 'operator recover' } = {}) {
+  const leasePolicy = loadLeasePolicy(repoRoot);
+  const staleMinutes = staleAfterMinutes
+    ? Number.parseInt(staleAfterMinutes, 10)
+    : leasePolicy.stale_after_minutes;
+  const worktreeMap = new Map(listWorktrees(db).map((worktree) => [worktree.name, worktree]));
+  const staleLeases = getStaleLeases(db, staleMinutes);
+  const staleTaskIds = new Set(staleLeases.map((lease) => lease.task_id));
+  const staleLeaseSummaries = staleLeases.map((lease) => {
+    const execution = getLeaseExecutionContext(db, lease.id);
+    const worktree = worktreeMap.get(lease.worktree) || execution?.worktree || null;
+    const changedFiles = worktree?.path ? getWorktreeChangedFiles(worktree.path, repoRoot) : [];
+    const claims = execution?.claims?.map((claim) => claim.file_path) || [];
+    const boundaryValidation = getBoundaryValidationState(db, lease.id);
+    const auditEvents = listAuditEvents(db, { taskId: lease.task_id, limit: 10 });
+    return summarizeRecoveredTaskState({
+      task: execution?.task || getTask(db, lease.task_id),
+      lease,
+      worktree,
+      changedFiles,
+      claims,
+      boundaryValidation,
+      auditEvents,
+      recoveryKind: 'stale_lease',
+      staleAfterMinutes: staleMinutes,
+    });
+  });
+
+  const strandedTasks = listTasks(db, 'in_progress')
+    .filter((task) => !staleTaskIds.has(task.id))
+    .filter((task) => !getActiveLeaseForTask(db, task.id));
+  const strandedTaskSummaries = strandedTasks.map((task) => {
+    const worktree = task.worktree ? worktreeMap.get(task.worktree) || null : null;
+    const changedFiles = worktree?.path ? getWorktreeChangedFiles(worktree.path, repoRoot) : [];
+    const auditEvents = listAuditEvents(db, { taskId: task.id, limit: 10 });
+    return summarizeRecoveredTaskState({
+      task,
+      worktree,
+      changedFiles,
+      claims: [],
+      boundaryValidation: null,
+      auditEvents,
+      recoveryKind: 'stranded_task',
+    });
+  });
+
+  const expiredLeases = staleLeases.length > 0
+    ? reapStaleLeases(db, staleMinutes, { requeueTask: leasePolicy.requeue_task_on_reap })
+    : [];
+  const retriedTasks = strandedTasks
+    .map((task) => retryTask(db, task.id, reason))
+    .filter(Boolean);
+  const repair = repairRepoState(db, repoRoot);
+
+  return {
+    stale_after_minutes: staleMinutes,
+    requeue_task_on_reap: leasePolicy.requeue_task_on_reap,
+    stale_leases: staleLeaseSummaries.map((item) => ({
+      ...item,
+      recovered_to: leasePolicy.requeue_task_on_reap ? 'pending' : 'failed',
+    })),
+    stranded_tasks: strandedTaskSummaries.map((item) => ({
+      ...item,
+      recovered_to: 'pending',
+    })),
+    repair,
+    recovered: {
+      stale_leases: expiredLeases.length,
+      stranded_tasks: retriedTasks.length,
+      repo_actions: repair.actions.length,
+    },
+    next_steps: [
+      ...(staleLeaseSummaries.length > 0 || strandedTaskSummaries.length > 0
+        ? ['switchman status', 'switchman task list --status pending']
+        : []),
+      ...(repair.next_action ? [repair.next_action] : []),
+    ].filter((value, index, all) => all.indexOf(value) === index),
+  };
+}
+
+function printRecoverSummary(report) {
+  const totalRecovered = report.recovered.stale_leases + report.recovered.stranded_tasks;
+  console.log(totalRecovered > 0 || report.repair.repaired
+    ? `${chalk.green('✓')} Recovered abandoned work and repaired safe interrupted state`
+    : `${chalk.green('✓')} No abandoned work needed recovery`);
+
+  console.log(`  ${chalk.dim('stale lease threshold:')} ${report.stale_after_minutes} minute(s)`);
+  console.log(`  ${chalk.dim('requeue on reap:')} ${report.requeue_task_on_reap ? 'on' : 'off'}`);
+  console.log(`  ${chalk.green('recovered stale leases:')} ${report.recovered.stale_leases}`);
+  console.log(`  ${chalk.green('recovered stranded tasks:')} ${report.recovered.stranded_tasks}`);
+  console.log(`  ${chalk.green('repo repair actions:')} ${report.recovered.repo_actions}`);
+
+  const recoveredItems = [...report.stale_leases, ...report.stranded_tasks];
+  if (recoveredItems.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Recovered work:'));
+    for (const item of recoveredItems) {
+      console.log(`  ${chalk.cyan(item.worktree || 'unknown')} ${chalk.dim(item.task_id)} ${chalk.bold(item.task_title)}`);
+      console.log(`    ${chalk.dim('type:')} ${item.kind === 'stale_lease' ? 'stale lease' : 'stranded in-progress task'}${item.lease_id ? `  ${chalk.dim('lease:')} ${item.lease_id}` : ''}`);
+      console.log(`    ${chalk.dim('summary:')} ${item.progress_summary}`);
+      if (item.changed_files.length > 0) {
+        console.log(`    ${chalk.dim('changed:')} ${item.changed_files.slice(0, 5).join(', ')}${item.changed_files.length > 5 ? ` ${chalk.dim(`+${item.changed_files.length - 5} more`)}` : ''}`);
+      }
+      if (item.claimed_files.length > 0) {
+        console.log(`    ${chalk.dim('claimed:')} ${item.claimed_files.slice(0, 5).join(', ')}${item.claimed_files.length > 5 ? ` ${chalk.dim(`+${item.claimed_files.length - 5} more`)}` : ''}`);
+      }
+      if (item.boundary_validation) {
+        console.log(`    ${chalk.dim('validation:')} ${item.boundary_validation.status}${item.boundary_validation.missing_task_types.length > 0 ? ` ${chalk.dim(`missing ${item.boundary_validation.missing_task_types.join(', ')}`)}` : ''}`);
+      }
+      console.log(`    ${chalk.yellow('inspect:')} ${item.next_action}`);
+    }
+  }
+
+  console.log('');
+  printRepairSummary(report.repair, {
+    repairedHeading: `${chalk.green('✓')} Repaired safe interrupted repo state during recovery`,
+    noRepairHeading: `${chalk.green('✓')} No extra repo repair action was needed during recovery`,
+    limit: 6,
+  });
+  if (report.next_steps.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Next steps:'));
+    for (const step of report.next_steps) {
+      console.log(`  ${chalk.cyan(step)}`);
+    }
+  }
+}
+
 function repairRepoState(db, repoRoot) {
   const actions = [];
   const warnings = [];
@@ -1758,7 +2069,7 @@ function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
     detail: claudeGuideExists ? 'CLAUDE.md is present' : 'CLAUDE.md is optional but recommended for Claude Code',
   });
   if (!claudeGuideExists) {
-    nextSteps.push('If you use Claude Code, add `CLAUDE.md` from the repo root setup guide.');
+    nextSteps.push('If you use Claude Code, run `switchman claude refresh` to generate a repo-aware `CLAUDE.md`.');
   }
 
   const windsurfConfigExists = existsSync(getWindsurfMcpConfigPath(homeDir || undefined));
@@ -1794,6 +2105,238 @@ function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
   };
 }
 
+function readJsonFileIfExists(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function detectClaudeGuideContext(repoRoot) {
+  const packageJson = readJsonFileIfExists(join(repoRoot, 'package.json'));
+  const hasTsconfig = existsSync(join(repoRoot, 'tsconfig.json'));
+  const hasPyproject = existsSync(join(repoRoot, 'pyproject.toml'));
+  const hasRequirements = existsSync(join(repoRoot, 'requirements.txt'));
+  const hasGoMod = existsSync(join(repoRoot, 'go.mod'));
+  const hasCargo = existsSync(join(repoRoot, 'Cargo.toml'));
+  const hasGemfile = existsSync(join(repoRoot, 'Gemfile'));
+
+  const stack = [];
+  if (packageJson) stack.push(hasTsconfig ? 'Node.js + TypeScript' : 'Node.js');
+  if (!packageJson && hasTsconfig) stack.push('TypeScript');
+  if (hasPyproject || hasRequirements) stack.push('Python');
+  if (hasGoMod) stack.push('Go');
+  if (hasCargo) stack.push('Rust');
+  if (hasGemfile) stack.push('Ruby');
+  if (stack.length === 0) stack.push('general-purpose codebase');
+
+  const packageManager = existsSync(join(repoRoot, 'pnpm-lock.yaml'))
+    ? 'pnpm'
+    : existsSync(join(repoRoot, 'yarn.lock'))
+      ? 'yarn'
+      : 'npm';
+
+  const scripts = packageJson?.scripts || {};
+  const packageRunner = packageManager === 'pnpm'
+    ? 'pnpm'
+    : packageManager === 'yarn'
+      ? 'yarn'
+      : 'npm run';
+  const testCommand = typeof scripts.test === 'string' && scripts.test.trim() && !scripts.test.includes('no test specified')
+    ? `${packageRunner}${packageManager === 'yarn' ? ' test' : ' test'}`
+    : hasPyproject || hasRequirements
+      ? 'pytest'
+      : hasGoMod
+        ? 'go test ./...'
+        : hasCargo
+          ? 'cargo test'
+          : null;
+  const buildCommand = typeof scripts.build === 'string' && scripts.build.trim()
+    ? `${packageRunner}${packageManager === 'yarn' ? ' build' : ' build'}`
+    : hasGoMod
+      ? 'go build ./...'
+      : hasCargo
+        ? 'cargo build'
+        : null;
+  const lintCommand = typeof scripts.lint === 'string' && scripts.lint.trim()
+    ? `${packageRunner}${packageManager === 'yarn' ? ' lint' : ' lint'}`
+    : null;
+
+  const importantPaths = [
+    existsSync(join(repoRoot, 'src')) ? 'src/' : null,
+    existsSync(join(repoRoot, 'app')) ? 'app/' : null,
+    existsSync(join(repoRoot, 'lib')) ? 'lib/' : null,
+    existsSync(join(repoRoot, 'tests')) ? 'tests/' : null,
+    existsSync(join(repoRoot, 'test')) ? 'test/' : null,
+    existsSync(join(repoRoot, 'docs')) ? 'docs/' : null,
+    existsSync(join(repoRoot, 'packages')) ? 'packages/' : null,
+  ].filter(Boolean);
+
+  const conventions = [];
+  if (existsSync(join(repoRoot, '.mcp.json'))) conventions.push('project-local MCP config is already wired');
+  if (existsSync(join(repoRoot, '.cursor', 'mcp.json'))) conventions.push('Cursor MCP config is present');
+  if (existsSync(join(repoRoot, '.git', 'info', 'exclude'))) conventions.push('repo-local git excludes can hide MCP noise from merges');
+
+  return {
+    stack,
+    packageManager,
+    testCommand,
+    buildCommand,
+    lintCommand,
+    importantPaths: importantPaths.slice(0, 5),
+    conventions,
+  };
+}
+
+function renderClaudeGuide(repoRoot) {
+  const context = detectClaudeGuideContext(repoRoot);
+  const stackSummary = formatHumanList(context.stack);
+  const importantPaths = context.importantPaths.length > 0
+    ? context.importantPaths.join(', ')
+    : 'the repo root';
+  const preferredCommands = [
+    context.testCommand ? `- Tests: \`${context.testCommand}\`` : null,
+    context.buildCommand ? `- Build: \`${context.buildCommand}\`` : null,
+    context.lintCommand ? `- Lint: \`${context.lintCommand}\`` : null,
+  ].filter(Boolean);
+  const conventions = context.conventions.length > 0
+    ? context.conventions.map((item) => `- ${item}`)
+    : ['- follow the existing file layout and naming conventions already in the repo'];
+
+  return `# Switchman Agent Instructions
+
+This repository uses **Switchman** to coordinate parallel AI coding agents.
+You MUST follow these instructions every session to avoid conflicting with other agents.
+
+You must use the Switchman MCP tools for coordination. Do not read from or write to \`.switchman/switchman.db\` directly, and do not bypass Switchman by issuing raw SQLite queries.
+
+---
+
+## Repo profile
+
+- Stack: ${stackSummary}
+- Important paths: ${importantPaths}
+${preferredCommands.length > 0 ? preferredCommands.join('\n') : '- Commands: follow the repo-specific test/build scripts before marking work complete'}
+
+## Existing conventions
+
+${conventions.join('\n')}
+
+When you make changes, preserve the current code style, folder structure, and script usage that already exist in this repo.
+
+---
+
+## Your worktree
+
+Find your worktree name by running:
+\`\`\`bash
+git worktree list
+\`\`\`
+The path that matches your current directory is your worktree. Use the last path segment as your worktree name (e.g. \`/projects/myapp-feature-auth\` → \`feature-auth\`). The main repo root is always named \`main\`.
+
+---
+
+## Required workflow — follow this every session
+
+### 1. Start of session — get your task
+
+Call the \`switchman_task_next\` MCP tool with your worktree name:
+\`\`\`
+switchman_task_next({ worktree: "<your-worktree-name>", agent: "claude-code" })
+\`\`\`
+
+- If \`task\` is \`null\` — the queue is empty. Ask the user what to work on, or stop.
+- If you receive a task — note the \`task.id\`. You'll need it in the next steps.
+- If the \`switchman_*\` tools are unavailable, stop and tell the user the MCP server is not connected. Do not fall back to direct SQLite access.
+
+### 2. Before editing any files — claim them
+
+Call \`switchman_task_claim\` with every file you plan to edit **before you edit them**:
+\`\`\`
+switchman_task_claim({
+  task_id: "<task-id>",
+  worktree: "<your-worktree-name>",
+  files: ["src/auth/login.js", "tests/auth.test.js"]
+})
+\`\`\`
+
+- If \`safe_to_proceed\` is \`false\` — there are conflicts. Do NOT edit those files.
+  Read the \`conflicts\` array to see which worktrees own them, then either:
+  - Choose different files that accomplish the same goal
+  - Ask the user how to proceed
+
+- If \`safe_to_proceed\` is \`true\` — you are clear to edit.
+
+### 3. Do the work
+
+Implement the task. Make commits as normal. Other agents will avoid your claimed files.
+
+If you discover mid-task that you need to edit additional files, call \`switchman_task_claim\` again for those files before editing them.
+
+When MCP write tools are available, prefer the Switchman enforcement gateway over native file writes:
+\`\`\`text
+switchman_write_file(...)
+switchman_append_file(...)
+switchman_make_directory(...)
+switchman_move_path(...)
+switchman_remove_path(...)
+\`\`\`
+
+These tools validate your active lease and claimed paths before changing the filesystem. Use native file writes only when the Switchman write tools are unavailable and you have already claimed the path.
+
+### 4. Before marking work complete
+
+Run the repo's most relevant verification commands for the files you changed.
+${context.testCommand ? `At minimum, prefer \`${context.testCommand}\` when the task changes behavior or tests.\n` : ''}${context.lintCommand ? `Use \`${context.lintCommand}\` when the repo relies on linting before merge.\n` : ''}${context.buildCommand ? `Use \`${context.buildCommand}\` when the repo has a meaningful build step.\n` : ''}If the correct command is unclear, inspect the existing scripts and match the repo's normal workflow.
+
+### 5. End of session — mark complete or failed
+
+**On success:**
+\`\`\`
+switchman_task_done({ task_id: "<task-id>" })
+\`\`\`
+
+**On failure (can't complete the task):**
+\`\`\`
+switchman_task_fail({ task_id: "<task-id>", reason: "Brief explanation of what blocked you" })
+\`\`\`
+
+Always call one of these before ending your session. Released file claims allow other agents to proceed.
+
+---
+
+## Checking system state
+
+To see what other agents are doing:
+\`\`\`
+switchman_status()
+\`\`\`
+
+To recover abandoned work or stale sessions:
+\`\`\`
+switchman_recover()
+\`\`\`
+
+To scan for conflicts before merge:
+\`\`\`
+switchman_scan()
+\`\`\`
+
+---
+
+## Rules
+
+1. **Always claim files before editing them** — not after.
+2. **Always call \`switchman_task_done\` or \`switchman_task_fail\` at end of session** — never leave tasks as \`in_progress\` when you stop.
+3. **If \`safe_to_proceed\` is false, do not edit the conflicting files** — coordinate first.
+4. **Do not claim files you don't need** — over-claiming blocks other agents unnecessarily.
+5. **One task per session** — complete or fail your current task before taking another.
+6. **Never query or mutate the Switchman SQLite database directly** — use MCP tools only.
+`;
+}
+
 function renderSetupVerification(report, { compact = false } = {}) {
   console.log(chalk.bold(compact ? 'First-run check:' : 'Setup verification:'));
   for (const check of report.checks) {
@@ -2911,6 +3454,7 @@ program
 program.showHelpAfterError('(run with --help for usage examples)');
 const ROOT_HELP_COMMANDS = new Set([
   'advanced',
+  'claude',
   'demo',
   'setup',
   'verify-setup',
@@ -2919,6 +3463,7 @@ const ROOT_HELP_COMMANDS = new Set([
   'plan',
   'task',
   'status',
+  'recover',
   'merge',
   'repair',
   'help',
@@ -2936,13 +3481,16 @@ Start here:
   switchman setup --agents 3
   switchman task add "Your task" --priority 8
   switchman status --watch
+  switchman recover
   switchman gate ci && switchman queue run
 
 For you (the operator):
   switchman demo
   switchman setup
+  switchman claude refresh
   switchman task add
   switchman status
+  switchman recover
   switchman merge
   switchman repair
   switchman upgrade
@@ -3257,156 +3805,53 @@ Use this after setup or whenever editor/config wiring feels off.
     }, { homeDir: opts.home || null });
     if (!report.ok) process.exitCode = 1;
   });
+registerClaudeCommands(program, {
+  chalk,
+  existsSync,
+  getRepo,
+  join,
+  renderClaudeGuide,
+  writeFileSync,
+});
 
 
 // ── mcp ───────────────────────────────────────────────────────────────────────
 
-const mcpCmd = program.command('mcp').description('Manage editor connections for Switchman');
-const telemetryCmd = program.command('telemetry').description('Control anonymous opt-in telemetry for Switchman');
-
-telemetryCmd
-  .command('status')
-  .description('Show whether telemetry is enabled and where events would be sent')
-  .option('--home <path>', 'Override the home directory for telemetry config')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const config = loadTelemetryConfig(opts.home || undefined);
-    const runtime = getTelemetryRuntimeConfig();
-    const payload = {
-      enabled: config.telemetry_enabled === true,
-      configured: Boolean(runtime.apiKey) && !runtime.disabled,
-      install_id: config.telemetry_install_id,
-      destination: runtime.apiKey && !runtime.disabled ? runtime.host : null,
-      config_path: getTelemetryConfigPath(opts.home || undefined),
-    };
-
-    if (opts.json) {
-      console.log(JSON.stringify(payload, null, 2));
-      return;
-    }
-
-    console.log(`Telemetry: ${payload.enabled ? chalk.green('enabled') : chalk.yellow('disabled')}`);
-    console.log(`Configured destination: ${payload.configured ? chalk.cyan(payload.destination) : chalk.dim('not configured')}`);
-    console.log(`Config file: ${chalk.dim(payload.config_path)}`);
-    if (payload.install_id) {
-      console.log(`Install ID: ${chalk.dim(payload.install_id)}`);
-    }
-  });
-
-telemetryCmd
-  .command('enable')
-  .description('Enable anonymous telemetry for setup and operator workflows')
-  .option('--home <path>', 'Override the home directory for telemetry config')
-  .action((opts) => {
-    const runtime = getTelemetryRuntimeConfig();
-    if (!runtime.apiKey || runtime.disabled) {
-      printErrorWithNext('Telemetry destination is not configured. Set SWITCHMAN_TELEMETRY_API_KEY first.', 'switchman telemetry status');
-      process.exitCode = 1;
-      return;
-    }
-    const result = enableTelemetry(opts.home || undefined);
-    console.log(`${chalk.green('✓')} Telemetry enabled`);
-    console.log(`  ${chalk.dim(result.path)}`);
-  });
-
-telemetryCmd
-  .command('disable')
-  .description('Disable anonymous telemetry')
-  .option('--home <path>', 'Override the home directory for telemetry config')
-  .action((opts) => {
-    const result = disableTelemetry(opts.home || undefined);
-    console.log(`${chalk.green('✓')} Telemetry disabled`);
-    console.log(`  ${chalk.dim(result.path)}`);
-  });
-
-telemetryCmd
-  .command('test')
-  .description('Send one test telemetry event and report whether delivery succeeded')
-  .option('--home <path>', 'Override the home directory for telemetry config')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    const result = await sendTelemetryEvent('telemetry_test', {
-      app_version: program.version(),
-      os: process.platform,
-      node_version: process.version,
-      source: 'switchman-cli-test',
-    }, { homeDir: opts.home || undefined });
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-      if (!result.ok) process.exitCode = 1;
-      return;
-    }
-
-    if (result.ok) {
-      console.log(`${chalk.green('✓')} Telemetry test event delivered`);
-      console.log(`  ${chalk.dim('destination:')} ${chalk.cyan(result.destination)}`);
-      if (result.status) {
-        console.log(`  ${chalk.dim('status:')} ${result.status}`);
-      }
-      return;
-    }
-
-    printErrorWithNext(`Telemetry test failed (${result.reason || 'unknown_error'}).`, 'switchman telemetry status');
-    console.log(`  ${chalk.dim('destination:')} ${result.destination || 'unknown'}`);
-    if (result.status) {
-      console.log(`  ${chalk.dim('status:')} ${result.status}`);
-    }
-    if (result.error) {
-      console.log(`  ${chalk.dim('error:')} ${result.error}`);
-    }
-    process.exitCode = 1;
-  });
-
-mcpCmd
-  .command('install')
-  .description('Install editor-specific MCP config for Switchman')
-  .option('--windsurf', 'Write Windsurf MCP config to ~/.codeium/mcp_config.json')
-  .option('--home <path>', 'Override the home directory for config writes (useful for testing)')
-  .option('--json', 'Output raw JSON')
-  .addHelpText('after', `
-Examples:
-  switchman mcp install --windsurf
-  switchman mcp install --windsurf --json
-`)
-  .action((opts) => {
-    if (!opts.windsurf) {
-      console.error(chalk.red('Choose an editor install target, for example `switchman mcp install --windsurf`.'));
-      process.exitCode = 1;
-      return;
-    }
-
-    const result = upsertWindsurfMcpConfig(opts.home);
-
-    if (opts.json) {
-      console.log(JSON.stringify({
-        editor: 'windsurf',
-        path: result.path,
-        created: result.created,
-        changed: result.changed,
-      }, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Windsurf MCP config ${result.changed ? 'written' : 'already up to date'}`);
-    console.log(`  ${chalk.dim('path:')} ${chalk.cyan(result.path)}`);
-    console.log(`  ${chalk.dim('open:')} Windsurf -> Settings -> Cascade -> MCP Servers`);
-    console.log(`  ${chalk.dim('note:')} Windsurf reads the shared config from ${getWindsurfMcpConfigPath(opts.home)}`);
-  });
+registerMcpCommands(program, {
+  chalk,
+  getWindsurfMcpConfigPath,
+  upsertWindsurfMcpConfig,
+});
+registerTelemetryCommands(program, {
+  chalk,
+  disableTelemetry,
+  enableTelemetry,
+  getTelemetryConfigPath,
+  getTelemetryRuntimeConfig,
+  loadTelemetryConfig,
+  printErrorWithNext,
+  sendTelemetryEvent,
+});
 
 
 // ── plan ──────────────────────────────────────────────────────────────────────
 
 program
   .command('plan [goal]')
-  .description('Pro: suggest a parallel task plan from an explicit goal')
+  .description('Pro: suggest a parallel task plan from an explicit goal or GitHub issue')
+  .option('--issue <number>', 'Read planning context from a GitHub issue via gh')
+  .option('--pr <number>', 'Post the resulting plan summary to a GitHub pull request')
+  .option('--comment', 'Post a GitHub comment with the created plan summary after --apply')
+  .option('--gh-command <command>', 'Executable to use for GitHub CLI', 'gh')
   .option('--apply', 'Create the suggested tasks in Switchman')
   .option('--max-tasks <n>', 'Maximum number of suggested tasks', '6')
   .option('--json', 'Output raw JSON')
   .addHelpText('after', `
 Examples:
   switchman plan "Add authentication"
+  switchman plan --issue 47
   switchman plan "Add authentication" --apply
+  switchman plan --issue 47 --apply --comment
 `)
   .action(async (goal, opts) => {
     const repoRoot = getRepo();
@@ -3424,17 +3869,48 @@ Examples:
         return;
       }
 
-      if (!goal || !goal.trim()) {
+      let issueContext = null;
+      if (opts.issue) {
+        try {
+          issueContext = fetchGitHubIssueContext(repoRoot, opts.issue, opts.ghCommand);
+        } catch (err) {
+          printErrorWithNext(err.message, 'switchman plan "Add authentication"');
+          process.exitCode = 1;
+          return;
+        }
+      }
+
+      if ((!goal || !goal.trim()) && !issueContext) {
         console.log('');
         console.log(chalk.yellow('  ⚠  AI planning currently requires an explicit goal.'));
         console.log(`  ${chalk.dim('Try:')} ${chalk.cyan('switchman plan "Add authentication"')}`);
+        console.log(`  ${chalk.dim('Or:  ')} ${chalk.cyan('switchman plan --issue 47')}`);
         console.log(`  ${chalk.dim('Then:')} ${chalk.cyan('switchman plan "Add authentication" --apply')}`);
         console.log('');
         process.exitCode = 1;
         return;
       }
 
-      const context = collectPlanContext(repoRoot, goal || null);
+      if (opts.comment && !opts.apply) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  GitHub plan comments are only posted after task creation.'));
+        console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman plan --apply --comment')}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
+      }
+
+      if (opts.comment && !opts.pr && !issueContext) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  Choose where to post the plan summary.'));
+        console.log(`  ${chalk.dim('Use:')} ${chalk.cyan('switchman plan --issue 47 --apply --comment')}`);
+        console.log(`  ${chalk.dim('Or: ')} ${chalk.cyan('switchman plan "Add authentication" --pr 123 --apply --comment')}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
+      }
+
+      const context = collectPlanContext(repoRoot, goal || null, issueContext);
       const planningWorktrees = resolvePlanningWorktrees(repoRoot, db);
       const pipelineId = `plan-${slugifyValue(context.title)}-${Date.now().toString(36)}`;
       const plannedTasks = planPipelineTasks({
@@ -3514,6 +3990,19 @@ Examples:
 
       console.log('');
       console.log(`${chalk.green('✓')} Planned ${plannedTasks.length} task(s) from repo context.`);
+      if (opts.comment) {
+        const commentBody = buildPlanningCommentBody(context, plannedTasks);
+        const commentResult = postPlanningSummaryComment(repoRoot, {
+          ghCommand: opts.ghCommand,
+          issueNumber: issueContext?.number || null,
+          prNumber: opts.pr || null,
+          body: commentBody,
+        });
+        const targetLabel = commentResult.target_type === 'pr'
+          ? `PR #${commentResult.target_number}`
+          : `issue #${commentResult.target_number}`;
+        console.log(`  ${chalk.green('✓')} Posted plan summary to ${chalk.cyan(targetLabel)}.`);
+      }
       console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman status --watch')}`);
     } finally {
       db?.close();
@@ -3523,677 +4012,56 @@ Examples:
 
 // ── task ──────────────────────────────────────────────────────────────────────
 
-const taskCmd = program.command('task').description('Manage the task list');
-taskCmd.addHelpText('after', `
-Examples:
-  switchman task add "Fix login bug" --priority 8
-  switchman task list --status pending
-  switchman task done task-123
-`);
-
-taskCmd
-  .command('add <title>')
-  .description('Add a new task to the queue')
-  .option('-d, --description <desc>', 'Task description')
-  .option('-p, --priority <n>', 'Priority 1-10 (default 5)', '5')
-  .option('--id <id>', 'Custom task ID')
-  .action((title, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const taskId = createTask(db, {
-      id: opts.id,
-      title,
-      description: opts.description,
-      priority: parseInt(opts.priority),
-    });
-    db.close();
-    const scopeWarning = analyzeTaskScope(title, opts.description || '');
-    console.log(`${chalk.green('✓')} Task created: ${chalk.cyan(taskId)}`);
-    pushSyncEvent('task_added', { task_id: taskId, title, priority: parseInt(opts.priority) }).catch(() => {});
-    console.log(`  ${chalk.dim(title)}`);
-    if (scopeWarning) {
-      console.log(chalk.yellow(`  warning: ${scopeWarning.summary}`));
-      console.log(chalk.yellow(`  next: ${scopeWarning.next_step}`));
-      console.log(chalk.cyan(`  try: ${scopeWarning.command}`));
-    }
-  });
-
-taskCmd
-  .command('list')
-  .description('List all tasks')
-  .option('-s, --status <status>', 'Filter by status (pending|in_progress|done|failed)')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const tasks = listTasks(db, opts.status);
-    db.close();
-
-    if (!tasks.length) {
-      console.log(chalk.dim('No tasks found.'));
-      return;
-    }
-
-    console.log('');
-    for (const t of tasks) {
-      const badge = statusBadge(t.status);
-      const worktree = t.worktree ? chalk.cyan(t.worktree) : chalk.dim('unassigned');
-      console.log(`${badge} ${chalk.bold(t.title)}`);
-      console.log(`  ${chalk.dim('id:')} ${t.id}  ${chalk.dim('worktree:')} ${worktree}  ${chalk.dim('priority:')} ${t.priority}`);
-      if (t.description) console.log(`  ${chalk.dim(t.description)}`);
-      console.log('');
-    }
-  });
-
-taskCmd
-  .command('assign <taskId> <worktree>')
-  .description('Assign a task to a workspace (compatibility shim for lease acquire)')
-  .option('--agent <name>', 'Agent name (e.g. claude-code)')
-  .action((taskId, worktree, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const lease = startTaskLease(db, taskId, worktree, opts.agent);
-    db.close();
-    if (lease) {
-      console.log(`${chalk.green('✓')} Assigned ${chalk.cyan(taskId)} → ${chalk.cyan(worktree)} (${chalk.dim(lease.id)})`);
-    } else {
-      console.log(chalk.red(`Could not assign task. It may not exist or is not in 'pending' status.`));
-    }
-  });
-
-taskCmd
-  .command('retry <taskId>')
-  .description('Return a failed or stale completed task to pending so it can be revalidated')
-  .option('--reason <text>', 'Reason to record for the retry')
-  .option('--json', 'Output raw JSON')
-  .action((taskId, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const task = retryTask(db, taskId, opts.reason || 'manual retry');
-    db.close();
-
-    if (!task) {
-      printErrorWithNext(`Task ${taskId} is not retryable.`, 'switchman task list --status failed');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(task, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Reset ${chalk.cyan(task.id)} to pending`);
-    pushSyncEvent('task_retried', { task_id: task.id, title: task.title, reason: opts.reason || 'manual retry' }).catch(() => {});
-    console.log(`  ${chalk.dim('title:')} ${task.title}`);
-    console.log(`${chalk.yellow('next:')} switchman task assign ${task.id} <workspace>`);
-  });
-
-taskCmd
-  .command('retry-stale')
-  .description('Return all currently stale tasks to pending so they can be revalidated together')
-  .option('--pipeline <id>', 'Only retry stale tasks for one pipeline')
-  .option('--reason <text>', 'Reason to record for the retry', 'bulk stale retry')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const result = retryStaleTasks(db, {
-      pipelineId: opts.pipeline || null,
-      reason: opts.reason,
-    });
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    if (result.retried.length === 0) {
-      const scope = result.pipeline_id ? ` for ${result.pipeline_id}` : '';
-      console.log(chalk.dim(`No stale tasks to retry${scope}.`));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Reset ${result.retried.length} stale task(s) to pending`);
-    pushSyncEvent('task_retried', {
-      pipeline_id: result.pipeline_id || null,
-      task_count: result.retried.length,
-      task_ids: result.retried.map((task) => task.id),
-      reason: opts.reason,
-    }).catch(() => {});
-    if (result.pipeline_id) {
-      console.log(`  ${chalk.dim('pipeline:')} ${result.pipeline_id}`);
-    }
-    console.log(`  ${chalk.dim('tasks:')} ${result.retried.map((task) => task.id).join(', ')}`);
-    console.log(`${chalk.yellow('next:')} switchman status`);
-  });
-
-taskCmd
-  .command('done <taskId>')
-  .description('Mark a task as complete and release all file claims')
-  .action((taskId) => {
-    const repoRoot = getRepo();
-    try {
-      const result = completeTaskWithRetries(repoRoot, taskId);
-      if (result?.status === 'already_done') {
-        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} was already marked done — no new changes were recorded`);
-        return;
-      }
-      if (result?.status === 'failed') {
-        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} is currently failed — retry it before marking it done again`);
-        return;
-      }
-      if (result?.status === 'not_in_progress') {
-        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} is not currently in progress — start a lease before marking it done`);
-        return;
-      }
-      if (result?.status === 'no_active_lease') {
-        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} has no active lease — reacquire the task before marking it done`);
-        return;
-      }
-      console.log(`${chalk.green('✓')} Task ${chalk.cyan(taskId)} marked done — file claims released`);
-      pushSyncEvent('task_done', { task_id: taskId }).catch(() => {});
-    } catch (err) {
-      console.error(chalk.red(err.message));
-      process.exitCode = 1;
-    }
-  });
-
-taskCmd
-  .command('fail <taskId> [reason]')
-  .description('Mark a task as failed')
-  .action((taskId, reason) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    failTask(db, taskId, reason);
-    releaseFileClaims(db, taskId);
-    db.close();
-    console.log(`${chalk.red('✗')} Task ${chalk.cyan(taskId)} marked failed`);
-    pushSyncEvent('task_failed', { task_id: taskId, reason: reason || null }).catch(() => {});
-  });
-
-taskCmd
-  .command('next')
-  .description('Get the next pending task quickly (use `lease next` for the full workflow)')
-  .option('--json', 'Output as JSON')
-  .option('--worktree <name>', 'Workspace to assign the task to (defaults to the current folder name)')
-  .option('--agent <name>', 'Agent identifier for logging (e.g. claude-code)')
-  .addHelpText('after', `
-Examples:
-  switchman task next
-  switchman task next --json
-`)
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const worktreeName = getCurrentWorktreeName(opts.worktree);
-    const { task, lease, exhausted } = acquireNextTaskLeaseWithRetries(repoRoot, worktreeName, opts.agent || null);
-
-    if (!task) {
-      if (opts.json) console.log(JSON.stringify({ task: null }));
-      else if (exhausted) console.log(chalk.dim('No pending tasks.'));
-      else console.log(chalk.yellow('Tasks were claimed by other agents during assignment. Run again to get the next one.'));
-      return;
-    }
-
-    if (!lease) {
-      if (opts.json) console.log(JSON.stringify({ task: null, message: 'Task claimed by another agent — try again' }));
-      else console.log(chalk.yellow('Task was just claimed by another agent. Run again to get the next one.'));
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(taskJsonWithLease(task, worktreeName, lease), null, 2));
-    } else {
-      console.log(`${chalk.green('✓')} Assigned: ${chalk.bold(task.title)}`);
-      console.log(`  ${chalk.dim('id:')} ${task.id}  ${chalk.dim('worktree:')} ${chalk.cyan(worktreeName)}  ${chalk.dim('lease:')} ${chalk.dim(lease.id)}  ${chalk.dim('priority:')} ${task.priority}`);
-    }
-  });
+registerTaskCommands(program, {
+  acquireNextTaskLeaseWithRetries,
+  analyzeTaskScope,
+  chalk,
+  completeTaskWithRetries,
+  createTask,
+  failTask,
+  getCurrentWorktreeName,
+  getDb,
+  getRepo,
+  listTasks,
+  printErrorWithNext,
+  pushSyncEvent,
+  releaseFileClaims,
+  retryStaleTasks,
+  retryTask,
+  startTaskLease,
+  statusBadge,
+  taskJsonWithLease,
+});
 
 // ── queue ─────────────────────────────────────────────────────────────────────
 
-const queueCmd = program.command('queue').alias('land').description('Land finished work safely back onto main, one item at a time');
-queueCmd.addHelpText('after', `
-Examples:
-  switchman queue add --worktree agent1
-  switchman queue status
-  switchman queue run --watch
-`);
-
-queueCmd
-  .command('add [branch]')
-  .description('Add a branch, workspace, or pipeline to the landing queue')
-  .option('--worktree <name>', 'Queue a registered workspace by name')
-  .option('--pipeline <pipelineId>', 'Queue a pipeline by id')
-  .option('--target <branch>', 'Target branch to merge into', 'main')
-  .option('--max-retries <n>', 'Maximum automatic retries', '1')
-  .option('--submitted-by <name>', 'Operator or automation name')
-  .option('--json', 'Output raw JSON')
-  .addHelpText('after', `
-Examples:
-  switchman queue add feature/auth-hardening
-  switchman queue add --worktree agent2
-  switchman queue add --pipeline pipe-123
-
-Pipeline landing rule:
-  switchman queue add --pipeline <id>
-  lands the pipeline's inferred landing branch.
-  If completed work spans multiple branches, Switchman creates one synthetic landing branch first.
-`)
-  .action(async (branch, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-
-    try {
-      let payload;
-      if (opts.worktree) {
-        const worktree = listWorktrees(db).find((entry) => entry.name === opts.worktree);
-        if (!worktree) {
-          throw new Error(`Workspace ${opts.worktree} is not registered.`);
-        }
-        payload = {
-          sourceType: 'worktree',
-          sourceRef: worktree.branch,
-          sourceWorktree: worktree.name,
-          targetBranch: opts.target,
-          maxRetries: opts.maxRetries,
-          submittedBy: opts.submittedBy || null,
-        };
-      } else if (opts.pipeline) {
-        const policyGate = await evaluatePipelinePolicyGate(db, repoRoot, opts.pipeline);
-        if (!policyGate.ok) {
-          throw new Error(`${policyGate.summary} Next: ${policyGate.next_action}`);
-        }
-        const landingTarget = preparePipelineLandingTarget(db, repoRoot, opts.pipeline, {
-          baseBranch: opts.target || 'main',
-          requireCompleted: true,
-          allowCurrentBranchFallback: false,
-        });
-        payload = {
-          sourceType: 'pipeline',
-          sourceRef: landingTarget.branch,
-          sourcePipelineId: opts.pipeline,
-          sourceWorktree: landingTarget.worktree || null,
-          targetBranch: opts.target,
-          maxRetries: opts.maxRetries,
-          submittedBy: opts.submittedBy || null,
-          eventDetails: policyGate.override_applied
-            ? {
-              policy_override_summary: policyGate.override_summary,
-              overridden_task_types: policyGate.policy_state?.overridden_task_types || [],
-            }
-            : null,
-        };
-      } else if (branch) {
-        payload = {
-          sourceType: 'branch',
-          sourceRef: branch,
-          targetBranch: opts.target,
-          maxRetries: opts.maxRetries,
-          submittedBy: opts.submittedBy || null,
-        };
-      } else {
-        throw new Error('Choose one source to land: a branch name, `--worktree`, or `--pipeline`.');
-      }
-
-      const result = enqueueMergeItem(db, payload);
-      db.close();
-      pushSyncEvent('queue_added', {
-        item_id: result.id,
-        source_type: result.source_type,
-        source_ref: result.source_ref,
-        source_worktree: result.source_worktree || null,
-        target_branch: result.target_branch,
-      }, { worktree: result.source_worktree || null }).catch(() => {});
-
-      if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
-        return;
-      }
-
-      console.log(`${chalk.green('✓')} Queued ${chalk.cyan(result.id)} for ${chalk.bold(result.target_branch)}`);
-      console.log(`  ${chalk.dim('source:')} ${result.source_type} ${result.source_ref}`);
-      if (result.source_worktree) console.log(`  ${chalk.dim('worktree:')} ${result.source_worktree}`);
-      if (payload.eventDetails?.policy_override_summary) {
-        console.log(`  ${chalk.dim('policy override:')} ${payload.eventDetails.policy_override_summary}`);
-      }
-    } catch (err) {
-      db.close();
-      printErrorWithNext(err.message, 'switchman queue add --help');
-      process.exitCode = 1;
-    }
-  });
-
-queueCmd
-  .command('list')
-  .description('List merge queue items')
-  .option('--status <status>', 'Filter by queue status')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const items = listMergeQueue(db, { status: opts.status || null });
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(items, null, 2));
-      return;
-    }
-
-    if (items.length === 0) {
-      console.log(chalk.dim('Merge queue is empty.'));
-      return;
-    }
-
-    for (const item of items) {
-      const retryInfo = chalk.dim(`retries:${item.retry_count}/${item.max_retries}`);
-      const attemptInfo = item.last_attempt_at ? ` ${chalk.dim(`last-attempt:${item.last_attempt_at}`)}` : '';
-      const backoffInfo = item.backoff_until ? ` ${chalk.dim(`backoff-until:${item.backoff_until}`)}` : '';
-      const escalationInfo = item.escalated_at ? ` ${chalk.dim(`escalated:${item.escalated_at}`)}` : '';
-      console.log(`  ${statusBadge(item.status)} ${item.id} ${item.source_type}:${item.source_ref} ${chalk.dim(`→ ${item.target_branch}`)} ${retryInfo}${attemptInfo}${backoffInfo}${escalationInfo}`);
-      if (item.last_error_summary) {
-        console.log(`    ${chalk.red('why:')} ${item.last_error_summary}`);
-      }
-      if (item.next_action) {
-        console.log(`    ${chalk.yellow('next:')} ${item.next_action}`);
-      }
-    }
-  });
-
-queueCmd
-  .command('status')
-  .description('Show an operator-friendly merge queue summary')
-  .option('--json', 'Output raw JSON')
-  .addHelpText('after', `
-Plain English:
-  Use this when finished branches are waiting to land and you want one safe queue view.
-
-Examples:
-  switchman queue status
-  switchman queue status --json
-
-What it helps you answer:
-  - what lands next
-  - what is blocked
-  - what command should I run now
-`)
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const items = listMergeQueue(db);
-    const summary = buildQueueStatusSummary(items, { db, repoRoot });
-    const recentEvents = items.slice(0, 5).flatMap((item) =>
-      listMergeQueueEvents(db, item.id, { limit: 3 }).map((event) => ({ ...event, queue_item_id: item.id })),
-    ).sort((a, b) => b.id - a.id).slice(0, 8);
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify({ items, summary, recent_events: recentEvents }, null, 2));
-      return;
-    }
-
-    if (items.length === 0) {
-      console.log('');
-      console.log(chalk.bold('switchman queue status'));
-      console.log('');
-      console.log('Queue is empty.');
-      console.log(`Add finished work with: ${chalk.cyan('switchman queue add --worktree agent1')}`);
-      return;
-    }
-
-    const queueHealth = summary.counts.blocked > 0
-      ? 'block'
-      : summary.counts.retrying > 0 || summary.counts.held > 0 || summary.counts.wave_blocked > 0 || summary.counts.escalated > 0
-        ? 'warn'
-        : 'healthy';
-    const queueHealthColor = colorForHealth(queueHealth);
-    const retryingItems = items.filter((item) => item.status === 'retrying');
-    const focus = summary.blocked[0] || retryingItems[0] || summary.next || null;
-    const focusLine = focus
-      ? `${focus.id} ${focus.source_type}:${focus.source_ref}${focus.last_error_summary ? ` ${chalk.dim(`• ${focus.last_error_summary}`)}` : ''}`
-      : 'Nothing waiting. Landing queue is clear.';
-
-    console.log('');
-    console.log(queueHealthColor('='.repeat(72)));
-    console.log(`${queueHealthColor(healthLabel(queueHealth))} ${chalk.bold('switchman queue status')} ${chalk.dim('• landing mission control')}`);
-    console.log(queueHealthColor('='.repeat(72)));
-    console.log(renderSignalStrip([
-      renderChip('queued', summary.counts.queued, summary.counts.queued > 0 ? chalk.yellow : chalk.green),
-      renderChip('retrying', summary.counts.retrying, summary.counts.retrying > 0 ? chalk.yellow : chalk.green),
-      renderChip('held', summary.counts.held, summary.counts.held > 0 ? chalk.yellow : chalk.green),
-      renderChip('wave blocked', summary.counts.wave_blocked, summary.counts.wave_blocked > 0 ? chalk.yellow : chalk.green),
-      renderChip('escalated', summary.counts.escalated, summary.counts.escalated > 0 ? chalk.red : chalk.green),
-      renderChip('blocked', summary.counts.blocked, summary.counts.blocked > 0 ? chalk.red : chalk.green),
-      renderChip('merging', summary.counts.merging, summary.counts.merging > 0 ? chalk.blue : chalk.green),
-      renderChip('merged', summary.counts.merged, summary.counts.merged > 0 ? chalk.green : chalk.white),
-    ]));
-    console.log(renderMetricRow([
-      { label: 'items', value: items.length, color: chalk.white },
-      { label: 'validating', value: summary.counts.validating, color: chalk.blue },
-      { label: 'rebasing', value: summary.counts.rebasing, color: chalk.blue },
-      { label: 'target', value: summary.next?.target_branch || 'main', color: chalk.cyan },
-    ]));
-    console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
-
-    const queueFocusLines = summary.next
-      ? [
-        `${renderChip(summary.next.recommendation?.action === 'retry' ? 'RETRY' : summary.next.recommendation?.action === 'escalate' ? 'ESCALATE' : 'NEXT', summary.next.id, summary.next.recommendation?.action === 'retry' ? chalk.yellow : summary.next.recommendation?.action === 'escalate' ? chalk.red : chalk.green)} ${summary.next.source_type}:${summary.next.source_ref} ${chalk.dim(`retries:${summary.next.retry_count}/${summary.next.max_retries}`)}${summary.next.queue_assessment?.goal_priority ? ` ${chalk.dim(`priority:${summary.next.queue_assessment.goal_priority}`)}` : ''}${summary.next.queue_assessment?.integration_risk && summary.next.queue_assessment.integration_risk !== 'normal' ? ` ${chalk.dim(`risk:${summary.next.queue_assessment.integration_risk}`)}` : ''}${summary.next.queue_assessment?.freshness ? ` ${chalk.dim(`freshness:${summary.next.queue_assessment.freshness}`)}` : ''}${summary.next.queue_assessment?.stale_invalidation_count ? ` ${chalk.dim(`stale:${summary.next.queue_assessment.stale_invalidation_count}`)}` : ''}`,
-        ...(summary.next.queue_assessment?.reason ? [`  ${chalk.dim('why next:')} ${summary.next.queue_assessment.reason}`] : []),
-        ...(summary.next.recommendation?.summary ? [`  ${chalk.dim('decision:')} ${summary.next.recommendation.summary}`] : []),
-        `  ${chalk.yellow('run:')} ${summary.next.recommendation?.command || 'switchman queue run'}`,
-      ]
-      : [chalk.dim('No queued landing work right now.')];
-
-    const queueHeldBackLines = summary.held_back.length > 0
-      ? summary.held_back.flatMap((item) => {
-        const lines = [`${renderChip(item.recommendation?.action === 'escalate' ? 'ESCALATE' : 'HOLD', item.id, item.recommendation?.action === 'escalate' ? chalk.red : chalk.yellow)} ${item.source_type}:${item.source_ref}${item.queue_assessment?.goal_priority ? ` ${chalk.dim(`priority:${item.queue_assessment.goal_priority}`)}` : ''} ${chalk.dim(`freshness:${item.queue_assessment?.freshness || 'unknown'}`)}${item.queue_assessment?.integration_risk && item.queue_assessment.integration_risk !== 'normal' ? ` ${chalk.dim(`risk:${item.queue_assessment.integration_risk}`)}` : ''}${item.queue_assessment?.stale_invalidation_count ? ` ${chalk.dim(`stale:${item.queue_assessment.stale_invalidation_count}`)}` : ''}`];
-        if (item.queue_assessment?.reason) lines.push(`  ${chalk.dim('why later:')} ${item.queue_assessment.reason}`);
-        if (item.recommendation?.summary) lines.push(`  ${chalk.dim('decision:')} ${item.recommendation.summary}`);
-        if (item.queue_assessment?.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.queue_assessment.next_action}`);
-        return lines;
-      })
-      : [chalk.green('Nothing significant is being held back.')];
-
-    const queueBlockedLines = summary.blocked.length > 0
-      ? summary.blocked.slice(0, 4).flatMap((item) => {
-        const lines = [`${renderChip('BLOCKED', item.id, chalk.red)} ${item.source_type}:${item.source_ref} ${chalk.dim(`retries:${item.retry_count}/${item.max_retries}`)}`];
-        if (item.last_error_summary) lines.push(`  ${chalk.red('why:')} ${item.last_error_summary}`);
-        if (item.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.next_action}`);
-        return lines;
-      })
-      : [chalk.green('Nothing blocked.')];
-
-    const queueWatchLines = items.filter((item) => ['retrying', 'held', 'wave_blocked', 'escalated', 'merging', 'rebasing', 'validating'].includes(item.status)).length > 0
-      ? items
-        .filter((item) => ['retrying', 'held', 'wave_blocked', 'escalated', 'merging', 'rebasing', 'validating'].includes(item.status))
-        .slice(0, 4)
-        .flatMap((item) => {
-          const lines = [`${renderChip(item.status.toUpperCase(), item.id, item.status === 'retrying' || item.status === 'held' || item.status === 'wave_blocked' ? chalk.yellow : item.status === 'escalated' ? chalk.red : chalk.blue)} ${item.source_type}:${item.source_ref}`];
-          if (item.last_error_summary) lines.push(`  ${chalk.dim(item.last_error_summary)}`);
-          if (item.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.next_action}`);
-          return lines;
-        })
-      : [chalk.green('No in-flight queue items right now.')];
-
-    const queueCommandLines = [
-      `${chalk.cyan('$')} switchman queue run`,
-      `${chalk.cyan('$')} switchman queue status --json`,
-      ...(summary.blocked[0] ? [`${chalk.cyan('$')} switchman queue retry ${summary.blocked[0].id}`] : []),
-    ];
-
-    const queuePlanLines = [
-      ...(summary.plan?.land_now?.slice(0, 2).map((item) => `${renderChip('LAND NOW', item.item_id, chalk.green)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-      ...(summary.plan?.prepare_next?.slice(0, 2).map((item) => `${renderChip('PREP NEXT', item.item_id, chalk.cyan)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-      ...(summary.plan?.unblock_first?.slice(0, 2).map((item) => `${renderChip('UNBLOCK', item.item_id, chalk.yellow)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-      ...(summary.plan?.escalate?.slice(0, 2).map((item) => `${renderChip('ESCALATE', item.item_id, chalk.red)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-      ...(summary.plan?.defer?.slice(0, 2).map((item) => `${renderChip('DEFER', item.item_id, chalk.white)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-    ];
-    const queueSequenceLines = summary.recommended_sequence?.length > 0
-      ? summary.recommended_sequence.map((item) => `${chalk.bold(`${item.stage}.`)} ${item.source_type}:${item.source_ref} ${chalk.dim(`[${item.lane}]`)} ${item.summary}`)
-      : [chalk.green('No recommended sequence beyond the current landing focus.')];
-
-    console.log('');
-    for (const block of [
-      renderPanel('Landing focus', queueFocusLines, chalk.green),
-      renderPanel('Recommended sequence', queueSequenceLines, summary.recommended_sequence?.length > 0 ? chalk.cyan : chalk.green),
-      renderPanel('Queue plan', queuePlanLines.length > 0 ? queuePlanLines : [chalk.green('Nothing else needs planning right now.')], queuePlanLines.length > 0 ? chalk.cyan : chalk.green),
-      renderPanel('Held back', queueHeldBackLines, summary.held_back.length > 0 ? chalk.yellow : chalk.green),
-      renderPanel('Blocked', queueBlockedLines, summary.counts.blocked > 0 ? chalk.red : chalk.green),
-      renderPanel('In flight', queueWatchLines, queueWatchLines[0] === 'No in-flight queue items right now.' ? chalk.green : chalk.blue),
-      renderPanel('Next commands', queueCommandLines, chalk.cyan),
-    ]) {
-      for (const line of block) console.log(line);
-      console.log('');
-    }
-
-    if (recentEvents.length > 0) {
-      console.log(chalk.bold('Recent Queue Events:'));
-      for (const event of recentEvents) {
-        console.log(`  ${chalk.cyan(event.queue_item_id)} ${chalk.dim(event.event_type)} ${chalk.dim(event.status || '')} ${chalk.dim(event.created_at)}`.trim());
-      }
-    }
-  });
-
-queueCmd
-  .command('run')
-  .description('Process landing-queue items one at a time')
-  .option('--max-items <n>', 'Maximum queue items to process', '1')
-  .option('--follow-plan', 'Only run queue items that are currently in the land_now lane')
-  .option('--merge-budget <n>', 'Maximum successful merges to allow in this run')
-  .option('--target <branch>', 'Default target branch', 'main')
-  .option('--watch', 'Keep polling for new queue items')
-  .option('--watch-interval-ms <n>', 'Polling interval for --watch mode', '1000')
-  .option('--max-cycles <n>', 'Maximum watch cycles before exiting (mainly for tests)')
-  .option('--json', 'Output raw JSON')
-  .addHelpText('after', `
-Examples:
-  switchman queue run
-  switchman queue run --follow-plan --merge-budget 2
-  switchman queue run --watch
-  switchman queue run --watch --watch-interval-ms 1000
-`)
-  .action(async (opts) => {
-    const repoRoot = getRepo();
-
-    try {
-      const watch = Boolean(opts.watch);
-      const followPlan = Boolean(opts.followPlan);
-      const watchIntervalMs = Math.max(0, Number.parseInt(opts.watchIntervalMs, 10) || 1000);
-      const maxCycles = opts.maxCycles ? Math.max(1, Number.parseInt(opts.maxCycles, 10) || 1) : null;
-      const mergeBudget = opts.mergeBudget !== undefined
-        ? Math.max(0, Number.parseInt(opts.mergeBudget, 10) || 0)
-        : null;
-      const aggregate = {
-        processed: [],
-        cycles: 0,
-        watch,
-        execution_policy: {
-          follow_plan: followPlan,
-          merge_budget: mergeBudget,
-          merged_count: 0,
-        },
-      };
-
-      while (true) {
-        const db = getDb(repoRoot);
-        const result = await runMergeQueue(db, repoRoot, {
-          maxItems: Number.parseInt(opts.maxItems, 10) || 1,
-          targetBranch: opts.target || 'main',
-          followPlan,
-          mergeBudget,
-        });
-        db.close();
-
-        aggregate.processed.push(...result.processed);
-        aggregate.summary = result.summary;
-        aggregate.deferred = result.deferred || aggregate.deferred || null;
-        aggregate.execution_policy = result.execution_policy || aggregate.execution_policy;
-        aggregate.cycles += 1;
-
-        if (!watch) break;
-        if (maxCycles && aggregate.cycles >= maxCycles) break;
-        if (mergeBudget !== null && aggregate.execution_policy.merged_count >= mergeBudget) break;
-        if (result.processed.length === 0) {
-          sleepSync(watchIntervalMs);
-        }
-      }
-
-      if (opts.json) {
-        console.log(JSON.stringify(aggregate, null, 2));
-        return;
-      }
-
-      if (aggregate.processed.length === 0) {
-        const deferredFocus = aggregate.deferred || aggregate.summary?.next || null;
-        if (deferredFocus?.recommendation?.action) {
-          console.log(chalk.yellow('No landing candidate is ready to run right now.'));
-          console.log(`  ${chalk.dim('focus:')} ${deferredFocus.id} ${deferredFocus.source_type}:${deferredFocus.source_ref}`);
-          if (followPlan) {
-            console.log(`  ${chalk.dim('policy:')} following the queue plan, so only land_now items will run automatically`);
-          }
-          if (deferredFocus.recommendation?.summary) {
-            console.log(`  ${chalk.dim('decision:')} ${deferredFocus.recommendation.summary}`);
-          }
-          if (deferredFocus.recommendation?.command) {
-            console.log(`  ${chalk.yellow('next:')} ${deferredFocus.recommendation.command}`);
-          }
-        } else {
-          console.log(chalk.dim('No queued merge items.'));
-        }
-        await maybeCaptureTelemetry('queue_used', {
-          watch,
-          cycles: aggregate.cycles,
-          processed_count: 0,
-          merged_count: 0,
-          blocked_count: 0,
-        });
-        return;
-      }
-
-      for (const entry of aggregate.processed) {
-        const item = entry.item;
-        if (entry.status === 'merged') {
-          pushSyncEvent('queue_merged', {
-            item_id: item.id,
-            source_type: item.source_type,
-            source_ref: item.source_ref,
-            source_worktree: item.source_worktree || null,
-            target_branch: item.target_branch,
-            merged_commit: item.merged_commit || null,
-          }, { worktree: item.source_worktree || null }).catch(() => {});
-          console.log(`${chalk.green('✓')} Merged ${chalk.cyan(item.id)} into ${chalk.bold(item.target_branch)}`);
-          console.log(`  ${chalk.dim('commit:')} ${item.merged_commit}`);
-        } else {
-          pushSyncEvent('queue_blocked', {
-            item_id: item.id,
-            source_type: item.source_type,
-            source_ref: item.source_ref,
-            source_worktree: item.source_worktree || null,
-            target_branch: item.target_branch,
-            error_code: item.last_error_code || null,
-            error_summary: item.last_error_summary || null,
-          }, { worktree: item.source_worktree || null }).catch(() => {});
-          console.log(`${chalk.red('✗')} Blocked ${chalk.cyan(item.id)}`);
-          console.log(`  ${chalk.red('why:')} ${item.last_error_summary}`);
-          if (item.next_action) console.log(`  ${chalk.yellow('next:')} ${item.next_action}`);
-        }
-      }
-
-      if (aggregate.execution_policy.follow_plan) {
-        console.log(`${chalk.dim('plan-aware run:')} merged ${aggregate.execution_policy.merged_count}${aggregate.execution_policy.merge_budget !== null ? ` of ${aggregate.execution_policy.merge_budget}` : ''} budgeted item(s)`);
-      }
-
-      await maybeCaptureTelemetry('queue_used', {
-        watch,
-        cycles: aggregate.cycles,
-        processed_count: aggregate.processed.length,
-        merged_count: aggregate.processed.filter((entry) => entry.status === 'merged').length,
-        blocked_count: aggregate.processed.filter((entry) => entry.status !== 'merged').length,
-      });
-    } catch (err) {
-      console.error(chalk.red(err.message));
-      process.exitCode = 1;
-    }
-  });
+registerQueueCommands(program, {
+  buildQueueStatusSummary,
+  chalk,
+  colorForHealth,
+  escalateMergeQueueItem,
+  enqueueMergeItem,
+  evaluatePipelinePolicyGate,
+  getDb,
+  getRepo,
+  healthLabel,
+  listMergeQueue,
+  listMergeQueueEvents,
+  listWorktrees,
+  maybeCaptureTelemetry,
+  preparePipelineLandingTarget,
+  printErrorWithNext,
+  pushSyncEvent,
+  renderChip,
+  renderMetricRow,
+  renderPanel,
+  renderSignalStrip,
+  removeMergeQueueItem,
+  retryMergeQueueItem,
+  runMergeQueue,
+  sleepSync,
+  statusBadge,
+});
 
 program
   .command('merge')
@@ -4331,82 +4199,6 @@ Examples:
     }
   });
 
-queueCmd
-  .command('retry <itemId>')
-  .description('Retry a blocked merge queue item')
-  .option('--json', 'Output raw JSON')
-  .action((itemId, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const item = retryMergeQueueItem(db, itemId);
-    db.close();
-
-    if (!item) {
-      printErrorWithNext(`Queue item ${itemId} is not retryable.`, 'switchman queue status');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(item, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Queue item ${chalk.cyan(item.id)} reset to retrying`);
-  });
-
-queueCmd
-  .command('escalate <itemId>')
-  .description('Mark a queue item as needing explicit operator review before landing')
-  .option('--reason <text>', 'Why this item is being escalated')
-  .option('--json', 'Output raw JSON')
-  .action((itemId, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const item = escalateMergeQueueItem(db, itemId, {
-      summary: opts.reason || null,
-      nextAction: `Run \`switchman explain queue ${itemId}\` to review the landing risk, then \`switchman queue retry ${itemId}\` when it is ready again.`,
-    });
-    db.close();
-
-    if (!item) {
-      printErrorWithNext(`Queue item ${itemId} cannot be escalated.`, 'switchman queue status');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(item, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.yellow('!')} Queue item ${chalk.cyan(item.id)} marked escalated for operator review`);
-    if (item.last_error_summary) {
-      console.log(`  ${chalk.red('why:')} ${item.last_error_summary}`);
-    }
-    if (item.next_action) {
-      console.log(`  ${chalk.yellow('next:')} ${item.next_action}`);
-    }
-  });
-
-queueCmd
-  .command('remove <itemId>')
-  .description('Remove a merge queue item')
-  .action((itemId) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const item = removeMergeQueueItem(db, itemId);
-    db.close();
-
-    if (!item) {
-      printErrorWithNext(`Queue item ${itemId} does not exist.`, 'switchman queue status');
-      process.exitCode = 1;
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Removed ${chalk.cyan(item.id)} from the merge queue`);
-  });
-
 // ── explain ───────────────────────────────────────────────────────────────────
 
 const explainCmd = program.command('explain').description('Explain why Switchman blocked something and what to do next');
@@ -5451,317 +5243,37 @@ Examples:
 
 // ── lease ────────────────────────────────────────────────────────────────────
 
-const leaseCmd = program.command('lease').alias('session').description('Manage active work sessions and keep long-running tasks alive');
-leaseCmd.addHelpText('after', `
-Plain English:
-  lease = a task currently checked out by an agent
-
-Examples:
-  switchman lease next --json
-  switchman lease heartbeat lease-123
-  switchman lease reap
-`);
-
-leaseCmd
-  .command('acquire <taskId> <worktree>')
-  .description('Start a tracked work session for a specific pending task')
-  .option('--agent <name>', 'Agent identifier for logging')
-  .option('--json', 'Output as JSON')
-  .addHelpText('after', `
-Examples:
-  switchman lease acquire task-123 agent2
-  switchman lease acquire task-123 agent2 --agent cursor
-`)
-  .action((taskId, worktree, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const task = getTask(db, taskId);
-    const lease = startTaskLease(db, taskId, worktree, opts.agent || null);
-    db.close();
-
-    if (!lease || !task) {
-      if (opts.json) console.log(JSON.stringify({ lease: null, task: null }));
-      else printErrorWithNext('Could not start a work session. The task may not exist or may already be in progress.', 'switchman task list --status pending');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify({
-        lease,
-        task: taskJsonWithLease(task, worktree, lease).task,
-      }, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Lease acquired ${chalk.dim(lease.id)}`);
-    console.log(`  ${chalk.dim('task:')} ${chalk.bold(task.title)}`);
-    console.log(`  ${chalk.dim('worktree:')} ${chalk.cyan(worktree)}`);
-  });
-
-leaseCmd
-  .command('next')
-  .description('Start the next pending task and open a tracked work session for it')
-  .option('--json', 'Output as JSON')
-  .option('--worktree <name>', 'Workspace to assign the task to (defaults to the current folder name)')
-  .option('--agent <name>', 'Agent identifier for logging')
-  .addHelpText('after', `
-Examples:
-  switchman lease next
-  switchman lease next --json
-  switchman lease next --worktree agent2 --agent cursor
-`)
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const worktreeName = getCurrentWorktreeName(opts.worktree);
-    const { task, lease, exhausted } = acquireNextTaskLeaseWithRetries(repoRoot, worktreeName, opts.agent || null);
-
-    if (!task) {
-      if (opts.json) console.log(JSON.stringify({ task: null, lease: null }));
-      else if (exhausted) console.log(chalk.dim('No pending tasks. Add one with `switchman task add "Your task"`.'));
-      else console.log(chalk.yellow('Tasks were claimed by other agents during assignment. Run again to get the next one.'));
-      return;
-    }
-
-    if (!lease) {
-      if (opts.json) console.log(JSON.stringify({ task: null, lease: null, message: 'Task claimed by another agent — try again' }));
-      else console.log(chalk.yellow('Task was just claimed by another agent. Run again to get the next one.'));
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify({
-        lease,
-        ...taskJsonWithLease(task, worktreeName, lease),
-      }, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Lease acquired: ${chalk.bold(task.title)}`);
-    pushSyncEvent('lease_acquired', { task_id: task.id, title: task.title }, { worktree: worktreeName }).catch(() => {});
-    console.log(`  ${chalk.dim('task:')} ${task.id}  ${chalk.dim('lease:')} ${lease.id}`);
-    console.log(`  ${chalk.dim('worktree:')} ${chalk.cyan(worktreeName)}  ${chalk.dim('priority:')} ${task.priority}`);
-  });
-
-leaseCmd
-  .command('list')
-  .description('List leases, newest first')
-  .option('-s, --status <status>', 'Filter by status (active|completed|failed|expired)')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const leases = listLeases(db, opts.status);
-    db.close();
-
-    if (!leases.length) {
-      console.log(chalk.dim('No leases found.'));
-      return;
-    }
-
-    console.log('');
-    for (const lease of leases) {
-      console.log(`${statusBadge(lease.status)} ${chalk.bold(lease.task_title)}`);
-      console.log(`  ${chalk.dim('lease:')} ${lease.id}  ${chalk.dim('task:')} ${lease.task_id}`);
-      console.log(`  ${chalk.dim('worktree:')} ${chalk.cyan(lease.worktree)}  ${chalk.dim('agent:')} ${lease.agent || 'unknown'}`);
-      console.log(`  ${chalk.dim('started:')} ${lease.started_at}  ${chalk.dim('heartbeat:')} ${lease.heartbeat_at}`);
-      if (lease.failure_reason) console.log(`  ${chalk.red(lease.failure_reason)}`);
-      console.log('');
-    }
-  });
-
-leaseCmd
-  .command('heartbeat <leaseId>')
-  .description('Refresh the heartbeat timestamp for an active lease')
-  .option('--agent <name>', 'Agent identifier for logging')
-  .option('--json', 'Output as JSON')
-  .action((leaseId, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const lease = heartbeatLease(db, leaseId, opts.agent || null);
-    db.close();
-
-    if (!lease) {
-      if (opts.json) console.log(JSON.stringify({ lease: null }));
-      else printErrorWithNext(`No active work session found for ${leaseId}.`, 'switchman lease list --status active');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify({ lease }, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Heartbeat refreshed for ${chalk.dim(lease.id)}`);
-    console.log(`  ${chalk.dim('task:')} ${lease.task_title}  ${chalk.dim('worktree:')} ${chalk.cyan(lease.worktree)}`);
-  });
-
-leaseCmd
-  .command('reap')
-  .description('Clean up abandoned work sessions and release their file locks')
-  .option('--stale-after-minutes <minutes>', 'Age threshold for staleness')
-  .option('--json', 'Output as JSON')
-  .addHelpText('after', `
-Examples:
-  switchman lease reap
-  switchman lease reap --stale-after-minutes 20
-`)
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const leasePolicy = loadLeasePolicy(repoRoot);
-    const staleAfterMinutes = opts.staleAfterMinutes
-      ? Number.parseInt(opts.staleAfterMinutes, 10)
-      : leasePolicy.stale_after_minutes;
-    const expired = reapStaleLeases(db, staleAfterMinutes, {
-      requeueTask: leasePolicy.requeue_task_on_reap,
-    });
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify({ stale_after_minutes: staleAfterMinutes, expired }, null, 2));
-      return;
-    }
-
-    if (!expired.length) {
-      console.log(chalk.dim(`No stale leases older than ${staleAfterMinutes} minute(s).`));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Reaped ${expired.length} stale lease(s)`);
-    for (const lease of expired) {
-      console.log(`  ${chalk.dim(lease.id)}  ${chalk.cyan(lease.worktree)} → ${lease.task_title}`);
-    }
-  });
-
-const leasePolicyCmd = leaseCmd.command('policy').description('Inspect or update the stale-lease policy for this repo');
-
-leasePolicyCmd
-  .command('set')
-  .description('Persist a stale-lease policy for this repo')
-  .option('--heartbeat-interval-seconds <seconds>', 'Recommended heartbeat interval')
-  .option('--stale-after-minutes <minutes>', 'Age threshold for staleness')
-  .option('--reap-on-status-check <boolean>', 'Automatically reap stale leases during `switchman status`')
-  .option('--requeue-task-on-reap <boolean>', 'Return stale tasks to pending instead of failing them')
-  .option('--json', 'Output as JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const current = loadLeasePolicy(repoRoot);
-    const next = {
-      ...current,
-      ...(opts.heartbeatIntervalSeconds ? { heartbeat_interval_seconds: Number.parseInt(opts.heartbeatIntervalSeconds, 10) } : {}),
-      ...(opts.staleAfterMinutes ? { stale_after_minutes: Number.parseInt(opts.staleAfterMinutes, 10) } : {}),
-      ...(opts.reapOnStatusCheck ? { reap_on_status_check: opts.reapOnStatusCheck === 'true' } : {}),
-      ...(opts.requeueTaskOnReap ? { requeue_task_on_reap: opts.requeueTaskOnReap === 'true' } : {}),
-    };
-    const path = writeLeasePolicy(repoRoot, next);
-    const saved = loadLeasePolicy(repoRoot);
-
-    if (opts.json) {
-      console.log(JSON.stringify({ path, policy: saved }, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Lease policy updated`);
-    console.log(`  ${chalk.dim(path)}`);
-    console.log(`  ${chalk.dim('heartbeat_interval_seconds:')} ${saved.heartbeat_interval_seconds}`);
-    console.log(`  ${chalk.dim('stale_after_minutes:')} ${saved.stale_after_minutes}`);
-    console.log(`  ${chalk.dim('reap_on_status_check:')} ${saved.reap_on_status_check}`);
-    console.log(`  ${chalk.dim('requeue_task_on_reap:')} ${saved.requeue_task_on_reap}`);
-  });
-
-leasePolicyCmd
-  .description('Show the active stale-lease policy for this repo')
-  .option('--json', 'Output as JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const policy = loadLeasePolicy(repoRoot);
-    if (opts.json) {
-      console.log(JSON.stringify({ policy }, null, 2));
-      return;
-    }
-
-    console.log(chalk.bold('Lease policy'));
-    console.log(`  ${chalk.dim('heartbeat_interval_seconds:')} ${policy.heartbeat_interval_seconds}`);
-    console.log(`  ${chalk.dim('stale_after_minutes:')} ${policy.stale_after_minutes}`);
-    console.log(`  ${chalk.dim('reap_on_status_check:')} ${policy.reap_on_status_check}`);
-    console.log(`  ${chalk.dim('requeue_task_on_reap:')} ${policy.requeue_task_on_reap}`);
-  });
+registerLeaseCommands(program, {
+  acquireNextTaskLeaseWithRetries,
+  chalk,
+  getCurrentWorktreeName,
+  getDb,
+  getRepo,
+  getTask,
+  heartbeatLease,
+  listLeases,
+  loadLeasePolicy,
+  pushSyncEvent,
+  reapStaleLeases,
+  startTaskLease,
+  statusBadge,
+  taskJsonWithLease,
+  writeLeasePolicy,
+});
 
 // ── worktree ───────────────────────────────────────────────────────────────────
 
-const wtCmd = program.command('worktree').alias('workspace').description('Manage registered workspaces (Git worktrees)');
-wtCmd.addHelpText('after', `
-Plain English:
-  worktree = the Git feature behind each agent workspace
-
-Examples:
-  switchman worktree list
-  switchman workspace list
-  switchman worktree sync
-`);
-
-wtCmd
-  .command('add <name> <path> <branch>')
-  .description('Register a workspace with Switchman')
-  .option('--agent <name>', 'Agent assigned to this worktree')
-  .action((name, path, branch, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    registerWorktree(db, { name, path, branch, agent: opts.agent });
-    db.close();
-    console.log(`${chalk.green('✓')} Registered worktree: ${chalk.cyan(name)}`);
-  });
-
-wtCmd
-  .command('list')
-  .description('List all registered workspaces')
-  .action(() => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const worktrees = listWorktrees(db);
-    const gitWorktrees = listGitWorktrees(repoRoot);
-
-    if (!worktrees.length && !gitWorktrees.length) {
-      db.close();
-      console.log(chalk.dim('No workspaces found. Run `switchman setup --agents 3` or `switchman worktree sync`.'));
-      return;
-    }
-
-    // Show git worktrees (source of truth) annotated with db info
-    const complianceReport = evaluateRepoCompliance(db, repoRoot, gitWorktrees);
-    console.log('');
-    console.log(chalk.bold('Git Worktrees:'));
-    for (const wt of gitWorktrees) {
-      const dbInfo = worktrees.find(d => d.path === wt.path);
-      const complianceInfo = complianceReport.worktreeCompliance.find((entry) => entry.worktree === wt.name) || null;
-      const agent = dbInfo?.agent ? chalk.cyan(dbInfo.agent) : chalk.dim('no agent');
-      const status = dbInfo?.status ? statusBadge(dbInfo.status) : chalk.dim('unregistered');
-      const compliance = complianceInfo?.compliance_state ? statusBadge(complianceInfo.compliance_state) : dbInfo?.compliance_state ? statusBadge(dbInfo.compliance_state) : chalk.dim('unknown');
-      console.log(`  ${chalk.bold(wt.name.padEnd(20))} ${status} ${compliance} branch: ${chalk.cyan(wt.branch || 'unknown')}  agent: ${agent}`);
-      console.log(`    ${chalk.dim(wt.path)}`);
-      if ((complianceInfo?.unclaimed_changed_files || []).length > 0) {
-        console.log(`    ${chalk.red('files:')} ${complianceInfo.unclaimed_changed_files.slice(0, 5).join(', ')}${complianceInfo.unclaimed_changed_files.length > 5 ? ` ${chalk.dim(`+${complianceInfo.unclaimed_changed_files.length - 5} more`)}` : ''}`);
-      }
-    }
-    console.log('');
-    db.close();
-  });
-
-wtCmd
-  .command('sync')
-  .description('Sync Git workspaces into the Switchman database')
-  .action(() => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const gitWorktrees = listGitWorktrees(repoRoot);
-    for (const wt of gitWorktrees) {
-      registerWorktree(db, { name: wt.name, path: wt.path, branch: wt.branch || 'unknown' });
-    }
-    db.close();
-    installMcpConfig([...new Set([repoRoot, ...gitWorktrees.map((wt) => wt.path)])]);
-    console.log(`${chalk.green('✓')} Synced ${gitWorktrees.length} worktree(s) from git`);
-  });
+registerWorktreeCommands(program, {
+  chalk,
+  evaluateRepoCompliance,
+  getDb,
+  getRepo,
+  installMcpConfig,
+  listGitWorktrees,
+  listWorktrees,
+  registerWorktree,
+  statusBadge,
+});
 
 // ── claim ──────────────────────────────────────────────────────────────────────
 
@@ -6183,11 +5695,47 @@ Use this first when the repo feels stuck.
       sleepSync(watchIntervalMs);
     }
 
-    if (watch) {
-      await maybeCaptureTelemetry('status_watch_used', {
-        cycles,
-        interval_ms: watchIntervalMs,
+    if (watch) {
+      await maybeCaptureTelemetry('status_watch_used', {
+        cycles,
+        interval_ms: watchIntervalMs,
+      });
+    }
+  });
+
+program
+  .command('recover')
+  .description('Recover abandoned agent work, repair safe interrupted state, and point at the right checkpoint')
+  .option('--stale-after-minutes <minutes>', 'Age threshold for stale lease recovery')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman recover
+  switchman recover --stale-after-minutes 20
+  switchman recover --json
+
+Use this when an agent crashed, a worktree was abandoned mid-task, or the repo feels stuck after interrupted work.
+`)
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const report = buildRecoverReport(db, repoRoot, {
+        staleAfterMinutes: opts.staleAfterMinutes || null,
       });
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      printRecoverSummary(report);
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, 'switchman status');
+      process.exitCode = 1;
     }
   });
 
@@ -6362,334 +5910,29 @@ Examples:
 
 // ── gate ─────────────────────────────────────────────────────────────────────
 
-const gateCmd = program.command('gate').description('Safety checks for edits, merges, and CI');
-gateCmd.addHelpText('after', `
-Examples:
-  switchman gate ci
-  switchman gate ai
-  switchman gate install-ci
-`);
-
-const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
-auditCmd._switchmanAdvanced = true;
-
-auditCmd
-  .command('change <pipelineId>')
-  .description('Show a signed, operator-friendly history for one pipeline')
-  .option('--json', 'Output raw JSON')
-  .action((pipelineId, options) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-
-    try {
-      const report = buildPipelineHistoryReport(db, repoRoot, pipelineId);
-      db.close();
-
-      if (options.json) {
-        console.log(JSON.stringify(report, null, 2));
-        return;
-      }
-
-      console.log(chalk.bold(`Audit history for pipeline ${report.pipeline_id}`));
-      console.log(`  ${chalk.dim('title:')} ${report.title}`);
-      console.log(`  ${chalk.dim('events:')} ${report.events.length}`);
-      console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
-      for (const event of report.events.slice(-20)) {
-        const status = event.status ? ` ${statusBadge(event.status).trim()}` : '';
-        console.log(`  ${chalk.dim(event.created_at)} ${chalk.cyan(event.label)}${status}`);
-        console.log(`    ${event.summary}`);
-      }
-    } catch (err) {
-      db.close();
-      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
-      process.exitCode = 1;
-    }
-  });
-
-auditCmd
-  .command('verify')
-  .description('Verify the audit log hash chain and project signatures')
-  .option('--json', 'Output verification details as JSON')
-  .action((options) => {
-    const repo = getRepo();
-    const db = getDb(repo);
-    const result = verifyAuditTrail(db);
-
-    if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
-      process.exit(result.ok ? 0 : 1);
-    }
-
-    if (result.ok) {
-      console.log(chalk.green(`Audit trail verified: ${result.count} signed events in order.`));
-      return;
-    }
-
-    console.log(chalk.red(`Audit trail verification failed: ${result.failures.length} problem(s) across ${result.count} events.`));
-    for (const failure of result.failures.slice(0, 10)) {
-      const prefix = failure.sequence ? `#${failure.sequence}` : `event ${failure.id}`;
-      console.log(`  ${chalk.red(prefix)} ${failure.reason_code}: ${failure.message}`);
-    }
-    if (result.failures.length > 10) {
-      console.log(chalk.dim(`  ...and ${result.failures.length - 10} more`));
-    }
-    process.exit(1);
-  });
-
-gateCmd
-  .command('commit')
-  .description('Validate current worktree changes against the active lease and claims')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const result = runCommitGate(db, repoRoot);
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (result.ok) {
-      console.log(`${chalk.green('✓')} ${result.summary}`);
-    } else {
-      console.log(chalk.red(`✗ ${result.summary}`));
-      for (const violation of result.violations) {
-        const label = violation.file || '(worktree)';
-        console.log(`  ${chalk.yellow(label)} ${chalk.dim(violation.reason_code)}`);
-      }
-    }
-
-    if (!result.ok) process.exitCode = 1;
-  });
-
-gateCmd
-  .command('merge')
-  .description('Validate current worktree changes before recording a merge commit')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const result = runCommitGate(db, repoRoot);
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (result.ok) {
-      console.log(`${chalk.green('✓')} Merge gate passed for ${chalk.cyan(result.worktree || 'current worktree')}.`);
-    } else {
-      console.log(chalk.red(`✗ Merge gate rejected changes in ${chalk.cyan(result.worktree || 'current worktree')}.`));
-      for (const violation of result.violations) {
-        const label = violation.file || '(worktree)';
-        console.log(`  ${chalk.yellow(label)} ${chalk.dim(violation.reason_code)}`);
-      }
-    }
-
-    if (!result.ok) process.exitCode = 1;
-  });
-
-gateCmd
-  .command('install')
-  .description('Install git hooks that run the Switchman commit and merge gates')
-  .action(() => {
-    const repoRoot = getRepo();
-    const hookPaths = installGateHooks(repoRoot);
-    console.log(`${chalk.green('✓')} Installed pre-commit hook at ${chalk.cyan(hookPaths.pre_commit)}`);
-    console.log(`${chalk.green('✓')} Installed pre-merge-commit hook at ${chalk.cyan(hookPaths.pre_merge_commit)}`);
-  });
-
-gateCmd
-  .command('ci')
-  .description('Run a repo-level enforcement gate suitable for CI, merges, or PR validation')
-  .option('--github', 'Write GitHub Actions step summary/output when GITHUB_* env vars are present')
-  .option('--github-step-summary <path>', 'Path to write GitHub Actions step summary markdown')
-  .option('--github-output <path>', 'Path to write GitHub Actions outputs')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const report = await scanAllWorktrees(db, repoRoot);
-    const aiGate = await runAiMergeGate(db, repoRoot);
-    db.close();
-
-    const ok = report.conflicts.length === 0
-      && report.fileConflicts.length === 0
-      && (report.ownershipConflicts?.length || 0) === 0
-      && (report.semanticConflicts?.length || 0) === 0
-      && report.unclaimedChanges.length === 0
-      && report.complianceSummary.non_compliant === 0
-      && report.complianceSummary.stale === 0
-      && aiGate.status !== 'blocked'
-      && (aiGate.dependency_invalidations?.filter((item) => item.severity === 'blocked').length || 0) === 0;
-
-    const result = {
-      ok,
-      summary: ok
-        ? `Repo gate passed for ${report.worktrees.length} worktree(s).`
-        : 'Repo gate rejected unmanaged changes, stale leases, ownership conflicts, stale dependency invalidations, or boundary validation failures.',
-      compliance: report.complianceSummary,
-      unclaimed_changes: report.unclaimedChanges,
-      file_conflicts: report.fileConflicts,
-      ownership_conflicts: report.ownershipConflicts || [],
-      semantic_conflicts: report.semanticConflicts || [],
-      branch_conflicts: report.conflicts,
-      ai_gate_status: aiGate.status,
-      boundary_validations: aiGate.boundary_validations || [],
-      dependency_invalidations: aiGate.dependency_invalidations || [],
-    };
-
-    const githubTargets = resolveGitHubOutputTargets(opts);
-    if (githubTargets.stepSummaryPath || githubTargets.outputPath) {
-      writeGitHubCiStatus({
-        result,
-        stepSummaryPath: githubTargets.stepSummaryPath,
-        outputPath: githubTargets.outputPath,
-      });
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (ok) {
-      console.log(`${chalk.green('✓')} ${result.summary}`);
-    } else {
-      console.log(chalk.red(`✗ ${result.summary}`));
-      if (result.unclaimed_changes.length > 0) {
-        console.log(chalk.bold('  Unclaimed changes:'));
-        for (const entry of result.unclaimed_changes) {
-          console.log(`    ${chalk.cyan(entry.worktree)}: ${entry.files.join(', ')}`);
-        }
-      }
-      if (result.file_conflicts.length > 0) {
-        console.log(chalk.bold('  File conflicts:'));
-        for (const conflict of result.file_conflicts) {
-          console.log(`    ${chalk.yellow(conflict.file)} ${chalk.dim(conflict.worktrees.join(', '))}`);
-        }
-      }
-      if (result.ownership_conflicts.length > 0) {
-        console.log(chalk.bold('  Ownership conflicts:'));
-        for (const conflict of result.ownership_conflicts) {
-          if (conflict.type === 'subsystem_overlap') {
-            console.log(`    ${chalk.yellow(conflict.worktreeA)} ${chalk.dim('vs')} ${chalk.yellow(conflict.worktreeB)} ${chalk.dim(`subsystem:${conflict.subsystemTag}`)}`);
-          } else {
-            console.log(`    ${chalk.yellow(conflict.worktreeA)} ${chalk.dim('vs')} ${chalk.yellow(conflict.worktreeB)} ${chalk.dim(`${conflict.scopeA} ↔ ${conflict.scopeB}`)}`);
-          }
-        }
-      }
-      if (result.semantic_conflicts.length > 0) {
-        console.log(chalk.bold('  Semantic conflicts:'));
-        for (const conflict of result.semantic_conflicts) {
-          console.log(`    ${chalk.yellow(conflict.object_name)} ${chalk.dim(`${conflict.worktreeA} vs ${conflict.worktreeB}`)}`);
-        }
-      }
-      if (result.branch_conflicts.length > 0) {
-        console.log(chalk.bold('  Branch conflicts:'));
-        for (const conflict of result.branch_conflicts) {
-          console.log(`    ${chalk.yellow(conflict.worktreeA)} ${chalk.dim('vs')} ${chalk.yellow(conflict.worktreeB)}`);
-        }
-      }
-      if (result.boundary_validations.length > 0) {
-        console.log(chalk.bold('  Boundary validations:'));
-        for (const validation of result.boundary_validations) {
-          console.log(`    ${chalk.yellow(validation.task_id)} ${chalk.dim(validation.missing_task_types.join(', '))}`);
-        }
-      }
-      if (result.dependency_invalidations.length > 0) {
-        console.log(chalk.bold('  Stale dependency invalidations:'));
-        for (const invalidation of result.dependency_invalidations) {
-          console.log(`    ${chalk.yellow(invalidation.affected_task_id)} ${chalk.dim(invalidation.stale_area)}`);
-        }
-      }
-    }
-
-    await maybeCaptureTelemetry(ok ? 'gate_ci_passed' : 'gate_ci_failed', {
-      worktree_count: report.worktrees.length,
-      unclaimed_change_count: result.unclaimed_changes.length,
-      file_conflict_count: result.file_conflicts.length,
-      ownership_conflict_count: result.ownership_conflicts.length,
-      semantic_conflict_count: result.semantic_conflicts.length,
-      branch_conflict_count: result.branch_conflicts.length,
-    });
-
-    if (!ok) process.exitCode = 1;
-  });
-
-gateCmd
-  .command('install-ci')
-  .description('Install a GitHub Actions workflow that runs the Switchman CI gate on PRs and pushes')
-  .option('--workflow-name <name>', 'Workflow file name', 'switchman-gate.yml')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const workflowPath = installGitHubActionsWorkflow(repoRoot, opts.workflowName);
-    console.log(`${chalk.green('✓')} Installed GitHub Actions workflow at ${chalk.cyan(workflowPath)}`);
-  });
-
-gateCmd
-  .command('ai')
-  .description('Run the AI-style merge check to assess risky overlap across workspaces')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const result = await runAiMergeGate(db, repoRoot);
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      const badge = result.status === 'pass'
-        ? chalk.green('PASS')
-        : result.status === 'warn'
-          ? chalk.yellow('WARN')
-          : chalk.red('BLOCK');
-      console.log(`${badge} ${result.summary}`);
-
-      const riskyPairs = result.pairs.filter((pair) => pair.status !== 'pass');
-      if (riskyPairs.length > 0) {
-        console.log(chalk.bold('  Risky pairs:'));
-        for (const pair of riskyPairs) {
-          console.log(`    ${chalk.cyan(pair.worktree_a)} ${chalk.dim('vs')} ${chalk.cyan(pair.worktree_b)} ${chalk.dim(pair.status)} ${chalk.dim(`score=${pair.score}`)}`);
-          for (const reason of pair.reasons.slice(0, 3)) {
-            console.log(`      ${chalk.yellow(reason)}`);
-          }
-        }
-      }
-
-      if ((result.boundary_validations?.length || 0) > 0) {
-        console.log(chalk.bold('  Boundary validations:'));
-        for (const validation of result.boundary_validations.slice(0, 5)) {
-          console.log(`    ${chalk.cyan(validation.task_id)} ${chalk.dim(validation.severity)} ${chalk.dim(validation.missing_task_types.join(', '))}`);
-          if (validation.rationale?.[0]) {
-            console.log(`      ${chalk.yellow(validation.rationale[0])}`);
-          }
-        }
-      }
-
-      if ((result.dependency_invalidations?.length || 0) > 0) {
-        console.log(chalk.bold('  Stale dependency invalidations:'));
-        for (const invalidation of result.dependency_invalidations.slice(0, 5)) {
-          console.log(`    ${chalk.cyan(invalidation.affected_task_id)} ${chalk.dim(invalidation.severity)} ${chalk.dim(invalidation.stale_area)}`);
-        }
-      }
-
-      if ((result.semantic_conflicts?.length || 0) > 0) {
-        console.log(chalk.bold('  Semantic conflicts:'));
-        for (const conflict of result.semantic_conflicts.slice(0, 5)) {
-          console.log(`    ${chalk.cyan(conflict.object_name)} ${chalk.dim(conflict.type)} ${chalk.dim(`${conflict.worktreeA} vs ${conflict.worktreeB}`)}`);
-        }
-      }
-
-      const riskyWorktrees = result.worktrees.filter((worktree) => worktree.findings.length > 0);
-      if (riskyWorktrees.length > 0) {
-        console.log(chalk.bold('  Worktree signals:'));
-        for (const worktree of riskyWorktrees) {
-          console.log(`    ${chalk.cyan(worktree.worktree)} ${chalk.dim(`score=${worktree.score}`)}`);
-          for (const finding of worktree.findings.slice(0, 2)) {
-            console.log(`      ${chalk.yellow(finding)}`);
-          }
-        }
-      }
-    }
+registerAuditCommands(program, {
+  buildPipelineHistoryReport,
+  chalk,
+  getDb,
+  getRepo,
+  printErrorWithNext,
+  statusBadge,
+  verifyAuditTrail,
+});
 
-    if (result.status === 'blocked') process.exitCode = 1;
-  });
+registerGateCommands(program, {
+  chalk,
+  getDb,
+  getRepo,
+  installGateHooks,
+  installGitHubActionsWorkflow,
+  maybeCaptureTelemetry,
+  resolveGitHubOutputTargets,
+  runAiMergeGate,
+  runCommitGate,
+  scanAllWorktrees,
+  writeGitHubCiStatus,
+});
 
 const semanticCmd = program
   .command('semantic')
@@ -6792,180 +6035,20 @@ objectCmd
 
 // ── monitor ──────────────────────────────────────────────────────────────────
 
-const monitorCmd = program.command('monitor').description('Observe workspaces for runtime file changes');
-monitorCmd._switchmanAdvanced = true;
-
-monitorCmd
-  .command('once')
-  .description('Capture one monitoring pass and log observed file changes')
-  .option('--json', 'Output raw JSON')
-  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const worktrees = resolveMonitoredWorktrees(db, repoRoot);
-    const result = monitorWorktreesOnce(db, repoRoot, worktrees, { quarantine: opts.quarantine });
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    if (result.events.length === 0) {
-      console.log(chalk.dim('No file changes observed since the last monitor snapshot.'));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Observed ${result.summary.total} file change(s)`);
-    for (const event of result.events) {
-      renderMonitorEvent(event);
-    }
-  });
-
-monitorCmd
-  .command('watch')
-  .description('Poll workspaces continuously and log observed file changes')
-  .option('--interval-ms <ms>', 'Polling interval in milliseconds', '2000')
-  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
-  .option('--daemonized', 'Internal flag used by monitor start', false)
-  .action(async (opts) => {
-    const repoRoot = getRepo();
-    const intervalMs = Number.parseInt(opts.intervalMs, 10);
-
-    if (!Number.isFinite(intervalMs) || intervalMs < 100) {
-      console.error(chalk.red('--interval-ms must be at least 100'));
-      process.exit(1);
-    }
-
-    console.log(chalk.cyan(`Watching workspaces every ${intervalMs}ms. Press Ctrl+C to stop.`));
-
-    let stopped = false;
-    const stop = () => {
-      stopped = true;
-      process.stdout.write('\n');
-      if (opts.daemonized) {
-        clearMonitorState(repoRoot);
-      }
-    };
-    process.on('SIGINT', stop);
-    process.on('SIGTERM', stop);
-
-    while (!stopped) {
-      const db = getDb(repoRoot);
-      const worktrees = resolveMonitoredWorktrees(db, repoRoot);
-      const result = monitorWorktreesOnce(db, repoRoot, worktrees, { quarantine: opts.quarantine });
-      db.close();
-
-      for (const event of result.events) {
-        renderMonitorEvent(event);
-      }
-
-      if (stopped) break;
-      await new Promise((resolvePromise) => setTimeout(resolvePromise, intervalMs));
-    }
-
-    console.log(chalk.dim('Stopped worktree monitor.'));
-  });
-
-monitorCmd
-  .command('start')
-  .description('Start the worktree monitor as a background process')
-  .option('--interval-ms <ms>', 'Polling interval in milliseconds', '2000')
-  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const intervalMs = Number.parseInt(opts.intervalMs, 10);
-    const state = startBackgroundMonitor(repoRoot, {
-      intervalMs,
-      quarantine: Boolean(opts.quarantine),
-    });
-
-    if (state.already_running) {
-      console.log(chalk.yellow(`Monitor already running with pid ${state.state.pid}`));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Started monitor pid ${chalk.cyan(String(state.state.pid))}`);
-    console.log(`${chalk.dim('State:')} ${state.state_path}`);
-  });
-
-monitorCmd
-  .command('stop')
-  .description('Stop the background worktree monitor')
-  .action(() => {
-    const repoRoot = getRepo();
-    const state = readMonitorState(repoRoot);
-
-    if (!state) {
-      console.log(chalk.dim('Monitor is not running.'));
-      return;
-    }
-
-    if (!isProcessRunning(state.pid)) {
-      clearMonitorState(repoRoot);
-      console.log(chalk.dim('Monitor state was stale and has been cleared.'));
-      return;
-    }
-
-    process.kill(state.pid, 'SIGTERM');
-    clearMonitorState(repoRoot);
-    console.log(`${chalk.green('✓')} Stopped monitor pid ${chalk.cyan(String(state.pid))}`);
-  });
-
-monitorCmd
-  .command('status')
-  .description('Show background monitor process status')
-  .action(() => {
-    const repoRoot = getRepo();
-    const state = readMonitorState(repoRoot);
-
-    if (!state) {
-      console.log(chalk.dim('Monitor is not running.'));
-      return;
-    }
-
-    const running = isProcessRunning(state.pid);
-    if (!running) {
-      clearMonitorState(repoRoot);
-      console.log(chalk.yellow('Monitor state existed but the process is no longer running.'));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Monitor running`);
-    console.log(`  ${chalk.dim('pid')} ${state.pid}`);
-    console.log(`  ${chalk.dim('interval_ms')} ${state.interval_ms}`);
-    console.log(`  ${chalk.dim('quarantine')} ${state.quarantine ? 'true' : 'false'}`);
-    console.log(`  ${chalk.dim('started_at')} ${state.started_at}`);
-  });
-
-program
-  .command('watch')
-  .description('Watch worktrees for direct writes and rogue edits in real time')
-  .option('--interval-ms <ms>', 'Polling interval in milliseconds', '2000')
-  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
-  .action(async (opts) => {
-    const repoRoot = getRepo();
-    const child = spawn(process.execPath, [
-      process.argv[1],
-      'monitor',
-      'watch',
-      '--interval-ms',
-      String(opts.intervalMs || '2000'),
-      ...(opts.quarantine ? ['--quarantine'] : []),
-    ], {
-      cwd: repoRoot,
-      stdio: 'inherit',
-    });
-
-    await new Promise((resolve, reject) => {
-      child.on('exit', (code) => {
-        process.exitCode = code ?? 0;
-        resolve();
-      });
-      child.on('error', reject);
-    });
-  });
+registerMonitorCommands(program, {
+  chalk,
+  clearMonitorState,
+  getDb,
+  getRepo,
+  isProcessRunning,
+  monitorWorktreesOnce,
+  processExecPath: process.execPath,
+  readMonitorState,
+  renderMonitorEvent,
+  resolveMonitoredWorktrees,
+  spawn,
+  startBackgroundMonitor,
+});
 
 // ── policy ───────────────────────────────────────────────────────────────────