dw-kit 1.4.0 → 1.7.0-rc.1

package/src/cli.mjs

@@ -93,6 +93,318 @@ export function run(argv) {
       console.log(chalk.green('✓') + ` Wrote ${target}`);
     });
 
+  const taskCmd = program
+    .command('task')
+    .description('v3 task docs operations (ADR-0008): show · new · migrate · lint');
+
+  taskCmd
+    .command('show [task-name]')
+    .description('Print ANSI snapshot (status + subtask tracker) of a v3 task')
+    .option('-v, --verbose', 'Include Section 1 Snapshot body')
+    .action(async (taskName, opts) => {
+      const { taskShowCommand } = await import('./commands/task-show.mjs');
+      await taskShowCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('new <task-name>')
+    .description('Scaffold a new v3 task from template')
+    .option('-d, --depth <level>', 'quick | standard | thorough', 'standard')
+    .option('-t, --title <title>', 'Human-readable task title')
+    .option('-o, --owner <name>', 'Task owner', '')
+    .option('-a, --adr <ref>', 'Related ADR (ADR-NNNN or none)', 'none')
+    .option('--target <ship>', 'Target ship milestone', 'TBD')
+    .action(async (taskName, opts) => {
+      const { taskNewCommand } = await import('./commands/task-new.mjs');
+      await taskNewCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('migrate [task-name]')
+    .description('Migrate v2 spec.md + tracking.md → v3 task.md, OR bump v3.0 → v3.1 schema (--to-v3.1)')
+    .option('-n, --dry-run', 'Preview without writing')
+    .option('--diff', 'Show diff against existing task.md')
+    .option('--all', 'Scan and migrate all v2 tasks (or all v3.0 tasks when --to-v3.1)')
+    .option('--force', 'Overwrite existing task.md')
+    .option('--remove-v2', 'Delete spec.md/tracking.md after backup (default keeps them)')
+    .option('--rollback', 'Restore v2 files from .v2bak backups (requires task name)')
+    .option('--to-v3-1', 'Bump v3.0 → v3.1 schema (adds optional parent_goal_id, contributing_goal_ids, summary fields per ADR-0010)')
+    .action(async (taskName, opts) => {
+      const { taskMigrateCommand } = await import('./commands/task-migrate.mjs');
+      await taskMigrateCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('lint [task-name]')
+    .description('Lint v3 task.md: schema validate + drift markers + line caps')
+    .option('-l, --level <level>', 'strict | warn | off (overrides config)', '')
+    .action(async (taskName, opts) => {
+      const { lintTaskCommand } = await import('./commands/lint-task.mjs');
+      await lintTaskCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('rotate [task-name]')
+    .description('Auto-rotate Section 4 (Timeline/Changelog) > 400 lines to timeline-history.md (keeps last 8 entries)')
+    .option('-n, --dry-run', 'Preview without writing')
+    .option('-q, --quiet', 'Suppress output (hook usage)')
+    .action(async (taskName, opts) => {
+      const { taskRotateCommand } = await import('./commands/task-rotate.mjs');
+      await taskRotateCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('render [task-name]')
+    .description('Render timeline.svg sidecar via dw-kit-render sub-package; falls back to Mermaid block in Section 4 if absent')
+    .option('-n, --dry-run', 'Print manifest without writing files')
+    .option('-f, --format <kind>', 'svg | png | svg,png', 'svg')
+    .option('--mermaid-only', 'Skip SVG, only inject Mermaid fallback block')
+    .option('--always-mermaid', 'Inject Mermaid block AND SVG (both)')
+    .action(async (taskName, opts) => {
+      const formats = String(opts.format || 'svg').split(',').map((s) => s.trim()).filter(Boolean);
+      const { taskRenderCommand } = await import('./commands/task-render.mjs');
+      await taskRenderCommand(taskName, { ...opts, formats });
+    });
+
+  taskCmd
+    .command('view [task-name]')
+    .description('Render lean HTML dashboard (snapshot + tracker + recent activity + handoff) and open in browser')
+    .option('--no-open', 'Generate HTML without opening browser (prints path)')
+    .action(async (taskName, opts) => {
+      const { taskViewCommand } = await import('./commands/task-view.mjs');
+      await taskViewCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('watch [task-name]')
+    .description('Watch task.md for changes and live-reload the HTML preview in browser (local server, debounced)')
+    .option('-p, --port <port>', 'Local server port (auto-finds next available if busy)', parseInt)
+    .option('--rotate-token', 'Regenerate .dw/cache/watch.token at startup (invalidates old browser sessions; C-3)')
+    .action(async (taskName, opts) => {
+      const { taskWatchCommand } = await import('./commands/task-watch.mjs');
+      await taskWatchCommand(taskName, opts);
+    });
+
+  taskCmd
+    .command('summary <task-name>')
+    .description('Read or update task summary frontmatter field (≤1000 chars; agentchattr borrow)')
+    .option('--write <text>', 'Update summary (auto-bumps schema_version v3.0→v3.1 if needed)')
+    .action(async (taskName, opts) => {
+      const { taskSummaryCommand } = await import('./commands/task-summary.mjs');
+      await taskSummaryCommand(taskName, opts);
+    });
+
+  const agentCmd = program
+    .command('agent')
+    .description('Agent OS multi-agent orchestration (ADR-0009): claim · release · claims · reports · conflicts');
+
+  agentCmd
+    .command('claim <task-id>')
+    .description('Create a cooperative claim for a task (subtasks + write_scope)')
+    .option('-s, --subtasks <list>', 'Comma-separated subtask IDs (e.g. ST-1,ST-2)')
+    .option('-w, --write <paths>', 'Comma-separated write_scope glob paths')
+    .option('-r, --read <paths>', 'Comma-separated read_scope hint paths (informational)')
+    .option('-a, --agent <id>', 'Agent identifier (default: env DW_AGENT_ID or auto-generated)')
+    .option('-v, --vendor <name>', 'Vendor: claude | codex | gemini | human | other', 'claude')
+    .option('--role <role>', 'worker | reader | orchestrator | reviewer', 'worker')
+    .option('-l, --lease <duration>', 'Lease duration (e.g. 30m, 1h, 4h, 1d)', '1h')
+    .option('--worktree <path>', 'Worktree path if agent uses git worktree (R2-3)')
+    .option('-f, --force', 'Override conflict detection (use sparingly)')
+    .action(async (taskId, opts) => {
+      const { agentClaimCommand } = await import('./commands/agent-claim.mjs');
+      await agentClaimCommand(taskId, opts);
+    });
+
+  agentCmd
+    .command('release <claim-id>')
+    .description('Release a claim (clean exit; transitions status to "released")')
+    .option('-r, --reason <text>', 'Optional reason for release')
+    .action(async (claimId, opts) => {
+      const { agentReleaseCommand } = await import('./commands/agent-claim.mjs');
+      await agentReleaseCommand(claimId, opts);
+    });
+
+  agentCmd
+    .command('expire <claim-id>')
+    .description('Mark a claim as expired or invalidated (orchestrator action)')
+    .option('-r, --reason <text>', 'Reason for expiry')
+    .option('--invalidate', 'Invalidate instead of expire (orchestrator override)')
+    .action(async (claimId, opts) => {
+      const { agentExpireCommand } = await import('./commands/agent-claim.mjs');
+      await agentExpireCommand(claimId, opts);
+    });
+
+  agentCmd
+    .command('claims')
+    .description('List claims (default: active only). Filter by task / status / --all to include released')
+    .option('-t, --task <id>', 'Filter by task ID')
+    .option('-s, --status <status>', 'Filter by status: created | active | released | expired | invalidated')
+    .option('--all', 'Include released and invalidated claims')
+    .action(async (opts) => {
+      const { agentClaimsCommand } = await import('./commands/agent-inspect.mjs');
+      await agentClaimsCommand(opts);
+    });
+
+  agentCmd
+    .command('reports')
+    .description('List agent reports across tasks (read-only audit view)')
+    .option('-t, --task <id>', 'Filter by task ID')
+    .option('-a, --agent <id>', 'Filter by agent ID')
+    .action(async (opts) => {
+      const { agentReportsCommand } = await import('./commands/agent-inspect.mjs');
+      await agentReportsCommand(opts);
+    });
+
+  agentCmd
+    .command('conflicts')
+    .description('Detect overlapping active claims (subtask or write_scope). Exits 1 if conflicts found (use --no-strict to suppress).')
+    .option('-t, --task <id>', 'Filter by task ID')
+    .option('--no-strict', 'Do not exit 1 on conflict (just report)')
+    .action(async (opts) => {
+      const { agentConflictsCommand } = await import('./commands/agent-inspect.mjs');
+      await agentConflictsCommand(opts);
+    });
+
+  const goalCmd = program
+    .command('goal')
+    .description('Goals Management Layer (ADR-0010): strategic layer above tasks. new · show · link · summary · portfolio · lint · bump · delete · view');
+
+  goalCmd
+    .command('new <goal-id>')
+    .description('Create a new goal from template (ID format G-{slug})')
+    .option('--title <text>', 'Goal title (default: "New Goal")')
+    .option('--owner <name>', 'Owner (default: current user)')
+    .option('--target-date <YYYY-MM-DD>', 'Target date (default: TBD)')
+    .option('--icon <emoji>', 'Icon/emoji for portfolio cards (default: 🎯)')
+    .option('--cycle <label>', 'Cycle label e.g. "Q2 2026", "v1.7-cycle"')
+    .option('--summary <text>', 'Initial ≤1000-char summary')
+    .option('--parent-goal-id <id>', 'Parent goal ID for sub-goals')
+    .action(async (goalId, opts) => {
+      const { goalNewCommand } = await import('./commands/goal-new.mjs');
+      await goalNewCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('set <goal-id>')
+    .description('Update goal metadata fields (icon, cycle, owner, target_date, parent_goal_id)')
+    .option('--icon <emoji>', 'Icon/emoji (empty string removes)')
+    .option('--cycle <label>', 'Cycle label (empty string removes)')
+    .option('--owner <name>', 'New owner')
+    .option('--target-date <YYYY-MM-DD>', 'New target date or "TBD"')
+    .option('--parent-goal-id <id>', 'Parent goal ID or "none"')
+    .action(async (goalId, opts) => {
+      const { goalSetCommand } = await import('./commands/goal-set.mjs');
+      await goalSetCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('show [goal-id]')
+    .description('ANSI snapshot of a goal (no arg = list all)')
+    .action(async (goalId, opts) => {
+      const { goalShowCommand } = await import('./commands/goal-show.mjs');
+      await goalShowCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('link <goal-id> <task-id>')
+    .description('Link a task → goal (primary parent_goal_id; --contributing for secondary)')
+    .option('--contributing', 'Add to contributing_goal_ids instead of parent_goal_id (Q1)')
+    .option('-f, --force', 'Override existing parent_goal_id')
+    .action(async (goalId, taskId, opts) => {
+      const { goalLinkCommand } = await import('./commands/goal-link.mjs');
+      await goalLinkCommand(goalId, taskId, opts);
+    });
+
+  goalCmd
+    .command('unlink <goal-id> <task-id>')
+    .description('Remove task→goal mapping (clears both parent_goal_id and contributing_goal_ids)')
+    .action(async (goalId, taskId) => {
+      const { goalUnlinkCommand } = await import('./commands/goal-link.mjs');
+      await goalUnlinkCommand(goalId, taskId);
+    });
+
+  goalCmd
+    .command('summary <goal-id>')
+    .description('Read or update goal summary (≤1000 chars; agentchattr borrow)')
+    .option('--write <text>', 'Update summary (≤1000 chars); auto-syncs to goals-index.json')
+    .action(async (goalId, opts) => {
+      const { goalSummaryCommand } = await import('./commands/goal-summary.mjs');
+      await goalSummaryCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('bump <goal-id>')
+    .description('Manually bump goal_version (Q4 material change; requires --reason)')
+    .option('--reason <text>', 'Reason for the version bump (required)')
+    .action(async (goalId, opts) => {
+      const { goalBumpCommand } = await import('./commands/goal-bump.mjs');
+      await goalBumpCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('delete <goal-id>')
+    .description('Delete a goal (C-2: soft by default, --hard removes folder)')
+    .option('--cascade', 'Clear parent_goal_id / contributing_goal_ids on linked tasks')
+    .option('--hard', 'Hard-delete: remove .dw/goals/{id}/ folder (vs soft = status→Abandoned)')
+    .option('-n, --dry-run', 'Preview without writing')
+    .action(async (goalId, opts) => {
+      const { goalDeleteCommand } = await import('./commands/goal-delete.mjs');
+      await goalDeleteCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('lint [goal-id]')
+    .description('Lint goal.md: frontmatter schema + summary length + index drift + orphan cross-refs')
+    .action(async (goalId, opts) => {
+      const { goalLintCommand } = await import('./commands/goal-lint.mjs');
+      await goalLintCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('portfolio')
+    .description('Show all goals at-a-glance (O(1) read via goals-index.json; W-1)')
+    .option('--status <status>', 'Filter by status (Draft | Active | Achieved | Abandoned | Pivoted)')
+    .action(async (opts) => {
+      const { goalPortfolioCommand } = await import('./commands/goal-portfolio.mjs');
+      await goalPortfolioCommand(opts);
+    });
+
+  goalCmd
+    .command('view [goal-id]')
+    .description('Generate HTML portfolio (P1+P2 joint MVP per W-7)')
+    .option('--no-open', 'Do not auto-open browser')
+    .action(async (goalId, opts) => {
+      const { goalViewCommand } = await import('./commands/goal-view.mjs');
+      await goalViewCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('migrate [goal-id]')
+    .description('Stub for future schema bump (S-1; goal@v1 → goal@v2)')
+    .option('--to <schema>', 'Target schema (default: goal@v2)')
+    .action(async (goalId, opts) => {
+      const { goalMigrateCommand } = await import('./commands/goal-stubs.mjs');
+      await goalMigrateCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('suggest-krs <goal-id>')
+    .description('Build SMART-formatted prompt to paste into AI agent chat for KR brainstorming (W-5)')
+    .option('--count <n>', 'Requested number of KRs (default: 3)', '3')
+    .option('--json', 'Output structured JSON (for agent piping)')
+    .action(async (goalId, opts) => {
+      const { goalSuggestKrsCommand } = await import('./commands/goal-suggest-krs.mjs');
+      await goalSuggestKrsCommand(goalId, opts);
+    });
+
+  goalCmd
+    .command('render [goal-id]')
+    .description('Render constellation SVG for goal(s) — goal center + KR satellites + task leaves (R-G6 shipped)')
+    .action(async (goalId, opts) => {
+      const { goalRenderCommand } = await import('./commands/goal-render.mjs');
+      await goalRenderCommand(goalId, opts);
+    });
+
   program
     .command('dashboard')
     .description('Show team dashboard — active tasks, ADRs, telemetry summary, health')

package/src/commands/agent-claim.mjs

@@ -0,0 +1,235 @@
+import chalk from 'chalk';
+import { existsSync, openSync, closeSync, mkdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createClaim, persistClaim, validateClaim, transitionClaim, loadClaim, listClaims } from '../lib/agent-claim.mjs';
+import { logAgentEvent } from '../lib/agent-events.mjs';
+import { scopesOverlap } from '../lib/agent-conflict.mjs';
+import { logEvent as logTelemetry } from '../lib/telemetry.mjs';
+
+const LOCK_DIR = '.dw/cache/agents';
+const LOCK_FILE = 'claim.lock';
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_POLL_MS = 50;
+
+function acquireClaimLock(rootDir) {
+  const dir = join(rootDir, LOCK_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const lockPath = join(dir, LOCK_FILE);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let fd;
+  while (Date.now() < deadline) {
+    try {
+      fd = openSync(lockPath, 'wx');
+      return { fd, path: lockPath };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      const wait = LOCK_POLL_MS + Math.floor(Math.random() * 50);
+      const end = Date.now() + wait;
+      while (Date.now() < end) { /* busy wait — node has no sync sleep */ }
+    }
+  }
+  return { fd: null, path: lockPath, timedOut: true };
+}
+
+function releaseClaimLock(lock) {
+  if (!lock || lock.fd === null) return;
+  try { closeSync(lock.fd); } catch { /* ignore */ }
+  try { unlinkSync(lock.path); } catch { /* ignore */ }
+}
+
+function parseList(value) {
+  if (!value) return [];
+  return String(value).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+function parseLease(s) {
+  const m = String(s || '').match(/^(\d+)([smhd]?)$/i);
+  if (!m) return 3600;
+  const n = parseInt(m[1], 10);
+  const unit = (m[2] || 's').toLowerCase();
+  const mult = { s: 1, m: 60, h: 3600, d: 86400 }[unit];
+  return n * mult;
+}
+
+export async function agentClaimCommand(taskId, opts = {}) {
+  const rootDir = process.cwd();
+
+  if (!taskId) {
+    console.error(chalk.red('✗ Task ID required: dw agent claim <task-id> --subtasks ST-1,ST-2 --write src/foo.js'));
+    process.exit(1);
+  }
+  if (!existsSync(join(rootDir, '.dw/tasks', taskId, 'task.md'))) {
+    console.error(chalk.red(`✗ No v3 task at .dw/tasks/${taskId}/task.md`));
+    process.exit(1);
+  }
+
+  const subtasks = parseList(opts.subtasks);
+  if (subtasks.length === 0) {
+    console.error(chalk.red('✗ --subtasks required (e.g. --subtasks ST-1,ST-2)'));
+    process.exit(1);
+  }
+
+  const role = opts.role || 'worker';
+  const writeScope = parseList(opts.write);
+  const readScope = parseList(opts.read);
+  const leaseSeconds = parseLease(opts.lease || '1h');
+
+  if (role !== 'reader' && writeScope.length === 0) {
+    console.error(chalk.red('✗ --write required for non-reader roles (e.g. --write "src/foo.js,test/**")'));
+    process.exit(1);
+  }
+
+  const agentId = opts.agent || process.env.DW_AGENT_ID || `${opts.vendor || 'claude'}-${Date.now().toString(36)}-${randomBytes(2).toString('hex')}`;
+  const vendor = opts.vendor || 'claude';
+
+  const claim = createClaim({
+    taskId,
+    agent: { id: agentId, vendor, role },
+    subtasks,
+    writeScope,
+    readScope,
+    leaseSeconds,
+    worktreePath: opts.worktree || null,
+  }, rootDir);
+
+  const v = validateClaim(claim, rootDir);
+  if (!v.ok) {
+    console.error(chalk.red('✗ Schema validation failed:'));
+    for (const e of v.errors) console.error(chalk.red(`  ${e.path}: ${e.message}`));
+    process.exit(1);
+  }
+
+  // R2-1 + reviewer Critical #2: acquire exclusive lock around overlap-check + persist
+  // to close the TOCTOU window between two concurrent `dw agent claim` invocations.
+  const lock = acquireClaimLock(rootDir);
+  if (lock.timedOut) {
+    console.error(chalk.red(`✗ Could not acquire claim lock (${lock.path}) within ${LOCK_TIMEOUT_MS}ms.`));
+    console.error(chalk.dim('  Another `dw agent claim` may be running. Retry, or stale-remove the lock file.'));
+    process.exit(1);
+  }
+  let target;
+  try {
+    const wouldConflict = checkOverlapAgainstActive(claim, rootDir);
+    if (wouldConflict.length && !opts.force) {
+      console.error(chalk.red(`✗ Claim would overlap ${wouldConflict.length} existing active claim(s):`));
+      for (const c of wouldConflict) {
+        console.error(chalk.red(`  - ${c.claim_id} (agent: ${c.agent_id}, overlap: ${c.reason})`));
+      }
+      console.error(chalk.dim('  Use --force to claim anyway, or release the conflicting claim first.'));
+      releaseClaimLock(lock);
+      process.exit(1);
+    }
+    target = persistClaim(claim, rootDir);
+  } finally {
+    releaseClaimLock(lock);
+  }
+  logAgentEvent(taskId, {
+    event: 'claim_created',
+    claim_id: claim.claim_id,
+    agent_id: agentId,
+    vendor,
+    role,
+    subtasks,
+    write_scope: writeScope,
+    lease_expires: claim.lease_expires,
+  }, rootDir);
+  logTelemetry({ event: 'agent', action: 'claim.create', name: taskId, vendor, role }, rootDir);
+
+  console.log();
+  console.log(chalk.green('✓') + ` Claim created: ${chalk.cyan(claim.claim_id)}`);
+  console.log(chalk.dim(`  file: ${target}`));
+  console.log(chalk.dim(`  task: ${taskId}`));
+  console.log(chalk.dim(`  agent: ${agentId} (${vendor}/${role})`));
+  console.log(chalk.dim(`  subtasks: ${subtasks.join(', ')}`));
+  console.log(chalk.dim(`  write_scope: ${writeScope.join(', ') || '(read-only)'}`));
+  console.log(chalk.dim(`  lease_expires: ${claim.lease_expires} (in ${leaseSeconds}s)`));
+  console.log();
+  console.log(chalk.dim('  Next: write your changes, then `dw agent release ' + claim.claim_id + '` when done.'));
+  console.log();
+}
+
+function checkOverlapAgainstActive(newClaim, rootDir) {
+  // Reviewer Warning #3: write_scope collisions must be detected REPO-WIDE,
+  // not just within the same task. Subtask overlap remains task-scoped (IDs only
+  // meaningful within a single task).
+  const allActive = listClaims(rootDir).filter((c) => {
+    const ls = c._live_status;
+    return ls === 'created' || ls === 'active';
+  });
+
+  const conflicts = [];
+  for (const e of allActive) {
+    const sameTask = e.task_id === newClaim.task_id;
+    const subtaskOverlap = sameTask
+      ? newClaim.subtasks.filter((s) => e.subtasks.includes(s))
+      : [];
+    const writeOverlap = [];
+    for (const pa of newClaim.write_scope) {
+      for (const pb of e.write_scope) {
+        if (scopesOverlap(pa, pb)) writeOverlap.push({ new: pa, existing: pb });
+      }
+    }
+    if (subtaskOverlap.length || writeOverlap.length) {
+      const reasons = [];
+      if (subtaskOverlap.length) reasons.push(`subtasks ${subtaskOverlap.join(',')}`);
+      if (writeOverlap.length) reasons.push(`write scope ${writeOverlap.map((o) => o.existing).join(',')}`);
+      if (!sameTask) reasons.push(`(cross-task: ${e.task_id})`);
+      conflicts.push({ claim_id: e.claim_id, agent_id: e.agent.id, reason: reasons.join('; ') });
+    }
+  }
+  return conflicts;
+}
+
+export async function agentReleaseCommand(claimId, opts = {}) {
+  const rootDir = process.cwd();
+  if (!claimId) {
+    console.error(chalk.red('✗ Claim ID required: dw agent release <claim-id>'));
+    process.exit(1);
+  }
+  const claim = loadClaim(claimId, rootDir);
+  if (!claim) {
+    console.error(chalk.red(`✗ Claim not found: ${claimId}`));
+    process.exit(1);
+  }
+  const result = transitionClaim(claimId, 'released', { reason: opts.reason }, rootDir);
+  if (!result.ok) {
+    console.error(chalk.red(`✗ Cannot release: ${result.reason}`));
+    process.exit(1);
+  }
+  logAgentEvent(claim.task_id, {
+    event: 'claim_released',
+    claim_id: claimId,
+    agent_id: claim.agent.id,
+    reason: opts.reason || 'clean exit',
+  }, rootDir);
+  logTelemetry({ event: 'agent', action: 'claim.release', name: claim.task_id }, rootDir);
+  console.log(chalk.green('✓') + ` Released: ${claimId}`);
+}
+
+export async function agentExpireCommand(claimId, opts = {}) {
+  const rootDir = process.cwd();
+  if (!claimId) {
+    console.error(chalk.red('✗ Claim ID required'));
+    process.exit(1);
+  }
+  const claim = loadClaim(claimId, rootDir);
+  if (!claim) {
+    console.error(chalk.red(`✗ Claim not found: ${claimId}`));
+    process.exit(1);
+  }
+  const status = opts.invalidate ? 'invalidated' : 'expired';
+  const result = transitionClaim(claimId, status, { reason: opts.reason || 'manual expire' }, rootDir);
+  if (!result.ok) {
+    console.error(chalk.red(`✗ Cannot ${status}: ${result.reason}`));
+    process.exit(1);
+  }
+  logAgentEvent(claim.task_id, {
+    event: status === 'invalidated' ? 'claim_invalidated' : 'claim_expired',
+    claim_id: claimId,
+    agent_id: claim.agent.id,
+    reason: opts.reason || 'manual',
+  }, rootDir);
+  logTelemetry({ event: 'agent', action: `claim.${status}`, name: claim.task_id }, rootDir);
+  console.log(chalk.yellow(`⚠ ${status}: ${claimId}`));
+}

package/src/commands/agent-inspect.mjs

@@ -0,0 +1,123 @@
+import chalk from 'chalk';
+import { listClaims, computeEffectiveExpiry } from '../lib/agent-claim.mjs';
+import { listReports } from '../lib/agent-report.mjs';
+import { detectClaimOverlaps } from '../lib/agent-conflict.mjs';
+import { logEvent as logTelemetry } from '../lib/telemetry.mjs';
+
+const STATUS_COLOR = {
+  created: chalk.cyan,
+  active: chalk.yellow,
+  released: chalk.green,
+  expired: chalk.red,
+  invalidated: chalk.magenta,
+};
+
+function fmtRel(iso) {
+  if (!iso) return '—';
+  const diff = Date.parse(iso) - Date.now();
+  const abs = Math.abs(diff) / 1000;
+  const unit = abs < 60 ? `${Math.round(abs)}s` : abs < 3600 ? `${Math.round(abs / 60)}m` : abs < 86400 ? `${Math.round(abs / 3600)}h` : `${Math.round(abs / 86400)}d`;
+  return diff < 0 ? `${unit} ago` : `in ${unit}`;
+}
+
+export async function agentClaimsCommand(opts = {}) {
+  const rootDir = process.cwd();
+  const claims = listClaims(rootDir, {
+    taskId: opts.task,
+    status: opts.status,
+    includeStale: !!opts.all,
+  });
+
+  logTelemetry({ event: 'agent', action: 'claims.list', count: claims.length }, rootDir);
+
+  console.log();
+  if (claims.length === 0) {
+    console.log(chalk.dim(`  No claims found${opts.task ? ` for task ${opts.task}` : ''}.`));
+    console.log(chalk.dim('  Create one: `dw agent claim <task> --subtasks ST-1 --write src/foo.js`'));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.bold(`  ${claims.length} claim${claims.length === 1 ? '' : 's'}${opts.task ? ` for ${opts.task}` : ''}`));
+  console.log();
+
+  for (const c of claims) {
+    const liveStatus = c._live_status;
+    const colorFn = STATUS_COLOR[liveStatus] || chalk.white;
+    const effectiveExp = computeEffectiveExpiry(c);
+    const wallClockExp = Date.parse(c.lease_expires);
+    const usingRelative = effectiveExp > wallClockExp;
+
+    console.log(`  ${colorFn(`[${liveStatus.toUpperCase()}]`)} ${chalk.cyan(c.claim_id)}`);
+    console.log(`    task: ${c.task_id}`);
+    console.log(`    agent: ${c.agent.id} (${c.agent.vendor}/${c.agent.role})`);
+    console.log(`    subtasks: ${c.subtasks.join(', ')}`);
+    console.log(`    write_scope: ${c.write_scope.length ? c.write_scope.join(', ') : chalk.dim('(read-only)')}`);
+    console.log(`    lease: ${c.lease_expires} (${fmtRel(c.lease_expires)})${usingRelative ? chalk.dim(' [+relative fallback]') : ''}`);
+    if (c.released_at) console.log(`    released_at: ${c.released_at}${c.release_reason ? ' — ' + c.release_reason : ''}`);
+    if (c.worktree_path) console.log(`    worktree: ${c.worktree_path}`);
+    console.log();
+  }
+}
+
+export async function agentReportsCommand(opts = {}) {
+  const rootDir = process.cwd();
+  const reports = listReports(rootDir, { taskId: opts.task, agentId: opts.agent });
+
+  logTelemetry({ event: 'agent', action: 'reports.list', count: reports.length }, rootDir);
+
+  console.log();
+  if (reports.length === 0) {
+    console.log(chalk.dim(`  No reports found${opts.task ? ` for task ${opts.task}` : ''}.`));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.bold(`  ${reports.length} report${reports.length === 1 ? '' : 's'}`));
+  console.log();
+
+  for (const r of reports) {
+    const sevColor = r.status === 'completed' ? chalk.green : r.status === 'needs-review' ? chalk.red : r.status === 'partial' ? chalk.yellow : chalk.dim;
+    console.log(`  ${sevColor(`[${(r.status || '?').toUpperCase()}]`)} ${chalk.cyan(r._file.split(/[\\/]/).pop())}`);
+    console.log(`    task: ${r._task} · agent: ${r.agent_id || '?'} (${r.vendor || '?'})`);
+    console.log(`    claim: ${r.claim_id || '?'}`);
+    if (r.subtasks_addressed && r.subtasks_addressed.length) console.log(`    subtasks: ${r.subtasks_addressed.join(', ')}`);
+    if (r.files_changed && r.files_changed.length) console.log(`    files: ${r.files_changed.slice(0, 5).join(', ')}${r.files_changed.length > 5 ? `, +${r.files_changed.length - 5} more` : ''}`);
+    if (r.files_outside_scope && r.files_outside_scope.length) console.log(chalk.red(`    out-of-scope: ${r.files_outside_scope.join(', ')}`));
+    if (r.open_questions && r.open_questions.length) console.log(chalk.yellow(`    open: ${r.open_questions[0]}${r.open_questions.length > 1 ? ` (+${r.open_questions.length - 1})` : ''}`));
+    console.log(chalk.dim(`    ${r.created_at || ''}`));
+    console.log();
+  }
+}
+
+export async function agentConflictsCommand(opts = {}) {
+  const rootDir = process.cwd();
+  const conflicts = detectClaimOverlaps(rootDir, { taskId: opts.task });
+
+  logTelemetry({ event: 'agent', action: 'conflicts.check', count: conflicts.length }, rootDir);
+
+  console.log();
+  if (conflicts.length === 0) {
+    console.log(chalk.green('  ✓ No conflicts among active claims.'));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.red(`  ✗ ${conflicts.length} conflict${conflicts.length === 1 ? '' : 's'} detected:`));
+  console.log();
+
+  for (const c of conflicts) {
+    console.log(`  ${chalk.cyan(c.claim_a)} (${c.agent_a})`);
+    console.log(`  ${chalk.cyan(c.claim_b)} (${c.agent_b})`);
+    console.log(`  task: ${c.task_id}`);
+    if (c.subtask_overlap.length) console.log(chalk.yellow(`  subtask overlap: ${c.subtask_overlap.join(', ')}`));
+    for (const w of c.write_overlap) {
+      console.log(chalk.red(`  write overlap: "${w.a}" ↔ "${w.b}"`));
+    }
+    console.log();
+  }
+
+  if (opts.strict !== false) {
+    process.exit(1);
+  }
+}