@delegance/claude-autopilot 5.2.2 → 6.2.2

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

@@ -0,0 +1,395 @@
+// src/cli/runs-watch.ts
+//
+// `runs watch <runId>` — tails a run's events.ndjson and renders a live
+// cost/token meter that updates as phases execute.
+//
+// Tail strategy: fs.watchFile with a 1s polling interval. fs.watch (inotify
+// on Linux, FSEvents on macOS) is unreliable for append-only logs in our
+// matrix — it sometimes never fires for tiny appends, sometimes fires twice
+// per write. Polling is consistent across darwin / linux / win32 and the
+// 1-second cadence is plenty for a human-facing meter.
+//
+// Modes:
+//   default          pretty-rendered live tail (header + per-event lines + final summary)
+//   --no-follow      render snapshot once, exit
+//   --json           emit raw NDJSON to stdout (for piping to jq / dashboards)
+//   --since <seq>    replay forward from a specific seq (resume after disconnect)
+//
+// Spec: tasks/v6.1-runs-watch.md.
+import * as fs from 'node:fs';
+import { GuardrailError } from "../core/errors.js";
+import { foldEvents, readEvents, eventsPath } from "../core/run-state/events.js";
+import { readStateSnapshot } from "../core/run-state/state.js";
+import { runDirFor } from "../core/run-state/runs.js";
+import { isValidULID } from "../core/run-state/ulid.js";
+import { renderEventLine, renderFinalSummary, renderHeader, } from "./runs-watch-renderer.js";
+// ----------------------------------------------------------------------------
+// Implementation.
+// ----------------------------------------------------------------------------
+/** ULID validation, mirrors the helper in runs.ts. Inlined to avoid an
+ *  internal import that isn't exported. */
+function assertValidRunId(runId) {
+    if (!runId) {
+        throw new GuardrailError('a run id is required', {
+            code: 'invalid_config',
+            provider: 'runs-cli',
+            details: { runId },
+        });
+    }
+    if (!isValidULID(runId)) {
+        throw new GuardrailError(`run id is not a valid ULID: ${runId}`, {
+            code: 'invalid_config',
+            provider: 'runs-cli',
+            details: { runId },
+        });
+    }
+}
+function formatErr(err) {
+    if (err instanceof GuardrailError)
+        return `${err.code}: ${err.message}`;
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/** Pull a `BudgetConfig` out of `RunState.config` if one was recorded at
+ *  run-creation time. Returns null on any shape mismatch — we never throw,
+ *  the watcher should degrade gracefully when the budget block is absent. */
+function extractBudget(state) {
+    const cfg = state.config;
+    if (!cfg || typeof cfg !== 'object')
+        return null;
+    // Two recognized shapes:
+    //   1. `config.budget = { perRunUSD: ..., ... }` (preferred — matches
+    //      what `BudgetConfig` looks like in budget.ts)
+    //   2. `config.budgets = { perRunUSD: ..., ... }` (yaml plural alias —
+    //      matches what guardrail.config.yaml uses; see migration-guide.md
+    //      "Budget config" section)
+    const candidate = cfg.budget
+        ?? cfg.budgets;
+    if (!candidate || typeof candidate !== 'object')
+        return null;
+    const c = candidate;
+    if (typeof c.perRunUSD !== 'number')
+        return null;
+    const out = { perRunUSD: c.perRunUSD };
+    if (typeof c.perPhaseUSD === 'number')
+        out.perPhaseUSD = c.perPhaseUSD;
+    if (typeof c.conservativePhaseReserveUSD === 'number') {
+        out.conservativePhaseReserveUSD = c.conservativePhaseReserveUSD;
+    }
+    return out;
+}
+/** Fold the events list into a (totalCostUSD, terminalEvent) tuple. The
+ *  watcher uses this to know when to stop following — a terminal event is
+ *  any `run.complete`, the run-level `status` field on it, or a marker
+ *  event the verb treats as terminal. */
+function isTerminalEvent(ev) {
+    if (ev.event === 'run.complete')
+        return true;
+    return false;
+}
+/** Public entry point — exported so the dispatcher in runs.ts can call us
+ *  uniformly with the other verbs.  */
+export async function runRunsWatch(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const json = !!opts.json;
+    // ---- 1. Validate inputs --------------------------------------------------
+    try {
+        assertValidRunId(opts.runId);
+    }
+    catch (err) {
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [`[claude-autopilot] runs watch: ${formatErr(err)}`],
+        };
+    }
+    const runDir = runDirFor(cwd, opts.runId);
+    if (!fs.existsSync(runDir)) {
+        const err = new GuardrailError(`run not found: ${opts.runId}`, {
+            code: 'not_found',
+            provider: 'runs-cli',
+            details: { runId: opts.runId, runDir },
+        });
+        return {
+            exit: 2,
+            stdout: [],
+            stderr: [`[claude-autopilot] runs watch: ${formatErr(err)}`],
+        };
+    }
+    if (opts.since !== undefined && (!Number.isFinite(opts.since) || opts.since < 0)) {
+        const err = new GuardrailError(`--since must be a non-negative integer (got ${opts.since})`, { code: 'invalid_config', provider: 'runs-cli', details: { since: opts.since } });
+        return {
+            exit: 1,
+            stdout: [],
+            stderr: [`[claude-autopilot] runs watch: ${formatErr(err)}`],
+        };
+    }
+    // ---- 2. Decide ANSI mode -------------------------------------------------
+    //
+    // ansi=true iff:
+    //   - not --json mode, AND
+    //   - --no-color was not passed, AND
+    //   - NO_COLOR env var not set, AND
+    //   - stdout is a TTY (via the test seam or the real flag)
+    const realIsTTY = opts.__testIsTTY !== undefined ? opts.__testIsTTY : !!process.stdout.isTTY;
+    const ansi = !json && !opts.noColor && !process.env.NO_COLOR && realIsTTY;
+    const renderOpts = { ansi };
+    // ---- 3. Read initial state -----------------------------------------------
+    let state;
+    try {
+        state = readStateSnapshot(runDir);
+    }
+    catch {
+        state = null;
+    }
+    // Fall back to events replay if state.json is missing/corrupt — this is
+    // the same path runs show takes. Watch should never refuse to start on
+    // snapshot drift; events.ndjson is authoritative.
+    if (!state) {
+        try {
+            state = foldEvents(runDir, readEvents(runDir).events);
+        }
+        catch (err) {
+            return {
+                exit: 1,
+                stdout: [],
+                stderr: [`[claude-autopilot] runs watch: ${formatErr(err)}`],
+            };
+        }
+    }
+    const budget = extractBudget(state);
+    // The output sinks. In tests these are buffer-collectors; in production
+    // they wrap process.stdout / process.stderr.
+    const stdoutLines = [];
+    const stderrLines = [];
+    const writeStdout = opts.__testWriteStdout
+        ?? ((s) => { stdoutLines.push(s.endsWith('\n') ? s.slice(0, -1) : s); });
+    const writeStderr = opts.__testWriteStderr
+        ?? ((s) => { stderrLines.push(s.endsWith('\n') ? s.slice(0, -1) : s); });
+    // ---- 4. Snapshot mode (--no-follow) --------------------------------------
+    if (opts.noFollow) {
+        const since = opts.since ?? 0;
+        let runningTotal = 0;
+        let allEvents;
+        try {
+            allEvents = readEvents(runDir).events;
+        }
+        catch (err) {
+            return {
+                exit: 1,
+                stdout: [],
+                stderr: [`[claude-autopilot] runs watch: ${formatErr(err)}`],
+            };
+        }
+        if (json) {
+            // JSON mode: dump every event from `since` forward as raw NDJSON.
+            // Strict channel discipline — exactly the bytes that landed on disk.
+            for (const ev of allEvents) {
+                if (ev.seq < since)
+                    continue;
+                writeStdout(JSON.stringify(ev) + '\n');
+            }
+            return finishOk(stdoutLines, stderrLines);
+        }
+        // Pretty: header + every event-line.
+        for (const line of renderHeader(state, budget, renderOpts))
+            writeStdout(line + '\n');
+        for (const ev of allEvents) {
+            if (ev.seq < since)
+                continue;
+            if (ev.event === 'phase.cost')
+                runningTotal += ev.costUSD;
+            writeStdout(renderEventLine(ev, runningTotal, renderOpts) + '\n');
+        }
+        // Final summary if the run terminated.
+        if (state.status === 'success' || state.status === 'failed' || state.status === 'aborted') {
+            const summary = {
+                runId: state.runId,
+                status: state.status,
+                totalCostUSD: state.totalCostUSD,
+                durationMs: computeDurationMs(state),
+            };
+            for (const line of renderFinalSummary(summary, renderOpts))
+                writeStdout(line + '\n');
+        }
+        return finishOk(stdoutLines, stderrLines);
+    }
+    // ---- 5. Live tail mode ---------------------------------------------------
+    // We re-read the file from byte 0 each poll cycle (simpler than offset
+    // tracking and the file is bounded). We track lastSeq to decide which
+    // events are new. The `since` flag is treated as a floor on what we
+    // print, not on what we read — we always need the full event stream
+    // to compute runningTotal correctly.
+    const since = opts.since ?? 0;
+    let lastSeq = 0;
+    let runningTotal = 0;
+    // Print header up front (default mode only — JSON pipes the raw stream).
+    if (!json) {
+        for (const line of renderHeader(state, budget, renderOpts))
+            writeStdout(line + '\n');
+    }
+    // Drain whatever's already on disk.
+    const initialEvents = readEvents(runDir).events;
+    for (const ev of initialEvents) {
+        if (ev.event === 'phase.cost')
+            runningTotal += ev.costUSD;
+        if (ev.seq >= since) {
+            if (json)
+                writeStdout(JSON.stringify(ev) + '\n');
+            else
+                writeStdout(renderEventLine(ev, runningTotal, renderOpts) + '\n');
+        }
+        lastSeq = Math.max(lastSeq, ev.seq);
+    }
+    // Did the run already terminate before we started watching? Short-circuit
+    // so the verb doesn't hang waiting for events that will never arrive.
+    const terminalAlready = initialEvents.some(isTerminalEvent);
+    if (terminalAlready) {
+        if (!json) {
+            const finalState = foldEvents(runDir, initialEvents);
+            const summary = {
+                runId: finalState.runId,
+                status: finalState.status,
+                totalCostUSD: finalState.totalCostUSD,
+                durationMs: computeDurationMs(finalState),
+            };
+            for (const line of renderFinalSummary(summary, renderOpts))
+                writeStdout(line + '\n');
+        }
+        return finishOk(stdoutLines, stderrLines);
+    }
+    // Set up the polling watcher.
+    const eventsFile = eventsPath(runDir);
+    const pollInterval = opts.__testPollIntervalMs ?? 1000;
+    let lastFileSize = fs.existsSync(eventsFile) ? fs.statSync(eventsFile).size : 0;
+    return await new Promise(resolve => {
+        let resolved = false;
+        let sigintHandler = null;
+        const finish = (status, errMsg) => {
+            if (resolved)
+                return;
+            resolved = true;
+            try {
+                fs.unwatchFile(eventsFile);
+            }
+            catch { /* ignore */ }
+            if (sigintHandler) {
+                try {
+                    process.off('SIGINT', sigintHandler);
+                }
+                catch { /* ignore */ }
+            }
+            // Final summary in pretty mode.
+            if (!json) {
+                try {
+                    const finalEvents = readEvents(runDir).events;
+                    const finalState = foldEvents(runDir, finalEvents);
+                    const summary = {
+                        runId: finalState.runId,
+                        // For Ctrl-C (interrupted) we tag the summary that way even
+                        // though the run itself may still be running. The renderer
+                        // colors `interrupted` as bold-yellow.
+                        status: status === 'interrupted' ? 'interrupted' : finalState.status,
+                        totalCostUSD: finalState.totalCostUSD,
+                        durationMs: computeDurationMs(finalState),
+                    };
+                    for (const line of renderFinalSummary(summary, renderOpts)) {
+                        writeStdout(line + '\n');
+                    }
+                }
+                catch {
+                    // Ignore — final summary is best-effort.
+                }
+            }
+            const exit = status === 'error' ? 1 : 0;
+            const result = {
+                exit,
+                stdout: stdoutLines,
+                stderr: errMsg
+                    ? [...stderrLines, `[claude-autopilot] runs watch: ${errMsg}`]
+                    : stderrLines,
+            };
+            resolve(result);
+        };
+        const tick = () => {
+            // File-shrink recovery: if the file is smaller than last poll the
+            // log was rotated/truncated externally — re-read from start.
+            let stat = null;
+            try {
+                stat = fs.statSync(eventsFile);
+            }
+            catch {
+                // File doesn't exist yet — wait for it.
+                return;
+            }
+            if (stat.size < lastFileSize) {
+                // Truncation. Reset and re-fold from scratch.
+                lastSeq = 0;
+                runningTotal = 0;
+            }
+            lastFileSize = stat.size;
+            let events;
+            try {
+                events = readEvents(runDir).events;
+            }
+            catch (err) {
+                // Mid-log corruption — surface and exit. The runs doctor verb
+                // can be used to diagnose / fix.
+                finish('error', formatErr(err));
+                return;
+            }
+            for (const ev of events) {
+                if (ev.seq <= lastSeq)
+                    continue;
+                if (ev.event === 'phase.cost')
+                    runningTotal += ev.costUSD;
+                if (ev.seq >= since) {
+                    if (json)
+                        writeStdout(JSON.stringify(ev) + '\n');
+                    else
+                        writeStdout(renderEventLine(ev, runningTotal, renderOpts) + '\n');
+                }
+                lastSeq = ev.seq;
+                if (isTerminalEvent(ev)) {
+                    // Run terminated — drain remaining events (already done in the
+                    // loop) and exit.
+                    finish('completed');
+                    return;
+                }
+            }
+        };
+        // fs.watchFile polls at the interval we pass; the listener fires when
+        // mtime changes. We do an explicit tick on each fire because the file
+        // size delta isn't enough on its own (an event could land between
+        // polls).
+        fs.watchFile(eventsFile, { interval: pollInterval, persistent: true }, () => {
+            tick();
+        });
+        // Ctrl-C — clean exit with summary. The handler is removed by `finish`.
+        if (!opts.__testStopAfterTerminal) {
+            sigintHandler = () => finish('interrupted');
+            process.on('SIGINT', sigintHandler);
+        }
+        // First tick — we already drained initial events above, but kicking
+        // tick() once here covers the rare race where new events appended
+        // between our drain and our watchFile registration.
+        tick();
+    });
+}
+/** Compute wall-clock duration from a state snapshot. Used in the final
+ *  summary line. Falls back to 0 if the run hasn't started or the timestamps
+ *  are malformed. */
+function computeDurationMs(state) {
+    const start = Date.parse(state.startedAt);
+    if (!Number.isFinite(start))
+        return 0;
+    const end = state.endedAt ? Date.parse(state.endedAt) : Date.now();
+    if (!Number.isFinite(end))
+        return 0;
+    return Math.max(0, end - start);
+}
+function finishOk(stdout, stderr) {
+    return { exit: 0, stdout, stderr };
+}
+//# sourceMappingURL=runs-watch.js.map

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

@@ -0,0 +1,122 @@
+import { statePath } from '../core/run-state/state.ts';
+import type { ExternalRef, RunState, RunStatus } from '../core/run-state/types.ts';
+interface RunsCliResult {
+    exit: number;
+    /** Lines (will be newline-joined) for stdout under text mode. Under --json
+     *  mode this is replaced by a single envelope JSON line. */
+    stdout: string[];
+    /** Lines for stderr under text mode. Phase 5 will move all human warnings
+     *  into NDJSON events on stderr; Phase 3 keeps text-mode warnings here. */
+    stderr: string[];
+}
+export interface RunRunsListOptions {
+    cwd?: string;
+    status?: string;
+    json?: boolean;
+}
+/** `runs list` — newest-first listing. Optional --status filter narrows to
+ *  one RunStatus. `--json` emits an envelope; text mode prints a tight
+ *  table. */
+export declare function runRunsList(opts: RunRunsListOptions): Promise<RunsCliResult>;
+export interface RunRunsShowOptions {
+    runId: string;
+    cwd?: string;
+    /** Tail the events.ndjson log after the state summary. */
+    events?: boolean;
+    /** How many tail events to show with --events. Default 20. */
+    eventsTail?: number;
+    json?: boolean;
+}
+/** `runs show <id>` — render state.json (or replay if missing) plus, with
+ *  --events, the tail of events.ndjson. JSON mode bundles state + events into
+ *  the envelope. */
+export declare function runRunsShow(opts: RunRunsShowOptions): Promise<RunsCliResult>;
+export interface RunRunsGcOptions {
+    cwd?: string;
+    /** Default 30. */
+    olderThanDays?: number;
+    dryRun?: boolean;
+    json?: boolean;
+    /** Skip the interactive confirmation prompt. */
+    yes?: boolean;
+}
+/** `runs gc` — wraps gcRuns with confirmation. Default cutoff 30 days. With
+ *  --dry-run, lists what would be removed without touching disk. */
+export declare function runRunsGc(opts: RunRunsGcOptions): Promise<RunsCliResult>;
+export interface RunRunsDeleteOptions {
+    runId: string;
+    cwd?: string;
+    /** Override the terminal-status guard. */
+    force?: boolean;
+    json?: boolean;
+}
+/** `runs delete <id>` — explicit single-run delete. Refuses non-terminal
+ *  status without --force; refuses if the run lock is currently held by
+ *  another writer.
+ *
+ *  We acquire the lock for the duration of the delete so we never race a
+ *  concurrent writer. Lock acquisition uses a tiny timeout — we want
+ *  fail-fast over blocking. */
+export declare function runRunsDelete(opts: RunRunsDeleteOptions): Promise<RunsCliResult>;
+export type ResumeDecision = 'retry' | 'skip-idempotent' | 'needs-human' | 'already-complete';
+export interface RunResumeLookup {
+    runId: string;
+    status: RunStatus;
+    currentPhase: string | null;
+    nextPhase: string | null;
+    decision: ResumeDecision;
+    reason: string;
+    externalRefs: ExternalRef[];
+}
+export interface RunRunResumeOptions {
+    runId: string;
+    cwd?: string;
+    /** Optional explicit phase to resume from (by name). Surfaces as a
+     *  validation hint here; actual execution lands in Phase 6+. */
+    fromPhase?: string;
+    json?: boolean;
+}
+/** `run resume <id>` — Phase 3 LOOKUP ONLY.
+ *
+ *  This verb identifies which phase a future resume would pick up from and
+ *  the decision the engine would make per the spec's idempotency table. It
+ *  does NOT execute the phase — that wires in Phase 6+ once the budget
+ *  enforcer (Phase 4) and the JSON event stream (Phase 5) are in place.
+ *
+ *  Decision rules (mirror `runPhase` in src/core/run-state/phase-runner.ts):
+ *    - already-complete  : run.status === 'success' or every phase succeeded
+ *    - skip-idempotent   : nextPhase has a prior phase.success AND idempotent
+ *    - needs-human       : nextPhase has a prior phase.success AND side-effects
+ *    - retry             : default (no prior success — first attempt or retry
+ *                          of a failed attempt) */
+export declare function runRunResume(opts: RunRunResumeOptions): Promise<RunsCliResult>;
+/** Pure projection over a RunState that decides the next phase + replay rule.
+ *  Exported for tests. */
+export declare function computeResumeLookup(state: RunState, fromPhase?: string): RunResumeLookup;
+export interface RunRunsDoctorOptions {
+    cwd?: string;
+    /** Limit the check to a single run id. */
+    runId?: string;
+    /** Rewrite state.json from the events.ndjson replay where drift is found. */
+    fix?: boolean;
+    json?: boolean;
+}
+export interface RunsDoctorRunReport {
+    runId: string;
+    drift: 'none' | 'snapshot-vs-replay' | 'snapshot-missing' | 'snapshot-corrupt' | 'events-corrupt';
+    details?: string;
+    fixed?: boolean;
+}
+/** `runs doctor` — replay events.ndjson per run, compare against state.json,
+ *  report drift. With --fix, rewrite state.json from the replay where drift
+ *  exists.
+ *
+ *  Drift categories:
+ *    snapshot-vs-replay : both readable but disagree on a key field
+ *    snapshot-missing   : state.json absent, replay successful
+ *    snapshot-corrupt   : state.json present but unparseable
+ *    events-corrupt     : events.ndjson can't be folded (bigger problem)
+ */
+export declare function runRunsDoctor(opts: RunRunsDoctorOptions): Promise<RunsCliResult>;
+export { statePath };
+//# sourceMappingURL=runs.d.ts.map