switchman-dev 0.1.7 → 0.1.9

package/src/cli/commands/audit.js

@@ -0,0 +1,77 @@
+export function registerAuditCommands(program, {
+  buildPipelineHistoryReport,
+  chalk,
+  getDb,
+  getRepo,
+  printErrorWithNext,
+  statusBadge,
+  verifyAuditTrail,
+}) {
+  const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
+  auditCmd._switchmanAdvanced = true;
+
+  auditCmd
+    .command('change <pipelineId>')
+    .description('Show a signed, operator-friendly history for one pipeline')
+    .option('--json', 'Output raw JSON')
+    .action((pipelineId, options) => {
+      const repoRoot = getRepo();
+      const db = getDb(repoRoot);
+
+      try {
+        const report = buildPipelineHistoryReport(db, repoRoot, pipelineId);
+        db.close();
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+          return;
+        }
+
+        console.log(chalk.bold(`Audit history for pipeline ${report.pipeline_id}`));
+        console.log(`  ${chalk.dim('title:')} ${report.title}`);
+        console.log(`  ${chalk.dim('events:')} ${report.events.length}`);
+        console.log(`  ${chalk.yellow('next:')} ${report.next_action}`);
+        for (const event of report.events.slice(-20)) {
+          const status = event.status ? ` ${statusBadge(event.status).trim()}` : '';
+          console.log(`  ${chalk.dim(event.created_at)} ${chalk.cyan(event.label)}${status}`);
+          console.log(`    ${event.summary}`);
+        }
+      } catch (err) {
+        db.close();
+        printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
+        process.exitCode = 1;
+      }
+    });
+
+  auditCmd
+    .command('verify')
+    .description('Verify the audit log hash chain and project signatures')
+    .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);
+    });
+
+  return auditCmd;
+}

package/src/cli/commands/claude.js

@@ -0,0 +1,37 @@
+export function registerClaudeCommands(program, {
+  chalk,
+  existsSync,
+  getRepo,
+  join,
+  renderClaudeGuide,
+  writeFileSync,
+}) {
+  const claudeCmd = program.command('claude').description('Generate or refresh Claude Code instructions for this repo');
+
+  claudeCmd
+    .command('refresh')
+    .description('Generate a repo-aware CLAUDE.md for this repository')
+    .option('--print', 'Print the generated guide instead of writing CLAUDE.md')
+    .addHelpText('after', `
+Examples:
+  switchman claude refresh
+  switchman claude refresh --print
+`)
+    .action((opts) => {
+      const repoRoot = getRepo();
+      const claudeGuidePath = join(repoRoot, 'CLAUDE.md');
+      const content = renderClaudeGuide(repoRoot);
+
+      if (opts.print) {
+        process.stdout.write(content);
+        return;
+      }
+
+      const existed = existsSync(claudeGuidePath);
+      writeFileSync(claudeGuidePath, content, 'utf8');
+      console.log(`${chalk.green('✓')} ${existed ? 'Refreshed' : 'Created'} ${chalk.cyan(claudeGuidePath)}`);
+      console.log(`  ${chalk.dim('next:')} ${chalk.cyan('switchman verify-setup')}`);
+    });
+
+  return claudeCmd;
+}

package/src/cli/commands/gate.js

@@ -0,0 +1,278 @@
+export function registerGateCommands(program, {
+  chalk,
+  getDb,
+  getRepo,
+  installGateHooks,
+  installGitHubActionsWorkflow,
+  maybeCaptureTelemetry,
+  resolveGitHubOutputTargets,
+  runAiMergeGate,
+  runCommitGate,
+  scanAllWorktrees,
+  writeGitHubCiStatus,
+}) {
+  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
+`);
+
+  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])}`);
+            }
+          }
+        }
+
+        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)}`);
+          }
+        }
+
+        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 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)}`);
+            }
+          }
+        }
+      }
+
+      if (result.status === 'blocked') process.exitCode = 1;
+    });
+
+  return gateCmd;
+}

package/src/cli/commands/lease.js

@@ -0,0 +1,256 @@
+export function registerLeaseCommands(program, {
+  acquireNextTaskLeaseWithRetries,
+  chalk,
+  getCurrentWorktreeName,
+  getDb,
+  getRepo,
+  getTask,
+  heartbeatLease,
+  listLeases,
+  loadLeasePolicy,
+  pushSyncEvent,
+  reapStaleLeases,
+  startTaskLease,
+  statusBadge,
+  taskJsonWithLease,
+  writeLeasePolicy,
+}) {
+  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 console.log(chalk.red('Could not start a work session. The task may not exist or may already be in progress.'));
+        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)}`);
+      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}`);
+    });
+
+  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 console.log(chalk.red(`No active work session found for ${leaseId}.`));
+        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;
+      }
+
+      console.log(`${chalk.green('✓')} Lease policy updated`);
+      console.log(`  ${chalk.dim(path)}`);
+      console.log(`  ${chalk.dim('heartbeat_interval_seconds:')} ${saved.heartbeat_interval_seconds}`);
+      console.log(`  ${chalk.dim('stale_after_minutes:')} ${saved.stale_after_minutes}`);
+      console.log(`  ${chalk.dim('reap_on_status_check:')} ${saved.reap_on_status_check}`);
+      console.log(`  ${chalk.dim('requeue_task_on_reap:')} ${saved.requeue_task_on_reap}`);
+    });
+
+  leasePolicyCmd
+    .description('Show the active stale-lease policy for this repo')
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
+      const repoRoot = getRepo();
+      const policy = loadLeasePolicy(repoRoot);
+      if (opts.json) {
+        console.log(JSON.stringify({ policy }, null, 2));
+        return;
+      }
+
+      console.log(chalk.bold('Lease policy'));
+      console.log(`  ${chalk.dim('heartbeat_interval_seconds:')} ${policy.heartbeat_interval_seconds}`);
+      console.log(`  ${chalk.dim('stale_after_minutes:')} ${policy.stale_after_minutes}`);
+      console.log(`  ${chalk.dim('reap_on_status_check:')} ${policy.reap_on_status_check}`);
+      console.log(`  ${chalk.dim('requeue_task_on_reap:')} ${policy.requeue_task_on_reap}`);
+    });
+
+  return leaseCmd;
+}