switchman-dev 0.1.6 → 0.1.8

package/src/cli/index.js

@@ -16,34 +16,41 @@
  *   switchman status             - Show the repo dashboard
  */
 
-import { program } from 'commander';
+import { Help, 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, createGitWorktree, findRepoRoot, getWorktreeBranch, getWorktreeChangedFiles, gitAssessBranchFreshness, gitBranchExists, listGitWorktrees } 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,
+  upsertTaskSpec,
+  listAuditEvents, pruneDatabaseMaintenance, 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 { ensureProjectLocalMcpGitExcludes, getWindsurfMcpConfigPath, upsertAllProjectMcpConfigs, upsertWindsurfMcpConfig } from '../core/mcp.js';
+import { evaluateRepoCompliance, 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, evaluateQueueRepoGate, resolveQueueSource, runMergeQueue } from '../core/queue.js';
+import { DEFAULT_CHANGE_POLICY, DEFAULT_LEASE_POLICY, getChangePolicyPath, loadChangePolicy, loadLeasePolicy, writeChangePolicy, writeLeasePolicy } from '../core/policy.js';
+import { planPipelineTasks } from '../core/planner.js';
 import {
   captureTelemetryEvent,
   disableTelemetry,
@@ -54,6 +61,20 @@ import {
   maybePromptForTelemetry,
   sendTelemetryEvent,
 } from '../core/telemetry.js';
+import { checkLicence, clearCredentials, FREE_AGENT_LIMIT, getRetentionDaysForCurrentPlan, loginWithGitHub, PRO_PAGE_URL, readCredentials } from '../core/licence.js';
+import { homedir } from 'os';
+import { cleanupOldSyncEvents, pullActiveTeamMembers, pullTeamState, pushSyncEvent } from '../core/sync.js';
+
+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 +100,225 @@ function getDb(repoRoot) {
   }
 }
 
+function getOptionalDb(repoRoot) {
+  try {
+    return openDb(repoRoot);
+  } catch {
+    return null;
+  }
+}
+
+function slugifyValue(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'plan';
+}
+
+function capitalizeSentence(value) {
+  const text = String(value || '').trim();
+  if (!text) return text;
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+function formatHumanList(values = []) {
+  if (values.length === 0) return '';
+  if (values.length === 1) return values[0];
+  if (values.length === 2) return `${values[0]} and ${values[1]}`;
+  return `${values.slice(0, -1).join(', ')}, and ${values[values.length - 1]}`;
+}
+
+function readPlanningFile(repoRoot, fileName, maxChars = 1200) {
+  const filePath = join(repoRoot, fileName);
+  if (!existsSync(filePath)) return null;
+  try {
+    const text = readFileSync(filePath, 'utf8').trim();
+    if (!text) return null;
+    return {
+      file: fileName,
+      text: text.slice(0, maxChars),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function extractMarkdownSignal(text) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  for (const line of lines) {
+    const normalized = line.replace(/^#+\s*/, '').replace(/^[-*]\s+/, '').trim();
+    if (!normalized) continue;
+    if (/^switchman\b/i.test(normalized)) continue;
+    return normalized;
+  }
+  return null;
+}
+
+function deriveGoalFromBranch(branchName) {
+  const raw = String(branchName || '').replace(/^refs\/heads\//, '').trim();
+  if (!raw || ['main', 'master', 'trunk', 'develop', 'development'].includes(raw)) return null;
+  const tail = raw.split('/').pop() || raw;
+  const tokens = tail
+    .replace(/^\d+[-_]?/, '')
+    .split(/[-_]/)
+    .filter(Boolean)
+    .filter((token) => !['feature', 'feat', 'fix', 'bugfix', 'chore', 'task', 'issue', 'story', 'work'].includes(token.toLowerCase()));
+  if (tokens.length === 0) return null;
+  return capitalizeSentence(tokens.join(' '));
+}
+
+function getRecentCommitSubjects(repoRoot, limit = 6) {
+  try {
+    return execSync(`git log --pretty=%s -n ${limit}`, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim().split('\n').map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function summarizeRecentCommitContext(branchGoal, subjects) {
+  if (!subjects.length) return null;
+  const topicWords = String(branchGoal || '')
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((word) => word.length >= 4);
+  const relatedCount = topicWords.length > 0
+    ? subjects.filter((subject) => {
+      const lower = subject.toLowerCase();
+      return topicWords.some((word) => lower.includes(word));
+    }).length
+    : 0;
+  const effectiveCount = relatedCount > 0 ? relatedCount : Math.min(subjects.length, 3);
+  const topicLabel = relatedCount > 0 && topicWords.length > 0 ? `${topicWords[0]}-related ` : '';
+  return `${effectiveCount} recent ${topicLabel}commit${effectiveCount === 1 ? '' : 's'}`;
+}
+
+function collectPlanContext(repoRoot, explicitGoal = null) {
+  const planningFiles = ['CLAUDE.md', 'ROADMAP.md', 'tasks.md', 'TASKS.md', 'TODO.md', 'README.md']
+    .map((fileName) => readPlanningFile(repoRoot, fileName))
+    .filter(Boolean);
+  const planningByName = new Map(planningFiles.map((entry) => [entry.file, entry]));
+  const branch = getWorktreeBranch(process.cwd()) || null;
+  const branchGoal = deriveGoalFromBranch(branch);
+  const recentCommitSubjects = getRecentCommitSubjects(repoRoot, 6);
+  const recentCommitSummary = summarizeRecentCommitContext(branchGoal, recentCommitSubjects);
+  const preferredPlanningFile = planningByName.get('CLAUDE.md')
+    || planningByName.get('tasks.md')
+    || planningByName.get('TASKS.md')
+    || planningByName.get('ROADMAP.md')
+    || planningByName.get('TODO.md')
+    || planningByName.get('README.md')
+    || null;
+  const planningSignal = preferredPlanningFile ? extractMarkdownSignal(preferredPlanningFile.text) : null;
+  const title = capitalizeSentence(explicitGoal || branchGoal || planningSignal || 'Plan the next coordinated change');
+  const descriptionParts = [];
+  if (preferredPlanningFile?.text) descriptionParts.push(preferredPlanningFile.text);
+  if (recentCommitSubjects.length > 0) descriptionParts.push(`Recent git history summary: ${recentCommitSubjects.slice(0, 3).join('; ')}.`);
+  const description = descriptionParts.join('\n\n').trim() || null;
+
+  const found = [];
+  const used = [];
+  if (explicitGoal) {
+    used.push('explicit goal');
+  }
+  if (branch) {
+    found.push(`branch ${branch}`);
+    if (branchGoal) used.push('branch name');
+  }
+  if (preferredPlanningFile?.file) {
+    found.push(preferredPlanningFile.file);
+    used.push(preferredPlanningFile.file);
+  }
+  if (recentCommitSummary) {
+    found.push(recentCommitSummary);
+    used.push('recent git history');
+  }
+
+  return {
+    branch,
+    title,
+    description,
+    found,
+    used: [...new Set(used)],
+  };
+}
+
+function resolvePlanningWorktrees(repoRoot, db = null) {
+  if (db) {
+    const registered = listWorktrees(db)
+      .filter((worktree) => worktree.name !== 'main' && worktree.status !== 'missing')
+      .map((worktree) => ({ name: worktree.name, path: worktree.path, branch: worktree.branch }));
+    if (registered.length > 0) return registered;
+  }
+  return listGitWorktrees(repoRoot)
+    .filter((worktree) => !worktree.isMain)
+    .map((worktree) => ({ name: worktree.name, path: worktree.path, branch: worktree.branch || null }));
+}
+
+function planTaskPriority(taskSpec = null) {
+  const taskType = taskSpec?.task_type || 'implementation';
+  if (taskType === 'implementation') return 8;
+  if (taskType === 'tests') return 7;
+  if (taskType === 'docs') return 6;
+  if (taskType === 'governance') return 6;
+  return 5;
+}
+
+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,
@@ -223,15 +463,1203 @@ function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
-function boolBadge(ok) {
-  return ok ? chalk.green('OK   ') : chalk.yellow('CHECK');
+function boolBadge(ok) {
+  return ok ? chalk.green('OK   ') : chalk.yellow('CHECK');
+}
+
+function printErrorWithNext(message, nextCommand = null) {
+  console.error(chalk.red(message));
+  if (nextCommand) {
+    console.error(`${chalk.yellow('next:')} ${nextCommand}`);
+  }
+}
+
+function writeDemoFile(filePath, contents) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, contents);
+}
+
+function gitCommitAll(worktreePath, message) {
+  execSync('git add .', {
+    cwd: worktreePath,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  execSync(`git -c user.email="demo@switchman.dev" -c user.name="Switchman Demo" commit -m ${JSON.stringify(message)}`, {
+    cwd: worktreePath,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+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 {
+      claimFiles(db, taskDocs, 'agent2', ['src/auth.js']);
+    } catch (err) {
+      blockedClaimMessage = String(err.message || 'Claim blocked.');
+    }
+    claimFiles(db, taskDocs, 'agent2', ['docs/auth-flow.md']);
+
+    writeDemoFile(join(agent1Path, 'src', 'auth.js'), 'export function authHeader(token) {\n  return `Bearer ${token}`;\n}\n');
+    gitCommitAll(agent1Path, 'Add auth helper');
+    completeTask(db, taskAuth);
+
+    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;
+  }
+}
+
+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;
+}
+
+function buildQueueExplainReport(db, repoRoot, itemId) {
+  const item = getMergeQueueItem(db, itemId);
+  if (!item) {
+    throw new Error(`Queue item ${itemId} does not exist.`);
+  }
+
+  let resolved = null;
+  let resolutionError = null;
+  try {
+    resolved = resolveQueueSource(db, repoRoot, item);
+  } catch (err) {
+    resolutionError = err.message;
+  }
+
+  const recentEvents = listMergeQueueEvents(db, item.id, { limit: 5 });
+  return {
+    item,
+    resolved_source: resolved,
+    resolution_error: resolutionError,
+    next_action: item.next_action || inferQueueExplainNextAction(item, resolved, resolutionError),
+    recent_events: recentEvents,
+  };
+}
+
+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 (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.`;
+  }
+  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 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,
+    }];
+  });
+
+  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 buildStaleTaskExplainReport(db, taskId) {
+  const task = getTask(db, taskId);
+  if (!task) {
+    throw new Error(`Task ${taskId} does not exist.`);
+  }
+
+  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,
+  };
+}
+
+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'}`,
+  };
+}
+
+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 printErrorWithNext(message, nextCommand = null) {
-  console.error(chalk.red(message));
-  if (nextCommand) {
-    console.error(`${chalk.yellow('next:')} ${nextCommand}`);
+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 } = {}) {
@@ -515,6 +1943,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) => {
@@ -530,12 +1959,24 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
       };
     });
 
-  const blockedWorktrees = scanReport.unclaimedChanges.map((entry) => ({
-    worktree: entry.worktree,
-    files: entry.files,
-    reason_code: entry.reasons?.[0]?.reason_code || null,
-    next_step: nextStepForReason(entry.reasons?.[0]?.reason_code) || 'inspect the changed files and bring them back under Switchman claims',
-  }));
+  const worktreeByName = new Map((scanReport.worktrees || []).map((worktree) => [worktree.name, worktree]));
+  const blockedWorktrees = scanReport.unclaimedChanges.map((entry) => {
+    const worktreeInfo = worktreeByName.get(entry.worktree) || null;
+    const reasonCode = entry.reasons?.[0]?.reason_code || null;
+    const isDirtyWorktree = reasonCode === 'no_active_lease';
+    return {
+      worktree: entry.worktree,
+      path: worktreeInfo?.path || null,
+      files: entry.files,
+      reason_code: reasonCode,
+      next_step: isDirtyWorktree
+        ? 'commit or discard the changed files in that worktree, then rescan before continuing'
+        : (nextStepForReason(reasonCode) || 'inspect the changed files and bring them back under Switchman claims'),
+      command: worktreeInfo?.path
+        ? `cd ${JSON.stringify(worktreeInfo.path)} && git status`
+        : 'switchman scan',
+    };
+  });
 
   const fileConflicts = scanReport.fileConflicts.map((conflict) => ({
     file: conflict.file,
@@ -564,6 +2005,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',
@@ -584,9 +2026,9 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
     ...blockedWorktrees.map((entry) => ({
       kind: 'unmanaged_changes',
       title: `${entry.worktree} has unmanaged changed files`,
-      detail: `${entry.files.slice(0, 3).join(', ')}${entry.files.length > 3 ? ` +${entry.files.length - 3} more` : ''}`,
+      detail: `${entry.files.slice(0, 5).join(', ')}${entry.files.length > 5 ? ` +${entry.files.length - 5} more` : ''}${entry.path ? ` • ${entry.path}` : ''}`,
       next_step: entry.next_step,
-      command: 'switchman scan',
+      command: entry.command,
       severity: 'block',
     })),
     ...fileConflicts.map((conflict) => ({
@@ -651,14 +2093,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 +2113,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 +2162,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)
@@ -728,6 +2185,7 @@ function buildUnifiedStatusReport({
   queueItems,
   queueSummary,
   recentQueueEvents,
+  retentionDays = 7,
 }) {
   const queueAttention = [
     ...queueItems
@@ -776,6 +2234,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 +2261,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 +2286,11 @@ 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),
+    retention_days: retentionDays,
   };
 }
 
@@ -823,6 +2298,9 @@ async function collectStatusSnapshot(repoRoot) {
   const db = getDb(repoRoot);
   try {
     const leasePolicy = loadLeasePolicy(repoRoot);
+    const retentionDays = await getRetentionDaysForCurrentPlan();
+    pruneDatabaseMaintenance(db, { retentionDays });
+    cleanupOldSyncEvents({ retentionDays }).catch(() => {});
 
     if (leasePolicy.reap_on_status_check) {
       reapStaleLeases(db, leasePolicy.stale_after_minutes, {
@@ -862,13 +2340,40 @@ async function collectStatusSnapshot(repoRoot) {
       queueItems,
       queueSummary,
       recentQueueEvents,
+      retentionDays,
     });
   } finally {
     db.close();
   }
 }
 
-function renderUnifiedStatusReport(report) {
+function summarizeTeamCoordinationState(events = [], myUserId = null) {
+  const visibleEvents = events.filter((event) => event.user_id !== myUserId);
+  if (visibleEvents.length === 0) {
+    return {
+      members: 0,
+      queue_events: 0,
+      lease_events: 0,
+      claim_events: 0,
+      latest_queue_event: null,
+    };
+  }
+
+  const activeMembers = new Set(visibleEvents.map((event) => event.user_id || `${event.payload?.email || 'unknown'}:${event.worktree || 'unknown'}`));
+  const queueEvents = visibleEvents.filter((event) => ['queue_added', 'queue_merged', 'queue_blocked'].includes(event.event_type));
+  const leaseEvents = visibleEvents.filter((event) => ['lease_acquired', 'task_done', 'task_failed', 'task_retried'].includes(event.event_type));
+  const claimEvents = visibleEvents.filter((event) => ['claim_added', 'claim_released'].includes(event.event_type));
+
+  return {
+    members: activeMembers.size,
+    queue_events: queueEvents.length,
+    lease_events: leaseEvents.length,
+    claim_events: claimEvents.length,
+    latest_queue_event: queueEvents[0] || null,
+  };
+}
+
+function renderUnifiedStatusReport(report, { teamActivity = [], teamSummary = null } = {}) {
   const healthColor = colorForHealth(report.health);
   const badge = healthColor(healthLabel(report.health));
   const mergeColor = report.merge_readiness.ci_gate_ok ? chalk.green : chalk.red;
@@ -884,7 +2389,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 +2427,47 @@ 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'}`));
+  console.log(chalk.dim(`history retention: ${report.retention_days || 7} days`));
+  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'}`));
+  }
+
+  // ── Team activity (Pro cloud sync) ──────────────────────────────────────────
+  if (teamSummary && teamSummary.members > 0) {
+    console.log('');
+    console.log(chalk.bold('Shared cloud state:'));
+    console.log(`  ${chalk.dim('members:')} ${teamSummary.members}  ${chalk.dim('leases:')} ${teamSummary.lease_events}  ${chalk.dim('claims:')} ${teamSummary.claim_events}  ${chalk.dim('queue:')} ${teamSummary.queue_events}`);
+    if (teamSummary.latest_queue_event) {
+      console.log(`  ${chalk.dim('latest queue event:')} ${chalk.cyan(teamSummary.latest_queue_event.event_type)} ${chalk.dim(teamSummary.latest_queue_event.payload?.source_ref || teamSummary.latest_queue_event.payload?.item_id || '')}`.trim());
+    }
+  }
+  if (teamActivity.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Team activity:'));
+    for (const member of teamActivity) {
+      const email = member.payload?.email ?? chalk.dim(member.user_id?.slice(0, 8) ?? 'unknown');
+      const worktree = chalk.cyan(member.worktree ?? 'unknown');
+      const eventLabel = {
+        task_added:     'added a task',
+        task_done:      'completed a task',
+        task_failed:    'failed a task',
+        task_retried:   'retried a task',
+        lease_acquired: `working on: ${chalk.dim(member.payload?.title ?? '')}`,
+        claim_added:    `claimed ${chalk.dim(member.payload?.file_count ?? 0)} file(s)`,
+        claim_released: 'released file claims',
+        queue_added:    `queued ${chalk.dim(member.payload?.source_ref ?? member.payload?.item_id ?? 'work')}`,
+        queue_merged:   `landed ${chalk.dim(member.payload?.source_ref ?? member.payload?.item_id ?? 'work')}`,
+        queue_blocked:  `blocked ${chalk.dim(member.payload?.source_ref ?? member.payload?.item_id ?? 'work')}`,
+        status_ping:    'active',
+      }[member.event_type] ?? member.event_type;
+      console.log(`  ${chalk.dim('○')} ${email} · ${worktree} · ${eventLabel}`);
+    }
+  }
 
   const runningLines = report.active_work.length > 0
     ? report.active_work.slice(0, 5).map((item) => {
@@ -931,6 +2483,27 @@ function renderUnifiedStatusReport(report) {
 
   const blockedItems = report.attention.filter((item) => item.severity === 'block');
   const warningItems = report.attention.filter((item) => item.severity !== 'block');
+  const isQuietEmptyState = report.active_work.length === 0
+    && blockedItems.length === 0
+    && warningItems.length === 0
+    && report.queue.items.length === 0
+    && report.next_up.length === 0
+    && report.failed_tasks.length === 0;
+
+  if (isQuietEmptyState) {
+    console.log('');
+    console.log(healthColor('='.repeat(72)));
+    console.log(`${badge} ${chalk.bold('switchman status')} ${chalk.dim('• mission control for parallel agents')}`);
+    console.log(`${chalk.dim(report.repo_root)}`);
+    console.log(`${chalk.dim(report.summary)}`);
+    console.log(healthColor('='.repeat(72)));
+    console.log('');
+    console.log(chalk.green('Nothing is running yet.'));
+    console.log(`Add work with: ${chalk.cyan('switchman task add "Your first task" --priority 8')}`);
+    console.log(`Or prove the flow in 30 seconds with: ${chalk.cyan('switchman demo')}`);
+    console.log('');
+    return;
+  }
 
   const blockedLines = blockedItems.length > 0
     ? blockedItems.slice(0, 4).flatMap((item) => {
@@ -955,8 +2528,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 +2548,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 +2589,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),
   ];
@@ -1069,10 +2679,12 @@ function completeTaskWithRetries(repoRoot, taskId, attempts = 20) {
     let db = null;
     try {
       db = openDb(repoRoot);
-      completeTask(db, taskId);
-      releaseFileClaims(db, taskId);
+      const result = completeTask(db, taskId);
+      if (result?.status === 'completed') {
+        releaseFileClaims(db, taskId);
+      }
       db.close();
-      return;
+      return result;
     } catch (err) {
       lastError = err;
       try { db?.close(); } catch { /* no-op */ }
@@ -1085,6 +2697,210 @@ function completeTaskWithRetries(repoRoot, taskId, attempts = 20) {
   throw lastError;
 }
 
+function startBackgroundMonitor(repoRoot, { intervalMs = 2000, quarantine = false } = {}) {
+  const existingState = readMonitorState(repoRoot);
+  if (existingState && isProcessRunning(existingState.pid)) {
+    return {
+      already_running: true,
+      state: existingState,
+      state_path: getMonitorStatePath(repoRoot),
+    };
+  }
+
+  const logPath = join(repoRoot, '.switchman', 'monitor.log');
+  const child = spawn(process.execPath, [
+    process.argv[1],
+    'monitor',
+    'watch',
+    '--interval-ms',
+    String(intervalMs),
+    ...(quarantine ? ['--quarantine'] : []),
+    '--daemonized',
+  ], {
+    cwd: repoRoot,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  const statePath = writeMonitorState(repoRoot, {
+    pid: child.pid,
+    interval_ms: intervalMs,
+    quarantine: Boolean(quarantine),
+    log_path: logPath,
+    started_at: new Date().toISOString(),
+  });
+
+  return {
+    already_running: false,
+    state: readMonitorState(repoRoot),
+    state_path: statePath,
+  };
+}
+
+function renderMonitorEvent(event) {
+  const ownerText = event.owner_worktree
+    ? `${event.owner_worktree}${event.owner_task_id ? ` (${event.owner_task_id})` : ''}`
+    : null;
+  const claimCommand = event.task_id
+    ? `switchman claim ${event.task_id} ${event.worktree} ${event.file_path}`
+    : null;
+
+  if (event.status === 'denied') {
+    console.log(`${chalk.yellow('⚠')} ${chalk.cyan(event.worktree)} modified ${chalk.yellow(event.file_path)} without governed ownership`);
+    if (ownerText) {
+      console.log(`   ${chalk.dim('Owned by:')} ${chalk.cyan(ownerText)}${event.owner_task_title ? ` ${chalk.dim(`— ${event.owner_task_title}`)}` : ''}`);
+    }
+    if (claimCommand) {
+      console.log(`   ${chalk.dim('Run:')} ${chalk.cyan(claimCommand)}`);
+    }
+    console.log(`   ${chalk.dim('Or:')} ${chalk.cyan('switchman status')}  ${chalk.dim('to inspect current claims and blockers')}`);
+    if (event.enforcement_action) {
+      console.log(`   ${chalk.dim('Action:')} ${event.enforcement_action}`);
+    }
+    return;
+  }
+
+  const ownerSuffix = ownerText ? ` ${chalk.dim(`(${ownerText})`)}` : '';
+  console.log(`${chalk.green('✓')} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${ownerSuffix}`);
+}
+
+function resolveMonitoredWorktrees(db, repoRoot) {
+  const registeredByPath = new Map(
+    listWorktrees(db)
+      .filter((worktree) => worktree.path)
+      .map((worktree) => [worktree.path, worktree])
+  );
+
+  return listGitWorktrees(repoRoot).map((worktree) => {
+    const registered = registeredByPath.get(worktree.path);
+    if (!registered) return worktree;
+    return {
+      ...worktree,
+      name: registered.name,
+      path: registered.path || worktree.path,
+      branch: registered.branch || worktree.branch,
+    };
+  });
+}
+
+function discoverMergeCandidates(db, repoRoot, { targetBranch = 'main' } = {}) {
+  const worktrees = listWorktrees(db).filter((worktree) => worktree.name !== 'main');
+  const activeLeases = new Set(listLeases(db, 'active').map((lease) => lease.worktree));
+  const tasks = listTasks(db);
+  const queueItems = listMergeQueue(db).filter((item) => item.status !== 'merged');
+  const alreadyQueued = new Set(queueItems.map((item) => item.source_worktree).filter(Boolean));
+
+  const eligible = [];
+  const blocked = [];
+  const skipped = [];
+
+  for (const worktree of worktrees) {
+    const doneTasks = tasks.filter((task) => task.worktree === worktree.name && task.status === 'done');
+    if (doneTasks.length === 0) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'no_completed_tasks',
+        summary: 'no completed tasks are assigned to this worktree yet',
+        command: `switchman task list --status done`,
+      });
+      continue;
+    }
+
+    if (!worktree.branch || worktree.branch === targetBranch) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch || null,
+        reason: 'no_merge_branch',
+        summary: `worktree is on ${targetBranch} already`,
+        command: `switchman worktree list`,
+      });
+      continue;
+    }
+
+    if (!gitBranchExists(repoRoot, worktree.branch)) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'missing_branch',
+        summary: `branch ${worktree.branch} is not available in git`,
+        command: `switchman worktree sync`,
+      });
+      continue;
+    }
+
+    if (activeLeases.has(worktree.name)) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'active_lease',
+        summary: 'an active lease is still running in this worktree',
+        command: `switchman status`,
+      });
+      continue;
+    }
+
+    if (alreadyQueued.has(worktree.name)) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'already_queued',
+        summary: 'worktree is already in the landing queue',
+        command: `switchman queue status`,
+      });
+      continue;
+    }
+
+    const dirtyFiles = getWorktreeChangedFiles(worktree.path, repoRoot);
+    if (dirtyFiles.length > 0) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        path: worktree.path,
+        files: dirtyFiles,
+        reason: 'dirty_worktree',
+        summary: `worktree has uncommitted changes: ${dirtyFiles.slice(0, 5).join(', ')}${dirtyFiles.length > 5 ? ` +${dirtyFiles.length - 5} more` : ''}`,
+        command: `cd ${JSON.stringify(worktree.path)} && git status`,
+      });
+      continue;
+    }
+
+    const freshness = gitAssessBranchFreshness(repoRoot, targetBranch, worktree.branch);
+    eligible.push({
+      worktree: worktree.name,
+      branch: worktree.branch,
+      path: worktree.path,
+      done_task_count: doneTasks.length,
+      done_task_titles: doneTasks.slice(0, 3).map((task) => task.title),
+      freshness,
+    });
+  }
+
+  return { eligible, blocked, skipped, queue_items: queueItems };
+}
+
+function printMergeDiscovery(discovery) {
+  console.log('');
+  console.log(chalk.bold(`Checking ${discovery.eligible.length + discovery.blocked.length + discovery.skipped.length} worktree(s)...`));
+
+  for (const entry of discovery.eligible) {
+    const freshness = entry.freshness?.state && entry.freshness.state !== 'unknown'
+      ? ` ${chalk.dim(`(${entry.freshness.state})`)}`
+      : '';
+    console.log(`  ${chalk.green('✓')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch)}${freshness}`);
+  }
+
+  for (const entry of discovery.blocked) {
+    console.log(`  ${chalk.yellow('!')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch || 'no branch')}  ${chalk.dim(`— ${entry.summary}`)}`);
+  }
+
+  for (const entry of discovery.skipped) {
+    if (entry.reason === 'no_completed_tasks') continue;
+    console.log(`  ${chalk.dim('·')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch || 'no branch')}  ${chalk.dim(`— ${entry.summary}`)}`);
+  }
+}
+
 // ─── Program ──────────────────────────────────────────────────────────────────
 
 program
@@ -1093,22 +2909,131 @@ program
   .version('0.1.0');
 
 program.showHelpAfterError('(run with --help for usage examples)');
+const ROOT_HELP_COMMANDS = new Set([
+  'advanced',
+  'demo',
+  'setup',
+  'verify-setup',
+  'login',
+  'upgrade',
+  'plan',
+  'task',
+  'status',
+  'merge',
+  'repair',
+  'help',
+]);
+program.configureHelp({
+  visibleCommands(cmd) {
+    const commands = Help.prototype.visibleCommands.call(this, cmd);
+    if (cmd.parent) return commands;
+    return commands.filter((command) => ROOT_HELP_COMMANDS.has(command.name()) && !command._switchmanAdvanced);
+  },
+});
 program.addHelpText('after', `
 Start here:
-  switchman setup --agents 5
+  switchman demo
+  switchman setup --agents 3
+  switchman task add "Your task" --priority 8
   switchman status --watch
-  switchman gate ci
+  switchman gate ci && switchman queue run
 
-Most useful commands:
-  switchman task add "Implement auth helper" --priority 9
-  switchman lease next --json
-  switchman queue run --watch
+For you (the operator):
+  switchman demo
+  switchman setup
+  switchman task add
+  switchman status
+  switchman merge
+  switchman repair
+  switchman upgrade
+  switchman login
+  switchman plan "Add authentication"   (Pro)
+
+For your agents (via CLAUDE.md or MCP):
+  switchman lease next
+  switchman claim
+  switchman task done
+  switchman write
+  switchman wrap
 
 Docs:
   README.md
-  docs/setup-cursor.md
+  docs/setup-claude-code.md
+
+Power tools:
+  switchman advanced --help
 `);
 
+const advancedCmd = program
+  .command('advanced')
+  .description('Show advanced, experimental, and power-user command groups')
+  .addHelpText('after', `
+Advanced operator commands:
+  switchman pipeline <...>
+  switchman audit <...>
+  switchman policy <...>
+  switchman monitor <...>
+  switchman repair
+
+Experimental commands:
+  switchman semantic <...>
+  switchman object <...>
+
+Compatibility aliases:
+  switchman doctor
+
+Tip:
+  The main help keeps the day-one workflow small on purpose.
+`)
+  .action(() => {
+    advancedCmd.outputHelp();
+  });
+advancedCmd._switchmanAdvanced = false;
+
+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
@@ -1127,12 +3052,16 @@ program
       }
 
       const mcpConfigWrites = installMcpConfig([...new Set([repoRoot, ...gitWorktrees.map((wt) => wt.path)])]);
+      const mcpExclude = ensureProjectLocalMcpGitExcludes(repoRoot);
 
       db.close();
       spinner.succeed(`Initialized in ${chalk.cyan(repoRoot)}`);
       console.log(chalk.dim(`  Found and registered ${gitWorktrees.length} git worktree(s)`));
       console.log(chalk.dim(`  Database: .switchman/switchman.db`));
       console.log(chalk.dim(`  MCP config: ${mcpConfigWrites.filter((result) => result.changed).length} file(s) written`));
+      if (mcpExclude.managed) {
+        console.log(chalk.dim(`  MCP excludes: ${mcpExclude.changed ? 'updated' : 'already set'} in .git/info/exclude`));
+      }
       console.log('');
       console.log(`Next steps:`);
       console.log(`  ${chalk.cyan('switchman task add "Fix the login bug"')}  — add a task`);
@@ -1152,6 +3081,8 @@ program
   .description('One-command setup: create agent workspaces and initialise Switchman')
   .option('-a, --agents <n>', 'Number of agent workspaces to create (default: 3)', '3')
   .option('--prefix <prefix>', 'Branch prefix (default: switchman)', 'switchman')
+  .option('--no-monitor', 'Do not start the background rogue-edit monitor')
+  .option('--monitor-interval-ms <ms>', 'Polling interval for the background monitor', '2000')
   .addHelpText('after', `
 Examples:
   switchman setup --agents 5
@@ -1165,6 +3096,24 @@ Examples:
       process.exit(1);
     }
 
+        if (agentCount > FREE_AGENT_LIMIT) {
+      const licence = await checkLicence();
+      if (!licence.valid) {
+        console.log('');
+        console.log(chalk.yellow(`  ⚠  Free tier supports up to ${FREE_AGENT_LIMIT} agents.`));
+        console.log('');
+        console.log(`  You requested ${chalk.cyan(agentCount)} agents — that requires ${chalk.bold('Switchman Pro')}.`);
+        console.log('');
+        console.log(`  ${chalk.dim('Upgrade at:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+        console.log(`  ${chalk.dim('Or run:   ')} ${chalk.cyan('switchman upgrade')}`);
+        console.log('');
+        process.exit(1);
+      }
+      if (licence.offline) {
+        console.log(chalk.dim(`  Pro licence verified (offline cache · ${Math.ceil((7 * 24 * 60 * 60 * 1000 - (Date.now() - (licence.cached_at ?? 0))) / (24 * 60 * 60 * 1000))}d remaining)`));
+      }
+    }
+
     const repoRoot = getRepo();
     const spinner = ora('Setting up Switchman...').start();
 
@@ -1210,6 +3159,12 @@ Examples:
       }
 
       const mcpConfigWrites = installMcpConfig([...new Set([repoRoot, ...created.map((wt) => wt.path)])]);
+      const mcpExclude = ensureProjectLocalMcpGitExcludes(repoRoot);
+
+      const monitorIntervalMs = Math.max(100, Number.parseInt(opts.monitorIntervalMs, 10) || 2000);
+      const monitorState = opts.monitor
+        ? startBackgroundMonitor(repoRoot, { intervalMs: monitorIntervalMs, quarantine: false })
+        : null;
 
       db.close();
 
@@ -1229,14 +3184,35 @@ Examples:
         const status = result.created ? 'created' : result.changed ? 'updated' : 'unchanged';
         console.log(`  ${chalk.green('✓')} ${chalk.cyan(result.path)} ${chalk.dim(`(${status})`)}`);
       }
+      if (mcpExclude.managed) {
+        console.log(`  ${chalk.green('✓')} ${chalk.cyan(mcpExclude.path)} ${chalk.dim(`(${mcpExclude.changed ? 'updated' : 'unchanged'})`)}`);
+      }
+
+      if (opts.monitor) {
+        console.log('');
+        console.log(chalk.bold('Monitor:'));
+        if (monitorState?.already_running) {
+          console.log(`  ${chalk.green('✓')} Background rogue-edit monitor already running ${chalk.dim(`(pid ${monitorState.state.pid})`)}`);
+        } else {
+          console.log(`  ${chalk.green('✓')} Started background rogue-edit monitor ${chalk.dim(`(pid ${monitorState?.state?.pid ?? 'unknown'})`)}`);
+        }
+        console.log(`    ${chalk.dim('interval:')} ${monitorIntervalMs}ms`);
+      }
 
       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(`  4. Run the final check and land finished work:`);
+      console.log(`     ${chalk.cyan('switchman gate ci')}`);
+      console.log(`     ${chalk.cyan('switchman queue run')}`);
+      if (opts.monitor) {
+        console.log(`  5. Watch for rogue edits or direct writes in real time:`);
+        console.log(`     ${chalk.cyan('switchman monitor status')}`);
+      }
       console.log('');
 
       const verification = collectSetupVerification(repoRoot);
@@ -1419,6 +3395,132 @@ Examples:
   });
 
 
+// ── plan ──────────────────────────────────────────────────────────────────────
+
+program
+  .command('plan [goal]')
+  .description('Pro: suggest a parallel task plan from an explicit goal')
+  .option('--apply', 'Create the suggested tasks in Switchman')
+  .option('--max-tasks <n>', 'Maximum number of suggested tasks', '6')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman plan "Add authentication"
+  switchman plan "Add authentication" --apply
+`)
+  .action(async (goal, opts) => {
+    const repoRoot = getRepo();
+    const db = getOptionalDb(repoRoot);
+
+    try {
+      const licence = await checkLicence();
+      if (!licence.valid) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  AI planning requires Switchman Pro.'));
+        console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman upgrade')}`);
+        console.log(`  ${chalk.dim('Or visit:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
+      }
+
+      if (!goal || !goal.trim()) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  AI planning currently requires an explicit goal.'));
+        console.log(`  ${chalk.dim('Try:')} ${chalk.cyan('switchman plan "Add authentication"')}`);
+        console.log(`  ${chalk.dim('Then:')} ${chalk.cyan('switchman plan "Add authentication" --apply')}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
+      }
+
+      const context = collectPlanContext(repoRoot, goal || null);
+      const planningWorktrees = resolvePlanningWorktrees(repoRoot, db);
+      const pipelineId = `plan-${slugifyValue(context.title)}-${Date.now().toString(36)}`;
+      const plannedTasks = planPipelineTasks({
+        pipelineId,
+        title: context.title,
+        description: context.description,
+        worktrees: planningWorktrees,
+        maxTasks: Math.max(1, parseInt(opts.maxTasks, 10) || 6),
+        repoRoot,
+      });
+
+      if (opts.json) {
+        const payload = {
+          title: context.title,
+          context: {
+            found: context.found,
+            used: context.used,
+            branch: context.branch,
+          },
+          planned_tasks: plannedTasks.map((task) => ({
+            id: task.id,
+            title: task.title,
+            suggested_worktree: task.suggested_worktree || null,
+            task_type: task.task_spec?.task_type || null,
+            dependencies: task.dependencies || [],
+          })),
+          apply_ready: Boolean(db),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(chalk.bold('Reading repo context...'));
+      if (context.found.length > 0) {
+        console.log(`${chalk.dim('Found:')} ${context.found.join(', ')}`);
+      } else {
+        console.log(chalk.dim('Found: local repo context only'));
+      }
+      console.log('');
+      console.log(`${chalk.bold('Suggested plan based on:')} ${context.used.length > 0 ? formatHumanList(context.used) : 'available repo context'}`);
+      console.log('');
+
+      plannedTasks.forEach((task, index) => {
+        const worktreeLabel = task.suggested_worktree ? chalk.cyan(task.suggested_worktree) : chalk.dim('unassigned');
+        console.log(`  ${chalk.green('✓')} ${chalk.bold(`${index + 1}.`)} ${task.title}  ${chalk.dim('→')} ${worktreeLabel}`);
+      });
+
+      if (!opts.apply) {
+        console.log('');
+        if (!db) {
+          console.log(chalk.dim('Preview only — run `switchman setup --agents 3` first if you want Switchman to create and track these tasks.'));
+        } else {
+          console.log(chalk.dim('Preview only — rerun with `switchman plan --apply` to create these tasks.'));
+        }
+        return;
+      }
+
+      if (!db) {
+        console.log('');
+        console.log(`${chalk.red('✗')} Switchman is not set up in this repo yet.`);
+        console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman setup --agents 3')}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      console.log('');
+      for (const task of plannedTasks) {
+        createTask(db, {
+          id: task.id,
+          title: task.title,
+          description: `Planned from: ${context.title}`,
+          priority: planTaskPriority(task.task_spec),
+        });
+        upsertTaskSpec(db, task.id, task.task_spec);
+        console.log(`  ${chalk.green('✓')} Created ${chalk.cyan(task.id)} ${chalk.dim(task.title)}`);
+      }
+
+      console.log('');
+      console.log(`${chalk.green('✓')} Planned ${plannedTasks.length} task(s) from repo context.`);
+      console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman status --watch')}`);
+    } finally {
+      db?.close();
+    }
+  });
+
+
 // ── task ──────────────────────────────────────────────────────────────────────
 
 const taskCmd = program.command('task').description('Manage the task list');
@@ -1447,6 +3549,7 @@ taskCmd
     db.close();
     const scopeWarning = analyzeTaskScope(title, opts.description || '');
     console.log(`${chalk.green('✓')} Task created: ${chalk.cyan(taskId)}`);
+    pushSyncEvent('task_added', { task_id: taskId, title, priority: parseInt(opts.priority) }).catch(() => {});
     console.log(`  ${chalk.dim(title)}`);
     if (scopeWarning) {
       console.log(chalk.yellow(`  warning: ${scopeWarning.summary}`));
@@ -1497,14 +3600,99 @@ 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`);
+    pushSyncEvent('task_retried', { task_id: task.id, title: task.title, reason: opts.reason || 'manual retry' }).catch(() => {});
+    console.log(`  ${chalk.dim('title:')} ${task.title}`);
+    console.log(`${chalk.yellow('next:')} switchman task assign ${task.id} <workspace>`);
+  });
+
+taskCmd
+  .command('retry-stale')
+  .description('Return all currently stale tasks to pending so they can be revalidated together')
+  .option('--pipeline <id>', 'Only retry stale tasks for one pipeline')
+  .option('--reason <text>', 'Reason to record for the retry', 'bulk stale retry')
+  .option('--json', 'Output raw JSON')
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+    const result = retryStaleTasks(db, {
+      pipelineId: opts.pipeline || null,
+      reason: opts.reason,
+    });
+    db.close();
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    if (result.retried.length === 0) {
+      const scope = result.pipeline_id ? ` for ${result.pipeline_id}` : '';
+      console.log(chalk.dim(`No stale tasks to retry${scope}.`));
+      return;
+    }
+
+    console.log(`${chalk.green('✓')} Reset ${result.retried.length} stale task(s) to pending`);
+    pushSyncEvent('task_retried', {
+      pipeline_id: result.pipeline_id || null,
+      task_count: result.retried.length,
+      task_ids: result.retried.map((task) => task.id),
+      reason: opts.reason,
+    }).catch(() => {});
+    if (result.pipeline_id) {
+      console.log(`  ${chalk.dim('pipeline:')} ${result.pipeline_id}`);
+    }
+    console.log(`  ${chalk.dim('tasks:')} ${result.retried.map((task) => task.id).join(', ')}`);
+    console.log(`${chalk.yellow('next:')} switchman status`);
+  });
+
 taskCmd
   .command('done <taskId>')
   .description('Mark a task as complete and release all file claims')
   .action((taskId) => {
     const repoRoot = getRepo();
     try {
-      completeTaskWithRetries(repoRoot, taskId);
+      const result = completeTaskWithRetries(repoRoot, taskId);
+      if (result?.status === 'already_done') {
+        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} was already marked done — no new changes were recorded`);
+        return;
+      }
+      if (result?.status === 'failed') {
+        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} is currently failed — retry it before marking it done again`);
+        return;
+      }
+      if (result?.status === 'not_in_progress') {
+        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} is not currently in progress — start a lease before marking it done`);
+        return;
+      }
+      if (result?.status === 'no_active_lease') {
+        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} has no active lease — reacquire the task before marking it done`);
+        return;
+      }
       console.log(`${chalk.green('✓')} Task ${chalk.cyan(taskId)} marked done — file claims released`);
+      pushSyncEvent('task_done', { task_id: taskId }).catch(() => {});
     } catch (err) {
       console.error(chalk.red(err.message));
       process.exitCode = 1;
@@ -1521,6 +3709,7 @@ taskCmd
     releaseFileClaims(db, taskId);
     db.close();
     console.log(`${chalk.red('✗')} Task ${chalk.cyan(taskId)} marked failed`);
+    pushSyncEvent('task_failed', { task_id: taskId, reason: reason || null }).catch(() => {});
   });
 
 taskCmd
@@ -1584,8 +3773,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 +3799,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 = {
@@ -1627,6 +3837,13 @@ Examples:
 
       const result = enqueueMergeItem(db, payload);
       db.close();
+      pushSyncEvent('queue_added', {
+        item_id: result.id,
+        source_type: result.source_type,
+        source_ref: result.source_ref,
+        source_worktree: result.source_worktree || null,
+        target_branch: result.target_branch,
+      }, { worktree: result.source_worktree || null }).catch(() => {});
 
       if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -1636,6 +3853,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 +3887,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 +3920,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 +3931,23 @@ What it helps you answer:
       return;
     }
 
-    const queueHealth = summary.counts.blocked > 0 ? 'block' : summary.counts.retrying > 0 ? 'warn' : 'healthy';
+    if (items.length === 0) {
+      console.log('');
+      console.log(chalk.bold('switchman queue status'));
+      console.log('');
+      console.log('Queue is empty.');
+      console.log(`Add finished work with: ${chalk.cyan('switchman queue add --worktree agent1')}`);
+      return;
+    }
+
+    const queueHealth = summary.counts.blocked > 0
+      ? 'block'
+      : summary.counts.retrying > 0 || summary.counts.held > 0 || summary.counts.wave_blocked > 0 || summary.counts.escalated > 0
+        ? 'warn'
+        : 'healthy';
     const queueHealthColor = colorForHealth(queueHealth);
-    const 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 +3959,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 +3976,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 +4002,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 +4020,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 +4057,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 +4067,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 +4076,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,15 +4098,20 @@ 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 (mergeBudget !== null && aggregate.execution_policy.merged_count >= mergeBudget) break;
         if (result.processed.length === 0) {
           sleepSync(watchIntervalMs);
         }
@@ -1840,7 +4123,22 @@ Examples:
       }
 
       if (aggregate.processed.length === 0) {
-        console.log(chalk.dim('No queued merge items.'));
+        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,
@@ -1854,15 +4152,36 @@ Examples:
       for (const entry of aggregate.processed) {
         const item = entry.item;
         if (entry.status === 'merged') {
+          pushSyncEvent('queue_merged', {
+            item_id: item.id,
+            source_type: item.source_type,
+            source_ref: item.source_ref,
+            source_worktree: item.source_worktree || null,
+            target_branch: item.target_branch,
+            merged_commit: item.merged_commit || null,
+          }, { worktree: item.source_worktree || null }).catch(() => {});
           console.log(`${chalk.green('✓')} Merged ${chalk.cyan(item.id)} into ${chalk.bold(item.target_branch)}`);
           console.log(`  ${chalk.dim('commit:')} ${item.merged_commit}`);
         } else {
+          pushSyncEvent('queue_blocked', {
+            item_id: item.id,
+            source_type: item.source_type,
+            source_ref: item.source_ref,
+            source_worktree: item.source_worktree || null,
+            target_branch: item.target_branch,
+            error_code: item.last_error_code || null,
+            error_summary: item.last_error_summary || null,
+          }, { worktree: item.source_worktree || null }).catch(() => {});
           console.log(`${chalk.red('✗')} Blocked ${chalk.cyan(item.id)}`);
           console.log(`  ${chalk.red('why:')} ${item.last_error_summary}`);
           if (item.next_action) console.log(`  ${chalk.yellow('next:')} ${item.next_action}`);
         }
       }
 
+      if (aggregate.execution_policy.follow_plan) {
+        console.log(`${chalk.dim('plan-aware run:')} merged ${aggregate.execution_policy.merged_count}${aggregate.execution_policy.merge_budget !== null ? ` of ${aggregate.execution_policy.merge_budget}` : ''} budgeted item(s)`);
+      }
+
       await maybeCaptureTelemetry('queue_used', {
         watch,
         cycles: aggregate.cycles,
@@ -1876,6 +4195,142 @@ Examples:
     }
   });
 
+program
+  .command('merge')
+  .description('Queue finished worktrees and land safe work through one guided front door')
+  .option('--target <branch>', 'Target branch to merge into', 'main')
+  .option('--dry-run', 'Preview mergeable work without queueing or landing anything')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman merge
+  switchman merge --dry-run
+  switchman merge --target release
+`)
+  .action(async (opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const discovery = discoverMergeCandidates(db, repoRoot, { targetBranch: opts.target || 'main' });
+      const queued = [];
+
+      for (const entry of discovery.eligible) {
+        queued.push(enqueueMergeItem(db, {
+          sourceType: 'worktree',
+          sourceRef: entry.branch,
+          sourceWorktree: entry.worktree,
+          targetBranch: opts.target || 'main',
+          submittedBy: 'switchman merge',
+        }));
+      }
+
+      const queueItems = listMergeQueue(db);
+      const summary = buildQueueStatusSummary(queueItems, { db, repoRoot });
+      const mergeOrder = summary.recommended_sequence
+        .filter((item) => ['land_now', 'prepare_next'].includes(item.lane))
+        .map((item) => item.source_ref);
+
+      if (opts.json) {
+        if (opts.dryRun) {
+          console.log(JSON.stringify({ discovery, queued, summary, merge_order: mergeOrder, dry_run: true }, null, 2));
+          db.close();
+          return;
+        }
+
+        const gate = await evaluateQueueRepoGate(db, repoRoot);
+        const runnableCount = listMergeQueue(db).filter((item) => ['queued', 'retrying'].includes(item.status)).length;
+        const result = gate.ok
+          ? await runMergeQueue(db, repoRoot, {
+            targetBranch: opts.target || 'main',
+            maxItems: Math.max(1, runnableCount),
+            mergeBudget: Math.max(1, runnableCount),
+            followPlan: false,
+          })
+          : null;
+        console.log(JSON.stringify({ discovery, queued, summary, merge_order: mergeOrder, gate, result }, null, 2));
+        db.close();
+        return;
+      }
+
+      printMergeDiscovery(discovery);
+
+      if (discovery.blocked.length > 0) {
+        console.log('');
+        console.log(chalk.bold('Needs attention before landing:'));
+        for (const entry of discovery.blocked) {
+          console.log(`  ${chalk.yellow(entry.worktree)}: ${entry.summary}`);
+          console.log(`    ${chalk.dim('run:')} ${chalk.cyan(entry.command)}`);
+        }
+      }
+
+      if (mergeOrder.length > 0) {
+        console.log('');
+        console.log(`${chalk.bold('Merge order:')} ${mergeOrder.join(' → ')}`);
+      }
+
+      if (opts.dryRun) {
+        console.log('');
+        console.log(chalk.dim('Dry run only — nothing was landed.'));
+        db.close();
+        return;
+      }
+
+      if (discovery.eligible.length === 0) {
+        console.log('');
+        console.log(chalk.dim('No finished worktrees are ready to land yet.'));
+        console.log(`${chalk.yellow('next:')} ${chalk.cyan('switchman status')}`);
+        db.close();
+        return;
+      }
+
+      const gate = await evaluateQueueRepoGate(db, repoRoot);
+      if (!gate.ok) {
+        console.log('');
+        console.log(`${chalk.red('✗')} Merge gate blocked landing`);
+        console.log(`  ${chalk.dim(gate.summary)}`);
+        console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman gate ci')}`);
+        db.close();
+        return;
+      }
+
+      console.log('');
+      const runnableCount = listMergeQueue(db).filter((item) => ['queued', 'retrying'].includes(item.status)).length;
+      const result = await runMergeQueue(db, repoRoot, {
+        targetBranch: opts.target || 'main',
+        maxItems: Math.max(1, runnableCount),
+        mergeBudget: Math.max(1, runnableCount),
+        followPlan: false,
+      });
+
+      const merged = result.processed.filter((item) => item.status === 'merged');
+      for (const mergedItem of merged) {
+        console.log(`  ${chalk.green('✓')} Landed ${chalk.cyan(mergedItem.item.source_ref)} into ${chalk.bold(mergedItem.item.target_branch)}`);
+      }
+
+      if (merged.length > 0 && !result.deferred && result.processed.every((item) => item.status === 'merged')) {
+        console.log('');
+        console.log(`${chalk.green('✓')} Done. ${merged.length} worktree(s) landed cleanly.`);
+        db.close();
+        return;
+      }
+
+      const blocked = result.processed.find((item) => item.status !== 'merged')?.item || result.deferred || null;
+      if (blocked) {
+        console.log('');
+        console.log(`${chalk.yellow('!')} Landing stopped at ${chalk.cyan(blocked.source_ref)}`);
+        if (blocked.last_error_summary) console.log(`  ${chalk.dim(blocked.last_error_summary)}`);
+        if (blocked.next_action) console.log(`  ${chalk.yellow('next:')} ${blocked.next_action}`);
+      }
+
+      db.close();
+    } catch (err) {
+      db.close();
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
 queueCmd
   .command('retry <itemId>')
   .description('Retry a blocked merge queue item')
@@ -1900,6 +4355,40 @@ queueCmd
     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')
@@ -1909,23 +4398,302 @@ queueCmd
     const item = removeMergeQueueItem(db, itemId);
     db.close();
 
-    if (!item) {
-      printErrorWithNext(`Queue item ${itemId} does not exist.`, 'switchman queue status');
+    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(report, null, 2));
+        return;
+      }
+
+      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;
+      }
+
+      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}`);
+        }
+      }
+
+      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) {
+      db.close();
+      printErrorWithNext(err.message, 'switchman status');
+      process.exitCode = 1;
+    }
+  });
+
+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((taskId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    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;
+    }
+  });
+
+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);
+
+    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;
+    }
+  });
+
+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);
+
+    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 ──────────────────────────────────────────────────────────────────
 
 const pipelineCmd = program.command('pipeline').description('Create and summarize issue-to-PR execution pipelines');
+pipelineCmd._switchmanAdvanced = true;
 pipelineCmd.addHelpText('after', `
 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 +4746,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 +4791,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 +4805,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';
@@ -2038,9 +4835,55 @@ Examples:
         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}`] : []),
       ];
 
@@ -2049,6 +4892,8 @@ Examples:
         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);
@@ -2089,6 +4934,9 @@ pipelineCmd
 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();
@@ -2098,6 +4946,15 @@ pipelineCmd
       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;
@@ -2108,6 +4965,8 @@ pipelineCmd
       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));
@@ -2115,6 +4974,129 @@ pipelineCmd
     }
   });
 
+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;
+        }
+
+        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();
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      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();
+      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
+      process.exitCode = 1;
+    }
+  });
+
 pipelineCmd
   .command('publish <pipelineId> [outputDir]')
   .description('Create a hosted GitHub pull request for a pipeline using gh')
@@ -2155,6 +5137,138 @@ pipelineCmd
     }
   });
 
+pipelineCmd
+  .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 {
+      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) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      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));
+      process.exitCode = 1;
+    }
+  });
+
+pipelineCmd
+  .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 {
+      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('✓')} 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();
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
 pipelineCmd
   .command('run <pipelineId> [agentCommand...]')
   .description('Dispatch pending pipeline tasks onto available worktrees and optionally launch an agent command in each one')
@@ -2200,6 +5314,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')
@@ -2377,6 +5538,7 @@ Examples:
     }
 
     console.log(`${chalk.green('✓')} Lease acquired: ${chalk.bold(task.title)}`);
+    pushSyncEvent('lease_acquired', { task_id: task.id, title: task.title }, { worktree: worktreeName }).catch(() => {});
     console.log(`  ${chalk.dim('task:')} ${task.id}  ${chalk.dim('lease:')} ${lease.id}`);
     console.log(`  ${chalk.dim('worktree:')} ${chalk.cyan(worktreeName)}  ${chalk.dim('priority:')} ${task.priority}`);
   });
@@ -2559,25 +5721,31 @@ wtCmd
     const db = getDb(repoRoot);
     const worktrees = listWorktrees(db);
     const gitWorktrees = listGitWorktrees(repoRoot);
-    db.close();
 
     if (!worktrees.length && !gitWorktrees.length) {
+      db.close();
       console.log(chalk.dim('No workspaces found. Run `switchman setup --agents 3` or `switchman worktree sync`.'));
       return;
     }
 
     // Show git worktrees (source of truth) annotated with db info
+    const complianceReport = evaluateRepoCompliance(db, repoRoot, gitWorktrees);
     console.log('');
     console.log(chalk.bold('Git Worktrees:'));
     for (const wt of gitWorktrees) {
       const dbInfo = worktrees.find(d => d.path === wt.path);
+      const complianceInfo = complianceReport.worktreeCompliance.find((entry) => entry.worktree === wt.name) || null;
       const agent = dbInfo?.agent ? chalk.cyan(dbInfo.agent) : chalk.dim('no agent');
       const status = dbInfo?.status ? statusBadge(dbInfo.status) : chalk.dim('unregistered');
-      const compliance = dbInfo?.compliance_state ? statusBadge(dbInfo.compliance_state) : chalk.dim('unknown');
+      const compliance = complianceInfo?.compliance_state ? statusBadge(complianceInfo.compliance_state) : dbInfo?.compliance_state ? statusBadge(dbInfo.compliance_state) : chalk.dim('unknown');
       console.log(`  ${chalk.bold(wt.name.padEnd(20))} ${status} ${compliance} branch: ${chalk.cyan(wt.branch || 'unknown')}  agent: ${agent}`);
       console.log(`    ${chalk.dim(wt.path)}`);
+      if ((complianceInfo?.unclaimed_changed_files || []).length > 0) {
+        console.log(`    ${chalk.red('files:')} ${complianceInfo.unclaimed_changed_files.slice(0, 5).join(', ')}${complianceInfo.unclaimed_changed_files.length > 5 ? ` ${chalk.dim(`+${complianceInfo.unclaimed_changed_files.length - 5} more`)}` : ''}`);
+      }
     }
     console.log('');
+    db.close();
   });
 
 wtCmd
@@ -2601,13 +5769,14 @@ program
   .command('claim <taskId> <worktree> [files...]')
   .description('Lock files for a task before editing')
   .option('--agent <name>', 'Agent name')
-  .option('--force', 'Claim even if conflicts exist')
+  .option('--force', 'Emergency override for manual recovery when a conflicting claim is known to be stale or wrong')
   .addHelpText('after', `
 Examples:
   switchman claim task-123 agent2 src/auth.js src/server.js
   switchman claim task-123 agent2 src/auth.js --agent cursor
 
 Use this before editing files in a shared repo.
+Only use --force for operator-led recovery after checking switchman status or switchman explain claim <path>.
 `)
   .action((taskId, worktree, files, opts) => {
     if (!files.length) {
@@ -2626,7 +5795,7 @@ Use this before editing files in a shared repo.
         for (const c of conflicts) {
           console.log(`  ${chalk.yellow(c.file)} → already claimed by worktree ${chalk.cyan(c.claimedBy.worktree)} (task: ${c.claimedBy.task_title})`);
         }
-        console.log(chalk.dim('\nUse --force to claim anyway, or pick different files first.'));
+        console.log(chalk.dim('\nDo not use --force as a shortcut. Check status or explain the claim first, then only override if the existing claim is known-bad.'));
         console.log(`${chalk.yellow('next:')} switchman status`);
         process.exitCode = 1;
         return;
@@ -2634,6 +5803,12 @@ Use this before editing files in a shared repo.
 
       const lease = claimFiles(db, taskId, worktree, files, opts.agent);
       console.log(`${chalk.green('✓')} Claimed ${files.length} file(s) for task ${chalk.cyan(taskId)} (${chalk.dim(lease.id)})`);
+      pushSyncEvent('claim_added', {
+        task_id: taskId,
+        lease_id: lease.id,
+        file_count: files.length,
+        files: files.slice(0, 10),
+      }, { worktree }).catch(() => {});
       files.forEach(f => console.log(`  ${chalk.dim(f)}`));
     } catch (err) {
       printErrorWithNext(err.message, 'switchman task list --status in_progress');
@@ -2649,9 +5824,11 @@ program
   .action((taskId) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
+    const task = getTask(db, taskId);
     releaseFileClaims(db, taskId);
     db.close();
     console.log(`${chalk.green('✓')} Released all claims for task ${chalk.cyan(taskId)}`);
+    pushSyncEvent('claim_released', { task_id: taskId }, { worktree: task?.worktree || null }).catch(() => {});
   });
 
 program
@@ -2927,12 +6104,14 @@ program
   .description('Show one dashboard view of what is running, blocked, and ready next')
   .option('--json', 'Output raw JSON')
   .option('--watch', 'Keep refreshing status in the terminal')
+  .option('--repair', 'Repair safe interrupted queue and pipeline state before rendering status')
   .option('--watch-interval-ms <n>', 'Polling interval for --watch mode', '2000')
   .option('--max-cycles <n>', 'Maximum refresh cycles before exiting', '0')
   .addHelpText('after', `
 Examples:
   switchman status
   switchman status --watch
+  switchman status --repair
   switchman status --json
 
 Use this first when the repo feels stuck.
@@ -2950,13 +6129,40 @@ Use this first when the repo feels stuck.
         console.clear();
       }
 
+      let repairResult = null;
+      if (opts.repair) {
+        const repairDb = getDb(repoRoot);
+        try {
+          repairResult = repairRepoState(repairDb, repoRoot);
+        } finally {
+          repairDb.close();
+        }
+      }
+
       const report = await collectStatusSnapshot(repoRoot);
+      const [teamActivity, teamState] = await Promise.all([
+        pullActiveTeamMembers(),
+        pullTeamState(),
+      ]);
+      const myUserId = readCredentials()?.user_id;
+      const otherMembers = teamActivity.filter(e => e.user_id !== myUserId);
+      const teamSummary = summarizeTeamCoordinationState(teamState, myUserId);
       cycles += 1;
 
       if (opts.json) {
-        console.log(JSON.stringify(watch ? { ...report, watch: true, cycles } : report, null, 2));
+        const payload = watch ? { ...report, watch: true, cycles } : report;
+        const withTeam = { ...payload, team_sync: { summary: teamSummary, recent_events: teamState.filter((event) => event.user_id !== myUserId).slice(0, 25) } };
+        console.log(JSON.stringify(opts.repair ? { ...withTeam, repair: repairResult } : withTeam, null, 2));
       } else {
-        renderUnifiedStatusReport(report);
+        if (opts.repair && repairResult) {
+          printRepairSummary(repairResult, {
+            repairedHeading: `${chalk.green('✓')} Repaired safe interrupted repo state before rendering status`,
+            noRepairHeading: `${chalk.green('✓')} No repo repair action needed before rendering status`,
+            limit: 6,
+          });
+          console.log('');
+        }
+        renderUnifiedStatusReport(report, { teamActivity: otherMembers, teamSummary });
         if (watch) {
           const signature = buildWatchSignature(report);
           const watchState = lastSignature === null
@@ -2986,8 +6192,49 @@ 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;
+    }
+  });
+
+const doctorCmd = program
   .command('doctor')
-  .description('Show one operator-focused health view: what is running, what is blocked, and what to do next')
+  .description('Show one operator-focused health view: what is running, what is blocked, and what to do next');
+doctorCmd._switchmanAdvanced = true;
+doctorCmd
+  .option('--repair', 'Repair safe interrupted queue and pipeline state before reporting health')
   .option('--json', 'Output raw JSON')
   .addHelpText('after', `
 Plain English:
@@ -3000,6 +6247,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 +6265,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 +6328,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 +6352,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);
@@ -3089,18 +6360,52 @@ Examples:
     }
   });
 
-// ── gate ─────────────────────────────────────────────────────────────────────
-
-const gateCmd = program.command('gate').description('Safety checks for edits, merges, and CI');
-gateCmd.addHelpText('after', `
-Examples:
-  switchman gate ci
-  switchman gate ai
-  switchman gate install-ci
-`);
-
-const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
-
+// ── gate ─────────────────────────────────────────────────────────────────────
+
+const gateCmd = program.command('gate').description('Safety checks for edits, merges, and CI');
+gateCmd.addHelpText('after', `
+Examples:
+  switchman gate ci
+  switchman gate ai
+  switchman gate install-ci
+`);
+
+const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
+auditCmd._switchmanAdvanced = true;
+
+auditCmd
+  .command('change <pipelineId>')
+  .description('Show a signed, operator-friendly history for one pipeline')
+  .option('--json', 'Output raw JSON')
+  .action((pipelineId, options) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const report = buildPipelineHistoryReport(db, repoRoot, pipelineId);
+      db.close();
+
+      if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      console.log(chalk.bold(`Audit history for pipeline ${report.pipeline_id}`));
+      console.log(`  ${chalk.dim('title:')} ${report.title}`);
+      console.log(`  ${chalk.dim('events:')} ${report.events.length}`);
+      console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
+      for (const event of report.events.slice(-20)) {
+        const status = event.status ? ` ${statusBadge(event.status).trim()}` : '';
+        console.log(`  ${chalk.dim(event.created_at)} ${chalk.cyan(event.label)}${status}`);
+        console.log(`    ${event.summary}`);
+      }
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
+      process.exitCode = 1;
+    }
+  });
+
 auditCmd
   .command('verify')
   .description('Verify the audit log hash chain and project signatures')
@@ -3389,6 +6694,7 @@ gateCmd
 const semanticCmd = program
   .command('semantic')
   .description('Inspect or materialize the derived semantic code-object view');
+semanticCmd._switchmanAdvanced = true;
 
 semanticCmd
   .command('materialize')
@@ -3405,6 +6711,7 @@ semanticCmd
 const objectCmd = program
   .command('object')
   .description('Experimental object-source mode backed by canonical exported code objects');
+objectCmd._switchmanAdvanced = true;
 
 objectCmd
   .command('import')
@@ -3486,6 +6793,7 @@ objectCmd
 // ── monitor ──────────────────────────────────────────────────────────────────
 
 const monitorCmd = program.command('monitor').description('Observe workspaces for runtime file changes');
+monitorCmd._switchmanAdvanced = true;
 
 monitorCmd
   .command('once')
@@ -3495,7 +6803,7 @@ monitorCmd
   .action((opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
-    const worktrees = listGitWorktrees(repoRoot);
+    const worktrees = resolveMonitoredWorktrees(db, repoRoot);
     const result = monitorWorktreesOnce(db, repoRoot, worktrees, { quarantine: opts.quarantine });
     db.close();
 
@@ -3511,9 +6819,7 @@ monitorCmd
 
     console.log(`${chalk.green('✓')} Observed ${result.summary.total} file change(s)`);
     for (const event of result.events) {
-      const badge = event.status === 'allowed' ? chalk.green('ALLOWED') : chalk.red('DENIED ');
-      const action = event.enforcement_action ? ` ${chalk.dim(event.enforcement_action)}` : '';
-      console.log(`  ${badge} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${event.reason_code ? ` ${chalk.dim(event.reason_code)}` : ''}${action}`);
+      renderMonitorEvent(event);
     }
   });
 
@@ -3547,14 +6853,12 @@ monitorCmd
 
     while (!stopped) {
       const db = getDb(repoRoot);
-      const worktrees = listGitWorktrees(repoRoot);
+      const worktrees = resolveMonitoredWorktrees(db, repoRoot);
       const result = monitorWorktreesOnce(db, repoRoot, worktrees, { quarantine: opts.quarantine });
       db.close();
 
       for (const event of result.events) {
-        const badge = event.status === 'allowed' ? chalk.green('ALLOWED') : chalk.red('DENIED ');
-        const action = event.enforcement_action ? ` ${chalk.dim(event.enforcement_action)}` : '';
-        console.log(`  ${badge} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${event.reason_code ? ` ${chalk.dim(event.reason_code)}` : ''}${action}`);
+        renderMonitorEvent(event);
       }
 
       if (stopped) break;
@@ -3572,39 +6876,18 @@ monitorCmd
   .action((opts) => {
     const repoRoot = getRepo();
     const intervalMs = Number.parseInt(opts.intervalMs, 10);
-    const existingState = readMonitorState(repoRoot);
+    const state = startBackgroundMonitor(repoRoot, {
+      intervalMs,
+      quarantine: Boolean(opts.quarantine),
+    });
 
-    if (existingState && isProcessRunning(existingState.pid)) {
-      console.log(chalk.yellow(`Monitor already running with pid ${existingState.pid}`));
+    if (state.already_running) {
+      console.log(chalk.yellow(`Monitor already running with pid ${state.state.pid}`));
       return;
     }
 
-    const logPath = join(repoRoot, '.switchman', 'monitor.log');
-    const child = spawn(process.execPath, [
-      process.argv[1],
-      'monitor',
-      'watch',
-      '--interval-ms',
-      String(intervalMs),
-      ...(opts.quarantine ? ['--quarantine'] : []),
-      '--daemonized',
-    ], {
-      cwd: repoRoot,
-      detached: true,
-      stdio: 'ignore',
-    });
-    child.unref();
-
-    const statePath = writeMonitorState(repoRoot, {
-      pid: child.pid,
-      interval_ms: intervalMs,
-      quarantine: Boolean(opts.quarantine),
-      log_path: logPath,
-      started_at: new Date().toISOString(),
-    });
-
-    console.log(`${chalk.green('✓')} Started monitor pid ${chalk.cyan(String(child.pid))}`);
-    console.log(`${chalk.dim('State:')} ${statePath}`);
+    console.log(`${chalk.green('✓')} Started monitor pid ${chalk.cyan(String(state.state.pid))}`);
+    console.log(`${chalk.dim('State:')} ${state.state_path}`);
   });
 
 monitorCmd
@@ -3656,9 +6939,38 @@ monitorCmd
     console.log(`  ${chalk.dim('started_at')} ${state.started_at}`);
   });
 
+program
+  .command('watch')
+  .description('Watch worktrees for direct writes and rogue edits in real time')
+  .option('--interval-ms <ms>', 'Polling interval in milliseconds', '2000')
+  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
+  .action(async (opts) => {
+    const repoRoot = getRepo();
+    const child = spawn(process.execPath, [
+      process.argv[1],
+      'monitor',
+      'watch',
+      '--interval-ms',
+      String(opts.intervalMs || '2000'),
+      ...(opts.quarantine ? ['--quarantine'] : []),
+    ], {
+      cwd: repoRoot,
+      stdio: 'inherit',
+    });
+
+    await new Promise((resolve, reject) => {
+      child.on('exit', (code) => {
+        process.exitCode = code ?? 0;
+        resolve();
+      });
+      child.on('error', reject);
+    });
+  });
+
 // ── policy ───────────────────────────────────────────────────────────────────
 
-const policyCmd = program.command('policy').description('Manage enforcement policy exceptions');
+const policyCmd = program.command('policy').description('Manage enforcement and change-governance policy');
+policyCmd._switchmanAdvanced = true;
 
 policyCmd
   .command('init')
@@ -3675,4 +6987,501 @@ 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}`);
+    }
+  });
+
+
+ 
+// ── login ──────────────────────────────────────────────────────────────────────
+ 
+program
+  .command('login')
+  .description('Sign in with GitHub to activate Switchman Pro')
+  .option('--invite <token>', 'Join a team with an invite token')
+  .option('--status', 'Show current login status')
+  .addHelpText('after', `
+Examples:
+  switchman login
+  switchman login --status
+  switchman login --invite tk_8f3a2c
+`)
+  .action(async (opts) => {
+    // Show current status
+    if (opts.status) {
+      const creds = readCredentials();
+      if (!creds?.access_token) {
+        console.log('');
+        console.log(`  ${chalk.dim('Status:')} Not logged in`);
+        console.log(`  ${chalk.dim('Run:   ')} ${chalk.cyan('switchman login')}`);
+        console.log('');
+        return;
+      }
+ 
+      const licence = await checkLicence();
+      console.log('');
+      if (licence.valid) {
+        console.log(`  ${chalk.green('✓')} Logged in as ${chalk.cyan(creds.email ?? 'unknown')}`);
+        console.log(`  ${chalk.dim('Plan:')} ${licence.plan ?? 'Pro'}`);
+        if (licence.current_period_end) {
+          console.log(`  ${chalk.dim('Renews:')} ${new Date(licence.current_period_end).toLocaleDateString()}`);
+        }
+        if (licence.offline) {
+          console.log(`  ${chalk.dim('(offline cache)')}`);
+        }
+      } else {
+        console.log(`  ${chalk.yellow('⚠')} Logged in as ${chalk.cyan(creds.email ?? 'unknown')} but no active Pro licence`);
+        console.log(`  ${chalk.dim('Upgrade at:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+      }
+      console.log('');
+      return;
+    }
+
+    // Handle --invite token
+    if (opts.invite) {
+      const SUPABASE_URL  = process.env.SWITCHMAN_SUPABASE_URL
+        ?? 'https://afilbolhlkiingnsupgr.supabase.co';
+      const SUPABASE_ANON = process.env.SWITCHMAN_SUPABASE_ANON
+        ?? 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFmaWxib2xobGtpaW5nbnN1cGdyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzM1OTIzOTIsImV4cCI6MjA4OTE2ODM5Mn0.8TBfHfRB0vEyKPMWBd6i1DNwx1nS9UqprIAsJf35n88';
+
+      const creds = readCredentials();
+      if (!creds?.access_token) {
+        console.log('');
+        console.log(chalk.yellow('  You need to sign in first before accepting an invite.'));
+        console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman login')} ${chalk.dim('then try again with --invite')}`);
+        console.log('');
+        process.exit(1);
+      }
+
+      const { createClient } = await import('@supabase/supabase-js');
+      const sb = createClient(SUPABASE_URL, SUPABASE_ANON, {
+        global: { headers: { Authorization: `Bearer ${creds.access_token}` } }
+      });
+
+      const { data: { user } } = await sb.auth.getUser();
+      if (!user) {
+        console.log(chalk.red('  ✗  Could not verify your account. Run: switchman login'));
+        process.exit(1);
+      }
+
+      // Look up the invite
+      const { data: invite, error: inviteError } = await sb
+        .from('team_invites')
+        .select('id, team_id, email, accepted')
+        .eq('token', opts.invite)
+        .maybeSingle();
+
+      if (inviteError || !invite) {
+        console.log('');
+        console.log(chalk.red('  ✗  Invite token not found or already used.'));
+        console.log(`  ${chalk.dim('Ask your teammate to send a new invite.')}`);
+        console.log('');
+        process.exit(1);
+      }
+
+      if (invite.accepted) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  This invite has already been accepted.'));
+        console.log('');
+        process.exit(1);
+      }
+
+      // Add user to the team
+      const { error: memberError } = await sb
+        .from('team_members')
+        .insert({ team_id: invite.team_id, user_id: user.id, role: 'member' });
+
+      if (memberError && !memberError.message.includes('duplicate')) {
+        console.log(chalk.red(`  ✗  Could not join team: ${memberError.message}`));
+        process.exit(1);
+      }
+
+      // Mark invite as accepted
+      await sb
+        .from('team_invites')
+        .update({ accepted: true })
+        .eq('id', invite.id);
+
+      console.log('');
+      console.log(`  ${chalk.green('✓')}  Joined the team successfully`);
+      console.log(`  ${chalk.dim('Your agents now share coordination with your teammates.')}`);
+      console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman status')} ${chalk.dim('to see the shared view.')}`);
+      console.log('');
+      return;
+    }
+ 
+    // Already logged in?
+    const existing = readCredentials();
+    if (existing?.access_token) {
+      const licence = await checkLicence();
+      if (licence.valid) {
+        console.log('');
+        console.log(`  ${chalk.green('✓')} Already logged in as ${chalk.cyan(existing.email ?? 'unknown')}`);
+        console.log(`  ${chalk.dim('Plan:')} ${licence.plan ?? 'Pro'}`);
+        console.log(`  ${chalk.dim('Run')} ${chalk.cyan('switchman login --status')} ${chalk.dim('to see full details')}`);
+        console.log('');
+        return;
+      }
+    }
+ 
+    console.log('');
+    console.log(chalk.bold('  Switchman Pro — sign in with GitHub'));
+    console.log('');
+ 
+    const spinner = ora('Waiting for GitHub sign-in...').start();
+    spinner.stop();
+ 
+    const result = await loginWithGitHub();
+ 
+    if (!result.success) {
+      console.log(`  ${chalk.red('✗')} Sign in failed: ${result.error ?? 'unknown error'}`);
+      console.log(`  ${chalk.dim('Try again or visit:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+      console.log('');
+      process.exit(1);
+    }
+ 
+    // Verify the licence
+    const licence = await checkLicence();
+ 
+    console.log(`  ${chalk.green('✓')} Signed in as ${chalk.cyan(result.email ?? 'unknown')}`);
+ 
+    if (licence.valid) {
+      console.log(`  ${chalk.green('✓')} Switchman Pro active`);
+      console.log(`  ${chalk.dim('Plan:')} ${licence.plan ?? 'Pro'}`);
+      console.log('');
+      console.log(`  ${chalk.dim('Credentials saved · valid 24h · 7-day offline grace')}`);
+      console.log('');
+      console.log(`  Run ${chalk.cyan('switchman setup --agents 10')} to use unlimited agents.`);
+    } else {
+      console.log(`  ${chalk.yellow('⚠')} No active Pro licence found`);
+      console.log('');
+      console.log(`  If you just paid, it may take a moment to activate.`);
+      console.log(`  ${chalk.dim('Upgrade at:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+    }
+ 
+    console.log('');
+  });
+ 
+ 
+// ── logout ─────────────────────────────────────────────────────────────────────
+ 
+program
+  .command('logout')
+  .description('Sign out and remove saved credentials')
+  .action(() => {
+    clearCredentials();
+    console.log('');
+    console.log(`  ${chalk.green('✓')} Signed out — credentials removed`);
+    console.log('');
+  });
+ 
+ 
+// ── upgrade ────────────────────────────────────────────────────────────────────
+ 
+program
+  .command('upgrade')
+  .description('Open the Switchman Pro page in your browser')
+  .action(async () => {
+    console.log('');
+    console.log(`  Opening ${chalk.cyan(PRO_PAGE_URL)}...`);
+    console.log('');
+    const { default: open } = await import('open');
+    await open(PRO_PAGE_URL);
+  });
+ 
+  // ── team ───────────────────────────────────────────────────────────────────────
+
+const teamCmd = program
+  .command('team')
+  .description('Manage your Switchman Pro team');
+
+teamCmd
+  .command('invite <email>')
+  .description('Invite a teammate to your shared coordination')
+  .addHelpText('after', `
+Examples:
+  switchman team invite alice@example.com
+`)
+  .action(async (email) => {
+    const licence = await checkLicence();
+    if (!licence.valid) {
+      console.log('');
+      console.log(chalk.yellow('  ⚠  Team invites require Switchman Pro.'));
+      console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman upgrade')}`);
+      console.log('');
+      process.exit(1);
+    }
+
+    const repoRoot = getRepo();
+    const creds = readCredentials();
+    if (!creds?.access_token) {
+      console.log('');
+      console.log(chalk.yellow('  ⚠  You need to be logged in.'));
+      console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman login')}`);
+      console.log('');
+      process.exit(1);
+    }
+
+    const SUPABASE_URL  = process.env.SWITCHMAN_SUPABASE_URL
+      ?? 'https://afilbolhlkiingnsupgr.supabase.co';
+    const SUPABASE_ANON = process.env.SWITCHMAN_SUPABASE_ANON
+      ?? 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFmaWxib2xobGtpaW5nbnN1cGdyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzM1OTIzOTIsImV4cCI6MjA4OTE2ODM5Mn0.8TBfHfRB0vEyKPMWBd6i1DNwx1nS9UqprIAsJf35n88';
+
+    const { createClient } = await import('@supabase/supabase-js');
+    const sb = createClient(SUPABASE_URL, SUPABASE_ANON, {
+      global: { headers: { Authorization: `Bearer ${creds.access_token}` } }
+    });
+
+    const { data: { user } } = await sb.auth.getUser();
+    if (!user) {
+      console.log(chalk.red('  ✗  Could not verify your account. Run: switchman login'));
+      process.exit(1);
+    }
+
+    // Get or create team
+    let teamId;
+    const { data: membership } = await sb
+      .from('team_members')
+      .select('team_id')
+      .eq('user_id', user.id)
+      .maybeSingle();
+
+    if (membership?.team_id) {
+      teamId = membership.team_id;
+    } else {
+      // Create a new team
+      const { data: team, error: teamError } = await sb
+        .from('teams')
+        .insert({ owner_id: user.id, name: 'My Team' })
+        .select('id')
+        .single();
+
+      if (teamError) {
+        console.log(chalk.red(`  ✗  Could not create team: ${teamError.message}`));
+        process.exit(1);
+      }
+
+      teamId = team.id;
+
+      // Add the owner as a member
+      await sb.from('team_members').insert({
+        team_id: teamId,
+        user_id: user.id,
+        role: 'owner',
+      });
+    }
+
+    // Create the invite
+    const { data: invite, error: inviteError } = await sb
+      .from('team_invites')
+      .insert({
+        team_id: teamId,
+        invited_by: user.id,
+        email,
+      })
+      .select('token')
+      .single();
+
+    if (inviteError) {
+      console.log(chalk.red(`  ✗  Could not create invite: ${inviteError.message}`));
+      process.exit(1);
+    }
+
+    console.log('');
+    console.log(`  ${chalk.green('✓')}  Invite created for ${chalk.cyan(email)}`);
+    console.log('');
+    console.log(`  They can join with:`);
+    console.log(`  ${chalk.cyan(`switchman login --invite ${invite.token}`)}`);
+    console.log('');
+  });
+
+teamCmd
+  .command('list')
+  .description('List your team members')
+  .action(async () => {
+    const licence = await checkLicence();
+    if (!licence.valid) {
+      console.log('');
+      console.log(chalk.yellow('  ⚠  Team features require Switchman Pro.'));
+      console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman upgrade')}`);
+      console.log('');
+      process.exit(1);
+    }
+
+    const creds = readCredentials();
+    if (!creds?.access_token) {
+      console.log(chalk.red('  ✗  Not logged in. Run: switchman login'));
+      process.exit(1);
+    }
+
+    const SUPABASE_URL  = process.env.SWITCHMAN_SUPABASE_URL
+      ?? 'https://afilbolhlkiingnsupgr.supabase.co';
+    const SUPABASE_ANON = process.env.SWITCHMAN_SUPABASE_ANON
+      ?? 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFmaWxib2xobGtpaW5nbnN1cGdyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzM1OTIzOTIsImV4cCI6MjA4OTE2ODM5Mn0.8TBfHfRB0vEyKPMWBd6i1DNwx1nS9UqprIAsJf35n88';
+
+    const { createClient } = await import('@supabase/supabase-js');
+    const sb = createClient(SUPABASE_URL, SUPABASE_ANON, {
+      global: { headers: { Authorization: `Bearer ${creds.access_token}` } }
+    });
+
+    const { data: membership } = await sb
+      .from('team_members')
+      .select('team_id')
+      .eq('user_id', (await sb.auth.getUser()).data.user?.id)
+      .maybeSingle();
+
+    if (!membership?.team_id) {
+      console.log('');
+      console.log(`  ${chalk.dim('No team yet. Invite someone with:')} ${chalk.cyan('switchman team invite <email>')}`);
+      console.log('');
+      return;
+    }
+
+    const { data: members } = await sb
+      .from('team_members')
+      .select('user_id, role, joined_at')
+      .eq('team_id', membership.team_id);
+
+    const { data: invites } = await sb
+      .from('team_invites')
+      .select('email, token, accepted, created_at')
+      .eq('team_id', membership.team_id)
+      .eq('accepted', false);
+
+    console.log('');
+    for (const m of members ?? []) {
+      const roleLabel = m.role === 'owner' ? chalk.dim('(owner)') : chalk.dim('(member)');
+      console.log(`  ${chalk.green('✓')} ${chalk.cyan(m.user_id.slice(0, 8))}  ${roleLabel}`);
+    }
+    for (const inv of invites ?? []) {
+      console.log(`  ${chalk.dim('○')} ${chalk.cyan(inv.email)}  ${chalk.dim('(invited)')}`);
+    }
+    console.log('');
+  });
+
 program.parse();