@weldr/runr 0.3.0

package/dist/cli.js

@@ -0,0 +1,464 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { runCommand } from './commands/run.js';
+import { resumeCommand } from './commands/resume.js';
+import { statusCommand, statusAllCommand } from './commands/status.js';
+import { reportCommand, findLatestRunId } from './commands/report.js';
+import { summarizeCommand } from './commands/summarize.js';
+import { compareCommand } from './commands/compare.js';
+import { guardsOnlyCommand } from './commands/guards-only.js';
+import { doctorCommand } from './commands/doctor.js';
+import { followCommand, findBestRunToFollow } from './commands/follow.js';
+import { gcCommand } from './commands/gc.js';
+import { waitCommand, findLatestRunId as findLatestRunIdForWait } from './commands/wait.js';
+import { orchestrateCommand, resumeOrchestrationCommand, waitOrchestrationCommand } from './commands/orchestrate.js';
+import { pathsCommand } from './commands/paths.js';
+import { metricsCommand } from './commands/metrics.js';
+import { versionCommand } from './commands/version.js';
+const program = new Command();
+// Check if invoked as deprecated 'agent' command
+const invokedAs = process.argv[1]?.split('/').pop() || 'runr';
+if (invokedAs === 'agent') {
+    console.warn('\x1b[33m⚠ Deprecation: The "agent" command is deprecated. Use "runr" instead.\x1b[0m\n');
+}
+program
+    .name('runr')
+    .description('Phase-gated orchestration for agent tasks');
+program
+    .command('run')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .requiredOption('--task <path>', 'Task brief file')
+    .option('--time <minutes>', 'Time budget in minutes', '120')
+    .option('--config <path>', 'Path to runr.config.json (or agent.config.json)')
+    .option('--allow-deps', 'Allow lockfile changes', false)
+    .option('--allow-dirty', 'Allow dirty worktree', false)
+    .option('--no-branch', 'Do not checkout run branch')
+    .option('--no-write', 'Do not write run artifacts')
+    .option('--web', 'Allow web access for unblock', false)
+    .option('--dry-run', 'Initialize run without executing', false)
+    .option('--max-ticks <count>', 'Max supervisor ticks (default: 50)', '50')
+    .option('--skip-doctor', 'Skip worker health checks', false)
+    .option('--fresh-target', 'Wipe target root before starting', false)
+    .option('--worktree', 'Create isolated git worktree for this run', false)
+    .option('--fast', 'Fast path: skip PLAN and REVIEW phases for small tasks', false)
+    .option('--auto-resume', 'Auto-resume on transient failures (stall, worker timeout)', false)
+    .option('--force-parallel', 'Bypass file collision checks with active runs', false)
+    .option('--json', 'Output JSON with run_id (for orchestrator consumption)', false)
+    .action(async (options) => {
+    const noBranch = options.branch === false;
+    const noWrite = options.write === false;
+    await runCommand({
+        repo: options.repo,
+        task: options.task,
+        time: Number.parseInt(options.time, 10),
+        config: options.config,
+        allowDeps: options.allowDeps,
+        allowDirty: options.allowDirty,
+        web: options.web,
+        dryRun: options.dryRun,
+        noBranch,
+        noWrite,
+        maxTicks: Number.parseInt(options.maxTicks, 10),
+        skipDoctor: options.skipDoctor,
+        freshTarget: options.freshTarget,
+        worktree: options.worktree,
+        fast: options.fast,
+        autoResume: options.autoResume,
+        forceParallel: options.forceParallel,
+        json: options.json
+    });
+});
+program
+    .command('guards-only')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .requiredOption('--task <path>', 'Task brief file')
+    .option('--config <path>', 'Path to runr.config.json (or agent.config.json)')
+    .option('--allow-deps', 'Allow lockfile changes', false)
+    .option('--allow-dirty', 'Allow dirty worktree', false)
+    .option('--no-write', 'Do not write run artifacts')
+    .action(async (options) => {
+    const noWrite = options.write === false;
+    await guardsOnlyCommand({
+        repo: options.repo,
+        task: options.task,
+        config: options.config,
+        allowDeps: options.allowDeps,
+        allowDirty: options.allowDirty,
+        noWrite
+    });
+});
+program
+    .command('resume')
+    .argument('<runId>', 'Run ID')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .option('--time <minutes>', 'Time budget in minutes', '120')
+    .option('--max-ticks <count>', 'Max supervisor ticks (default: 50)', '50')
+    .option('--allow-deps', 'Allow lockfile changes', false)
+    .option('--config <path>', 'Path to runr.config.json (or agent.config.json)')
+    .option('--force', 'Resume despite env fingerprint mismatch', false)
+    .option('--auto-resume', 'Continue auto-resuming on transient failures', false)
+    .action(async (runId, options) => {
+    await resumeCommand({
+        runId,
+        repo: options.repo,
+        time: Number.parseInt(options.time, 10),
+        maxTicks: Number.parseInt(options.maxTicks, 10),
+        allowDeps: options.allowDeps,
+        config: options.config,
+        force: options.force,
+        autoResume: options.autoResume
+    });
+});
+program
+    .command('status')
+    .argument('[runId]', 'Run ID (omit with --all to show all runs)')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .option('--all', 'Show status of all runs', false)
+    .action(async (runId, options) => {
+    if (options.all) {
+        await statusAllCommand({ repo: options.repo });
+    }
+    else if (runId) {
+        await statusCommand({ runId, repo: options.repo });
+    }
+    else {
+        console.error('Error: Run ID required unless using --all');
+        process.exit(1);
+    }
+});
+program
+    .command('report')
+    .argument('<runId>', 'Run ID (or "latest")')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .option('--tail <count>', 'Tail last N events', '50')
+    .option('--kpi-only', 'Show compact KPI summary only')
+    .action(async (runId, options) => {
+    let resolvedRunId = runId;
+    if (runId === 'latest') {
+        const latest = findLatestRunId(options.repo);
+        if (!latest) {
+            console.error('No runs found');
+            process.exit(1);
+        }
+        resolvedRunId = latest;
+    }
+    await reportCommand({
+        runId: resolvedRunId,
+        repo: options.repo,
+        tail: Number.parseInt(options.tail, 10),
+        kpiOnly: options.kpiOnly
+    });
+});
+program
+    .command('summarize')
+    .description('Generate summary.json from run KPIs')
+    .argument('<runId>', 'Run ID (or "latest")')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .action(async (runId, options) => {
+    let resolvedRunId = runId;
+    if (runId === 'latest') {
+        const latest = findLatestRunId(options.repo);
+        if (!latest) {
+            console.error('No runs found');
+            process.exit(1);
+        }
+        resolvedRunId = latest;
+    }
+    await summarizeCommand({ runId: resolvedRunId, repo: options.repo });
+});
+program
+    .command('compare')
+    .description('Compare KPIs between two runs')
+    .argument('<runA>', 'First run ID')
+    .argument('<runB>', 'Second run ID')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .action(async (runA, runB, options) => {
+    await compareCommand({ runA, runB, repo: options.repo });
+});
+program
+    .command('doctor')
+    .description('Check worker CLI availability and headless mode')
+    .option('--repo <path>', 'Target repo path', '.')
+    .option('--config <path>', 'Path to runr.config.json (or agent.config.json)')
+    .action(async (options) => {
+    await doctorCommand({
+        repo: options.repo,
+        config: options.config
+    });
+});
+program
+    .command('paths')
+    .description('Display canonical runr directory paths (for scripts and tooling)')
+    .option('--repo <path>', 'Target repo path', '.')
+    .option('--json', 'Output JSON (default: true)', true)
+    .option('--no-json', 'Output human-readable table')
+    .action(async (options) => {
+    await pathsCommand({
+        repo: options.repo,
+        json: options.json
+    });
+});
+program
+    .command('metrics')
+    .description('Show aggregated metrics across all runs and orchestrations')
+    .option('--repo <path>', 'Target repo path', '.')
+    .option('--days <n>', 'Number of days to aggregate (default: 30)', '30')
+    .option('--window <n>', 'Max runs to consider (default: 50 runs, 20 orchestrations)')
+    .option('--json', 'Output JSON format', false)
+    .action(async (options) => {
+    await metricsCommand({
+        repo: options.repo,
+        days: parseInt(options.days, 10),
+        window: options.window ? parseInt(options.window, 10) : undefined,
+        json: options.json
+    });
+});
+program
+    .command('version')
+    .description('Show version information')
+    .option('--json', 'Output JSON format', false)
+    .action(async (options) => {
+    await versionCommand({
+        json: options.json
+    });
+});
+program
+    .command('follow')
+    .description('Tail run timeline and exit on termination')
+    .argument('[runId]', 'Run ID (or "latest", default: latest running or latest)')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .action(async (runId, options) => {
+    let resolvedRunId;
+    if (!runId || runId === 'latest') {
+        const best = findBestRunToFollow(options.repo);
+        if (!best) {
+            console.error('No runs found');
+            process.exit(1);
+        }
+        resolvedRunId = best.runId;
+        if (!best.wasRunning) {
+            console.log(`No running runs; following latest (${resolvedRunId})`);
+        }
+    }
+    else {
+        resolvedRunId = runId;
+    }
+    await followCommand({ runId: resolvedRunId, repo: options.repo });
+});
+program
+    .command('gc')
+    .description('Clean up old worktree directories to reclaim disk space')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .option('--dry-run', 'Preview what would be deleted without actually deleting', false)
+    .option('--older-than <days>', 'Only delete worktrees older than N days', '7')
+    .action(async (options) => {
+    await gcCommand({
+        repo: options.repo,
+        dryRun: options.dryRun,
+        olderThan: Number.parseInt(options.olderThan, 10)
+    });
+});
+program
+    .command('wait')
+    .description('Block until run reaches terminal state (for meta-agent coordination)')
+    .argument('[runId]', 'Run ID (or "latest")')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .option('--for <condition>', 'Wait condition: terminal, stop, complete', 'terminal')
+    .option('--timeout <ms>', 'Timeout in milliseconds')
+    .option('--json', 'Output JSON (default: true)', true)
+    .option('--no-json', 'Output human-readable text')
+    .action(async (runId, options) => {
+    let resolvedRunId;
+    if (!runId || runId === 'latest') {
+        const latest = findLatestRunIdForWait(options.repo);
+        if (!latest) {
+            if (options.json) {
+                console.log(JSON.stringify({ error: 'no_runs', message: 'No runs found' }));
+            }
+            else {
+                console.error('No runs found');
+            }
+            process.exit(1);
+        }
+        resolvedRunId = latest;
+    }
+    else {
+        resolvedRunId = runId;
+    }
+    await waitCommand({
+        runId: resolvedRunId,
+        repo: options.repo,
+        for: options.for,
+        timeout: options.timeout ? Number.parseInt(options.timeout, 10) : undefined,
+        json: options.json
+    });
+});
+// Orchestrate subcommands
+const orchestrateCmd = program
+    .command('orchestrate')
+    .description('Run multiple tracks of tasks in parallel with collision-aware scheduling');
+orchestrateCmd
+    .command('run')
+    .description('Start a new orchestration from config')
+    .requiredOption('--config <path>', 'Path to orchestration config file (YAML or JSON)')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .option('--time <minutes>', 'Time budget per run in minutes', '120')
+    .option('--max-ticks <count>', 'Max supervisor ticks per run', '50')
+    .option('--collision-policy <policy>', 'Collision policy: serialize, force, fail', 'serialize')
+    .option('--allow-deps', 'Allow lockfile changes', false)
+    .option('--worktree', 'Create isolated git worktree for each run', false)
+    .option('--fast', 'Fast path: skip PLAN and REVIEW phases', false)
+    .option('--auto-resume', 'Auto-resume runs on transient failures', false)
+    .option('--dry-run', 'Show planned execution without running', false)
+    .action(async (options) => {
+    const collisionPolicy = options.collisionPolicy;
+    if (!['serialize', 'force', 'fail'].includes(collisionPolicy)) {
+        console.error(`Invalid collision policy: ${collisionPolicy}`);
+        console.error('Valid values: serialize, force, fail');
+        process.exit(1);
+    }
+    await orchestrateCommand({
+        config: options.config,
+        repo: options.repo,
+        time: Number.parseInt(options.time, 10),
+        maxTicks: Number.parseInt(options.maxTicks, 10),
+        collisionPolicy,
+        allowDeps: options.allowDeps,
+        worktree: options.worktree,
+        fast: options.fast,
+        autoResume: options.autoResume,
+        dryRun: options.dryRun
+    });
+});
+orchestrateCmd
+    .command('resume')
+    .description('Resume a previously started orchestration')
+    .argument('<orchestratorId>', 'Orchestrator ID to resume (or "latest")')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    // Policy override flags (optional, logged if used)
+    .option('--time <minutes>', 'Override time budget per run')
+    .option('--max-ticks <count>', 'Override max supervisor ticks')
+    .option('--fast', 'Override fast mode (skip PLAN/REVIEW)')
+    .option('--no-fast', 'Disable fast mode override')
+    .option('--collision-policy <policy>', 'Override collision policy: serialize, force, fail')
+    .action(async (orchestratorId, options) => {
+    await resumeOrchestrationCommand({
+        orchestratorId,
+        repo: options.repo,
+        overrides: {
+            time: options.time ? Number.parseInt(options.time, 10) : undefined,
+            maxTicks: options.maxTicks ? Number.parseInt(options.maxTicks, 10) : undefined,
+            fast: options.fast,
+            collisionPolicy: options.collisionPolicy
+        }
+    });
+});
+orchestrateCmd
+    .command('wait')
+    .description('Block until orchestration reaches terminal state')
+    .argument('<orchestratorId>', 'Orchestrator ID to wait for (or "latest")')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .option('--for <condition>', 'Wait condition: terminal, stop, complete', 'terminal')
+    .option('--timeout <ms>', 'Timeout in milliseconds')
+    .option('--json', 'Output JSON (default: true)', true)
+    .option('--no-json', 'Output human-readable text')
+    .action(async (orchestratorId, options) => {
+    await waitOrchestrationCommand({
+        orchestratorId,
+        repo: options.repo,
+        for: options.for,
+        timeout: options.timeout ? Number.parseInt(options.timeout, 10) : undefined,
+        json: options.json
+    });
+});
+// ==========================================
+// Edgy aliases (same commands, different vibe)
+// ==========================================
+// summon → run
+program
+    .command('summon')
+    .description('Summon a worker to execute a task (alias for "run")')
+    .option('--repo <path>', 'Target repo path', '.')
+    .requiredOption('--task <path>', 'Task brief file')
+    .option('--time <minutes>', 'Time budget in minutes', '120')
+    .option('--config <path>', 'Path to runr.config.json')
+    .option('--worktree', 'Create isolated git worktree', false)
+    .option('--fast', 'Skip PLAN and REVIEW phases', false)
+    .option('--auto-resume', 'Auto-resume on transient failures', false)
+    .option('--json', 'Output JSON', false)
+    .action(async (options) => {
+    await runCommand({
+        repo: options.repo,
+        task: options.task,
+        time: Number.parseInt(options.time, 10),
+        config: options.config,
+        allowDeps: false,
+        allowDirty: false,
+        web: false,
+        dryRun: false,
+        noBranch: false,
+        noWrite: false,
+        maxTicks: 50,
+        skipDoctor: false,
+        freshTarget: false,
+        worktree: options.worktree,
+        fast: options.fast,
+        autoResume: options.autoResume,
+        forceParallel: false,
+        json: options.json
+    });
+});
+// resurrect → resume
+program
+    .command('resurrect')
+    .description('Resurrect a stopped run from checkpoint (alias for "resume")')
+    .argument('<runId>', 'Run ID')
+    .option('--repo <path>', 'Target repo path', '.')
+    .option('--time <minutes>', 'Time budget in minutes', '120')
+    .option('--force', 'Resume despite env mismatch', false)
+    .action(async (runId, options) => {
+    await resumeCommand({
+        runId,
+        repo: options.repo,
+        time: Number.parseInt(options.time, 10),
+        maxTicks: 50,
+        allowDeps: false,
+        config: options.config,
+        force: options.force,
+        autoResume: false
+    });
+});
+// scry → status
+program
+    .command('scry')
+    .description('Scry the fate of a run (alias for "status")')
+    .argument('[runId]', 'Run ID')
+    .option('--repo <path>', 'Target repo path', '.')
+    .option('--all', 'Show all runs', false)
+    .action(async (runId, options) => {
+    if (options.all) {
+        await statusAllCommand({ repo: options.repo });
+    }
+    else if (runId) {
+        await statusCommand({ runId, repo: options.repo });
+    }
+    else {
+        console.error('Error: Run ID required unless using --all');
+        process.exit(1);
+    }
+});
+// banish → gc
+program
+    .command('banish')
+    .description('Banish old worktrees to the void (alias for "gc")')
+    .option('--repo <path>', 'Target repo path', '.')
+    .option('--dry-run', 'Preview without deleting', false)
+    .option('--older-than <days>', 'Only banish worktrees older than N days', '7')
+    .action(async (options) => {
+    await gcCommand({
+        repo: options.repo,
+        dryRun: options.dryRun,
+        olderThan: Number.parseInt(options.olderThan, 10)
+    });
+});
+program.parseAsync();

package/dist/commands/__tests__/report.test.js

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import { computeKpiFromEvents } from '../report.js';
+// Helper to create events with timestamps
+function event(type, timestamp, payload = {}) {
+    return { type, timestamp, payload };
+}
+describe('computeKpiFromEvents', () => {
+    describe('graceful degradation', () => {
+        it('never throws on empty events', () => {
+            expect(() => computeKpiFromEvents([])).not.toThrow();
+        });
+        it('returns unknown for workers when no worker_stats event', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('phase_start', '2025-01-01T00:00:01Z', { phase: 'PLAN' }),
+                event('stop', '2025-01-01T00:01:00Z', { reason: 'user' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.workers.claude).toBe('unknown');
+            expect(kpi.workers.codex).toBe('unknown');
+        });
+        it('returns outcome running when no stop or complete event', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('phase_start', '2025-01-01T00:00:01Z', { phase: 'PLAN' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.outcome).toBe('running');
+            expect(kpi.total_duration_ms).toBeNull();
+            expect(kpi.unattributed_ms).toBeNull();
+        });
+        it('returns outcome unknown when no run_started event', () => {
+            const events = [
+                event('phase_start', '2025-01-01T00:00:01Z', { phase: 'PLAN' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.outcome).toBe('unknown');
+        });
+        it('returns empty phases when no phase_start events', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('stop', '2025-01-01T00:01:00Z', { reason: 'user' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(Object.keys(kpi.phases)).toHaveLength(0);
+        });
+    });
+    describe('old run (no worker_stats)', () => {
+        it('computes duration and phases without worker counts', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('phase_start', '2025-01-01T00:00:10Z', { phase: 'PLAN' }),
+                event('phase_start', '2025-01-01T00:01:00Z', { phase: 'IMPLEMENT' }),
+                event('phase_start', '2025-01-01T00:02:00Z', { phase: 'VERIFY' }),
+                event('verification', '2025-01-01T00:02:05Z', { tier: 'tier0', ok: true, duration_ms: 5000 }),
+                event('stop', '2025-01-01T00:02:10Z', { reason: 'complete' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.total_duration_ms).toBe(130000); // 2m10s
+            expect(kpi.workers.claude).toBe('unknown');
+            expect(kpi.workers.codex).toBe('unknown');
+            expect(kpi.phases['PLAN'].duration_ms).toBe(50000); // 50s
+            expect(kpi.phases['IMPLEMENT'].duration_ms).toBe(60000); // 60s
+            expect(kpi.phases['VERIFY'].duration_ms).toBe(10000); // 10s
+            expect(kpi.verify.attempts).toBe(1);
+        });
+    });
+    describe('multiple phase loops', () => {
+        it('accumulates phase durations across multiple iterations', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                // First IMPLEMENT cycle
+                event('phase_start', '2025-01-01T00:00:00Z', { phase: 'IMPLEMENT' }),
+                event('phase_start', '2025-01-01T00:01:00Z', { phase: 'VERIFY' }),
+                event('verification', '2025-01-01T00:01:05Z', { tier: 'tier0', ok: false }),
+                // Retry - second IMPLEMENT cycle
+                event('phase_start', '2025-01-01T00:01:10Z', { phase: 'IMPLEMENT' }),
+                event('phase_start', '2025-01-01T00:02:00Z', { phase: 'VERIFY' }),
+                event('verification', '2025-01-01T00:02:05Z', { tier: 'tier0', ok: false }),
+                // Retry - third IMPLEMENT cycle
+                event('phase_start', '2025-01-01T00:02:10Z', { phase: 'IMPLEMENT' }),
+                event('phase_start', '2025-01-01T00:03:00Z', { phase: 'VERIFY' }),
+                event('verification', '2025-01-01T00:03:05Z', { tier: 'tier0', ok: true }),
+                event('stop', '2025-01-01T00:03:10Z', { reason: 'complete' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.phases['IMPLEMENT'].count).toBe(3);
+            expect(kpi.phases['VERIFY'].count).toBe(3);
+            // IMPLEMENT: 60s + 50s + 50s = 160s
+            expect(kpi.phases['IMPLEMENT'].duration_ms).toBe(160000);
+            // VERIFY: 10s + 10s + 10s = 30s
+            expect(kpi.phases['VERIFY'].duration_ms).toBe(30000);
+            expect(kpi.verify.attempts).toBe(3);
+        });
+    });
+    describe('verify retries', () => {
+        it('counts retry field from verification events', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('phase_start', '2025-01-01T00:00:00Z', { phase: 'VERIFY' }),
+                event('verification', '2025-01-01T00:00:05Z', { tier: 'tier0', ok: false, retry: 0 }),
+                event('verification', '2025-01-01T00:00:10Z', { tier: 'tier0', ok: false, retry: 1 }),
+                event('verification', '2025-01-01T00:00:15Z', { tier: 'tier0', ok: true, retry: 2 }),
+                event('stop', '2025-01-01T00:00:20Z', { reason: 'complete' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.verify.attempts).toBe(3);
+            expect(kpi.verify.retries).toBe(3); // 0 + 1 + 2 = 3
+        });
+    });
+    describe('worker_stats tracking', () => {
+        it('extracts worker call counts from worker_stats event', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('phase_start', '2025-01-01T00:00:00Z', { phase: 'PLAN' }),
+                event('worker_stats', '2025-01-01T00:01:00Z', {
+                    stats: { claude: 5, codex: 3, by_phase: {} }
+                }),
+                event('stop', '2025-01-01T00:01:00Z', { reason: 'complete' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.workers.claude).toBe(5);
+            expect(kpi.workers.codex).toBe(3);
+        });
+    });
+    describe('milestone tracking', () => {
+        it('counts milestone_complete events', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('milestone_complete', '2025-01-01T00:01:00Z', { index: 0 }),
+                event('milestone_complete', '2025-01-01T00:02:00Z', { index: 1 }),
+                event('milestone_complete', '2025-01-01T00:03:00Z', { index: 2 }),
+                event('stop', '2025-01-01T00:03:00Z', { reason: 'complete' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.milestones.completed).toBe(3);
+        });
+    });
+    describe('outcome detection', () => {
+        it('sets outcome to stopped with reason', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('stop', '2025-01-01T00:01:00Z', { reason: 'implement_blocked' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.outcome).toBe('stopped');
+            expect(kpi.stop_reason).toBe('implement_blocked');
+        });
+        it('sets outcome to complete on run_complete', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('run_complete', '2025-01-01T00:01:00Z')
+            ];
+            const kpi = computeKpiFromEvents(events);
+            expect(kpi.outcome).toBe('complete');
+            expect(kpi.stop_reason).toBeNull();
+        });
+    });
+    describe('unattributed time', () => {
+        it('computes positive unattributed time (preflight, gaps)', () => {
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                // 30s gap before first phase (preflight, etc)
+                event('phase_start', '2025-01-01T00:00:30Z', { phase: 'PLAN' }),
+                event('phase_start', '2025-01-01T00:01:00Z', { phase: 'IMPLEMENT' }),
+                event('stop', '2025-01-01T00:02:00Z', { reason: 'complete' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            // Total: 2m = 120s
+            // PLAN: 30s, IMPLEMENT: 60s
+            // Unattributed: 120 - 90 = 30s
+            expect(kpi.total_duration_ms).toBe(120000);
+            expect(kpi.unattributed_ms).toBe(30000);
+        });
+        it('handles negative unattributed (resumed runs with gap)', () => {
+            // This can happen when run is paused and resumed
+            // Total duration doesn't account for pause gap
+            const events = [
+                event('run_started', '2025-01-01T00:00:00Z'),
+                event('phase_start', '2025-01-01T00:00:00Z', { phase: 'IMPLEMENT' }),
+                event('stop', '2025-01-01T00:01:00Z', { reason: 'blocked' }),
+                // After resume - phase duration exceeds tracked total
+                event('run_resumed', '2025-01-01T00:10:00Z'),
+                event('phase_start', '2025-01-01T00:10:00Z', { phase: 'IMPLEMENT' }),
+                event('stop', '2025-01-01T00:11:00Z', { reason: 'complete' })
+            ];
+            const kpi = computeKpiFromEvents(events);
+            // Total: 11m - but phases ran: 1m + 1m = 2m
+            // Actually: stop at 00:11:00 - started at 00:00:00 = 11m
+            // Phase IMPLEMENT: 1m (00:00:00-00:01:00) + 1m (00:10:00-00:11:00) = 2m
+            // Unattributed: 11m - 2m = 9m (positive in this case due to pause gap)
+            expect(kpi.outcome).toBe('stopped');
+            // The second stop overwrites the first
+        });
+    });
+    describe('version field', () => {
+        it('always returns version 1', () => {
+            const kpi = computeKpiFromEvents([]);
+            expect(kpi.version).toBe(1);
+        });
+    });
+});