switchman-dev 0.1.3 → 0.1.4

package/src/cli/index.js

@@ -7,13 +7,13 @@
  *   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';
@@ -29,20 +29,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 +83,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,6 +128,52 @@ 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 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);
 }
@@ -454,6 +511,278 @@ 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;
+
+  console.log('');
+  console.log(healthColor('='.repeat(64)));
+  console.log(`${badge} ${chalk.bold('switchman status')} ${chalk.dim('• user-centred repo overview')}`);
+  console.log(`${chalk.dim(report.repo_root)}`);
+  console.log(`${chalk.dim(report.summary)}`);
+  console.log(healthColor('='.repeat(64)));
+  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.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 ? ` validation:${item.boundary_validation.status}` : '';
+      const stale = (item.dependency_invalidations?.length || 0) > 0 ? ` stale:${item.dependency_invalidations.length}` : '';
+      return `${chalk.cyan(item.worktree)} -> ${item.task_title} ${chalk.dim(item.task_id)}${item.scope_summary ? ` ${chalk.dim(item.scope_summary)}` : ''}${chalk.dim(boundary)}${chalk.dim(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 = [`${chalk.red('BLOCK')} ${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 tone = chalk.yellow('WARN ');
+      const lines = [`${tone} ${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 = [`${statusBadge(item.status)} ${item.id} ${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) => `[p${task.priority}] ${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 {
@@ -570,8 +899,8 @@ 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')
   .action((opts) => {
     const agentCount = parseInt(opts.agents);
@@ -592,7 +921,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 +929,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,7 +979,7 @@ 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('');
@@ -662,9 +991,45 @@ program
   });
 
 
+// ── 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')
+  .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
   .command('add <title>')
@@ -720,7 +1085,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();
@@ -764,7 +1129,7 @@ taskCmd
   .command('next')
   .description('Get and assign the next pending task (compatibility shim for lease next)')
   .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)')
   .action((opts) => {
     const repoRoot = getRepo();
@@ -792,6 +1157,259 @@ taskCmd
     }
   });
 
+// ── queue ─────────────────────────────────────────────────────────────────────
+
+const queueCmd = program.command('queue').description('Land finished work safely back onto main, one item at a time');
+
+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')
+  .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(`Worktree ${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('Provide a branch, --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();
+      console.error(chalk.red(err.message));
+      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')
+  .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;
+    }
+
+    console.log(`Queue: ${items.length} item(s)`);
+    console.log(`  ${chalk.dim('queued')} ${summary.counts.queued}  ${chalk.dim('validating')} ${summary.counts.validating}  ${chalk.dim('rebasing')} ${summary.counts.rebasing}  ${chalk.dim('merging')} ${summary.counts.merging}  ${chalk.dim('retrying')} ${summary.counts.retrying}  ${chalk.dim('blocked')} ${summary.counts.blocked}  ${chalk.dim('merged')} ${summary.counts.merged}`);
+    if (summary.next) {
+      console.log(`  ${chalk.dim('next:')} ${summary.next.id} ${summary.next.source_type}:${summary.next.source_ref} ${chalk.dim(`retries:${summary.next.retry_count}/${summary.next.max_retries}`)}`);
+    }
+    for (const item of summary.blocked) {
+      console.log(`  ${statusBadge(item.status)} ${item.id} ${item.source_type}:${item.source_ref} ${chalk.dim(`retries:${item.retry_count}/${item.max_retries}`)}`);
+      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}`);
+    }
+    if (recentEvents.length > 0) {
+      console.log('');
+      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 queued merge items serially')
+  .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')
+  .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) {
+      console.error(chalk.red(`Queue item ${itemId} is not retryable.`));
+      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) {
+      console.error(chalk.red(`Queue item ${itemId} does not exist.`));
+      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');
@@ -1215,13 +1833,18 @@ 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))
+  .option('--stale-after-minutes <minutes>', 'Age threshold for staleness')
   .option('--json', 'Output as JSON')
   .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,6 +1863,60 @@ 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');
@@ -1501,13 +2178,13 @@ 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')
   .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 +2277,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,194 +2291,41 @@ 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')
+  .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('');
-
-    // 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);
+    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;
 
-    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}`);
-      }
-    } 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}`);
+    while (true) {
+      if (watch && process.stdout.isTTY && !opts.json) {
+        console.clear();
       }
-    }
 
-    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)}`);
-      }
-    }
+      const report = await collectStatusSnapshot(repoRoot);
+      cycles += 1;
 
-    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` : ''}`);
-      }
-    }
-
-    // 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`);
+        renderUnifiedStatusReport(report);
+        if (watch) {
+          console.log('');
+          console.log(chalk.dim(`Watching every ${watchIntervalMs}ms${maxCycles > 0 ? ` • cycle ${cycles}/${maxCycles}` : ''}`));
         }
       }
 
-      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)}`);
-        }
-      }
-
-      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
@@ -1891,7 +2415,7 @@ program
 
 // ── 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');
 
 const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
 
@@ -2103,7 +2627,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 +2794,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 +2828,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 +2841,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 = () => {