@delegance/claude-autopilot 5.2.2 → 6.2.2

package/dist/src/cli/preflight.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { runSafe } from "../core/shell.js";
 import { detectLLMKey, loadEnvFile, LLM_KEY_NAMES } from "../core/detect/llm-key.js";
 import { findPackageRoot } from "./_pkg-root.js";
+import { isSdkInstalled } from "../adapters/sdk-loader.js";
 const PASS = '\x1b[32m✓\x1b[0m';
 const FAIL = '\x1b[31m✗\x1b[0m';
 const WARN = '\x1b[33m!\x1b[0m';
@@ -29,6 +30,39 @@ function skillRoots() {
         roots.push(path.join(home, '.claude', 'plugins'));
     return roots.filter(p => fs.existsSync(p));
 }
+/**
+ * Reads `deploy.adapter` from guardrail.config.yaml without pulling in the
+ * full config loader (which validates against a JSON schema and would noise
+ * up the doctor output). Returns `null` if the config or field is absent.
+ */
+function readDeployAdapter(configPath) {
+    if (!fs.existsSync(configPath))
+        return null;
+    try {
+        const text = fs.readFileSync(configPath, 'utf8');
+        // Match `deploy:` block then look for `adapter:` two lines down. Cheap
+        // line-based parse — avoids js-yaml dependency in the doctor path.
+        const lines = text.split(/\r?\n/);
+        let inDeploy = false;
+        for (const line of lines) {
+            if (/^deploy\s*:\s*$/.test(line)) {
+                inDeploy = true;
+                continue;
+            }
+            if (inDeploy && /^\S/.test(line))
+                inDeploy = false; // dedented out of block
+            if (inDeploy) {
+                const m = line.match(/^\s+adapter\s*:\s*['"]?([a-zA-Z0-9_-]+)['"]?\s*$/);
+                if (m)
+                    return m[1] ?? null;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 export function findMissingSuperpowersSkills() {
     // Traverse each root once, collect all discovered skill names, then diff against
     // the required set. Previous implementation did N × roots separate recursive walks.
@@ -173,7 +207,74 @@ export async function runDoctor() {
             ? 'git user.name / user.email not set — commits will fail.'
             : undefined,
     });
-    // 9. Superpowers plugin — required for pipeline phases, optional for review-only use
+    // 9. LLM SDK install state — surfaces which providers are usable. After
+    //    the v5.5 lazy-load refactor, three SDKs moved to optionalDependencies;
+    //    `--omit=optional` users may have removed them. This check shows users
+    //    which providers will work without `npm install <sdk>`.
+    const sdkChecks = [
+        { pkg: '@anthropic-ai/sdk', provider: 'claude' },
+        { pkg: 'openai', provider: 'openai/codex' },
+        { pkg: '@google/generative-ai', provider: 'gemini' },
+    ];
+    const installed = [];
+    const missing = [];
+    for (const { pkg } of sdkChecks) {
+        if (await isSdkInstalled(pkg))
+            installed.push(pkg);
+        else
+            missing.push(pkg);
+    }
+    checks.push({
+        name: `LLM SDKs installed (${installed.length}/${sdkChecks.length})`,
+        result: installed.length === 0 ? 'fail' : missing.length > 0 ? 'warn' : 'pass',
+        message: installed.length === 0
+            ? `No LLM SDKs found. Install at least one: ${sdkChecks.map(s => s.pkg).join(', ')}`
+            : missing.length > 0
+                ? `Missing (run npm install <pkg> to enable): ${missing.join(', ')}`
+                : undefined,
+    });
+    // 10. Vercel deploy adapter auth (Phase 6 of v5.4 spec). Detects
+    //     `deploy.adapter: vercel` in guardrail.config.yaml and verifies the
+    //     auth token is set. Warn-not-fail because users without deploy
+    //     configured don't care.
+    const deployAdapter = readDeployAdapter(configYaml);
+    if (deployAdapter === 'vercel') {
+        const token = process.env.VERCEL_TOKEN ?? envVars['VERCEL_TOKEN'];
+        checks.push({
+            name: 'VERCEL_TOKEN (deploy adapter: vercel)',
+            result: token ? 'pass' : 'warn',
+            message: token
+                ? undefined
+                : 'deploy.adapter is "vercel" but VERCEL_TOKEN is not set. Generate one at https://vercel.com/account/tokens',
+        });
+    }
+    // 10b. Fly.io deploy adapter auth (Phase 6 of v5.6 spec). Mirrors the
+    //      Vercel check above — warn-not-fail when FLY_API_TOKEN is missing
+    //      and the configured adapter is `fly`.
+    if (deployAdapter === 'fly') {
+        const token = process.env.FLY_API_TOKEN ?? envVars['FLY_API_TOKEN'];
+        checks.push({
+            name: 'FLY_API_TOKEN (deploy adapter: fly)',
+            result: token ? 'pass' : 'warn',
+            message: token
+                ? undefined
+                : 'deploy.adapter is "fly" but FLY_API_TOKEN is not set. Generate one at https://fly.io/dashboard/personal/tokens',
+        });
+    }
+    // 10c. Render deploy adapter auth (Phase 6 of v5.6 spec). Mirrors the
+    //      Vercel/Fly checks — warn-not-fail when RENDER_API_KEY is missing
+    //      and the configured adapter is `render`.
+    if (deployAdapter === 'render') {
+        const token = process.env.RENDER_API_KEY ?? envVars['RENDER_API_KEY'];
+        checks.push({
+            name: 'RENDER_API_KEY (deploy adapter: render)',
+            result: token ? 'pass' : 'warn',
+            message: token
+                ? undefined
+                : 'deploy.adapter is "render" but RENDER_API_KEY is not set. Generate one at https://dashboard.render.com/u/settings#api-keys',
+        });
+    }
+    // 11. Superpowers plugin — required for pipeline phases, optional for review-only use
     const missingSkills = findMissingSuperpowersSkills();
     const allSkillsFound = missingSkills.length === 0;
     checks.push({

package/dist/src/cli/review.d.ts

@@ -0,0 +1,27 @@
+export interface ReviewCommandOptions {
+    cwd?: string;
+    configPath?: string;
+    /**
+     * Optional context note injected into the review log. The actual review
+     * content (LLM-driven code review against a PR diff or working tree) is
+     * produced by the Claude Code review skills (`/review`, `/review-2pass`,
+     * `pr-review-toolkit:review-pr`); this CLI verb is the engine-wrap shell
+     * so v6 pipeline runs can checkpoint a `review` phase entry.
+     */
+    context?: string;
+    /**
+     * Where to write the review log file. Defaults to
+     * `.guardrail-cache/reviews/<timestamp>-review.md` so it lands inside the
+     * cache that's already gitignored. The path is recorded on ReviewOutput so
+     * the engine path can persist it as `result` for replay.
+     */
+    outputPath?: string;
+    /**
+     * v6.0.4 — engine knob inputs. Same shape and precedence as scan / costs /
+     * fix / plan (CLI > env > config > built-in default off in v6.0.x).
+     */
+    cliEngine?: boolean;
+    envEngine?: string;
+}
+export declare function runReview(options?: ReviewCommandOptions): Promise<number>;
+//# sourceMappingURL=review.d.ts.map

package/dist/src/cli/review.js

@@ -0,0 +1,126 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { loadConfig } from "../core/config/loader.js";
+import { runPhaseWithLifecycle } from "../core/run-state/run-phase-with-lifecycle.js";
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m', red: '\x1b[31m',
+};
+const fmt = (c, t) => `${C[c]}${t}${C.reset}`;
+export async function runReview(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = options.configPath ?? path.join(cwd, 'guardrail.config.yaml');
+    let config = { configVersion: 1 };
+    if (fs.existsSync(configPath)) {
+        const loaded = await loadConfig(configPath);
+        if (loaded)
+            config = loaded;
+    }
+    // INTENTIONAL DEVIATION FROM THE SPEC TABLE (preserved in v6.0.6):
+    // the v6 spec (docs/specs/v6-run-state-engine.md) lists `review` with
+    // externalRefs `review-comments`, implying the phase posts review
+    // comments to a GitHub PR (which would make `hasSideEffects: true`).
+    // The implementation here does NOT post anywhere — it writes a review
+    // log to a local file under .guardrail-cache/reviews/ and stops.
+    // Posting per-line comments to a PR is owned by `claude-autopilot pr`
+    // (which already has `--inline-comments` / `--post-comments`); the
+    // `review` verb is the engine-wrap shell for the LLM-driven code
+    // review skills (`/review`, `/review-2pass`, `pr-review-toolkit:review-pr`)
+    // so pipeline runs can checkpoint a `review` phase entry. Therefore
+    // `idempotent: true, hasSideEffects: false` is correct for the wrapped
+    // behavior. If a future PR adds platform-side comment posting to this
+    // verb, both declarations will need to flip and the readback rules in
+    // the wrapping recipe will need to plumb a `review-comments` externalRef.
+    const context = options.context ?? null;
+    const outputPath = options.outputPath
+        ? path.resolve(cwd, options.outputPath)
+        : path.join(cwd, '.guardrail-cache', 'reviews', `${new Date().toISOString().replace(/[:.]/g, '-')}-review.md`);
+    const reviewInput = { cwd, context, outputPath };
+    // The wrapped phase body — writes a review log stub to disk. The actual
+    // LLM-driven review content is produced by the Claude Code review skills.
+    // Engine-off callers invoke this directly via `executeReviewPhase()`;
+    // engine-on callers route through `runPhase()`.
+    const phase = {
+        name: 'review',
+        // Re-running the review verb against the same context writes the same
+        // log file. Engine treats local file writes as overwrite-style — same
+        // precedent as scan's findings-cache.
+        idempotent: true,
+        // Local file write only — no PR comment posting, no git push, no
+        // provider-side mutation. See the long deviation note above where the
+        // engine resolution is computed.
+        hasSideEffects: false,
+        run: async (input) => executeReviewPhase(input),
+    };
+    // v6.0.6 — lifecycle wiring lives in `runPhaseWithLifecycle`.
+    let output;
+    try {
+        const result = await runPhaseWithLifecycle({
+            cwd,
+            phase,
+            input: reviewInput,
+            config,
+            cliEngine: options.cliEngine,
+            envEngine: options.envEngine,
+            runEngineOff: () => executeReviewPhase(reviewInput),
+        });
+        output = result.output;
+    }
+    catch {
+        return 1;
+    }
+    return renderReviewOutput(output, reviewInput);
+}
+// ---------------------------------------------------------------------------
+// Phase body — write a review log stub. Pure: no console output, no exit
+// codes. Returns a JSON-serializable ReviewOutput so the engine can persist
+// it as `result` on the phase snapshot. The actual LLM-driven review
+// content is produced by the Claude Code review skills; this CLI verb's
+// job is to provide a checkpointable phase shell.
+// ---------------------------------------------------------------------------
+async function executeReviewPhase(input) {
+    const { context, outputPath } = input;
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    const lines = [
+        '# Review',
+        '',
+        `Generated: ${new Date().toISOString()}`,
+        '',
+        context ? `Context: ${context}` : 'Context: (none provided)',
+        '',
+        '<!--',
+        'This is the v6 engine-wrap stub for the `review` phase. The actual',
+        'LLM-driven review content is produced by the Claude Code review skills',
+        '(`/review`, `/review-2pass`, `pr-review-toolkit:review-pr`). The CLI',
+        'verb exists to provide a checkpointable phase shell so',
+        '`claude-autopilot runs show <id>` reflects a `review` phase entry when',
+        'the pipeline includes one. PR-side comment posting lives in',
+        '`claude-autopilot pr --inline-comments` / `--post-comments`, which is',
+        'a separate verb.',
+        '-->',
+        '',
+    ];
+    fs.writeFileSync(outputPath, lines.join('\n'), 'utf8');
+    return {
+        reviewLogPath: outputPath,
+        context,
+    };
+}
+// ---------------------------------------------------------------------------
+// Render — translate ReviewOutput back to a stdout summary + exit code.
+// Lives outside the wrapped phase because it's pure presentation.
+// ---------------------------------------------------------------------------
+function renderReviewOutput(output, input) {
+    const { reviewLogPath, context } = output;
+    const { cwd } = input;
+    console.log('');
+    console.log(fmt('bold', '[review]') + ' ' + fmt('dim', context ? `context: ${context}` : 'no context provided'));
+    console.log(fmt('dim', `  → ${path.relative(cwd, reviewLogPath)}`));
+    console.log('');
+    console.log(fmt('cyan', 'Note:') + fmt('dim', ' the LLM-driven reviewer lives in Claude Code (superpowers:requesting-code-review,'));
+    console.log(fmt('dim', '       /review, /review-2pass, pr-review-toolkit:review-pr).'));
+    console.log(fmt('dim', '       PR comment posting lives in `claude-autopilot pr` (--inline-comments / --post-comments).'));
+    console.log('');
+    return 0;
+}
+//# sourceMappingURL=review.js.map

package/dist/src/cli/runs-watch-renderer.d.ts

@@ -0,0 +1,45 @@
+import type { BudgetConfig } from '../core/run-state/budget.ts';
+import type { RunEvent, RunState } from '../core/run-state/types.ts';
+type Color = 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'bold-red' | 'bold-green' | 'bold-yellow' | 'dim';
+/** Wrap `text` in `color` if ansi is enabled, else return as-is. */
+export declare function colorize(text: string, color: Color, ansi: boolean): string;
+/** Strip ANSI escape sequences. Public so tests can assert against plain
+ *  text without worrying about whether the renderer was called with
+ *  ansi=true. */
+export declare function stripAnsi(s: string): string;
+/** Format a USD amount with two decimals + leading $. Used in cost lines and
+ *  budget bars. Negative amounts (over-budget) are shown as `-$X.YZ`. */
+export declare function fmtUSD(amount: number): string;
+export interface RenderOptions {
+    /** When false, no ANSI escape codes are emitted. Default true. The verb
+     *  forces this off under --json or when stdout is not a TTY. */
+    ansi: boolean;
+    /** When true, the renderer emits compact two-column output (timestamp +
+     *  one-line event) without the header. Used for live tailing. Default
+     *  is true; --no-follow snapshot mode flips it off + adds the header. */
+    compact?: boolean;
+}
+/** Render the running cost vs. configured per-run cap as a single line.
+ *  Color thresholds: <50% green, 50-90% yellow, >90% red. When budget is
+ *  null (no BudgetConfig recorded), shows just the running total. */
+export declare function renderBudgetBar(totalCostUSD: number, budget: BudgetConfig | null, opts: RenderOptions): string;
+/** Render the run header — the play arrow + run id, the phase plan, and the
+ *  initial budget line. Returns an array of lines (no trailing newlines).
+ *  The verb prints these at startup. */
+export declare function renderHeader(state: RunState, budget: BudgetConfig | null, opts: RenderOptions): string[];
+/** Render one event as a single output line. `runningTotal` is the running
+ *  cost AFTER this event has been folded in (for `phase.cost`) — the verb
+ *  is responsible for accumulating; this function only formats. */
+export declare function renderEventLine(ev: RunEvent, runningTotal: number, opts: RenderOptions): string;
+export interface FinalSummary {
+    runId: string;
+    status: 'success' | 'failed' | 'aborted' | 'paused' | 'running' | 'pending' | 'interrupted';
+    totalCostUSD: number;
+    /** Wall clock from run start to now, in milliseconds. */
+    durationMs: number;
+}
+/** One- or two-line goodbye block. Engine-on runs produce a real summary
+ *  here; Ctrl-C interrupts get the same shape with status='interrupted'. */
+export declare function renderFinalSummary(s: FinalSummary, opts: RenderOptions): string[];
+export {};
+//# sourceMappingURL=runs-watch-renderer.d.ts.map

package/dist/src/cli/runs-watch-renderer.js

@@ -0,0 +1,275 @@
+// src/cli/runs-watch-renderer.ts
+//
+// Pure renderer for `runs watch <id>`. Every function here is referentially
+// transparent — no file I/O, no clock reads, no subprocess calls — so the
+// demo-grade live cost meter is testable as a pile of string assertions.
+//
+// The verb in `runs-watch.ts` reads events.ndjson, accumulates a running
+// total, and calls `renderEventLine` for each new event. Headers are rendered
+// once via `renderHeader`. Final summary is rendered via `renderFinalSummary`.
+//
+// Spec: tasks/v6.1-runs-watch.md "Pretty rendering" + "YC-demo polish".
+// ----------------------------------------------------------------------------
+// ANSI helpers. Single source of truth so tests can flip ansi=false and
+// assert plain text trivially.
+// ----------------------------------------------------------------------------
+const ANSI_RESET = '\x1b[0m';
+const ANSI_BOLD = '\x1b[1m';
+const ANSI_DIM = '\x1b[2m';
+const ANSI_RED = '\x1b[31m';
+const ANSI_GREEN = '\x1b[32m';
+const ANSI_YELLOW = '\x1b[33m';
+const ANSI_BLUE = '\x1b[34m';
+const ANSI_MAGENTA = '\x1b[35m';
+const ANSI_CYAN = '\x1b[36m';
+function colorCode(c) {
+    switch (c) {
+        case 'red': return ANSI_RED;
+        case 'green': return ANSI_GREEN;
+        case 'yellow': return ANSI_YELLOW;
+        case 'blue': return ANSI_BLUE;
+        case 'magenta': return ANSI_MAGENTA;
+        case 'cyan': return ANSI_CYAN;
+        case 'bold-red': return ANSI_BOLD + ANSI_RED;
+        case 'bold-green': return ANSI_BOLD + ANSI_GREEN;
+        case 'bold-yellow': return ANSI_BOLD + ANSI_YELLOW;
+        case 'dim': return ANSI_DIM;
+    }
+}
+/** Wrap `text` in `color` if ansi is enabled, else return as-is. */
+export function colorize(text, color, ansi) {
+    if (!ansi)
+        return text;
+    return colorCode(color) + text + ANSI_RESET;
+}
+/** Strip ANSI escape sequences. Public so tests can assert against plain
+ *  text without worrying about whether the renderer was called with
+ *  ansi=true. */
+export function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+// ----------------------------------------------------------------------------
+// Money + duration formatting.
+// ----------------------------------------------------------------------------
+/** Format a USD amount with two decimals + leading $. Used in cost lines and
+ *  budget bars. Negative amounts (over-budget) are shown as `-$X.YZ`. */
+export function fmtUSD(amount) {
+    if (amount < 0)
+        return `-$${(-amount).toFixed(2)}`;
+    return `$${amount.toFixed(2)}`;
+}
+/** Format a token count with k/M suffixes when the number is large. Keeps
+ *  cost lines readable on narrow terminals — `123.4k` instead of `123412`. */
+function fmtTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return String(n);
+}
+function fmtDurationMs(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const minutes = Math.floor(ms / 60_000);
+    const seconds = Math.floor((ms % 60_000) / 1000);
+    return `${minutes}m${seconds.toString().padStart(2, '0')}s`;
+}
+/** Pull the time portion out of an ISO timestamp — `12:00:42` from
+ *  `2026-05-04T12:00:42.123Z`. Returns the original string on parse
+ *  failure so the renderer never throws on malformed events. */
+function fmtTimestamp(iso) {
+    const m = /T(\d{2}:\d{2}:\d{2})/.exec(iso);
+    return m ? m[1] : iso;
+}
+// ----------------------------------------------------------------------------
+// Budget bar.
+// ----------------------------------------------------------------------------
+/** Render the running cost vs. configured per-run cap as a single line.
+ *  Color thresholds: <50% green, 50-90% yellow, >90% red. When budget is
+ *  null (no BudgetConfig recorded), shows just the running total. */
+export function renderBudgetBar(totalCostUSD, budget, opts) {
+    if (budget === null) {
+        return `  budget: ${fmtUSD(totalCostUSD)} (no cap configured)`;
+    }
+    const cap = budget.perRunUSD;
+    const pctRaw = cap > 0 ? (totalCostUSD / cap) * 100 : 0;
+    // Clamp the percentage label to [0, 999] so absurd over-budget runs still
+    // fit a fixed-width column. The underlying number stays untruncated for
+    // the cost figure itself.
+    const pctLabel = Math.min(999, Math.max(0, Math.round(pctRaw)));
+    let color;
+    if (pctRaw > 90)
+        color = 'red';
+    else if (pctRaw >= 50)
+        color = 'yellow';
+    else
+        color = 'green';
+    const body = `${fmtUSD(totalCostUSD)} / ${fmtUSD(cap)} (${pctLabel}%)`;
+    return `  budget: ${colorize(body, color, opts.ansi)}`;
+}
+// ----------------------------------------------------------------------------
+// Header.
+// ----------------------------------------------------------------------------
+/** Render the run header — the play arrow + run id, the phase plan, and the
+ *  initial budget line. Returns an array of lines (no trailing newlines).
+ *  The verb prints these at startup. */
+export function renderHeader(state, budget, opts) {
+    const lines = [];
+    // Bullet glyph: ▶ in TTY, "*" in plain mode for screen-reader friendliness.
+    const bullet = opts.ansi ? '▶' : '*';
+    lines.push(`${colorize(bullet, 'cyan', opts.ansi)} run ${state.runId}`);
+    if (state.phases.length > 0) {
+        const phaseList = state.phases
+            .map(p => colorPhase(p.name, p.status, opts))
+            .join(opts.ansi ? ' → ' : ' -> ');
+        lines.push(`  phases: ${phaseList}`);
+    }
+    lines.push(renderBudgetBar(state.totalCostUSD, budget, opts));
+    return lines;
+}
+function colorPhase(name, status, opts) {
+    switch (status) {
+        case 'succeeded':
+            return colorize(name, 'green', opts.ansi);
+        case 'running':
+            return colorize(name, 'cyan', opts.ansi);
+        case 'failed':
+            return colorize(name, 'red', opts.ansi);
+        case 'aborted':
+            return colorize(name, 'red', opts.ansi);
+        case 'skipped':
+            return colorize(name, 'dim', opts.ansi);
+        case 'pending':
+        default:
+            return colorize(name, 'dim', opts.ansi);
+    }
+}
+// ----------------------------------------------------------------------------
+// Per-event line. The core of the live tail.
+// ----------------------------------------------------------------------------
+/** Total-column width — pads the running total so it scans visually as a
+ *  fixed right-most column. Picked to fit `total: $9999.99` cleanly. */
+const TOTAL_COL_WIDTH = 18;
+/** Render one event as a single output line. `runningTotal` is the running
+ *  cost AFTER this event has been folded in (for `phase.cost`) — the verb
+ *  is responsible for accumulating; this function only formats. */
+export function renderEventLine(ev, runningTotal, opts) {
+    const ts = `[${fmtTimestamp(ev.ts)}]`;
+    // The "verb" column. Padded so the body of the line aligns visually.
+    const verb = padRight(ev.event, 20);
+    switch (ev.event) {
+        case 'run.start': {
+            const phaseList = ev.phases.join(', ');
+            return `${ts} ${colorize(verb, 'cyan', opts.ansi)} phases=[${phaseList}]`;
+        }
+        case 'phase.start': {
+            const body = `${ev.phase}${ev.attempt > 1 ? `  (attempt ${ev.attempt})` : ''}`;
+            return `${ts} ${colorize(verb, 'cyan', opts.ansi)} ${body}`;
+        }
+        case 'phase.cost': {
+            const delta = colorize(`+${fmtUSD(ev.costUSD)}`, 'yellow', opts.ansi);
+            const tokens = `(in: ${fmtTokens(ev.inputTokens)}, out: ${fmtTokens(ev.outputTokens)})`;
+            const total = padLeft(`total: ${fmtUSD(runningTotal)}`, TOTAL_COL_WIDTH);
+            return `${ts} ${colorize(verb, 'yellow', opts.ansi)} ${padRight(ev.phase, 14)} ${delta}  ${tokens}  ${total}`;
+        }
+        case 'phase.success': {
+            const dur = fmtDurationMs(ev.durationMs);
+            // Box-drawing checkmark in TTY; plain "OK" in plain mode (per the
+            // ANSI-on-non-TTY rule above).
+            const glyph = opts.ansi ? '✓' : 'OK';
+            return `${ts} ${colorize(verb, 'green', opts.ansi)} ${padRight(ev.phase, 14)} ${colorize(glyph, 'green', opts.ansi)} ${dur}`;
+        }
+        case 'phase.failed': {
+            const dur = fmtDurationMs(ev.durationMs);
+            const errMsg = ev.error.length > 80 ? `${ev.error.slice(0, 77)}...` : ev.error;
+            const glyph = opts.ansi ? '✗' : 'FAIL';
+            return `${ts} ${colorize(verb, 'red', opts.ansi)} ${padRight(ev.phase, 14)} ${colorize(glyph, 'red', opts.ansi)} ${dur}  ${errMsg}`;
+        }
+        case 'phase.aborted': {
+            const glyph = opts.ansi ? '✗' : 'ABORT';
+            return `${ts} ${colorize(verb, 'red', opts.ansi)} ${padRight(ev.phase, 14)} ${colorize(glyph, 'red', opts.ansi)} reason=${ev.reason}`;
+        }
+        case 'phase.externalRef': {
+            // YC-demo polish — surface the kind+id inline so observers see the
+            // breadcrumb materialize as the phase runs (e.g. "→ github-pr#42").
+            const arrow = opts.ansi ? '→' : '->';
+            const refLabel = `${arrow} ${ev.ref.kind}#${ev.ref.id}`;
+            return `${ts} ${colorize(verb, 'magenta', opts.ansi)} ${padRight(ev.phase, 14)} ${colorize(refLabel, 'magenta', opts.ansi)}`;
+        }
+        case 'phase.needs-human': {
+            return `${ts} ${colorize(verb, 'yellow', opts.ansi)} ${padRight(ev.phase, 14)} reason=${ev.reason}`;
+        }
+        case 'budget.check': {
+            const decisionColor = ev.decision === 'hard-fail' ? 'red'
+                : ev.decision === 'pause' ? 'yellow'
+                    : 'dim';
+            const body = `${ev.phase}  decision=${ev.decision}  capRemaining=${fmtUSD(ev.capRemaining)}`;
+            return `${ts} ${colorize(verb, decisionColor, opts.ansi)} ${body}`;
+        }
+        case 'run.complete': {
+            const dur = fmtDurationMs(ev.durationMs);
+            const statusColor = ev.status === 'success' ? 'bold-green'
+                : ev.status === 'failed' ? 'bold-red'
+                    : 'bold-red';
+            const body = `status=${ev.status}  totalCostUSD=${fmtUSD(ev.totalCostUSD)}  duration=${dur}`;
+            return `${ts} ${colorize(verb, statusColor, opts.ansi)} ${body}`;
+        }
+        case 'run.warning': {
+            return `${ts} ${colorize(verb, 'yellow', opts.ansi)} ${ev.message}`;
+        }
+        case 'run.recovery': {
+            return `${ts} ${colorize(verb, 'yellow', opts.ansi)} reason=${ev.reason}`;
+        }
+        case 'lock.takeover': {
+            return `${ts} ${colorize(verb, 'magenta', opts.ansi)} reason=${ev.reason}`;
+        }
+        case 'index.rebuilt': {
+            return `${ts} ${colorize(verb, 'dim', opts.ansi)} cause=${ev.cause}`;
+        }
+        case 'replay.override': {
+            return `${ts} ${colorize(verb, 'magenta', opts.ansi)} ${ev.phase}  reason=${ev.reason}`;
+        }
+        default: {
+            // Exhaustiveness guard. New event variants must be added here so a
+            // future RunEvent extension forces a compile error rather than
+            // silently rendering an opaque event.
+            const _exhaustive = ev;
+            void _exhaustive;
+            return `${ts} ${verb}`;
+        }
+    }
+}
+/** One- or two-line goodbye block. Engine-on runs produce a real summary
+ *  here; Ctrl-C interrupts get the same shape with status='interrupted'. */
+export function renderFinalSummary(s, opts) {
+    const status = s.status;
+    const color = status === 'success' ? 'bold-green'
+        : status === 'failed' ? 'bold-red'
+            : status === 'aborted' ? 'bold-red'
+                : status === 'interrupted' ? 'bold-yellow'
+                    : 'dim';
+    const dur = fmtDurationMs(s.durationMs);
+    const body = `status=${status}  totalCostUSD=${fmtUSD(s.totalCostUSD)}  duration=${dur}`;
+    return [
+        '',
+        `${colorize('done', color, opts.ansi)}  run ${s.runId}`,
+        `  ${body}`,
+    ];
+}
+// ----------------------------------------------------------------------------
+// Tiny string helpers (kept private to the renderer module).
+// ----------------------------------------------------------------------------
+function padRight(s, width) {
+    if (s.length >= width)
+        return s;
+    return s + ' '.repeat(width - s.length);
+}
+function padLeft(s, width) {
+    if (s.length >= width)
+        return s;
+    return ' '.repeat(width - s.length) + s;
+}
+//# sourceMappingURL=runs-watch-renderer.js.map

package/dist/src/cli/runs-watch.d.ts

@@ -0,0 +1,41 @@
+export interface RunsWatchCliResult {
+    exit: number;
+    stdout: string[];
+    stderr: string[];
+}
+export interface RunRunsWatchOptions {
+    runId: string;
+    cwd?: string;
+    /** Replay forward from this seq (1-based, matching the events.ndjson seq
+     *  field). Useful for resuming a watch after a disconnect. */
+    since?: number;
+    /** When true, render snapshot once and exit. No file watcher, no Ctrl-C
+     *  handler. Useful for one-shot status pulls. */
+    noFollow?: boolean;
+    /** When true, emit raw NDJSON (one event per line) to stdout instead of the
+     *  pretty rendering. ANSI is forced off. */
+    json?: boolean;
+    /** When true, force ANSI off regardless of TTY detection. Honored even
+     *  in default mode (e.g. `claude-autopilot runs watch <id> --no-color`). */
+    noColor?: boolean;
+    /** Override TTY detection. Tests pass `false` to assert ANSI-stripped
+     *  output. Production callers leave undefined; the verb consults
+     *  `process.stdout.isTTY`. */
+    __testIsTTY?: boolean;
+    /** Override `process.stdout.write`. Tests pass a buffer-collector so
+     *  they can assert on emitted lines without spawning. */
+    __testWriteStdout?: (chunk: string) => void;
+    /** Override `process.stderr.write`. Same shape as above. */
+    __testWriteStderr?: (chunk: string) => void;
+    /** Override the polling interval (ms). Default 1000; tests pass a much
+     *  smaller value to make live-tail tests run quickly. */
+    __testPollIntervalMs?: number;
+    /** When set, the verb resolves with this status the moment the watcher
+     *  observes a `run.complete` (or matching terminal event). Tests use this
+     *  to assert the auto-exit-on-completion behavior without a real signal. */
+    __testStopAfterTerminal?: boolean;
+}
+/** Public entry point — exported so the dispatcher in runs.ts can call us
+ *  uniformly with the other verbs.  */
+export declare function runRunsWatch(opts: RunRunsWatchOptions): Promise<RunsWatchCliResult>;
+//# sourceMappingURL=runs-watch.d.ts.map