switchman-dev 0.1.6 → 0.1.7

package/src/cli/index.js

@@ -19,31 +19,36 @@
 import { program } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
-import { existsSync } from 'fs';
-import { join } from 'path';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { dirname, join, posix } from 'path';
 import { execSync, spawn } from 'child_process';
 
-import { findRepoRoot, listGitWorktrees, createGitWorktree } from '../core/git.js';
+import { cleanupCrashedLandingTempWorktrees, findRepoRoot, listGitWorktrees, createGitWorktree } from '../core/git.js';
+import { matchesPathPatterns } from '../core/ignore.js';
 import {
   initDb, openDb,
   DEFAULT_STALE_LEASE_MINUTES,
   createTask, startTaskLease, completeTask, failTask, getBoundaryValidationState, getTaskSpec, listTasks, getTask, getNextPendingTask,
   listDependencyInvalidations, listLeases, listScopeReservations, heartbeatLease, getStaleLeases, reapStaleLeases,
-  registerWorktree, listWorktrees,
-  enqueueMergeItem, getMergeQueueItem, listMergeQueue, listMergeQueueEvents, removeMergeQueueItem, retryMergeQueueItem,
-  claimFiles, releaseFileClaims, getActiveFileClaims, checkFileConflicts,
-  verifyAuditTrail,
+  registerWorktree, listWorktrees, updateWorktreeStatus,
+  enqueueMergeItem, escalateMergeQueueItem, getMergeQueueItem, listMergeQueue, listMergeQueueEvents, removeMergeQueueItem, retryMergeQueueItem,
+  markMergeQueueState,
+  createPolicyOverride, listPolicyOverrides, revokePolicyOverride,
+  finishOperationJournalEntry, listOperationJournal, listTempResources, updateTempResource,
+  claimFiles, releaseFileClaims, getActiveFileClaims, checkFileConflicts, retryTask,
+  listAuditEvents, verifyAuditTrail,
 } from '../core/db.js';
 import { scanAllWorktrees } from '../core/detector.js';
 import { getWindsurfMcpConfigPath, upsertAllProjectMcpConfigs, upsertWindsurfMcpConfig } from '../core/mcp.js';
 import { gatewayAppendFile, gatewayMakeDirectory, gatewayMovePath, gatewayRemovePath, gatewayWriteFile, installGateHooks, monitorWorktreesOnce, runCommitGate, runWrappedCommand, writeEnforcementPolicy } from '../core/enforcement.js';
 import { runAiMergeGate } from '../core/merge-gate.js';
 import { clearMonitorState, getMonitorStatePath, isProcessRunning, readMonitorState, writeMonitorState } from '../core/monitor.js';
-import { buildPipelinePrSummary, createPipelineFollowupTasks, executePipeline, exportPipelinePrBundle, getPipelineStatus, publishPipelinePr, runPipeline, startPipeline } from '../core/pipeline.js';
-import { installGitHubActionsWorkflow, resolveGitHubOutputTargets, writeGitHubCiStatus } from '../core/ci.js';
+import { buildPipelinePrSummary, cleanupPipelineLandingRecovery, commentPipelinePr, createPipelineFollowupTasks, evaluatePipelinePolicyGate, executePipeline, exportPipelinePrBundle, getPipelineLandingBranchStatus, getPipelineLandingExplainReport, getPipelineStatus, inferPipelineIdFromBranch, materializePipelineLandingBranch, preparePipelineLandingRecovery, preparePipelineLandingTarget, publishPipelinePr, repairPipelineState, resumePipelineLandingRecovery, runPipeline, startPipeline, summarizePipelinePolicyState, syncPipelinePr } from '../core/pipeline.js';
+import { installGitHubActionsWorkflow, resolveGitHubOutputTargets, writeGitHubCiStatus, writeGitHubPipelineLandingStatus } from '../core/ci.js';
 import { importCodeObjectsToStore, listCodeObjects, materializeCodeObjects, materializeSemanticIndex, updateCodeObjectSource } from '../core/semantic.js';
-import { buildQueueStatusSummary, runMergeQueue } from '../core/queue.js';
-import { DEFAULT_LEASE_POLICY, loadLeasePolicy, writeLeasePolicy } from '../core/policy.js';
+import { buildQueueStatusSummary, resolveQueueSource, runMergeQueue } from '../core/queue.js';
+import { DEFAULT_CHANGE_POLICY, DEFAULT_LEASE_POLICY, getChangePolicyPath, loadChangePolicy, loadLeasePolicy, writeChangePolicy, writeLeasePolicy } from '../core/policy.js';
 import {
   captureTelemetryEvent,
   disableTelemetry,
@@ -55,6 +60,17 @@ import {
   sendTelemetryEvent,
 } from '../core/telemetry.js';
 
+const originalProcessEmit = process.emit.bind(process);
+process.emit = function patchedProcessEmit(event, ...args) {
+  if (event === 'warning') {
+    const [warning] = args;
+    if (warning?.name === 'ExperimentalWarning' && warning?.message?.includes('SQLite')) {
+      return false;
+    }
+  }
+  return originalProcessEmit(event, ...args);
+};
+
 function installMcpConfig(targetDirs) {
   return targetDirs.flatMap((targetDir) => upsertAllProjectMcpConfigs(targetDir));
 }
@@ -79,6 +95,54 @@ function getDb(repoRoot) {
   }
 }
 
+function resolvePrNumberFromEnv(env = process.env) {
+  if (env.SWITCHMAN_PR_NUMBER) return String(env.SWITCHMAN_PR_NUMBER);
+  if (env.GITHUB_PR_NUMBER) return String(env.GITHUB_PR_NUMBER);
+
+  if (env.GITHUB_EVENT_PATH && existsSync(env.GITHUB_EVENT_PATH)) {
+    try {
+      const payload = JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, 'utf8'));
+      const prNumber = payload.pull_request?.number || payload.issue?.number || null;
+      if (prNumber) return String(prNumber);
+    } catch {
+      // Ignore malformed GitHub event payloads.
+    }
+  }
+
+  return null;
+}
+
+function resolveBranchFromEnv(env = process.env) {
+  return env.SWITCHMAN_BRANCH
+    || env.GITHUB_HEAD_REF
+    || env.GITHUB_REF_NAME
+    || null;
+}
+
+function retryStaleTasks(db, { pipelineId = null, reason = 'bulk stale retry' } = {}) {
+  const invalidations = listDependencyInvalidations(db, { pipelineId });
+  const staleTaskIds = [...new Set(invalidations.map((item) => item.affected_task_id).filter(Boolean))];
+  const retried = [];
+  const skipped = [];
+
+  for (const taskId of staleTaskIds) {
+    const task = retryTask(db, taskId, reason);
+    if (task) {
+      retried.push(task);
+    } else {
+      skipped.push(taskId);
+    }
+  }
+
+  return {
+    pipeline_id: pipelineId,
+    stale_task_ids: staleTaskIds,
+    retried,
+    skipped,
+    invalidation_count: invalidations.length,
+  };
+}
+
 function statusBadge(status) {
   const colors = {
     pending: chalk.yellow,
@@ -234,227 +298,1415 @@ function printErrorWithNext(message, nextCommand = null) {
   }
 }
 
-async function maybeCaptureTelemetry(event, properties = {}, { homeDir = null } = {}) {
-  try {
-    await maybePromptForTelemetry({ homeDir: homeDir || undefined });
-    await captureTelemetryEvent(event, {
-      app_version: program.version(),
-      os: process.platform,
-      node_version: process.version,
-      ...properties,
-    }, { homeDir: homeDir || undefined });
-  } catch {
-    // Telemetry must never block CLI usage.
-  }
+function writeDemoFile(filePath, contents) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, contents);
 }
 
-function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
-  const dbPath = join(repoRoot, '.switchman', 'switchman.db');
-  const rootMcpPath = join(repoRoot, '.mcp.json');
-  const cursorMcpPath = join(repoRoot, '.cursor', 'mcp.json');
-  const claudeGuidePath = join(repoRoot, 'CLAUDE.md');
-  const checks = [];
-  const nextSteps = [];
-  let workspaces = [];
-  let db = null;
-
-  const dbExists = existsSync(dbPath);
-  checks.push({
-    key: 'database',
-    ok: dbExists,
-    label: 'Project database',
-    detail: dbExists ? '.switchman/switchman.db is ready' : 'Switchman database is missing',
+function gitCommitAll(worktreePath, message) {
+  execSync('git add .', {
+    cwd: worktreePath,
+    stdio: ['ignore', 'pipe', 'pipe'],
   });
-  if (!dbExists) {
-    nextSteps.push('Run `switchman init` or `switchman setup --agents 3` in this repo.');
-  }
+  execSync(`git -c user.email="demo@switchman.dev" -c user.name="Switchman Demo" commit -m ${JSON.stringify(message)}`, {
+    cwd: worktreePath,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
 
-  if (dbExists) {
+async function runDemoScenario({ repoPath = null, cleanup = false } = {}) {
+  const repoDir = repoPath || join(tmpdir(), `switchman-demo-${Date.now()}`);
+  mkdirSync(repoDir, { recursive: true });
+
+  try {
+    execSync('git init -b main', { cwd: repoDir, stdio: ['ignore', 'pipe', 'pipe'] });
+    execSync('git config user.email "demo@switchman.dev"', { cwd: repoDir, stdio: ['ignore', 'pipe', 'pipe'] });
+    execSync('git config user.name "Switchman Demo"', { cwd: repoDir, stdio: ['ignore', 'pipe', 'pipe'] });
+
+    writeDemoFile(join(repoDir, 'README.md'), '# Switchman demo repo\n');
+    writeDemoFile(join(repoDir, 'src', 'index.js'), 'export function ready() {\n  return true;\n}\n');
+    writeDemoFile(join(repoDir, 'docs', 'overview.md'), '# Demo\n');
+    gitCommitAll(repoDir, 'Initial demo repo');
+
+    const db = initDb(repoDir);
+    registerWorktree(db, { name: 'main', path: repoDir, branch: 'main' });
+
+    const agent1Path = createGitWorktree(repoDir, 'agent1', 'switchman/demo-agent1');
+    const agent2Path = createGitWorktree(repoDir, 'agent2', 'switchman/demo-agent2');
+    registerWorktree(db, { name: 'agent1', path: agent1Path, branch: 'switchman/demo-agent1' });
+    registerWorktree(db, { name: 'agent2', path: agent2Path, branch: 'switchman/demo-agent2' });
+
+    const taskAuth = createTask(db, {
+      id: 'demo-01',
+      title: 'Add auth helper',
+      priority: 9,
+    });
+    const taskDocs = createTask(db, {
+      id: 'demo-02',
+      title: 'Document auth flow',
+      priority: 8,
+    });
+
+    const lease1 = startTaskLease(db, taskAuth, 'agent1');
+    claimFiles(db, taskAuth, 'agent1', ['src/auth.js']);
+
+    const lease2 = startTaskLease(db, taskDocs, 'agent2');
+    let blockedClaimMessage = null;
     try {
-      db = getDb(repoRoot);
-      workspaces = listWorktrees(db);
-    } catch {
-      checks.push({
-        key: 'database_open',
-        ok: false,
-        label: 'Database access',
-        detail: 'Switchman could not open the project database',
-      });
-      nextSteps.push('Re-run `switchman init` if the project database looks corrupted.');
-    } finally {
-      try { db?.close(); } catch { /* no-op */ }
+      claimFiles(db, taskDocs, 'agent2', ['src/auth.js']);
+    } catch (err) {
+      blockedClaimMessage = String(err.message || 'Claim blocked.');
     }
-  }
+    claimFiles(db, taskDocs, 'agent2', ['docs/auth-flow.md']);
 
-  const agentWorkspaces = workspaces.filter((entry) => entry.name !== 'main');
-  const workspaceReady = agentWorkspaces.length > 0;
-  checks.push({
-    key: 'workspaces',
-    ok: workspaceReady,
-    label: 'Agent workspaces',
-    detail: workspaceReady
-      ? `${agentWorkspaces.length} agent workspace(s) registered`
-      : 'No agent workspaces are registered yet',
-  });
-  if (!workspaceReady) {
-    nextSteps.push('Run `switchman setup --agents 3` to create agent workspaces.');
-  }
+    writeDemoFile(join(agent1Path, 'src', 'auth.js'), 'export function authHeader(token) {\n  return `Bearer ${token}`;\n}\n');
+    gitCommitAll(agent1Path, 'Add auth helper');
+    completeTask(db, taskAuth);
 
-  const rootMcpExists = existsSync(rootMcpPath);
-  checks.push({
-    key: 'claude_mcp',
-    ok: rootMcpExists,
-    label: 'Claude Code MCP',
-    detail: rootMcpExists ? '.mcp.json is present in the repo root' : '.mcp.json is missing from the repo root',
-  });
-  if (!rootMcpExists) {
-    nextSteps.push('Re-run `switchman setup --agents 3` to restore the repo-local MCP config.');
+    writeDemoFile(join(agent2Path, 'docs', 'auth-flow.md'), '# Auth flow\n\n- claims stop overlap early\n');
+    gitCommitAll(agent2Path, 'Document auth flow');
+    completeTask(db, taskDocs);
+
+    enqueueMergeItem(db, {
+      sourceType: 'worktree',
+      sourceRef: 'agent1',
+      sourceWorktree: 'agent1',
+      targetBranch: 'main',
+    });
+    enqueueMergeItem(db, {
+      sourceType: 'worktree',
+      sourceRef: 'agent2',
+      sourceWorktree: 'agent2',
+      targetBranch: 'main',
+    });
+
+    const queueRun = await runMergeQueue(db, repoDir, {
+      maxItems: 2,
+      targetBranch: 'main',
+    });
+    const queueItems = listMergeQueue(db);
+    const gateReport = await scanAllWorktrees(db, repoDir);
+    const aiGate = await runAiMergeGate(db, repoDir);
+
+    const result = {
+      repo_path: repoDir,
+      worktrees: listWorktrees(db).map((worktree) => ({
+        name: worktree.name,
+        path: worktree.path,
+        branch: worktree.branch,
+      })),
+      tasks: listTasks(db).map((task) => ({
+        id: task.id,
+        title: task.title,
+        status: task.status,
+      })),
+      overlap_demo: {
+        blocked_path: 'src/auth.js',
+        blocked_message: blockedClaimMessage,
+        safe_path: 'docs/auth-flow.md',
+        leases: [lease1.id, lease2.id],
+      },
+      queue: {
+        processed: queueRun.processed.map((entry) => ({
+          status: entry.status,
+          item_id: entry.item?.id || null,
+          source_ref: entry.item?.source_ref || null,
+        })),
+        final_items: queueItems.map((item) => ({
+          id: item.id,
+          status: item.status,
+          source_ref: item.source_ref,
+        })),
+      },
+      final_gate: {
+        ok: gateReport.conflicts.length === 0
+          && gateReport.fileConflicts.length === 0
+          && gateReport.unclaimedChanges.length === 0
+          && gateReport.complianceSummary.non_compliant === 0
+          && aiGate.status !== 'blocked',
+        ai_gate_status: aiGate.status,
+      },
+      next_steps: [
+        `cd ${repoDir}`,
+        'switchman status',
+        'switchman queue status',
+      ],
+    };
+
+    db.close();
+    if (cleanup) {
+      rmSync(repoDir, { recursive: true, force: true });
+    }
+    return result;
+  } catch (err) {
+    if (cleanup) {
+      rmSync(repoDir, { recursive: true, force: true });
+    }
+    throw err;
   }
+}
 
-  const cursorMcpExists = existsSync(cursorMcpPath);
-  checks.push({
-    key: 'cursor_mcp',
-    ok: cursorMcpExists,
-    label: 'Cursor MCP',
-    detail: cursorMcpExists ? '.cursor/mcp.json is present in the repo root' : '.cursor/mcp.json is missing from the repo root',
-  });
-  if (!cursorMcpExists) {
-    nextSteps.push('Re-run `switchman setup --agents 3` if you want Cursor to attach automatically.');
+function normalizeCliRepoPath(targetPath) {
+  const rawPath = String(targetPath || '').replace(/\\/g, '/').trim();
+  const normalized = posix.normalize(rawPath.replace(/^\.\/+/, ''));
+  if (
+    normalized === '' ||
+    normalized === '.' ||
+    normalized === '..' ||
+    normalized.startsWith('../') ||
+    rawPath.startsWith('/') ||
+    /^[A-Za-z]:\//.test(rawPath)
+  ) {
+    throw new Error('Target path must point to a file inside the repository.');
   }
+  return normalized;
+}
 
-  const claudeGuideExists = existsSync(claudeGuidePath);
-  checks.push({
-    key: 'claude_md',
-    ok: claudeGuideExists,
-    label: 'Claude guide',
-    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.');
+function buildQueueExplainReport(db, repoRoot, itemId) {
+  const item = getMergeQueueItem(db, itemId);
+  if (!item) {
+    throw new Error(`Queue item ${itemId} does not exist.`);
   }
 
-  const windsurfConfigExists = existsSync(getWindsurfMcpConfigPath(homeDir || undefined));
-  checks.push({
-    key: 'windsurf_mcp',
-    ok: windsurfConfigExists,
-    label: 'Windsurf MCP',
-    detail: windsurfConfigExists
-      ? 'Windsurf shared MCP config is installed'
-      : 'Windsurf shared MCP config is optional and not installed',
-  });
-  if (!windsurfConfigExists) {
-    nextSteps.push('If you use Windsurf, run `switchman mcp install --windsurf` once.');
+  let resolved = null;
+  let resolutionError = null;
+  try {
+    resolved = resolveQueueSource(db, repoRoot, item);
+  } catch (err) {
+    resolutionError = err.message;
   }
 
-  const ok = checks.every((item) => item.ok || ['claude_md', 'windsurf_mcp'].includes(item.key));
+  const recentEvents = listMergeQueueEvents(db, item.id, { limit: 5 });
   return {
-    ok,
-    repo_root: repoRoot,
-    checks,
-    workspaces: workspaces.map((entry) => ({
-      name: entry.name,
-      path: entry.path,
-      branch: entry.branch,
-    })),
-    suggested_commands: [
-      'switchman status --watch',
-      'switchman task add "Your first task" --priority 8',
-      'switchman gate ci',
-      ...nextSteps.some((step) => step.includes('Windsurf')) ? ['switchman mcp install --windsurf'] : [],
-    ],
-    next_steps: [...new Set(nextSteps)].slice(0, 6),
+    item,
+    resolved_source: resolved,
+    resolution_error: resolutionError,
+    next_action: item.next_action || inferQueueExplainNextAction(item, resolved, resolutionError),
+    recent_events: recentEvents,
   };
 }
 
-function renderSetupVerification(report, { compact = false } = {}) {
-  console.log(chalk.bold(compact ? 'First-run check:' : 'Setup verification:'));
-  for (const check of report.checks) {
-    const badge = boolBadge(check.ok);
-    console.log(`  ${badge} ${check.label} ${chalk.dim(`— ${check.detail}`)}`);
+function inferQueueExplainNextAction(item, resolved, resolutionError) {
+  if (item.status === 'blocked' && item.next_action) return item.next_action;
+  if (item.status === 'blocked' && item.last_error_code === 'source_missing') {
+    return `Recreate the source branch, then run \`switchman queue retry ${item.id}\`.`;
   }
-  if (report.next_steps.length > 0) {
-    console.log('');
-    console.log(chalk.bold('Fix next:'));
-    for (const step of report.next_steps) {
-      console.log(`  - ${step}`);
-    }
+  if (resolutionError) return 'Fix the source resolution issue, then re-run `switchman explain queue <itemId>` or queue a branch/worktree explicitly.';
+  if (item.status === 'retrying' && item.backoff_until) {
+    return item.next_action || `Wait until ${item.backoff_until}, or run \`switchman queue retry ${item.id}\` to retry sooner.`;
   }
-  console.log('');
-  console.log(chalk.bold('Try next:'));
-  for (const command of report.suggested_commands.slice(0, 4)) {
-    console.log(`  ${chalk.cyan(command)}`);
+  if (item.status === 'wave_blocked') {
+    return item.next_action || `Run \`switchman explain queue ${item.id}\` to review the shared stale wave, then revalidate the affected pipelines together.`;
   }
+  if (item.status === 'escalated') {
+    return item.next_action || `Run \`switchman explain queue ${item.id}\` to review the landing risk, then \`switchman queue retry ${item.id}\` when it is ready again.`;
+  }
+  if (item.status === 'queued' || item.status === 'retrying') return 'Run `switchman queue run` to continue landing queued work.';
+  if (item.status === 'merged') return 'No action needed.';
+  if (resolved?.pipeline_id) return `Run \`switchman pipeline status ${resolved.pipeline_id}\` to inspect the pipeline state.`;
+  return 'Run `switchman queue status` to inspect the landing queue.';
 }
 
-function summarizeLeaseScope(db, lease) {
-  const reservations = listScopeReservations(db, { leaseId: lease.id });
-  const pathScopes = reservations
-    .filter((reservation) => reservation.ownership_level === 'path_scope' && reservation.scope_pattern)
-    .map((reservation) => reservation.scope_pattern);
-  if (pathScopes.length === 1) return `scope:${pathScopes[0]}`;
-  if (pathScopes.length > 1) return `scope:${pathScopes.length} paths`;
+function buildClaimExplainReport(db, filePath) {
+  const normalizedPath = normalizeCliRepoPath(filePath);
+  const activeClaims = getActiveFileClaims(db);
+  const directClaims = activeClaims.filter((claim) => claim.file_path === normalizedPath);
+  const activeLeases = listLeases(db, 'active');
+  const scopeOwners = activeLeases.flatMap((lease) => {
+    const taskSpec = getTaskSpec(db, lease.task_id);
+    const patterns = taskSpec?.allowed_paths || [];
+    if (!patterns.some((pattern) => matchesPathPatterns(normalizedPath, [pattern]))) {
+      return [];
+    }
+    return [{
+      lease_id: lease.id,
+      task_id: lease.task_id,
+      task_title: lease.task_title,
+      worktree: lease.worktree,
+      agent: lease.agent || null,
+      ownership_type: 'scope',
+      allowed_paths: patterns,
+    }];
+  });
 
-  const subsystemScopes = reservations
-    .filter((reservation) => reservation.ownership_level === 'subsystem' && reservation.subsystem_tag)
-    .map((reservation) => reservation.subsystem_tag);
-  if (subsystemScopes.length === 1) return `subsystem:${subsystemScopes[0]}`;
-  if (subsystemScopes.length > 1) return `subsystem:${subsystemScopes.length}`;
-  return null;
+  return {
+    file_path: normalizedPath,
+    claims: directClaims.map((claim) => ({
+      lease_id: claim.lease_id,
+      task_id: claim.task_id,
+      task_title: claim.task_title,
+      task_status: claim.task_status,
+      worktree: claim.worktree,
+      agent: claim.agent || null,
+      ownership_type: 'claim',
+      heartbeat_at: claim.lease_heartbeat_at || null,
+    })),
+    scope_owners: scopeOwners.filter((owner, index, all) =>
+      all.findIndex((candidate) => candidate.lease_id === owner.lease_id) === index,
+    ),
+  };
 }
 
-function isBusyError(err) {
-  const message = String(err?.message || '').toLowerCase();
-  return message.includes('database is locked') || message.includes('sqlite_busy');
-}
+function buildStaleTaskExplainReport(db, taskId) {
+  const task = getTask(db, taskId);
+  if (!task) {
+    throw new Error(`Task ${taskId} does not exist.`);
+  }
 
-function humanizeReasonCode(reasonCode) {
-  const labels = {
-    no_active_lease: 'no active lease',
-    lease_expired: 'lease expired',
-    worktree_mismatch: 'wrong worktree',
-    path_not_claimed: 'path not claimed',
-    path_claimed_by_other_lease: 'claimed by another lease',
-    path_scoped_by_other_lease: 'scoped by another lease',
-    path_within_task_scope: 'within task scope',
-    policy_exception_required: 'policy exception required',
-    policy_exception_allowed: 'policy exception allowed',
-    changes_outside_claims: 'changed files outside claims',
-    changes_outside_task_scope: 'changed files outside task scope',
-    missing_expected_tests: 'missing expected tests',
-    missing_expected_docs: 'missing expected docs',
-    missing_expected_source_changes: 'missing expected source changes',
-    objective_not_evidenced: 'task objective not evidenced',
-    no_changes_detected: 'no changes detected',
-    task_execution_timeout: 'task execution timed out',
-    task_failed: 'task failed',
-    agent_command_failed: 'agent command failed',
-    rejected: 'rejected',
+  const invalidations = listDependencyInvalidations(db, { affectedTaskId: taskId });
+  return {
+    task,
+    invalidations: invalidations.map((item) => ({
+      ...item,
+      details: item.details || {},
+      revalidation_set: item.details?.revalidation_set || (item.reason_type === 'semantic_contract_drift' ? 'contract' : item.reason_type === 'semantic_object_overlap' ? 'semantic_object' : item.reason_type === 'shared_module_drift' ? 'shared_module' : item.reason_type === 'subsystem_overlap' ? 'subsystem' : 'scope'),
+      stale_area: item.reason_type === 'subsystem_overlap'
+        ? `subsystem:${item.subsystem_tag}`
+        : item.reason_type === 'semantic_contract_drift'
+          ? `contract:${(item.details?.contract_names || []).join('|') || 'unknown'}`
+        : item.reason_type === 'semantic_object_overlap'
+          ? `object:${(item.details?.object_names || []).join('|') || 'unknown'}`
+        : item.reason_type === 'shared_module_drift'
+          ? `module:${(item.details?.module_paths || []).join('|') || 'unknown'}`
+        : `${item.source_scope_pattern} ↔ ${item.affected_scope_pattern}`,
+      summary: item.reason_type === 'semantic_contract_drift'
+        ? `${item.details?.source_task_title || item.source_task_id} changed shared contract ${(item.details?.contract_names || []).join(', ') || 'unknown'}`
+        : item.reason_type === 'semantic_object_overlap'
+          ? `${item.details?.source_task_title || item.source_task_id} changed shared exported object ${(item.details?.object_names || []).join(', ') || 'unknown'}`
+          : item.reason_type === 'shared_module_drift'
+            ? `${item.details?.source_task_title || item.source_task_id} changed shared module ${(item.details?.module_paths || []).join(', ') || 'unknown'} used by ${(item.details?.dependent_files || []).join(', ') || item.affected_task_id}`
+          : `${item.details?.source_task_title || item.source_task_id} changed shared ${item.reason_type === 'subsystem_overlap' ? `subsystem:${item.subsystem_tag}` : 'scope'}`,
+    })),
+    next_action: invalidations.length > 0
+      ? `switchman task retry ${taskId}`
+      : null,
   };
-  return labels[reasonCode] || String(reasonCode || 'unknown').replace(/_/g, ' ');
 }
 
-function nextStepForReason(reasonCode) {
-  const actions = {
-    no_active_lease: 'reacquire the task or lease before writing',
-    lease_expired: 'refresh or reacquire the lease, then retry',
-    worktree_mismatch: 'run the task from the assigned worktree',
-    path_not_claimed: 'claim the file before editing it',
-    path_claimed_by_other_lease: 'wait for the other task or pick a different file',
-    changes_outside_claims: 'claim all edited files or narrow the task scope',
-    changes_outside_task_scope: 'keep edits inside allowed paths or update the plan',
-    missing_expected_tests: 'add test coverage before rerunning',
-    missing_expected_docs: 'add the expected docs change before rerunning',
-    missing_expected_source_changes: 'make a source change inside the task scope',
-    objective_not_evidenced: 'align the output more closely to the task objective',
-    no_changes_detected: 'produce a tracked change or close the task differently',
-    task_execution_timeout: 'raise the timeout or reduce task size',
-    agent_command_failed: 'inspect stderr/stdout and rerun the agent',
+function normalizeDependencyInvalidation(item) {
+  const details = item.details || {};
+  return {
+    ...item,
+    severity: item.severity || details.severity || (item.reason_type === 'semantic_contract_drift' ? 'blocked' : 'warn'),
+    details,
+    revalidation_set: details.revalidation_set || (item.reason_type === 'semantic_contract_drift' ? 'contract' : item.reason_type === 'semantic_object_overlap' ? 'semantic_object' : item.reason_type === 'shared_module_drift' ? 'shared_module' : item.reason_type === 'subsystem_overlap' ? 'subsystem' : 'scope'),
+    stale_area: item.reason_type === 'subsystem_overlap'
+      ? `subsystem:${item.subsystem_tag}`
+      : item.reason_type === 'semantic_contract_drift'
+        ? `contract:${(details.contract_names || []).join('|') || 'unknown'}`
+      : item.reason_type === 'semantic_object_overlap'
+        ? `object:${(details.object_names || []).join('|') || 'unknown'}`
+      : item.reason_type === 'shared_module_drift'
+        ? `module:${(details.module_paths || []).join('|') || 'unknown'}`
+      : `${item.source_scope_pattern} ↔ ${item.affected_scope_pattern}`,
+    summary: item.reason_type === 'semantic_contract_drift'
+      ? `${details?.source_task_title || item.source_task_id} changed shared contract ${(details.contract_names || []).join(', ') || 'unknown'}`
+      : item.reason_type === 'semantic_object_overlap'
+        ? `${details?.source_task_title || item.source_task_id} changed shared exported object ${(details.object_names || []).join(', ') || 'unknown'}`
+        : item.reason_type === 'shared_module_drift'
+          ? `${details?.source_task_title || item.source_task_id} changed shared module ${(details.module_paths || []).join(', ') || 'unknown'} used by ${(details.dependent_files || []).join(', ') || item.affected_task_id}`
+        : `${details?.source_task_title || item.source_task_id} changed shared ${item.reason_type === 'subsystem_overlap' ? `subsystem:${item.subsystem_tag}` : 'scope'}`,
   };
-  return actions[reasonCode] || null;
 }
 
-function latestTaskFailure(task) {
-  const failureLine = String(task.description || '')
+function buildStaleClusters(invalidations = []) {
+  const clusters = new Map();
+  for (const invalidation of invalidations.map(normalizeDependencyInvalidation)) {
+    const clusterKey = invalidation.affected_pipeline_id
+      ? `pipeline:${invalidation.affected_pipeline_id}`
+      : `task:${invalidation.affected_task_id}`;
+    if (!clusters.has(clusterKey)) {
+      clusters.set(clusterKey, {
+        key: clusterKey,
+        affected_pipeline_id: invalidation.affected_pipeline_id || null,
+        affected_task_ids: new Set(),
+        source_task_ids: new Set(),
+        source_task_titles: new Set(),
+        source_worktrees: new Set(),
+        affected_worktrees: new Set(),
+        stale_areas: new Set(),
+        revalidation_sets: new Set(),
+        dependent_files: new Set(),
+        dependent_areas: new Set(),
+        module_paths: new Set(),
+        invalidations: [],
+        severity: 'warn',
+        highest_affected_priority: 0,
+        highest_source_priority: 0,
+      });
+    }
+    const cluster = clusters.get(clusterKey);
+    cluster.invalidations.push(invalidation);
+    cluster.affected_task_ids.add(invalidation.affected_task_id);
+    if (invalidation.source_task_id) cluster.source_task_ids.add(invalidation.source_task_id);
+    if (invalidation.details?.source_task_title) cluster.source_task_titles.add(invalidation.details.source_task_title);
+    if (invalidation.source_worktree) cluster.source_worktrees.add(invalidation.source_worktree);
+    if (invalidation.affected_worktree) cluster.affected_worktrees.add(invalidation.affected_worktree);
+    cluster.stale_areas.add(invalidation.stale_area);
+    if (invalidation.revalidation_set) cluster.revalidation_sets.add(invalidation.revalidation_set);
+    for (const filePath of invalidation.details?.dependent_files || []) cluster.dependent_files.add(filePath);
+    for (const area of invalidation.details?.dependent_areas || []) cluster.dependent_areas.add(area);
+    for (const modulePath of invalidation.details?.module_paths || []) cluster.module_paths.add(modulePath);
+    if (invalidation.severity === 'blocked') cluster.severity = 'block';
+    cluster.highest_affected_priority = Math.max(cluster.highest_affected_priority, Number(invalidation.details?.affected_task_priority || 0));
+    cluster.highest_source_priority = Math.max(cluster.highest_source_priority, Number(invalidation.details?.source_task_priority || 0));
+  }
+
+  const clusterEntries = [...clusters.values()]
+    .map((cluster) => {
+      const affectedTaskIds = [...cluster.affected_task_ids];
+      const sourceTaskTitles = [...cluster.source_task_titles];
+      const staleAreas = [...cluster.stale_areas];
+      const sourceWorktrees = [...cluster.source_worktrees];
+      const affectedWorktrees = [...cluster.affected_worktrees];
+      return {
+        key: cluster.key,
+        affected_pipeline_id: cluster.affected_pipeline_id,
+        affected_task_ids: affectedTaskIds,
+        invalidation_count: cluster.invalidations.length,
+        source_task_ids: [...cluster.source_task_ids],
+        source_pipeline_ids: [...new Set(cluster.invalidations.map((item) => item.source_pipeline_id).filter(Boolean))],
+        source_task_titles: sourceTaskTitles,
+        source_worktrees: sourceWorktrees,
+        affected_worktrees: affectedWorktrees,
+        stale_areas: staleAreas,
+        revalidation_sets: [...cluster.revalidation_sets],
+        dependent_files: [...cluster.dependent_files],
+        dependent_areas: [...cluster.dependent_areas],
+        module_paths: [...cluster.module_paths],
+        revalidation_set_type: cluster.revalidation_sets.has('contract')
+          ? 'contract'
+          : cluster.revalidation_sets.has('shared_module')
+            ? 'shared_module'
+          : cluster.revalidation_sets.has('semantic_object')
+            ? 'semantic_object'
+            : cluster.revalidation_sets.has('subsystem')
+              ? 'subsystem'
+              : 'scope',
+        rerun_priority: cluster.severity === 'block'
+          ? (cluster.revalidation_sets.has('contract') || cluster.highest_affected_priority >= 8 ? 'urgent' : 'high')
+          : cluster.revalidation_sets.has('shared_module') && cluster.dependent_files.size >= 3
+            ? 'high'
+          : cluster.highest_affected_priority >= 8
+            ? 'high'
+            : cluster.highest_affected_priority >= 5
+              ? 'medium'
+              : 'low',
+        rerun_priority_score: (cluster.severity === 'block' ? 100 : 0)
+          + (cluster.revalidation_sets.has('contract') ? 30 : cluster.revalidation_sets.has('shared_module') ? 20 : cluster.revalidation_sets.has('semantic_object') ? 15 : 0)
+          + (cluster.highest_affected_priority * 3)
+          + (cluster.dependent_files.size * 4)
+          + (cluster.dependent_areas.size * 2)
+          + cluster.module_paths.size
+          + cluster.invalidations.length,
+        rerun_breadth_score: (cluster.dependent_files.size * 4) + (cluster.dependent_areas.size * 2) + cluster.module_paths.size,
+        highest_affected_priority: cluster.highest_affected_priority,
+        highest_source_priority: cluster.highest_source_priority,
+        severity: cluster.severity,
+        invalidations: cluster.invalidations,
+        title: cluster.affected_pipeline_id
+          ? `Pipeline ${cluster.affected_pipeline_id} has ${cluster.invalidations.length} stale ${cluster.revalidation_sets.has('contract') ? 'contract' : cluster.revalidation_sets.has('shared_module') ? 'shared-module' : cluster.revalidation_sets.has('semantic_object') ? 'semantic-object' : 'dependency'} invalidation${cluster.invalidations.length === 1 ? '' : 's'}`
+          : `${affectedTaskIds[0]} has ${cluster.invalidations.length} stale ${cluster.revalidation_sets.has('contract') ? 'contract' : cluster.revalidation_sets.has('shared_module') ? 'shared-module' : cluster.revalidation_sets.has('semantic_object') ? 'semantic-object' : 'dependency'} invalidation${cluster.invalidations.length === 1 ? '' : 's'}`,
+        detail: `${sourceTaskTitles[0] || cluster.invalidations[0]?.source_task_id || 'unknown source'} -> ${affectedWorktrees.join(', ') || 'unknown target'} (${staleAreas.join(', ')})`,
+        next_step: cluster.revalidation_sets.has('contract')
+          ? (cluster.affected_pipeline_id
+            ? 'retry the stale pipeline tasks together so the affected contract can be revalidated before merge'
+            : 'retry the stale task so the affected contract can be revalidated before merge')
+          : cluster.revalidation_sets.has('shared_module')
+            ? (cluster.affected_pipeline_id
+              ? 'retry the stale pipeline tasks together so dependent shared-module work can be revalidated before merge'
+              : 'retry the stale task so its shared-module dependency can be revalidated before merge')
+          : cluster.affected_pipeline_id
+            ? 'retry the stale pipeline tasks together so the whole cluster can be revalidated before merge'
+            : 'retry the stale task so it can be revalidated before merge',
+        command: cluster.affected_pipeline_id
+          ? `switchman task retry-stale --pipeline ${cluster.affected_pipeline_id}`
+          : `switchman task retry ${affectedTaskIds[0]}`,
+      };
+    });
+
+  const causeGroups = new Map();
+  for (const cluster of clusterEntries) {
+    const primary = cluster.invalidations[0] || {};
+    const details = primary.details || {};
+    const causeKey = cluster.revalidation_set_type === 'contract'
+      ? `contract:${(details.contract_names || []).join('|') || cluster.stale_areas.join('|')}|source:${cluster.source_task_ids.join('|') || 'unknown'}`
+      : cluster.revalidation_set_type === 'shared_module'
+        ? `shared_module:${(details.module_paths || cluster.module_paths || []).join('|') || cluster.stale_areas.join('|')}|source:${cluster.source_task_ids.join('|') || 'unknown'}`
+        : cluster.revalidation_set_type === 'semantic_object'
+          ? `semantic_object:${(details.object_names || []).join('|') || cluster.stale_areas.join('|')}|source:${cluster.source_task_ids.join('|') || 'unknown'}`
+          : `dependency:${cluster.stale_areas.join('|')}|source:${cluster.source_task_ids.join('|') || 'unknown'}`;
+    if (!causeGroups.has(causeKey)) causeGroups.set(causeKey, []);
+    causeGroups.get(causeKey).push(cluster);
+  }
+
+  for (const [causeKey, relatedClusters] of causeGroups.entries()) {
+    const relatedPipelines = [...new Set(relatedClusters.map((cluster) => cluster.affected_pipeline_id).filter(Boolean))];
+    const primary = relatedClusters[0];
+    const details = primary.invalidations[0]?.details || {};
+    const causeSummary = primary.revalidation_set_type === 'contract'
+      ? `shared contract drift in ${(details.contract_names || []).join(', ') || 'unknown contract'}`
+      : primary.revalidation_set_type === 'shared_module'
+        ? `shared module drift in ${(details.module_paths || primary.module_paths || []).join(', ') || 'unknown module'}`
+        : primary.revalidation_set_type === 'semantic_object'
+          ? `shared exported object drift in ${(details.object_names || []).join(', ') || 'unknown object'}`
+          : `shared dependency drift across ${primary.stale_areas.join(', ')}`;
+    for (let index = 0; index < relatedClusters.length; index += 1) {
+      relatedClusters[index].causal_group_id = `cause-${causeKey}`;
+      relatedClusters[index].causal_group_size = relatedClusters.length;
+      relatedClusters[index].causal_group_rank = index + 1;
+      relatedClusters[index].causal_group_summary = causeSummary;
+      relatedClusters[index].related_affected_pipelines = relatedPipelines;
+    }
+  }
+
+  return clusterEntries.sort((a, b) =>
+      b.rerun_priority_score - a.rerun_priority_score
+      || (a.severity === 'block' ? -1 : 1) - (b.severity === 'block' ? -1 : 1)
+      || (a.revalidation_set_type === 'contract' ? -1 : 1) - (b.revalidation_set_type === 'contract' ? -1 : 1)
+      || (a.revalidation_set_type === 'shared_module' ? -1 : 1) - (b.revalidation_set_type === 'shared_module' ? -1 : 1)
+      || b.invalidation_count - a.invalidation_count
+      || String(a.affected_pipeline_id || a.affected_task_ids[0]).localeCompare(String(b.affected_pipeline_id || b.affected_task_ids[0])));
+}
+
+function buildStalePipelineExplainReport(db, pipelineId) {
+  const invalidations = listDependencyInvalidations(db, { pipelineId });
+  const staleClusters = buildStaleClusters(invalidations)
+    .filter((cluster) => cluster.affected_pipeline_id === pipelineId);
+  return {
+    pipeline_id: pipelineId,
+    invalidations: invalidations.map(normalizeDependencyInvalidation),
+    stale_clusters: staleClusters,
+    next_action: staleClusters.length > 0
+      ? `switchman task retry-stale --pipeline ${pipelineId}`
+      : null,
+  };
+}
+
+function parseEventDetails(details) {
+  try {
+    return JSON.parse(details || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function pipelineOwnsAuditEvent(event, pipelineId) {
+  if (event.task_id?.startsWith(`${pipelineId}-`)) return true;
+  const details = parseEventDetails(event.details);
+  if (details.pipeline_id === pipelineId) return true;
+  if (details.source_pipeline_id === pipelineId) return true;
+  if (Array.isArray(details.task_ids) && details.task_ids.some((taskId) => String(taskId).startsWith(`${pipelineId}-`))) {
+    return true;
+  }
+  return false;
+}
+
+function fallbackEventLabel(eventType) {
+  return String(eventType || 'event')
+    .split('_')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function summarizePipelineAuditHistoryEvent(event, pipelineId) {
+  const details = parseEventDetails(event.details);
+  const defaultNextAction = `switchman pipeline status ${pipelineId}`;
+
+  switch (event.event_type) {
+    case 'pipeline_created':
+      return {
+        label: 'Pipeline created',
+        summary: `Created pipeline "${details.title || pipelineId}" with ${(details.task_ids || []).length} planned task${(details.task_ids || []).length === 1 ? '' : 's'}.`,
+        next_action: defaultNextAction,
+      };
+    case 'task_completed':
+      return {
+        label: 'Task completed',
+        summary: `Completed ${event.task_id}.`,
+        next_action: defaultNextAction,
+      };
+    case 'task_failed':
+      return {
+        label: 'Task failed',
+        summary: `Failed ${event.task_id}${event.reason_code ? ` because ${humanizeReasonCode(event.reason_code)}` : ''}.`,
+        next_action: defaultNextAction,
+      };
+    case 'task_retried':
+    case 'pipeline_task_retry_scheduled':
+      return {
+        label: 'Task retry scheduled',
+        summary: `Scheduled a retry for ${event.task_id}${details.retry_attempt ? ` (attempt ${details.retry_attempt})` : ''}.`,
+        next_action: defaultNextAction,
+      };
+    case 'dependency_invalidations_updated':
+      {
+        const reasonTypes = details.reason_types || [];
+        const revalidationSets = details.revalidation_sets || [];
+      return {
+        label: 'Stale work detected',
+        summary: `Marked stale work after ${details.source_task_title || details.source_task_id || 'an upstream task'} changed a shared boundary${revalidationSets.length > 0 ? ` across ${revalidationSets.join(', ')} revalidation` : reasonTypes.length > 0 ? ` across ${reasonTypes.join(', ')}` : ''}.`,
+        next_action: details.affected_pipeline_id
+          ? `switchman explain stale --pipeline ${details.affected_pipeline_id}`
+          : defaultNextAction,
+      };
+      }
+    case 'boundary_validation_state':
+      return {
+        label: 'Boundary validation updated',
+        summary: details.summary || 'Updated boundary validation state for the pipeline.',
+        next_action: defaultNextAction,
+      };
+    case 'pipeline_followups_created':
+      return {
+        label: 'Follow-up work created',
+        summary: `Created ${(details.created_task_ids || []).length} follow-up task${(details.created_task_ids || []).length === 1 ? '' : 's'} for review or validation.`,
+        next_action: `switchman pipeline review ${pipelineId}`,
+      };
+    case 'pipeline_pr_summary':
+      return {
+        label: 'PR summary built',
+        summary: 'Built the reviewer-facing pipeline summary.',
+        next_action: `switchman pipeline sync-pr ${pipelineId} --pr-from-env`,
+      };
+    case 'pipeline_pr_bundle_exported':
+      return {
+        label: 'PR bundle exported',
+        summary: 'Exported PR and landing artifacts for CI or review.',
+        next_action: `switchman pipeline sync-pr ${pipelineId} --pr-from-env`,
+      };
+    case 'pipeline_pr_commented':
+      return {
+        label: 'PR comment updated',
+        summary: `Updated PR #${details.pr_number || 'unknown'} with the latest pipeline status.`,
+        next_action: defaultNextAction,
+      };
+    case 'pipeline_pr_synced':
+      return {
+        label: 'PR sync completed',
+        summary: `Synced PR #${details.pr_number || 'unknown'} with bundle artifacts, comment, and CI outputs.`,
+        next_action: defaultNextAction,
+      };
+    case 'pipeline_pr_published':
+      return {
+        label: 'PR published',
+        summary: `Published pipeline PR${details.pr_number ? ` #${details.pr_number}` : ''}.`,
+        next_action: defaultNextAction,
+      };
+    case 'pipeline_landing_branch_materialized':
+      return {
+        label: event.status === 'allowed' ? 'Landing branch assembled' : 'Landing branch failed',
+        summary: event.status === 'allowed'
+          ? `Materialized synthetic landing branch ${details.branch || 'unknown'} from ${(details.component_branches || []).length} component branch${(details.component_branches || []).length === 1 ? '' : 'es'}.`
+          : `Failed to materialize the landing branch${details.failed_branch ? ` while merging ${details.failed_branch}` : ''}.`,
+        next_action: details.next_action || `switchman explain landing ${pipelineId}`,
+      };
+    case 'pipeline_landing_recovery_prepared':
+      return {
+        label: 'Landing recovery prepared',
+        summary: `Prepared a recovery worktree${details.recovery_path ? ` at ${details.recovery_path}` : ''} for the landing branch.`,
+        next_action: details.inspect_command || `switchman pipeline land ${pipelineId} --recover`,
+      };
+    case 'pipeline_landing_recovery_resumed':
+      return {
+        label: 'Landing recovery resumed',
+        summary: 'Recorded a manually resolved landing branch and marked it ready to queue again.',
+        next_action: details.resume_command || `switchman queue add --pipeline ${pipelineId}`,
+      };
+    case 'pipeline_landing_recovery_cleared':
+      return {
+        label: 'Landing recovery cleaned up',
+        summary: `Cleared the recorded landing recovery worktree${details.recovery_path ? ` at ${details.recovery_path}` : ''}.`,
+        next_action: defaultNextAction,
+      };
+    default:
+      return {
+        label: fallbackEventLabel(event.event_type),
+        summary: details.summary || fallbackEventLabel(event.event_type),
+        next_action: defaultNextAction,
+      };
+  }
+}
+
+function summarizePipelineQueueHistoryEvent(item, event) {
+  const details = parseEventDetails(event.details);
+
+  switch (event.event_type) {
+    case 'merge_queue_enqueued':
+      return {
+        label: 'Queued for landing',
+        summary: `Queued ${item.id} to land ${item.source_ref} onto ${item.target_branch}.${details.policy_override_summary ? ` ${details.policy_override_summary}` : ''}`,
+        next_action: 'switchman queue status',
+      };
+    case 'merge_queue_started':
+      return {
+        label: 'Queue processing started',
+        summary: `Started validating queue item ${item.id}.`,
+        next_action: 'switchman queue status',
+      };
+    case 'merge_queue_retried':
+      return {
+        label: 'Queue item retried',
+        summary: `Moved ${item.id} back into the landing queue for another attempt.`,
+        next_action: 'switchman queue status',
+      };
+    case 'merge_queue_state_changed':
+      return {
+        label: `Queue ${event.status || 'updated'}`,
+        summary: details.last_error_summary
+          || (event.status === 'merged'
+            ? `Merged ${item.id}${details.merged_commit ? ` at ${String(details.merged_commit).slice(0, 12)}` : ''}.`
+            : `Updated ${item.id} to ${event.status || 'unknown'}.`),
+        next_action: details.next_action || item.next_action || `switchman explain queue ${item.id}`,
+      };
+    default:
+      return {
+        label: fallbackEventLabel(event.event_type),
+        summary: fallbackEventLabel(event.event_type),
+        next_action: item.next_action || `switchman explain queue ${item.id}`,
+      };
+  }
+}
+
+function buildPipelineHistoryReport(db, repoRoot, pipelineId) {
+  const status = getPipelineStatus(db, pipelineId);
+  let landing;
+  try {
+    landing = getPipelineLandingExplainReport(db, repoRoot, pipelineId);
+  } catch (err) {
+    landing = {
+      pipeline_id: pipelineId,
+      landing: {
+        branch: null,
+        strategy: 'unresolved',
+        synthetic: false,
+        stale: false,
+        stale_reasons: [],
+        last_failure: {
+          reason_code: 'landing_not_ready',
+          summary: String(err.message || 'Landing branch is not ready yet.'),
+        },
+        last_recovery: null,
+      },
+      next_action: `switchman pipeline status ${pipelineId}`,
+    };
+  }
+  const staleClusters = buildStaleClusters(listDependencyInvalidations(db, { pipelineId }))
+    .filter((cluster) => cluster.affected_pipeline_id === pipelineId);
+  const queueItems = listMergeQueue(db)
+    .filter((item) => item.source_pipeline_id === pipelineId)
+    .map((item) => ({
+      ...item,
+      recent_events: listMergeQueueEvents(db, item.id, { limit: 20 }),
+    }));
+  const auditEvents = listAuditEvents(db, { limit: 2000 })
+    .filter((event) => pipelineOwnsAuditEvent(event, pipelineId));
+
+  const events = [
+    ...auditEvents.map((event) => {
+      const described = summarizePipelineAuditHistoryEvent(event, pipelineId);
+      return {
+        source: 'audit',
+        id: `audit:${event.id}`,
+        created_at: event.created_at,
+        event_type: event.event_type,
+        status: event.status,
+        reason_code: event.reason_code || null,
+        task_id: event.task_id || null,
+        ...described,
+      };
+    }),
+    ...queueItems.flatMap((item) => item.recent_events.map((event) => {
+      const described = summarizePipelineQueueHistoryEvent(item, event);
+      return {
+        source: 'queue',
+        id: `queue:${item.id}:${event.id}`,
+        created_at: event.created_at,
+        event_type: event.event_type,
+        status: event.status || item.status,
+        reason_code: null,
+        task_id: null,
+        queue_item_id: item.id,
+        ...described,
+      };
+    })),
+  ].sort((a, b) => {
+    const timeCompare = String(a.created_at || '').localeCompare(String(b.created_at || ''));
+    if (timeCompare !== 0) return timeCompare;
+    return a.id.localeCompare(b.id);
+  });
+
+  const blockedQueueItem = queueItems.find((item) => item.status === 'blocked');
+  const nextAction = staleClusters[0]?.command
+    || blockedQueueItem?.next_action
+    || landing.next_action
+    || `switchman pipeline status ${pipelineId}`;
+
+  return {
+    pipeline_id: pipelineId,
+    title: status.title,
+    description: status.description,
+    counts: status.counts,
+    current: {
+      stale_clusters: staleClusters,
+      queue_items: queueItems.map((item) => ({
+        id: item.id,
+        status: item.status,
+        target_branch: item.target_branch,
+        last_error_code: item.last_error_code || null,
+        last_error_summary: item.last_error_summary || null,
+        next_action: item.next_action || null,
+      })),
+      landing: {
+        branch: landing.landing.branch,
+        strategy: landing.landing.strategy,
+        synthetic: landing.landing.synthetic,
+        stale: landing.landing.stale,
+        stale_reasons: landing.landing.stale_reasons,
+        last_failure: landing.landing.last_failure,
+        last_recovery: landing.landing.last_recovery,
+      },
+    },
+    events,
+    next_action: nextAction,
+  };
+}
+
+function collectKnownPipelineIds(db) {
+  return [...new Set(
+    listTasks(db)
+      .map((task) => getTaskSpec(db, task.id)?.pipeline_id || null)
+      .filter(Boolean),
+  )].sort();
+}
+
+function reconcileWorktreeState(db, repoRoot) {
+  const actions = [];
+  const dbWorktrees = listWorktrees(db);
+  const gitWorktrees = listGitWorktrees(repoRoot);
+
+  const dbByPath = new Map(dbWorktrees.map((worktree) => [worktree.path, worktree]));
+  const dbByName = new Map(dbWorktrees.map((worktree) => [worktree.name, worktree]));
+  const gitByPath = new Map(gitWorktrees.map((worktree) => [worktree.path, worktree]));
+
+  for (const gitWorktree of gitWorktrees) {
+    const dbMatch = dbByPath.get(gitWorktree.path) || dbByName.get(gitWorktree.name) || null;
+    if (!dbMatch) {
+      registerWorktree(db, {
+        name: gitWorktree.name,
+        path: gitWorktree.path,
+        branch: gitWorktree.branch || 'unknown',
+        agent: null,
+      });
+      actions.push({
+        kind: 'git_worktree_registered',
+        worktree: gitWorktree.name,
+        path: gitWorktree.path,
+        branch: gitWorktree.branch || 'unknown',
+      });
+      continue;
+    }
+
+    if (dbMatch.path !== gitWorktree.path || dbMatch.branch !== (gitWorktree.branch || dbMatch.branch) || dbMatch.status === 'missing') {
+      registerWorktree(db, {
+        name: dbMatch.name,
+        path: gitWorktree.path,
+        branch: gitWorktree.branch || dbMatch.branch || 'unknown',
+        agent: dbMatch.agent,
+      });
+      actions.push({
+        kind: 'db_worktree_reconciled',
+        worktree: dbMatch.name,
+        path: gitWorktree.path,
+        branch: gitWorktree.branch || dbMatch.branch || 'unknown',
+      });
+    }
+  }
+
+  for (const dbWorktree of dbWorktrees) {
+    if (!gitByPath.has(dbWorktree.path) && dbWorktree.status !== 'missing') {
+      updateWorktreeStatus(db, dbWorktree.name, 'missing');
+      actions.push({
+        kind: 'db_worktree_marked_missing',
+        worktree: dbWorktree.name,
+        path: dbWorktree.path,
+        branch: dbWorktree.branch,
+      });
+    }
+  }
+
+  return actions;
+}
+
+function reconcileTrackedTempResources(db, repoRoot) {
+  const actions = [];
+  const warnings = [];
+  const gitWorktrees = listGitWorktrees(repoRoot);
+  const gitPaths = new Set(gitWorktrees.map((worktree) => worktree.path));
+  const resources = listTempResources(db, { limit: 500 }).filter((resource) => resource.status !== 'released');
+
+  for (const resource of resources) {
+    const exists = existsSync(resource.path);
+    const trackedByGit = gitPaths.has(resource.path);
+
+    if (resource.resource_type === 'landing_temp_worktree') {
+      if (!exists && !trackedByGit) {
+        updateTempResource(db, resource.id, {
+          status: 'abandoned',
+          details: JSON.stringify({
+            repaired_by: 'switchman repair',
+            reason: 'temp_worktree_missing_after_interruption',
+            path: resource.path,
+          }),
+        });
+        actions.push({
+          kind: 'temp_resource_reconciled',
+          resource_id: resource.id,
+          resource_type: resource.resource_type,
+          path: resource.path,
+          status: 'abandoned',
+        });
+      }
+      continue;
+    }
+
+    if (resource.resource_type === 'landing_recovery_worktree') {
+      if (!exists && !trackedByGit) {
+        updateTempResource(db, resource.id, {
+          status: 'abandoned',
+          details: JSON.stringify({
+            repaired_by: 'switchman repair',
+            reason: 'recovery_worktree_missing',
+            path: resource.path,
+          }),
+        });
+        actions.push({
+          kind: 'temp_resource_reconciled',
+          resource_id: resource.id,
+          resource_type: resource.resource_type,
+          path: resource.path,
+          status: 'abandoned',
+        });
+      } else if (exists && !trackedByGit) {
+        warnings.push({
+          kind: 'temp_resource_manual_review',
+          resource_id: resource.id,
+          resource_type: resource.resource_type,
+          path: resource.path,
+          status: resource.status,
+          next_action: `Inspect ${resource.path} and either re-register it or clean it up with switchman pipeline land ${resource.scope_id} --cleanup ${JSON.stringify(resource.path)}`,
+        });
+      }
+    }
+  }
+
+  return { actions, warnings };
+}
+
+function summarizeRepairReport(actions = [], warnings = [], notes = []) {
+  return {
+    auto_fixed: actions,
+    manual_review: warnings,
+    skipped: [],
+    notes,
+    counts: {
+      auto_fixed: actions.length,
+      manual_review: warnings.length,
+      skipped: 0,
+    },
+  };
+}
+
+function renderRepairLine(action) {
+  if (action.kind === 'git_worktree_registered') {
+    return `${chalk.dim('registered git worktree:')} ${action.worktree} ${action.path}`;
+  }
+  if (action.kind === 'db_worktree_reconciled') {
+    return `${chalk.dim('reconciled db worktree:')} ${action.worktree} ${action.path}`;
+  }
+  if (action.kind === 'db_worktree_marked_missing') {
+    return `${chalk.dim('marked missing db worktree:')} ${action.worktree} ${action.path}`;
+  }
+  if (action.kind === 'queue_item_blocked_missing_worktree') {
+    return `${chalk.dim('blocked queue item with missing worktree:')} ${action.queue_item_id} ${action.worktree}`;
+  }
+  if (action.kind === 'stale_temp_worktree_removed') {
+    return `${chalk.dim('removed stale temp landing worktree:')} ${action.path}`;
+  }
+  if (action.kind === 'stale_temp_worktree_pruned') {
+    return `${chalk.dim('pruned stale temp landing metadata:')} ${action.path}`;
+  }
+  if (action.kind === 'journal_operation_repaired') {
+    return `${chalk.dim('closed interrupted operation:')} ${action.operation_type} ${action.scope_type}:${action.scope_id}`;
+  }
+  if (action.kind === 'queue_item_reset') {
+    return `${chalk.dim('queue reset:')} ${action.queue_item_id} ${action.previous_status} -> ${action.status}`;
+  }
+  if (action.kind === 'pipeline_repaired') {
+    return `${chalk.dim('pipeline repair:')} ${action.pipeline_id}`;
+  }
+  if (action.kind === 'temp_resource_reconciled') {
+    return `${chalk.dim('reconciled tracked temp resource:')} ${action.resource_type} ${action.path} -> ${action.status}`;
+  }
+  return `${chalk.dim(action.kind + ':')} ${JSON.stringify(action)}`;
+}
+
+function renderRepairWarningLine(warning) {
+  if (warning.kind === 'temp_resource_manual_review') {
+    return `${chalk.yellow('manual review:')} ${warning.resource_type} ${warning.path}`;
+  }
+  return `${chalk.yellow('manual review:')} ${warning.kind}`;
+}
+
+function printRepairSummary(report, {
+  repairedHeading,
+  noRepairHeading,
+  limit = null,
+} = {}) {
+  const autoFixed = report.summary?.auto_fixed || report.actions || [];
+  const manualReview = report.summary?.manual_review || report.warnings || [];
+  const skipped = report.summary?.skipped || [];
+  const limitedAutoFixed = limit == null ? autoFixed : autoFixed.slice(0, limit);
+  const limitedManualReview = limit == null ? manualReview : manualReview.slice(0, limit);
+  const limitedSkipped = limit == null ? skipped : skipped.slice(0, limit);
+
+  console.log(report.repaired ? repairedHeading : noRepairHeading);
+  for (const note of report.notes || []) {
+    console.log(`  ${chalk.dim(note)}`);
+  }
+
+  console.log(`  ${chalk.green('auto-fixed:')} ${autoFixed.length}`);
+  for (const action of limitedAutoFixed) {
+    console.log(`    ${renderRepairLine(action)}`);
+  }
+  console.log(`  ${chalk.yellow('manual review:')} ${manualReview.length}`);
+  for (const warning of limitedManualReview) {
+    console.log(`    ${renderRepairWarningLine(warning)}`);
+  }
+  console.log(`  ${chalk.dim('skipped:')} ${skipped.length}`);
+  for (const item of limitedSkipped) {
+    console.log(`    ${chalk.dim(JSON.stringify(item))}`);
+  }
+}
+
+function repairRepoState(db, repoRoot) {
+  const actions = [];
+  const warnings = [];
+  const notes = [];
+  const repairedQueueItems = new Set();
+  for (const action of reconcileWorktreeState(db, repoRoot)) {
+    actions.push(action);
+  }
+  const tempLandingCleanup = cleanupCrashedLandingTempWorktrees(repoRoot);
+  for (const action of tempLandingCleanup.actions) {
+    actions.push(action);
+  }
+  const tempResourceReconciliation = reconcileTrackedTempResources(db, repoRoot);
+  for (const action of tempResourceReconciliation.actions) {
+    actions.push(action);
+  }
+  for (const warning of tempResourceReconciliation.warnings) {
+    warnings.push(warning);
+  }
+  const queueItems = listMergeQueue(db);
+  const runningQueueOperations = listOperationJournal(db, { scopeType: 'queue_item', status: 'running', limit: 200 });
+
+  for (const operation of runningQueueOperations) {
+    const item = getMergeQueueItem(db, operation.scope_id);
+    if (!item) {
+      finishOperationJournalEntry(db, operation.id, {
+        status: 'repaired',
+        details: JSON.stringify({
+          repaired_by: 'switchman repair',
+          summary: 'Queue item no longer exists; interrupted journal entry was cleared.',
+        }),
+      });
+      actions.push({
+        kind: 'journal_operation_repaired',
+        operation_id: operation.id,
+        operation_type: operation.operation_type,
+        scope_type: operation.scope_type,
+        scope_id: operation.scope_id,
+      });
+      continue;
+    }
+
+    if (['validating', 'rebasing', 'merging'].includes(item.status)) {
+      const repaired = markMergeQueueState(db, item.id, {
+        status: 'retrying',
+        lastErrorCode: 'interrupted_queue_run',
+        lastErrorSummary: `Queue item ${item.id} was interrupted during ${operation.operation_type} and has been reset to retrying.`,
+        nextAction: 'Run `switchman queue run` to resume landing.',
+      });
+      finishOperationJournalEntry(db, operation.id, {
+        status: 'repaired',
+        details: JSON.stringify({
+          repaired_by: 'switchman repair',
+          queue_item_id: item.id,
+          previous_status: item.status,
+          status: repaired.status,
+        }),
+      });
+      repairedQueueItems.add(item.id);
+      actions.push({
+        kind: 'queue_item_reset',
+        queue_item_id: repaired.id,
+        previous_status: item.status,
+        status: repaired.status,
+        next_action: repaired.next_action,
+      });
+      actions.push({
+        kind: 'journal_operation_repaired',
+        operation_id: operation.id,
+        operation_type: operation.operation_type,
+        scope_type: operation.scope_type,
+        scope_id: operation.scope_id,
+      });
+      continue;
+    }
+
+    if (!['running', 'queued', 'retrying'].includes(item.status)) {
+      finishOperationJournalEntry(db, operation.id, {
+        status: 'repaired',
+        details: JSON.stringify({
+          repaired_by: 'switchman repair',
+          queue_item_id: item.id,
+          summary: `Queue item is already ${item.status}; stale running journal entry was cleared.`,
+        }),
+      });
+      actions.push({
+        kind: 'journal_operation_repaired',
+        operation_id: operation.id,
+        operation_type: operation.operation_type,
+        scope_type: operation.scope_type,
+        scope_id: operation.scope_id,
+      });
+    }
+  }
+
+  const interruptedQueueItems = queueItems.filter((item) => ['validating', 'rebasing', 'merging'].includes(item.status) && !repairedQueueItems.has(item.id));
+
+  for (const item of interruptedQueueItems) {
+    const repaired = markMergeQueueState(db, item.id, {
+      status: 'retrying',
+      lastErrorCode: 'interrupted_queue_run',
+      lastErrorSummary: `Queue item ${item.id} was left in ${item.status} and has been reset to retrying.`,
+      nextAction: 'Run `switchman queue run` to resume landing.',
+    });
+    actions.push({
+      kind: 'queue_item_reset',
+      queue_item_id: repaired.id,
+      previous_status: item.status,
+      status: repaired.status,
+      next_action: repaired.next_action,
+      });
+  }
+
+  const reconciledWorktrees = new Map(listWorktrees(db).map((worktree) => [worktree.name, worktree]));
+  for (const item of queueItems.filter((entry) => ['queued', 'retrying'].includes(entry.status) && entry.source_type === 'worktree')) {
+    const worktree = reconciledWorktrees.get(item.source_worktree || item.source_ref) || null;
+    if (!worktree || worktree.status === 'missing') {
+      const blocked = markMergeQueueState(db, item.id, {
+        status: 'blocked',
+        lastErrorCode: 'source_worktree_missing',
+        lastErrorSummary: `Queued worktree ${item.source_worktree || item.source_ref} is no longer available.`,
+        nextAction: `Restore or re-register ${item.source_worktree || item.source_ref}, then run \`switchman queue retry ${item.id}\`.`,
+      });
+      actions.push({
+        kind: 'queue_item_blocked_missing_worktree',
+        queue_item_id: blocked.id,
+        worktree: item.source_worktree || item.source_ref,
+        next_action: blocked.next_action,
+      });
+    }
+  }
+
+  const pipelineIds = [...new Set([
+    ...collectKnownPipelineIds(db),
+    ...queueItems.map((item) => item.source_pipeline_id).filter(Boolean),
+  ])];
+  const runningPipelineOperations = listOperationJournal(db, { scopeType: 'pipeline', status: 'running', limit: 200 });
+
+  for (const pipelineId of pipelineIds) {
+    const repaired = repairPipelineState(db, repoRoot, pipelineId);
+    if (!repaired.repaired) continue;
+    actions.push({
+      kind: 'pipeline_repaired',
+      pipeline_id: pipelineId,
+      actions: repaired.actions,
+      next_action: repaired.next_action,
+    });
+
+    for (const operation of runningPipelineOperations.filter((entry) => entry.scope_id === pipelineId)) {
+      finishOperationJournalEntry(db, operation.id, {
+        status: 'repaired',
+        details: JSON.stringify({
+          repaired_by: 'switchman repair',
+          pipeline_id: pipelineId,
+          repair_actions: repaired.actions.map((action) => action.kind),
+        }),
+      });
+      actions.push({
+        kind: 'journal_operation_repaired',
+        operation_id: operation.id,
+        operation_type: operation.operation_type,
+        scope_type: operation.scope_type,
+        scope_id: operation.scope_id,
+      });
+    }
+  }
+
+  if (actions.length === 0) {
+    notes.push('No safe repair action was needed.');
+  }
+
+  const summary = summarizeRepairReport(actions, warnings, notes);
+
+  return {
+    repaired: actions.length > 0,
+    actions,
+    warnings,
+    summary,
+    notes,
+    next_action: warnings[0]?.next_action || (interruptedQueueItems.length > 0 ? 'switchman queue run' : 'switchman status'),
+  };
+}
+
+function buildLandingStateLabel(landing) {
+  if (!landing) return null;
+  if (!landing.synthetic) {
+    return `${landing.branch} ${chalk.dim('(single branch)')}`;
+  }
+  if (!landing.last_materialized) {
+    return `${landing.branch} ${chalk.yellow('(not created yet)')}`;
+  }
+  if (landing.stale) {
+    return `${landing.branch} ${chalk.red('(stale)')}`;
+  }
+  return `${landing.branch} ${chalk.green('(current)')}`;
+}
+
+async function maybeCaptureTelemetry(event, properties = {}, { homeDir = null } = {}) {
+  try {
+    await maybePromptForTelemetry({ homeDir: homeDir || undefined });
+    await captureTelemetryEvent(event, {
+      app_version: program.version(),
+      os: process.platform,
+      node_version: process.version,
+      ...properties,
+    }, { homeDir: homeDir || undefined });
+  } catch {
+    // Telemetry must never block CLI usage.
+  }
+}
+
+function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
+  const dbPath = join(repoRoot, '.switchman', 'switchman.db');
+  const rootMcpPath = join(repoRoot, '.mcp.json');
+  const cursorMcpPath = join(repoRoot, '.cursor', 'mcp.json');
+  const claudeGuidePath = join(repoRoot, 'CLAUDE.md');
+  const checks = [];
+  const nextSteps = [];
+  let workspaces = [];
+  let db = null;
+
+  const dbExists = existsSync(dbPath);
+  checks.push({
+    key: 'database',
+    ok: dbExists,
+    label: 'Project database',
+    detail: dbExists ? '.switchman/switchman.db is ready' : 'Switchman database is missing',
+  });
+  if (!dbExists) {
+    nextSteps.push('Run `switchman init` or `switchman setup --agents 3` in this repo.');
+  }
+
+  if (dbExists) {
+    try {
+      db = getDb(repoRoot);
+      workspaces = listWorktrees(db);
+    } catch {
+      checks.push({
+        key: 'database_open',
+        ok: false,
+        label: 'Database access',
+        detail: 'Switchman could not open the project database',
+      });
+      nextSteps.push('Re-run `switchman init` if the project database looks corrupted.');
+    } finally {
+      try { db?.close(); } catch { /* no-op */ }
+    }
+  }
+
+  const agentWorkspaces = workspaces.filter((entry) => entry.name !== 'main');
+  const workspaceReady = agentWorkspaces.length > 0;
+  checks.push({
+    key: 'workspaces',
+    ok: workspaceReady,
+    label: 'Agent workspaces',
+    detail: workspaceReady
+      ? `${agentWorkspaces.length} agent workspace(s) registered`
+      : 'No agent workspaces are registered yet',
+  });
+  if (!workspaceReady) {
+    nextSteps.push('Run `switchman setup --agents 3` to create agent workspaces.');
+  }
+
+  const rootMcpExists = existsSync(rootMcpPath);
+  checks.push({
+    key: 'claude_mcp',
+    ok: rootMcpExists,
+    label: 'Claude Code MCP',
+    detail: rootMcpExists ? '.mcp.json is present in the repo root' : '.mcp.json is missing from the repo root',
+  });
+  if (!rootMcpExists) {
+    nextSteps.push('Re-run `switchman setup --agents 3` to restore the repo-local MCP config.');
+  }
+
+  const cursorMcpExists = existsSync(cursorMcpPath);
+  checks.push({
+    key: 'cursor_mcp',
+    ok: cursorMcpExists,
+    label: 'Cursor MCP',
+    detail: cursorMcpExists ? '.cursor/mcp.json is present in the repo root' : '.cursor/mcp.json is missing from the repo root',
+  });
+  if (!cursorMcpExists) {
+    nextSteps.push('Re-run `switchman setup --agents 3` if you want Cursor to attach automatically.');
+  }
+
+  const claudeGuideExists = existsSync(claudeGuidePath);
+  checks.push({
+    key: 'claude_md',
+    ok: claudeGuideExists,
+    label: 'Claude guide',
+    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.');
+  }
+
+  const windsurfConfigExists = existsSync(getWindsurfMcpConfigPath(homeDir || undefined));
+  checks.push({
+    key: 'windsurf_mcp',
+    ok: windsurfConfigExists,
+    label: 'Windsurf MCP',
+    detail: windsurfConfigExists
+      ? 'Windsurf shared MCP config is installed'
+      : 'Windsurf shared MCP config is optional and not installed',
+  });
+  if (!windsurfConfigExists) {
+    nextSteps.push('If you use Windsurf, run `switchman mcp install --windsurf` once.');
+  }
+
+  const ok = checks.every((item) => item.ok || ['claude_md', 'windsurf_mcp'].includes(item.key));
+  return {
+    ok,
+    repo_root: repoRoot,
+    checks,
+    workspaces: workspaces.map((entry) => ({
+      name: entry.name,
+      path: entry.path,
+      branch: entry.branch,
+    })),
+    suggested_commands: [
+      'switchman status --watch',
+      'switchman task add "Your first task" --priority 8',
+      'switchman gate ci',
+      ...nextSteps.some((step) => step.includes('Windsurf')) ? ['switchman mcp install --windsurf'] : [],
+    ],
+    next_steps: [...new Set(nextSteps)].slice(0, 6),
+  };
+}
+
+function renderSetupVerification(report, { compact = false } = {}) {
+  console.log(chalk.bold(compact ? 'First-run check:' : 'Setup verification:'));
+  for (const check of report.checks) {
+    const badge = boolBadge(check.ok);
+    console.log(`  ${badge} ${check.label} ${chalk.dim(`— ${check.detail}`)}`);
+  }
+  if (report.next_steps.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Fix next:'));
+    for (const step of report.next_steps) {
+      console.log(`  - ${step}`);
+    }
+  }
+  console.log('');
+  console.log(chalk.bold('Try next:'));
+  for (const command of report.suggested_commands.slice(0, 4)) {
+    console.log(`  ${chalk.cyan(command)}`);
+  }
+}
+
+function summarizeLeaseScope(db, lease) {
+  const reservations = listScopeReservations(db, { leaseId: lease.id });
+  const pathScopes = reservations
+    .filter((reservation) => reservation.ownership_level === 'path_scope' && reservation.scope_pattern)
+    .map((reservation) => reservation.scope_pattern);
+  if (pathScopes.length === 1) return `scope:${pathScopes[0]}`;
+  if (pathScopes.length > 1) return `scope:${pathScopes.length} paths`;
+
+  const subsystemScopes = reservations
+    .filter((reservation) => reservation.ownership_level === 'subsystem' && reservation.subsystem_tag)
+    .map((reservation) => reservation.subsystem_tag);
+  if (subsystemScopes.length === 1) return `subsystem:${subsystemScopes[0]}`;
+  if (subsystemScopes.length > 1) return `subsystem:${subsystemScopes.length}`;
+  return null;
+}
+
+function isBusyError(err) {
+  const message = String(err?.message || '').toLowerCase();
+  return message.includes('database is locked') || message.includes('sqlite_busy');
+}
+
+function humanizeReasonCode(reasonCode) {
+  const labels = {
+    no_active_lease: 'no active lease',
+    lease_expired: 'lease expired',
+    worktree_mismatch: 'wrong worktree',
+    path_not_claimed: 'path not claimed',
+    path_claimed_by_other_lease: 'claimed by another lease',
+    path_scoped_by_other_lease: 'scoped by another lease',
+    path_within_task_scope: 'within task scope',
+    policy_exception_required: 'policy exception required',
+    policy_exception_allowed: 'policy exception allowed',
+    changes_outside_claims: 'changed files outside claims',
+    changes_outside_task_scope: 'changed files outside task scope',
+    missing_expected_tests: 'missing expected tests',
+    missing_expected_docs: 'missing expected docs',
+    missing_expected_source_changes: 'missing expected source changes',
+    objective_not_evidenced: 'task objective not evidenced',
+    no_changes_detected: 'no changes detected',
+    task_execution_timeout: 'task execution timed out',
+    task_failed: 'task failed',
+    agent_command_failed: 'agent command failed',
+    rejected: 'rejected',
+  };
+  return labels[reasonCode] || String(reasonCode || 'unknown').replace(/_/g, ' ');
+}
+
+function nextStepForReason(reasonCode) {
+  const actions = {
+    no_active_lease: 'reacquire the task or lease before writing',
+    lease_expired: 'refresh or reacquire the lease, then retry',
+    worktree_mismatch: 'run the task from the assigned worktree',
+    path_not_claimed: 'claim the file before editing it',
+    path_claimed_by_other_lease: 'wait for the other task or pick a different file',
+    changes_outside_claims: 'claim all edited files or narrow the task scope',
+    changes_outside_task_scope: 'keep edits inside allowed paths or update the plan',
+    missing_expected_tests: 'add test coverage before rerunning',
+    missing_expected_docs: 'add the expected docs change before rerunning',
+    missing_expected_source_changes: 'make a source change inside the task scope',
+    objective_not_evidenced: 'align the output more closely to the task objective',
+    no_changes_detected: 'produce a tracked change or close the task differently',
+    task_execution_timeout: 'raise the timeout or reduce task size',
+    agent_command_failed: 'inspect stderr/stdout and rerun the agent',
+  };
+  return actions[reasonCode] || null;
+}
+
+function latestTaskFailure(task) {
+  const failureLine = String(task.description || '')
     .split('\n')
     .map((line) => line.trim())
     .filter(Boolean)
@@ -515,6 +1767,7 @@ function commandForFailedTask(task, failure) {
 }
 
 function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, scanReport, aiGate }) {
+  const changePolicy = loadChangePolicy(repoRoot);
   const failedTasks = tasks
     .filter((task) => task.status === 'failed')
     .map((task) => {
@@ -564,6 +1817,7 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
     next_step: 'review the overlapping branches before merge',
   }));
 
+  const staleClusters = buildStaleClusters(aiGate.dependency_invalidations || []);
   const attention = [
     ...staleLeases.map((lease) => ({
       kind: 'stale_lease',
@@ -651,14 +1905,17 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
     });
   }
 
-  for (const invalidation of aiGate.dependency_invalidations || []) {
+  for (const cluster of staleClusters) {
     attention.push({
       kind: 'dependency_invalidation',
-      title: invalidation.summary,
-      detail: `${invalidation.source_worktree || 'unknown'} -> ${invalidation.affected_worktree || 'unknown'} (${invalidation.stale_area})`,
-      next_step: 'rerun or re-review the stale task before merge',
-      command: invalidation.affected_pipeline_id ? `switchman pipeline status ${invalidation.affected_pipeline_id}` : 'switchman gate ai',
-      severity: invalidation.severity === 'blocked' ? 'block' : 'warn',
+      title: cluster.title,
+      detail: cluster.detail,
+      next_step: cluster.next_step,
+      command: cluster.command,
+      severity: cluster.severity,
+      affected_pipeline_id: cluster.affected_pipeline_id,
+      affected_task_ids: cluster.affected_task_ids,
+      invalidation_count: cluster.invalidation_count,
     });
   }
 
@@ -668,6 +1925,16 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
       ? 'warn'
       : 'healthy';
 
+  const repoPolicyState = summarizePipelinePolicyState(db, {
+    tasks,
+    counts: {
+      done: tasks.filter((task) => task.status === 'done').length,
+      in_progress: tasks.filter((task) => task.status === 'in_progress').length,
+      pending: tasks.filter((task) => task.status === 'pending').length,
+      failed: tasks.filter((task) => task.status === 'failed').length,
+    },
+  }, changePolicy, aiGate.boundary_validations || []);
+
   return {
     repo_root: repoRoot,
     health,
@@ -707,8 +1974,10 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
       ai_gate_status: aiGate.status,
       boundary_validations: aiGate.boundary_validations || [],
       dependency_invalidations: aiGate.dependency_invalidations || [],
+      stale_clusters: staleClusters,
       compliance: scanReport.complianceSummary,
       semantic_conflicts: scanReport.semanticConflicts || [],
+      policy_state: repoPolicyState,
     },
     next_steps: attention.length > 0
       ? [...new Set(attention.map((item) => item.next_step))].slice(0, 5)
@@ -776,6 +2045,20 @@ function buildUnifiedStatusReport({
     ...(queueItems.length > 0 ? ['switchman queue status'] : []),
     ...(queueSummary.next ? ['switchman queue run'] : []),
   ].filter(Boolean);
+  const isFirstRunReady = tasks.length === 0
+    && doctorReport.active_work.length === 0
+    && queueItems.length === 0
+    && claims.length === 0;
+  const defaultNextSteps = isFirstRunReady
+    ? [
+      'add a first task with `switchman task add "Your first task" --priority 8`',
+      'keep `switchman status --watch` open while agents start work',
+      'run `switchman demo` if you want the shortest proof before using a real repo',
+    ]
+    : ['run `switchman gate ci` before merge', 'run `switchman scan` after major parallel work'];
+  const defaultSuggestedCommands = isFirstRunReady
+    ? ['switchman task add "Your first task" --priority 8', 'switchman status --watch', 'switchman demo']
+    : ['switchman gate ci', 'switchman scan'];
 
   return {
     generated_at: new Date().toISOString(),
@@ -789,6 +2072,8 @@ function buildUnifiedStatusReport({
       ? 'Repo needs attention before more work or merge.'
       : attention.some((item) => item.severity === 'warn')
         ? 'Repo is running, but a few items need review.'
+        : isFirstRunReady
+          ? 'Switchman is set up and ready. Add a task or run the demo to start.'
         : 'Repo looks healthy. Agents are coordinated and merge checks are clear.',
     lease_policy: leasePolicy,
     counts: {
@@ -812,10 +2097,10 @@ function buildUnifiedStatusReport({
       file_path: claim.file_path,
     })),
     next_steps: [...new Set([
-      ...doctorReport.next_steps,
+      ...(attention.length > 0 ? doctorReport.next_steps : defaultNextSteps),
       ...queueAttention.map((item) => item.next_step),
     ])].slice(0, 6),
-    suggested_commands: [...new Set(suggestedCommands)].slice(0, 6),
+    suggested_commands: [...new Set(attention.length > 0 ? suggestedCommands : defaultSuggestedCommands)].slice(0, 6),
   };
 }
 
@@ -884,7 +2169,15 @@ function renderUnifiedStatusReport(report) {
     ? ('title' in focusItem
       ? `${focusItem.title}${focusItem.detail ? ` ${chalk.dim(`• ${focusItem.detail}`)}` : ''}`
       : `${focusItem.title} ${chalk.dim(focusItem.id)}`)
+    : report.counts.pending === 0 && report.counts.in_progress === 0 && report.queue.items.length === 0
+      ? 'Nothing active yet. Add a task or run the demo to start.'
     : 'Nothing urgent. Safe to keep parallel work moving.';
+  const primaryCommand = ('command' in (focusItem || {}) && focusItem?.command)
+    ? focusItem.command
+    : report.suggested_commands[0] || 'switchman status --watch';
+  const nextStepLine = ('next_step' in (focusItem || {}) && focusItem?.next_step)
+    ? focusItem.next_step
+    : report.next_steps[0] || 'Keep work moving and check back here if anything blocks.';
   const queueLoad = queueCounts.queued + queueCounts.retrying + queueCounts.merging + queueCounts.blocked;
   const landingLabel = report.merge_readiness.ci_gate_ok ? 'ready' : 'hold';
 
@@ -914,8 +2207,14 @@ function renderUnifiedStatusReport(report) {
     { label: 'merging', value: queueCounts.merging, color: chalk.blue },
     { label: 'merged', value: queueCounts.merged, color: chalk.green },
   ]));
-  console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+  console.log(`${chalk.bold('Now:')} ${report.summary}`);
+  console.log(`${chalk.bold('Attention:')} ${focusLine}`);
+  console.log(`${chalk.bold('Run next:')} ${chalk.cyan(primaryCommand)}`);
+  console.log(`${chalk.dim('why:')} ${nextStepLine}`);
   console.log(chalk.dim(`policy: ${formatRelativePolicy(report.lease_policy)} • requeue on reap ${report.lease_policy.requeue_task_on_reap ? 'on' : 'off'}`));
+  if (report.merge_readiness.policy_state?.active) {
+    console.log(chalk.dim(`change policy: ${report.merge_readiness.policy_state.domains.join(', ')} • ${report.merge_readiness.policy_state.enforcement} • missing ${report.merge_readiness.policy_state.missing_task_types.join(', ') || 'none'}`));
+  }
 
   const runningLines = report.active_work.length > 0
     ? report.active_work.slice(0, 5).map((item) => {
@@ -955,8 +2254,14 @@ function renderUnifiedStatusReport(report) {
   const queueLines = report.queue.items.length > 0
     ? [
       ...(report.queue.summary.next
-        ? [`${chalk.dim('next:')} ${report.queue.summary.next.id} ${report.queue.summary.next.source_type}:${report.queue.summary.next.source_ref} ${chalk.dim(`retries:${report.queue.summary.next.retry_count}/${report.queue.summary.next.max_retries}`)}`]
+        ? [
+          `${chalk.dim('next:')} ${report.queue.summary.next.id} ${report.queue.summary.next.source_type}:${report.queue.summary.next.source_ref} ${chalk.dim(`retries:${report.queue.summary.next.retry_count}/${report.queue.summary.next.max_retries}`)}${report.queue.summary.next.queue_assessment?.goal_priority ? ` ${chalk.dim(`priority:${report.queue.summary.next.queue_assessment.goal_priority}`)}` : ''}${report.queue.summary.next.queue_assessment?.integration_risk && report.queue.summary.next.queue_assessment.integration_risk !== 'normal' ? ` ${chalk.dim(`risk:${report.queue.summary.next.queue_assessment.integration_risk}`)}` : ''}`,
+          ...(report.queue.summary.next.recommendation?.summary ? [`  ${chalk.dim('decision:')} ${report.queue.summary.next.recommendation.summary}`] : []),
+        ]
         : []),
+      ...report.queue.summary.held_back
+        .slice(0, 2)
+        .map((item) => `  ${chalk.dim(item.recommendation?.action === 'escalate' ? 'escalate:' : 'hold:')} ${item.id} ${item.source_type}:${item.source_ref} ${chalk.dim(item.recommendation?.summary || item.queue_assessment?.reason || '')}`),
       ...report.queue.items
         .filter((entry) => ['blocked', 'retrying', 'merging'].includes(entry.status))
         .slice(0, 4)
@@ -969,6 +2274,35 @@ function renderUnifiedStatusReport(report) {
     ]
     : [chalk.dim('No queued merges.')];
 
+  const staleClusterLines = report.merge_readiness.stale_clusters?.length > 0
+    ? report.merge_readiness.stale_clusters.slice(0, 4).flatMap((cluster) => {
+      const lines = [`${renderChip(cluster.severity === 'block' ? 'STALE' : 'WATCH', cluster.affected_pipeline_id || cluster.affected_task_ids[0], cluster.severity === 'block' ? chalk.red : chalk.yellow)} ${cluster.title}`];
+      lines.push(`  ${chalk.dim(cluster.detail)}`);
+      if (cluster.causal_group_size > 1) lines.push(`  ${chalk.dim('cause:')} ${cluster.causal_group_summary} ${chalk.dim(`(${cluster.causal_group_rank}/${cluster.causal_group_size} in same stale wave)`)}${cluster.related_affected_pipelines?.length ? ` ${chalk.dim(`related:${cluster.related_affected_pipelines.join(', ')}`)}` : ''}`);
+      lines.push(`  ${chalk.dim('areas:')} ${cluster.stale_areas.join(', ')}`);
+      lines.push(`  ${chalk.dim('rerun priority:')} ${cluster.rerun_priority} ${chalk.dim(`score:${cluster.rerun_priority_score}`)}${cluster.highest_affected_priority ? ` ${chalk.dim(`affected-priority:${cluster.highest_affected_priority}`)}` : ''}${cluster.rerun_breadth_score ? ` ${chalk.dim(`breadth:${cluster.rerun_breadth_score}`)}` : ''}`);
+      lines.push(`  ${chalk.yellow('next:')} ${cluster.next_step}`);
+      lines.push(`  ${chalk.cyan('run:')} ${cluster.command}`);
+      return lines;
+    })
+    : [chalk.green('No stale dependency clusters.')];
+
+  const policyLines = report.merge_readiness.policy_state?.active
+    ? [
+      `${renderChip(report.merge_readiness.policy_state.enforcement.toUpperCase(), report.merge_readiness.policy_state.domains.join(','), report.merge_readiness.policy_state.enforcement === 'blocked' ? chalk.red : chalk.yellow)} ${report.merge_readiness.policy_state.summary}`,
+      `  ${chalk.dim('required:')} ${report.merge_readiness.policy_state.required_task_types.join(', ') || 'none'}`,
+      `  ${chalk.dim('missing:')} ${report.merge_readiness.policy_state.missing_task_types.join(', ') || 'none'}`,
+      `  ${chalk.dim('overridden:')} ${report.merge_readiness.policy_state.overridden_task_types.join(', ') || 'none'}`,
+      ...report.merge_readiness.policy_state.requirement_status
+        .filter((requirement) => requirement.evidence.length > 0)
+        .slice(0, 3)
+        .map((requirement) => `  ${chalk.dim(`${requirement.task_type}:`)} ${requirement.evidence.map((entry) => entry.artifact_path ? `${entry.task_id} (${entry.artifact_path})` : entry.task_id).join(', ')}`),
+      ...report.merge_readiness.policy_state.overrides
+        .slice(0, 3)
+        .map((entry) => `  ${chalk.dim(`override ${entry.id}:`)} ${(entry.task_types || []).join(', ') || 'all'} by ${entry.approved_by || 'unknown'}`),
+    ]
+    : [chalk.green('No explicit change policy requirements are active.')];
+
   const nextActionLines = [
     ...(report.next_up.length > 0
       ? report.next_up.map((task) => `${renderChip('NEXT', `p${task.priority}`, chalk.green)} ${task.title} ${chalk.dim(task.id)}`)
@@ -981,6 +2315,8 @@ function renderUnifiedStatusReport(report) {
     renderPanel('Running now', runningLines, chalk.cyan),
     renderPanel('Blocked', blockedLines, blockedItems.length > 0 ? chalk.red : chalk.green),
     renderPanel('Warnings', warningLines, warningItems.length > 0 ? chalk.yellow : chalk.green),
+    renderPanel('Stale clusters', staleClusterLines, (report.merge_readiness.stale_clusters?.some((cluster) => cluster.severity === 'block') ? chalk.red : (report.merge_readiness.stale_clusters?.length || 0) > 0 ? chalk.yellow : chalk.green)),
+    renderPanel('Policy', policyLines, report.merge_readiness.policy_state?.active && report.merge_readiness.policy_state.missing_task_types.length > 0 ? chalk.red : chalk.green),
     renderPanel('Landing queue', queueLines, queueCounts.blocked > 0 ? chalk.red : chalk.blue),
     renderPanel('Next action', nextActionLines, chalk.green),
   ];
@@ -1095,6 +2431,7 @@ program
 program.showHelpAfterError('(run with --help for usage examples)');
 program.addHelpText('after', `
 Start here:
+  switchman demo
   switchman setup --agents 5
   switchman status --watch
   switchman gate ci
@@ -1109,6 +2446,50 @@ Docs:
   docs/setup-cursor.md
 `);
 
+program
+  .command('demo')
+  .description('Create a throwaway repo that proves overlapping claims are blocked and safe landing works')
+  .option('--path <dir>', 'Directory to create the demo repo in')
+  .option('--cleanup', 'Delete the demo repo after the run finishes')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman demo
+  switchman demo --path /tmp/switchman-demo
+`)
+  .action(async (opts) => {
+    try {
+      const result = await runDemoScenario({
+        repoPath: opts.path || null,
+        cleanup: Boolean(opts.cleanup),
+      });
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(`${chalk.green('✓')} Demo repo ready`);
+      console.log(`  ${chalk.dim('path:')} ${result.repo_path}`);
+      console.log(`  ${chalk.dim('proof:')} agent2 was blocked from ${chalk.cyan(result.overlap_demo.blocked_path)}`);
+      console.log(`  ${chalk.dim('safe reroute:')} agent2 claimed ${chalk.cyan(result.overlap_demo.safe_path)} instead`);
+      console.log(`  ${chalk.dim('landing:')} ${result.queue.processed.filter((entry) => entry.status === 'merged').length} queue item(s) merged safely`);
+      console.log(`  ${chalk.dim('final gate:')} ${result.final_gate.ok ? chalk.green('clean') : chalk.red('attention needed')}`);
+      console.log('');
+      console.log(chalk.bold('What to do next:'));
+      for (const step of result.next_steps) {
+        console.log(`  ${chalk.cyan(step)}`);
+      }
+      if (!opts.cleanup) {
+        console.log('');
+        console.log(chalk.dim('The demo repo stays on disk so you can inspect it, record it, or keep experimenting.'));
+      }
+    } catch (err) {
+      printErrorWithNext(err.message, 'switchman demo --json');
+      process.exitCode = 1;
+    }
+  });
+
 // ── init ──────────────────────────────────────────────────────────────────────
 
 program
@@ -1232,11 +2613,11 @@ Examples:
 
       console.log('');
       console.log(chalk.bold('Next steps:'));
-      console.log(`  1. Add your tasks:`);
+      console.log(`  1. Add a first task:`);
       console.log(`     ${chalk.cyan('switchman task add "Your first task" --priority 8')}`);
-      console.log(`  2. Open Claude Code or Cursor in each folder above — the local MCP config will attach Switchman automatically`);
-      console.log(`  3. Check status at any time:`);
-      console.log(`     ${chalk.cyan('switchman status')}`);
+      console.log(`  2. Open Claude Code or Cursor in the workspaces above — the local MCP config will attach Switchman automatically`);
+      console.log(`  3. Keep the repo dashboard open while work starts:`);
+      console.log(`     ${chalk.cyan('switchman status --watch')}`);
       console.log('');
 
       const verification = collectSetupVerification(repoRoot);
@@ -1497,6 +2878,67 @@ taskCmd
     }
   });
 
+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`);
+    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`);
+    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')
@@ -1584,8 +3026,13 @@ 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((branch, opts) => {
+  .action(async (branch, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
 
@@ -1605,13 +3052,29 @@ Examples:
           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: opts.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 = {
@@ -1636,6 +3099,9 @@ Examples:
       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');
@@ -1667,7 +3133,9 @@ queueCmd
     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}`)}` : '';
-      console.log(`  ${statusBadge(item.status)} ${item.id} ${item.source_type}:${item.source_ref} ${chalk.dim(`→ ${item.target_branch}`)} ${retryInfo}${attemptInfo}`);
+      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}`);
       }
@@ -1698,7 +3166,7 @@ What it helps you answer:
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
     const items = listMergeQueue(db);
-    const summary = buildQueueStatusSummary(items);
+    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);
@@ -1709,9 +3177,14 @@ What it helps you answer:
       return;
     }
 
-    const queueHealth = summary.counts.blocked > 0 ? 'block' : summary.counts.retrying > 0 ? 'warn' : 'healthy';
+    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 focus = summary.blocked[0] || summary.retrying[0] || summary.next || null;
+    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.';
@@ -1723,6 +3196,9 @@ What it helps you answer:
     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),
@@ -1737,11 +3213,23 @@ What it helps you answer:
 
     const queueFocusLines = summary.next
       ? [
-        `${renderChip('NEXT', summary.next.id, chalk.green)} ${summary.next.source_type}:${summary.next.source_ref} ${chalk.dim(`retries:${summary.next.retry_count}/${summary.next.max_retries}`)}`,
-        `  ${chalk.yellow('run:')} switchman queue run`,
+        `${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}`)}`];
@@ -1751,13 +3239,14 @@ What it helps you answer:
       })
       : [chalk.green('Nothing blocked.')];
 
-    const queueWatchLines = items.filter((item) => ['retrying', 'merging', 'rebasing', 'validating'].includes(item.status)).length > 0
+    const queueWatchLines = items.filter((item) => ['retrying', 'held', 'wave_blocked', 'escalated', 'merging', 'rebasing', 'validating'].includes(item.status)).length > 0
       ? items
-        .filter((item) => ['retrying', 'merging', 'rebasing', 'validating'].includes(item.status))
+        .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' ? chalk.yellow : chalk.blue)} ${item.source_type}:${item.source_ref}`];
+          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.')];
@@ -1768,9 +3257,23 @@ What it helps you answer:
       ...(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),
@@ -1791,6 +3294,8 @@ 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')
@@ -1799,6 +3304,7 @@ queueCmd
   .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
 `)
@@ -1807,12 +3313,21 @@ Examples:
 
     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) {
@@ -1820,102 +3335,437 @@ Examples:
         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 (result.processed.length === 0) {
-          sleepSync(watchIntervalMs);
-        }
-      }
+        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') {
+          console.log(`${chalk.green('✓')} Merged ${chalk.cyan(item.id)} into ${chalk.bold(item.target_branch)}`);
+          console.log(`  ${chalk.dim('commit:')} ${item.merged_commit}`);
+        } else {
+          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;
+    }
+  });
+
+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');
+explainCmd.addHelpText('after', `
+Examples:
+  switchman explain queue mq-123
+  switchman explain claim src/auth/login.js
+  switchman explain history pipe-123
+`);
+
+explainCmd
+  .command('queue <itemId>')
+  .description('Explain one landing-queue item in plain English')
+  .option('--json', 'Output raw JSON')
+  .action((itemId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const report = buildQueueExplainReport(db, repoRoot, itemId);
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      console.log(chalk.bold(`Queue item ${report.item.id}`));
+      console.log(`  ${chalk.dim('status:')} ${statusBadge(report.item.status)}`.trim());
+      console.log(`  ${chalk.dim('source:')} ${report.item.source_type} ${report.item.source_ref}`);
+      console.log(`  ${chalk.dim('target:')} ${report.item.target_branch}`);
+      if (report.resolved_source) {
+        console.log(`  ${chalk.dim('resolved branch:')} ${chalk.cyan(report.resolved_source.branch)}`);
+        if (report.resolved_source.worktree) {
+          console.log(`  ${chalk.dim('resolved worktree:')} ${chalk.cyan(report.resolved_source.worktree)}`);
+        }
+      }
+      if (report.resolution_error) {
+        console.log(`  ${chalk.red('why:')} ${report.resolution_error}`);
+      } else if (report.item.last_error_summary) {
+        console.log(`  ${chalk.red('why:')} ${report.item.last_error_summary}`);
+      } else {
+        console.log(`  ${chalk.dim('why:')} waiting to land`);
+      }
+      console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
+      if (report.recent_events.length > 0) {
+        console.log(chalk.bold('\nRecent events'));
+        for (const event of report.recent_events) {
+          console.log(`  ${chalk.dim(event.created_at)} ${event.event_type}${event.status ? ` ${statusBadge(event.status).trim()}` : ''}`);
+        }
+      }
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, 'switchman queue status');
+      process.exitCode = 1;
+    }
+  });
+
+explainCmd
+  .command('claim <path>')
+  .description('Explain who currently owns a file path')
+  .option('--json', 'Output raw JSON')
+  .action((filePath, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const report = buildClaimExplainReport(db, filePath);
+      db.close();
 
       if (opts.json) {
-        console.log(JSON.stringify(aggregate, null, 2));
+        console.log(JSON.stringify(report, null, 2));
         return;
       }
 
-      if (aggregate.processed.length === 0) {
-        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,
-        });
+      console.log(chalk.bold(`Claim status for ${report.file_path}`));
+      if (report.claims.length === 0 && report.scope_owners.length === 0) {
+        console.log(`  ${chalk.green('status:')} unowned`);
+        console.log(`  ${chalk.yellow('next:')} switchman claim <taskId> <workspace> ${report.file_path}`);
         return;
       }
 
-      for (const entry of aggregate.processed) {
-        const item = entry.item;
-        if (entry.status === 'merged') {
-          console.log(`${chalk.green('✓')} Merged ${chalk.cyan(item.id)} into ${chalk.bold(item.target_branch)}`);
-          console.log(`  ${chalk.dim('commit:')} ${item.merged_commit}`);
-        } else {
-          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 (report.claims.length > 0) {
+        console.log(`  ${chalk.red('explicit claim:')}`);
+        for (const claim of report.claims) {
+          console.log(`    ${chalk.cyan(claim.worktree)} task:${claim.task_id} ${chalk.dim(`lease:${claim.lease_id}`)}`);
+          console.log(`    ${chalk.dim('title:')} ${claim.task_title}`);
         }
       }
 
-      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,
-      });
+      if (report.scope_owners.length > 0) {
+        console.log(`  ${chalk.yellow('task scope owner:')}`);
+        for (const owner of report.scope_owners) {
+          console.log(`    ${chalk.cyan(owner.worktree)} task:${owner.task_id} ${chalk.dim(`lease:${owner.lease_id}`)}`);
+          console.log(`    ${chalk.dim('title:')} ${owner.task_title}`);
+        }
+      }
+
+      const blockingOwner = report.claims[0] || report.scope_owners[0];
+      if (blockingOwner) {
+        console.log(`  ${chalk.yellow('next:')} inspect ${chalk.cyan(blockingOwner.worktree)} or choose a different file before claiming this path`);
+      }
     } catch (err) {
-      console.error(chalk.red(err.message));
+      db.close();
+      printErrorWithNext(err.message, 'switchman status');
       process.exitCode = 1;
     }
   });
 
-queueCmd
-  .command('retry <itemId>')
-  .description('Retry a blocked merge queue item')
+explainCmd
+  .command('stale [taskId]')
+  .description('Explain why a task or pipeline is stale and how to revalidate it')
+  .option('--pipeline <pipelineId>', 'Explain stale invalidations for a whole pipeline')
   .option('--json', 'Output raw JSON')
-  .action((itemId, opts) => {
+  .action((taskId, 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');
+    try {
+      if (!opts.pipeline && !taskId) {
+        throw new Error('Pass a task id or `--pipeline <id>`.');
+      }
+      const report = opts.pipeline
+        ? buildStalePipelineExplainReport(db, opts.pipeline)
+        : buildStaleTaskExplainReport(db, taskId);
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      if (opts.pipeline) {
+        console.log(chalk.bold(`Stale status for pipeline ${report.pipeline_id}`));
+        if (report.stale_clusters.length === 0) {
+          console.log(`  ${chalk.green('state:')} no active dependency invalidations`);
+          return;
+        }
+        for (const cluster of report.stale_clusters) {
+          console.log(`  ${cluster.severity === 'block' ? chalk.red('why:') : chalk.yellow('why:')} ${cluster.title}`);
+          console.log(`  ${chalk.dim('source worktrees:')} ${cluster.source_worktrees.join(', ') || 'unknown'}`);
+          console.log(`  ${chalk.dim('affected tasks:')} ${cluster.affected_task_ids.join(', ')}`);
+          console.log(`  ${chalk.dim('stale areas:')} ${cluster.stale_areas.join(', ')}`);
+        }
+        console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
+        return;
+      }
+
+      console.log(chalk.bold(`Stale status for ${report.task.id}`));
+      console.log(`  ${chalk.dim('title:')} ${report.task.title}`);
+      console.log(`  ${chalk.dim('status:')} ${statusBadge(report.task.status)}`.trim());
+      if (report.invalidations.length === 0) {
+        console.log(`  ${chalk.green('state:')} no active dependency invalidations`);
+        return;
+      }
+      for (const invalidation of report.invalidations) {
+        console.log(`  ${chalk.red('why:')} ${invalidation.summary}`);
+        console.log(`  ${chalk.dim('source task:')} ${invalidation.source_task_id}`);
+        console.log(`  ${chalk.dim('stale area:')} ${invalidation.stale_area}`);
+      }
+      console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, opts.pipeline ? 'switchman doctor' : 'switchman doctor');
       process.exitCode = 1;
-      return;
     }
+  });
 
-    if (opts.json) {
-      console.log(JSON.stringify(item, null, 2));
-      return;
-    }
+explainCmd
+  .command('history <pipelineId>')
+  .description('Explain the recent change timeline for one pipeline')
+  .option('--json', 'Output raw JSON')
+  .action((pipelineId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
 
-    console.log(`${chalk.green('✓')} Queue item ${chalk.cyan(item.id)} reset to retrying`);
+    try {
+      const report = buildPipelineHistoryReport(db, repoRoot, pipelineId);
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      console.log(chalk.bold(`History for pipeline ${report.pipeline_id}`));
+      console.log(`  ${chalk.dim('title:')} ${report.title}`);
+      console.log(`  ${chalk.dim('tasks:')} pending ${report.counts.pending} • in progress ${report.counts.in_progress} • done ${report.counts.done} • failed ${report.counts.failed}`);
+      if (report.current.queue_items.length > 0) {
+        const queueSummary = report.current.queue_items
+          .map((item) => `${item.id} ${item.status}`)
+          .join(', ');
+        console.log(`  ${chalk.dim('queue:')} ${queueSummary}`);
+      }
+      if (report.current.stale_clusters.length > 0) {
+        console.log(`  ${chalk.red('stale:')} ${report.current.stale_clusters[0].title}`);
+      }
+      if (report.current.landing.last_failure) {
+        console.log(`  ${chalk.red('landing:')} ${humanizeReasonCode(report.current.landing.last_failure.reason_code || 'landing_branch_materialization_failed')}`);
+      } else if (report.current.landing.stale) {
+        console.log(`  ${chalk.yellow('landing:')} synthetic landing branch is stale`);
+      } else {
+        console.log(`  ${chalk.dim('landing:')} ${report.current.landing.branch} (${report.current.landing.strategy})`);
+      }
+      console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
+
+      console.log(chalk.bold('\nTimeline'));
+      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}`);
+        if (event.next_action) {
+          console.log(`    ${chalk.dim(`next: ${event.next_action}`)}`);
+        }
+      }
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
+      process.exitCode = 1;
+    }
   });
 
-queueCmd
-  .command('remove <itemId>')
-  .description('Remove a merge queue item')
-  .action((itemId) => {
+explainCmd
+  .command('landing <pipelineId>')
+  .description('Explain the current landing branch state for a pipeline')
+  .option('--json', 'Output raw JSON')
+  .action((pipelineId, opts) => {
     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');
+    try {
+      const report = getPipelineLandingExplainReport(db, repoRoot, pipelineId);
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      console.log(chalk.bold(`Landing status for ${report.pipeline_id}`));
+      console.log(`  ${chalk.dim('branch:')} ${report.landing.branch}`);
+      console.log(`  ${chalk.dim('strategy:')} ${report.landing.strategy}`);
+      if (report.landing.last_failure) {
+        console.log(`  ${chalk.red('failure:')} ${humanizeReasonCode(report.landing.last_failure.reason_code || 'landing_branch_materialization_failed')}`);
+        if (report.landing.last_failure.failed_branch) {
+          console.log(`  ${chalk.dim('failed branch:')} ${report.landing.last_failure.failed_branch}`);
+        }
+        if (report.landing.last_failure.conflicting_files?.length > 0) {
+          console.log(`  ${chalk.dim('conflicts:')} ${report.landing.last_failure.conflicting_files.join(', ')}`);
+        }
+        if (report.landing.last_failure.output) {
+          console.log(`  ${chalk.dim('details:')} ${report.landing.last_failure.output.split('\n')[0]}`);
+        }
+      } else if (report.landing.last_recovery?.recovery_path) {
+        console.log(`  ${chalk.dim('recovery path:')} ${report.landing.last_recovery.recovery_path}`);
+        if (report.landing.last_recovery.state?.status) {
+          console.log(`  ${chalk.dim('recovery state:')} ${report.landing.last_recovery.state.status}`);
+        }
+      } else if (report.landing.last_materialized?.head_commit) {
+        console.log(`  ${chalk.green('head:')} ${report.landing.last_materialized.head_commit.slice(0, 12)}`);
+      } else if (report.landing.stale_reasons.length > 0) {
+        for (const reason of report.landing.stale_reasons) {
+          console.log(`  ${chalk.red('why:')} ${reason.summary}`);
+        }
+      } else if (report.landing.last_materialized) {
+        console.log(`  ${chalk.green('state:')} landing branch is current`);
+      } else {
+        console.log(`  ${chalk.yellow('state:')} landing branch has not been materialized yet`);
+      }
+      console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
       process.exitCode = 1;
-      return;
     }
-
-    console.log(`${chalk.green('✓')} Removed ${chalk.cyan(item.id)} from the merge queue`);
   });
 
 // ── pipeline ──────────────────────────────────────────────────────────────────
@@ -1926,6 +3776,7 @@ Examples:
   switchman pipeline start "Harden auth API permissions"
   switchman pipeline exec pipe-123 "/path/to/agent-command"
   switchman pipeline status pipe-123
+  switchman pipeline land pipe-123
 `);
 
 pipelineCmd
@@ -1978,10 +3829,33 @@ Examples:
 
     try {
       const result = getPipelineStatus(db, pipelineId);
+      let landing;
+      let landingError = null;
+      try {
+        landing = getPipelineLandingBranchStatus(db, repoRoot, pipelineId, {
+          requireCompleted: false,
+        });
+      } catch (err) {
+        landingError = String(err.message || 'Landing branch is not ready yet.');
+        landing = {
+          branch: null,
+          synthetic: false,
+          stale: false,
+          stale_reasons: [],
+          last_failure: null,
+          last_recovery: null,
+        };
+      }
+      const policyState = summarizePipelinePolicyState(db, result, loadChangePolicy(repoRoot), []);
       db.close();
 
       if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
+        console.log(JSON.stringify({
+          ...result,
+          landing_branch: landing,
+          landing_error: landingError,
+          policy_state: policyState,
+        }, null, 2));
         return;
       }
 
@@ -2000,6 +3874,7 @@ Examples:
       const focusLine = focusTask
         ? `${focusTask.title} ${chalk.dim(focusTask.id)}`
         : 'No pipeline tasks found.';
+      const landingLabel = buildLandingStateLabel(landing);
 
       console.log('');
       console.log(pipelineHealthColor('='.repeat(72)));
@@ -2013,6 +3888,11 @@ Examples:
         renderChip('failed', result.counts.failed, result.counts.failed > 0 ? chalk.red : chalk.green),
       ]));
       console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+      if (landingLabel) {
+        console.log(`${chalk.bold('Landing:')} ${landingLabel}`);
+      } else if (landingError) {
+        console.log(`${chalk.bold('Landing:')} ${chalk.yellow('not ready yet')} ${chalk.dim(landingError)}`);
+      }
 
       const runningLines = result.tasks.filter((task) => task.status === 'in_progress').slice(0, 4).map((task) => {
         const worktree = task.worktree || task.suggested_worktree || 'unassigned';
@@ -2028,49 +3908,298 @@ Examples:
           const reasonLabel = humanizeReasonCode(task.failure.reason_code);
           lines.push(`  ${chalk.red('why:')} ${task.failure.summary} ${chalk.dim(`(${reasonLabel})`)}`);
         }
-        if (task.next_action) lines.push(`  ${chalk.yellow('next:')} ${task.next_action}`);
-        return lines;
-      });
+        if (task.next_action) lines.push(`  ${chalk.yellow('next:')} ${task.next_action}`);
+        return lines;
+      });
+
+      const nextLines = result.tasks.filter((task) => task.status === 'pending').slice(0, 4).map((task) => {
+        const worktree = task.suggested_worktree || task.worktree || 'unassigned';
+        const blocked = task.blocked_by?.length ? ` ${chalk.dim(`blocked by ${task.blocked_by.join(', ')}`)}` : '';
+        return `${renderChip('NEXT', task.id, chalk.green)} ${task.title} ${chalk.dim(worktree)}${blocked}`;
+      });
+
+      const landingLines = landing.synthetic
+        ? [
+          `${renderChip(landing.stale ? 'STALE' : 'LAND', landing.branch, landing.stale ? chalk.red : chalk.green)} ${chalk.dim(`base ${landing.base_branch}`)}`,
+          ...(landing.last_failure
+            ? [
+              `  ${chalk.red('failure:')} ${humanizeReasonCode(landing.last_failure.reason_code || 'landing_branch_materialization_failed')}`,
+              ...(landing.last_failure.failed_branch ? [`  ${chalk.dim('failed branch:')} ${landing.last_failure.failed_branch}`] : []),
+            ]
+            : []),
+          ...(landing.last_recovery?.state?.status
+            ? [
+              `  ${chalk.dim('recovery:')} ${landing.last_recovery.state.status} ${landing.last_recovery.recovery_path}`,
+            ]
+            : []),
+          ...(landing.stale_reasons.length > 0
+            ? landing.stale_reasons.slice(0, 3).map((reason) => `  ${chalk.red('why:')} ${reason.summary}`)
+            : [landing.last_materialized
+              ? `  ${chalk.green('state:')} ready to queue`
+              : `  ${chalk.yellow('next:')} switchman pipeline land ${result.pipeline_id}`]),
+          (landing.last_failure?.command
+            ? `  ${chalk.yellow('next:')} ${landing.last_failure.command}`
+            : landing.stale
+            ? `  ${chalk.yellow('next:')} switchman pipeline land ${result.pipeline_id} --refresh`
+            : `  ${chalk.yellow('next:')} switchman queue add --pipeline ${result.pipeline_id}`),
+        ]
+        : [];
+
+      const policyLines = policyState.active
+        ? [
+          `${renderChip(policyState.enforcement.toUpperCase(), policyState.domains.join(','), policyState.enforcement === 'blocked' ? chalk.red : chalk.yellow)} ${policyState.summary}`,
+          `  ${chalk.dim('required:')} ${policyState.required_task_types.join(', ') || 'none'}`,
+          `  ${chalk.dim('satisfied:')} ${policyState.satisfied_task_types.join(', ') || 'none'}`,
+          `  ${chalk.dim('missing:')} ${policyState.missing_task_types.join(', ') || 'none'}`,
+          `  ${chalk.dim('overridden:')} ${policyState.overridden_task_types.join(', ') || 'none'}`,
+          ...policyState.requirement_status
+            .filter((requirement) => requirement.evidence.length > 0)
+            .slice(0, 4)
+            .map((requirement) => `  ${chalk.dim(`${requirement.task_type}:`)} ${requirement.evidence.map((entry) => entry.artifact_path ? `${entry.task_id} (${entry.artifact_path})` : entry.task_id).join(', ')}`),
+          ...policyState.overrides
+            .slice(0, 3)
+            .map((entry) => `  ${chalk.dim(`override ${entry.id}:`)} ${(entry.task_types || []).join(', ') || 'all'} by ${entry.approved_by || 'unknown'}`),
+        ]
+        : [chalk.green('No explicit change policy requirements are active for this pipeline.')];
+
+      const commandLines = [
+        `${chalk.cyan('$')} switchman pipeline exec ${result.pipeline_id} "/path/to/agent-command"`,
+        `${chalk.cyan('$')} switchman pipeline pr ${result.pipeline_id}`,
+        ...(landing.last_failure?.command ? [`${chalk.cyan('$')} ${landing.last_failure.command}`] : []),
+        ...(landing.synthetic && landing.stale ? [`${chalk.cyan('$')} switchman pipeline land ${result.pipeline_id} --refresh`] : []),
+        ...(result.counts.failed > 0 ? [`${chalk.cyan('$')} switchman pipeline status ${result.pipeline_id}`] : []),
+      ];
+
+      console.log('');
+      for (const block of [
+        renderPanel('Running now', runningLines.length > 0 ? runningLines : [chalk.dim('No tasks are actively running.')], runningLines.length > 0 ? chalk.cyan : chalk.green),
+        renderPanel('Blocked', blockedLines.length > 0 ? blockedLines : [chalk.green('Nothing blocked.')], blockedLines.length > 0 ? chalk.red : chalk.green),
+        renderPanel('Next up', nextLines.length > 0 ? nextLines : [chalk.dim('No pending tasks left.')], chalk.green),
+        renderPanel('Policy', policyLines, policyState.active ? (policyState.missing_task_types.length > 0 ? chalk.red : chalk.green) : chalk.green),
+        ...(landing.synthetic ? [renderPanel('Landing branch', landingLines, landing.stale ? chalk.red : chalk.cyan)] : []),
+        renderPanel('Next commands', commandLines, chalk.cyan),
+      ]) {
+        for (const line of block) console.log(line);
+        console.log('');
+      }
+    } catch (err) {
+      db.close();
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
+pipelineCmd
+  .command('pr <pipelineId>')
+  .description('Generate a PR-ready summary for a pipeline using the repo and AI gates')
+  .option('--json', 'Output raw JSON')
+  .action(async (pipelineId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const result = await buildPipelinePrSummary(db, repoRoot, pipelineId);
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(result.markdown);
+    } catch (err) {
+      db.close();
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
+pipelineCmd
+  .command('bundle <pipelineId> [outputDir]')
+  .description('Export a reviewer-ready PR bundle for a pipeline to disk')
+  .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 (pipelineId, outputDir, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const result = await exportPipelinePrBundle(db, repoRoot, pipelineId, outputDir || null);
+      db.close();
+
+      const githubTargets = resolveGitHubOutputTargets(opts);
+      if (githubTargets.stepSummaryPath || githubTargets.outputPath) {
+        writeGitHubPipelineLandingStatus({
+          result: result.landing_summary,
+          stepSummaryPath: githubTargets.stepSummaryPath,
+          outputPath: githubTargets.outputPath,
+        });
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(`${chalk.green('✓')} Exported PR bundle for ${chalk.cyan(result.pipeline_id)}`);
+      console.log(`  ${chalk.dim(result.output_dir)}`);
+      console.log(`  ${chalk.dim('json:')} ${result.files.summary_json}`);
+      console.log(`  ${chalk.dim('summary:')} ${result.files.summary_markdown}`);
+      console.log(`  ${chalk.dim('body:')} ${result.files.pr_body_markdown}`);
+      console.log(`  ${chalk.dim('landing json:')} ${result.files.landing_summary_json}`);
+      console.log(`  ${chalk.dim('landing md:')} ${result.files.landing_summary_markdown}`);
+    } catch (err) {
+      db.close();
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
+pipelineCmd
+  .command('land <pipelineId>')
+  .description('Create or refresh one landing branch for a completed pipeline')
+  .option('--base <branch>', 'Base branch for the landing branch', 'main')
+  .option('--branch <branch>', 'Custom landing branch name')
+  .option('--refresh', 'Rebuild the landing branch when a source branch or base branch has moved')
+  .option('--recover', 'Create a recovery worktree for an unresolved landing merge conflict')
+  .option('--replace-recovery', 'Replace an existing recovery worktree when creating a new one')
+  .option('--resume [path]', 'Validate a resolved recovery worktree and mark the landing branch ready again')
+  .option('--cleanup [path]', 'Remove a recorded recovery worktree after it is resolved or abandoned')
+  .option('--json', 'Output raw JSON')
+  .action((pipelineId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const selectedModes = [opts.refresh, opts.recover, Boolean(opts.resume), Boolean(opts.cleanup)].filter(Boolean).length;
+      if (selectedModes > 1) {
+        throw new Error('Choose only one of --refresh, --recover, --resume, or --cleanup.');
+      }
+      if (opts.recover) {
+        const result = preparePipelineLandingRecovery(db, repoRoot, pipelineId, {
+          baseBranch: opts.base,
+          landingBranch: opts.branch || null,
+          replaceExisting: Boolean(opts.replaceRecovery),
+        });
+        db.close();
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        console.log(`${chalk.green('✓')} ${result.reused_existing ? 'Recovery worktree already ready for' : 'Recovery worktree ready for'} ${chalk.cyan(result.pipeline_id)}`);
+        console.log(`  ${chalk.dim('branch:')} ${chalk.cyan(result.branch)}`);
+        console.log(`  ${chalk.dim('path:')} ${result.recovery_path}`);
+        if (result.reused_existing) {
+          console.log(`  ${chalk.dim('state:')} reusing existing recovery worktree`);
+        }
+        console.log(`  ${chalk.dim('blocked by:')} ${result.failed_branch}`);
+        if (result.conflicting_files.length > 0) {
+          console.log(`  ${chalk.dim('conflicts:')} ${result.conflicting_files.join(', ')}`);
+        }
+        console.log(`  ${chalk.yellow('inspect:')} ${result.inspect_command}`);
+        console.log(`  ${chalk.yellow('after resolving + commit:')} ${result.resume_command}`);
+        return;
+      }
+      if (opts.cleanup) {
+        const result = cleanupPipelineLandingRecovery(db, repoRoot, pipelineId, {
+          baseBranch: opts.base,
+          landingBranch: opts.branch || null,
+          recoveryPath: typeof opts.cleanup === 'string' ? opts.cleanup : null,
+        });
+        db.close();
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        console.log(`${chalk.green('✓')} Recovery worktree cleared for ${chalk.cyan(result.pipeline_id)}`);
+        console.log(`  ${chalk.dim('path:')} ${result.recovery_path}`);
+        console.log(`  ${chalk.dim('removed:')} ${result.removed ? 'yes' : 'no'}`);
+        console.log(`  ${chalk.yellow('next:')} switchman explain landing ${result.pipeline_id}`);
+        return;
+      }
+      if (opts.resume) {
+        const result = resumePipelineLandingRecovery(db, repoRoot, pipelineId, {
+          baseBranch: opts.base,
+          landingBranch: opts.branch || null,
+          recoveryPath: typeof opts.resume === 'string' ? opts.resume : null,
+        });
+        db.close();
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
 
-      const nextLines = result.tasks.filter((task) => task.status === 'pending').slice(0, 4).map((task) => {
-        const worktree = task.suggested_worktree || task.worktree || 'unassigned';
-        const blocked = task.blocked_by?.length ? ` ${chalk.dim(`blocked by ${task.blocked_by.join(', ')}`)}` : '';
-        return `${renderChip('NEXT', task.id, chalk.green)} ${task.title} ${chalk.dim(worktree)}${blocked}`;
+        console.log(`${chalk.green('✓')} ${result.already_resumed ? 'Landing recovery already resumed for' : 'Landing recovery resumed for'} ${chalk.cyan(result.pipeline_id)}`);
+        console.log(`  ${chalk.dim('branch:')} ${chalk.cyan(result.branch)}`);
+        console.log(`  ${chalk.dim('head:')} ${result.head_commit}`);
+        if (result.recovery_path) {
+          console.log(`  ${chalk.dim('recovery path:')} ${result.recovery_path}`);
+        }
+        if (result.already_resumed) {
+          console.log(`  ${chalk.dim('state:')} already aligned and ready to queue`);
+        }
+        console.log(`  ${chalk.yellow('next:')} ${result.resume_command}`);
+        return;
+      }
+
+      const result = materializePipelineLandingBranch(db, repoRoot, pipelineId, {
+        baseBranch: opts.base,
+        landingBranch: opts.branch || null,
+        requireCompleted: true,
+        refresh: Boolean(opts.refresh),
       });
+      db.close();
 
-      const commandLines = [
-        `${chalk.cyan('$')} switchman pipeline exec ${result.pipeline_id} "/path/to/agent-command"`,
-        `${chalk.cyan('$')} switchman pipeline pr ${result.pipeline_id}`,
-        ...(result.counts.failed > 0 ? [`${chalk.cyan('$')} switchman pipeline status ${result.pipeline_id}`] : []),
-      ];
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
 
-      console.log('');
-      for (const block of [
-        renderPanel('Running now', runningLines.length > 0 ? runningLines : [chalk.dim('No tasks are actively running.')], runningLines.length > 0 ? chalk.cyan : chalk.green),
-        renderPanel('Blocked', blockedLines.length > 0 ? blockedLines : [chalk.green('Nothing blocked.')], blockedLines.length > 0 ? chalk.red : chalk.green),
-        renderPanel('Next up', nextLines.length > 0 ? nextLines : [chalk.dim('No pending tasks left.')], chalk.green),
-        renderPanel('Next commands', commandLines, chalk.cyan),
-      ]) {
-        for (const line of block) console.log(line);
-        console.log('');
+      console.log(`${chalk.green('✓')} Landing branch ready for ${chalk.cyan(result.pipeline_id)}`);
+      console.log(`  ${chalk.dim('branch:')} ${chalk.cyan(result.branch)}`);
+      console.log(`  ${chalk.dim('base:')} ${result.base_branch}`);
+      console.log(`  ${chalk.dim('strategy:')} ${result.strategy}`);
+      console.log(`  ${chalk.dim('components:')} ${result.component_branches.join(', ')}`);
+      if (result.reused_existing) {
+        console.log(`  ${chalk.dim('state:')} already current`);
+      } else if (result.refreshed) {
+        console.log(`  ${chalk.dim('state:')} refreshed`);
       }
+      console.log(`  ${chalk.yellow('next:')} switchman queue add ${result.branch}`);
     } catch (err) {
       db.close();
-      console.error(chalk.red(err.message));
+      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
       process.exitCode = 1;
     }
   });
 
 pipelineCmd
-  .command('pr <pipelineId>')
-  .description('Generate a PR-ready summary for a pipeline using the repo and AI gates')
+  .command('publish <pipelineId> [outputDir]')
+  .description('Create a hosted GitHub pull request for a pipeline using gh')
+  .option('--base <branch>', 'Base branch for the pull request', 'main')
+  .option('--head <branch>', 'Head branch for the pull request (defaults to inferred pipeline branch)')
+  .option('--draft', 'Create the pull request as a draft')
+  .option('--gh-command <command>', 'Executable to use for GitHub CLI', 'gh')
   .option('--json', 'Output raw JSON')
-  .action(async (pipelineId, opts) => {
+  .action(async (pipelineId, outputDir, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
 
     try {
-      const result = await buildPipelinePrSummary(db, repoRoot, pipelineId);
+      const result = await publishPipelinePr(db, repoRoot, pipelineId, {
+        baseBranch: opts.base,
+        headBranch: opts.head || null,
+        draft: Boolean(opts.draft),
+        ghCommand: opts.ghCommand,
+        outputDir: outputDir || null,
+      });
       db.close();
 
       if (opts.json) {
@@ -2078,7 +4207,12 @@ pipelineCmd
         return;
       }
 
-      console.log(result.markdown);
+      console.log(`${chalk.green('✓')} Published PR for ${chalk.cyan(result.pipeline_id)}`);
+      console.log(`  ${chalk.dim('base:')} ${result.base_branch}`);
+      console.log(`  ${chalk.dim('head:')} ${result.head_branch}`);
+      if (result.output) {
+        console.log(`  ${chalk.dim(result.output)}`);
+      }
     } catch (err) {
       db.close();
       console.error(chalk.red(err.message));
@@ -2087,15 +4221,28 @@ pipelineCmd
   });
 
 pipelineCmd
-  .command('bundle <pipelineId> [outputDir]')
-  .description('Export a reviewer-ready PR bundle for a pipeline to disk')
+  .command('comment <pipelineId> [outputDir]')
+  .description('Post or update a GitHub PR comment with the pipeline landing summary')
+  .option('--pr <number>', 'Pull request number to comment on')
+  .option('--pr-from-env', 'Read the pull request number from GitHub Actions environment variables')
+  .option('--gh-command <command>', 'Executable to use for GitHub CLI', 'gh')
+  .option('--update-existing', 'Edit the last comment from this user instead of creating a new one')
   .option('--json', 'Output raw JSON')
   .action(async (pipelineId, outputDir, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
+    const prNumber = opts.pr || (opts.prFromEnv ? resolvePrNumberFromEnv() : null);
 
     try {
-      const result = await exportPipelinePrBundle(db, repoRoot, pipelineId, outputDir || null);
+      if (!prNumber) {
+        throw new Error('A pull request number is required. Pass `--pr <number>` or `--pr-from-env`.');
+      }
+      const result = await commentPipelinePr(db, repoRoot, pipelineId, {
+        prNumber,
+        ghCommand: opts.ghCommand,
+        outputDir: outputDir || null,
+        updateExisting: Boolean(opts.updateExisting),
+      });
       db.close();
 
       if (opts.json) {
@@ -2103,11 +4250,12 @@ pipelineCmd
         return;
       }
 
-      console.log(`${chalk.green('✓')} Exported PR bundle for ${chalk.cyan(result.pipeline_id)}`);
-      console.log(`  ${chalk.dim(result.output_dir)}`);
-      console.log(`  ${chalk.dim('json:')} ${result.files.summary_json}`);
-      console.log(`  ${chalk.dim('summary:')} ${result.files.summary_markdown}`);
-      console.log(`  ${chalk.dim('body:')} ${result.files.pr_body_markdown}`);
+      console.log(`${chalk.green('✓')} Posted pipeline comment for ${chalk.cyan(result.pipeline_id)}`);
+      console.log(`  ${chalk.dim('pr:')} #${result.pr_number}`);
+      console.log(`  ${chalk.dim('body:')} ${result.bundle.files.landing_summary_markdown}`);
+      if (result.updated_existing) {
+        console.log(`  ${chalk.dim('mode:')} update existing comment`);
+      }
     } catch (err) {
       db.close();
       console.error(chalk.red(err.message));
@@ -2116,37 +4264,86 @@ pipelineCmd
   });
 
 pipelineCmd
-  .command('publish <pipelineId> [outputDir]')
-  .description('Create a hosted GitHub pull request for a pipeline using gh')
-  .option('--base <branch>', 'Base branch for the pull request', 'main')
-  .option('--head <branch>', 'Head branch for the pull request (defaults to inferred pipeline branch)')
-  .option('--draft', 'Create the pull request as a draft')
+  .command('sync-pr [pipelineId] [outputDir]')
+  .description('Build PR artifacts, emit GitHub outputs, and update the PR comment in one command')
+  .option('--pr <number>', 'Pull request number to comment on')
+  .option('--pr-from-env', 'Read the pull request number from GitHub Actions environment variables')
+  .option('--pipeline-from-env', 'Infer the pipeline id from the current GitHub branch context')
+  .option('--skip-missing-pipeline', 'Exit successfully when no matching pipeline can be inferred')
   .option('--gh-command <command>', 'Executable to use for GitHub CLI', 'gh')
+  .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('--no-comment', 'Skip updating the PR comment')
   .option('--json', 'Output raw JSON')
   .action(async (pipelineId, outputDir, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
+    const branchFromEnv = opts.pipelineFromEnv ? resolveBranchFromEnv() : null;
+    const resolvedPipelineId = pipelineId || (branchFromEnv ? inferPipelineIdFromBranch(db, branchFromEnv) : null);
+    const prNumber = opts.pr || (opts.prFromEnv ? resolvePrNumberFromEnv() : null);
 
     try {
-      const result = await publishPipelinePr(db, repoRoot, pipelineId, {
-        baseBranch: opts.base,
-        headBranch: opts.head || null,
-        draft: Boolean(opts.draft),
+      if (!resolvedPipelineId) {
+        if (!opts.skipMissingPipeline) {
+          throw new Error(opts.pipelineFromEnv
+            ? `Could not infer a pipeline from branch ${branchFromEnv || 'unknown'}. Pass a pipeline id explicitly or use a branch that maps to one Switchman pipeline.`
+            : 'A pipeline id is required. Pass one explicitly or use `--pipeline-from-env`.');
+        }
+        const skipped = {
+          skipped: true,
+          reason: 'no_pipeline_inferred',
+          branch: branchFromEnv,
+          next_action: 'Run `switchman pipeline status <pipelineId>` locally to confirm the pipeline id, then rerun sync-pr with that id.',
+        };
+        db.close();
+        if (opts.json) {
+          console.log(JSON.stringify(skipped, null, 2));
+          return;
+        }
+        console.log(`${chalk.green('✓')} No pipeline sync needed`);
+        if (branchFromEnv) {
+          console.log(`  ${chalk.dim('branch:')} ${branchFromEnv}`);
+        }
+        console.log(`  ${chalk.dim('reason:')} no matching Switchman pipeline was inferred`);
+        console.log(`  ${chalk.yellow('next:')} ${skipped.next_action}`);
+        return;
+      }
+
+      if (opts.comment !== false && !prNumber) {
+        throw new Error('A pull request number is required for comment sync. Pass `--pr <number>`, `--pr-from-env`, or `--no-comment`.');
+      }
+
+      const result = await syncPipelinePr(db, repoRoot, resolvedPipelineId, {
+        prNumber: opts.comment === false ? null : prNumber,
         ghCommand: opts.ghCommand,
         outputDir: outputDir || null,
+        updateExisting: true,
       });
       db.close();
 
+      const githubTargets = resolveGitHubOutputTargets(opts);
+      if (githubTargets.stepSummaryPath || githubTargets.outputPath) {
+        writeGitHubPipelineLandingStatus({
+          result: result.bundle.landing_summary,
+          stepSummaryPath: githubTargets.stepSummaryPath,
+          outputPath: githubTargets.outputPath,
+        });
+      }
+
       if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
       }
 
-      console.log(`${chalk.green('✓')} Published PR for ${chalk.cyan(result.pipeline_id)}`);
-      console.log(`  ${chalk.dim('base:')} ${result.base_branch}`);
-      console.log(`  ${chalk.dim('head:')} ${result.head_branch}`);
-      if (result.output) {
-        console.log(`  ${chalk.dim(result.output)}`);
+      console.log(`${chalk.green('✓')} Synced PR artifacts for ${chalk.cyan(result.pipeline_id)}`);
+      console.log(`  ${chalk.dim('bundle:')} ${result.bundle.output_dir}`);
+      if (result.comment) {
+        console.log(`  ${chalk.dim('pr:')} #${result.comment.pr_number}`);
+        console.log(`  ${chalk.dim('comment:')} updated existing`);
+      }
+      if (githubTargets.stepSummaryPath || githubTargets.outputPath) {
+        console.log(`  ${chalk.dim('github:')} wrote PR check artifacts`);
       }
     } catch (err) {
       db.close();
@@ -2200,6 +4397,53 @@ pipelineCmd
     }
   });
 
+pipelineCmd
+  .command('repair <pipelineId>')
+  .description('Safely repair interrupted landing state for one pipeline')
+  .option('--base <branch>', 'Base branch for landing repair checks', 'main')
+  .option('--branch <branch>', 'Custom landing branch name')
+  .option('--json', 'Output raw JSON')
+  .action((pipelineId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const result = repairPipelineState(db, repoRoot, pipelineId, {
+        baseBranch: opts.base,
+        landingBranch: opts.branch || null,
+      });
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      if (!result.repaired) {
+        console.log(`${chalk.green('✓')} No repair action needed for ${chalk.cyan(result.pipeline_id)}`);
+        for (const note of result.notes) {
+          console.log(`  ${chalk.dim(note)}`);
+        }
+        console.log(`  ${chalk.yellow('next:')} ${result.next_action}`);
+        return;
+      }
+
+      console.log(`${chalk.green('✓')} Repaired ${chalk.cyan(result.pipeline_id)}`);
+      for (const action of result.actions) {
+        if (action.kind === 'recovery_state_cleared') {
+          console.log(`  ${chalk.dim('cleared recovery record:')} ${action.recovery_path}`);
+        } else if (action.kind === 'landing_branch_refreshed') {
+          console.log(`  ${chalk.dim('refreshed landing branch:')} ${action.branch}${action.head_commit ? ` ${chalk.dim(action.head_commit.slice(0, 12))}` : ''}`);
+        }
+      }
+      console.log(`  ${chalk.yellow('next:')} ${result.next_action}`);
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
+      process.exitCode = 1;
+    }
+  });
+
 pipelineCmd
   .command('review <pipelineId>')
   .description('Inspect repo and AI gate failures for a pipeline and create follow-up fix tasks')
@@ -2985,9 +5229,48 @@ Use this first when the repo feels stuck.
     }
   });
 
+program
+  .command('repair')
+  .description('Repair safe interrupted queue and pipeline state across the repo')
+  .option('--json', 'Output raw JSON')
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const result = repairRepoState(db, repoRoot);
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      if (!result.repaired) {
+        printRepairSummary(result, {
+          repairedHeading: `${chalk.green('✓')} Repaired safe interrupted repo state`,
+          noRepairHeading: `${chalk.green('✓')} No repo repair action needed`,
+        });
+        console.log(`  ${chalk.yellow('next:')} ${result.next_action}`);
+        return;
+      }
+
+      printRepairSummary(result, {
+        repairedHeading: `${chalk.green('✓')} Repaired safe interrupted repo state`,
+        noRepairHeading: `${chalk.green('✓')} No repo repair action needed`,
+      });
+      console.log(`  ${chalk.yellow('next:')} ${result.next_action}`);
+    } catch (err) {
+      db.close();
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
 program
   .command('doctor')
   .description('Show one operator-focused health view: what is running, what is blocked, and what to do next')
+  .option('--repair', 'Repair safe interrupted queue and pipeline state before reporting health')
   .option('--json', 'Output raw JSON')
   .addHelpText('after', `
 Plain English:
@@ -3000,6 +5283,7 @@ Examples:
   .action(async (opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
+    const repairResult = opts.repair ? repairRepoState(db, repoRoot) : null;
     const tasks = listTasks(db);
     const activeLeases = listLeases(db, 'active');
     const staleLeases = getStaleLeases(db);
@@ -3017,10 +5301,19 @@ Examples:
     db.close();
 
     if (opts.json) {
-      console.log(JSON.stringify(report, null, 2));
+      console.log(JSON.stringify(opts.repair ? { ...report, repair: repairResult } : report, null, 2));
       return;
     }
 
+    if (opts.repair) {
+      printRepairSummary(repairResult, {
+        repairedHeading: `${chalk.green('✓')} Repaired safe interrupted repo state before running doctor`,
+        noRepairHeading: `${chalk.green('✓')} No repo repair action needed before doctor`,
+        limit: 6,
+      });
+      console.log('');
+    }
+
     const doctorColor = colorForHealth(report.health);
     const blockedCount = report.attention.filter((item) => item.severity === 'block').length;
     const warningCount = report.attention.filter((item) => item.severity !== 'block').length;
@@ -3071,6 +5364,19 @@ Examples:
       })
       : [chalk.green('Nothing urgent.')];
 
+    const staleClusterLines = report.merge_readiness.stale_clusters?.length > 0
+      ? report.merge_readiness.stale_clusters.slice(0, 5).flatMap((cluster) => {
+        const lines = [`${cluster.severity === 'block' ? renderChip('STALE', cluster.affected_pipeline_id || cluster.affected_task_ids[0], chalk.red) : renderChip('WATCH', cluster.affected_pipeline_id || cluster.affected_task_ids[0], chalk.yellow)} ${cluster.title}`];
+        lines.push(`  ${chalk.dim(cluster.detail)}`);
+        if (cluster.causal_group_size > 1) lines.push(`  ${chalk.dim('cause:')} ${cluster.causal_group_summary} ${chalk.dim(`(${cluster.causal_group_rank}/${cluster.causal_group_size} in same stale wave)`)}${cluster.related_affected_pipelines?.length ? ` ${chalk.dim(`related:${cluster.related_affected_pipelines.join(', ')}`)}` : ''}`);
+        lines.push(`  ${chalk.dim('areas:')} ${cluster.stale_areas.join(', ')}`);
+        lines.push(`  ${chalk.dim('rerun priority:')} ${cluster.rerun_priority} ${chalk.dim(`score:${cluster.rerun_priority_score}`)}${cluster.highest_affected_priority ? ` ${chalk.dim(`affected-priority:${cluster.highest_affected_priority}`)}` : ''}${cluster.rerun_breadth_score ? ` ${chalk.dim(`breadth:${cluster.rerun_breadth_score}`)}` : ''}`);
+        lines.push(`  ${chalk.yellow('next:')} ${cluster.next_step}`);
+        lines.push(`  ${chalk.cyan('run:')} ${cluster.command}`);
+        return lines;
+      })
+      : [chalk.green('No stale dependency clusters.')];
+
     const nextStepLines = [
       ...report.next_steps.slice(0, 4).map((step) => `- ${step}`),
       '',
@@ -3082,6 +5388,7 @@ Examples:
     for (const block of [
       renderPanel('Running now', runningLines, chalk.cyan),
       renderPanel('Attention now', attentionLines, report.attention.some((item) => item.severity === 'block') ? chalk.red : report.attention.length > 0 ? chalk.yellow : chalk.green),
+      renderPanel('Stale clusters', staleClusterLines, report.merge_readiness.stale_clusters?.some((cluster) => cluster.severity === 'block') ? chalk.red : (report.merge_readiness.stale_clusters?.length || 0) > 0 ? chalk.yellow : chalk.green),
       renderPanel('Recommended next steps', nextStepLines, chalk.green),
     ]) {
       for (const line of block) console.log(line);
@@ -3101,6 +5408,39 @@ Examples:
 
 const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
 
+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')
@@ -3658,7 +5998,7 @@ monitorCmd
 
 // ── policy ───────────────────────────────────────────────────────────────────
 
-const policyCmd = program.command('policy').description('Manage enforcement policy exceptions');
+const policyCmd = program.command('policy').description('Manage enforcement and change-governance policy');
 
 policyCmd
   .command('init')
@@ -3675,4 +6015,133 @@ policyCmd
     console.log(`${chalk.green('✓')} Wrote enforcement policy to ${chalk.cyan(policyPath)}`);
   });
 
+policyCmd
+  .command('init-change')
+  .description('Write a starter change policy file for governed domains like auth, payments, and schema')
+  .action(() => {
+    const repoRoot = getRepo();
+    const policyPath = writeChangePolicy(repoRoot, DEFAULT_CHANGE_POLICY);
+    console.log(`${chalk.green('✓')} Wrote change policy to ${chalk.cyan(policyPath)}`);
+  });
+
+policyCmd
+  .command('show-change')
+  .description('Show the active change policy for this repo')
+  .option('--json', 'Output raw JSON')
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const policy = loadChangePolicy(repoRoot);
+    const policyPath = getChangePolicyPath(repoRoot);
+
+    if (opts.json) {
+      console.log(JSON.stringify({ path: policyPath, policy }, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold('Change policy'));
+    console.log(`  ${chalk.dim('path:')} ${policyPath}`);
+    for (const [domain, rule] of Object.entries(policy.domain_rules || {})) {
+      console.log(`  ${chalk.cyan(domain)} ${chalk.dim(rule.enforcement)}`);
+      console.log(`    ${chalk.dim('requires:')} ${(rule.required_completed_task_types || []).join(', ') || 'none'}`);
+    }
+  });
+
+policyCmd
+  .command('override <pipelineId>')
+  .description('Record a policy override for one pipeline requirement or task type')
+  .requiredOption('--task-types <types>', 'Comma-separated task types to override, e.g. tests,governance')
+  .requiredOption('--reason <text>', 'Why this override is being granted')
+  .option('--by <actor>', 'Who approved the override', 'operator')
+  .option('--json', 'Output raw JSON')
+  .action((pipelineId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+    const taskTypes = String(opts.taskTypes || '')
+      .split(',')
+      .map((value) => value.trim())
+      .filter(Boolean);
+
+    if (taskTypes.length === 0) {
+      db.close();
+      printErrorWithNext('At least one task type is required for a policy override.', 'switchman policy override <pipelineId> --task-types tests --reason "why"');
+      process.exit(1);
+    }
+
+    const override = createPolicyOverride(db, {
+      pipelineId,
+      taskTypes,
+      requirementKeys: taskTypes.map((taskType) => `completed_task_type:${taskType}`),
+      reason: opts.reason,
+      approvedBy: opts.by || null,
+    });
+    db.close();
+
+    if (opts.json) {
+      console.log(JSON.stringify({ override }, null, 2));
+      return;
+    }
+
+    console.log(`${chalk.yellow('!')} Policy override ${chalk.cyan(override.id)} recorded for ${chalk.cyan(pipelineId)}`);
+    console.log(`  ${chalk.dim('task types:')} ${taskTypes.join(', ')}`);
+    console.log(`  ${chalk.dim('approved by:')} ${opts.by || 'operator'}`);
+    console.log(`  ${chalk.dim('reason:')} ${opts.reason}`);
+    console.log(`  ${chalk.dim('next:')} switchman pipeline status ${pipelineId}`);
+  });
+
+policyCmd
+  .command('revoke <overrideId>')
+  .description('Revoke a previously recorded policy override')
+  .option('--reason <text>', 'Why the override is being revoked')
+  .option('--by <actor>', 'Who revoked the override', 'operator')
+  .option('--json', 'Output raw JSON')
+  .action((overrideId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+    const override = revokePolicyOverride(db, overrideId, {
+      revokedBy: opts.by || null,
+      reason: opts.reason || null,
+    });
+    db.close();
+
+    if (opts.json) {
+      console.log(JSON.stringify({ override }, null, 2));
+      return;
+    }
+
+    console.log(`${chalk.green('✓')} Policy override ${chalk.cyan(override.id)} revoked`);
+    console.log(`  ${chalk.dim('pipeline:')} ${override.pipeline_id}`);
+    console.log(`  ${chalk.dim('revoked by:')} ${opts.by || 'operator'}`);
+    if (opts.reason) {
+      console.log(`  ${chalk.dim('reason:')} ${opts.reason}`);
+    }
+  });
+
+policyCmd
+  .command('list-overrides <pipelineId>')
+  .description('Show policy overrides recorded for a pipeline')
+  .option('--json', 'Output raw JSON')
+  .action((pipelineId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+    const overrides = listPolicyOverrides(db, { pipelineId, limit: 100 });
+    db.close();
+
+    if (opts.json) {
+      console.log(JSON.stringify({ pipeline_id: pipelineId, overrides }, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold(`Policy overrides for ${pipelineId}`));
+    if (overrides.length === 0) {
+      console.log(`  ${chalk.green('No overrides recorded.')}`);
+      return;
+    }
+    for (const entry of overrides) {
+      console.log(`  ${chalk.cyan(entry.id)} ${chalk.dim(entry.status)}`);
+      console.log(`    ${chalk.dim('task types:')} ${(entry.task_types || []).join(', ') || 'none'}`);
+      console.log(`    ${chalk.dim('approved by:')} ${entry.approved_by || 'unknown'}`);
+      console.log(`    ${chalk.dim('reason:')} ${entry.reason}`);
+    }
+  });
+
 program.parse();