switchman-dev 0.1.3 → 0.1.5

package/src/cli/index.js

@@ -7,18 +7,19 @@
  *   switchman init               - Initialize in current repo
  *   switchman task add           - Add a task to the queue
  *   switchman task list          - List all tasks
- *   switchman task assign        - Assign task to a worktree
+ *   switchman task assign        - Assign task to a workspace
  *   switchman task done          - Mark task complete
- *   switchman worktree add       - Register a worktree
- *   switchman worktree list      - List registered worktrees
- *   switchman scan               - Scan for conflicts across worktrees
+ *   switchman worktree add       - Register a workspace
+ *   switchman worktree list      - List registered workspaces
+ *   switchman scan               - Scan for conflicts across workspaces
  *   switchman claim              - Claim files for a task
- *   switchman status             - Show full system status
+ *   switchman status             - Show the repo dashboard
  */
 
 import { program } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
+import { existsSync } from 'fs';
 import { join } from 'path';
 import { execSync, spawn } from 'child_process';
 
@@ -29,20 +30,23 @@ import {
   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,
 } from '../core/db.js';
 import { scanAllWorktrees } from '../core/detector.js';
-import { upsertProjectMcpConfig } from '../core/mcp.js';
+import { getWindsurfMcpConfigPath, upsertAllProjectMcpConfigs, upsertWindsurfMcpConfig } from '../core/mcp.js';
 import { gatewayAppendFile, gatewayMakeDirectory, gatewayMovePath, gatewayRemovePath, gatewayWriteFile, installGateHooks, monitorWorktreesOnce, runCommitGate, runWrappedCommand, writeEnforcementPolicy } from '../core/enforcement.js';
 import { runAiMergeGate } from '../core/merge-gate.js';
 import { clearMonitorState, getMonitorStatePath, isProcessRunning, readMonitorState, writeMonitorState } from '../core/monitor.js';
 import { buildPipelinePrSummary, createPipelineFollowupTasks, executePipeline, exportPipelinePrBundle, getPipelineStatus, publishPipelinePr, runPipeline, startPipeline } from '../core/pipeline.js';
 import { installGitHubActionsWorkflow, resolveGitHubOutputTargets, writeGitHubCiStatus } from '../core/ci.js';
 import { 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';
 
 function installMcpConfig(targetDirs) {
-  return targetDirs.map((targetDir) => upsertProjectMcpConfig(targetDir));
+  return targetDirs.flatMap((targetDir) => upsertAllProjectMcpConfigs(targetDir));
 }
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -80,6 +84,14 @@ function statusBadge(status) {
     observed: chalk.yellow,
     non_compliant: chalk.red,
     stale: chalk.red,
+    queued: chalk.yellow,
+    validating: chalk.blue,
+    rebasing: chalk.blue,
+    retrying: chalk.yellow,
+    blocked: chalk.red,
+    merging: chalk.blue,
+    merged: chalk.green,
+    canceled: chalk.gray,
   };
   return (colors[status] || chalk.white)(status.toUpperCase().padEnd(11));
 }
@@ -117,10 +129,239 @@ function printTable(rows, columns) {
   }
 }
 
+function padRight(value, width) {
+  return String(value).padEnd(width);
+}
+
+function stripAnsi(text) {
+  return String(text).replace(/\x1B\[[0-9;]*m/g, '');
+}
+
+function colorForHealth(health) {
+  if (health === 'healthy') return chalk.green;
+  if (health === 'warn') return chalk.yellow;
+  return chalk.red;
+}
+
+function healthLabel(health) {
+  if (health === 'healthy') return 'HEALTHY';
+  if (health === 'warn') return 'ATTENTION';
+  return 'BLOCKED';
+}
+
+function renderPanel(title, lines, color = chalk.cyan) {
+  const content = lines.length > 0 ? lines : [chalk.dim('No items.')];
+  const width = Math.max(
+    stripAnsi(title).length + 2,
+    ...content.map((line) => stripAnsi(line).length),
+  );
+  const top = color(`+${'-'.repeat(width + 2)}+`);
+  const titleLine = color(`| ${padRight(title, width)} |`);
+  const body = content.map((line) => `| ${padRight(line, width)} |`);
+  const bottom = color(`+${'-'.repeat(width + 2)}+`);
+  return [top, titleLine, top, ...body, bottom];
+}
+
+function renderMetricRow(metrics) {
+  return metrics.map(({ label, value, color = chalk.white }) => `${chalk.dim(label)} ${color(String(value))}`).join(chalk.dim('   |   '));
+}
+
+function renderMiniBar(items) {
+  if (!items.length) return chalk.dim('none');
+  return items.map(({ label, value, color = chalk.white }) => `${color('■')} ${label}:${value}`).join(chalk.dim('  '));
+}
+
+function renderChip(label, value, color = chalk.white) {
+  return color(`[${label}:${value}]`);
+}
+
+function renderSignalStrip(signals) {
+  return signals.join(chalk.dim('  '));
+}
+
+function formatClockTime(isoString) {
+  if (!isoString) return null;
+  const date = new Date(isoString);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toLocaleTimeString('en-GB', {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  });
+}
+
+function buildWatchSignature(report) {
+  return JSON.stringify({
+    health: report.health,
+    summary: report.summary,
+    counts: report.counts,
+    active_work: report.active_work,
+    attention: report.attention,
+    queue_summary: report.queue?.summary || null,
+    next_up: report.next_up || null,
+    next_steps: report.next_steps,
+    suggested_commands: report.suggested_commands,
+  });
+}
+
+function formatRelativePolicy(policy) {
+  return `stale ${policy.stale_after_minutes}m • heartbeat ${policy.heartbeat_interval_seconds}s • auto-reap ${policy.reap_on_status_check ? 'on' : 'off'}`;
+}
+
 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 printErrorWithNext(message, nextCommand = null) {
+  console.error(chalk.red(message));
+  if (nextCommand) {
+    console.error(`${chalk.yellow('next:')} ${nextCommand}`);
+  }
+}
+
+function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
+  const dbPath = join(repoRoot, '.switchman', 'switchman.db');
+  const rootMcpPath = join(repoRoot, '.mcp.json');
+  const cursorMcpPath = join(repoRoot, '.cursor', 'mcp.json');
+  const claudeGuidePath = join(repoRoot, 'CLAUDE.md');
+  const checks = [];
+  const nextSteps = [];
+  let workspaces = [];
+  let db = null;
+
+  const dbExists = existsSync(dbPath);
+  checks.push({
+    key: 'database',
+    ok: dbExists,
+    label: 'Project database',
+    detail: dbExists ? '.switchman/switchman.db is ready' : 'Switchman database is missing',
+  });
+  if (!dbExists) {
+    nextSteps.push('Run `switchman init` or `switchman setup --agents 3` in this repo.');
+  }
+
+  if (dbExists) {
+    try {
+      db = getDb(repoRoot);
+      workspaces = listWorktrees(db);
+    } catch {
+      checks.push({
+        key: 'database_open',
+        ok: false,
+        label: 'Database access',
+        detail: 'Switchman could not open the project database',
+      });
+      nextSteps.push('Re-run `switchman init` if the project database looks corrupted.');
+    } finally {
+      try { db?.close(); } catch { /* no-op */ }
+    }
+  }
+
+  const agentWorkspaces = workspaces.filter((entry) => entry.name !== 'main');
+  const workspaceReady = agentWorkspaces.length > 0;
+  checks.push({
+    key: 'workspaces',
+    ok: workspaceReady,
+    label: 'Agent workspaces',
+    detail: workspaceReady
+      ? `${agentWorkspaces.length} agent workspace(s) registered`
+      : 'No agent workspaces are registered yet',
+  });
+  if (!workspaceReady) {
+    nextSteps.push('Run `switchman setup --agents 3` to create agent workspaces.');
+  }
+
+  const rootMcpExists = existsSync(rootMcpPath);
+  checks.push({
+    key: 'claude_mcp',
+    ok: rootMcpExists,
+    label: 'Claude Code MCP',
+    detail: rootMcpExists ? '.mcp.json is present in the repo root' : '.mcp.json is missing from the repo root',
+  });
+  if (!rootMcpExists) {
+    nextSteps.push('Re-run `switchman setup --agents 3` to restore the repo-local MCP config.');
+  }
+
+  const cursorMcpExists = existsSync(cursorMcpPath);
+  checks.push({
+    key: 'cursor_mcp',
+    ok: cursorMcpExists,
+    label: 'Cursor MCP',
+    detail: cursorMcpExists ? '.cursor/mcp.json is present in the repo root' : '.cursor/mcp.json is missing from the repo root',
+  });
+  if (!cursorMcpExists) {
+    nextSteps.push('Re-run `switchman setup --agents 3` if you want Cursor to attach automatically.');
+  }
+
+  const claudeGuideExists = existsSync(claudeGuidePath);
+  checks.push({
+    key: 'claude_md',
+    ok: claudeGuideExists,
+    label: 'Claude guide',
+    detail: claudeGuideExists ? 'CLAUDE.md is present' : 'CLAUDE.md is optional but recommended for Claude Code',
+  });
+  if (!claudeGuideExists) {
+    nextSteps.push('If you use Claude Code, add `CLAUDE.md` from the repo root setup guide.');
+  }
+
+  const windsurfConfigExists = existsSync(getWindsurfMcpConfigPath(homeDir || undefined));
+  checks.push({
+    key: 'windsurf_mcp',
+    ok: windsurfConfigExists,
+    label: 'Windsurf MCP',
+    detail: windsurfConfigExists
+      ? 'Windsurf shared MCP config is installed'
+      : 'Windsurf shared MCP config is optional and not installed',
+  });
+  if (!windsurfConfigExists) {
+    nextSteps.push('If you use Windsurf, run `switchman mcp install --windsurf` once.');
+  }
+
+  const ok = checks.every((item) => item.ok || ['claude_md', 'windsurf_mcp'].includes(item.key));
+  return {
+    ok,
+    repo_root: repoRoot,
+    checks,
+    workspaces: workspaces.map((entry) => ({
+      name: entry.name,
+      path: entry.path,
+      branch: entry.branch,
+    })),
+    suggested_commands: [
+      'switchman status --watch',
+      'switchman task add "Your first task" --priority 8',
+      'switchman gate ci',
+      ...nextSteps.some((step) => step.includes('Windsurf')) ? ['switchman mcp install --windsurf'] : [],
+    ],
+    next_steps: [...new Set(nextSteps)].slice(0, 6),
+  };
+}
+
+function renderSetupVerification(report, { compact = false } = {}) {
+  console.log(chalk.bold(compact ? 'First-run check:' : 'Setup verification:'));
+  for (const check of report.checks) {
+    const badge = boolBadge(check.ok);
+    console.log(`  ${badge} ${check.label} ${chalk.dim(`— ${check.detail}`)}`);
+  }
+  if (report.next_steps.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Fix next:'));
+    for (const step of report.next_steps) {
+      console.log(`  - ${step}`);
+    }
+  }
+  console.log('');
+  console.log(chalk.bold('Try next:'));
+  for (const command of report.suggested_commands.slice(0, 4)) {
+    console.log(`  ${chalk.cyan(command)}`);
+  }
+}
+
 function summarizeLeaseScope(db, lease) {
   const reservations = listScopeReservations(db, { leaseId: lease.id });
   const pathScopes = reservations
@@ -454,6 +695,303 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
   };
 }
 
+function buildUnifiedStatusReport({
+  repoRoot,
+  leasePolicy,
+  tasks,
+  claims,
+  doctorReport,
+  queueItems,
+  queueSummary,
+  recentQueueEvents,
+}) {
+  const queueAttention = [
+    ...queueItems
+      .filter((item) => item.status === 'blocked')
+      .map((item) => ({
+        kind: 'queue_blocked',
+        title: `${item.id} is blocked from landing`,
+        detail: item.last_error_summary || `${item.source_type}:${item.source_ref}`,
+        next_step: item.next_action || `Run \`switchman queue retry ${item.id}\` after fixing the branch state.`,
+        command: item.next_action?.includes('queue retry') ? `switchman queue retry ${item.id}` : 'switchman queue status',
+        severity: 'block',
+      })),
+    ...queueItems
+      .filter((item) => item.status === 'retrying')
+      .map((item) => ({
+        kind: 'queue_retrying',
+        title: `${item.id} is waiting for another landing attempt`,
+        detail: item.last_error_summary || `${item.source_type}:${item.source_ref}`,
+        next_step: item.next_action || 'Run `switchman queue run` again to continue landing queued work.',
+        command: 'switchman queue run',
+        severity: 'warn',
+      })),
+  ];
+
+  const attention = [...doctorReport.attention, ...queueAttention];
+  const nextUp = tasks
+    .filter((task) => task.status === 'pending')
+    .sort((a, b) => Number(b.priority || 0) - Number(a.priority || 0))
+    .slice(0, 3)
+    .map((task) => ({
+      id: task.id,
+      title: task.title,
+      priority: task.priority,
+    }));
+  const failedTasks = tasks
+    .filter((task) => task.status === 'failed')
+    .slice(0, 5)
+    .map((task) => ({
+      id: task.id,
+      title: task.title,
+      failure: latestTaskFailure(task),
+    }));
+
+  const suggestedCommands = [
+    ...doctorReport.suggested_commands,
+    ...(queueItems.length > 0 ? ['switchman queue status'] : []),
+    ...(queueSummary.next ? ['switchman queue run'] : []),
+  ].filter(Boolean);
+
+  return {
+    generated_at: new Date().toISOString(),
+    repo_root: repoRoot,
+    health: attention.some((item) => item.severity === 'block')
+      ? 'block'
+      : attention.some((item) => item.severity === 'warn')
+        ? 'warn'
+        : doctorReport.health,
+    summary: attention.some((item) => item.severity === 'block')
+      ? 'Repo needs attention before more work or merge.'
+      : attention.some((item) => item.severity === 'warn')
+        ? 'Repo is running, but a few items need review.'
+        : 'Repo looks healthy. Agents are coordinated and merge checks are clear.',
+    lease_policy: leasePolicy,
+    counts: {
+      ...doctorReport.counts,
+      queue: queueSummary.counts,
+      active_claims: claims.length,
+    },
+    active_work: doctorReport.active_work,
+    attention,
+    next_up: nextUp,
+    failed_tasks: failedTasks,
+    queue: {
+      items: queueItems,
+      summary: queueSummary,
+      recent_events: recentQueueEvents,
+    },
+    merge_readiness: doctorReport.merge_readiness,
+    claims: claims.map((claim) => ({
+      worktree: claim.worktree,
+      task_id: claim.task_id,
+      file_path: claim.file_path,
+    })),
+    next_steps: [...new Set([
+      ...doctorReport.next_steps,
+      ...queueAttention.map((item) => item.next_step),
+    ])].slice(0, 6),
+    suggested_commands: [...new Set(suggestedCommands)].slice(0, 6),
+  };
+}
+
+async function collectStatusSnapshot(repoRoot) {
+  const db = getDb(repoRoot);
+  try {
+    const leasePolicy = loadLeasePolicy(repoRoot);
+
+    if (leasePolicy.reap_on_status_check) {
+      reapStaleLeases(db, leasePolicy.stale_after_minutes, {
+        requeueTask: leasePolicy.requeue_task_on_reap,
+      });
+    }
+
+    const tasks = listTasks(db);
+    const activeLeases = listLeases(db, 'active');
+    const staleLeases = getStaleLeases(db, leasePolicy.stale_after_minutes);
+    const claims = getActiveFileClaims(db);
+    const queueItems = listMergeQueue(db);
+    const queueSummary = buildQueueStatusSummary(queueItems);
+    const recentQueueEvents = queueItems
+      .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);
+    const scanReport = await scanAllWorktrees(db, repoRoot);
+    const aiGate = await runAiMergeGate(db, repoRoot);
+    const doctorReport = buildDoctorReport({
+      db,
+      repoRoot,
+      tasks,
+      activeLeases,
+      staleLeases,
+      scanReport,
+      aiGate,
+    });
+
+    return buildUnifiedStatusReport({
+      repoRoot,
+      leasePolicy,
+      tasks,
+      claims,
+      doctorReport,
+      queueItems,
+      queueSummary,
+      recentQueueEvents,
+    });
+  } finally {
+    db.close();
+  }
+}
+
+function renderUnifiedStatusReport(report) {
+  const healthColor = colorForHealth(report.health);
+  const badge = healthColor(healthLabel(report.health));
+  const mergeColor = report.merge_readiness.ci_gate_ok ? chalk.green : chalk.red;
+  const queueCounts = report.counts.queue;
+  const blockedCount = report.attention.filter((item) => item.severity === 'block').length;
+  const warningCount = report.attention.filter((item) => item.severity !== 'block').length;
+  const focusItem = blockedCount > 0
+    ? report.attention.find((item) => item.severity === 'block')
+    : warningCount > 0
+      ? report.attention.find((item) => item.severity !== 'block')
+      : report.next_up[0];
+  const focusLine = focusItem
+    ? ('title' in focusItem
+      ? `${focusItem.title}${focusItem.detail ? ` ${chalk.dim(`• ${focusItem.detail}`)}` : ''}`
+      : `${focusItem.title} ${chalk.dim(focusItem.id)}`)
+    : 'Nothing urgent. Safe to keep parallel work moving.';
+  const queueLoad = queueCounts.queued + queueCounts.retrying + queueCounts.merging + queueCounts.blocked;
+  const landingLabel = report.merge_readiness.ci_gate_ok ? 'ready' : 'hold';
+
+  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(renderSignalStrip([
+    renderChip('health', healthLabel(report.health), healthColor),
+    renderChip('blocked', blockedCount, blockedCount > 0 ? chalk.red : chalk.green),
+    renderChip('watch', warningCount, warningCount > 0 ? chalk.yellow : chalk.green),
+    renderChip('landing', landingLabel, mergeColor),
+    renderChip('queue', queueLoad, queueLoad > 0 ? chalk.blue : chalk.green),
+  ]));
+  console.log(renderMetricRow([
+    { label: 'tasks', value: `${report.counts.pending}/${report.counts.in_progress}/${report.counts.done}/${report.counts.failed}`, color: chalk.white },
+    { label: 'leases', value: `${report.counts.active_leases} active`, color: chalk.blue },
+    { label: 'claims', value: report.counts.active_claims, color: chalk.cyan },
+    { label: 'merge', value: report.merge_readiness.ci_gate_ok ? 'clear' : 'blocked', color: mergeColor },
+  ]));
+  console.log(renderMiniBar([
+    { label: 'queued', value: queueCounts.queued, color: chalk.yellow },
+    { label: 'retrying', value: queueCounts.retrying, color: chalk.yellow },
+    { label: 'blocked', value: queueCounts.blocked, color: chalk.red },
+    { 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.dim(`policy: ${formatRelativePolicy(report.lease_policy)} • requeue on reap ${report.lease_policy.requeue_task_on_reap ? 'on' : 'off'}`));
+
+  const runningLines = report.active_work.length > 0
+    ? report.active_work.slice(0, 5).map((item) => {
+      const boundary = item.boundary_validation
+        ? ` ${renderChip('validation', item.boundary_validation.status, item.boundary_validation.status === 'accepted' ? chalk.green : chalk.yellow)}`
+        : '';
+      const stale = (item.dependency_invalidations?.length || 0) > 0
+        ? ` ${renderChip('stale', item.dependency_invalidations.length, chalk.yellow)}`
+        : '';
+      return `${chalk.cyan(item.worktree)} -> ${item.task_title} ${chalk.dim(item.task_id)}${item.scope_summary ? ` ${chalk.dim(item.scope_summary)}` : ''}${boundary}${stale}`;
+    })
+    : [chalk.dim('Nothing active right now.')];
+
+  const blockedItems = report.attention.filter((item) => item.severity === 'block');
+  const warningItems = report.attention.filter((item) => item.severity !== 'block');
+
+  const blockedLines = blockedItems.length > 0
+    ? blockedItems.slice(0, 4).flatMap((item) => {
+      const lines = [`${renderChip('BLOCKED', item.kind || 'item', chalk.red)} ${item.title}`];
+      if (item.detail) lines.push(`  ${chalk.dim(item.detail)}`);
+      lines.push(`  ${chalk.yellow('next:')} ${item.next_step}`);
+      if (item.command) lines.push(`  ${chalk.cyan('run:')} ${item.command}`);
+      return lines;
+    })
+    : [chalk.green('Nothing blocked.')];
+
+  const warningLines = warningItems.length > 0
+    ? warningItems.slice(0, 4).flatMap((item) => {
+      const lines = [`${renderChip('WATCH', item.kind || 'item', chalk.yellow)} ${item.title}`];
+      if (item.detail) lines.push(`  ${chalk.dim(item.detail)}`);
+      lines.push(`  ${chalk.yellow('next:')} ${item.next_step}`);
+      if (item.command) lines.push(`  ${chalk.cyan('run:')} ${item.command}`);
+      return lines;
+    })
+    : [chalk.green('Nothing warning-worthy right now.')];
+
+  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}`)}`]
+        : []),
+      ...report.queue.items
+        .filter((entry) => ['blocked', 'retrying', 'merging'].includes(entry.status))
+        .slice(0, 4)
+        .flatMap((item) => {
+          const lines = [`${renderChip(item.status.toUpperCase(), item.id, item.status === 'blocked' ? chalk.red : item.status === 'retrying' ? chalk.yellow : chalk.blue)} ${item.source_type}:${item.source_ref} ${chalk.dim(`retries:${item.retry_count}/${item.max_retries}`)}`];
+          if (item.last_error_summary) lines.push(`  ${chalk.red('why:')} ${item.last_error_summary}`);
+          if (item.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.next_action}`);
+          return lines;
+        }),
+    ]
+    : [chalk.dim('No queued merges.')];
+
+  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)}`)
+      : [chalk.dim('No pending tasks waiting right now.')]),
+    '',
+    ...report.suggested_commands.slice(0, 4).map((command) => `${chalk.cyan('$')} ${command}`),
+  ];
+
+  const panelBlocks = [
+    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('Landing queue', queueLines, queueCounts.blocked > 0 ? chalk.red : chalk.blue),
+    renderPanel('Next action', nextActionLines, chalk.green),
+  ];
+
+  console.log('');
+  for (const block of panelBlocks) {
+    for (const line of block) console.log(line);
+    console.log('');
+  }
+
+  if (report.failed_tasks.length > 0) {
+    console.log(chalk.bold('Recent failed tasks:'));
+    for (const task of report.failed_tasks) {
+      const reason = humanizeReasonCode(task.failure?.reason_code);
+      const summary = task.failure?.summary || 'unknown failure';
+      console.log(`  ${chalk.red(task.title)} ${chalk.dim(task.id)}`);
+      console.log(`    ${chalk.red('why:')} ${summary} ${chalk.dim(`(${reason})`)}`);
+    }
+    console.log('');
+  }
+
+  if (report.queue.recent_events.length > 0) {
+    console.log(chalk.bold('Recent queue events:'));
+    for (const event of report.queue.recent_events.slice(0, 5)) {
+      console.log(`  ${chalk.cyan(event.queue_item_id)} ${chalk.dim(event.event_type)} ${chalk.dim(event.status || '')} ${chalk.dim(event.created_at)}`.trim());
+    }
+    console.log('');
+  }
+
+  console.log(chalk.bold('Recommended next steps:'));
+  for (const step of report.next_steps) {
+    console.log(`  - ${step}`);
+  }
+}
+
 function acquireNextTaskLease(db, worktreeName, agent, attempts = 20) {
   for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
@@ -530,6 +1068,23 @@ program
   .description('Conflict-aware task coordinator for parallel AI coding agents')
   .version('0.1.0');
 
+program.showHelpAfterError('(run with --help for usage examples)');
+program.addHelpText('after', `
+Start here:
+  switchman setup --agents 5
+  switchman status --watch
+  switchman gate ci
+
+Most useful commands:
+  switchman task add "Implement auth helper" --priority 9
+  switchman lease next --json
+  switchman queue run --watch
+
+Docs:
+  README.md
+  docs/setup-cursor.md
+`);
+
 // ── init ──────────────────────────────────────────────────────────────────────
 
 program
@@ -570,9 +1125,14 @@ program
 
 program
   .command('setup')
-  .description('One-command setup: create agent worktrees and initialise switchman')
-  .option('-a, --agents <n>', 'Number of agent worktrees to create (default: 3)', '3')
+  .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')
+  .addHelpText('after', `
+Examples:
+  switchman setup --agents 5
+  switchman setup --agents 3 --prefix team
+`)
   .action((opts) => {
     const agentCount = parseInt(opts.agents);
 
@@ -592,7 +1152,7 @@ program
           stdio: ['pipe', 'pipe', 'pipe'],
         });
       } catch {
-        spinner.fail('Your repo needs at least one commit before worktrees can be created.');
+        spinner.fail('Your repo needs at least one commit before agent workspaces can be created.');
         console.log(chalk.dim('  Run: git commit --allow-empty -m "init"  then try again'));
         process.exit(1);
       }
@@ -600,7 +1160,7 @@ program
       // Init the switchman database
       const db = initDb(repoRoot);
 
-      // Create one worktree per agent
+      // Create one workspace (git worktree) per agent
       const created = [];
       for (let i = 1; i <= agentCount; i++) {
         const name = `agent${i}`;
@@ -650,21 +1210,97 @@ program
       console.log(chalk.bold('Next steps:'));
       console.log(`  1. Add your tasks:`);
       console.log(`     ${chalk.cyan('switchman task add "Your first task" --priority 8')}`);
-      console.log(`  2. Open Claude Code in each folder above — the local .mcp.json will attach Switchman automatically`);
+      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('');
 
+      const verification = collectSetupVerification(repoRoot);
+      renderSetupVerification(verification, { compact: true });
+
     } catch (err) {
       spinner.fail(err.message);
       process.exit(1);
     }
   });
 
+program
+  .command('verify-setup')
+  .description('Check whether this repo is ready for a smooth first Switchman run')
+  .option('--json', 'Output raw JSON')
+  .option('--home <path>', 'Override the home directory for editor config checks')
+  .addHelpText('after', `
+Examples:
+  switchman verify-setup
+  switchman verify-setup --json
+
+Use this after setup or whenever editor/config wiring feels off.
+`)
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const report = collectSetupVerification(repoRoot, { homeDir: opts.home || null });
+
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+      if (!report.ok) process.exitCode = 1;
+      return;
+    }
+
+    renderSetupVerification(report);
+    if (!report.ok) process.exitCode = 1;
+  });
+
+
+// ── mcp ───────────────────────────────────────────────────────────────────────
+
+const mcpCmd = program.command('mcp').description('Manage editor connections for Switchman');
+
+mcpCmd
+  .command('install')
+  .description('Install editor-specific MCP config for Switchman')
+  .option('--windsurf', 'Write Windsurf MCP config to ~/.codeium/mcp_config.json')
+  .option('--home <path>', 'Override the home directory for config writes (useful for testing)')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman mcp install --windsurf
+  switchman mcp install --windsurf --json
+`)
+  .action((opts) => {
+    if (!opts.windsurf) {
+      console.error(chalk.red('Choose an editor install target, for example `switchman mcp install --windsurf`.'));
+      process.exitCode = 1;
+      return;
+    }
+
+    const result = upsertWindsurfMcpConfig(opts.home);
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        editor: 'windsurf',
+        path: result.path,
+        created: result.created,
+        changed: result.changed,
+      }, null, 2));
+      return;
+    }
+
+    console.log(`${chalk.green('✓')} Windsurf MCP config ${result.changed ? 'written' : 'already up to date'}`);
+    console.log(`  ${chalk.dim('path:')} ${chalk.cyan(result.path)}`);
+    console.log(`  ${chalk.dim('open:')} Windsurf -> Settings -> Cascade -> MCP Servers`);
+    console.log(`  ${chalk.dim('note:')} Windsurf reads the shared config from ${getWindsurfMcpConfigPath(opts.home)}`);
+  });
+
 
 // ── task ──────────────────────────────────────────────────────────────────────
 
-const taskCmd = program.command('task').description('Manage the task queue');
+const taskCmd = program.command('task').description('Manage the task list');
+taskCmd.addHelpText('after', `
+Examples:
+  switchman task add "Fix login bug" --priority 8
+  switchman task list --status pending
+  switchman task done task-123
+`);
 
 taskCmd
   .command('add <title>')
@@ -720,7 +1356,7 @@ taskCmd
 
 taskCmd
   .command('assign <taskId> <worktree>')
-  .description('Assign a task to a worktree (compatibility shim for lease acquire)')
+  .description('Assign a task to a workspace (compatibility shim for lease acquire)')
   .option('--agent <name>', 'Agent name (e.g. claude-code)')
   .action((taskId, worktree, opts) => {
     const repoRoot = getRepo();
@@ -762,10 +1398,15 @@ taskCmd
 
 taskCmd
   .command('next')
-  .description('Get and assign the next pending task (compatibility shim for lease next)')
+  .description('Get the next pending task quickly (use `lease next` for the full workflow)')
   .option('--json', 'Output as JSON')
-  .option('--worktree <name>', 'Worktree to assign the task to (defaults to current worktree name)')
+  .option('--worktree <name>', 'Workspace to assign the task to (defaults to the current folder name)')
   .option('--agent <name>', 'Agent identifier for logging (e.g. claude-code)')
+  .addHelpText('after', `
+Examples:
+  switchman task next
+  switchman task next --json
+`)
   .action((opts) => {
     const repoRoot = getRepo();
     const worktreeName = getCurrentWorktreeName(opts.worktree);
@@ -792,9 +1433,358 @@ taskCmd
     }
   });
 
+// ── queue ─────────────────────────────────────────────────────────────────────
+
+const queueCmd = program.command('queue').alias('land').description('Land finished work safely back onto main, one item at a time');
+queueCmd.addHelpText('after', `
+Examples:
+  switchman queue add --worktree agent1
+  switchman queue status
+  switchman queue run --watch
+`);
+
+queueCmd
+  .command('add [branch]')
+  .description('Add a branch, workspace, or pipeline to the landing queue')
+  .option('--worktree <name>', 'Queue a registered workspace by name')
+  .option('--pipeline <pipelineId>', 'Queue a pipeline by id')
+  .option('--target <branch>', 'Target branch to merge into', 'main')
+  .option('--max-retries <n>', 'Maximum automatic retries', '1')
+  .option('--submitted-by <name>', 'Operator or automation name')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman queue add feature/auth-hardening
+  switchman queue add --worktree agent2
+  switchman queue add --pipeline pipe-123
+`)
+  .action((branch, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      let payload;
+      if (opts.worktree) {
+        const worktree = listWorktrees(db).find((entry) => entry.name === opts.worktree);
+        if (!worktree) {
+          throw new Error(`Workspace ${opts.worktree} is not registered.`);
+        }
+        payload = {
+          sourceType: 'worktree',
+          sourceRef: worktree.branch,
+          sourceWorktree: worktree.name,
+          targetBranch: opts.target,
+          maxRetries: opts.maxRetries,
+          submittedBy: opts.submittedBy || null,
+        };
+      } else if (opts.pipeline) {
+        payload = {
+          sourceType: 'pipeline',
+          sourceRef: opts.pipeline,
+          sourcePipelineId: opts.pipeline,
+          targetBranch: opts.target,
+          maxRetries: opts.maxRetries,
+          submittedBy: opts.submittedBy || null,
+        };
+      } else if (branch) {
+        payload = {
+          sourceType: 'branch',
+          sourceRef: branch,
+          targetBranch: opts.target,
+          maxRetries: opts.maxRetries,
+          submittedBy: opts.submittedBy || null,
+        };
+      } else {
+        throw new Error('Choose one source to land: a branch name, `--worktree`, or `--pipeline`.');
+      }
+
+      const result = enqueueMergeItem(db, payload);
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+
+      console.log(`${chalk.green('✓')} Queued ${chalk.cyan(result.id)} for ${chalk.bold(result.target_branch)}`);
+      console.log(`  ${chalk.dim('source:')} ${result.source_type} ${result.source_ref}`);
+      if (result.source_worktree) console.log(`  ${chalk.dim('worktree:')} ${result.source_worktree}`);
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, 'switchman queue add --help');
+      process.exitCode = 1;
+    }
+  });
+
+queueCmd
+  .command('list')
+  .description('List merge queue items')
+  .option('--status <status>', 'Filter by queue status')
+  .option('--json', 'Output raw JSON')
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+    const items = listMergeQueue(db, { status: opts.status || null });
+    db.close();
+
+    if (opts.json) {
+      console.log(JSON.stringify(items, null, 2));
+      return;
+    }
+
+    if (items.length === 0) {
+      console.log(chalk.dim('Merge queue is empty.'));
+      return;
+    }
+
+    for (const item of items) {
+      const retryInfo = chalk.dim(`retries:${item.retry_count}/${item.max_retries}`);
+      const attemptInfo = item.last_attempt_at ? ` ${chalk.dim(`last-attempt:${item.last_attempt_at}`)}` : '';
+      console.log(`  ${statusBadge(item.status)} ${item.id} ${item.source_type}:${item.source_ref} ${chalk.dim(`→ ${item.target_branch}`)} ${retryInfo}${attemptInfo}`);
+      if (item.last_error_summary) {
+        console.log(`    ${chalk.red('why:')} ${item.last_error_summary}`);
+      }
+      if (item.next_action) {
+        console.log(`    ${chalk.yellow('next:')} ${item.next_action}`);
+      }
+    }
+  });
+
+queueCmd
+  .command('status')
+  .description('Show an operator-friendly merge queue summary')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Plain English:
+  Use this when finished branches are waiting to land and you want one safe queue view.
+
+Examples:
+  switchman queue status
+  switchman queue status --json
+
+What it helps you answer:
+  - what lands next
+  - what is blocked
+  - what command should I run now
+`)
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+    const items = listMergeQueue(db);
+    const summary = buildQueueStatusSummary(items);
+    const recentEvents = items.slice(0, 5).flatMap((item) =>
+      listMergeQueueEvents(db, item.id, { limit: 3 }).map((event) => ({ ...event, queue_item_id: item.id })),
+    ).sort((a, b) => b.id - a.id).slice(0, 8);
+    db.close();
+
+    if (opts.json) {
+      console.log(JSON.stringify({ items, summary, recent_events: recentEvents }, null, 2));
+      return;
+    }
+
+    const queueHealth = summary.counts.blocked > 0 ? 'block' : summary.counts.retrying > 0 ? 'warn' : 'healthy';
+    const queueHealthColor = colorForHealth(queueHealth);
+    const focus = summary.blocked[0] || summary.retrying[0] || summary.next || null;
+    const focusLine = focus
+      ? `${focus.id} ${focus.source_type}:${focus.source_ref}${focus.last_error_summary ? ` ${chalk.dim(`• ${focus.last_error_summary}`)}` : ''}`
+      : 'Nothing waiting. Landing queue is clear.';
+
+    console.log('');
+    console.log(queueHealthColor('='.repeat(72)));
+    console.log(`${queueHealthColor(healthLabel(queueHealth))} ${chalk.bold('switchman queue status')} ${chalk.dim('• landing mission control')}`);
+    console.log(queueHealthColor('='.repeat(72)));
+    console.log(renderSignalStrip([
+      renderChip('queued', summary.counts.queued, summary.counts.queued > 0 ? chalk.yellow : chalk.green),
+      renderChip('retrying', summary.counts.retrying, summary.counts.retrying > 0 ? chalk.yellow : chalk.green),
+      renderChip('blocked', summary.counts.blocked, summary.counts.blocked > 0 ? chalk.red : chalk.green),
+      renderChip('merging', summary.counts.merging, summary.counts.merging > 0 ? chalk.blue : chalk.green),
+      renderChip('merged', summary.counts.merged, summary.counts.merged > 0 ? chalk.green : chalk.white),
+    ]));
+    console.log(renderMetricRow([
+      { label: 'items', value: items.length, color: chalk.white },
+      { label: 'validating', value: summary.counts.validating, color: chalk.blue },
+      { label: 'rebasing', value: summary.counts.rebasing, color: chalk.blue },
+      { label: 'target', value: summary.next?.target_branch || 'main', color: chalk.cyan },
+    ]));
+    console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+
+    const queueFocusLines = summary.next
+      ? [
+        `${renderChip('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`,
+      ]
+      : [chalk.dim('No queued landing work right now.')];
+
+    const queueBlockedLines = summary.blocked.length > 0
+      ? summary.blocked.slice(0, 4).flatMap((item) => {
+        const lines = [`${renderChip('BLOCKED', item.id, chalk.red)} ${item.source_type}:${item.source_ref} ${chalk.dim(`retries:${item.retry_count}/${item.max_retries}`)}`];
+        if (item.last_error_summary) lines.push(`  ${chalk.red('why:')} ${item.last_error_summary}`);
+        if (item.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.next_action}`);
+        return lines;
+      })
+      : [chalk.green('Nothing blocked.')];
+
+    const queueWatchLines = items.filter((item) => ['retrying', 'merging', 'rebasing', 'validating'].includes(item.status)).length > 0
+      ? items
+        .filter((item) => ['retrying', '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}`];
+          if (item.last_error_summary) lines.push(`  ${chalk.dim(item.last_error_summary)}`);
+          return lines;
+        })
+      : [chalk.green('No in-flight queue items right now.')];
+
+    const queueCommandLines = [
+      `${chalk.cyan('$')} switchman queue run`,
+      `${chalk.cyan('$')} switchman queue status --json`,
+      ...(summary.blocked[0] ? [`${chalk.cyan('$')} switchman queue retry ${summary.blocked[0].id}`] : []),
+    ];
+
+    console.log('');
+    for (const block of [
+      renderPanel('Landing focus', queueFocusLines, chalk.green),
+      renderPanel('Blocked', queueBlockedLines, summary.counts.blocked > 0 ? chalk.red : chalk.green),
+      renderPanel('In flight', queueWatchLines, queueWatchLines[0] === 'No in-flight queue items right now.' ? chalk.green : chalk.blue),
+      renderPanel('Next commands', queueCommandLines, chalk.cyan),
+    ]) {
+      for (const line of block) console.log(line);
+      console.log('');
+    }
+
+    if (recentEvents.length > 0) {
+      console.log(chalk.bold('Recent Queue Events:'));
+      for (const event of recentEvents) {
+        console.log(`  ${chalk.cyan(event.queue_item_id)} ${chalk.dim(event.event_type)} ${chalk.dim(event.status || '')} ${chalk.dim(event.created_at)}`.trim());
+      }
+    }
+  });
+
+queueCmd
+  .command('run')
+  .description('Process landing-queue items one at a time')
+  .option('--max-items <n>', 'Maximum queue items to process', '1')
+  .option('--target <branch>', 'Default target branch', 'main')
+  .option('--watch', 'Keep polling for new queue items')
+  .option('--watch-interval-ms <n>', 'Polling interval for --watch mode', '1000')
+  .option('--max-cycles <n>', 'Maximum watch cycles before exiting (mainly for tests)')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman queue run
+  switchman queue run --watch
+  switchman queue run --watch --watch-interval-ms 1000
+`)
+  .action(async (opts) => {
+    const repoRoot = getRepo();
+
+    try {
+      const watch = Boolean(opts.watch);
+      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 aggregate = {
+        processed: [],
+        cycles: 0,
+        watch,
+      };
+
+      while (true) {
+        const db = getDb(repoRoot);
+        const result = await runMergeQueue(db, repoRoot, {
+          maxItems: Number.parseInt(opts.maxItems, 10) || 1,
+          targetBranch: opts.target || 'main',
+        });
+        db.close();
+
+        aggregate.processed.push(...result.processed);
+        aggregate.summary = result.summary;
+        aggregate.cycles += 1;
+
+        if (!watch) break;
+        if (maxCycles && aggregate.cycles >= maxCycles) break;
+        if (result.processed.length === 0) {
+          sleepSync(watchIntervalMs);
+        }
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(aggregate, null, 2));
+        return;
+      }
+
+      if (aggregate.processed.length === 0) {
+        console.log(chalk.dim('No queued merge items.'));
+        return;
+      }
+
+      for (const entry of aggregate.processed) {
+        const item = entry.item;
+        if (entry.status === 'merged') {
+          console.log(`${chalk.green('✓')} Merged ${chalk.cyan(item.id)} into ${chalk.bold(item.target_branch)}`);
+          console.log(`  ${chalk.dim('commit:')} ${item.merged_commit}`);
+        } else {
+          console.log(`${chalk.red('✗')} Blocked ${chalk.cyan(item.id)}`);
+          console.log(`  ${chalk.red('why:')} ${item.last_error_summary}`);
+          if (item.next_action) console.log(`  ${chalk.yellow('next:')} ${item.next_action}`);
+        }
+      }
+    } catch (err) {
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
+queueCmd
+  .command('retry <itemId>')
+  .description('Retry a blocked merge queue item')
+  .option('--json', 'Output raw JSON')
+  .action((itemId, opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+    const item = retryMergeQueueItem(db, itemId);
+    db.close();
+
+    if (!item) {
+      printErrorWithNext(`Queue item ${itemId} is not retryable.`, 'switchman queue status');
+      process.exitCode = 1;
+      return;
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(item, null, 2));
+      return;
+    }
+
+    console.log(`${chalk.green('✓')} Queue item ${chalk.cyan(item.id)} reset to retrying`);
+  });
+
+queueCmd
+  .command('remove <itemId>')
+  .description('Remove a merge queue item')
+  .action((itemId) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+    const item = removeMergeQueueItem(db, itemId);
+    db.close();
+
+    if (!item) {
+      printErrorWithNext(`Queue item ${itemId} does not exist.`, 'switchman queue status');
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log(`${chalk.green('✓')} Removed ${chalk.cyan(item.id)} from the merge queue`);
+  });
+
 // ── pipeline ──────────────────────────────────────────────────────────────────
 
 const pipelineCmd = program.command('pipeline').description('Create and summarize issue-to-PR execution pipelines');
+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
+`);
 
 pipelineCmd
   .command('start <title>')
@@ -832,6 +1822,14 @@ pipelineCmd
   .command('status <pipelineId>')
   .description('Show task status for a pipeline')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Plain English:
+  Use this when one goal has been split into several tasks and you want to see what is running, stuck, or next.
+
+Examples:
+  switchman pipeline status pipe-123
+  switchman pipeline status pipe-123 --json
+`)
   .action((pipelineId, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -845,20 +1843,74 @@ pipelineCmd
         return;
       }
 
+      const pipelineHealth = result.status === 'blocked'
+        ? 'block'
+        : result.counts.failed > 0
+          ? 'warn'
+          : result.counts.in_progress > 0
+            ? 'warn'
+            : 'healthy';
+      const pipelineHealthColor = colorForHealth(pipelineHealth);
+      const failedTask = result.tasks.find((task) => task.status === 'failed');
+      const runningTask = result.tasks.find((task) => task.status === 'in_progress');
+      const nextPendingTask = result.tasks.find((task) => task.status === 'pending');
+      const focusTask = failedTask || runningTask || nextPendingTask || result.tasks[0] || null;
+      const focusLine = focusTask
+        ? `${focusTask.title} ${chalk.dim(focusTask.id)}`
+        : 'No pipeline tasks found.';
+
+      console.log('');
+      console.log(pipelineHealthColor('='.repeat(72)));
+      console.log(`${pipelineHealthColor(healthLabel(pipelineHealth))} ${chalk.bold('switchman pipeline status')} ${chalk.dim('• pipeline mission control')}`);
       console.log(`${chalk.bold(result.title)} ${chalk.dim(result.pipeline_id)}`);
-      console.log(`  ${chalk.dim('done')} ${result.counts.done}  ${chalk.dim('in_progress')} ${result.counts.in_progress}  ${chalk.dim('pending')} ${result.counts.pending}  ${chalk.dim('failed')} ${result.counts.failed}`);
-      for (const task of result.tasks) {
+      console.log(pipelineHealthColor('='.repeat(72)));
+      console.log(renderSignalStrip([
+        renderChip('done', result.counts.done, result.counts.done > 0 ? chalk.green : chalk.white),
+        renderChip('running', result.counts.in_progress, result.counts.in_progress > 0 ? chalk.blue : chalk.green),
+        renderChip('pending', result.counts.pending, result.counts.pending > 0 ? chalk.yellow : chalk.green),
+        renderChip('failed', result.counts.failed, result.counts.failed > 0 ? chalk.red : chalk.green),
+      ]));
+      console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+
+      const runningLines = result.tasks.filter((task) => task.status === 'in_progress').slice(0, 4).map((task) => {
         const worktree = task.worktree || task.suggested_worktree || 'unassigned';
         const blocked = task.blocked_by?.length ? ` ${chalk.dim(`blocked by ${task.blocked_by.join(', ')}`)}` : '';
         const type = task.task_spec?.task_type ? ` ${chalk.dim(`[${task.task_spec.task_type}]`)}` : '';
-        console.log(`  ${statusBadge(task.status)} ${task.id} ${task.title}${type} ${chalk.dim(worktree)}${blocked}`);
+        return `${chalk.cyan(worktree)} -> ${task.title}${type} ${chalk.dim(task.id)}${blocked}`;
+      });
+
+      const blockedLines = result.tasks.filter((task) => task.status === 'failed').slice(0, 4).flatMap((task) => {
+        const type = task.task_spec?.task_type ? ` ${chalk.dim(`[${task.task_spec.task_type}]`)}` : '';
+        const lines = [`${renderChip('BLOCKED', task.id, chalk.red)} ${task.title}${type}`];
         if (task.failure?.summary) {
           const reasonLabel = humanizeReasonCode(task.failure.reason_code);
-          console.log(`    ${chalk.red('why:')} ${task.failure.summary} ${chalk.dim(`(${reasonLabel})`)}`);
-        }
-        if (task.next_action) {
-          console.log(`    ${chalk.yellow('next:')} ${task.next_action}`);
+          lines.push(`  ${chalk.red('why:')} ${task.failure.summary} ${chalk.dim(`(${reasonLabel})`)}`);
         }
+        if (task.next_action) lines.push(`  ${chalk.yellow('next:')} ${task.next_action}`);
+        return lines;
+      });
+
+      const nextLines = result.tasks.filter((task) => task.status === 'pending').slice(0, 4).map((task) => {
+        const worktree = task.suggested_worktree || task.worktree || 'unassigned';
+        const blocked = task.blocked_by?.length ? ` ${chalk.dim(`blocked by ${task.blocked_by.join(', ')}`)}` : '';
+        return `${renderChip('NEXT', task.id, chalk.green)} ${task.title} ${chalk.dim(worktree)}${blocked}`;
+      });
+
+      const commandLines = [
+        `${chalk.cyan('$')} switchman pipeline exec ${result.pipeline_id} "/path/to/agent-command"`,
+        `${chalk.cyan('$')} switchman pipeline pr ${result.pipeline_id}`,
+        ...(result.counts.failed > 0 ? [`${chalk.cyan('$')} switchman pipeline status ${result.pipeline_id}`] : []),
+      ];
+
+      console.log('');
+      for (const block of [
+        renderPanel('Running now', runningLines.length > 0 ? runningLines : [chalk.dim('No tasks are actively running.')], runningLines.length > 0 ? chalk.cyan : chalk.green),
+        renderPanel('Blocked', blockedLines.length > 0 ? blockedLines : [chalk.green('Nothing blocked.')], blockedLines.length > 0 ? chalk.red : chalk.green),
+        renderPanel('Next up', nextLines.length > 0 ? nextLines : [chalk.dim('No pending tasks left.')], chalk.green),
+        renderPanel('Next commands', commandLines, chalk.cyan),
+      ]) {
+        for (const line of block) console.log(line);
+        console.log('');
       }
     } catch (err) {
       db.close();
@@ -1048,6 +2100,14 @@ pipelineCmd
   .option('--retry-backoff-ms <ms>', 'Base backoff in milliseconds between retry attempts', '0')
   .option('--timeout-ms <ms>', 'Default command timeout in milliseconds when a task spec does not provide one', '0')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Plain English:
+  pipeline = one goal, broken into smaller safe tasks
+
+Examples:
+  switchman pipeline exec pipe-123 "/path/to/agent-command"
+  switchman pipeline exec pipe-123 "npm test"
+`)
   .action(async (pipelineId, agentCommand, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1081,20 +2141,34 @@ pipelineCmd
       console.log(chalk.dim(result.pr.markdown.split('\n')[0]));
     } catch (err) {
       db.close();
-      console.error(chalk.red(err.message));
+      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
       process.exitCode = 1;
     }
   });
 
 // ── lease ────────────────────────────────────────────────────────────────────
 
-const leaseCmd = program.command('lease').description('Manage active work leases');
+const leaseCmd = program.command('lease').alias('session').description('Manage active work sessions and keep long-running tasks alive');
+leaseCmd.addHelpText('after', `
+Plain English:
+  lease = a task currently checked out by an agent
+
+Examples:
+  switchman lease next --json
+  switchman lease heartbeat lease-123
+  switchman lease reap
+`);
 
 leaseCmd
   .command('acquire <taskId> <worktree>')
-  .description('Acquire a lease for a pending task')
+  .description('Start a tracked work session for a specific pending task')
   .option('--agent <name>', 'Agent identifier for logging')
   .option('--json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  switchman lease acquire task-123 agent2
+  switchman lease acquire task-123 agent2 --agent cursor
+`)
   .action((taskId, worktree, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1104,7 +2178,7 @@ leaseCmd
 
     if (!lease || !task) {
       if (opts.json) console.log(JSON.stringify({ lease: null, task: null }));
-      else console.log(chalk.red(`Could not acquire lease. The task may not exist or is not pending.`));
+      else printErrorWithNext('Could not start a work session. The task may not exist or may already be in progress.', 'switchman task list --status pending');
       process.exitCode = 1;
       return;
     }
@@ -1124,10 +2198,16 @@ leaseCmd
 
 leaseCmd
   .command('next')
-  .description('Claim the next pending task and acquire its lease')
+  .description('Start the next pending task and open a tracked work session for it')
   .option('--json', 'Output as JSON')
-  .option('--worktree <name>', 'Worktree to assign the task to (defaults to current worktree name)')
+  .option('--worktree <name>', 'Workspace to assign the task to (defaults to the current folder name)')
   .option('--agent <name>', 'Agent identifier for logging')
+  .addHelpText('after', `
+Examples:
+  switchman lease next
+  switchman lease next --json
+  switchman lease next --worktree agent2 --agent cursor
+`)
   .action((opts) => {
     const repoRoot = getRepo();
     const worktreeName = getCurrentWorktreeName(opts.worktree);
@@ -1135,7 +2215,7 @@ leaseCmd
 
     if (!task) {
       if (opts.json) console.log(JSON.stringify({ task: null, lease: null }));
-      else if (exhausted) console.log(chalk.dim('No pending tasks.'));
+      else if (exhausted) console.log(chalk.dim('No pending tasks. Add one with `switchman task add "Your task"`.'));
       else console.log(chalk.yellow('Tasks were claimed by other agents during assignment. Run again to get the next one.'));
       return;
     }
@@ -1198,7 +2278,7 @@ leaseCmd
 
     if (!lease) {
       if (opts.json) console.log(JSON.stringify({ lease: null }));
-      else console.log(chalk.red(`No active lease found for ${leaseId}`));
+      else printErrorWithNext(`No active work session found for ${leaseId}.`, 'switchman lease list --status active');
       process.exitCode = 1;
       return;
     }
@@ -1214,14 +2294,24 @@ leaseCmd
 
 leaseCmd
   .command('reap')
-  .description('Expire stale leases, release their claims, and return their tasks to pending')
-  .option('--stale-after-minutes <minutes>', 'Age threshold for staleness', String(DEFAULT_STALE_LEASE_MINUTES))
+  .description('Clean up abandoned work sessions and release their file locks')
+  .option('--stale-after-minutes <minutes>', 'Age threshold for staleness')
   .option('--json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  switchman lease reap
+  switchman lease reap --stale-after-minutes 20
+`)
   .action((opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
-    const staleAfterMinutes = Number.parseInt(opts.staleAfterMinutes, 10);
-    const expired = reapStaleLeases(db, staleAfterMinutes);
+    const leasePolicy = loadLeasePolicy(repoRoot);
+    const staleAfterMinutes = opts.staleAfterMinutes
+      ? Number.parseInt(opts.staleAfterMinutes, 10)
+      : leasePolicy.stale_after_minutes;
+    const expired = reapStaleLeases(db, staleAfterMinutes, {
+      requeueTask: leasePolicy.requeue_task_on_reap,
+    });
     db.close();
 
     if (opts.json) {
@@ -1240,13 +2330,76 @@ leaseCmd
     }
   });
 
+const leasePolicyCmd = leaseCmd.command('policy').description('Inspect or update the stale-lease policy for this repo');
+
+leasePolicyCmd
+  .command('set')
+  .description('Persist a stale-lease policy for this repo')
+  .option('--heartbeat-interval-seconds <seconds>', 'Recommended heartbeat interval')
+  .option('--stale-after-minutes <minutes>', 'Age threshold for staleness')
+  .option('--reap-on-status-check <boolean>', 'Automatically reap stale leases during `switchman status`')
+  .option('--requeue-task-on-reap <boolean>', 'Return stale tasks to pending instead of failing them')
+  .option('--json', 'Output as JSON')
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const current = loadLeasePolicy(repoRoot);
+    const next = {
+      ...current,
+      ...(opts.heartbeatIntervalSeconds ? { heartbeat_interval_seconds: Number.parseInt(opts.heartbeatIntervalSeconds, 10) } : {}),
+      ...(opts.staleAfterMinutes ? { stale_after_minutes: Number.parseInt(opts.staleAfterMinutes, 10) } : {}),
+      ...(opts.reapOnStatusCheck ? { reap_on_status_check: opts.reapOnStatusCheck === 'true' } : {}),
+      ...(opts.requeueTaskOnReap ? { requeue_task_on_reap: opts.requeueTaskOnReap === 'true' } : {}),
+    };
+    const path = writeLeasePolicy(repoRoot, next);
+    const saved = loadLeasePolicy(repoRoot);
+
+    if (opts.json) {
+      console.log(JSON.stringify({ path, policy: saved }, null, 2));
+      return;
+    }
+
+    console.log(`${chalk.green('✓')} Lease policy updated`);
+    console.log(`  ${chalk.dim(path)}`);
+    console.log(`  ${chalk.dim('heartbeat_interval_seconds:')} ${saved.heartbeat_interval_seconds}`);
+    console.log(`  ${chalk.dim('stale_after_minutes:')} ${saved.stale_after_minutes}`);
+    console.log(`  ${chalk.dim('reap_on_status_check:')} ${saved.reap_on_status_check}`);
+    console.log(`  ${chalk.dim('requeue_task_on_reap:')} ${saved.requeue_task_on_reap}`);
+  });
+
+leasePolicyCmd
+  .description('Show the active stale-lease policy for this repo')
+  .option('--json', 'Output as JSON')
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const policy = loadLeasePolicy(repoRoot);
+    if (opts.json) {
+      console.log(JSON.stringify({ policy }, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold('Lease policy'));
+    console.log(`  ${chalk.dim('heartbeat_interval_seconds:')} ${policy.heartbeat_interval_seconds}`);
+    console.log(`  ${chalk.dim('stale_after_minutes:')} ${policy.stale_after_minutes}`);
+    console.log(`  ${chalk.dim('reap_on_status_check:')} ${policy.reap_on_status_check}`);
+    console.log(`  ${chalk.dim('requeue_task_on_reap:')} ${policy.requeue_task_on_reap}`);
+  });
+
 // ── worktree ───────────────────────────────────────────────────────────────────
 
-const wtCmd = program.command('worktree').description('Manage worktrees');
+const wtCmd = program.command('worktree').alias('workspace').description('Manage registered workspaces (Git worktrees)');
+wtCmd.addHelpText('after', `
+Plain English:
+  worktree = the Git feature behind each agent workspace
+
+Examples:
+  switchman worktree list
+  switchman workspace list
+  switchman worktree sync
+`);
 
 wtCmd
   .command('add <name> <path> <branch>')
-  .description('Register a worktree with switchman')
+  .description('Register a workspace with Switchman')
   .option('--agent <name>', 'Agent assigned to this worktree')
   .action((name, path, branch, opts) => {
     const repoRoot = getRepo();
@@ -1258,7 +2411,7 @@ wtCmd
 
 wtCmd
   .command('list')
-  .description('List all registered worktrees')
+  .description('List all registered workspaces')
   .action(() => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1267,7 +2420,7 @@ wtCmd
     db.close();
 
     if (!worktrees.length && !gitWorktrees.length) {
-      console.log(chalk.dim('No worktrees found.'));
+      console.log(chalk.dim('No workspaces found. Run `switchman setup --agents 3` or `switchman worktree sync`.'));
       return;
     }
 
@@ -1287,7 +2440,7 @@ wtCmd
 
 wtCmd
   .command('sync')
-  .description('Sync git worktrees into the switchman database')
+  .description('Sync Git workspaces into the Switchman database')
   .action(() => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1304,12 +2457,20 @@ wtCmd
 
 program
   .command('claim <taskId> <worktree> [files...]')
-  .description('Claim files for a task (warns if conflicts exist)')
+  .description('Lock files for a task before editing')
   .option('--agent <name>', 'Agent name')
   .option('--force', 'Claim even if conflicts exist')
+  .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.
+`)
   .action((taskId, worktree, files, opts) => {
     if (!files.length) {
-      console.log(chalk.yellow('No files specified. Use: switchman claim <taskId> <worktree> file1 file2 ...'));
+      console.log(chalk.yellow('No files specified.'));
+      console.log(`${chalk.yellow('next:')} switchman claim <taskId> <workspace> file1 file2`);
       return;
     }
     const repoRoot = getRepo();
@@ -1323,7 +2484,8 @@ program
         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 resolve conflicts first.'));
+        console.log(chalk.dim('\nUse --force to claim anyway, or pick different files first.'));
+        console.log(`${chalk.yellow('next:')} switchman status`);
         process.exitCode = 1;
         return;
       }
@@ -1332,7 +2494,7 @@ program
       console.log(`${chalk.green('✓')} Claimed ${files.length} file(s) for task ${chalk.cyan(taskId)} (${chalk.dim(lease.id)})`);
       files.forEach(f => console.log(`  ${chalk.dim(f)}`));
     } catch (err) {
-      console.error(chalk.red(err.message));
+      printErrorWithNext(err.message, 'switchman task list --status in_progress');
       process.exitCode = 1;
     } finally {
       db.close();
@@ -1501,13 +2663,19 @@ program
 
 program
   .command('scan')
-  .description('Scan all worktrees for conflicts')
+  .description('Scan all workspaces for conflicts')
   .option('--json', 'Output raw JSON')
   .option('--quiet', 'Only show conflicts')
+  .addHelpText('after', `
+Examples:
+  switchman scan
+  switchman scan --quiet
+  switchman scan --json
+`)
   .action(async (opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
-    const spinner = ora('Scanning worktrees for conflicts...').start();
+    const spinner = ora('Scanning workspaces for conflicts...').start();
 
     try {
       const report = await scanAllWorktrees(db, repoRoot);
@@ -1600,7 +2768,7 @@ program
 
       // All clear
       if (report.conflicts.length === 0 && report.fileConflicts.length === 0 && (report.ownershipConflicts?.length || 0) === 0 && (report.semanticConflicts?.length || 0) === 0 && report.unclaimedChanges.length === 0) {
-        console.log(chalk.green(`✓ No conflicts detected across ${report.worktrees.length} worktree(s)`));
+        console.log(chalk.green(`✓ No conflicts detected across ${report.worktrees.length} workspace(s)`));
       }
 
     } catch (err) {
@@ -1614,200 +2782,72 @@ program
 
 program
   .command('status')
-  .description('Show full system status: tasks, worktrees, claims, and conflicts')
-  .action(async () => {
+  .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('--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 --json
+
+Use this first when the repo feels stuck.
+`)
+  .action(async (opts) => {
     const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-
-    console.log('');
-    console.log(chalk.bold.cyan('━━━ switchman status ━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-    console.log(chalk.dim(`Repo: ${repoRoot}`));
-    console.log('');
+    const watch = Boolean(opts.watch);
+    const watchIntervalMs = Math.max(100, Number.parseInt(opts.watchIntervalMs, 10) || 2000);
+    const maxCycles = Math.max(0, Number.parseInt(opts.maxCycles, 10) || 0);
+    let cycles = 0;
+    let lastSignature = null;
 
-    // Tasks
-    const tasks = listTasks(db);
-    const pending = tasks.filter(t => t.status === 'pending');
-    const inProgress = tasks.filter(t => t.status === 'in_progress');
-    const done = tasks.filter(t => t.status === 'done');
-    const failed = tasks.filter(t => t.status === 'failed');
-    const activeLeases = listLeases(db, 'active');
-    const staleLeases = getStaleLeases(db);
-
-    console.log(chalk.bold('Tasks:'));
-    console.log(`  ${chalk.yellow('Pending')}     ${pending.length}`);
-    console.log(`  ${chalk.blue('In Progress')} ${inProgress.length}`);
-    console.log(`  ${chalk.green('Done')}        ${done.length}`);
-    console.log(`  ${chalk.red('Failed')}      ${failed.length}`);
-
-    if (activeLeases.length > 0) {
-      console.log('');
-      console.log(chalk.bold('Active Leases:'));
-      for (const lease of activeLeases) {
-        const agent = lease.agent ? ` ${chalk.dim(`agent:${lease.agent}`)}` : '';
-        const scope = summarizeLeaseScope(db, lease);
-        const boundaryValidation = getBoundaryValidationState(db, lease.id);
-        const dependencyInvalidations = listDependencyInvalidations(db, { affectedTaskId: lease.task_id });
-        const boundary = boundaryValidation ? ` ${chalk.dim(`validation:${boundaryValidation.status}`)}` : '';
-        const staleMarker = dependencyInvalidations.length > 0 ? ` ${chalk.dim(`stale:${dependencyInvalidations.length}`)}` : '';
-        console.log(`  ${chalk.cyan(lease.worktree)} → ${lease.task_title} ${chalk.dim(lease.id)} ${chalk.dim(`task:${lease.task_id}`)}${agent}${scope ? ` ${chalk.dim(scope)}` : ''}${boundary}${staleMarker}`);
+    while (true) {
+      if (watch && process.stdout.isTTY && !opts.json) {
+        console.clear();
       }
-    } else if (inProgress.length > 0) {
-      console.log('');
-      console.log(chalk.bold('In-Progress Tasks Without Lease:'));
-      for (const t of inProgress) {
-        console.log(`  ${chalk.cyan(t.worktree || 'unassigned')} → ${t.title}`);
-      }
-    }
 
-    if (staleLeases.length > 0) {
-      console.log('');
-      console.log(chalk.bold('Stale Leases:'));
-      for (const lease of staleLeases) {
-        console.log(`  ${chalk.red(lease.worktree)} → ${lease.task_title} ${chalk.dim(lease.id)} ${chalk.dim(lease.heartbeat_at)}`);
-      }
-    }
-
-    if (pending.length > 0) {
-      console.log('');
-      console.log(chalk.bold('Next Up:'));
-      const next = pending.slice(0, 3);
-      for (const t of next) {
-        console.log(`  [p${t.priority}] ${t.title} ${chalk.dim(t.id)}`);
-      }
-    }
-
-    if (failed.length > 0) {
-      console.log('');
-      console.log(chalk.bold('Failed Tasks:'));
-      for (const task of failed.slice(0, 5)) {
-        const failureLine = String(task.description || '')
-          .split('\n')
-          .map((line) => line.trim())
-          .filter(Boolean)
-          .reverse()
-          .find((line) => line.startsWith('FAILED: '));
-        const failureText = failureLine ? failureLine.slice('FAILED: '.length) : 'unknown failure';
-        const reasonMatch = failureText.match(/^([a-z0-9_]+):\s*(.+)$/i);
-        const reasonCode = reasonMatch ? reasonMatch[1] : null;
-        const summary = reasonMatch ? reasonMatch[2] : failureText;
-        const nextStep = nextStepForReason(reasonCode);
-        console.log(`  ${chalk.red(task.title)} ${chalk.dim(task.id)}`);
-        console.log(`    ${chalk.red('why:')} ${summary} ${chalk.dim(`(${humanizeReasonCode(reasonCode)})`)}`);
-        if (nextStep) {
-          console.log(`    ${chalk.yellow('next:')} ${nextStep}`);
-        }
-      }
-    }
-
-    // File Claims
-    const claims = getActiveFileClaims(db);
-    if (claims.length > 0) {
-      console.log('');
-      console.log(chalk.bold(`Active File Claims (${claims.length}):`));
-      const byWorktree = {};
-      for (const c of claims) {
-        if (!byWorktree[c.worktree]) byWorktree[c.worktree] = [];
-        byWorktree[c.worktree].push(c.file_path);
-      }
-      for (const [wt, files] of Object.entries(byWorktree)) {
-        console.log(`  ${chalk.cyan(wt)}: ${files.slice(0, 5).join(', ')}${files.length > 5 ? ` +${files.length - 5} more` : ''}`);
-      }
-    }
+      const report = await collectStatusSnapshot(repoRoot);
+      cycles += 1;
 
-    // Quick conflict scan
-    console.log('');
-    const spinner = ora('Running conflict scan...').start();
-    try {
-      const report = await scanAllWorktrees(db, repoRoot);
-      spinner.stop();
-
-      const totalConflicts = report.conflicts.length + report.fileConflicts.length + (report.ownershipConflicts?.length || 0) + (report.semanticConflicts?.length || 0) + report.unclaimedChanges.length;
-      if (totalConflicts === 0) {
-        console.log(chalk.green(`✓ No conflicts across ${report.worktrees.length} worktree(s)`));
+      if (opts.json) {
+        console.log(JSON.stringify(watch ? { ...report, watch: true, cycles } : report, null, 2));
       } else {
-        console.log(chalk.red(`⚠ ${totalConflicts} conflict(s) detected — run 'switchman scan' for details`));
-      }
-
-      console.log('');
-      console.log(chalk.bold('Compliance:'));
-      console.log(`  ${chalk.green('Managed')}       ${report.complianceSummary.managed}`);
-      console.log(`  ${chalk.yellow('Observed')}      ${report.complianceSummary.observed}`);
-      console.log(`  ${chalk.red('Non-Compliant')} ${report.complianceSummary.non_compliant}`);
-      console.log(`  ${chalk.red('Stale')}         ${report.complianceSummary.stale}`);
-
-      if (report.unclaimedChanges.length > 0) {
-        console.log('');
-        console.log(chalk.bold('Unclaimed Changed Paths:'));
-        for (const entry of report.unclaimedChanges) {
-          const reasonCode = entry.reasons?.[0]?.reason_code || null;
-          const nextStep = nextStepForReason(reasonCode);
-          console.log(`  ${chalk.cyan(entry.worktree)}: ${entry.files.slice(0, 5).join(', ')}${entry.files.length > 5 ? ` +${entry.files.length - 5} more` : ''}`);
-          console.log(`    ${chalk.dim(humanizeReasonCode(reasonCode))}${nextStep ? ` — ${nextStep}` : ''}`);
-        }
-      }
-
-      if ((report.ownershipConflicts?.length || 0) > 0) {
-        console.log('');
-        console.log(chalk.bold('Ownership Boundary Overlaps:'));
-        for (const conflict of report.ownershipConflicts.slice(0, 5)) {
-          if (conflict.type === 'subsystem_overlap') {
-            console.log(`  ${chalk.cyan(conflict.worktreeA)}: ${chalk.dim(`subsystem:${conflict.subsystemTag}`)} ${chalk.dim('vs')} ${chalk.cyan(conflict.worktreeB)}`);
-          } else {
-            console.log(`  ${chalk.cyan(conflict.worktreeA)}: ${chalk.dim(conflict.scopeA)} ${chalk.dim('vs')} ${chalk.cyan(conflict.worktreeB)} ${chalk.dim(conflict.scopeB)}`);
-          }
-        }
-      }
-
-      if ((report.semanticConflicts?.length || 0) > 0) {
-        console.log('');
-        console.log(chalk.bold('Semantic Overlaps:'));
-        for (const conflict of report.semanticConflicts.slice(0, 5)) {
-          console.log(`  ${chalk.cyan(conflict.worktreeA)}: ${chalk.dim(conflict.object_name)} ${chalk.dim('vs')} ${chalk.cyan(conflict.worktreeB)} ${chalk.dim(`${conflict.fileA} ↔ ${conflict.fileB}`)}`);
-        }
-      }
-
-      const staleInvalidations = listDependencyInvalidations(db, { status: 'stale' });
-      if (staleInvalidations.length > 0) {
-        console.log('');
-        console.log(chalk.bold('Stale For Revalidation:'));
-        for (const invalidation of staleInvalidations.slice(0, 5)) {
-          const staleArea = invalidation.reason_type === 'subsystem_overlap'
-            ? `subsystem:${invalidation.subsystem_tag}`
-            : `${invalidation.source_scope_pattern} ↔ ${invalidation.affected_scope_pattern}`;
-          console.log(`  ${chalk.cyan(invalidation.affected_worktree || 'unknown')}: ${chalk.dim(staleArea)} ${chalk.dim('because')} ${chalk.cyan(invalidation.source_worktree || 'unknown')} changed it`);
-        }
-      }
-
-      if (report.commitGateFailures.length > 0) {
-        console.log('');
-        console.log(chalk.bold('Recent Commit Gate Failures:'));
-        for (const failure of report.commitGateFailures.slice(0, 5)) {
-          console.log(`  ${chalk.red(failure.worktree || 'unknown')} ${chalk.dim(humanizeReasonCode(failure.reason_code || 'rejected'))} ${chalk.dim(failure.created_at)}`);
+        renderUnifiedStatusReport(report);
+        if (watch) {
+          const signature = buildWatchSignature(report);
+          const watchState = lastSignature === null
+            ? chalk.cyan('baseline snapshot')
+            : signature === lastSignature
+              ? chalk.dim('no repo changes since last refresh')
+              : chalk.green('change detected');
+          const updatedAt = formatClockTime(report.generated_at);
+          lastSignature = signature;
+          console.log('');
+          console.log(chalk.dim(`Live watch • updated ${updatedAt || 'just now'} • ${watchState}${maxCycles > 0 ? ` • cycle ${cycles}/${maxCycles}` : ''} • refresh ${watchIntervalMs}ms`));
         }
       }
 
-      if (report.deniedWrites.length > 0) {
-        console.log('');
-        console.log(chalk.bold('Recent Denied Events:'));
-        for (const event of report.deniedWrites.slice(0, 5)) {
-          console.log(`  ${chalk.red(event.event_type)} ${chalk.cyan(event.worktree || 'repo')} ${chalk.dim(humanizeReasonCode(event.reason_code || event.status))}`);
-        }
-      }
-    } catch {
-      spinner.stop();
-      console.log(chalk.dim('Could not run conflict scan'));
+      if (!watch) break;
+      if (maxCycles > 0 && cycles >= maxCycles) break;
+      if (opts.json) break;
+      sleepSync(watchIntervalMs);
     }
-
-    db.close();
-    console.log('');
-    console.log(chalk.dim('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
-    console.log('');
   });
 
 program
   .command('doctor')
   .description('Show one operator-focused health view: what is running, what is blocked, and what to do next')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Plain English:
+  Use this when the repo feels risky, noisy, or stuck and you want the health summary plus exact next moves.
+
+Examples:
+  switchman doctor
+  switchman doctor --json
+`)
   .action(async (opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1832,66 +2872,83 @@ program
       return;
     }
 
-    const badge = report.health === 'healthy'
-      ? chalk.green('HEALTHY')
-      : report.health === 'warn'
-        ? chalk.yellow('ATTENTION')
-        : chalk.red('BLOCKED');
-    console.log(`${badge} ${report.summary}`);
-    console.log(chalk.dim(repoRoot));
-    console.log('');
-
-    console.log(chalk.bold('At a glance:'));
-    console.log(`  ${chalk.dim('tasks')} ${report.counts.pending} pending, ${report.counts.in_progress} in progress, ${report.counts.done} done, ${report.counts.failed} failed`);
-    console.log(`  ${chalk.dim('leases')} ${report.counts.active_leases} active, ${report.counts.stale_leases} stale`);
-    console.log(`  ${chalk.dim('merge')} CI ${report.merge_readiness.ci_gate_ok ? chalk.green('clear') : chalk.red('blocked')}  AI ${report.merge_readiness.ai_gate_status}`);
+    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;
+    const focusItem = report.attention[0] || report.active_work[0] || null;
+    const focusLine = focusItem
+      ? `${focusItem.title || focusItem.task_title}${focusItem.detail ? ` ${chalk.dim(`• ${focusItem.detail}`)}` : ''}`
+      : 'Nothing urgent. Repo health looks steady.';
 
-    if (report.active_work.length > 0) {
-      console.log('');
-      console.log(chalk.bold('Running now:'));
-      for (const item of report.active_work.slice(0, 5)) {
+    console.log('');
+    console.log(doctorColor('='.repeat(72)));
+    console.log(`${doctorColor(healthLabel(report.health))} ${chalk.bold('switchman doctor')} ${chalk.dim('• repo health mission control')}`);
+    console.log(chalk.dim(repoRoot));
+    console.log(chalk.dim(report.summary));
+    console.log(doctorColor('='.repeat(72)));
+    console.log(renderSignalStrip([
+      renderChip('blocked', blockedCount, blockedCount > 0 ? chalk.red : chalk.green),
+      renderChip('watch', warningCount, warningCount > 0 ? chalk.yellow : chalk.green),
+      renderChip('leases', report.counts.active_leases, report.counts.active_leases > 0 ? chalk.blue : chalk.green),
+      renderChip('stale', report.counts.stale_leases, report.counts.stale_leases > 0 ? chalk.red : chalk.green),
+      renderChip('merge', report.merge_readiness.ci_gate_ok ? 'clear' : 'hold', report.merge_readiness.ci_gate_ok ? chalk.green : chalk.red),
+    ]));
+    console.log(renderMetricRow([
+      { label: 'tasks', value: `${report.counts.pending}/${report.counts.in_progress}/${report.counts.done}/${report.counts.failed}`, color: chalk.white },
+      { label: 'AI gate', value: report.merge_readiness.ai_gate_status, color: report.merge_readiness.ai_gate_status === 'blocked' ? chalk.red : report.merge_readiness.ai_gate_status === 'warn' ? chalk.yellow : chalk.green },
+    ]));
+    console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+
+    const runningLines = report.active_work.length > 0
+      ? report.active_work.slice(0, 5).map((item) => {
         const leaseId = activeLeases.find((lease) => lease.task_id === item.task_id && lease.worktree === item.worktree)?.id || null;
         const boundary = item.boundary_validation
-          ? ` ${chalk.dim(`validation:${item.boundary_validation.status}`)}`
+          ? ` ${renderChip('validation', item.boundary_validation.status, item.boundary_validation.status === 'accepted' ? chalk.green : chalk.yellow)}`
           : '';
         const stale = (item.dependency_invalidations?.length || 0) > 0
-          ? ` ${chalk.dim(`stale:${item.dependency_invalidations.length}`)}`
+          ? ` ${renderChip('stale', item.dependency_invalidations.length, chalk.yellow)}`
           : '';
-        console.log(`  ${chalk.cyan(item.worktree)} -> ${item.task_title} ${chalk.dim(item.task_id)}${leaseId ? ` ${chalk.dim(`lease:${leaseId}`)}` : ''}${item.scope_summary ? ` ${chalk.dim(item.scope_summary)}` : ''}${boundary}${stale}`);
-      }
-    }
+        return `${chalk.cyan(item.worktree)} -> ${item.task_title} ${chalk.dim(item.task_id)}${leaseId ? ` ${chalk.dim(`lease:${leaseId}`)}` : ''}${item.scope_summary ? ` ${chalk.dim(item.scope_summary)}` : ''}${boundary}${stale}`;
+      })
+      : [chalk.dim('Nothing active right now.')];
+
+    const attentionLines = report.attention.length > 0
+      ? report.attention.slice(0, 6).flatMap((item) => {
+        const lines = [`${item.severity === 'block' ? renderChip('BLOCKED', item.kind || 'item', chalk.red) : renderChip('WATCH', item.kind || 'item', chalk.yellow)} ${item.title}`];
+        if (item.detail) lines.push(`  ${chalk.dim(item.detail)}`);
+        lines.push(`  ${chalk.yellow('next:')} ${item.next_step}`);
+        if (item.command) lines.push(`  ${chalk.cyan('run:')} ${item.command}`);
+        return lines;
+      })
+      : [chalk.green('Nothing urgent.')];
+
+    const nextStepLines = [
+      ...report.next_steps.slice(0, 4).map((step) => `- ${step}`),
+      '',
+      ...report.suggested_commands.slice(0, 4).map((command) => `${chalk.cyan('$')} ${command}`),
+    ];
 
     console.log('');
     console.log(chalk.bold('Attention now:'));
-    if (report.attention.length === 0) {
-      console.log(`  ${chalk.green('Nothing urgent.')}`);
-    } else {
-      for (const item of report.attention.slice(0, 6)) {
-        const itemBadge = item.severity === 'block' ? chalk.red('block') : chalk.yellow('warn ');
-        console.log(`  ${itemBadge} ${item.title}`);
-        if (item.detail) console.log(`        ${chalk.dim(item.detail)}`);
-        console.log(`        ${chalk.yellow('next:')} ${item.next_step}`);
-        if (item.command) console.log(`        ${chalk.cyan('run:')} ${item.command}`);
-      }
-    }
-
-    console.log('');
-    console.log(chalk.bold('Recommended next steps:'));
-    for (const step of report.next_steps) {
-      console.log(`  - ${step}`);
-    }
-    if (report.suggested_commands.length > 0) {
+    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('Recommended next steps', nextStepLines, chalk.green),
+    ]) {
+      for (const line of block) console.log(line);
       console.log('');
-      console.log(chalk.bold('Suggested commands:'));
-      for (const command of report.suggested_commands) {
-        console.log(`  ${chalk.cyan(command)}`);
-      }
     }
   });
 
 // ── gate ─────────────────────────────────────────────────────────────────────
 
-const gateCmd = program.command('gate').description('Enforcement and commit-gate helpers');
+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');
 
@@ -2103,7 +3160,7 @@ gateCmd
 
 gateCmd
   .command('ai')
-  .description('Run the AI-style merge gate to assess semantic integration risk across worktrees')
+  .description('Run the AI-style merge check to assess risky overlap across workspaces')
   .option('--json', 'Output raw JSON')
   .action(async (opts) => {
     const repoRoot = getRepo();
@@ -2270,7 +3327,7 @@ objectCmd
 
 // ── monitor ──────────────────────────────────────────────────────────────────
 
-const monitorCmd = program.command('monitor').description('Observe worktrees for runtime file mutations');
+const monitorCmd = program.command('monitor').description('Observe workspaces for runtime file changes');
 
 monitorCmd
   .command('once')
@@ -2304,7 +3361,7 @@ monitorCmd
 
 monitorCmd
   .command('watch')
-  .description('Poll worktrees continuously and log observed file changes')
+  .description('Poll workspaces continuously and log observed file changes')
   .option('--interval-ms <ms>', 'Polling interval in milliseconds', '2000')
   .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
   .option('--daemonized', 'Internal flag used by monitor start', false)
@@ -2317,7 +3374,7 @@ monitorCmd
       process.exit(1);
     }
 
-    console.log(chalk.cyan(`Watching worktrees every ${intervalMs}ms. Press Ctrl+C to stop.`));
+    console.log(chalk.cyan(`Watching workspaces every ${intervalMs}ms. Press Ctrl+C to stop.`));
 
     let stopped = false;
     const stop = () => {