switchman-dev 0.1.7 → 0.1.9

package/src/cli/index.js

@@ -16,15 +16,15 @@
  *   switchman status             - Show the repo dashboard
  */
 
-import { program } from 'commander';
+import { Help, program } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { dirname, join, posix } from 'path';
-import { execSync, spawn } from 'child_process';
+import { execSync, spawn, spawnSync } from 'child_process';
 
-import { cleanupCrashedLandingTempWorktrees, findRepoRoot, listGitWorktrees, createGitWorktree } from '../core/git.js';
+import { cleanupCrashedLandingTempWorktrees, createGitWorktree, findRepoRoot, getWorktreeBranch, getWorktreeChangedFiles, gitAssessBranchFreshness, gitBranchExists, listGitWorktrees } from '../core/git.js';
 import { matchesPathPatterns } from '../core/ignore.js';
 import {
   initDb, openDb,
@@ -37,18 +37,21 @@ import {
   createPolicyOverride, listPolicyOverrides, revokePolicyOverride,
   finishOperationJournalEntry, listOperationJournal, listTempResources, updateTempResource,
   claimFiles, releaseFileClaims, getActiveFileClaims, checkFileConflicts, retryTask,
-  listAuditEvents, verifyAuditTrail,
+  upsertTaskSpec,
+  listAuditEvents, pruneDatabaseMaintenance, verifyAuditTrail,
+  getLeaseExecutionContext, getActiveLeaseForTask,
 } from '../core/db.js';
 import { scanAllWorktrees } from '../core/detector.js';
-import { getWindsurfMcpConfigPath, upsertAllProjectMcpConfigs, upsertWindsurfMcpConfig } from '../core/mcp.js';
-import { gatewayAppendFile, gatewayMakeDirectory, gatewayMovePath, gatewayRemovePath, gatewayWriteFile, installGateHooks, monitorWorktreesOnce, runCommitGate, runWrappedCommand, writeEnforcementPolicy } from '../core/enforcement.js';
+import { ensureProjectLocalMcpGitExcludes, getWindsurfMcpConfigPath, upsertAllProjectMcpConfigs, upsertWindsurfMcpConfig } from '../core/mcp.js';
+import { evaluateRepoCompliance, gatewayAppendFile, gatewayMakeDirectory, gatewayMovePath, gatewayRemovePath, gatewayWriteFile, installGateHooks, monitorWorktreesOnce, runCommitGate, runWrappedCommand, writeEnforcementPolicy } from '../core/enforcement.js';
 import { runAiMergeGate } from '../core/merge-gate.js';
 import { clearMonitorState, getMonitorStatePath, isProcessRunning, readMonitorState, writeMonitorState } from '../core/monitor.js';
 import { buildPipelinePrSummary, cleanupPipelineLandingRecovery, commentPipelinePr, createPipelineFollowupTasks, evaluatePipelinePolicyGate, executePipeline, exportPipelinePrBundle, getPipelineLandingBranchStatus, getPipelineLandingExplainReport, getPipelineStatus, inferPipelineIdFromBranch, materializePipelineLandingBranch, preparePipelineLandingRecovery, preparePipelineLandingTarget, publishPipelinePr, repairPipelineState, resumePipelineLandingRecovery, runPipeline, startPipeline, summarizePipelinePolicyState, syncPipelinePr } from '../core/pipeline.js';
 import { installGitHubActionsWorkflow, resolveGitHubOutputTargets, writeGitHubCiStatus, writeGitHubPipelineLandingStatus } from '../core/ci.js';
 import { importCodeObjectsToStore, listCodeObjects, materializeCodeObjects, materializeSemanticIndex, updateCodeObjectSource } from '../core/semantic.js';
-import { buildQueueStatusSummary, resolveQueueSource, runMergeQueue } from '../core/queue.js';
+import { buildQueueStatusSummary, evaluateQueueRepoGate, resolveQueueSource, runMergeQueue } from '../core/queue.js';
 import { DEFAULT_CHANGE_POLICY, DEFAULT_LEASE_POLICY, getChangePolicyPath, loadChangePolicy, loadLeasePolicy, writeChangePolicy, writeLeasePolicy } from '../core/policy.js';
+import { planPipelineTasks } from '../core/planner.js';
 import {
   captureTelemetryEvent,
   disableTelemetry,
@@ -59,6 +62,19 @@ import {
   maybePromptForTelemetry,
   sendTelemetryEvent,
 } from '../core/telemetry.js';
+import { checkLicence, clearCredentials, FREE_AGENT_LIMIT, getRetentionDaysForCurrentPlan, loginWithGitHub, PRO_PAGE_URL, readCredentials } from '../core/licence.js';
+import { homedir } from 'os';
+import { cleanupOldSyncEvents, pullActiveTeamMembers, pullTeamState, pushSyncEvent } from '../core/sync.js';
+import { registerClaudeCommands } from './commands/claude.js';
+import { registerMcpCommands } from './commands/mcp.js';
+import { registerAuditCommands } from './commands/audit.js';
+import { registerGateCommands } from './commands/gate.js';
+import { registerLeaseCommands } from './commands/lease.js';
+import { registerMonitorCommands } from './commands/monitor.js';
+import { registerQueueCommands } from './commands/queue.js';
+import { registerTaskCommands } from './commands/task.js';
+import { registerTelemetryCommands } from './commands/telemetry.js';
+import { registerWorktreeCommands } from './commands/worktree.js';
 
 const originalProcessEmit = process.emit.bind(process);
 process.emit = function patchedProcessEmit(event, ...args) {
@@ -95,6 +111,299 @@ function getDb(repoRoot) {
   }
 }
 
+function getOptionalDb(repoRoot) {
+  try {
+    return openDb(repoRoot);
+  } catch {
+    return null;
+  }
+}
+
+function slugifyValue(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'plan';
+}
+
+function capitalizeSentence(value) {
+  const text = String(value || '').trim();
+  if (!text) return text;
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+function formatHumanList(values = []) {
+  if (values.length === 0) return '';
+  if (values.length === 1) return values[0];
+  if (values.length === 2) return `${values[0]} and ${values[1]}`;
+  return `${values.slice(0, -1).join(', ')}, and ${values[values.length - 1]}`;
+}
+
+function readPlanningFile(repoRoot, fileName, maxChars = 1200) {
+  const filePath = join(repoRoot, fileName);
+  if (!existsSync(filePath)) return null;
+  try {
+    const text = readFileSync(filePath, 'utf8').trim();
+    if (!text) return null;
+    return {
+      file: fileName,
+      text: text.slice(0, maxChars),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function extractMarkdownSignal(text) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  for (const line of lines) {
+    const normalized = line.replace(/^#+\s*/, '').replace(/^[-*]\s+/, '').trim();
+    if (!normalized) continue;
+    if (/^switchman\b/i.test(normalized)) continue;
+    return normalized;
+  }
+  return null;
+}
+
+function deriveGoalFromBranch(branchName) {
+  const raw = String(branchName || '').replace(/^refs\/heads\//, '').trim();
+  if (!raw || ['main', 'master', 'trunk', 'develop', 'development'].includes(raw)) return null;
+  const tail = raw.split('/').pop() || raw;
+  const tokens = tail
+    .replace(/^\d+[-_]?/, '')
+    .split(/[-_]/)
+    .filter(Boolean)
+    .filter((token) => !['feature', 'feat', 'fix', 'bugfix', 'chore', 'task', 'issue', 'story', 'work'].includes(token.toLowerCase()));
+  if (tokens.length === 0) return null;
+  return capitalizeSentence(tokens.join(' '));
+}
+
+function getRecentCommitSubjects(repoRoot, limit = 6) {
+  try {
+    return execSync(`git log --pretty=%s -n ${limit}`, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim().split('\n').map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function summarizeRecentCommitContext(branchGoal, subjects) {
+  if (!subjects.length) return null;
+  const topicWords = String(branchGoal || '')
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((word) => word.length >= 4);
+  const relatedCount = topicWords.length > 0
+    ? subjects.filter((subject) => {
+      const lower = subject.toLowerCase();
+      return topicWords.some((word) => lower.includes(word));
+    }).length
+    : 0;
+  const effectiveCount = relatedCount > 0 ? relatedCount : Math.min(subjects.length, 3);
+  const topicLabel = relatedCount > 0 && topicWords.length > 0 ? `${topicWords[0]}-related ` : '';
+  return `${effectiveCount} recent ${topicLabel}commit${effectiveCount === 1 ? '' : 's'}`;
+}
+
+function collectPlanContext(repoRoot, explicitGoal = null, issueContext = null) {
+  const planningFiles = ['CLAUDE.md', 'ROADMAP.md', 'tasks.md', 'TASKS.md', 'TODO.md', 'README.md']
+    .map((fileName) => readPlanningFile(repoRoot, fileName))
+    .filter(Boolean);
+  const planningByName = new Map(planningFiles.map((entry) => [entry.file, entry]));
+  const branch = getWorktreeBranch(process.cwd()) || null;
+  const branchGoal = deriveGoalFromBranch(branch);
+  const recentCommitSubjects = getRecentCommitSubjects(repoRoot, 6);
+  const recentCommitSummary = summarizeRecentCommitContext(branchGoal, recentCommitSubjects);
+  const preferredPlanningFile = planningByName.get('CLAUDE.md')
+    || planningByName.get('tasks.md')
+    || planningByName.get('TASKS.md')
+    || planningByName.get('ROADMAP.md')
+    || planningByName.get('TODO.md')
+    || planningByName.get('README.md')
+    || null;
+  const planningSignal = preferredPlanningFile ? extractMarkdownSignal(preferredPlanningFile.text) : null;
+  const title = capitalizeSentence(issueContext?.title || explicitGoal || branchGoal || planningSignal || 'Plan the next coordinated change');
+  const descriptionParts = [];
+  if (issueContext?.description) descriptionParts.push(issueContext.description);
+  if (preferredPlanningFile?.text) descriptionParts.push(preferredPlanningFile.text);
+  if (recentCommitSubjects.length > 0) descriptionParts.push(`Recent git history summary: ${recentCommitSubjects.slice(0, 3).join('; ')}.`);
+  const description = descriptionParts.join('\n\n').trim() || null;
+
+  const found = [];
+  const used = [];
+  if (issueContext?.number) {
+    found.push(`issue #${issueContext.number} "${issueContext.title}"`);
+    used.push(`GitHub issue #${issueContext.number}`);
+  }
+  if (explicitGoal) {
+    used.push('explicit goal');
+  }
+  if (branch) {
+    found.push(`branch ${branch}`);
+    if (branchGoal) used.push('branch name');
+  }
+  if (preferredPlanningFile?.file) {
+    found.push(preferredPlanningFile.file);
+    used.push(preferredPlanningFile.file);
+  }
+  if (recentCommitSummary) {
+    found.push(recentCommitSummary);
+    used.push('recent git history');
+  }
+
+  return {
+    branch,
+    title,
+    description,
+    found,
+    used: [...new Set(used)],
+  };
+}
+
+function fetchGitHubIssueContext(repoRoot, issueNumber, ghCommand = 'gh') {
+  const normalizedIssueNumber = String(issueNumber || '').trim();
+  if (!normalizedIssueNumber) {
+    throw new Error('A GitHub issue number is required.');
+  }
+
+  const result = spawnSync(ghCommand, [
+    'issue',
+    'view',
+    normalizedIssueNumber,
+    '--json',
+    'title,body,comments',
+  ], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+
+  if (result.error) {
+    throw new Error(`Could not run ${ghCommand} to read issue #${normalizedIssueNumber}. ${result.error.message}`);
+  }
+
+  if (result.status !== 0) {
+    const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+    throw new Error(output || `gh issue view failed for issue #${normalizedIssueNumber}. Make sure gh is installed and authenticated.`);
+  }
+
+  let issue;
+  try {
+    issue = JSON.parse(result.stdout || '{}');
+  } catch {
+    throw new Error(`Could not parse GitHub issue #${normalizedIssueNumber}.`);
+  }
+
+  const comments = Array.isArray(issue.comments)
+    ? issue.comments.map((entry) => entry?.body || '').filter(Boolean)
+    : [];
+  const descriptionParts = [
+    `GitHub issue #${normalizedIssueNumber}: ${issue.title || 'Untitled issue'}`,
+    issue.body || '',
+    comments.length > 0 ? `Comments:\n${comments.join('\n---\n')}` : '',
+  ].filter(Boolean);
+
+  return {
+    number: normalizedIssueNumber,
+    title: issue.title || `Issue #${normalizedIssueNumber}`,
+    description: descriptionParts.join('\n\n'),
+    comment_count: comments.length,
+  };
+}
+
+function buildPlanningCommentBody(context, plannedTasks) {
+  const lines = [
+    '## Switchman plan summary',
+    '',
+    `Planned from: **${context.title}**`,
+  ];
+
+  if (context.used.length > 0) {
+    lines.push(`Context used: ${context.used.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push('Proposed parallel tasks:');
+  lines.push('');
+
+  plannedTasks.forEach((task, index) => {
+    const worktreeLabel = task.suggested_worktree || 'unassigned';
+    lines.push(`${index + 1}. ${task.title} (${worktreeLabel})`);
+  });
+
+  lines.push('');
+  lines.push('_Generated by Switchman._');
+  return `${lines.join('\n')}\n`;
+}
+
+function postPlanningSummaryComment(repoRoot, {
+  ghCommand = 'gh',
+  issueNumber = null,
+  prNumber = null,
+  body,
+}) {
+  const targetNumber = prNumber || issueNumber;
+  if (!targetNumber) {
+    throw new Error('A GitHub issue or pull request number is required to post a planning summary.');
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'switchman-plan-comment-'));
+  const bodyPath = join(tempDir, 'plan-summary.md');
+  writeFileSync(bodyPath, body, 'utf8');
+
+  try {
+    const args = prNumber
+      ? ['pr', 'comment', String(prNumber), '--body-file', bodyPath]
+      : ['issue', 'comment', String(issueNumber), '--body-file', bodyPath];
+    const result = spawnSync(ghCommand, args, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    });
+
+    if (result.error) {
+      throw new Error(`Could not run ${ghCommand} to post the planning summary. ${result.error.message}`);
+    }
+
+    if (result.status !== 0) {
+      const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+      throw new Error(output || `gh ${prNumber ? 'pr' : 'issue'} comment failed.`);
+    }
+
+    return {
+      target_type: prNumber ? 'pr' : 'issue',
+      target_number: String(targetNumber),
+    };
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function resolvePlanningWorktrees(repoRoot, db = null) {
+  if (db) {
+    const registered = listWorktrees(db)
+      .filter((worktree) => worktree.name !== 'main' && worktree.status !== 'missing')
+      .map((worktree) => ({ name: worktree.name, path: worktree.path, branch: worktree.branch }));
+    if (registered.length > 0) return registered;
+  }
+  return listGitWorktrees(repoRoot)
+    .filter((worktree) => !worktree.isMain)
+    .map((worktree) => ({ name: worktree.name, path: worktree.path, branch: worktree.branch || null }));
+}
+
+function planTaskPriority(taskSpec = null) {
+  const taskType = taskSpec?.task_type || 'implementation';
+  if (taskType === 'implementation') return 8;
+  if (taskType === 'tests') return 7;
+  if (taskType === 'docs') return 6;
+  if (taskType === 'governance') return 6;
+  return 5;
+}
+
 function resolvePrNumberFromEnv(env = process.env) {
   if (env.SWITCHMAN_PR_NUMBER) return String(env.SWITCHMAN_PR_NUMBER);
   if (env.GITHUB_PR_NUMBER) return String(env.GITHUB_PR_NUMBER);
@@ -1289,6 +1598,184 @@ function printRepairSummary(report, {
   }
 }
 
+function summarizeRecoveredTaskState({
+  task,
+  lease = null,
+  worktree = null,
+  changedFiles = [],
+  claims = [],
+  boundaryValidation = null,
+  auditEvents = [],
+  recoveryKind,
+  staleAfterMinutes = null,
+}) {
+  const observedWrites = auditEvents.filter((event) => event.event_type === 'write_observed');
+  const latestAuditEvent = auditEvents[0] || null;
+  const nextAction = worktree?.path
+    ? `cd "${worktree.path}" && git status`
+    : `switchman task retry ${task.id}`;
+
+  return {
+    kind: recoveryKind,
+    task_id: task.id,
+    task_title: task.title,
+    worktree: worktree?.name || lease?.worktree || task.worktree || null,
+    worktree_path: worktree?.path || null,
+    lease_id: lease?.id || null,
+    agent: lease?.agent || task.agent || null,
+    stale_after_minutes: staleAfterMinutes,
+    changed_files: changedFiles,
+    claimed_files: claims,
+    observed_write_count: observedWrites.length,
+    latest_audit_event: latestAuditEvent ? {
+      event_type: latestAuditEvent.event_type,
+      status: latestAuditEvent.status,
+      created_at: latestAuditEvent.created_at,
+      reason_code: latestAuditEvent.reason_code || null,
+    } : null,
+    boundary_validation: boundaryValidation ? {
+      status: boundaryValidation.status,
+      missing_task_types: boundaryValidation.missing_task_types || [],
+    } : null,
+    progress_summary: changedFiles.length > 0
+      ? `Observed uncommitted changes in ${changedFiles.length} file(s).`
+      : claims.length > 0
+        ? `Lease held ${claims.length} active claim(s) before recovery.`
+        : observedWrites.length > 0
+          ? `Observed ${observedWrites.length} governed write event(s) before recovery.`
+          : 'No uncommitted changes were detected at recovery time.',
+    next_action: nextAction,
+  };
+}
+
+function buildRecoverReport(db, repoRoot, { staleAfterMinutes = null, reason = 'operator recover' } = {}) {
+  const leasePolicy = loadLeasePolicy(repoRoot);
+  const staleMinutes = staleAfterMinutes
+    ? Number.parseInt(staleAfterMinutes, 10)
+    : leasePolicy.stale_after_minutes;
+  const worktreeMap = new Map(listWorktrees(db).map((worktree) => [worktree.name, worktree]));
+  const staleLeases = getStaleLeases(db, staleMinutes);
+  const staleTaskIds = new Set(staleLeases.map((lease) => lease.task_id));
+  const staleLeaseSummaries = staleLeases.map((lease) => {
+    const execution = getLeaseExecutionContext(db, lease.id);
+    const worktree = worktreeMap.get(lease.worktree) || execution?.worktree || null;
+    const changedFiles = worktree?.path ? getWorktreeChangedFiles(worktree.path, repoRoot) : [];
+    const claims = execution?.claims?.map((claim) => claim.file_path) || [];
+    const boundaryValidation = getBoundaryValidationState(db, lease.id);
+    const auditEvents = listAuditEvents(db, { taskId: lease.task_id, limit: 10 });
+    return summarizeRecoveredTaskState({
+      task: execution?.task || getTask(db, lease.task_id),
+      lease,
+      worktree,
+      changedFiles,
+      claims,
+      boundaryValidation,
+      auditEvents,
+      recoveryKind: 'stale_lease',
+      staleAfterMinutes: staleMinutes,
+    });
+  });
+
+  const strandedTasks = listTasks(db, 'in_progress')
+    .filter((task) => !staleTaskIds.has(task.id))
+    .filter((task) => !getActiveLeaseForTask(db, task.id));
+  const strandedTaskSummaries = strandedTasks.map((task) => {
+    const worktree = task.worktree ? worktreeMap.get(task.worktree) || null : null;
+    const changedFiles = worktree?.path ? getWorktreeChangedFiles(worktree.path, repoRoot) : [];
+    const auditEvents = listAuditEvents(db, { taskId: task.id, limit: 10 });
+    return summarizeRecoveredTaskState({
+      task,
+      worktree,
+      changedFiles,
+      claims: [],
+      boundaryValidation: null,
+      auditEvents,
+      recoveryKind: 'stranded_task',
+    });
+  });
+
+  const expiredLeases = staleLeases.length > 0
+    ? reapStaleLeases(db, staleMinutes, { requeueTask: leasePolicy.requeue_task_on_reap })
+    : [];
+  const retriedTasks = strandedTasks
+    .map((task) => retryTask(db, task.id, reason))
+    .filter(Boolean);
+  const repair = repairRepoState(db, repoRoot);
+
+  return {
+    stale_after_minutes: staleMinutes,
+    requeue_task_on_reap: leasePolicy.requeue_task_on_reap,
+    stale_leases: staleLeaseSummaries.map((item) => ({
+      ...item,
+      recovered_to: leasePolicy.requeue_task_on_reap ? 'pending' : 'failed',
+    })),
+    stranded_tasks: strandedTaskSummaries.map((item) => ({
+      ...item,
+      recovered_to: 'pending',
+    })),
+    repair,
+    recovered: {
+      stale_leases: expiredLeases.length,
+      stranded_tasks: retriedTasks.length,
+      repo_actions: repair.actions.length,
+    },
+    next_steps: [
+      ...(staleLeaseSummaries.length > 0 || strandedTaskSummaries.length > 0
+        ? ['switchman status', 'switchman task list --status pending']
+        : []),
+      ...(repair.next_action ? [repair.next_action] : []),
+    ].filter((value, index, all) => all.indexOf(value) === index),
+  };
+}
+
+function printRecoverSummary(report) {
+  const totalRecovered = report.recovered.stale_leases + report.recovered.stranded_tasks;
+  console.log(totalRecovered > 0 || report.repair.repaired
+    ? `${chalk.green('✓')} Recovered abandoned work and repaired safe interrupted state`
+    : `${chalk.green('✓')} No abandoned work needed recovery`);
+
+  console.log(`  ${chalk.dim('stale lease threshold:')} ${report.stale_after_minutes} minute(s)`);
+  console.log(`  ${chalk.dim('requeue on reap:')} ${report.requeue_task_on_reap ? 'on' : 'off'}`);
+  console.log(`  ${chalk.green('recovered stale leases:')} ${report.recovered.stale_leases}`);
+  console.log(`  ${chalk.green('recovered stranded tasks:')} ${report.recovered.stranded_tasks}`);
+  console.log(`  ${chalk.green('repo repair actions:')} ${report.recovered.repo_actions}`);
+
+  const recoveredItems = [...report.stale_leases, ...report.stranded_tasks];
+  if (recoveredItems.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Recovered work:'));
+    for (const item of recoveredItems) {
+      console.log(`  ${chalk.cyan(item.worktree || 'unknown')} ${chalk.dim(item.task_id)} ${chalk.bold(item.task_title)}`);
+      console.log(`    ${chalk.dim('type:')} ${item.kind === 'stale_lease' ? 'stale lease' : 'stranded in-progress task'}${item.lease_id ? `  ${chalk.dim('lease:')} ${item.lease_id}` : ''}`);
+      console.log(`    ${chalk.dim('summary:')} ${item.progress_summary}`);
+      if (item.changed_files.length > 0) {
+        console.log(`    ${chalk.dim('changed:')} ${item.changed_files.slice(0, 5).join(', ')}${item.changed_files.length > 5 ? ` ${chalk.dim(`+${item.changed_files.length - 5} more`)}` : ''}`);
+      }
+      if (item.claimed_files.length > 0) {
+        console.log(`    ${chalk.dim('claimed:')} ${item.claimed_files.slice(0, 5).join(', ')}${item.claimed_files.length > 5 ? ` ${chalk.dim(`+${item.claimed_files.length - 5} more`)}` : ''}`);
+      }
+      if (item.boundary_validation) {
+        console.log(`    ${chalk.dim('validation:')} ${item.boundary_validation.status}${item.boundary_validation.missing_task_types.length > 0 ? ` ${chalk.dim(`missing ${item.boundary_validation.missing_task_types.join(', ')}`)}` : ''}`);
+      }
+      console.log(`    ${chalk.yellow('inspect:')} ${item.next_action}`);
+    }
+  }
+
+  console.log('');
+  printRepairSummary(report.repair, {
+    repairedHeading: `${chalk.green('✓')} Repaired safe interrupted repo state during recovery`,
+    noRepairHeading: `${chalk.green('✓')} No extra repo repair action was needed during recovery`,
+    limit: 6,
+  });
+  if (report.next_steps.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Next steps:'));
+    for (const step of report.next_steps) {
+      console.log(`  ${chalk.cyan(step)}`);
+    }
+  }
+}
+
 function repairRepoState(db, repoRoot) {
   const actions = [];
   const warnings = [];
@@ -1582,7 +2069,7 @@ function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
     detail: claudeGuideExists ? 'CLAUDE.md is present' : 'CLAUDE.md is optional but recommended for Claude Code',
   });
   if (!claudeGuideExists) {
-    nextSteps.push('If you use Claude Code, add `CLAUDE.md` from the repo root setup guide.');
+    nextSteps.push('If you use Claude Code, run `switchman claude refresh` to generate a repo-aware `CLAUDE.md`.');
   }
 
   const windsurfConfigExists = existsSync(getWindsurfMcpConfigPath(homeDir || undefined));
@@ -1618,6 +2105,238 @@ function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
   };
 }
 
+function readJsonFileIfExists(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function detectClaudeGuideContext(repoRoot) {
+  const packageJson = readJsonFileIfExists(join(repoRoot, 'package.json'));
+  const hasTsconfig = existsSync(join(repoRoot, 'tsconfig.json'));
+  const hasPyproject = existsSync(join(repoRoot, 'pyproject.toml'));
+  const hasRequirements = existsSync(join(repoRoot, 'requirements.txt'));
+  const hasGoMod = existsSync(join(repoRoot, 'go.mod'));
+  const hasCargo = existsSync(join(repoRoot, 'Cargo.toml'));
+  const hasGemfile = existsSync(join(repoRoot, 'Gemfile'));
+
+  const stack = [];
+  if (packageJson) stack.push(hasTsconfig ? 'Node.js + TypeScript' : 'Node.js');
+  if (!packageJson && hasTsconfig) stack.push('TypeScript');
+  if (hasPyproject || hasRequirements) stack.push('Python');
+  if (hasGoMod) stack.push('Go');
+  if (hasCargo) stack.push('Rust');
+  if (hasGemfile) stack.push('Ruby');
+  if (stack.length === 0) stack.push('general-purpose codebase');
+
+  const packageManager = existsSync(join(repoRoot, 'pnpm-lock.yaml'))
+    ? 'pnpm'
+    : existsSync(join(repoRoot, 'yarn.lock'))
+      ? 'yarn'
+      : 'npm';
+
+  const scripts = packageJson?.scripts || {};
+  const packageRunner = packageManager === 'pnpm'
+    ? 'pnpm'
+    : packageManager === 'yarn'
+      ? 'yarn'
+      : 'npm run';
+  const testCommand = typeof scripts.test === 'string' && scripts.test.trim() && !scripts.test.includes('no test specified')
+    ? `${packageRunner}${packageManager === 'yarn' ? ' test' : ' test'}`
+    : hasPyproject || hasRequirements
+      ? 'pytest'
+      : hasGoMod
+        ? 'go test ./...'
+        : hasCargo
+          ? 'cargo test'
+          : null;
+  const buildCommand = typeof scripts.build === 'string' && scripts.build.trim()
+    ? `${packageRunner}${packageManager === 'yarn' ? ' build' : ' build'}`
+    : hasGoMod
+      ? 'go build ./...'
+      : hasCargo
+        ? 'cargo build'
+        : null;
+  const lintCommand = typeof scripts.lint === 'string' && scripts.lint.trim()
+    ? `${packageRunner}${packageManager === 'yarn' ? ' lint' : ' lint'}`
+    : null;
+
+  const importantPaths = [
+    existsSync(join(repoRoot, 'src')) ? 'src/' : null,
+    existsSync(join(repoRoot, 'app')) ? 'app/' : null,
+    existsSync(join(repoRoot, 'lib')) ? 'lib/' : null,
+    existsSync(join(repoRoot, 'tests')) ? 'tests/' : null,
+    existsSync(join(repoRoot, 'test')) ? 'test/' : null,
+    existsSync(join(repoRoot, 'docs')) ? 'docs/' : null,
+    existsSync(join(repoRoot, 'packages')) ? 'packages/' : null,
+  ].filter(Boolean);
+
+  const conventions = [];
+  if (existsSync(join(repoRoot, '.mcp.json'))) conventions.push('project-local MCP config is already wired');
+  if (existsSync(join(repoRoot, '.cursor', 'mcp.json'))) conventions.push('Cursor MCP config is present');
+  if (existsSync(join(repoRoot, '.git', 'info', 'exclude'))) conventions.push('repo-local git excludes can hide MCP noise from merges');
+
+  return {
+    stack,
+    packageManager,
+    testCommand,
+    buildCommand,
+    lintCommand,
+    importantPaths: importantPaths.slice(0, 5),
+    conventions,
+  };
+}
+
+function renderClaudeGuide(repoRoot) {
+  const context = detectClaudeGuideContext(repoRoot);
+  const stackSummary = formatHumanList(context.stack);
+  const importantPaths = context.importantPaths.length > 0
+    ? context.importantPaths.join(', ')
+    : 'the repo root';
+  const preferredCommands = [
+    context.testCommand ? `- Tests: \`${context.testCommand}\`` : null,
+    context.buildCommand ? `- Build: \`${context.buildCommand}\`` : null,
+    context.lintCommand ? `- Lint: \`${context.lintCommand}\`` : null,
+  ].filter(Boolean);
+  const conventions = context.conventions.length > 0
+    ? context.conventions.map((item) => `- ${item}`)
+    : ['- follow the existing file layout and naming conventions already in the repo'];
+
+  return `# Switchman Agent Instructions
+
+This repository uses **Switchman** to coordinate parallel AI coding agents.
+You MUST follow these instructions every session to avoid conflicting with other agents.
+
+You must use the Switchman MCP tools for coordination. Do not read from or write to \`.switchman/switchman.db\` directly, and do not bypass Switchman by issuing raw SQLite queries.
+
+---
+
+## Repo profile
+
+- Stack: ${stackSummary}
+- Important paths: ${importantPaths}
+${preferredCommands.length > 0 ? preferredCommands.join('\n') : '- Commands: follow the repo-specific test/build scripts before marking work complete'}
+
+## Existing conventions
+
+${conventions.join('\n')}
+
+When you make changes, preserve the current code style, folder structure, and script usage that already exist in this repo.
+
+---
+
+## Your worktree
+
+Find your worktree name by running:
+\`\`\`bash
+git worktree list
+\`\`\`
+The path that matches your current directory is your worktree. Use the last path segment as your worktree name (e.g. \`/projects/myapp-feature-auth\` → \`feature-auth\`). The main repo root is always named \`main\`.
+
+---
+
+## Required workflow — follow this every session
+
+### 1. Start of session — get your task
+
+Call the \`switchman_task_next\` MCP tool with your worktree name:
+\`\`\`
+switchman_task_next({ worktree: "<your-worktree-name>", agent: "claude-code" })
+\`\`\`
+
+- If \`task\` is \`null\` — the queue is empty. Ask the user what to work on, or stop.
+- If you receive a task — note the \`task.id\`. You'll need it in the next steps.
+- If the \`switchman_*\` tools are unavailable, stop and tell the user the MCP server is not connected. Do not fall back to direct SQLite access.
+
+### 2. Before editing any files — claim them
+
+Call \`switchman_task_claim\` with every file you plan to edit **before you edit them**:
+\`\`\`
+switchman_task_claim({
+  task_id: "<task-id>",
+  worktree: "<your-worktree-name>",
+  files: ["src/auth/login.js", "tests/auth.test.js"]
+})
+\`\`\`
+
+- If \`safe_to_proceed\` is \`false\` — there are conflicts. Do NOT edit those files.
+  Read the \`conflicts\` array to see which worktrees own them, then either:
+  - Choose different files that accomplish the same goal
+  - Ask the user how to proceed
+
+- If \`safe_to_proceed\` is \`true\` — you are clear to edit.
+
+### 3. Do the work
+
+Implement the task. Make commits as normal. Other agents will avoid your claimed files.
+
+If you discover mid-task that you need to edit additional files, call \`switchman_task_claim\` again for those files before editing them.
+
+When MCP write tools are available, prefer the Switchman enforcement gateway over native file writes:
+\`\`\`text
+switchman_write_file(...)
+switchman_append_file(...)
+switchman_make_directory(...)
+switchman_move_path(...)
+switchman_remove_path(...)
+\`\`\`
+
+These tools validate your active lease and claimed paths before changing the filesystem. Use native file writes only when the Switchman write tools are unavailable and you have already claimed the path.
+
+### 4. Before marking work complete
+
+Run the repo's most relevant verification commands for the files you changed.
+${context.testCommand ? `At minimum, prefer \`${context.testCommand}\` when the task changes behavior or tests.\n` : ''}${context.lintCommand ? `Use \`${context.lintCommand}\` when the repo relies on linting before merge.\n` : ''}${context.buildCommand ? `Use \`${context.buildCommand}\` when the repo has a meaningful build step.\n` : ''}If the correct command is unclear, inspect the existing scripts and match the repo's normal workflow.
+
+### 5. End of session — mark complete or failed
+
+**On success:**
+\`\`\`
+switchman_task_done({ task_id: "<task-id>" })
+\`\`\`
+
+**On failure (can't complete the task):**
+\`\`\`
+switchman_task_fail({ task_id: "<task-id>", reason: "Brief explanation of what blocked you" })
+\`\`\`
+
+Always call one of these before ending your session. Released file claims allow other agents to proceed.
+
+---
+
+## Checking system state
+
+To see what other agents are doing:
+\`\`\`
+switchman_status()
+\`\`\`
+
+To recover abandoned work or stale sessions:
+\`\`\`
+switchman_recover()
+\`\`\`
+
+To scan for conflicts before merge:
+\`\`\`
+switchman_scan()
+\`\`\`
+
+---
+
+## Rules
+
+1. **Always claim files before editing them** — not after.
+2. **Always call \`switchman_task_done\` or \`switchman_task_fail\` at end of session** — never leave tasks as \`in_progress\` when you stop.
+3. **If \`safe_to_proceed\` is false, do not edit the conflicting files** — coordinate first.
+4. **Do not claim files you don't need** — over-claiming blocks other agents unnecessarily.
+5. **One task per session** — complete or fail your current task before taking another.
+6. **Never query or mutate the Switchman SQLite database directly** — use MCP tools only.
+`;
+}
+
 function renderSetupVerification(report, { compact = false } = {}) {
   console.log(chalk.bold(compact ? 'First-run check:' : 'Setup verification:'));
   for (const check of report.checks) {
@@ -1783,12 +2502,24 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
       };
     });
 
-  const blockedWorktrees = scanReport.unclaimedChanges.map((entry) => ({
-    worktree: entry.worktree,
-    files: entry.files,
-    reason_code: entry.reasons?.[0]?.reason_code || null,
-    next_step: nextStepForReason(entry.reasons?.[0]?.reason_code) || 'inspect the changed files and bring them back under Switchman claims',
-  }));
+  const worktreeByName = new Map((scanReport.worktrees || []).map((worktree) => [worktree.name, worktree]));
+  const blockedWorktrees = scanReport.unclaimedChanges.map((entry) => {
+    const worktreeInfo = worktreeByName.get(entry.worktree) || null;
+    const reasonCode = entry.reasons?.[0]?.reason_code || null;
+    const isDirtyWorktree = reasonCode === 'no_active_lease';
+    return {
+      worktree: entry.worktree,
+      path: worktreeInfo?.path || null,
+      files: entry.files,
+      reason_code: reasonCode,
+      next_step: isDirtyWorktree
+        ? 'commit or discard the changed files in that worktree, then rescan before continuing'
+        : (nextStepForReason(reasonCode) || 'inspect the changed files and bring them back under Switchman claims'),
+      command: worktreeInfo?.path
+        ? `cd ${JSON.stringify(worktreeInfo.path)} && git status`
+        : 'switchman scan',
+    };
+  });
 
   const fileConflicts = scanReport.fileConflicts.map((conflict) => ({
     file: conflict.file,
@@ -1838,9 +2569,9 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
     ...blockedWorktrees.map((entry) => ({
       kind: 'unmanaged_changes',
       title: `${entry.worktree} has unmanaged changed files`,
-      detail: `${entry.files.slice(0, 3).join(', ')}${entry.files.length > 3 ? ` +${entry.files.length - 3} more` : ''}`,
+      detail: `${entry.files.slice(0, 5).join(', ')}${entry.files.length > 5 ? ` +${entry.files.length - 5} more` : ''}${entry.path ? ` • ${entry.path}` : ''}`,
       next_step: entry.next_step,
-      command: 'switchman scan',
+      command: entry.command,
       severity: 'block',
     })),
     ...fileConflicts.map((conflict) => ({
@@ -1997,6 +2728,7 @@ function buildUnifiedStatusReport({
   queueItems,
   queueSummary,
   recentQueueEvents,
+  retentionDays = 7,
 }) {
   const queueAttention = [
     ...queueItems
@@ -2101,6 +2833,7 @@ function buildUnifiedStatusReport({
       ...queueAttention.map((item) => item.next_step),
     ])].slice(0, 6),
     suggested_commands: [...new Set(attention.length > 0 ? suggestedCommands : defaultSuggestedCommands)].slice(0, 6),
+    retention_days: retentionDays,
   };
 }
 
@@ -2108,6 +2841,9 @@ async function collectStatusSnapshot(repoRoot) {
   const db = getDb(repoRoot);
   try {
     const leasePolicy = loadLeasePolicy(repoRoot);
+    const retentionDays = await getRetentionDaysForCurrentPlan();
+    pruneDatabaseMaintenance(db, { retentionDays });
+    cleanupOldSyncEvents({ retentionDays }).catch(() => {});
 
     if (leasePolicy.reap_on_status_check) {
       reapStaleLeases(db, leasePolicy.stale_after_minutes, {
@@ -2147,13 +2883,40 @@ async function collectStatusSnapshot(repoRoot) {
       queueItems,
       queueSummary,
       recentQueueEvents,
+      retentionDays,
     });
   } finally {
     db.close();
   }
 }
 
-function renderUnifiedStatusReport(report) {
+function summarizeTeamCoordinationState(events = [], myUserId = null) {
+  const visibleEvents = events.filter((event) => event.user_id !== myUserId);
+  if (visibleEvents.length === 0) {
+    return {
+      members: 0,
+      queue_events: 0,
+      lease_events: 0,
+      claim_events: 0,
+      latest_queue_event: null,
+    };
+  }
+
+  const activeMembers = new Set(visibleEvents.map((event) => event.user_id || `${event.payload?.email || 'unknown'}:${event.worktree || 'unknown'}`));
+  const queueEvents = visibleEvents.filter((event) => ['queue_added', 'queue_merged', 'queue_blocked'].includes(event.event_type));
+  const leaseEvents = visibleEvents.filter((event) => ['lease_acquired', 'task_done', 'task_failed', 'task_retried'].includes(event.event_type));
+  const claimEvents = visibleEvents.filter((event) => ['claim_added', 'claim_released'].includes(event.event_type));
+
+  return {
+    members: activeMembers.size,
+    queue_events: queueEvents.length,
+    lease_events: leaseEvents.length,
+    claim_events: claimEvents.length,
+    latest_queue_event: queueEvents[0] || null,
+  };
+}
+
+function renderUnifiedStatusReport(report, { teamActivity = [], teamSummary = null } = {}) {
   const healthColor = colorForHealth(report.health);
   const badge = healthColor(healthLabel(report.health));
   const mergeColor = report.merge_readiness.ci_gate_ok ? chalk.green : chalk.red;
@@ -2212,10 +2975,43 @@ function renderUnifiedStatusReport(report) {
   console.log(`${chalk.bold('Run next:')} ${chalk.cyan(primaryCommand)}`);
   console.log(`${chalk.dim('why:')} ${nextStepLine}`);
   console.log(chalk.dim(`policy: ${formatRelativePolicy(report.lease_policy)} • requeue on reap ${report.lease_policy.requeue_task_on_reap ? 'on' : 'off'}`));
+  console.log(chalk.dim(`history retention: ${report.retention_days || 7} days`));
   if (report.merge_readiness.policy_state?.active) {
     console.log(chalk.dim(`change policy: ${report.merge_readiness.policy_state.domains.join(', ')} • ${report.merge_readiness.policy_state.enforcement} • missing ${report.merge_readiness.policy_state.missing_task_types.join(', ') || 'none'}`));
   }
 
+  // ── Team activity (Pro cloud sync) ──────────────────────────────────────────
+  if (teamSummary && teamSummary.members > 0) {
+    console.log('');
+    console.log(chalk.bold('Shared cloud state:'));
+    console.log(`  ${chalk.dim('members:')} ${teamSummary.members}  ${chalk.dim('leases:')} ${teamSummary.lease_events}  ${chalk.dim('claims:')} ${teamSummary.claim_events}  ${chalk.dim('queue:')} ${teamSummary.queue_events}`);
+    if (teamSummary.latest_queue_event) {
+      console.log(`  ${chalk.dim('latest queue event:')} ${chalk.cyan(teamSummary.latest_queue_event.event_type)} ${chalk.dim(teamSummary.latest_queue_event.payload?.source_ref || teamSummary.latest_queue_event.payload?.item_id || '')}`.trim());
+    }
+  }
+  if (teamActivity.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Team activity:'));
+    for (const member of teamActivity) {
+      const email = member.payload?.email ?? chalk.dim(member.user_id?.slice(0, 8) ?? 'unknown');
+      const worktree = chalk.cyan(member.worktree ?? 'unknown');
+      const eventLabel = {
+        task_added:     'added a task',
+        task_done:      'completed a task',
+        task_failed:    'failed a task',
+        task_retried:   'retried a task',
+        lease_acquired: `working on: ${chalk.dim(member.payload?.title ?? '')}`,
+        claim_added:    `claimed ${chalk.dim(member.payload?.file_count ?? 0)} file(s)`,
+        claim_released: 'released file claims',
+        queue_added:    `queued ${chalk.dim(member.payload?.source_ref ?? member.payload?.item_id ?? 'work')}`,
+        queue_merged:   `landed ${chalk.dim(member.payload?.source_ref ?? member.payload?.item_id ?? 'work')}`,
+        queue_blocked:  `blocked ${chalk.dim(member.payload?.source_ref ?? member.payload?.item_id ?? 'work')}`,
+        status_ping:    'active',
+      }[member.event_type] ?? member.event_type;
+      console.log(`  ${chalk.dim('○')} ${email} · ${worktree} · ${eventLabel}`);
+    }
+  }
+
   const runningLines = report.active_work.length > 0
     ? report.active_work.slice(0, 5).map((item) => {
       const boundary = item.boundary_validation
@@ -2230,6 +3026,27 @@ function renderUnifiedStatusReport(report) {
 
   const blockedItems = report.attention.filter((item) => item.severity === 'block');
   const warningItems = report.attention.filter((item) => item.severity !== 'block');
+  const isQuietEmptyState = report.active_work.length === 0
+    && blockedItems.length === 0
+    && warningItems.length === 0
+    && report.queue.items.length === 0
+    && report.next_up.length === 0
+    && report.failed_tasks.length === 0;
+
+  if (isQuietEmptyState) {
+    console.log('');
+    console.log(healthColor('='.repeat(72)));
+    console.log(`${badge} ${chalk.bold('switchman status')} ${chalk.dim('• mission control for parallel agents')}`);
+    console.log(`${chalk.dim(report.repo_root)}`);
+    console.log(`${chalk.dim(report.summary)}`);
+    console.log(healthColor('='.repeat(72)));
+    console.log('');
+    console.log(chalk.green('Nothing is running yet.'));
+    console.log(`Add work with: ${chalk.cyan('switchman task add "Your first task" --priority 8')}`);
+    console.log(`Or prove the flow in 30 seconds with: ${chalk.cyan('switchman demo')}`);
+    console.log('');
+    return;
+  }
 
   const blockedLines = blockedItems.length > 0
     ? blockedItems.slice(0, 4).flatMap((item) => {
@@ -2405,10 +3222,12 @@ function completeTaskWithRetries(repoRoot, taskId, attempts = 20) {
     let db = null;
     try {
       db = openDb(repoRoot);
-      completeTask(db, taskId);
-      releaseFileClaims(db, taskId);
+      const result = completeTask(db, taskId);
+      if (result?.status === 'completed') {
+        releaseFileClaims(db, taskId);
+      }
       db.close();
-      return;
+      return result;
     } catch (err) {
       lastError = err;
       try { db?.close(); } catch { /* no-op */ }
@@ -2421,38 +3240,311 @@ function completeTaskWithRetries(repoRoot, taskId, attempts = 20) {
   throw lastError;
 }
 
-// ─── Program ──────────────────────────────────────────────────────────────────
+function startBackgroundMonitor(repoRoot, { intervalMs = 2000, quarantine = false } = {}) {
+  const existingState = readMonitorState(repoRoot);
+  if (existingState && isProcessRunning(existingState.pid)) {
+    return {
+      already_running: true,
+      state: existingState,
+      state_path: getMonitorStatePath(repoRoot),
+    };
+  }
 
-program
-  .name('switchman')
-  .description('Conflict-aware task coordinator for parallel AI coding agents')
-  .version('0.1.0');
+  const logPath = join(repoRoot, '.switchman', 'monitor.log');
+  const child = spawn(process.execPath, [
+    process.argv[1],
+    'monitor',
+    'watch',
+    '--interval-ms',
+    String(intervalMs),
+    ...(quarantine ? ['--quarantine'] : []),
+    '--daemonized',
+  ], {
+    cwd: repoRoot,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  const statePath = writeMonitorState(repoRoot, {
+    pid: child.pid,
+    interval_ms: intervalMs,
+    quarantine: Boolean(quarantine),
+    log_path: logPath,
+    started_at: new Date().toISOString(),
+  });
 
-program.showHelpAfterError('(run with --help for usage examples)');
-program.addHelpText('after', `
-Start here:
-  switchman demo
-  switchman setup --agents 5
-  switchman status --watch
-  switchman gate ci
+  return {
+    already_running: false,
+    state: readMonitorState(repoRoot),
+    state_path: statePath,
+  };
+}
 
-Most useful commands:
-  switchman task add "Implement auth helper" --priority 9
-  switchman lease next --json
-  switchman queue run --watch
+function renderMonitorEvent(event) {
+  const ownerText = event.owner_worktree
+    ? `${event.owner_worktree}${event.owner_task_id ? ` (${event.owner_task_id})` : ''}`
+    : null;
+  const claimCommand = event.task_id
+    ? `switchman claim ${event.task_id} ${event.worktree} ${event.file_path}`
+    : null;
 
-Docs:
-  README.md
-  docs/setup-cursor.md
-`);
+  if (event.status === 'denied') {
+    console.log(`${chalk.yellow('⚠')} ${chalk.cyan(event.worktree)} modified ${chalk.yellow(event.file_path)} without governed ownership`);
+    if (ownerText) {
+      console.log(`   ${chalk.dim('Owned by:')} ${chalk.cyan(ownerText)}${event.owner_task_title ? ` ${chalk.dim(`— ${event.owner_task_title}`)}` : ''}`);
+    }
+    if (claimCommand) {
+      console.log(`   ${chalk.dim('Run:')} ${chalk.cyan(claimCommand)}`);
+    }
+    console.log(`   ${chalk.dim('Or:')} ${chalk.cyan('switchman status')}  ${chalk.dim('to inspect current claims and blockers')}`);
+    if (event.enforcement_action) {
+      console.log(`   ${chalk.dim('Action:')} ${event.enforcement_action}`);
+    }
+    return;
+  }
 
-program
-  .command('demo')
-  .description('Create a throwaway repo that proves overlapping claims are blocked and safe landing works')
-  .option('--path <dir>', 'Directory to create the demo repo in')
-  .option('--cleanup', 'Delete the demo repo after the run finishes')
-  .option('--json', 'Output raw JSON')
-  .addHelpText('after', `
+  const ownerSuffix = ownerText ? ` ${chalk.dim(`(${ownerText})`)}` : '';
+  console.log(`${chalk.green('✓')} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${ownerSuffix}`);
+}
+
+function resolveMonitoredWorktrees(db, repoRoot) {
+  const registeredByPath = new Map(
+    listWorktrees(db)
+      .filter((worktree) => worktree.path)
+      .map((worktree) => [worktree.path, worktree])
+  );
+
+  return listGitWorktrees(repoRoot).map((worktree) => {
+    const registered = registeredByPath.get(worktree.path);
+    if (!registered) return worktree;
+    return {
+      ...worktree,
+      name: registered.name,
+      path: registered.path || worktree.path,
+      branch: registered.branch || worktree.branch,
+    };
+  });
+}
+
+function discoverMergeCandidates(db, repoRoot, { targetBranch = 'main' } = {}) {
+  const worktrees = listWorktrees(db).filter((worktree) => worktree.name !== 'main');
+  const activeLeases = new Set(listLeases(db, 'active').map((lease) => lease.worktree));
+  const tasks = listTasks(db);
+  const queueItems = listMergeQueue(db).filter((item) => item.status !== 'merged');
+  const alreadyQueued = new Set(queueItems.map((item) => item.source_worktree).filter(Boolean));
+
+  const eligible = [];
+  const blocked = [];
+  const skipped = [];
+
+  for (const worktree of worktrees) {
+    const doneTasks = tasks.filter((task) => task.worktree === worktree.name && task.status === 'done');
+    if (doneTasks.length === 0) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'no_completed_tasks',
+        summary: 'no completed tasks are assigned to this worktree yet',
+        command: `switchman task list --status done`,
+      });
+      continue;
+    }
+
+    if (!worktree.branch || worktree.branch === targetBranch) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch || null,
+        reason: 'no_merge_branch',
+        summary: `worktree is on ${targetBranch} already`,
+        command: `switchman worktree list`,
+      });
+      continue;
+    }
+
+    if (!gitBranchExists(repoRoot, worktree.branch)) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'missing_branch',
+        summary: `branch ${worktree.branch} is not available in git`,
+        command: `switchman worktree sync`,
+      });
+      continue;
+    }
+
+    if (activeLeases.has(worktree.name)) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'active_lease',
+        summary: 'an active lease is still running in this worktree',
+        command: `switchman status`,
+      });
+      continue;
+    }
+
+    if (alreadyQueued.has(worktree.name)) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'already_queued',
+        summary: 'worktree is already in the landing queue',
+        command: `switchman queue status`,
+      });
+      continue;
+    }
+
+    const dirtyFiles = getWorktreeChangedFiles(worktree.path, repoRoot);
+    if (dirtyFiles.length > 0) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        path: worktree.path,
+        files: dirtyFiles,
+        reason: 'dirty_worktree',
+        summary: `worktree has uncommitted changes: ${dirtyFiles.slice(0, 5).join(', ')}${dirtyFiles.length > 5 ? ` +${dirtyFiles.length - 5} more` : ''}`,
+        command: `cd ${JSON.stringify(worktree.path)} && git status`,
+      });
+      continue;
+    }
+
+    const freshness = gitAssessBranchFreshness(repoRoot, targetBranch, worktree.branch);
+    eligible.push({
+      worktree: worktree.name,
+      branch: worktree.branch,
+      path: worktree.path,
+      done_task_count: doneTasks.length,
+      done_task_titles: doneTasks.slice(0, 3).map((task) => task.title),
+      freshness,
+    });
+  }
+
+  return { eligible, blocked, skipped, queue_items: queueItems };
+}
+
+function printMergeDiscovery(discovery) {
+  console.log('');
+  console.log(chalk.bold(`Checking ${discovery.eligible.length + discovery.blocked.length + discovery.skipped.length} worktree(s)...`));
+
+  for (const entry of discovery.eligible) {
+    const freshness = entry.freshness?.state && entry.freshness.state !== 'unknown'
+      ? ` ${chalk.dim(`(${entry.freshness.state})`)}`
+      : '';
+    console.log(`  ${chalk.green('✓')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch)}${freshness}`);
+  }
+
+  for (const entry of discovery.blocked) {
+    console.log(`  ${chalk.yellow('!')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch || 'no branch')}  ${chalk.dim(`— ${entry.summary}`)}`);
+  }
+
+  for (const entry of discovery.skipped) {
+    if (entry.reason === 'no_completed_tasks') continue;
+    console.log(`  ${chalk.dim('·')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch || 'no branch')}  ${chalk.dim(`— ${entry.summary}`)}`);
+  }
+}
+
+// ─── Program ──────────────────────────────────────────────────────────────────
+
+program
+  .name('switchman')
+  .description('Conflict-aware task coordinator for parallel AI coding agents')
+  .version('0.1.0');
+
+program.showHelpAfterError('(run with --help for usage examples)');
+const ROOT_HELP_COMMANDS = new Set([
+  'advanced',
+  'claude',
+  'demo',
+  'setup',
+  'verify-setup',
+  'login',
+  'upgrade',
+  'plan',
+  'task',
+  'status',
+  'recover',
+  'merge',
+  'repair',
+  'help',
+]);
+program.configureHelp({
+  visibleCommands(cmd) {
+    const commands = Help.prototype.visibleCommands.call(this, cmd);
+    if (cmd.parent) return commands;
+    return commands.filter((command) => ROOT_HELP_COMMANDS.has(command.name()) && !command._switchmanAdvanced);
+  },
+});
+program.addHelpText('after', `
+Start here:
+  switchman demo
+  switchman setup --agents 3
+  switchman task add "Your task" --priority 8
+  switchman status --watch
+  switchman recover
+  switchman gate ci && switchman queue run
+
+For you (the operator):
+  switchman demo
+  switchman setup
+  switchman claude refresh
+  switchman task add
+  switchman status
+  switchman recover
+  switchman merge
+  switchman repair
+  switchman upgrade
+  switchman login
+  switchman plan "Add authentication"   (Pro)
+
+For your agents (via CLAUDE.md or MCP):
+  switchman lease next
+  switchman claim
+  switchman task done
+  switchman write
+  switchman wrap
+
+Docs:
+  README.md
+  docs/setup-claude-code.md
+
+Power tools:
+  switchman advanced --help
+`);
+
+const advancedCmd = program
+  .command('advanced')
+  .description('Show advanced, experimental, and power-user command groups')
+  .addHelpText('after', `
+Advanced operator commands:
+  switchman pipeline <...>
+  switchman audit <...>
+  switchman policy <...>
+  switchman monitor <...>
+  switchman repair
+
+Experimental commands:
+  switchman semantic <...>
+  switchman object <...>
+
+Compatibility aliases:
+  switchman doctor
+
+Tip:
+  The main help keeps the day-one workflow small on purpose.
+`)
+  .action(() => {
+    advancedCmd.outputHelp();
+  });
+advancedCmd._switchmanAdvanced = false;
+
+program
+  .command('demo')
+  .description('Create a throwaway repo that proves overlapping claims are blocked and safe landing works')
+  .option('--path <dir>', 'Directory to create the demo repo in')
+  .option('--cleanup', 'Delete the demo repo after the run finishes')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
 Examples:
   switchman demo
   switchman demo --path /tmp/switchman-demo
@@ -2508,12 +3600,16 @@ program
       }
 
       const mcpConfigWrites = installMcpConfig([...new Set([repoRoot, ...gitWorktrees.map((wt) => wt.path)])]);
+      const mcpExclude = ensureProjectLocalMcpGitExcludes(repoRoot);
 
       db.close();
       spinner.succeed(`Initialized in ${chalk.cyan(repoRoot)}`);
       console.log(chalk.dim(`  Found and registered ${gitWorktrees.length} git worktree(s)`));
       console.log(chalk.dim(`  Database: .switchman/switchman.db`));
       console.log(chalk.dim(`  MCP config: ${mcpConfigWrites.filter((result) => result.changed).length} file(s) written`));
+      if (mcpExclude.managed) {
+        console.log(chalk.dim(`  MCP excludes: ${mcpExclude.changed ? 'updated' : 'already set'} in .git/info/exclude`));
+      }
       console.log('');
       console.log(`Next steps:`);
       console.log(`  ${chalk.cyan('switchman task add "Fix the login bug"')}  — add a task`);
@@ -2533,6 +3629,8 @@ program
   .description('One-command setup: create agent workspaces and initialise Switchman')
   .option('-a, --agents <n>', 'Number of agent workspaces to create (default: 3)', '3')
   .option('--prefix <prefix>', 'Branch prefix (default: switchman)', 'switchman')
+  .option('--no-monitor', 'Do not start the background rogue-edit monitor')
+  .option('--monitor-interval-ms <ms>', 'Polling interval for the background monitor', '2000')
   .addHelpText('after', `
 Examples:
   switchman setup --agents 5
@@ -2546,6 +3644,24 @@ Examples:
       process.exit(1);
     }
 
+        if (agentCount > FREE_AGENT_LIMIT) {
+      const licence = await checkLicence();
+      if (!licence.valid) {
+        console.log('');
+        console.log(chalk.yellow(`  ⚠  Free tier supports up to ${FREE_AGENT_LIMIT} agents.`));
+        console.log('');
+        console.log(`  You requested ${chalk.cyan(agentCount)} agents — that requires ${chalk.bold('Switchman Pro')}.`);
+        console.log('');
+        console.log(`  ${chalk.dim('Upgrade at:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+        console.log(`  ${chalk.dim('Or run:   ')} ${chalk.cyan('switchman upgrade')}`);
+        console.log('');
+        process.exit(1);
+      }
+      if (licence.offline) {
+        console.log(chalk.dim(`  Pro licence verified (offline cache · ${Math.ceil((7 * 24 * 60 * 60 * 1000 - (Date.now() - (licence.cached_at ?? 0))) / (24 * 60 * 60 * 1000))}d remaining)`));
+      }
+    }
+
     const repoRoot = getRepo();
     const spinner = ora('Setting up Switchman...').start();
 
@@ -2591,6 +3707,12 @@ Examples:
       }
 
       const mcpConfigWrites = installMcpConfig([...new Set([repoRoot, ...created.map((wt) => wt.path)])]);
+      const mcpExclude = ensureProjectLocalMcpGitExcludes(repoRoot);
+
+      const monitorIntervalMs = Math.max(100, Number.parseInt(opts.monitorIntervalMs, 10) || 2000);
+      const monitorState = opts.monitor
+        ? startBackgroundMonitor(repoRoot, { intervalMs: monitorIntervalMs, quarantine: false })
+        : null;
 
       db.close();
 
@@ -2610,6 +3732,20 @@ Examples:
         const status = result.created ? 'created' : result.changed ? 'updated' : 'unchanged';
         console.log(`  ${chalk.green('✓')} ${chalk.cyan(result.path)} ${chalk.dim(`(${status})`)}`);
       }
+      if (mcpExclude.managed) {
+        console.log(`  ${chalk.green('✓')} ${chalk.cyan(mcpExclude.path)} ${chalk.dim(`(${mcpExclude.changed ? 'updated' : 'unchanged'})`)}`);
+      }
+
+      if (opts.monitor) {
+        console.log('');
+        console.log(chalk.bold('Monitor:'));
+        if (monitorState?.already_running) {
+          console.log(`  ${chalk.green('✓')} Background rogue-edit monitor already running ${chalk.dim(`(pid ${monitorState.state.pid})`)}`);
+        } else {
+          console.log(`  ${chalk.green('✓')} Started background rogue-edit monitor ${chalk.dim(`(pid ${monitorState?.state?.pid ?? 'unknown'})`)}`);
+        }
+        console.log(`    ${chalk.dim('interval:')} ${monitorIntervalMs}ms`);
+      }
 
       console.log('');
       console.log(chalk.bold('Next steps:'));
@@ -2618,6 +3754,13 @@ Examples:
       console.log(`  2. Open Claude Code or Cursor in the workspaces above — the local MCP config will attach Switchman automatically`);
       console.log(`  3. Keep the repo dashboard open while work starts:`);
       console.log(`     ${chalk.cyan('switchman status --watch')}`);
+      console.log(`  4. Run the final check and land finished work:`);
+      console.log(`     ${chalk.cyan('switchman gate ci')}`);
+      console.log(`     ${chalk.cyan('switchman queue run')}`);
+      if (opts.monitor) {
+        console.log(`  5. Watch for rogue edits or direct writes in real time:`);
+        console.log(`     ${chalk.cyan('switchman monitor status')}`);
+      }
       console.log('');
 
       const verification = collectSetupVerification(repoRoot);
@@ -2662,833 +3805,398 @@ Use this after setup or whenever editor/config wiring feels off.
     }, { homeDir: opts.home || null });
     if (!report.ok) process.exitCode = 1;
   });
+registerClaudeCommands(program, {
+  chalk,
+  existsSync,
+  getRepo,
+  join,
+  renderClaudeGuide,
+  writeFileSync,
+});
 
 
 // ── mcp ───────────────────────────────────────────────────────────────────────
 
-const mcpCmd = program.command('mcp').description('Manage editor connections for Switchman');
-const telemetryCmd = program.command('telemetry').description('Control anonymous opt-in telemetry for Switchman');
-
-telemetryCmd
-  .command('status')
-  .description('Show whether telemetry is enabled and where events would be sent')
-  .option('--home <path>', 'Override the home directory for telemetry config')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const config = loadTelemetryConfig(opts.home || undefined);
-    const runtime = getTelemetryRuntimeConfig();
-    const payload = {
-      enabled: config.telemetry_enabled === true,
-      configured: Boolean(runtime.apiKey) && !runtime.disabled,
-      install_id: config.telemetry_install_id,
-      destination: runtime.apiKey && !runtime.disabled ? runtime.host : null,
-      config_path: getTelemetryConfigPath(opts.home || undefined),
-    };
-
-    if (opts.json) {
-      console.log(JSON.stringify(payload, null, 2));
-      return;
-    }
-
-    console.log(`Telemetry: ${payload.enabled ? chalk.green('enabled') : chalk.yellow('disabled')}`);
-    console.log(`Configured destination: ${payload.configured ? chalk.cyan(payload.destination) : chalk.dim('not configured')}`);
-    console.log(`Config file: ${chalk.dim(payload.config_path)}`);
-    if (payload.install_id) {
-      console.log(`Install ID: ${chalk.dim(payload.install_id)}`);
-    }
-  });
-
-telemetryCmd
-  .command('enable')
-  .description('Enable anonymous telemetry for setup and operator workflows')
-  .option('--home <path>', 'Override the home directory for telemetry config')
-  .action((opts) => {
-    const runtime = getTelemetryRuntimeConfig();
-    if (!runtime.apiKey || runtime.disabled) {
-      printErrorWithNext('Telemetry destination is not configured. Set SWITCHMAN_TELEMETRY_API_KEY first.', 'switchman telemetry status');
-      process.exitCode = 1;
-      return;
-    }
-    const result = enableTelemetry(opts.home || undefined);
-    console.log(`${chalk.green('✓')} Telemetry enabled`);
-    console.log(`  ${chalk.dim(result.path)}`);
-  });
-
-telemetryCmd
-  .command('disable')
-  .description('Disable anonymous telemetry')
-  .option('--home <path>', 'Override the home directory for telemetry config')
-  .action((opts) => {
-    const result = disableTelemetry(opts.home || undefined);
-    console.log(`${chalk.green('✓')} Telemetry disabled`);
-    console.log(`  ${chalk.dim(result.path)}`);
-  });
-
-telemetryCmd
-  .command('test')
-  .description('Send one test telemetry event and report whether delivery succeeded')
-  .option('--home <path>', 'Override the home directory for telemetry config')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    const result = await sendTelemetryEvent('telemetry_test', {
-      app_version: program.version(),
-      os: process.platform,
-      node_version: process.version,
-      source: 'switchman-cli-test',
-    }, { homeDir: opts.home || undefined });
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-      if (!result.ok) process.exitCode = 1;
-      return;
-    }
+registerMcpCommands(program, {
+  chalk,
+  getWindsurfMcpConfigPath,
+  upsertWindsurfMcpConfig,
+});
+registerTelemetryCommands(program, {
+  chalk,
+  disableTelemetry,
+  enableTelemetry,
+  getTelemetryConfigPath,
+  getTelemetryRuntimeConfig,
+  loadTelemetryConfig,
+  printErrorWithNext,
+  sendTelemetryEvent,
+});
 
-    if (result.ok) {
-      console.log(`${chalk.green('✓')} Telemetry test event delivered`);
-      console.log(`  ${chalk.dim('destination:')} ${chalk.cyan(result.destination)}`);
-      if (result.status) {
-        console.log(`  ${chalk.dim('status:')} ${result.status}`);
-      }
-      return;
-    }
 
-    printErrorWithNext(`Telemetry test failed (${result.reason || 'unknown_error'}).`, 'switchman telemetry status');
-    console.log(`  ${chalk.dim('destination:')} ${result.destination || 'unknown'}`);
-    if (result.status) {
-      console.log(`  ${chalk.dim('status:')} ${result.status}`);
-    }
-    if (result.error) {
-      console.log(`  ${chalk.dim('error:')} ${result.error}`);
-    }
-    process.exitCode = 1;
-  });
+// ── plan ──────────────────────────────────────────────────────────────────────
 
-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)')
+program
+  .command('plan [goal]')
+  .description('Pro: suggest a parallel task plan from an explicit goal or GitHub issue')
+  .option('--issue <number>', 'Read planning context from a GitHub issue via gh')
+  .option('--pr <number>', 'Post the resulting plan summary to a GitHub pull request')
+  .option('--comment', 'Post a GitHub comment with the created plan summary after --apply')
+  .option('--gh-command <command>', 'Executable to use for GitHub CLI', 'gh')
+  .option('--apply', 'Create the suggested tasks in Switchman')
+  .option('--max-tasks <n>', 'Maximum number of suggested tasks', '6')
   .option('--json', 'Output raw JSON')
   .addHelpText('after', `
 Examples:
-  switchman mcp install --windsurf
-  switchman mcp install --windsurf --json
+  switchman plan "Add authentication"
+  switchman plan --issue 47
+  switchman plan "Add authentication" --apply
+  switchman plan --issue 47 --apply --comment
 `)
-  .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 list');
-taskCmd.addHelpText('after', `
-Examples:
-  switchman task add "Fix login bug" --priority 8
-  switchman task list --status pending
-  switchman task done task-123
-`);
-
-taskCmd
-  .command('add <title>')
-  .description('Add a new task to the queue')
-  .option('-d, --description <desc>', 'Task description')
-  .option('-p, --priority <n>', 'Priority 1-10 (default 5)', '5')
-  .option('--id <id>', 'Custom task ID')
-  .action((title, opts) => {
+  .action(async (goal, opts) => {
     const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const taskId = createTask(db, {
-      id: opts.id,
-      title,
-      description: opts.description,
-      priority: parseInt(opts.priority),
-    });
-    db.close();
-    const scopeWarning = analyzeTaskScope(title, opts.description || '');
-    console.log(`${chalk.green('✓')} Task created: ${chalk.cyan(taskId)}`);
-    console.log(`  ${chalk.dim(title)}`);
-    if (scopeWarning) {
-      console.log(chalk.yellow(`  warning: ${scopeWarning.summary}`));
-      console.log(chalk.yellow(`  next: ${scopeWarning.next_step}`));
-      console.log(chalk.cyan(`  try: ${scopeWarning.command}`));
-    }
-  });
-
-taskCmd
-  .command('list')
-  .description('List all tasks')
-  .option('-s, --status <status>', 'Filter by status (pending|in_progress|done|failed)')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const tasks = listTasks(db, opts.status);
-    db.close();
-
-    if (!tasks.length) {
-      console.log(chalk.dim('No tasks found.'));
-      return;
-    }
-
-    console.log('');
-    for (const t of tasks) {
-      const badge = statusBadge(t.status);
-      const worktree = t.worktree ? chalk.cyan(t.worktree) : chalk.dim('unassigned');
-      console.log(`${badge} ${chalk.bold(t.title)}`);
-      console.log(`  ${chalk.dim('id:')} ${t.id}  ${chalk.dim('worktree:')} ${worktree}  ${chalk.dim('priority:')} ${t.priority}`);
-      if (t.description) console.log(`  ${chalk.dim(t.description)}`);
-      console.log('');
-    }
-  });
-
-taskCmd
-  .command('assign <taskId> <worktree>')
-  .description('Assign a task to a workspace (compatibility shim for lease acquire)')
-  .option('--agent <name>', 'Agent name (e.g. claude-code)')
-  .action((taskId, worktree, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const lease = startTaskLease(db, taskId, worktree, opts.agent);
-    db.close();
-    if (lease) {
-      console.log(`${chalk.green('✓')} Assigned ${chalk.cyan(taskId)} → ${chalk.cyan(worktree)} (${chalk.dim(lease.id)})`);
-    } else {
-      console.log(chalk.red(`Could not assign task. It may not exist or is not in 'pending' status.`));
-    }
-  });
-
-taskCmd
-  .command('retry <taskId>')
-  .description('Return a failed or stale completed task to pending so it can be revalidated')
-  .option('--reason <text>', 'Reason to record for the retry')
-  .option('--json', 'Output raw JSON')
-  .action((taskId, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const task = retryTask(db, taskId, opts.reason || 'manual retry');
-    db.close();
-
-    if (!task) {
-      printErrorWithNext(`Task ${taskId} is not retryable.`, 'switchman task list --status failed');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(task, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Reset ${chalk.cyan(task.id)} to pending`);
-    console.log(`  ${chalk.dim('title:')} ${task.title}`);
-    console.log(`${chalk.yellow('next:')} switchman task assign ${task.id} <workspace>`);
-  });
-
-taskCmd
-  .command('retry-stale')
-  .description('Return all currently stale tasks to pending so they can be revalidated together')
-  .option('--pipeline <id>', 'Only retry stale tasks for one pipeline')
-  .option('--reason <text>', 'Reason to record for the retry', 'bulk stale retry')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const result = retryStaleTasks(db, {
-      pipelineId: opts.pipeline || null,
-      reason: opts.reason,
-    });
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    if (result.retried.length === 0) {
-      const scope = result.pipeline_id ? ` for ${result.pipeline_id}` : '';
-      console.log(chalk.dim(`No stale tasks to retry${scope}.`));
-      return;
-    }
+    const db = getOptionalDb(repoRoot);
 
-    console.log(`${chalk.green('✓')} Reset ${result.retried.length} stale task(s) to pending`);
-    if (result.pipeline_id) {
-      console.log(`  ${chalk.dim('pipeline:')} ${result.pipeline_id}`);
-    }
-    console.log(`  ${chalk.dim('tasks:')} ${result.retried.map((task) => task.id).join(', ')}`);
-    console.log(`${chalk.yellow('next:')} switchman status`);
-  });
-
-taskCmd
-  .command('done <taskId>')
-  .description('Mark a task as complete and release all file claims')
-  .action((taskId) => {
-    const repoRoot = getRepo();
     try {
-      completeTaskWithRetries(repoRoot, taskId);
-      console.log(`${chalk.green('✓')} Task ${chalk.cyan(taskId)} marked done — file claims released`);
-    } catch (err) {
-      console.error(chalk.red(err.message));
-      process.exitCode = 1;
-    }
-  });
-
-taskCmd
-  .command('fail <taskId> [reason]')
-  .description('Mark a task as failed')
-  .action((taskId, reason) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    failTask(db, taskId, reason);
-    releaseFileClaims(db, taskId);
-    db.close();
-    console.log(`${chalk.red('✗')} Task ${chalk.cyan(taskId)} marked failed`);
-  });
-
-taskCmd
-  .command('next')
-  .description('Get the next pending task quickly (use `lease next` for the full workflow)')
-  .option('--json', 'Output as JSON')
-  .option('--worktree <name>', 'Workspace to assign the task to (defaults to the current folder name)')
-  .option('--agent <name>', 'Agent identifier for logging (e.g. claude-code)')
-  .addHelpText('after', `
-Examples:
-  switchman task next
-  switchman task next --json
-`)
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const worktreeName = getCurrentWorktreeName(opts.worktree);
-    const { task, lease, exhausted } = acquireNextTaskLeaseWithRetries(repoRoot, worktreeName, opts.agent || null);
-
-    if (!task) {
-      if (opts.json) console.log(JSON.stringify({ task: null }));
-      else if (exhausted) console.log(chalk.dim('No pending tasks.'));
-      else console.log(chalk.yellow('Tasks were claimed by other agents during assignment. Run again to get the next one.'));
-      return;
-    }
-
-    if (!lease) {
-      if (opts.json) console.log(JSON.stringify({ task: null, message: 'Task claimed by another agent — try again' }));
-      else console.log(chalk.yellow('Task was just claimed by another agent. Run again to get the next one.'));
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(taskJsonWithLease(task, worktreeName, lease), null, 2));
-    } else {
-      console.log(`${chalk.green('✓')} Assigned: ${chalk.bold(task.title)}`);
-      console.log(`  ${chalk.dim('id:')} ${task.id}  ${chalk.dim('worktree:')} ${chalk.cyan(worktreeName)}  ${chalk.dim('lease:')} ${chalk.dim(lease.id)}  ${chalk.dim('priority:')} ${task.priority}`);
-    }
-  });
-
-// ── queue ─────────────────────────────────────────────────────────────────────
-
-const queueCmd = program.command('queue').alias('land').description('Land finished work safely back onto main, one item at a time');
-queueCmd.addHelpText('after', `
-Examples:
-  switchman queue add --worktree agent1
-  switchman queue status
-  switchman queue run --watch
-`);
-
-queueCmd
-  .command('add [branch]')
-  .description('Add a branch, workspace, or pipeline to the landing queue')
-  .option('--worktree <name>', 'Queue a registered workspace by name')
-  .option('--pipeline <pipelineId>', 'Queue a pipeline by id')
-  .option('--target <branch>', 'Target branch to merge into', 'main')
-  .option('--max-retries <n>', 'Maximum automatic retries', '1')
-  .option('--submitted-by <name>', 'Operator or automation name')
-  .option('--json', 'Output raw JSON')
-  .addHelpText('after', `
-Examples:
-  switchman queue add feature/auth-hardening
-  switchman queue add --worktree agent2
-  switchman queue add --pipeline pipe-123
-
-Pipeline landing rule:
-  switchman queue add --pipeline <id>
-  lands the pipeline's inferred landing branch.
-  If completed work spans multiple branches, Switchman creates one synthetic landing branch first.
-`)
-  .action(async (branch, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
+      const licence = await checkLicence();
+      if (!licence.valid) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  AI planning requires Switchman Pro.'));
+        console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman upgrade')}`);
+        console.log(`  ${chalk.dim('Or visit:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
+      }
 
-    try {
-      let payload;
-      if (opts.worktree) {
-        const worktree = listWorktrees(db).find((entry) => entry.name === opts.worktree);
-        if (!worktree) {
-          throw new Error(`Workspace ${opts.worktree} is not registered.`);
-        }
-        payload = {
-          sourceType: 'worktree',
-          sourceRef: worktree.branch,
-          sourceWorktree: worktree.name,
-          targetBranch: opts.target,
-          maxRetries: opts.maxRetries,
-          submittedBy: opts.submittedBy || null,
-        };
-      } else if (opts.pipeline) {
-        const policyGate = await evaluatePipelinePolicyGate(db, repoRoot, opts.pipeline);
-        if (!policyGate.ok) {
-          throw new Error(`${policyGate.summary} Next: ${policyGate.next_action}`);
+      let issueContext = null;
+      if (opts.issue) {
+        try {
+          issueContext = fetchGitHubIssueContext(repoRoot, opts.issue, opts.ghCommand);
+        } catch (err) {
+          printErrorWithNext(err.message, 'switchman plan "Add authentication"');
+          process.exitCode = 1;
+          return;
         }
-        const landingTarget = preparePipelineLandingTarget(db, repoRoot, opts.pipeline, {
-          baseBranch: opts.target || 'main',
-          requireCompleted: true,
-          allowCurrentBranchFallback: false,
-        });
-        payload = {
-          sourceType: 'pipeline',
-          sourceRef: landingTarget.branch,
-          sourcePipelineId: opts.pipeline,
-          sourceWorktree: landingTarget.worktree || null,
-          targetBranch: opts.target,
-          maxRetries: opts.maxRetries,
-          submittedBy: opts.submittedBy || null,
-          eventDetails: policyGate.override_applied
-            ? {
-              policy_override_summary: policyGate.override_summary,
-              overridden_task_types: policyGate.policy_state?.overridden_task_types || [],
-            }
-            : null,
-        };
-      } else if (branch) {
-        payload = {
-          sourceType: 'branch',
-          sourceRef: branch,
-          targetBranch: opts.target,
-          maxRetries: opts.maxRetries,
-          submittedBy: opts.submittedBy || null,
-        };
-      } else {
-        throw new Error('Choose one source to land: a branch name, `--worktree`, or `--pipeline`.');
       }
 
-      const result = enqueueMergeItem(db, payload);
-      db.close();
-
-      if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
+      if ((!goal || !goal.trim()) && !issueContext) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  AI planning currently requires an explicit goal.'));
+        console.log(`  ${chalk.dim('Try:')} ${chalk.cyan('switchman plan "Add authentication"')}`);
+        console.log(`  ${chalk.dim('Or:  ')} ${chalk.cyan('switchman plan --issue 47')}`);
+        console.log(`  ${chalk.dim('Then:')} ${chalk.cyan('switchman plan "Add authentication" --apply')}`);
+        console.log('');
+        process.exitCode = 1;
         return;
       }
 
-      console.log(`${chalk.green('✓')} Queued ${chalk.cyan(result.id)} for ${chalk.bold(result.target_branch)}`);
-      console.log(`  ${chalk.dim('source:')} ${result.source_type} ${result.source_ref}`);
-      if (result.source_worktree) console.log(`  ${chalk.dim('worktree:')} ${result.source_worktree}`);
-      if (payload.eventDetails?.policy_override_summary) {
-        console.log(`  ${chalk.dim('policy override:')} ${payload.eventDetails.policy_override_summary}`);
-      }
-    } catch (err) {
-      db.close();
-      printErrorWithNext(err.message, 'switchman queue add --help');
-      process.exitCode = 1;
-    }
-  });
-
-queueCmd
-  .command('list')
-  .description('List merge queue items')
-  .option('--status <status>', 'Filter by queue status')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const items = listMergeQueue(db, { status: opts.status || null });
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(items, null, 2));
-      return;
-    }
-
-    if (items.length === 0) {
-      console.log(chalk.dim('Merge queue is empty.'));
-      return;
-    }
-
-    for (const item of items) {
-      const retryInfo = chalk.dim(`retries:${item.retry_count}/${item.max_retries}`);
-      const attemptInfo = item.last_attempt_at ? ` ${chalk.dim(`last-attempt:${item.last_attempt_at}`)}` : '';
-      const backoffInfo = item.backoff_until ? ` ${chalk.dim(`backoff-until:${item.backoff_until}`)}` : '';
-      const escalationInfo = item.escalated_at ? ` ${chalk.dim(`escalated:${item.escalated_at}`)}` : '';
-      console.log(`  ${statusBadge(item.status)} ${item.id} ${item.source_type}:${item.source_ref} ${chalk.dim(`→ ${item.target_branch}`)} ${retryInfo}${attemptInfo}${backoffInfo}${escalationInfo}`);
-      if (item.last_error_summary) {
-        console.log(`    ${chalk.red('why:')} ${item.last_error_summary}`);
-      }
-      if (item.next_action) {
-        console.log(`    ${chalk.yellow('next:')} ${item.next_action}`);
+      if (opts.comment && !opts.apply) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  GitHub plan comments are only posted after task creation.'));
+        console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman plan --apply --comment')}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
       }
-    }
-  });
-
-queueCmd
-  .command('status')
-  .description('Show an operator-friendly merge queue summary')
-  .option('--json', 'Output raw JSON')
-  .addHelpText('after', `
-Plain English:
-  Use this when finished branches are waiting to land and you want one safe queue view.
-
-Examples:
-  switchman queue status
-  switchman queue status --json
-
-What it helps you answer:
-  - what lands next
-  - what is blocked
-  - what command should I run now
-`)
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const items = listMergeQueue(db);
-    const summary = buildQueueStatusSummary(items, { db, repoRoot });
-    const recentEvents = items.slice(0, 5).flatMap((item) =>
-      listMergeQueueEvents(db, item.id, { limit: 3 }).map((event) => ({ ...event, queue_item_id: item.id })),
-    ).sort((a, b) => b.id - a.id).slice(0, 8);
-    db.close();
 
-    if (opts.json) {
-      console.log(JSON.stringify({ items, summary, recent_events: recentEvents }, null, 2));
-      return;
-    }
-
-    const queueHealth = summary.counts.blocked > 0
-      ? 'block'
-      : summary.counts.retrying > 0 || summary.counts.held > 0 || summary.counts.wave_blocked > 0 || summary.counts.escalated > 0
-        ? 'warn'
-        : 'healthy';
-    const queueHealthColor = colorForHealth(queueHealth);
-    const retryingItems = items.filter((item) => item.status === 'retrying');
-    const focus = summary.blocked[0] || retryingItems[0] || summary.next || null;
-    const focusLine = focus
-      ? `${focus.id} ${focus.source_type}:${focus.source_ref}${focus.last_error_summary ? ` ${chalk.dim(`• ${focus.last_error_summary}`)}` : ''}`
-      : 'Nothing waiting. Landing queue is clear.';
+      if (opts.comment && !opts.pr && !issueContext) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  Choose where to post the plan summary.'));
+        console.log(`  ${chalk.dim('Use:')} ${chalk.cyan('switchman plan --issue 47 --apply --comment')}`);
+        console.log(`  ${chalk.dim('Or: ')} ${chalk.cyan('switchman plan "Add authentication" --pr 123 --apply --comment')}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
+      }
 
-    console.log('');
-    console.log(queueHealthColor('='.repeat(72)));
-    console.log(`${queueHealthColor(healthLabel(queueHealth))} ${chalk.bold('switchman queue status')} ${chalk.dim('• landing mission control')}`);
-    console.log(queueHealthColor('='.repeat(72)));
-    console.log(renderSignalStrip([
-      renderChip('queued', summary.counts.queued, summary.counts.queued > 0 ? chalk.yellow : chalk.green),
-      renderChip('retrying', summary.counts.retrying, summary.counts.retrying > 0 ? chalk.yellow : chalk.green),
-      renderChip('held', summary.counts.held, summary.counts.held > 0 ? chalk.yellow : chalk.green),
-      renderChip('wave blocked', summary.counts.wave_blocked, summary.counts.wave_blocked > 0 ? chalk.yellow : chalk.green),
-      renderChip('escalated', summary.counts.escalated, summary.counts.escalated > 0 ? chalk.red : chalk.green),
-      renderChip('blocked', summary.counts.blocked, summary.counts.blocked > 0 ? chalk.red : chalk.green),
-      renderChip('merging', summary.counts.merging, summary.counts.merging > 0 ? chalk.blue : chalk.green),
-      renderChip('merged', summary.counts.merged, summary.counts.merged > 0 ? chalk.green : chalk.white),
-    ]));
-    console.log(renderMetricRow([
-      { label: 'items', value: items.length, color: chalk.white },
-      { label: 'validating', value: summary.counts.validating, color: chalk.blue },
-      { label: 'rebasing', value: summary.counts.rebasing, color: chalk.blue },
-      { label: 'target', value: summary.next?.target_branch || 'main', color: chalk.cyan },
-    ]));
-    console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+      const context = collectPlanContext(repoRoot, goal || null, issueContext);
+      const planningWorktrees = resolvePlanningWorktrees(repoRoot, db);
+      const pipelineId = `plan-${slugifyValue(context.title)}-${Date.now().toString(36)}`;
+      const plannedTasks = planPipelineTasks({
+        pipelineId,
+        title: context.title,
+        description: context.description,
+        worktrees: planningWorktrees,
+        maxTasks: Math.max(1, parseInt(opts.maxTasks, 10) || 6),
+        repoRoot,
+      });
 
-    const queueFocusLines = summary.next
-      ? [
-        `${renderChip(summary.next.recommendation?.action === 'retry' ? 'RETRY' : summary.next.recommendation?.action === 'escalate' ? 'ESCALATE' : 'NEXT', summary.next.id, summary.next.recommendation?.action === 'retry' ? chalk.yellow : summary.next.recommendation?.action === 'escalate' ? chalk.red : chalk.green)} ${summary.next.source_type}:${summary.next.source_ref} ${chalk.dim(`retries:${summary.next.retry_count}/${summary.next.max_retries}`)}${summary.next.queue_assessment?.goal_priority ? ` ${chalk.dim(`priority:${summary.next.queue_assessment.goal_priority}`)}` : ''}${summary.next.queue_assessment?.integration_risk && summary.next.queue_assessment.integration_risk !== 'normal' ? ` ${chalk.dim(`risk:${summary.next.queue_assessment.integration_risk}`)}` : ''}${summary.next.queue_assessment?.freshness ? ` ${chalk.dim(`freshness:${summary.next.queue_assessment.freshness}`)}` : ''}${summary.next.queue_assessment?.stale_invalidation_count ? ` ${chalk.dim(`stale:${summary.next.queue_assessment.stale_invalidation_count}`)}` : ''}`,
-        ...(summary.next.queue_assessment?.reason ? [`  ${chalk.dim('why next:')} ${summary.next.queue_assessment.reason}`] : []),
-        ...(summary.next.recommendation?.summary ? [`  ${chalk.dim('decision:')} ${summary.next.recommendation.summary}`] : []),
-        `  ${chalk.yellow('run:')} ${summary.next.recommendation?.command || 'switchman queue run'}`,
-      ]
-      : [chalk.dim('No queued landing work right now.')];
-
-    const queueHeldBackLines = summary.held_back.length > 0
-      ? summary.held_back.flatMap((item) => {
-        const lines = [`${renderChip(item.recommendation?.action === 'escalate' ? 'ESCALATE' : 'HOLD', item.id, item.recommendation?.action === 'escalate' ? chalk.red : chalk.yellow)} ${item.source_type}:${item.source_ref}${item.queue_assessment?.goal_priority ? ` ${chalk.dim(`priority:${item.queue_assessment.goal_priority}`)}` : ''} ${chalk.dim(`freshness:${item.queue_assessment?.freshness || 'unknown'}`)}${item.queue_assessment?.integration_risk && item.queue_assessment.integration_risk !== 'normal' ? ` ${chalk.dim(`risk:${item.queue_assessment.integration_risk}`)}` : ''}${item.queue_assessment?.stale_invalidation_count ? ` ${chalk.dim(`stale:${item.queue_assessment.stale_invalidation_count}`)}` : ''}`];
-        if (item.queue_assessment?.reason) lines.push(`  ${chalk.dim('why later:')} ${item.queue_assessment.reason}`);
-        if (item.recommendation?.summary) lines.push(`  ${chalk.dim('decision:')} ${item.recommendation.summary}`);
-        if (item.queue_assessment?.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.queue_assessment.next_action}`);
-        return lines;
-      })
-      : [chalk.green('Nothing significant is being held back.')];
+      if (opts.json) {
+        const payload = {
+          title: context.title,
+          context: {
+            found: context.found,
+            used: context.used,
+            branch: context.branch,
+          },
+          planned_tasks: plannedTasks.map((task) => ({
+            id: task.id,
+            title: task.title,
+            suggested_worktree: task.suggested_worktree || null,
+            task_type: task.task_spec?.task_type || null,
+            dependencies: task.dependencies || [],
+          })),
+          apply_ready: Boolean(db),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
 
-    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.')];
+      console.log(chalk.bold('Reading repo context...'));
+      if (context.found.length > 0) {
+        console.log(`${chalk.dim('Found:')} ${context.found.join(', ')}`);
+      } else {
+        console.log(chalk.dim('Found: local repo context only'));
+      }
+      console.log('');
+      console.log(`${chalk.bold('Suggested plan based on:')} ${context.used.length > 0 ? formatHumanList(context.used) : 'available repo context'}`);
+      console.log('');
 
-    const queueWatchLines = items.filter((item) => ['retrying', 'held', 'wave_blocked', 'escalated', 'merging', 'rebasing', 'validating'].includes(item.status)).length > 0
-      ? items
-        .filter((item) => ['retrying', 'held', 'wave_blocked', 'escalated', 'merging', 'rebasing', 'validating'].includes(item.status))
-        .slice(0, 4)
-        .flatMap((item) => {
-          const lines = [`${renderChip(item.status.toUpperCase(), item.id, item.status === 'retrying' || item.status === 'held' || item.status === 'wave_blocked' ? chalk.yellow : item.status === 'escalated' ? chalk.red : chalk.blue)} ${item.source_type}:${item.source_ref}`];
-          if (item.last_error_summary) lines.push(`  ${chalk.dim(item.last_error_summary)}`);
-          if (item.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.next_action}`);
-          return lines;
-        })
-      : [chalk.green('No in-flight queue items right now.')];
+      plannedTasks.forEach((task, index) => {
+        const worktreeLabel = task.suggested_worktree ? chalk.cyan(task.suggested_worktree) : chalk.dim('unassigned');
+        console.log(`  ${chalk.green('✓')} ${chalk.bold(`${index + 1}.`)} ${task.title}  ${chalk.dim('→')} ${worktreeLabel}`);
+      });
 
-    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}`] : []),
-    ];
+      if (!opts.apply) {
+        console.log('');
+        if (!db) {
+          console.log(chalk.dim('Preview only — run `switchman setup --agents 3` first if you want Switchman to create and track these tasks.'));
+        } else {
+          console.log(chalk.dim('Preview only — rerun with `switchman plan --apply` to create these tasks.'));
+        }
+        return;
+      }
 
-    const queuePlanLines = [
-      ...(summary.plan?.land_now?.slice(0, 2).map((item) => `${renderChip('LAND NOW', item.item_id, chalk.green)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-      ...(summary.plan?.prepare_next?.slice(0, 2).map((item) => `${renderChip('PREP NEXT', item.item_id, chalk.cyan)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-      ...(summary.plan?.unblock_first?.slice(0, 2).map((item) => `${renderChip('UNBLOCK', item.item_id, chalk.yellow)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-      ...(summary.plan?.escalate?.slice(0, 2).map((item) => `${renderChip('ESCALATE', item.item_id, chalk.red)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-      ...(summary.plan?.defer?.slice(0, 2).map((item) => `${renderChip('DEFER', item.item_id, chalk.white)} ${item.source_type}:${item.source_ref} ${chalk.dim(item.summary)}`) || []),
-    ];
-    const queueSequenceLines = summary.recommended_sequence?.length > 0
-      ? summary.recommended_sequence.map((item) => `${chalk.bold(`${item.stage}.`)} ${item.source_type}:${item.source_ref} ${chalk.dim(`[${item.lane}]`)} ${item.summary}`)
-      : [chalk.green('No recommended sequence beyond the current landing focus.')];
+      if (!db) {
+        console.log('');
+        console.log(`${chalk.red('✗')} Switchman is not set up in this repo yet.`);
+        console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman setup --agents 3')}`);
+        process.exitCode = 1;
+        return;
+      }
 
-    console.log('');
-    for (const block of [
-      renderPanel('Landing focus', queueFocusLines, chalk.green),
-      renderPanel('Recommended sequence', queueSequenceLines, summary.recommended_sequence?.length > 0 ? chalk.cyan : chalk.green),
-      renderPanel('Queue plan', queuePlanLines.length > 0 ? queuePlanLines : [chalk.green('Nothing else needs planning right now.')], queuePlanLines.length > 0 ? chalk.cyan : chalk.green),
-      renderPanel('Held back', queueHeldBackLines, summary.held_back.length > 0 ? chalk.yellow : chalk.green),
-      renderPanel('Blocked', queueBlockedLines, summary.counts.blocked > 0 ? chalk.red : chalk.green),
-      renderPanel('In flight', queueWatchLines, queueWatchLines[0] === 'No in-flight queue items right now.' ? chalk.green : chalk.blue),
-      renderPanel('Next commands', queueCommandLines, chalk.cyan),
-    ]) {
-      for (const line of block) console.log(line);
       console.log('');
-    }
+      for (const task of plannedTasks) {
+        createTask(db, {
+          id: task.id,
+          title: task.title,
+          description: `Planned from: ${context.title}`,
+          priority: planTaskPriority(task.task_spec),
+        });
+        upsertTaskSpec(db, task.id, task.task_spec);
+        console.log(`  ${chalk.green('✓')} Created ${chalk.cyan(task.id)} ${chalk.dim(task.title)}`);
+      }
 
-    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());
+      console.log('');
+      console.log(`${chalk.green('✓')} Planned ${plannedTasks.length} task(s) from repo context.`);
+      if (opts.comment) {
+        const commentBody = buildPlanningCommentBody(context, plannedTasks);
+        const commentResult = postPlanningSummaryComment(repoRoot, {
+          ghCommand: opts.ghCommand,
+          issueNumber: issueContext?.number || null,
+          prNumber: opts.pr || null,
+          body: commentBody,
+        });
+        const targetLabel = commentResult.target_type === 'pr'
+          ? `PR #${commentResult.target_number}`
+          : `issue #${commentResult.target_number}`;
+        console.log(`  ${chalk.green('✓')} Posted plan summary to ${chalk.cyan(targetLabel)}.`);
       }
+      console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman status --watch')}`);
+    } finally {
+      db?.close();
     }
   });
 
-queueCmd
-  .command('run')
-  .description('Process landing-queue items one at a time')
-  .option('--max-items <n>', 'Maximum queue items to process', '1')
-  .option('--follow-plan', 'Only run queue items that are currently in the land_now lane')
-  .option('--merge-budget <n>', 'Maximum successful merges to allow in this run')
-  .option('--target <branch>', 'Default target branch', 'main')
-  .option('--watch', 'Keep polling for new queue items')
-  .option('--watch-interval-ms <n>', 'Polling interval for --watch mode', '1000')
-  .option('--max-cycles <n>', 'Maximum watch cycles before exiting (mainly for tests)')
+
+// ── task ──────────────────────────────────────────────────────────────────────
+
+registerTaskCommands(program, {
+  acquireNextTaskLeaseWithRetries,
+  analyzeTaskScope,
+  chalk,
+  completeTaskWithRetries,
+  createTask,
+  failTask,
+  getCurrentWorktreeName,
+  getDb,
+  getRepo,
+  listTasks,
+  printErrorWithNext,
+  pushSyncEvent,
+  releaseFileClaims,
+  retryStaleTasks,
+  retryTask,
+  startTaskLease,
+  statusBadge,
+  taskJsonWithLease,
+});
+
+// ── queue ─────────────────────────────────────────────────────────────────────
+
+registerQueueCommands(program, {
+  buildQueueStatusSummary,
+  chalk,
+  colorForHealth,
+  escalateMergeQueueItem,
+  enqueueMergeItem,
+  evaluatePipelinePolicyGate,
+  getDb,
+  getRepo,
+  healthLabel,
+  listMergeQueue,
+  listMergeQueueEvents,
+  listWorktrees,
+  maybeCaptureTelemetry,
+  preparePipelineLandingTarget,
+  printErrorWithNext,
+  pushSyncEvent,
+  renderChip,
+  renderMetricRow,
+  renderPanel,
+  renderSignalStrip,
+  removeMergeQueueItem,
+  retryMergeQueueItem,
+  runMergeQueue,
+  sleepSync,
+  statusBadge,
+});
+
+program
+  .command('merge')
+  .description('Queue finished worktrees and land safe work through one guided front door')
+  .option('--target <branch>', 'Target branch to merge into', 'main')
+  .option('--dry-run', 'Preview mergeable work without queueing or landing anything')
   .option('--json', 'Output raw JSON')
   .addHelpText('after', `
 Examples:
-  switchman queue run
-  switchman queue run --follow-plan --merge-budget 2
-  switchman queue run --watch
-  switchman queue run --watch --watch-interval-ms 1000
+  switchman merge
+  switchman merge --dry-run
+  switchman merge --target release
 `)
   .action(async (opts) => {
     const repoRoot = getRepo();
+    const db = getDb(repoRoot);
 
     try {
-      const watch = Boolean(opts.watch);
-      const followPlan = Boolean(opts.followPlan);
-      const watchIntervalMs = Math.max(0, Number.parseInt(opts.watchIntervalMs, 10) || 1000);
-      const maxCycles = opts.maxCycles ? Math.max(1, Number.parseInt(opts.maxCycles, 10) || 1) : null;
-      const mergeBudget = opts.mergeBudget !== undefined
-        ? Math.max(0, Number.parseInt(opts.mergeBudget, 10) || 0)
-        : null;
-      const aggregate = {
-        processed: [],
-        cycles: 0,
-        watch,
-        execution_policy: {
-          follow_plan: followPlan,
-          merge_budget: mergeBudget,
-          merged_count: 0,
-        },
-      };
+      const discovery = discoverMergeCandidates(db, repoRoot, { targetBranch: opts.target || 'main' });
+      const queued = [];
 
-      while (true) {
-        const db = getDb(repoRoot);
-        const result = await runMergeQueue(db, repoRoot, {
-          maxItems: Number.parseInt(opts.maxItems, 10) || 1,
+      for (const entry of discovery.eligible) {
+        queued.push(enqueueMergeItem(db, {
+          sourceType: 'worktree',
+          sourceRef: entry.branch,
+          sourceWorktree: entry.worktree,
           targetBranch: opts.target || 'main',
-          followPlan,
-          mergeBudget,
-        });
-        db.close();
-
-        aggregate.processed.push(...result.processed);
-        aggregate.summary = result.summary;
-        aggregate.deferred = result.deferred || aggregate.deferred || null;
-        aggregate.execution_policy = result.execution_policy || aggregate.execution_policy;
-        aggregate.cycles += 1;
-
-        if (!watch) break;
-        if (maxCycles && aggregate.cycles >= maxCycles) break;
-        if (mergeBudget !== null && aggregate.execution_policy.merged_count >= mergeBudget) break;
-        if (result.processed.length === 0) {
-          sleepSync(watchIntervalMs);
-        }
+          submittedBy: 'switchman merge',
+        }));
       }
 
-      if (opts.json) {
-        console.log(JSON.stringify(aggregate, null, 2));
-        return;
-      }
+      const queueItems = listMergeQueue(db);
+      const summary = buildQueueStatusSummary(queueItems, { db, repoRoot });
+      const mergeOrder = summary.recommended_sequence
+        .filter((item) => ['land_now', 'prepare_next'].includes(item.lane))
+        .map((item) => item.source_ref);
 
-      if (aggregate.processed.length === 0) {
-        const deferredFocus = aggregate.deferred || aggregate.summary?.next || null;
-        if (deferredFocus?.recommendation?.action) {
-          console.log(chalk.yellow('No landing candidate is ready to run right now.'));
-          console.log(`  ${chalk.dim('focus:')} ${deferredFocus.id} ${deferredFocus.source_type}:${deferredFocus.source_ref}`);
-          if (followPlan) {
-            console.log(`  ${chalk.dim('policy:')} following the queue plan, so only land_now items will run automatically`);
-          }
-          if (deferredFocus.recommendation?.summary) {
-            console.log(`  ${chalk.dim('decision:')} ${deferredFocus.recommendation.summary}`);
-          }
-          if (deferredFocus.recommendation?.command) {
-            console.log(`  ${chalk.yellow('next:')} ${deferredFocus.recommendation.command}`);
-          }
-        } else {
-          console.log(chalk.dim('No queued merge items.'));
+      if (opts.json) {
+        if (opts.dryRun) {
+          console.log(JSON.stringify({ discovery, queued, summary, merge_order: mergeOrder, dry_run: true }, null, 2));
+          db.close();
+          return;
         }
-        await maybeCaptureTelemetry('queue_used', {
-          watch,
-          cycles: aggregate.cycles,
-          processed_count: 0,
-          merged_count: 0,
-          blocked_count: 0,
-        });
+
+        const gate = await evaluateQueueRepoGate(db, repoRoot);
+        const runnableCount = listMergeQueue(db).filter((item) => ['queued', 'retrying'].includes(item.status)).length;
+        const result = gate.ok
+          ? await runMergeQueue(db, repoRoot, {
+            targetBranch: opts.target || 'main',
+            maxItems: Math.max(1, runnableCount),
+            mergeBudget: Math.max(1, runnableCount),
+            followPlan: false,
+          })
+          : null;
+        console.log(JSON.stringify({ discovery, queued, summary, merge_order: mergeOrder, gate, result }, null, 2));
+        db.close();
         return;
       }
 
-      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}`);
+      printMergeDiscovery(discovery);
+
+      if (discovery.blocked.length > 0) {
+        console.log('');
+        console.log(chalk.bold('Needs attention before landing:'));
+        for (const entry of discovery.blocked) {
+          console.log(`  ${chalk.yellow(entry.worktree)}: ${entry.summary}`);
+          console.log(`    ${chalk.dim('run:')} ${chalk.cyan(entry.command)}`);
         }
       }
 
-      if (aggregate.execution_policy.follow_plan) {
-        console.log(`${chalk.dim('plan-aware run:')} merged ${aggregate.execution_policy.merged_count}${aggregate.execution_policy.merge_budget !== null ? ` of ${aggregate.execution_policy.merge_budget}` : ''} budgeted item(s)`);
+      if (mergeOrder.length > 0) {
+        console.log('');
+        console.log(`${chalk.bold('Merge order:')} ${mergeOrder.join(' → ')}`);
       }
 
-      await maybeCaptureTelemetry('queue_used', {
-        watch,
-        cycles: aggregate.cycles,
-        processed_count: aggregate.processed.length,
-        merged_count: aggregate.processed.filter((entry) => entry.status === 'merged').length,
-        blocked_count: aggregate.processed.filter((entry) => entry.status !== 'merged').length,
-      });
-    } catch (err) {
-      console.error(chalk.red(err.message));
-      process.exitCode = 1;
-    }
-  });
-
-queueCmd
-  .command('retry <itemId>')
-  .description('Retry a blocked merge queue item')
-  .option('--json', 'Output raw JSON')
-  .action((itemId, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const item = retryMergeQueueItem(db, itemId);
-    db.close();
-
-    if (!item) {
-      printErrorWithNext(`Queue item ${itemId} is not retryable.`, 'switchman queue status');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(item, null, 2));
-      return;
-    }
+      if (opts.dryRun) {
+        console.log('');
+        console.log(chalk.dim('Dry run only — nothing was landed.'));
+        db.close();
+        return;
+      }
 
-    console.log(`${chalk.green('✓')} Queue item ${chalk.cyan(item.id)} reset to retrying`);
-  });
+      if (discovery.eligible.length === 0) {
+        console.log('');
+        console.log(chalk.dim('No finished worktrees are ready to land yet.'));
+        console.log(`${chalk.yellow('next:')} ${chalk.cyan('switchman status')}`);
+        db.close();
+        return;
+      }
 
-queueCmd
-  .command('escalate <itemId>')
-  .description('Mark a queue item as needing explicit operator review before landing')
-  .option('--reason <text>', 'Why this item is being escalated')
-  .option('--json', 'Output raw JSON')
-  .action((itemId, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const item = escalateMergeQueueItem(db, itemId, {
-      summary: opts.reason || null,
-      nextAction: `Run \`switchman explain queue ${itemId}\` to review the landing risk, then \`switchman queue retry ${itemId}\` when it is ready again.`,
-    });
-    db.close();
+      const gate = await evaluateQueueRepoGate(db, repoRoot);
+      if (!gate.ok) {
+        console.log('');
+        console.log(`${chalk.red('✗')} Merge gate blocked landing`);
+        console.log(`  ${chalk.dim(gate.summary)}`);
+        console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman gate ci')}`);
+        db.close();
+        return;
+      }
 
-    if (!item) {
-      printErrorWithNext(`Queue item ${itemId} cannot be escalated.`, 'switchman queue status');
-      process.exitCode = 1;
-      return;
-    }
+      console.log('');
+      const runnableCount = listMergeQueue(db).filter((item) => ['queued', 'retrying'].includes(item.status)).length;
+      const result = await runMergeQueue(db, repoRoot, {
+        targetBranch: opts.target || 'main',
+        maxItems: Math.max(1, runnableCount),
+        mergeBudget: Math.max(1, runnableCount),
+        followPlan: false,
+      });
 
-    if (opts.json) {
-      console.log(JSON.stringify(item, null, 2));
-      return;
-    }
+      const merged = result.processed.filter((item) => item.status === 'merged');
+      for (const mergedItem of merged) {
+        console.log(`  ${chalk.green('✓')} Landed ${chalk.cyan(mergedItem.item.source_ref)} into ${chalk.bold(mergedItem.item.target_branch)}`);
+      }
 
-    console.log(`${chalk.yellow('!')} Queue item ${chalk.cyan(item.id)} marked escalated for operator review`);
-    if (item.last_error_summary) {
-      console.log(`  ${chalk.red('why:')} ${item.last_error_summary}`);
-    }
-    if (item.next_action) {
-      console.log(`  ${chalk.yellow('next:')} ${item.next_action}`);
-    }
-  });
+      if (merged.length > 0 && !result.deferred && result.processed.every((item) => item.status === 'merged')) {
+        console.log('');
+        console.log(`${chalk.green('✓')} Done. ${merged.length} worktree(s) landed cleanly.`);
+        db.close();
+        return;
+      }
 
-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();
+      const blocked = result.processed.find((item) => item.status !== 'merged')?.item || result.deferred || null;
+      if (blocked) {
+        console.log('');
+        console.log(`${chalk.yellow('!')} Landing stopped at ${chalk.cyan(blocked.source_ref)}`);
+        if (blocked.last_error_summary) console.log(`  ${chalk.dim(blocked.last_error_summary)}`);
+        if (blocked.next_action) console.log(`  ${chalk.yellow('next:')} ${blocked.next_action}`);
+      }
 
-    if (!item) {
-      printErrorWithNext(`Queue item ${itemId} does not exist.`, 'switchman queue status');
+      db.close();
+    } catch (err) {
+      db.close();
+      console.error(chalk.red(err.message));
       process.exitCode = 1;
-      return;
     }
-
-    console.log(`${chalk.green('✓')} Removed ${chalk.cyan(item.id)} from the merge queue`);
   });
 
 // ── explain ───────────────────────────────────────────────────────────────────
@@ -3771,6 +4479,7 @@ explainCmd
 // ── pipeline ──────────────────────────────────────────────────────────────────
 
 const pipelineCmd = program.command('pipeline').description('Create and summarize issue-to-PR execution pipelines');
+pipelineCmd._switchmanAdvanced = true;
 pipelineCmd.addHelpText('after', `
 Examples:
   switchman pipeline start "Harden auth API permissions"
@@ -4528,316 +5237,43 @@ Examples:
     } catch (err) {
       db.close();
       printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
-      process.exitCode = 1;
-    }
-  });
-
-// ── lease ────────────────────────────────────────────────────────────────────
-
-const leaseCmd = program.command('lease').alias('session').description('Manage active work sessions and keep long-running tasks alive');
-leaseCmd.addHelpText('after', `
-Plain English:
-  lease = a task currently checked out by an agent
-
-Examples:
-  switchman lease next --json
-  switchman lease heartbeat lease-123
-  switchman lease reap
-`);
-
-leaseCmd
-  .command('acquire <taskId> <worktree>')
-  .description('Start a tracked work session for a specific pending task')
-  .option('--agent <name>', 'Agent identifier for logging')
-  .option('--json', 'Output as JSON')
-  .addHelpText('after', `
-Examples:
-  switchman lease acquire task-123 agent2
-  switchman lease acquire task-123 agent2 --agent cursor
-`)
-  .action((taskId, worktree, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const task = getTask(db, taskId);
-    const lease = startTaskLease(db, taskId, worktree, opts.agent || null);
-    db.close();
-
-    if (!lease || !task) {
-      if (opts.json) console.log(JSON.stringify({ lease: null, task: null }));
-      else printErrorWithNext('Could not start a work session. The task may not exist or may already be in progress.', 'switchman task list --status pending');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify({
-        lease,
-        task: taskJsonWithLease(task, worktree, lease).task,
-      }, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Lease acquired ${chalk.dim(lease.id)}`);
-    console.log(`  ${chalk.dim('task:')} ${chalk.bold(task.title)}`);
-    console.log(`  ${chalk.dim('worktree:')} ${chalk.cyan(worktree)}`);
-  });
-
-leaseCmd
-  .command('next')
-  .description('Start the next pending task and open a tracked work session for it')
-  .option('--json', 'Output as JSON')
-  .option('--worktree <name>', 'Workspace to assign the task to (defaults to the current folder name)')
-  .option('--agent <name>', 'Agent identifier for logging')
-  .addHelpText('after', `
-Examples:
-  switchman lease next
-  switchman lease next --json
-  switchman lease next --worktree agent2 --agent cursor
-`)
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const worktreeName = getCurrentWorktreeName(opts.worktree);
-    const { task, lease, exhausted } = acquireNextTaskLeaseWithRetries(repoRoot, worktreeName, opts.agent || null);
-
-    if (!task) {
-      if (opts.json) console.log(JSON.stringify({ task: null, lease: null }));
-      else if (exhausted) console.log(chalk.dim('No pending tasks. Add one with `switchman task add "Your task"`.'));
-      else console.log(chalk.yellow('Tasks were claimed by other agents during assignment. Run again to get the next one.'));
-      return;
-    }
-
-    if (!lease) {
-      if (opts.json) console.log(JSON.stringify({ task: null, lease: null, message: 'Task claimed by another agent — try again' }));
-      else console.log(chalk.yellow('Task was just claimed by another agent. Run again to get the next one.'));
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify({
-        lease,
-        ...taskJsonWithLease(task, worktreeName, lease),
-      }, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Lease acquired: ${chalk.bold(task.title)}`);
-    console.log(`  ${chalk.dim('task:')} ${task.id}  ${chalk.dim('lease:')} ${lease.id}`);
-    console.log(`  ${chalk.dim('worktree:')} ${chalk.cyan(worktreeName)}  ${chalk.dim('priority:')} ${task.priority}`);
-  });
-
-leaseCmd
-  .command('list')
-  .description('List leases, newest first')
-  .option('-s, --status <status>', 'Filter by status (active|completed|failed|expired)')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const leases = listLeases(db, opts.status);
-    db.close();
-
-    if (!leases.length) {
-      console.log(chalk.dim('No leases found.'));
-      return;
-    }
-
-    console.log('');
-    for (const lease of leases) {
-      console.log(`${statusBadge(lease.status)} ${chalk.bold(lease.task_title)}`);
-      console.log(`  ${chalk.dim('lease:')} ${lease.id}  ${chalk.dim('task:')} ${lease.task_id}`);
-      console.log(`  ${chalk.dim('worktree:')} ${chalk.cyan(lease.worktree)}  ${chalk.dim('agent:')} ${lease.agent || 'unknown'}`);
-      console.log(`  ${chalk.dim('started:')} ${lease.started_at}  ${chalk.dim('heartbeat:')} ${lease.heartbeat_at}`);
-      if (lease.failure_reason) console.log(`  ${chalk.red(lease.failure_reason)}`);
-      console.log('');
-    }
-  });
-
-leaseCmd
-  .command('heartbeat <leaseId>')
-  .description('Refresh the heartbeat timestamp for an active lease')
-  .option('--agent <name>', 'Agent identifier for logging')
-  .option('--json', 'Output as JSON')
-  .action((leaseId, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const lease = heartbeatLease(db, leaseId, opts.agent || null);
-    db.close();
-
-    if (!lease) {
-      if (opts.json) console.log(JSON.stringify({ lease: null }));
-      else printErrorWithNext(`No active work session found for ${leaseId}.`, 'switchman lease list --status active');
-      process.exitCode = 1;
-      return;
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify({ lease }, null, 2));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Heartbeat refreshed for ${chalk.dim(lease.id)}`);
-    console.log(`  ${chalk.dim('task:')} ${lease.task_title}  ${chalk.dim('worktree:')} ${chalk.cyan(lease.worktree)}`);
-  });
-
-leaseCmd
-  .command('reap')
-  .description('Clean up abandoned work sessions and release their file locks')
-  .option('--stale-after-minutes <minutes>', 'Age threshold for staleness')
-  .option('--json', 'Output as JSON')
-  .addHelpText('after', `
-Examples:
-  switchman lease reap
-  switchman lease reap --stale-after-minutes 20
-`)
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const leasePolicy = loadLeasePolicy(repoRoot);
-    const staleAfterMinutes = opts.staleAfterMinutes
-      ? Number.parseInt(opts.staleAfterMinutes, 10)
-      : leasePolicy.stale_after_minutes;
-    const expired = reapStaleLeases(db, staleAfterMinutes, {
-      requeueTask: leasePolicy.requeue_task_on_reap,
-    });
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify({ stale_after_minutes: staleAfterMinutes, expired }, null, 2));
-      return;
-    }
-
-    if (!expired.length) {
-      console.log(chalk.dim(`No stale leases older than ${staleAfterMinutes} minute(s).`));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Reaped ${expired.length} stale lease(s)`);
-    for (const lease of expired) {
-      console.log(`  ${chalk.dim(lease.id)}  ${chalk.cyan(lease.worktree)} → ${lease.task_title}`);
-    }
-  });
-
-const leasePolicyCmd = leaseCmd.command('policy').description('Inspect or update the stale-lease policy for this repo');
-
-leasePolicyCmd
-  .command('set')
-  .description('Persist a stale-lease policy for this repo')
-  .option('--heartbeat-interval-seconds <seconds>', 'Recommended heartbeat interval')
-  .option('--stale-after-minutes <minutes>', 'Age threshold for staleness')
-  .option('--reap-on-status-check <boolean>', 'Automatically reap stale leases during `switchman status`')
-  .option('--requeue-task-on-reap <boolean>', 'Return stale tasks to pending instead of failing them')
-  .option('--json', 'Output as JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const current = loadLeasePolicy(repoRoot);
-    const next = {
-      ...current,
-      ...(opts.heartbeatIntervalSeconds ? { heartbeat_interval_seconds: Number.parseInt(opts.heartbeatIntervalSeconds, 10) } : {}),
-      ...(opts.staleAfterMinutes ? { stale_after_minutes: Number.parseInt(opts.staleAfterMinutes, 10) } : {}),
-      ...(opts.reapOnStatusCheck ? { reap_on_status_check: opts.reapOnStatusCheck === 'true' } : {}),
-      ...(opts.requeueTaskOnReap ? { requeue_task_on_reap: opts.requeueTaskOnReap === 'true' } : {}),
-    };
-    const path = writeLeasePolicy(repoRoot, next);
-    const saved = loadLeasePolicy(repoRoot);
-
-    if (opts.json) {
-      console.log(JSON.stringify({ path, policy: saved }, null, 2));
-      return;
+      process.exitCode = 1;
     }
-
-    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;
-    }
+// ── lease ────────────────────────────────────────────────────────────────────
 
-    console.log(chalk.bold('Lease policy'));
-    console.log(`  ${chalk.dim('heartbeat_interval_seconds:')} ${policy.heartbeat_interval_seconds}`);
-    console.log(`  ${chalk.dim('stale_after_minutes:')} ${policy.stale_after_minutes}`);
-    console.log(`  ${chalk.dim('reap_on_status_check:')} ${policy.reap_on_status_check}`);
-    console.log(`  ${chalk.dim('requeue_task_on_reap:')} ${policy.requeue_task_on_reap}`);
-  });
+registerLeaseCommands(program, {
+  acquireNextTaskLeaseWithRetries,
+  chalk,
+  getCurrentWorktreeName,
+  getDb,
+  getRepo,
+  getTask,
+  heartbeatLease,
+  listLeases,
+  loadLeasePolicy,
+  pushSyncEvent,
+  reapStaleLeases,
+  startTaskLease,
+  statusBadge,
+  taskJsonWithLease,
+  writeLeasePolicy,
+});
 
 // ── worktree ───────────────────────────────────────────────────────────────────
 
-const wtCmd = program.command('worktree').alias('workspace').description('Manage registered workspaces (Git worktrees)');
-wtCmd.addHelpText('after', `
-Plain English:
-  worktree = the Git feature behind each agent workspace
-
-Examples:
-  switchman worktree list
-  switchman workspace list
-  switchman worktree sync
-`);
-
-wtCmd
-  .command('add <name> <path> <branch>')
-  .description('Register a workspace with Switchman')
-  .option('--agent <name>', 'Agent assigned to this worktree')
-  .action((name, path, branch, opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    registerWorktree(db, { name, path, branch, agent: opts.agent });
-    db.close();
-    console.log(`${chalk.green('✓')} Registered worktree: ${chalk.cyan(name)}`);
-  });
-
-wtCmd
-  .command('list')
-  .description('List all registered workspaces')
-  .action(() => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const worktrees = listWorktrees(db);
-    const gitWorktrees = listGitWorktrees(repoRoot);
-    db.close();
-
-    if (!worktrees.length && !gitWorktrees.length) {
-      console.log(chalk.dim('No workspaces found. Run `switchman setup --agents 3` or `switchman worktree sync`.'));
-      return;
-    }
-
-    // Show git worktrees (source of truth) annotated with db info
-    console.log('');
-    console.log(chalk.bold('Git Worktrees:'));
-    for (const wt of gitWorktrees) {
-      const dbInfo = worktrees.find(d => d.path === wt.path);
-      const agent = dbInfo?.agent ? chalk.cyan(dbInfo.agent) : chalk.dim('no agent');
-      const status = dbInfo?.status ? statusBadge(dbInfo.status) : chalk.dim('unregistered');
-      const compliance = dbInfo?.compliance_state ? statusBadge(dbInfo.compliance_state) : chalk.dim('unknown');
-      console.log(`  ${chalk.bold(wt.name.padEnd(20))} ${status} ${compliance} branch: ${chalk.cyan(wt.branch || 'unknown')}  agent: ${agent}`);
-      console.log(`    ${chalk.dim(wt.path)}`);
-    }
-    console.log('');
-  });
-
-wtCmd
-  .command('sync')
-  .description('Sync Git workspaces into the Switchman database')
-  .action(() => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const gitWorktrees = listGitWorktrees(repoRoot);
-    for (const wt of gitWorktrees) {
-      registerWorktree(db, { name: wt.name, path: wt.path, branch: wt.branch || 'unknown' });
-    }
-    db.close();
-    installMcpConfig([...new Set([repoRoot, ...gitWorktrees.map((wt) => wt.path)])]);
-    console.log(`${chalk.green('✓')} Synced ${gitWorktrees.length} worktree(s) from git`);
-  });
+registerWorktreeCommands(program, {
+  chalk,
+  evaluateRepoCompliance,
+  getDb,
+  getRepo,
+  installMcpConfig,
+  listGitWorktrees,
+  listWorktrees,
+  registerWorktree,
+  statusBadge,
+});
 
 // ── claim ──────────────────────────────────────────────────────────────────────
 
@@ -4845,13 +5281,14 @@ program
   .command('claim <taskId> <worktree> [files...]')
   .description('Lock files for a task before editing')
   .option('--agent <name>', 'Agent name')
-  .option('--force', 'Claim even if conflicts exist')
+  .option('--force', 'Emergency override for manual recovery when a conflicting claim is known to be stale or wrong')
   .addHelpText('after', `
 Examples:
   switchman claim task-123 agent2 src/auth.js src/server.js
   switchman claim task-123 agent2 src/auth.js --agent cursor
 
 Use this before editing files in a shared repo.
+Only use --force for operator-led recovery after checking switchman status or switchman explain claim <path>.
 `)
   .action((taskId, worktree, files, opts) => {
     if (!files.length) {
@@ -4870,7 +5307,7 @@ Use this before editing files in a shared repo.
         for (const c of conflicts) {
           console.log(`  ${chalk.yellow(c.file)} → already claimed by worktree ${chalk.cyan(c.claimedBy.worktree)} (task: ${c.claimedBy.task_title})`);
         }
-        console.log(chalk.dim('\nUse --force to claim anyway, or pick different files first.'));
+        console.log(chalk.dim('\nDo not use --force as a shortcut. Check status or explain the claim first, then only override if the existing claim is known-bad.'));
         console.log(`${chalk.yellow('next:')} switchman status`);
         process.exitCode = 1;
         return;
@@ -4878,6 +5315,12 @@ Use this before editing files in a shared repo.
 
       const lease = claimFiles(db, taskId, worktree, files, opts.agent);
       console.log(`${chalk.green('✓')} Claimed ${files.length} file(s) for task ${chalk.cyan(taskId)} (${chalk.dim(lease.id)})`);
+      pushSyncEvent('claim_added', {
+        task_id: taskId,
+        lease_id: lease.id,
+        file_count: files.length,
+        files: files.slice(0, 10),
+      }, { worktree }).catch(() => {});
       files.forEach(f => console.log(`  ${chalk.dim(f)}`));
     } catch (err) {
       printErrorWithNext(err.message, 'switchman task list --status in_progress');
@@ -4893,9 +5336,11 @@ program
   .action((taskId) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
+    const task = getTask(db, taskId);
     releaseFileClaims(db, taskId);
     db.close();
     console.log(`${chalk.green('✓')} Released all claims for task ${chalk.cyan(taskId)}`);
+    pushSyncEvent('claim_released', { task_id: taskId }, { worktree: task?.worktree || null }).catch(() => {});
   });
 
 program
@@ -5171,12 +5616,14 @@ program
   .description('Show one dashboard view of what is running, blocked, and ready next')
   .option('--json', 'Output raw JSON')
   .option('--watch', 'Keep refreshing status in the terminal')
+  .option('--repair', 'Repair safe interrupted queue and pipeline state before rendering status')
   .option('--watch-interval-ms <n>', 'Polling interval for --watch mode', '2000')
   .option('--max-cycles <n>', 'Maximum refresh cycles before exiting', '0')
   .addHelpText('after', `
 Examples:
   switchman status
   switchman status --watch
+  switchman status --repair
   switchman status --json
 
 Use this first when the repo feels stuck.
@@ -5194,13 +5641,40 @@ Use this first when the repo feels stuck.
         console.clear();
       }
 
+      let repairResult = null;
+      if (opts.repair) {
+        const repairDb = getDb(repoRoot);
+        try {
+          repairResult = repairRepoState(repairDb, repoRoot);
+        } finally {
+          repairDb.close();
+        }
+      }
+
       const report = await collectStatusSnapshot(repoRoot);
+      const [teamActivity, teamState] = await Promise.all([
+        pullActiveTeamMembers(),
+        pullTeamState(),
+      ]);
+      const myUserId = readCredentials()?.user_id;
+      const otherMembers = teamActivity.filter(e => e.user_id !== myUserId);
+      const teamSummary = summarizeTeamCoordinationState(teamState, myUserId);
       cycles += 1;
 
       if (opts.json) {
-        console.log(JSON.stringify(watch ? { ...report, watch: true, cycles } : report, null, 2));
+        const payload = watch ? { ...report, watch: true, cycles } : report;
+        const withTeam = { ...payload, team_sync: { summary: teamSummary, recent_events: teamState.filter((event) => event.user_id !== myUserId).slice(0, 25) } };
+        console.log(JSON.stringify(opts.repair ? { ...withTeam, repair: repairResult } : withTeam, null, 2));
       } else {
-        renderUnifiedStatusReport(report);
+        if (opts.repair && repairResult) {
+          printRepairSummary(repairResult, {
+            repairedHeading: `${chalk.green('✓')} Repaired safe interrupted repo state before rendering status`,
+            noRepairHeading: `${chalk.green('✓')} No repo repair action needed before rendering status`,
+            limit: 6,
+          });
+          console.log('');
+        }
+        renderUnifiedStatusReport(report, { teamActivity: otherMembers, teamSummary });
         if (watch) {
           const signature = buildWatchSignature(report);
           const watchState = lastSignature === null
@@ -5229,6 +5703,42 @@ Use this first when the repo feels stuck.
     }
   });
 
+program
+  .command('recover')
+  .description('Recover abandoned agent work, repair safe interrupted state, and point at the right checkpoint')
+  .option('--stale-after-minutes <minutes>', 'Age threshold for stale lease recovery')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman recover
+  switchman recover --stale-after-minutes 20
+  switchman recover --json
+
+Use this when an agent crashed, a worktree was abandoned mid-task, or the repo feels stuck after interrupted work.
+`)
+  .action((opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const report = buildRecoverReport(db, repoRoot, {
+        staleAfterMinutes: opts.staleAfterMinutes || null,
+      });
+      db.close();
+
+      if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+
+      printRecoverSummary(report);
+    } catch (err) {
+      db.close();
+      printErrorWithNext(err.message, 'switchman status');
+      process.exitCode = 1;
+    }
+  });
+
 program
   .command('repair')
   .description('Repair safe interrupted queue and pipeline state across the repo')
@@ -5267,9 +5777,11 @@ program
     }
   });
 
-program
+const doctorCmd = program
   .command('doctor')
-  .description('Show one operator-focused health view: what is running, what is blocked, and what to do next')
+  .description('Show one operator-focused health view: what is running, what is blocked, and what to do next');
+doctorCmd._switchmanAdvanced = true;
+doctorCmd
   .option('--repair', 'Repair safe interrupted queue and pipeline state before reporting health')
   .option('--json', 'Output raw JSON')
   .addHelpText('after', `
@@ -5358,377 +5870,74 @@ Examples:
       ? 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 staleClusterLines = report.merge_readiness.stale_clusters?.length > 0
-      ? report.merge_readiness.stale_clusters.slice(0, 5).flatMap((cluster) => {
-        const lines = [`${cluster.severity === 'block' ? renderChip('STALE', cluster.affected_pipeline_id || cluster.affected_task_ids[0], chalk.red) : renderChip('WATCH', cluster.affected_pipeline_id || cluster.affected_task_ids[0], chalk.yellow)} ${cluster.title}`];
-        lines.push(`  ${chalk.dim(cluster.detail)}`);
-        if (cluster.causal_group_size > 1) lines.push(`  ${chalk.dim('cause:')} ${cluster.causal_group_summary} ${chalk.dim(`(${cluster.causal_group_rank}/${cluster.causal_group_size} in same stale wave)`)}${cluster.related_affected_pipelines?.length ? ` ${chalk.dim(`related:${cluster.related_affected_pipelines.join(', ')}`)}` : ''}`);
-        lines.push(`  ${chalk.dim('areas:')} ${cluster.stale_areas.join(', ')}`);
-        lines.push(`  ${chalk.dim('rerun priority:')} ${cluster.rerun_priority} ${chalk.dim(`score:${cluster.rerun_priority_score}`)}${cluster.highest_affected_priority ? ` ${chalk.dim(`affected-priority:${cluster.highest_affected_priority}`)}` : ''}${cluster.rerun_breadth_score ? ` ${chalk.dim(`breadth:${cluster.rerun_breadth_score}`)}` : ''}`);
-        lines.push(`  ${chalk.yellow('next:')} ${cluster.next_step}`);
-        lines.push(`  ${chalk.cyan('run:')} ${cluster.command}`);
-        return lines;
-      })
-      : [chalk.green('No stale dependency clusters.')];
-
-    const nextStepLines = [
-      ...report.next_steps.slice(0, 4).map((step) => `- ${step}`),
-      '',
-      ...report.suggested_commands.slice(0, 4).map((command) => `${chalk.cyan('$')} ${command}`),
-    ];
-
-    console.log('');
-    console.log(chalk.bold('Attention now:'));
-    for (const block of [
-      renderPanel('Running now', runningLines, chalk.cyan),
-      renderPanel('Attention now', attentionLines, report.attention.some((item) => item.severity === 'block') ? chalk.red : report.attention.length > 0 ? chalk.yellow : chalk.green),
-      renderPanel('Stale clusters', staleClusterLines, report.merge_readiness.stale_clusters?.some((cluster) => cluster.severity === 'block') ? chalk.red : (report.merge_readiness.stale_clusters?.length || 0) > 0 ? chalk.yellow : chalk.green),
-      renderPanel('Recommended next steps', nextStepLines, chalk.green),
-    ]) {
-      for (const line of block) console.log(line);
-      console.log('');
-    }
-  });
-
-// ── gate ─────────────────────────────────────────────────────────────────────
-
-const gateCmd = program.command('gate').description('Safety checks for edits, merges, and CI');
-gateCmd.addHelpText('after', `
-Examples:
-  switchman gate ci
-  switchman gate ai
-  switchman gate install-ci
-`);
-
-const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
-
-auditCmd
-  .command('change <pipelineId>')
-  .description('Show a signed, operator-friendly history for one pipeline')
-  .option('--json', 'Output raw JSON')
-  .action((pipelineId, options) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-
-    try {
-      const report = buildPipelineHistoryReport(db, repoRoot, pipelineId);
-      db.close();
-
-      if (options.json) {
-        console.log(JSON.stringify(report, null, 2));
-        return;
-      }
-
-      console.log(chalk.bold(`Audit history for pipeline ${report.pipeline_id}`));
-      console.log(`  ${chalk.dim('title:')} ${report.title}`);
-      console.log(`  ${chalk.dim('events:')} ${report.events.length}`);
-      console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
-      for (const event of report.events.slice(-20)) {
-        const status = event.status ? ` ${statusBadge(event.status).trim()}` : '';
-        console.log(`  ${chalk.dim(event.created_at)} ${chalk.cyan(event.label)}${status}`);
-        console.log(`    ${event.summary}`);
-      }
-    } catch (err) {
-      db.close();
-      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
-      process.exitCode = 1;
-    }
-  });
-
-auditCmd
-  .command('verify')
-  .description('Verify the audit log hash chain and project signatures')
-  .option('--json', 'Output verification details as JSON')
-  .action((options) => {
-    const repo = getRepo();
-    const db = getDb(repo);
-    const result = verifyAuditTrail(db);
-
-    if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
-      process.exit(result.ok ? 0 : 1);
-    }
-
-    if (result.ok) {
-      console.log(chalk.green(`Audit trail verified: ${result.count} signed events in order.`));
-      return;
-    }
-
-    console.log(chalk.red(`Audit trail verification failed: ${result.failures.length} problem(s) across ${result.count} events.`));
-    for (const failure of result.failures.slice(0, 10)) {
-      const prefix = failure.sequence ? `#${failure.sequence}` : `event ${failure.id}`;
-      console.log(`  ${chalk.red(prefix)} ${failure.reason_code}: ${failure.message}`);
-    }
-    if (result.failures.length > 10) {
-      console.log(chalk.dim(`  ...and ${result.failures.length - 10} more`));
-    }
-    process.exit(1);
-  });
-
-gateCmd
-  .command('commit')
-  .description('Validate current worktree changes against the active lease and claims')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const result = runCommitGate(db, repoRoot);
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (result.ok) {
-      console.log(`${chalk.green('✓')} ${result.summary}`);
-    } else {
-      console.log(chalk.red(`✗ ${result.summary}`));
-      for (const violation of result.violations) {
-        const label = violation.file || '(worktree)';
-        console.log(`  ${chalk.yellow(label)} ${chalk.dim(violation.reason_code)}`);
-      }
-    }
-
-    if (!result.ok) process.exitCode = 1;
-  });
-
-gateCmd
-  .command('merge')
-  .description('Validate current worktree changes before recording a merge commit')
-  .option('--json', 'Output raw JSON')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const result = runCommitGate(db, repoRoot);
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (result.ok) {
-      console.log(`${chalk.green('✓')} Merge gate passed for ${chalk.cyan(result.worktree || 'current worktree')}.`);
-    } else {
-      console.log(chalk.red(`✗ Merge gate rejected changes in ${chalk.cyan(result.worktree || 'current worktree')}.`));
-      for (const violation of result.violations) {
-        const label = violation.file || '(worktree)';
-        console.log(`  ${chalk.yellow(label)} ${chalk.dim(violation.reason_code)}`);
-      }
-    }
-
-    if (!result.ok) process.exitCode = 1;
-  });
-
-gateCmd
-  .command('install')
-  .description('Install git hooks that run the Switchman commit and merge gates')
-  .action(() => {
-    const repoRoot = getRepo();
-    const hookPaths = installGateHooks(repoRoot);
-    console.log(`${chalk.green('✓')} Installed pre-commit hook at ${chalk.cyan(hookPaths.pre_commit)}`);
-    console.log(`${chalk.green('✓')} Installed pre-merge-commit hook at ${chalk.cyan(hookPaths.pre_merge_commit)}`);
-  });
-
-gateCmd
-  .command('ci')
-  .description('Run a repo-level enforcement gate suitable for CI, merges, or PR validation')
-  .option('--github', 'Write GitHub Actions step summary/output when GITHUB_* env vars are present')
-  .option('--github-step-summary <path>', 'Path to write GitHub Actions step summary markdown')
-  .option('--github-output <path>', 'Path to write GitHub Actions outputs')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const report = await scanAllWorktrees(db, repoRoot);
-    const aiGate = await runAiMergeGate(db, repoRoot);
-    db.close();
-
-    const ok = report.conflicts.length === 0
-      && report.fileConflicts.length === 0
-      && (report.ownershipConflicts?.length || 0) === 0
-      && (report.semanticConflicts?.length || 0) === 0
-      && report.unclaimedChanges.length === 0
-      && report.complianceSummary.non_compliant === 0
-      && report.complianceSummary.stale === 0
-      && aiGate.status !== 'blocked'
-      && (aiGate.dependency_invalidations?.filter((item) => item.severity === 'blocked').length || 0) === 0;
-
-    const result = {
-      ok,
-      summary: ok
-        ? `Repo gate passed for ${report.worktrees.length} worktree(s).`
-        : 'Repo gate rejected unmanaged changes, stale leases, ownership conflicts, stale dependency invalidations, or boundary validation failures.',
-      compliance: report.complianceSummary,
-      unclaimed_changes: report.unclaimedChanges,
-      file_conflicts: report.fileConflicts,
-      ownership_conflicts: report.ownershipConflicts || [],
-      semantic_conflicts: report.semanticConflicts || [],
-      branch_conflicts: report.conflicts,
-      ai_gate_status: aiGate.status,
-      boundary_validations: aiGate.boundary_validations || [],
-      dependency_invalidations: aiGate.dependency_invalidations || [],
-    };
-
-    const githubTargets = resolveGitHubOutputTargets(opts);
-    if (githubTargets.stepSummaryPath || githubTargets.outputPath) {
-      writeGitHubCiStatus({
-        result,
-        stepSummaryPath: githubTargets.stepSummaryPath,
-        outputPath: githubTargets.outputPath,
-      });
-    }
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else if (ok) {
-      console.log(`${chalk.green('✓')} ${result.summary}`);
-    } else {
-      console.log(chalk.red(`✗ ${result.summary}`));
-      if (result.unclaimed_changes.length > 0) {
-        console.log(chalk.bold('  Unclaimed changes:'));
-        for (const entry of result.unclaimed_changes) {
-          console.log(`    ${chalk.cyan(entry.worktree)}: ${entry.files.join(', ')}`);
-        }
-      }
-      if (result.file_conflicts.length > 0) {
-        console.log(chalk.bold('  File conflicts:'));
-        for (const conflict of result.file_conflicts) {
-          console.log(`    ${chalk.yellow(conflict.file)} ${chalk.dim(conflict.worktrees.join(', '))}`);
-        }
-      }
-      if (result.ownership_conflicts.length > 0) {
-        console.log(chalk.bold('  Ownership conflicts:'));
-        for (const conflict of result.ownership_conflicts) {
-          if (conflict.type === 'subsystem_overlap') {
-            console.log(`    ${chalk.yellow(conflict.worktreeA)} ${chalk.dim('vs')} ${chalk.yellow(conflict.worktreeB)} ${chalk.dim(`subsystem:${conflict.subsystemTag}`)}`);
-          } else {
-            console.log(`    ${chalk.yellow(conflict.worktreeA)} ${chalk.dim('vs')} ${chalk.yellow(conflict.worktreeB)} ${chalk.dim(`${conflict.scopeA} ↔ ${conflict.scopeB}`)}`);
-          }
-        }
-      }
-      if (result.semantic_conflicts.length > 0) {
-        console.log(chalk.bold('  Semantic conflicts:'));
-        for (const conflict of result.semantic_conflicts) {
-          console.log(`    ${chalk.yellow(conflict.object_name)} ${chalk.dim(`${conflict.worktreeA} vs ${conflict.worktreeB}`)}`);
-        }
-      }
-      if (result.branch_conflicts.length > 0) {
-        console.log(chalk.bold('  Branch conflicts:'));
-        for (const conflict of result.branch_conflicts) {
-          console.log(`    ${chalk.yellow(conflict.worktreeA)} ${chalk.dim('vs')} ${chalk.yellow(conflict.worktreeB)}`);
-        }
-      }
-      if (result.boundary_validations.length > 0) {
-        console.log(chalk.bold('  Boundary validations:'));
-        for (const validation of result.boundary_validations) {
-          console.log(`    ${chalk.yellow(validation.task_id)} ${chalk.dim(validation.missing_task_types.join(', '))}`);
-        }
-      }
-      if (result.dependency_invalidations.length > 0) {
-        console.log(chalk.bold('  Stale dependency invalidations:'));
-        for (const invalidation of result.dependency_invalidations) {
-          console.log(`    ${chalk.yellow(invalidation.affected_task_id)} ${chalk.dim(invalidation.stale_area)}`);
-        }
-      }
-    }
-
-    await maybeCaptureTelemetry(ok ? 'gate_ci_passed' : 'gate_ci_failed', {
-      worktree_count: report.worktrees.length,
-      unclaimed_change_count: result.unclaimed_changes.length,
-      file_conflict_count: result.file_conflicts.length,
-      ownership_conflict_count: result.ownership_conflicts.length,
-      semantic_conflict_count: result.semantic_conflicts.length,
-      branch_conflict_count: result.branch_conflicts.length,
-    });
-
-    if (!ok) process.exitCode = 1;
-  });
-
-gateCmd
-  .command('install-ci')
-  .description('Install a GitHub Actions workflow that runs the Switchman CI gate on PRs and pushes')
-  .option('--workflow-name <name>', 'Workflow file name', 'switchman-gate.yml')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const workflowPath = installGitHubActionsWorkflow(repoRoot, opts.workflowName);
-    console.log(`${chalk.green('✓')} Installed GitHub Actions workflow at ${chalk.cyan(workflowPath)}`);
-  });
-
-gateCmd
-  .command('ai')
-  .description('Run the AI-style merge check to assess risky overlap across workspaces')
-  .option('--json', 'Output raw JSON')
-  .action(async (opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const result = await runAiMergeGate(db, repoRoot);
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      const badge = result.status === 'pass'
-        ? chalk.green('PASS')
-        : result.status === 'warn'
-          ? chalk.yellow('WARN')
-          : chalk.red('BLOCK');
-      console.log(`${badge} ${result.summary}`);
-
-      const riskyPairs = result.pairs.filter((pair) => pair.status !== 'pass');
-      if (riskyPairs.length > 0) {
-        console.log(chalk.bold('  Risky pairs:'));
-        for (const pair of riskyPairs) {
-          console.log(`    ${chalk.cyan(pair.worktree_a)} ${chalk.dim('vs')} ${chalk.cyan(pair.worktree_b)} ${chalk.dim(pair.status)} ${chalk.dim(`score=${pair.score}`)}`);
-          for (const reason of pair.reasons.slice(0, 3)) {
-            console.log(`      ${chalk.yellow(reason)}`);
-          }
-        }
-      }
-
-      if ((result.boundary_validations?.length || 0) > 0) {
-        console.log(chalk.bold('  Boundary validations:'));
-        for (const validation of result.boundary_validations.slice(0, 5)) {
-          console.log(`    ${chalk.cyan(validation.task_id)} ${chalk.dim(validation.severity)} ${chalk.dim(validation.missing_task_types.join(', '))}`);
-          if (validation.rationale?.[0]) {
-            console.log(`      ${chalk.yellow(validation.rationale[0])}`);
-          }
-        }
-      }
+        lines.push(`  ${chalk.yellow('next:')} ${item.next_step}`);
+        if (item.command) lines.push(`  ${chalk.cyan('run:')} ${item.command}`);
+        return lines;
+      })
+      : [chalk.green('Nothing urgent.')];
 
-      if ((result.dependency_invalidations?.length || 0) > 0) {
-        console.log(chalk.bold('  Stale dependency invalidations:'));
-        for (const invalidation of result.dependency_invalidations.slice(0, 5)) {
-          console.log(`    ${chalk.cyan(invalidation.affected_task_id)} ${chalk.dim(invalidation.severity)} ${chalk.dim(invalidation.stale_area)}`);
-        }
-      }
+    const staleClusterLines = report.merge_readiness.stale_clusters?.length > 0
+      ? report.merge_readiness.stale_clusters.slice(0, 5).flatMap((cluster) => {
+        const lines = [`${cluster.severity === 'block' ? renderChip('STALE', cluster.affected_pipeline_id || cluster.affected_task_ids[0], chalk.red) : renderChip('WATCH', cluster.affected_pipeline_id || cluster.affected_task_ids[0], chalk.yellow)} ${cluster.title}`];
+        lines.push(`  ${chalk.dim(cluster.detail)}`);
+        if (cluster.causal_group_size > 1) lines.push(`  ${chalk.dim('cause:')} ${cluster.causal_group_summary} ${chalk.dim(`(${cluster.causal_group_rank}/${cluster.causal_group_size} in same stale wave)`)}${cluster.related_affected_pipelines?.length ? ` ${chalk.dim(`related:${cluster.related_affected_pipelines.join(', ')}`)}` : ''}`);
+        lines.push(`  ${chalk.dim('areas:')} ${cluster.stale_areas.join(', ')}`);
+        lines.push(`  ${chalk.dim('rerun priority:')} ${cluster.rerun_priority} ${chalk.dim(`score:${cluster.rerun_priority_score}`)}${cluster.highest_affected_priority ? ` ${chalk.dim(`affected-priority:${cluster.highest_affected_priority}`)}` : ''}${cluster.rerun_breadth_score ? ` ${chalk.dim(`breadth:${cluster.rerun_breadth_score}`)}` : ''}`);
+        lines.push(`  ${chalk.yellow('next:')} ${cluster.next_step}`);
+        lines.push(`  ${chalk.cyan('run:')} ${cluster.command}`);
+        return lines;
+      })
+      : [chalk.green('No stale dependency clusters.')];
 
-      if ((result.semantic_conflicts?.length || 0) > 0) {
-        console.log(chalk.bold('  Semantic conflicts:'));
-        for (const conflict of result.semantic_conflicts.slice(0, 5)) {
-          console.log(`    ${chalk.cyan(conflict.object_name)} ${chalk.dim(conflict.type)} ${chalk.dim(`${conflict.worktreeA} vs ${conflict.worktreeB}`)}`);
-        }
-      }
+    const nextStepLines = [
+      ...report.next_steps.slice(0, 4).map((step) => `- ${step}`),
+      '',
+      ...report.suggested_commands.slice(0, 4).map((command) => `${chalk.cyan('$')} ${command}`),
+    ];
 
-      const riskyWorktrees = result.worktrees.filter((worktree) => worktree.findings.length > 0);
-      if (riskyWorktrees.length > 0) {
-        console.log(chalk.bold('  Worktree signals:'));
-        for (const worktree of riskyWorktrees) {
-          console.log(`    ${chalk.cyan(worktree.worktree)} ${chalk.dim(`score=${worktree.score}`)}`);
-          for (const finding of worktree.findings.slice(0, 2)) {
-            console.log(`      ${chalk.yellow(finding)}`);
-          }
-        }
-      }
+    console.log('');
+    console.log(chalk.bold('Attention now:'));
+    for (const block of [
+      renderPanel('Running now', runningLines, chalk.cyan),
+      renderPanel('Attention now', attentionLines, report.attention.some((item) => item.severity === 'block') ? chalk.red : report.attention.length > 0 ? chalk.yellow : chalk.green),
+      renderPanel('Stale clusters', staleClusterLines, report.merge_readiness.stale_clusters?.some((cluster) => cluster.severity === 'block') ? chalk.red : (report.merge_readiness.stale_clusters?.length || 0) > 0 ? chalk.yellow : chalk.green),
+      renderPanel('Recommended next steps', nextStepLines, chalk.green),
+    ]) {
+      for (const line of block) console.log(line);
+      console.log('');
     }
-
-    if (result.status === 'blocked') process.exitCode = 1;
   });
 
+// ── gate ─────────────────────────────────────────────────────────────────────
+
+registerAuditCommands(program, {
+  buildPipelineHistoryReport,
+  chalk,
+  getDb,
+  getRepo,
+  printErrorWithNext,
+  statusBadge,
+  verifyAuditTrail,
+});
+
+registerGateCommands(program, {
+  chalk,
+  getDb,
+  getRepo,
+  installGateHooks,
+  installGitHubActionsWorkflow,
+  maybeCaptureTelemetry,
+  resolveGitHubOutputTargets,
+  runAiMergeGate,
+  runCommitGate,
+  scanAllWorktrees,
+  writeGitHubCiStatus,
+});
+
 const semanticCmd = program
   .command('semantic')
   .description('Inspect or materialize the derived semantic code-object view');
+semanticCmd._switchmanAdvanced = true;
 
 semanticCmd
   .command('materialize')
@@ -5745,6 +5954,7 @@ semanticCmd
 const objectCmd = program
   .command('object')
   .description('Experimental object-source mode backed by canonical exported code objects');
+objectCmd._switchmanAdvanced = true;
 
 objectCmd
   .command('import')
@@ -5825,180 +6035,25 @@ objectCmd
 
 // ── monitor ──────────────────────────────────────────────────────────────────
 
-const monitorCmd = program.command('monitor').description('Observe workspaces for runtime file changes');
-
-monitorCmd
-  .command('once')
-  .description('Capture one monitoring pass and log observed file changes')
-  .option('--json', 'Output raw JSON')
-  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const db = getDb(repoRoot);
-    const worktrees = listGitWorktrees(repoRoot);
-    const result = monitorWorktreesOnce(db, repoRoot, worktrees, { quarantine: opts.quarantine });
-    db.close();
-
-    if (opts.json) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    if (result.events.length === 0) {
-      console.log(chalk.dim('No file changes observed since the last monitor snapshot.'));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Observed ${result.summary.total} file change(s)`);
-    for (const event of result.events) {
-      const badge = event.status === 'allowed' ? chalk.green('ALLOWED') : chalk.red('DENIED ');
-      const action = event.enforcement_action ? ` ${chalk.dim(event.enforcement_action)}` : '';
-      console.log(`  ${badge} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${event.reason_code ? ` ${chalk.dim(event.reason_code)}` : ''}${action}`);
-    }
-  });
-
-monitorCmd
-  .command('watch')
-  .description('Poll workspaces continuously and log observed file changes')
-  .option('--interval-ms <ms>', 'Polling interval in milliseconds', '2000')
-  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
-  .option('--daemonized', 'Internal flag used by monitor start', false)
-  .action(async (opts) => {
-    const repoRoot = getRepo();
-    const intervalMs = Number.parseInt(opts.intervalMs, 10);
-
-    if (!Number.isFinite(intervalMs) || intervalMs < 100) {
-      console.error(chalk.red('--interval-ms must be at least 100'));
-      process.exit(1);
-    }
-
-    console.log(chalk.cyan(`Watching workspaces every ${intervalMs}ms. Press Ctrl+C to stop.`));
-
-    let stopped = false;
-    const stop = () => {
-      stopped = true;
-      process.stdout.write('\n');
-      if (opts.daemonized) {
-        clearMonitorState(repoRoot);
-      }
-    };
-    process.on('SIGINT', stop);
-    process.on('SIGTERM', stop);
-
-    while (!stopped) {
-      const db = getDb(repoRoot);
-      const worktrees = listGitWorktrees(repoRoot);
-      const result = monitorWorktreesOnce(db, repoRoot, worktrees, { quarantine: opts.quarantine });
-      db.close();
-
-      for (const event of result.events) {
-        const badge = event.status === 'allowed' ? chalk.green('ALLOWED') : chalk.red('DENIED ');
-        const action = event.enforcement_action ? ` ${chalk.dim(event.enforcement_action)}` : '';
-        console.log(`  ${badge} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${event.reason_code ? ` ${chalk.dim(event.reason_code)}` : ''}${action}`);
-      }
-
-      if (stopped) break;
-      await new Promise((resolvePromise) => setTimeout(resolvePromise, intervalMs));
-    }
-
-    console.log(chalk.dim('Stopped worktree monitor.'));
-  });
-
-monitorCmd
-  .command('start')
-  .description('Start the worktree monitor as a background process')
-  .option('--interval-ms <ms>', 'Polling interval in milliseconds', '2000')
-  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
-  .action((opts) => {
-    const repoRoot = getRepo();
-    const intervalMs = Number.parseInt(opts.intervalMs, 10);
-    const existingState = readMonitorState(repoRoot);
-
-    if (existingState && isProcessRunning(existingState.pid)) {
-      console.log(chalk.yellow(`Monitor already running with pid ${existingState.pid}`));
-      return;
-    }
-
-    const logPath = join(repoRoot, '.switchman', 'monitor.log');
-    const child = spawn(process.execPath, [
-      process.argv[1],
-      'monitor',
-      'watch',
-      '--interval-ms',
-      String(intervalMs),
-      ...(opts.quarantine ? ['--quarantine'] : []),
-      '--daemonized',
-    ], {
-      cwd: repoRoot,
-      detached: true,
-      stdio: 'ignore',
-    });
-    child.unref();
-
-    const statePath = writeMonitorState(repoRoot, {
-      pid: child.pid,
-      interval_ms: intervalMs,
-      quarantine: Boolean(opts.quarantine),
-      log_path: logPath,
-      started_at: new Date().toISOString(),
-    });
-
-    console.log(`${chalk.green('✓')} Started monitor pid ${chalk.cyan(String(child.pid))}`);
-    console.log(`${chalk.dim('State:')} ${statePath}`);
-  });
-
-monitorCmd
-  .command('stop')
-  .description('Stop the background worktree monitor')
-  .action(() => {
-    const repoRoot = getRepo();
-    const state = readMonitorState(repoRoot);
-
-    if (!state) {
-      console.log(chalk.dim('Monitor is not running.'));
-      return;
-    }
-
-    if (!isProcessRunning(state.pid)) {
-      clearMonitorState(repoRoot);
-      console.log(chalk.dim('Monitor state was stale and has been cleared.'));
-      return;
-    }
-
-    process.kill(state.pid, 'SIGTERM');
-    clearMonitorState(repoRoot);
-    console.log(`${chalk.green('✓')} Stopped monitor pid ${chalk.cyan(String(state.pid))}`);
-  });
-
-monitorCmd
-  .command('status')
-  .description('Show background monitor process status')
-  .action(() => {
-    const repoRoot = getRepo();
-    const state = readMonitorState(repoRoot);
-
-    if (!state) {
-      console.log(chalk.dim('Monitor is not running.'));
-      return;
-    }
-
-    const running = isProcessRunning(state.pid);
-    if (!running) {
-      clearMonitorState(repoRoot);
-      console.log(chalk.yellow('Monitor state existed but the process is no longer running.'));
-      return;
-    }
-
-    console.log(`${chalk.green('✓')} Monitor running`);
-    console.log(`  ${chalk.dim('pid')} ${state.pid}`);
-    console.log(`  ${chalk.dim('interval_ms')} ${state.interval_ms}`);
-    console.log(`  ${chalk.dim('quarantine')} ${state.quarantine ? 'true' : 'false'}`);
-    console.log(`  ${chalk.dim('started_at')} ${state.started_at}`);
-  });
+registerMonitorCommands(program, {
+  chalk,
+  clearMonitorState,
+  getDb,
+  getRepo,
+  isProcessRunning,
+  monitorWorktreesOnce,
+  processExecPath: process.execPath,
+  readMonitorState,
+  renderMonitorEvent,
+  resolveMonitoredWorktrees,
+  spawn,
+  startBackgroundMonitor,
+});
 
 // ── policy ───────────────────────────────────────────────────────────────────
 
 const policyCmd = program.command('policy').description('Manage enforcement and change-governance policy');
+policyCmd._switchmanAdvanced = true;
 
 policyCmd
   .command('init')
@@ -6144,4 +6199,372 @@ policyCmd
     }
   });
 
+
+ 
+// ── login ──────────────────────────────────────────────────────────────────────
+ 
+program
+  .command('login')
+  .description('Sign in with GitHub to activate Switchman Pro')
+  .option('--invite <token>', 'Join a team with an invite token')
+  .option('--status', 'Show current login status')
+  .addHelpText('after', `
+Examples:
+  switchman login
+  switchman login --status
+  switchman login --invite tk_8f3a2c
+`)
+  .action(async (opts) => {
+    // Show current status
+    if (opts.status) {
+      const creds = readCredentials();
+      if (!creds?.access_token) {
+        console.log('');
+        console.log(`  ${chalk.dim('Status:')} Not logged in`);
+        console.log(`  ${chalk.dim('Run:   ')} ${chalk.cyan('switchman login')}`);
+        console.log('');
+        return;
+      }
+ 
+      const licence = await checkLicence();
+      console.log('');
+      if (licence.valid) {
+        console.log(`  ${chalk.green('✓')} Logged in as ${chalk.cyan(creds.email ?? 'unknown')}`);
+        console.log(`  ${chalk.dim('Plan:')} ${licence.plan ?? 'Pro'}`);
+        if (licence.current_period_end) {
+          console.log(`  ${chalk.dim('Renews:')} ${new Date(licence.current_period_end).toLocaleDateString()}`);
+        }
+        if (licence.offline) {
+          console.log(`  ${chalk.dim('(offline cache)')}`);
+        }
+      } else {
+        console.log(`  ${chalk.yellow('⚠')} Logged in as ${chalk.cyan(creds.email ?? 'unknown')} but no active Pro licence`);
+        console.log(`  ${chalk.dim('Upgrade at:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+      }
+      console.log('');
+      return;
+    }
+
+    // Handle --invite token
+    if (opts.invite) {
+      const SUPABASE_URL  = process.env.SWITCHMAN_SUPABASE_URL
+        ?? 'https://afilbolhlkiingnsupgr.supabase.co';
+      const SUPABASE_ANON = process.env.SWITCHMAN_SUPABASE_ANON
+        ?? 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFmaWxib2xobGtpaW5nbnN1cGdyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzM1OTIzOTIsImV4cCI6MjA4OTE2ODM5Mn0.8TBfHfRB0vEyKPMWBd6i1DNwx1nS9UqprIAsJf35n88';
+
+      const creds = readCredentials();
+      if (!creds?.access_token) {
+        console.log('');
+        console.log(chalk.yellow('  You need to sign in first before accepting an invite.'));
+        console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman login')} ${chalk.dim('then try again with --invite')}`);
+        console.log('');
+        process.exit(1);
+      }
+
+      const { createClient } = await import('@supabase/supabase-js');
+      const sb = createClient(SUPABASE_URL, SUPABASE_ANON, {
+        global: { headers: { Authorization: `Bearer ${creds.access_token}` } }
+      });
+
+      const { data: { user } } = await sb.auth.getUser();
+      if (!user) {
+        console.log(chalk.red('  ✗  Could not verify your account. Run: switchman login'));
+        process.exit(1);
+      }
+
+      // Look up the invite
+      const { data: invite, error: inviteError } = await sb
+        .from('team_invites')
+        .select('id, team_id, email, accepted')
+        .eq('token', opts.invite)
+        .maybeSingle();
+
+      if (inviteError || !invite) {
+        console.log('');
+        console.log(chalk.red('  ✗  Invite token not found or already used.'));
+        console.log(`  ${chalk.dim('Ask your teammate to send a new invite.')}`);
+        console.log('');
+        process.exit(1);
+      }
+
+      if (invite.accepted) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  This invite has already been accepted.'));
+        console.log('');
+        process.exit(1);
+      }
+
+      // Add user to the team
+      const { error: memberError } = await sb
+        .from('team_members')
+        .insert({ team_id: invite.team_id, user_id: user.id, role: 'member' });
+
+      if (memberError && !memberError.message.includes('duplicate')) {
+        console.log(chalk.red(`  ✗  Could not join team: ${memberError.message}`));
+        process.exit(1);
+      }
+
+      // Mark invite as accepted
+      await sb
+        .from('team_invites')
+        .update({ accepted: true })
+        .eq('id', invite.id);
+
+      console.log('');
+      console.log(`  ${chalk.green('✓')}  Joined the team successfully`);
+      console.log(`  ${chalk.dim('Your agents now share coordination with your teammates.')}`);
+      console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman status')} ${chalk.dim('to see the shared view.')}`);
+      console.log('');
+      return;
+    }
+ 
+    // Already logged in?
+    const existing = readCredentials();
+    if (existing?.access_token) {
+      const licence = await checkLicence();
+      if (licence.valid) {
+        console.log('');
+        console.log(`  ${chalk.green('✓')} Already logged in as ${chalk.cyan(existing.email ?? 'unknown')}`);
+        console.log(`  ${chalk.dim('Plan:')} ${licence.plan ?? 'Pro'}`);
+        console.log(`  ${chalk.dim('Run')} ${chalk.cyan('switchman login --status')} ${chalk.dim('to see full details')}`);
+        console.log('');
+        return;
+      }
+    }
+ 
+    console.log('');
+    console.log(chalk.bold('  Switchman Pro — sign in with GitHub'));
+    console.log('');
+ 
+    const spinner = ora('Waiting for GitHub sign-in...').start();
+    spinner.stop();
+ 
+    const result = await loginWithGitHub();
+ 
+    if (!result.success) {
+      console.log(`  ${chalk.red('✗')} Sign in failed: ${result.error ?? 'unknown error'}`);
+      console.log(`  ${chalk.dim('Try again or visit:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+      console.log('');
+      process.exit(1);
+    }
+ 
+    // Verify the licence
+    const licence = await checkLicence();
+ 
+    console.log(`  ${chalk.green('✓')} Signed in as ${chalk.cyan(result.email ?? 'unknown')}`);
+ 
+    if (licence.valid) {
+      console.log(`  ${chalk.green('✓')} Switchman Pro active`);
+      console.log(`  ${chalk.dim('Plan:')} ${licence.plan ?? 'Pro'}`);
+      console.log('');
+      console.log(`  ${chalk.dim('Credentials saved · valid 24h · 7-day offline grace')}`);
+      console.log('');
+      console.log(`  Run ${chalk.cyan('switchman setup --agents 10')} to use unlimited agents.`);
+    } else {
+      console.log(`  ${chalk.yellow('⚠')} No active Pro licence found`);
+      console.log('');
+      console.log(`  If you just paid, it may take a moment to activate.`);
+      console.log(`  ${chalk.dim('Upgrade at:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+    }
+ 
+    console.log('');
+  });
+ 
+ 
+// ── logout ─────────────────────────────────────────────────────────────────────
+ 
+program
+  .command('logout')
+  .description('Sign out and remove saved credentials')
+  .action(() => {
+    clearCredentials();
+    console.log('');
+    console.log(`  ${chalk.green('✓')} Signed out — credentials removed`);
+    console.log('');
+  });
+ 
+ 
+// ── upgrade ────────────────────────────────────────────────────────────────────
+ 
+program
+  .command('upgrade')
+  .description('Open the Switchman Pro page in your browser')
+  .action(async () => {
+    console.log('');
+    console.log(`  Opening ${chalk.cyan(PRO_PAGE_URL)}...`);
+    console.log('');
+    const { default: open } = await import('open');
+    await open(PRO_PAGE_URL);
+  });
+ 
+  // ── team ───────────────────────────────────────────────────────────────────────
+
+const teamCmd = program
+  .command('team')
+  .description('Manage your Switchman Pro team');
+
+teamCmd
+  .command('invite <email>')
+  .description('Invite a teammate to your shared coordination')
+  .addHelpText('after', `
+Examples:
+  switchman team invite alice@example.com
+`)
+  .action(async (email) => {
+    const licence = await checkLicence();
+    if (!licence.valid) {
+      console.log('');
+      console.log(chalk.yellow('  ⚠  Team invites require Switchman Pro.'));
+      console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman upgrade')}`);
+      console.log('');
+      process.exit(1);
+    }
+
+    const repoRoot = getRepo();
+    const creds = readCredentials();
+    if (!creds?.access_token) {
+      console.log('');
+      console.log(chalk.yellow('  ⚠  You need to be logged in.'));
+      console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman login')}`);
+      console.log('');
+      process.exit(1);
+    }
+
+    const SUPABASE_URL  = process.env.SWITCHMAN_SUPABASE_URL
+      ?? 'https://afilbolhlkiingnsupgr.supabase.co';
+    const SUPABASE_ANON = process.env.SWITCHMAN_SUPABASE_ANON
+      ?? 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFmaWxib2xobGtpaW5nbnN1cGdyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzM1OTIzOTIsImV4cCI6MjA4OTE2ODM5Mn0.8TBfHfRB0vEyKPMWBd6i1DNwx1nS9UqprIAsJf35n88';
+
+    const { createClient } = await import('@supabase/supabase-js');
+    const sb = createClient(SUPABASE_URL, SUPABASE_ANON, {
+      global: { headers: { Authorization: `Bearer ${creds.access_token}` } }
+    });
+
+    const { data: { user } } = await sb.auth.getUser();
+    if (!user) {
+      console.log(chalk.red('  ✗  Could not verify your account. Run: switchman login'));
+      process.exit(1);
+    }
+
+    // Get or create team
+    let teamId;
+    const { data: membership } = await sb
+      .from('team_members')
+      .select('team_id')
+      .eq('user_id', user.id)
+      .maybeSingle();
+
+    if (membership?.team_id) {
+      teamId = membership.team_id;
+    } else {
+      // Create a new team
+      const { data: team, error: teamError } = await sb
+        .from('teams')
+        .insert({ owner_id: user.id, name: 'My Team' })
+        .select('id')
+        .single();
+
+      if (teamError) {
+        console.log(chalk.red(`  ✗  Could not create team: ${teamError.message}`));
+        process.exit(1);
+      }
+
+      teamId = team.id;
+
+      // Add the owner as a member
+      await sb.from('team_members').insert({
+        team_id: teamId,
+        user_id: user.id,
+        role: 'owner',
+      });
+    }
+
+    // Create the invite
+    const { data: invite, error: inviteError } = await sb
+      .from('team_invites')
+      .insert({
+        team_id: teamId,
+        invited_by: user.id,
+        email,
+      })
+      .select('token')
+      .single();
+
+    if (inviteError) {
+      console.log(chalk.red(`  ✗  Could not create invite: ${inviteError.message}`));
+      process.exit(1);
+    }
+
+    console.log('');
+    console.log(`  ${chalk.green('✓')}  Invite created for ${chalk.cyan(email)}`);
+    console.log('');
+    console.log(`  They can join with:`);
+    console.log(`  ${chalk.cyan(`switchman login --invite ${invite.token}`)}`);
+    console.log('');
+  });
+
+teamCmd
+  .command('list')
+  .description('List your team members')
+  .action(async () => {
+    const licence = await checkLicence();
+    if (!licence.valid) {
+      console.log('');
+      console.log(chalk.yellow('  ⚠  Team features require Switchman Pro.'));
+      console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman upgrade')}`);
+      console.log('');
+      process.exit(1);
+    }
+
+    const creds = readCredentials();
+    if (!creds?.access_token) {
+      console.log(chalk.red('  ✗  Not logged in. Run: switchman login'));
+      process.exit(1);
+    }
+
+    const SUPABASE_URL  = process.env.SWITCHMAN_SUPABASE_URL
+      ?? 'https://afilbolhlkiingnsupgr.supabase.co';
+    const SUPABASE_ANON = process.env.SWITCHMAN_SUPABASE_ANON
+      ?? 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFmaWxib2xobGtpaW5nbnN1cGdyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzM1OTIzOTIsImV4cCI6MjA4OTE2ODM5Mn0.8TBfHfRB0vEyKPMWBd6i1DNwx1nS9UqprIAsJf35n88';
+
+    const { createClient } = await import('@supabase/supabase-js');
+    const sb = createClient(SUPABASE_URL, SUPABASE_ANON, {
+      global: { headers: { Authorization: `Bearer ${creds.access_token}` } }
+    });
+
+    const { data: membership } = await sb
+      .from('team_members')
+      .select('team_id')
+      .eq('user_id', (await sb.auth.getUser()).data.user?.id)
+      .maybeSingle();
+
+    if (!membership?.team_id) {
+      console.log('');
+      console.log(`  ${chalk.dim('No team yet. Invite someone with:')} ${chalk.cyan('switchman team invite <email>')}`);
+      console.log('');
+      return;
+    }
+
+    const { data: members } = await sb
+      .from('team_members')
+      .select('user_id, role, joined_at')
+      .eq('team_id', membership.team_id);
+
+    const { data: invites } = await sb
+      .from('team_invites')
+      .select('email, token, accepted, created_at')
+      .eq('team_id', membership.team_id)
+      .eq('accepted', false);
+
+    console.log('');
+    for (const m of members ?? []) {
+      const roleLabel = m.role === 'owner' ? chalk.dim('(owner)') : chalk.dim('(member)');
+      console.log(`  ${chalk.green('✓')} ${chalk.cyan(m.user_id.slice(0, 8))}  ${roleLabel}`);
+    }
+    for (const inv of invites ?? []) {
+      console.log(`  ${chalk.dim('○')} ${chalk.cyan(inv.email)}  ${chalk.dim('(invited)')}`);
+    }
+    console.log('');
+  });
+
 program.parse();