switchman-dev 0.1.7 → 0.1.8

package/src/cli/index.js

@@ -16,7 +16,7 @@
  *   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';
@@ -24,7 +24,7 @@ import { tmpdir } from 'os';
 import { dirname, join, posix } from 'path';
 import { execSync, spawn } 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,20 @@ import {
   createPolicyOverride, listPolicyOverrides, revokePolicyOverride,
   finishOperationJournalEntry, listOperationJournal, listTempResources, updateTempResource,
   claimFiles, releaseFileClaims, getActiveFileClaims, checkFileConflicts, retryTask,
-  listAuditEvents, verifyAuditTrail,
+  upsertTaskSpec,
+  listAuditEvents, pruneDatabaseMaintenance, verifyAuditTrail,
 } from '../core/db.js';
 import { scanAllWorktrees } from '../core/detector.js';
-import { getWindsurfMcpConfigPath, upsertAllProjectMcpConfigs, upsertWindsurfMcpConfig } from '../core/mcp.js';
-import { gatewayAppendFile, gatewayMakeDirectory, gatewayMovePath, gatewayRemovePath, gatewayWriteFile, installGateHooks, monitorWorktreesOnce, runCommitGate, runWrappedCommand, writeEnforcementPolicy } from '../core/enforcement.js';
+import { ensureProjectLocalMcpGitExcludes, getWindsurfMcpConfigPath, upsertAllProjectMcpConfigs, upsertWindsurfMcpConfig } from '../core/mcp.js';
+import { evaluateRepoCompliance, gatewayAppendFile, gatewayMakeDirectory, gatewayMovePath, gatewayRemovePath, gatewayWriteFile, installGateHooks, monitorWorktreesOnce, runCommitGate, runWrappedCommand, writeEnforcementPolicy } from '../core/enforcement.js';
 import { runAiMergeGate } from '../core/merge-gate.js';
 import { clearMonitorState, getMonitorStatePath, isProcessRunning, readMonitorState, writeMonitorState } from '../core/monitor.js';
 import { buildPipelinePrSummary, 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 +61,9 @@ import {
   maybePromptForTelemetry,
   sendTelemetryEvent,
 } from '../core/telemetry.js';
+import { checkLicence, clearCredentials, FREE_AGENT_LIMIT, getRetentionDaysForCurrentPlan, loginWithGitHub, PRO_PAGE_URL, readCredentials } from '../core/licence.js';
+import { homedir } from 'os';
+import { cleanupOldSyncEvents, pullActiveTeamMembers, pullTeamState, pushSyncEvent } from '../core/sync.js';
 
 const originalProcessEmit = process.emit.bind(process);
 process.emit = function patchedProcessEmit(event, ...args) {
@@ -95,6 +100,177 @@ function getDb(repoRoot) {
   }
 }
 
+function getOptionalDb(repoRoot) {
+  try {
+    return openDb(repoRoot);
+  } catch {
+    return null;
+  }
+}
+
+function slugifyValue(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'plan';
+}
+
+function capitalizeSentence(value) {
+  const text = String(value || '').trim();
+  if (!text) return text;
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+function formatHumanList(values = []) {
+  if (values.length === 0) return '';
+  if (values.length === 1) return values[0];
+  if (values.length === 2) return `${values[0]} and ${values[1]}`;
+  return `${values.slice(0, -1).join(', ')}, and ${values[values.length - 1]}`;
+}
+
+function readPlanningFile(repoRoot, fileName, maxChars = 1200) {
+  const filePath = join(repoRoot, fileName);
+  if (!existsSync(filePath)) return null;
+  try {
+    const text = readFileSync(filePath, 'utf8').trim();
+    if (!text) return null;
+    return {
+      file: fileName,
+      text: text.slice(0, maxChars),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function extractMarkdownSignal(text) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  for (const line of lines) {
+    const normalized = line.replace(/^#+\s*/, '').replace(/^[-*]\s+/, '').trim();
+    if (!normalized) continue;
+    if (/^switchman\b/i.test(normalized)) continue;
+    return normalized;
+  }
+  return null;
+}
+
+function deriveGoalFromBranch(branchName) {
+  const raw = String(branchName || '').replace(/^refs\/heads\//, '').trim();
+  if (!raw || ['main', 'master', 'trunk', 'develop', 'development'].includes(raw)) return null;
+  const tail = raw.split('/').pop() || raw;
+  const tokens = tail
+    .replace(/^\d+[-_]?/, '')
+    .split(/[-_]/)
+    .filter(Boolean)
+    .filter((token) => !['feature', 'feat', 'fix', 'bugfix', 'chore', 'task', 'issue', 'story', 'work'].includes(token.toLowerCase()));
+  if (tokens.length === 0) return null;
+  return capitalizeSentence(tokens.join(' '));
+}
+
+function getRecentCommitSubjects(repoRoot, limit = 6) {
+  try {
+    return execSync(`git log --pretty=%s -n ${limit}`, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim().split('\n').map((line) => line.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function summarizeRecentCommitContext(branchGoal, subjects) {
+  if (!subjects.length) return null;
+  const topicWords = String(branchGoal || '')
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((word) => word.length >= 4);
+  const relatedCount = topicWords.length > 0
+    ? subjects.filter((subject) => {
+      const lower = subject.toLowerCase();
+      return topicWords.some((word) => lower.includes(word));
+    }).length
+    : 0;
+  const effectiveCount = relatedCount > 0 ? relatedCount : Math.min(subjects.length, 3);
+  const topicLabel = relatedCount > 0 && topicWords.length > 0 ? `${topicWords[0]}-related ` : '';
+  return `${effectiveCount} recent ${topicLabel}commit${effectiveCount === 1 ? '' : 's'}`;
+}
+
+function collectPlanContext(repoRoot, explicitGoal = null) {
+  const planningFiles = ['CLAUDE.md', 'ROADMAP.md', 'tasks.md', 'TASKS.md', 'TODO.md', 'README.md']
+    .map((fileName) => readPlanningFile(repoRoot, fileName))
+    .filter(Boolean);
+  const planningByName = new Map(planningFiles.map((entry) => [entry.file, entry]));
+  const branch = getWorktreeBranch(process.cwd()) || null;
+  const branchGoal = deriveGoalFromBranch(branch);
+  const recentCommitSubjects = getRecentCommitSubjects(repoRoot, 6);
+  const recentCommitSummary = summarizeRecentCommitContext(branchGoal, recentCommitSubjects);
+  const preferredPlanningFile = planningByName.get('CLAUDE.md')
+    || planningByName.get('tasks.md')
+    || planningByName.get('TASKS.md')
+    || planningByName.get('ROADMAP.md')
+    || planningByName.get('TODO.md')
+    || planningByName.get('README.md')
+    || null;
+  const planningSignal = preferredPlanningFile ? extractMarkdownSignal(preferredPlanningFile.text) : null;
+  const title = capitalizeSentence(explicitGoal || branchGoal || planningSignal || 'Plan the next coordinated change');
+  const descriptionParts = [];
+  if (preferredPlanningFile?.text) descriptionParts.push(preferredPlanningFile.text);
+  if (recentCommitSubjects.length > 0) descriptionParts.push(`Recent git history summary: ${recentCommitSubjects.slice(0, 3).join('; ')}.`);
+  const description = descriptionParts.join('\n\n').trim() || null;
+
+  const found = [];
+  const used = [];
+  if (explicitGoal) {
+    used.push('explicit goal');
+  }
+  if (branch) {
+    found.push(`branch ${branch}`);
+    if (branchGoal) used.push('branch name');
+  }
+  if (preferredPlanningFile?.file) {
+    found.push(preferredPlanningFile.file);
+    used.push(preferredPlanningFile.file);
+  }
+  if (recentCommitSummary) {
+    found.push(recentCommitSummary);
+    used.push('recent git history');
+  }
+
+  return {
+    branch,
+    title,
+    description,
+    found,
+    used: [...new Set(used)],
+  };
+}
+
+function resolvePlanningWorktrees(repoRoot, db = null) {
+  if (db) {
+    const registered = listWorktrees(db)
+      .filter((worktree) => worktree.name !== 'main' && worktree.status !== 'missing')
+      .map((worktree) => ({ name: worktree.name, path: worktree.path, branch: worktree.branch }));
+    if (registered.length > 0) return registered;
+  }
+  return listGitWorktrees(repoRoot)
+    .filter((worktree) => !worktree.isMain)
+    .map((worktree) => ({ name: worktree.name, path: worktree.path, branch: worktree.branch || null }));
+}
+
+function planTaskPriority(taskSpec = null) {
+  const taskType = taskSpec?.task_type || 'implementation';
+  if (taskType === 'implementation') return 8;
+  if (taskType === 'tests') return 7;
+  if (taskType === 'docs') return 6;
+  if (taskType === 'governance') return 6;
+  return 5;
+}
+
 function resolvePrNumberFromEnv(env = process.env) {
   if (env.SWITCHMAN_PR_NUMBER) return String(env.SWITCHMAN_PR_NUMBER);
   if (env.GITHUB_PR_NUMBER) return String(env.GITHUB_PR_NUMBER);
@@ -1783,12 +1959,24 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
       };
     });
 
-  const blockedWorktrees = scanReport.unclaimedChanges.map((entry) => ({
-    worktree: entry.worktree,
-    files: entry.files,
-    reason_code: entry.reasons?.[0]?.reason_code || null,
-    next_step: nextStepForReason(entry.reasons?.[0]?.reason_code) || 'inspect the changed files and bring them back under Switchman claims',
-  }));
+  const worktreeByName = new Map((scanReport.worktrees || []).map((worktree) => [worktree.name, worktree]));
+  const blockedWorktrees = scanReport.unclaimedChanges.map((entry) => {
+    const worktreeInfo = worktreeByName.get(entry.worktree) || null;
+    const reasonCode = entry.reasons?.[0]?.reason_code || null;
+    const isDirtyWorktree = reasonCode === 'no_active_lease';
+    return {
+      worktree: entry.worktree,
+      path: worktreeInfo?.path || null,
+      files: entry.files,
+      reason_code: reasonCode,
+      next_step: isDirtyWorktree
+        ? 'commit or discard the changed files in that worktree, then rescan before continuing'
+        : (nextStepForReason(reasonCode) || 'inspect the changed files and bring them back under Switchman claims'),
+      command: worktreeInfo?.path
+        ? `cd ${JSON.stringify(worktreeInfo.path)} && git status`
+        : 'switchman scan',
+    };
+  });
 
   const fileConflicts = scanReport.fileConflicts.map((conflict) => ({
     file: conflict.file,
@@ -1838,9 +2026,9 @@ function buildDoctorReport({ db, repoRoot, tasks, activeLeases, staleLeases, sca
     ...blockedWorktrees.map((entry) => ({
       kind: 'unmanaged_changes',
       title: `${entry.worktree} has unmanaged changed files`,
-      detail: `${entry.files.slice(0, 3).join(', ')}${entry.files.length > 3 ? ` +${entry.files.length - 3} more` : ''}`,
+      detail: `${entry.files.slice(0, 5).join(', ')}${entry.files.length > 5 ? ` +${entry.files.length - 5} more` : ''}${entry.path ? ` • ${entry.path}` : ''}`,
       next_step: entry.next_step,
-      command: 'switchman scan',
+      command: entry.command,
       severity: 'block',
     })),
     ...fileConflicts.map((conflict) => ({
@@ -1997,6 +2185,7 @@ function buildUnifiedStatusReport({
   queueItems,
   queueSummary,
   recentQueueEvents,
+  retentionDays = 7,
 }) {
   const queueAttention = [
     ...queueItems
@@ -2101,6 +2290,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 +2298,9 @@ async function collectStatusSnapshot(repoRoot) {
   const db = getDb(repoRoot);
   try {
     const leasePolicy = loadLeasePolicy(repoRoot);
+    const retentionDays = await getRetentionDaysForCurrentPlan();
+    pruneDatabaseMaintenance(db, { retentionDays });
+    cleanupOldSyncEvents({ retentionDays }).catch(() => {});
 
     if (leasePolicy.reap_on_status_check) {
       reapStaleLeases(db, leasePolicy.stale_after_minutes, {
@@ -2147,13 +2340,40 @@ async function collectStatusSnapshot(repoRoot) {
       queueItems,
       queueSummary,
       recentQueueEvents,
+      retentionDays,
     });
   } finally {
     db.close();
   }
 }
 
-function renderUnifiedStatusReport(report) {
+function summarizeTeamCoordinationState(events = [], myUserId = null) {
+  const visibleEvents = events.filter((event) => event.user_id !== myUserId);
+  if (visibleEvents.length === 0) {
+    return {
+      members: 0,
+      queue_events: 0,
+      lease_events: 0,
+      claim_events: 0,
+      latest_queue_event: null,
+    };
+  }
+
+  const activeMembers = new Set(visibleEvents.map((event) => event.user_id || `${event.payload?.email || 'unknown'}:${event.worktree || 'unknown'}`));
+  const queueEvents = visibleEvents.filter((event) => ['queue_added', 'queue_merged', 'queue_blocked'].includes(event.event_type));
+  const leaseEvents = visibleEvents.filter((event) => ['lease_acquired', 'task_done', 'task_failed', 'task_retried'].includes(event.event_type));
+  const claimEvents = visibleEvents.filter((event) => ['claim_added', 'claim_released'].includes(event.event_type));
+
+  return {
+    members: activeMembers.size,
+    queue_events: queueEvents.length,
+    lease_events: leaseEvents.length,
+    claim_events: claimEvents.length,
+    latest_queue_event: queueEvents[0] || null,
+  };
+}
+
+function renderUnifiedStatusReport(report, { teamActivity = [], teamSummary = null } = {}) {
   const healthColor = colorForHealth(report.health);
   const badge = healthColor(healthLabel(report.health));
   const mergeColor = report.merge_readiness.ci_gate_ok ? chalk.green : chalk.red;
@@ -2212,10 +2432,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 +2483,27 @@ function renderUnifiedStatusReport(report) {
 
   const blockedItems = report.attention.filter((item) => item.severity === 'block');
   const warningItems = report.attention.filter((item) => item.severity !== 'block');
+  const isQuietEmptyState = report.active_work.length === 0
+    && blockedItems.length === 0
+    && warningItems.length === 0
+    && report.queue.items.length === 0
+    && report.next_up.length === 0
+    && report.failed_tasks.length === 0;
+
+  if (isQuietEmptyState) {
+    console.log('');
+    console.log(healthColor('='.repeat(72)));
+    console.log(`${badge} ${chalk.bold('switchman status')} ${chalk.dim('• mission control for parallel agents')}`);
+    console.log(`${chalk.dim(report.repo_root)}`);
+    console.log(`${chalk.dim(report.summary)}`);
+    console.log(healthColor('='.repeat(72)));
+    console.log('');
+    console.log(chalk.green('Nothing is running yet.'));
+    console.log(`Add work with: ${chalk.cyan('switchman task add "Your first task" --priority 8')}`);
+    console.log(`Or prove the flow in 30 seconds with: ${chalk.cyan('switchman demo')}`);
+    console.log('');
+    return;
+  }
 
   const blockedLines = blockedItems.length > 0
     ? blockedItems.slice(0, 4).flatMap((item) => {
@@ -2405,10 +2679,12 @@ function completeTaskWithRetries(repoRoot, taskId, attempts = 20) {
     let db = null;
     try {
       db = openDb(repoRoot);
-      completeTask(db, taskId);
-      releaseFileClaims(db, taskId);
+      const result = completeTask(db, taskId);
+      if (result?.status === 'completed') {
+        releaseFileClaims(db, taskId);
+      }
       db.close();
-      return;
+      return result;
     } catch (err) {
       lastError = err;
       try { db?.close(); } catch { /* no-op */ }
@@ -2421,6 +2697,210 @@ function completeTaskWithRetries(repoRoot, taskId, attempts = 20) {
   throw lastError;
 }
 
+function startBackgroundMonitor(repoRoot, { intervalMs = 2000, quarantine = false } = {}) {
+  const existingState = readMonitorState(repoRoot);
+  if (existingState && isProcessRunning(existingState.pid)) {
+    return {
+      already_running: true,
+      state: existingState,
+      state_path: getMonitorStatePath(repoRoot),
+    };
+  }
+
+  const logPath = join(repoRoot, '.switchman', 'monitor.log');
+  const child = spawn(process.execPath, [
+    process.argv[1],
+    'monitor',
+    'watch',
+    '--interval-ms',
+    String(intervalMs),
+    ...(quarantine ? ['--quarantine'] : []),
+    '--daemonized',
+  ], {
+    cwd: repoRoot,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  const statePath = writeMonitorState(repoRoot, {
+    pid: child.pid,
+    interval_ms: intervalMs,
+    quarantine: Boolean(quarantine),
+    log_path: logPath,
+    started_at: new Date().toISOString(),
+  });
+
+  return {
+    already_running: false,
+    state: readMonitorState(repoRoot),
+    state_path: statePath,
+  };
+}
+
+function renderMonitorEvent(event) {
+  const ownerText = event.owner_worktree
+    ? `${event.owner_worktree}${event.owner_task_id ? ` (${event.owner_task_id})` : ''}`
+    : null;
+  const claimCommand = event.task_id
+    ? `switchman claim ${event.task_id} ${event.worktree} ${event.file_path}`
+    : null;
+
+  if (event.status === 'denied') {
+    console.log(`${chalk.yellow('⚠')} ${chalk.cyan(event.worktree)} modified ${chalk.yellow(event.file_path)} without governed ownership`);
+    if (ownerText) {
+      console.log(`   ${chalk.dim('Owned by:')} ${chalk.cyan(ownerText)}${event.owner_task_title ? ` ${chalk.dim(`— ${event.owner_task_title}`)}` : ''}`);
+    }
+    if (claimCommand) {
+      console.log(`   ${chalk.dim('Run:')} ${chalk.cyan(claimCommand)}`);
+    }
+    console.log(`   ${chalk.dim('Or:')} ${chalk.cyan('switchman status')}  ${chalk.dim('to inspect current claims and blockers')}`);
+    if (event.enforcement_action) {
+      console.log(`   ${chalk.dim('Action:')} ${event.enforcement_action}`);
+    }
+    return;
+  }
+
+  const ownerSuffix = ownerText ? ` ${chalk.dim(`(${ownerText})`)}` : '';
+  console.log(`${chalk.green('✓')} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${ownerSuffix}`);
+}
+
+function resolveMonitoredWorktrees(db, repoRoot) {
+  const registeredByPath = new Map(
+    listWorktrees(db)
+      .filter((worktree) => worktree.path)
+      .map((worktree) => [worktree.path, worktree])
+  );
+
+  return listGitWorktrees(repoRoot).map((worktree) => {
+    const registered = registeredByPath.get(worktree.path);
+    if (!registered) return worktree;
+    return {
+      ...worktree,
+      name: registered.name,
+      path: registered.path || worktree.path,
+      branch: registered.branch || worktree.branch,
+    };
+  });
+}
+
+function discoverMergeCandidates(db, repoRoot, { targetBranch = 'main' } = {}) {
+  const worktrees = listWorktrees(db).filter((worktree) => worktree.name !== 'main');
+  const activeLeases = new Set(listLeases(db, 'active').map((lease) => lease.worktree));
+  const tasks = listTasks(db);
+  const queueItems = listMergeQueue(db).filter((item) => item.status !== 'merged');
+  const alreadyQueued = new Set(queueItems.map((item) => item.source_worktree).filter(Boolean));
+
+  const eligible = [];
+  const blocked = [];
+  const skipped = [];
+
+  for (const worktree of worktrees) {
+    const doneTasks = tasks.filter((task) => task.worktree === worktree.name && task.status === 'done');
+    if (doneTasks.length === 0) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'no_completed_tasks',
+        summary: 'no completed tasks are assigned to this worktree yet',
+        command: `switchman task list --status done`,
+      });
+      continue;
+    }
+
+    if (!worktree.branch || worktree.branch === targetBranch) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch || null,
+        reason: 'no_merge_branch',
+        summary: `worktree is on ${targetBranch} already`,
+        command: `switchman worktree list`,
+      });
+      continue;
+    }
+
+    if (!gitBranchExists(repoRoot, worktree.branch)) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'missing_branch',
+        summary: `branch ${worktree.branch} is not available in git`,
+        command: `switchman worktree sync`,
+      });
+      continue;
+    }
+
+    if (activeLeases.has(worktree.name)) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'active_lease',
+        summary: 'an active lease is still running in this worktree',
+        command: `switchman status`,
+      });
+      continue;
+    }
+
+    if (alreadyQueued.has(worktree.name)) {
+      skipped.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        reason: 'already_queued',
+        summary: 'worktree is already in the landing queue',
+        command: `switchman queue status`,
+      });
+      continue;
+    }
+
+    const dirtyFiles = getWorktreeChangedFiles(worktree.path, repoRoot);
+    if (dirtyFiles.length > 0) {
+      blocked.push({
+        worktree: worktree.name,
+        branch: worktree.branch,
+        path: worktree.path,
+        files: dirtyFiles,
+        reason: 'dirty_worktree',
+        summary: `worktree has uncommitted changes: ${dirtyFiles.slice(0, 5).join(', ')}${dirtyFiles.length > 5 ? ` +${dirtyFiles.length - 5} more` : ''}`,
+        command: `cd ${JSON.stringify(worktree.path)} && git status`,
+      });
+      continue;
+    }
+
+    const freshness = gitAssessBranchFreshness(repoRoot, targetBranch, worktree.branch);
+    eligible.push({
+      worktree: worktree.name,
+      branch: worktree.branch,
+      path: worktree.path,
+      done_task_count: doneTasks.length,
+      done_task_titles: doneTasks.slice(0, 3).map((task) => task.title),
+      freshness,
+    });
+  }
+
+  return { eligible, blocked, skipped, queue_items: queueItems };
+}
+
+function printMergeDiscovery(discovery) {
+  console.log('');
+  console.log(chalk.bold(`Checking ${discovery.eligible.length + discovery.blocked.length + discovery.skipped.length} worktree(s)...`));
+
+  for (const entry of discovery.eligible) {
+    const freshness = entry.freshness?.state && entry.freshness.state !== 'unknown'
+      ? ` ${chalk.dim(`(${entry.freshness.state})`)}`
+      : '';
+    console.log(`  ${chalk.green('✓')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch)}${freshness}`);
+  }
+
+  for (const entry of discovery.blocked) {
+    console.log(`  ${chalk.yellow('!')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch || 'no branch')}  ${chalk.dim(`— ${entry.summary}`)}`);
+  }
+
+  for (const entry of discovery.skipped) {
+    if (entry.reason === 'no_completed_tasks') continue;
+    console.log(`  ${chalk.dim('·')} ${chalk.cyan(entry.worktree)}  ${chalk.dim(entry.branch || 'no branch')}  ${chalk.dim(`— ${entry.summary}`)}`);
+  }
+}
+
 // ─── Program ──────────────────────────────────────────────────────────────────
 
 program
@@ -2429,23 +2909,87 @@ program
   .version('0.1.0');
 
 program.showHelpAfterError('(run with --help for usage examples)');
+const ROOT_HELP_COMMANDS = new Set([
+  'advanced',
+  'demo',
+  'setup',
+  'verify-setup',
+  'login',
+  'upgrade',
+  'plan',
+  'task',
+  'status',
+  'merge',
+  'repair',
+  'help',
+]);
+program.configureHelp({
+  visibleCommands(cmd) {
+    const commands = Help.prototype.visibleCommands.call(this, cmd);
+    if (cmd.parent) return commands;
+    return commands.filter((command) => ROOT_HELP_COMMANDS.has(command.name()) && !command._switchmanAdvanced);
+  },
+});
 program.addHelpText('after', `
 Start here:
   switchman demo
-  switchman setup --agents 5
+  switchman setup --agents 3
+  switchman task add "Your task" --priority 8
   switchman status --watch
-  switchman gate ci
+  switchman gate ci && switchman queue run
 
-Most useful commands:
-  switchman task add "Implement auth helper" --priority 9
-  switchman lease next --json
-  switchman queue run --watch
+For you (the operator):
+  switchman demo
+  switchman setup
+  switchman task add
+  switchman status
+  switchman merge
+  switchman repair
+  switchman upgrade
+  switchman login
+  switchman plan "Add authentication"   (Pro)
+
+For your agents (via CLAUDE.md or MCP):
+  switchman lease next
+  switchman claim
+  switchman task done
+  switchman write
+  switchman wrap
 
 Docs:
   README.md
-  docs/setup-cursor.md
+  docs/setup-claude-code.md
+
+Power tools:
+  switchman advanced --help
 `);
 
+const advancedCmd = program
+  .command('advanced')
+  .description('Show advanced, experimental, and power-user command groups')
+  .addHelpText('after', `
+Advanced operator commands:
+  switchman pipeline <...>
+  switchman audit <...>
+  switchman policy <...>
+  switchman monitor <...>
+  switchman repair
+
+Experimental commands:
+  switchman semantic <...>
+  switchman object <...>
+
+Compatibility aliases:
+  switchman doctor
+
+Tip:
+  The main help keeps the day-one workflow small on purpose.
+`)
+  .action(() => {
+    advancedCmd.outputHelp();
+  });
+advancedCmd._switchmanAdvanced = false;
+
 program
   .command('demo')
   .description('Create a throwaway repo that proves overlapping claims are blocked and safe landing works')
@@ -2508,12 +3052,16 @@ program
       }
 
       const mcpConfigWrites = installMcpConfig([...new Set([repoRoot, ...gitWorktrees.map((wt) => wt.path)])]);
+      const mcpExclude = ensureProjectLocalMcpGitExcludes(repoRoot);
 
       db.close();
       spinner.succeed(`Initialized in ${chalk.cyan(repoRoot)}`);
       console.log(chalk.dim(`  Found and registered ${gitWorktrees.length} git worktree(s)`));
       console.log(chalk.dim(`  Database: .switchman/switchman.db`));
       console.log(chalk.dim(`  MCP config: ${mcpConfigWrites.filter((result) => result.changed).length} file(s) written`));
+      if (mcpExclude.managed) {
+        console.log(chalk.dim(`  MCP excludes: ${mcpExclude.changed ? 'updated' : 'already set'} in .git/info/exclude`));
+      }
       console.log('');
       console.log(`Next steps:`);
       console.log(`  ${chalk.cyan('switchman task add "Fix the login bug"')}  — add a task`);
@@ -2533,6 +3081,8 @@ program
   .description('One-command setup: create agent workspaces and initialise Switchman')
   .option('-a, --agents <n>', 'Number of agent workspaces to create (default: 3)', '3')
   .option('--prefix <prefix>', 'Branch prefix (default: switchman)', 'switchman')
+  .option('--no-monitor', 'Do not start the background rogue-edit monitor')
+  .option('--monitor-interval-ms <ms>', 'Polling interval for the background monitor', '2000')
   .addHelpText('after', `
 Examples:
   switchman setup --agents 5
@@ -2546,6 +3096,24 @@ Examples:
       process.exit(1);
     }
 
+        if (agentCount > FREE_AGENT_LIMIT) {
+      const licence = await checkLicence();
+      if (!licence.valid) {
+        console.log('');
+        console.log(chalk.yellow(`  ⚠  Free tier supports up to ${FREE_AGENT_LIMIT} agents.`));
+        console.log('');
+        console.log(`  You requested ${chalk.cyan(agentCount)} agents — that requires ${chalk.bold('Switchman Pro')}.`);
+        console.log('');
+        console.log(`  ${chalk.dim('Upgrade at:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+        console.log(`  ${chalk.dim('Or run:   ')} ${chalk.cyan('switchman upgrade')}`);
+        console.log('');
+        process.exit(1);
+      }
+      if (licence.offline) {
+        console.log(chalk.dim(`  Pro licence verified (offline cache · ${Math.ceil((7 * 24 * 60 * 60 * 1000 - (Date.now() - (licence.cached_at ?? 0))) / (24 * 60 * 60 * 1000))}d remaining)`));
+      }
+    }
+
     const repoRoot = getRepo();
     const spinner = ora('Setting up Switchman...').start();
 
@@ -2591,6 +3159,12 @@ Examples:
       }
 
       const mcpConfigWrites = installMcpConfig([...new Set([repoRoot, ...created.map((wt) => wt.path)])]);
+      const mcpExclude = ensureProjectLocalMcpGitExcludes(repoRoot);
+
+      const monitorIntervalMs = Math.max(100, Number.parseInt(opts.monitorIntervalMs, 10) || 2000);
+      const monitorState = opts.monitor
+        ? startBackgroundMonitor(repoRoot, { intervalMs: monitorIntervalMs, quarantine: false })
+        : null;
 
       db.close();
 
@@ -2610,6 +3184,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 +3206,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);
@@ -2800,6 +3395,132 @@ Examples:
   });
 
 
+// ── plan ──────────────────────────────────────────────────────────────────────
+
+program
+  .command('plan [goal]')
+  .description('Pro: suggest a parallel task plan from an explicit goal')
+  .option('--apply', 'Create the suggested tasks in Switchman')
+  .option('--max-tasks <n>', 'Maximum number of suggested tasks', '6')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman plan "Add authentication"
+  switchman plan "Add authentication" --apply
+`)
+  .action(async (goal, opts) => {
+    const repoRoot = getRepo();
+    const db = getOptionalDb(repoRoot);
+
+    try {
+      const licence = await checkLicence();
+      if (!licence.valid) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  AI planning requires Switchman Pro.'));
+        console.log(`  ${chalk.dim('Run:')} ${chalk.cyan('switchman upgrade')}`);
+        console.log(`  ${chalk.dim('Or visit:')} ${chalk.cyan(PRO_PAGE_URL)}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
+      }
+
+      if (!goal || !goal.trim()) {
+        console.log('');
+        console.log(chalk.yellow('  ⚠  AI planning currently requires an explicit goal.'));
+        console.log(`  ${chalk.dim('Try:')} ${chalk.cyan('switchman plan "Add authentication"')}`);
+        console.log(`  ${chalk.dim('Then:')} ${chalk.cyan('switchman plan "Add authentication" --apply')}`);
+        console.log('');
+        process.exitCode = 1;
+        return;
+      }
+
+      const context = collectPlanContext(repoRoot, goal || null);
+      const planningWorktrees = resolvePlanningWorktrees(repoRoot, db);
+      const pipelineId = `plan-${slugifyValue(context.title)}-${Date.now().toString(36)}`;
+      const plannedTasks = planPipelineTasks({
+        pipelineId,
+        title: context.title,
+        description: context.description,
+        worktrees: planningWorktrees,
+        maxTasks: Math.max(1, parseInt(opts.maxTasks, 10) || 6),
+        repoRoot,
+      });
+
+      if (opts.json) {
+        const payload = {
+          title: context.title,
+          context: {
+            found: context.found,
+            used: context.used,
+            branch: context.branch,
+          },
+          planned_tasks: plannedTasks.map((task) => ({
+            id: task.id,
+            title: task.title,
+            suggested_worktree: task.suggested_worktree || null,
+            task_type: task.task_spec?.task_type || null,
+            dependencies: task.dependencies || [],
+          })),
+          apply_ready: Boolean(db),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(chalk.bold('Reading repo context...'));
+      if (context.found.length > 0) {
+        console.log(`${chalk.dim('Found:')} ${context.found.join(', ')}`);
+      } else {
+        console.log(chalk.dim('Found: local repo context only'));
+      }
+      console.log('');
+      console.log(`${chalk.bold('Suggested plan based on:')} ${context.used.length > 0 ? formatHumanList(context.used) : 'available repo context'}`);
+      console.log('');
+
+      plannedTasks.forEach((task, index) => {
+        const worktreeLabel = task.suggested_worktree ? chalk.cyan(task.suggested_worktree) : chalk.dim('unassigned');
+        console.log(`  ${chalk.green('✓')} ${chalk.bold(`${index + 1}.`)} ${task.title}  ${chalk.dim('→')} ${worktreeLabel}`);
+      });
+
+      if (!opts.apply) {
+        console.log('');
+        if (!db) {
+          console.log(chalk.dim('Preview only — run `switchman setup --agents 3` first if you want Switchman to create and track these tasks.'));
+        } else {
+          console.log(chalk.dim('Preview only — rerun with `switchman plan --apply` to create these tasks.'));
+        }
+        return;
+      }
+
+      if (!db) {
+        console.log('');
+        console.log(`${chalk.red('✗')} Switchman is not set up in this repo yet.`);
+        console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman setup --agents 3')}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      console.log('');
+      for (const task of plannedTasks) {
+        createTask(db, {
+          id: task.id,
+          title: task.title,
+          description: `Planned from: ${context.title}`,
+          priority: planTaskPriority(task.task_spec),
+        });
+        upsertTaskSpec(db, task.id, task.task_spec);
+        console.log(`  ${chalk.green('✓')} Created ${chalk.cyan(task.id)} ${chalk.dim(task.title)}`);
+      }
+
+      console.log('');
+      console.log(`${chalk.green('✓')} Planned ${plannedTasks.length} task(s) from repo context.`);
+      console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman status --watch')}`);
+    } finally {
+      db?.close();
+    }
+  });
+
+
 // ── task ──────────────────────────────────────────────────────────────────────
 
 const taskCmd = program.command('task').description('Manage the task list');
@@ -2828,6 +3549,7 @@ taskCmd
     db.close();
     const scopeWarning = analyzeTaskScope(title, opts.description || '');
     console.log(`${chalk.green('✓')} Task created: ${chalk.cyan(taskId)}`);
+    pushSyncEvent('task_added', { task_id: taskId, title, priority: parseInt(opts.priority) }).catch(() => {});
     console.log(`  ${chalk.dim(title)}`);
     if (scopeWarning) {
       console.log(chalk.yellow(`  warning: ${scopeWarning.summary}`));
@@ -2901,6 +3623,7 @@ taskCmd
     }
 
     console.log(`${chalk.green('✓')} Reset ${chalk.cyan(task.id)} to pending`);
+    pushSyncEvent('task_retried', { task_id: task.id, title: task.title, reason: opts.reason || 'manual retry' }).catch(() => {});
     console.log(`  ${chalk.dim('title:')} ${task.title}`);
     console.log(`${chalk.yellow('next:')} switchman task assign ${task.id} <workspace>`);
   });
@@ -2932,6 +3655,12 @@ taskCmd
     }
 
     console.log(`${chalk.green('✓')} Reset ${result.retried.length} stale task(s) to pending`);
+    pushSyncEvent('task_retried', {
+      pipeline_id: result.pipeline_id || null,
+      task_count: result.retried.length,
+      task_ids: result.retried.map((task) => task.id),
+      reason: opts.reason,
+    }).catch(() => {});
     if (result.pipeline_id) {
       console.log(`  ${chalk.dim('pipeline:')} ${result.pipeline_id}`);
     }
@@ -2945,8 +3674,25 @@ taskCmd
   .action((taskId) => {
     const repoRoot = getRepo();
     try {
-      completeTaskWithRetries(repoRoot, taskId);
+      const result = completeTaskWithRetries(repoRoot, taskId);
+      if (result?.status === 'already_done') {
+        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} was already marked done — no new changes were recorded`);
+        return;
+      }
+      if (result?.status === 'failed') {
+        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} is currently failed — retry it before marking it done again`);
+        return;
+      }
+      if (result?.status === 'not_in_progress') {
+        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} is not currently in progress — start a lease before marking it done`);
+        return;
+      }
+      if (result?.status === 'no_active_lease') {
+        console.log(`${chalk.yellow('!')} Task ${chalk.cyan(taskId)} has no active lease — reacquire the task before marking it done`);
+        return;
+      }
       console.log(`${chalk.green('✓')} Task ${chalk.cyan(taskId)} marked done — file claims released`);
+      pushSyncEvent('task_done', { task_id: taskId }).catch(() => {});
     } catch (err) {
       console.error(chalk.red(err.message));
       process.exitCode = 1;
@@ -2963,6 +3709,7 @@ taskCmd
     releaseFileClaims(db, taskId);
     db.close();
     console.log(`${chalk.red('✗')} Task ${chalk.cyan(taskId)} marked failed`);
+    pushSyncEvent('task_failed', { task_id: taskId, reason: reason || null }).catch(() => {});
   });
 
 taskCmd
@@ -3090,6 +3837,13 @@ Pipeline landing rule:
 
       const result = enqueueMergeItem(db, payload);
       db.close();
+      pushSyncEvent('queue_added', {
+        item_id: result.id,
+        source_type: result.source_type,
+        source_ref: result.source_ref,
+        source_worktree: result.source_worktree || null,
+        target_branch: result.target_branch,
+      }, { worktree: result.source_worktree || null }).catch(() => {});
 
       if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -3177,6 +3931,15 @@ What it helps you answer:
       return;
     }
 
+    if (items.length === 0) {
+      console.log('');
+      console.log(chalk.bold('switchman queue status'));
+      console.log('');
+      console.log('Queue is empty.');
+      console.log(`Add finished work with: ${chalk.cyan('switchman queue add --worktree agent1')}`);
+      return;
+    }
+
     const queueHealth = summary.counts.blocked > 0
       ? 'block'
       : summary.counts.retrying > 0 || summary.counts.held > 0 || summary.counts.wave_blocked > 0 || summary.counts.escalated > 0
@@ -3389,9 +4152,26 @@ Examples:
       for (const entry of aggregate.processed) {
         const item = entry.item;
         if (entry.status === 'merged') {
+          pushSyncEvent('queue_merged', {
+            item_id: item.id,
+            source_type: item.source_type,
+            source_ref: item.source_ref,
+            source_worktree: item.source_worktree || null,
+            target_branch: item.target_branch,
+            merged_commit: item.merged_commit || null,
+          }, { worktree: item.source_worktree || null }).catch(() => {});
           console.log(`${chalk.green('✓')} Merged ${chalk.cyan(item.id)} into ${chalk.bold(item.target_branch)}`);
           console.log(`  ${chalk.dim('commit:')} ${item.merged_commit}`);
         } else {
+          pushSyncEvent('queue_blocked', {
+            item_id: item.id,
+            source_type: item.source_type,
+            source_ref: item.source_ref,
+            source_worktree: item.source_worktree || null,
+            target_branch: item.target_branch,
+            error_code: item.last_error_code || null,
+            error_summary: item.last_error_summary || null,
+          }, { worktree: item.source_worktree || null }).catch(() => {});
           console.log(`${chalk.red('✗')} Blocked ${chalk.cyan(item.id)}`);
           console.log(`  ${chalk.red('why:')} ${item.last_error_summary}`);
           if (item.next_action) console.log(`  ${chalk.yellow('next:')} ${item.next_action}`);
@@ -3415,8 +4195,144 @@ Examples:
     }
   });
 
-queueCmd
-  .command('retry <itemId>')
+program
+  .command('merge')
+  .description('Queue finished worktrees and land safe work through one guided front door')
+  .option('--target <branch>', 'Target branch to merge into', 'main')
+  .option('--dry-run', 'Preview mergeable work without queueing or landing anything')
+  .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman merge
+  switchman merge --dry-run
+  switchman merge --target release
+`)
+  .action(async (opts) => {
+    const repoRoot = getRepo();
+    const db = getDb(repoRoot);
+
+    try {
+      const discovery = discoverMergeCandidates(db, repoRoot, { targetBranch: opts.target || 'main' });
+      const queued = [];
+
+      for (const entry of discovery.eligible) {
+        queued.push(enqueueMergeItem(db, {
+          sourceType: 'worktree',
+          sourceRef: entry.branch,
+          sourceWorktree: entry.worktree,
+          targetBranch: opts.target || 'main',
+          submittedBy: 'switchman merge',
+        }));
+      }
+
+      const queueItems = listMergeQueue(db);
+      const summary = buildQueueStatusSummary(queueItems, { db, repoRoot });
+      const mergeOrder = summary.recommended_sequence
+        .filter((item) => ['land_now', 'prepare_next'].includes(item.lane))
+        .map((item) => item.source_ref);
+
+      if (opts.json) {
+        if (opts.dryRun) {
+          console.log(JSON.stringify({ discovery, queued, summary, merge_order: mergeOrder, dry_run: true }, null, 2));
+          db.close();
+          return;
+        }
+
+        const gate = await evaluateQueueRepoGate(db, repoRoot);
+        const runnableCount = listMergeQueue(db).filter((item) => ['queued', 'retrying'].includes(item.status)).length;
+        const result = gate.ok
+          ? await runMergeQueue(db, repoRoot, {
+            targetBranch: opts.target || 'main',
+            maxItems: Math.max(1, runnableCount),
+            mergeBudget: Math.max(1, runnableCount),
+            followPlan: false,
+          })
+          : null;
+        console.log(JSON.stringify({ discovery, queued, summary, merge_order: mergeOrder, gate, result }, null, 2));
+        db.close();
+        return;
+      }
+
+      printMergeDiscovery(discovery);
+
+      if (discovery.blocked.length > 0) {
+        console.log('');
+        console.log(chalk.bold('Needs attention before landing:'));
+        for (const entry of discovery.blocked) {
+          console.log(`  ${chalk.yellow(entry.worktree)}: ${entry.summary}`);
+          console.log(`    ${chalk.dim('run:')} ${chalk.cyan(entry.command)}`);
+        }
+      }
+
+      if (mergeOrder.length > 0) {
+        console.log('');
+        console.log(`${chalk.bold('Merge order:')} ${mergeOrder.join(' → ')}`);
+      }
+
+      if (opts.dryRun) {
+        console.log('');
+        console.log(chalk.dim('Dry run only — nothing was landed.'));
+        db.close();
+        return;
+      }
+
+      if (discovery.eligible.length === 0) {
+        console.log('');
+        console.log(chalk.dim('No finished worktrees are ready to land yet.'));
+        console.log(`${chalk.yellow('next:')} ${chalk.cyan('switchman status')}`);
+        db.close();
+        return;
+      }
+
+      const gate = await evaluateQueueRepoGate(db, repoRoot);
+      if (!gate.ok) {
+        console.log('');
+        console.log(`${chalk.red('✗')} Merge gate blocked landing`);
+        console.log(`  ${chalk.dim(gate.summary)}`);
+        console.log(`  ${chalk.yellow('next:')} ${chalk.cyan('switchman gate ci')}`);
+        db.close();
+        return;
+      }
+
+      console.log('');
+      const runnableCount = listMergeQueue(db).filter((item) => ['queued', 'retrying'].includes(item.status)).length;
+      const result = await runMergeQueue(db, repoRoot, {
+        targetBranch: opts.target || 'main',
+        maxItems: Math.max(1, runnableCount),
+        mergeBudget: Math.max(1, runnableCount),
+        followPlan: false,
+      });
+
+      const merged = result.processed.filter((item) => item.status === 'merged');
+      for (const mergedItem of merged) {
+        console.log(`  ${chalk.green('✓')} Landed ${chalk.cyan(mergedItem.item.source_ref)} into ${chalk.bold(mergedItem.item.target_branch)}`);
+      }
+
+      if (merged.length > 0 && !result.deferred && result.processed.every((item) => item.status === 'merged')) {
+        console.log('');
+        console.log(`${chalk.green('✓')} Done. ${merged.length} worktree(s) landed cleanly.`);
+        db.close();
+        return;
+      }
+
+      const blocked = result.processed.find((item) => item.status !== 'merged')?.item || result.deferred || null;
+      if (blocked) {
+        console.log('');
+        console.log(`${chalk.yellow('!')} Landing stopped at ${chalk.cyan(blocked.source_ref)}`);
+        if (blocked.last_error_summary) console.log(`  ${chalk.dim(blocked.last_error_summary)}`);
+        if (blocked.next_action) console.log(`  ${chalk.yellow('next:')} ${blocked.next_action}`);
+      }
+
+      db.close();
+    } catch (err) {
+      db.close();
+      console.error(chalk.red(err.message));
+      process.exitCode = 1;
+    }
+  });
+
+queueCmd
+  .command('retry <itemId>')
   .description('Retry a blocked merge queue item')
   .option('--json', 'Output raw JSON')
   .action((itemId, opts) => {
@@ -3771,6 +4687,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"
@@ -4621,6 +5538,7 @@ Examples:
     }
 
     console.log(`${chalk.green('✓')} Lease acquired: ${chalk.bold(task.title)}`);
+    pushSyncEvent('lease_acquired', { task_id: task.id, title: task.title }, { worktree: worktreeName }).catch(() => {});
     console.log(`  ${chalk.dim('task:')} ${task.id}  ${chalk.dim('lease:')} ${lease.id}`);
     console.log(`  ${chalk.dim('worktree:')} ${chalk.cyan(worktreeName)}  ${chalk.dim('priority:')} ${task.priority}`);
   });
@@ -4803,25 +5721,31 @@ wtCmd
     const db = getDb(repoRoot);
     const worktrees = listWorktrees(db);
     const gitWorktrees = listGitWorktrees(repoRoot);
-    db.close();
 
     if (!worktrees.length && !gitWorktrees.length) {
+      db.close();
       console.log(chalk.dim('No workspaces found. Run `switchman setup --agents 3` or `switchman worktree sync`.'));
       return;
     }
 
     // Show git worktrees (source of truth) annotated with db info
+    const complianceReport = evaluateRepoCompliance(db, repoRoot, gitWorktrees);
     console.log('');
     console.log(chalk.bold('Git Worktrees:'));
     for (const wt of gitWorktrees) {
       const dbInfo = worktrees.find(d => d.path === wt.path);
+      const complianceInfo = complianceReport.worktreeCompliance.find((entry) => entry.worktree === wt.name) || null;
       const agent = dbInfo?.agent ? chalk.cyan(dbInfo.agent) : chalk.dim('no agent');
       const status = dbInfo?.status ? statusBadge(dbInfo.status) : chalk.dim('unregistered');
-      const compliance = dbInfo?.compliance_state ? statusBadge(dbInfo.compliance_state) : chalk.dim('unknown');
+      const compliance = complianceInfo?.compliance_state ? statusBadge(complianceInfo.compliance_state) : dbInfo?.compliance_state ? statusBadge(dbInfo.compliance_state) : chalk.dim('unknown');
       console.log(`  ${chalk.bold(wt.name.padEnd(20))} ${status} ${compliance} branch: ${chalk.cyan(wt.branch || 'unknown')}  agent: ${agent}`);
       console.log(`    ${chalk.dim(wt.path)}`);
+      if ((complianceInfo?.unclaimed_changed_files || []).length > 0) {
+        console.log(`    ${chalk.red('files:')} ${complianceInfo.unclaimed_changed_files.slice(0, 5).join(', ')}${complianceInfo.unclaimed_changed_files.length > 5 ? ` ${chalk.dim(`+${complianceInfo.unclaimed_changed_files.length - 5} more`)}` : ''}`);
+      }
     }
     console.log('');
+    db.close();
   });
 
 wtCmd
@@ -4845,13 +5769,14 @@ program
   .command('claim <taskId> <worktree> [files...]')
   .description('Lock files for a task before editing')
   .option('--agent <name>', 'Agent name')
-  .option('--force', 'Claim even if conflicts exist')
+  .option('--force', 'Emergency override for manual recovery when a conflicting claim is known to be stale or wrong')
   .addHelpText('after', `
 Examples:
   switchman claim task-123 agent2 src/auth.js src/server.js
   switchman claim task-123 agent2 src/auth.js --agent cursor
 
 Use this before editing files in a shared repo.
+Only use --force for operator-led recovery after checking switchman status or switchman explain claim <path>.
 `)
   .action((taskId, worktree, files, opts) => {
     if (!files.length) {
@@ -4870,7 +5795,7 @@ Use this before editing files in a shared repo.
         for (const c of conflicts) {
           console.log(`  ${chalk.yellow(c.file)} → already claimed by worktree ${chalk.cyan(c.claimedBy.worktree)} (task: ${c.claimedBy.task_title})`);
         }
-        console.log(chalk.dim('\nUse --force to claim anyway, or pick different files first.'));
+        console.log(chalk.dim('\nDo not use --force as a shortcut. Check status or explain the claim first, then only override if the existing claim is known-bad.'));
         console.log(`${chalk.yellow('next:')} switchman status`);
         process.exitCode = 1;
         return;
@@ -4878,6 +5803,12 @@ Use this before editing files in a shared repo.
 
       const lease = claimFiles(db, taskId, worktree, files, opts.agent);
       console.log(`${chalk.green('✓')} Claimed ${files.length} file(s) for task ${chalk.cyan(taskId)} (${chalk.dim(lease.id)})`);
+      pushSyncEvent('claim_added', {
+        task_id: taskId,
+        lease_id: lease.id,
+        file_count: files.length,
+        files: files.slice(0, 10),
+      }, { worktree }).catch(() => {});
       files.forEach(f => console.log(`  ${chalk.dim(f)}`));
     } catch (err) {
       printErrorWithNext(err.message, 'switchman task list --status in_progress');
@@ -4893,9 +5824,11 @@ program
   .action((taskId) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
+    const task = getTask(db, taskId);
     releaseFileClaims(db, taskId);
     db.close();
     console.log(`${chalk.green('✓')} Released all claims for task ${chalk.cyan(taskId)}`);
+    pushSyncEvent('claim_released', { task_id: taskId }, { worktree: task?.worktree || null }).catch(() => {});
   });
 
 program
@@ -5171,12 +6104,14 @@ program
   .description('Show one dashboard view of what is running, blocked, and ready next')
   .option('--json', 'Output raw JSON')
   .option('--watch', 'Keep refreshing status in the terminal')
+  .option('--repair', 'Repair safe interrupted queue and pipeline state before rendering status')
   .option('--watch-interval-ms <n>', 'Polling interval for --watch mode', '2000')
   .option('--max-cycles <n>', 'Maximum refresh cycles before exiting', '0')
   .addHelpText('after', `
 Examples:
   switchman status
   switchman status --watch
+  switchman status --repair
   switchman status --json
 
 Use this first when the repo feels stuck.
@@ -5194,13 +6129,40 @@ Use this first when the repo feels stuck.
         console.clear();
       }
 
+      let repairResult = null;
+      if (opts.repair) {
+        const repairDb = getDb(repoRoot);
+        try {
+          repairResult = repairRepoState(repairDb, repoRoot);
+        } finally {
+          repairDb.close();
+        }
+      }
+
       const report = await collectStatusSnapshot(repoRoot);
+      const [teamActivity, teamState] = await Promise.all([
+        pullActiveTeamMembers(),
+        pullTeamState(),
+      ]);
+      const myUserId = readCredentials()?.user_id;
+      const otherMembers = teamActivity.filter(e => e.user_id !== myUserId);
+      const teamSummary = summarizeTeamCoordinationState(teamState, myUserId);
       cycles += 1;
 
       if (opts.json) {
-        console.log(JSON.stringify(watch ? { ...report, watch: true, cycles } : report, null, 2));
+        const payload = watch ? { ...report, watch: true, cycles } : report;
+        const withTeam = { ...payload, team_sync: { summary: teamSummary, recent_events: teamState.filter((event) => event.user_id !== myUserId).slice(0, 25) } };
+        console.log(JSON.stringify(opts.repair ? { ...withTeam, repair: repairResult } : withTeam, null, 2));
       } else {
-        renderUnifiedStatusReport(report);
+        if (opts.repair && repairResult) {
+          printRepairSummary(repairResult, {
+            repairedHeading: `${chalk.green('✓')} Repaired safe interrupted repo state before rendering status`,
+            noRepairHeading: `${chalk.green('✓')} No repo repair action needed before rendering status`,
+            limit: 6,
+          });
+          console.log('');
+        }
+        renderUnifiedStatusReport(report, { teamActivity: otherMembers, teamSummary });
         if (watch) {
           const signature = buildWatchSignature(report);
           const watchState = lastSignature === null
@@ -5267,9 +6229,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', `
@@ -5407,6 +6371,7 @@ Examples:
 `);
 
 const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
+auditCmd._switchmanAdvanced = true;
 
 auditCmd
   .command('change <pipelineId>')
@@ -5729,6 +6694,7 @@ gateCmd
 const semanticCmd = program
   .command('semantic')
   .description('Inspect or materialize the derived semantic code-object view');
+semanticCmd._switchmanAdvanced = true;
 
 semanticCmd
   .command('materialize')
@@ -5745,6 +6711,7 @@ semanticCmd
 const objectCmd = program
   .command('object')
   .description('Experimental object-source mode backed by canonical exported code objects');
+objectCmd._switchmanAdvanced = true;
 
 objectCmd
   .command('import')
@@ -5826,6 +6793,7 @@ objectCmd
 // ── monitor ──────────────────────────────────────────────────────────────────
 
 const monitorCmd = program.command('monitor').description('Observe workspaces for runtime file changes');
+monitorCmd._switchmanAdvanced = true;
 
 monitorCmd
   .command('once')
@@ -5835,7 +6803,7 @@ monitorCmd
   .action((opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
-    const worktrees = listGitWorktrees(repoRoot);
+    const worktrees = resolveMonitoredWorktrees(db, repoRoot);
     const result = monitorWorktreesOnce(db, repoRoot, worktrees, { quarantine: opts.quarantine });
     db.close();
 
@@ -5851,9 +6819,7 @@ monitorCmd
 
     console.log(`${chalk.green('✓')} Observed ${result.summary.total} file change(s)`);
     for (const event of result.events) {
-      const badge = event.status === 'allowed' ? chalk.green('ALLOWED') : chalk.red('DENIED ');
-      const action = event.enforcement_action ? ` ${chalk.dim(event.enforcement_action)}` : '';
-      console.log(`  ${badge} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${event.reason_code ? ` ${chalk.dim(event.reason_code)}` : ''}${action}`);
+      renderMonitorEvent(event);
     }
   });
 
@@ -5887,14 +6853,12 @@ monitorCmd
 
     while (!stopped) {
       const db = getDb(repoRoot);
-      const worktrees = listGitWorktrees(repoRoot);
+      const worktrees = resolveMonitoredWorktrees(db, repoRoot);
       const result = monitorWorktreesOnce(db, repoRoot, worktrees, { quarantine: opts.quarantine });
       db.close();
 
       for (const event of result.events) {
-        const badge = event.status === 'allowed' ? chalk.green('ALLOWED') : chalk.red('DENIED ');
-        const action = event.enforcement_action ? ` ${chalk.dim(event.enforcement_action)}` : '';
-        console.log(`  ${badge} ${chalk.cyan(event.worktree)} ${chalk.yellow(event.file_path)} ${chalk.dim(event.change_type)}${event.reason_code ? ` ${chalk.dim(event.reason_code)}` : ''}${action}`);
+        renderMonitorEvent(event);
       }
 
       if (stopped) break;
@@ -5912,39 +6876,18 @@ monitorCmd
   .action((opts) => {
     const repoRoot = getRepo();
     const intervalMs = Number.parseInt(opts.intervalMs, 10);
-    const existingState = readMonitorState(repoRoot);
+    const state = startBackgroundMonitor(repoRoot, {
+      intervalMs,
+      quarantine: Boolean(opts.quarantine),
+    });
 
-    if (existingState && isProcessRunning(existingState.pid)) {
-      console.log(chalk.yellow(`Monitor already running with pid ${existingState.pid}`));
+    if (state.already_running) {
+      console.log(chalk.yellow(`Monitor already running with pid ${state.state.pid}`));
       return;
     }
 
-    const logPath = join(repoRoot, '.switchman', 'monitor.log');
-    const child = spawn(process.execPath, [
-      process.argv[1],
-      'monitor',
-      'watch',
-      '--interval-ms',
-      String(intervalMs),
-      ...(opts.quarantine ? ['--quarantine'] : []),
-      '--daemonized',
-    ], {
-      cwd: repoRoot,
-      detached: true,
-      stdio: 'ignore',
-    });
-    child.unref();
-
-    const statePath = writeMonitorState(repoRoot, {
-      pid: child.pid,
-      interval_ms: intervalMs,
-      quarantine: Boolean(opts.quarantine),
-      log_path: logPath,
-      started_at: new Date().toISOString(),
-    });
-
-    console.log(`${chalk.green('✓')} Started monitor pid ${chalk.cyan(String(child.pid))}`);
-    console.log(`${chalk.dim('State:')} ${statePath}`);
+    console.log(`${chalk.green('✓')} Started monitor pid ${chalk.cyan(String(state.state.pid))}`);
+    console.log(`${chalk.dim('State:')} ${state.state_path}`);
   });
 
 monitorCmd
@@ -5996,9 +6939,38 @@ monitorCmd
     console.log(`  ${chalk.dim('started_at')} ${state.started_at}`);
   });
 
+program
+  .command('watch')
+  .description('Watch worktrees for direct writes and rogue edits in real time')
+  .option('--interval-ms <ms>', 'Polling interval in milliseconds', '2000')
+  .option('--quarantine', 'Move or restore denied runtime changes immediately after detection')
+  .action(async (opts) => {
+    const repoRoot = getRepo();
+    const child = spawn(process.execPath, [
+      process.argv[1],
+      'monitor',
+      'watch',
+      '--interval-ms',
+      String(opts.intervalMs || '2000'),
+      ...(opts.quarantine ? ['--quarantine'] : []),
+    ], {
+      cwd: repoRoot,
+      stdio: 'inherit',
+    });
+
+    await new Promise((resolve, reject) => {
+      child.on('exit', (code) => {
+        process.exitCode = code ?? 0;
+        resolve();
+      });
+      child.on('error', reject);
+    });
+  });
+
 // ── policy ───────────────────────────────────────────────────────────────────
 
 const policyCmd = program.command('policy').description('Manage enforcement and change-governance policy');
+policyCmd._switchmanAdvanced = true;
 
 policyCmd
   .command('init')
@@ -6144,4 +7116,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();