@loopover/engine 1.0.0

package/dist/miner/attempt-log.js

@@ -0,0 +1,100 @@
+// Driver-level structured attempt log — pure event shapes (#4294). Mirrors `governor-ledger.ts`: fixed vocabulary,
+// fail-closed normalization, JSON-round-trip-verified payloads. SQLite persistence + JSONL export live in
+// `packages/gittensory-miner/lib/attempt-log.js`, which imports this normalizer from the engine package.
+export const ATTEMPT_LOG_EVENT_TYPES = Object.freeze([
+    "attempt_started",
+    "attempt_tool_edit",
+    "attempt_shadow",
+    "attempt_succeeded",
+    "attempt_failed",
+    "attempt_aborted",
+]);
+const attemptEventTypeSet = new Set(ATTEMPT_LOG_EVENT_TYPES);
+const codingAgentModes = new Set(["paused", "dry_run", "live"]);
+/* v8 ignore start -- Normalization helpers are covered through normalizeAttemptLogEvent export tests. */
+function normalizeRequiredString(value, code) {
+    if (typeof value !== "string")
+        throw new Error(code);
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(code);
+    return trimmed;
+}
+function jsonRoundTripEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    const aIsArray = Array.isArray(a);
+    if (aIsArray !== Array.isArray(b))
+        return false;
+    if (aIsArray) {
+        const bArr = b;
+        const aArr = a;
+        return aArr.length === bArr.length && aArr.every((value, index) => jsonRoundTripEqual(value, bArr[index]));
+    }
+    const aKeys = Object.keys(a);
+    const bRecord = b;
+    return aKeys.length === Object.keys(bRecord).length && aKeys.every((key) => Object.hasOwn(bRecord, key) && jsonRoundTripEqual(a[key], bRecord[key]));
+}
+function serializePayload(payload) {
+    if (payload === undefined)
+        return "{}";
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new Error("invalid_payload");
+    }
+    let json;
+    try {
+        json = JSON.stringify(payload);
+    }
+    catch {
+        throw new Error("invalid_payload");
+    }
+    if (!jsonRoundTripEqual(JSON.parse(json), payload)) {
+        throw new Error("invalid_payload");
+    }
+    return json;
+}
+/* v8 ignore stop */
+function normalizeMode(value) {
+    const mode = normalizeRequiredString(value, "invalid_mode");
+    if (!codingAgentModes.has(mode))
+        throw new Error("invalid_mode");
+    return mode;
+}
+/** Validate and normalize an attempt-log row before append. Fail-closed on unknown types/modes. */
+export function normalizeAttemptLogEvent(input) {
+    if (!input || typeof input !== "object")
+        throw new Error("invalid_event");
+    const event = input;
+    const eventType = normalizeRequiredString(event.eventType, "invalid_event_type");
+    if (!attemptEventTypeSet.has(eventType))
+        throw new Error("invalid_event_type");
+    return {
+        eventType: eventType,
+        attemptId: normalizeRequiredString(event.attemptId, "invalid_attempt_id"),
+        actionClass: normalizeRequiredString(event.actionClass, "invalid_action_class"),
+        mode: normalizeMode(event.mode),
+        reason: normalizeRequiredString(event.reason, "invalid_reason"),
+        payloadJson: serializePayload(event.payload),
+    };
+}
+/** Serialize normalized events as JSONL (one attempt's trace). Pure. */
+export function formatAttemptLogJsonl(events) {
+    return events.map((event) => JSON.stringify(event)).join("\n");
+}
+/** In-memory appender for tests and local tooling — production persistence uses `gittensory-miner/lib/attempt-log.js`. */
+export function createAttemptLogBuffer() {
+    const rows = [];
+    return {
+        append(event) {
+            const normalized = normalizeAttemptLogEvent(event);
+            rows.push(normalized);
+            return normalized;
+        },
+        events: () => rows,
+        jsonl: () => formatAttemptLogJsonl(rows),
+    };
+}

package/dist/miner/attempt-metering.d.ts

@@ -0,0 +1,39 @@
+/** One usage increment normalized to the metered unit. `costUsd` is 0 when a driver can't report spend. */
+export type AttemptUsage = {
+    /** Model tokens consumed (prompt + completion) in this increment. */
+    tokens: number;
+    /** Agent turns (one full agent iteration) in this increment. */
+    turns: number;
+    /** Wall-clock milliseconds elapsed in this increment. */
+    wallClockMs: number;
+    /** Monetary cost (USD) of this increment; 0 when the driver does not report spend. */
+    costUsd: number;
+};
+/** Accumulated attempt totals — same shape as a single increment. */
+export type AttemptMeterTotals = AttemptUsage;
+/** Per-axis ceilings. An omitted axis means "no limit on that axis". */
+export type AttemptBudget = {
+    maxTokens?: number;
+    maxTurns?: number;
+    maxWallClockMs?: number;
+    maxCostUsd?: number;
+};
+/** Which metered axes have reached or exceeded their ceiling. */
+export type AttemptBudgetAxis = "tokens" | "turns" | "wallClockMs" | "costUsd";
+export type AttemptMeterVerdict = {
+    totals: AttemptMeterTotals;
+    /** True when no axis has reached its ceiling. */
+    withinBudget: boolean;
+    /** The axes at/over ceiling (empty when within budget). */
+    breaches: AttemptBudgetAxis[];
+};
+/** Fold one usage increment into a running total. Pure — returns a new total, mutates nothing. */
+export declare function accumulateAttemptUsage(total: AttemptMeterTotals, next: AttemptUsage): AttemptMeterTotals;
+/** Sum a sequence of usage increments from zero. Pure. */
+export declare function meterAttemptUsage(increments: readonly AttemptUsage[]): AttemptMeterTotals;
+/**
+ * Evaluate accumulated totals against a budget. An axis is breached when its total is **at or above** its
+ * ceiling (`>=`), so a total exactly equal to the ceiling counts as a breach — the boundary the caller must
+ * stop on. An omitted ceiling never breaches. Pure and deterministic.
+ */
+export declare function evaluateAttemptBudget(totals: AttemptMeterTotals, budget: AttemptBudget): AttemptMeterVerdict;

package/dist/miner/attempt-metering.js

@@ -0,0 +1,67 @@
+// Per-attempt cost/turn metering (#4311): pure accumulation of a coding-agent attempt's usage
+// (tokens / turns / wall-clock / cost) plus a pure evaluation of the running totals against a configured
+// budget. Numbers only — no IO, no Date.now(), no randomness, no enforcement. This module reports whether a
+// ceiling has been reached; it never stops, kills, or gates a driver. That enforcement wiring (graceful-stop
+// vs. hard SIGKILL) and the attempt-log persistence (#4294) are separate, maintainer-owned concerns.
+//
+// Mirrors the governor/rate-limit.ts discipline ("computes numbers only... does NOT store state, schedule,
+// or gate any write action"). Drivers report usage in different native shapes (CLI-subprocess vs. Agent-SDK);
+// the caller normalizes each increment to the {tokens, turns, wallClockMs, costUsd} unit defined here.
+const ZERO_USAGE = { tokens: 0, turns: 0, wallClockMs: 0, costUsd: 0 };
+function assertNonNegativeFiniteNumber(name, value) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${name} must be a finite, non-negative number`);
+    }
+}
+function assertAttemptUsage(name, usage) {
+    assertNonNegativeFiniteNumber(`${name}.tokens`, usage.tokens);
+    assertNonNegativeFiniteNumber(`${name}.turns`, usage.turns);
+    assertNonNegativeFiniteNumber(`${name}.wallClockMs`, usage.wallClockMs);
+    assertNonNegativeFiniteNumber(`${name}.costUsd`, usage.costUsd);
+}
+function assertAttemptBudget(budget) {
+    if (budget.maxTokens !== undefined)
+        assertNonNegativeFiniteNumber("budget.maxTokens", budget.maxTokens);
+    if (budget.maxTurns !== undefined)
+        assertNonNegativeFiniteNumber("budget.maxTurns", budget.maxTurns);
+    if (budget.maxWallClockMs !== undefined) {
+        assertNonNegativeFiniteNumber("budget.maxWallClockMs", budget.maxWallClockMs);
+    }
+    if (budget.maxCostUsd !== undefined)
+        assertNonNegativeFiniteNumber("budget.maxCostUsd", budget.maxCostUsd);
+}
+/** Fold one usage increment into a running total. Pure — returns a new total, mutates nothing. */
+export function accumulateAttemptUsage(total, next) {
+    assertAttemptUsage("total", total);
+    assertAttemptUsage("next", next);
+    return {
+        tokens: total.tokens + next.tokens,
+        turns: total.turns + next.turns,
+        wallClockMs: total.wallClockMs + next.wallClockMs,
+        costUsd: total.costUsd + next.costUsd,
+    };
+}
+/** Sum a sequence of usage increments from zero. Pure. */
+export function meterAttemptUsage(increments) {
+    return increments.reduce(accumulateAttemptUsage, { ...ZERO_USAGE });
+}
+/**
+ * Evaluate accumulated totals against a budget. An axis is breached when its total is **at or above** its
+ * ceiling (`>=`), so a total exactly equal to the ceiling counts as a breach — the boundary the caller must
+ * stop on. An omitted ceiling never breaches. Pure and deterministic.
+ */
+export function evaluateAttemptBudget(totals, budget) {
+    assertAttemptUsage("totals", totals);
+    assertAttemptBudget(budget);
+    const breaches = [];
+    if (budget.maxTokens !== undefined && totals.tokens >= budget.maxTokens)
+        breaches.push("tokens");
+    if (budget.maxTurns !== undefined && totals.turns >= budget.maxTurns)
+        breaches.push("turns");
+    if (budget.maxWallClockMs !== undefined && totals.wallClockMs >= budget.maxWallClockMs) {
+        breaches.push("wallClockMs");
+    }
+    if (budget.maxCostUsd !== undefined && totals.costUsd >= budget.maxCostUsd)
+        breaches.push("costUsd");
+    return { totals, withinBudget: breaches.length === 0, breaches };
+}

package/dist/miner/cli-subprocess-driver.d.ts

@@ -0,0 +1,68 @@
+import type { CodingAgentDriver, CodingAgentDriverTask } from "./coding-agent-driver.js";
+/** The spawn primitive a CLI driver depends on — the generalized shape of src/selfhost/ai.ts's `SpawnFn`. Injected
+ *  so the driver never hardcodes `child_process`; a fake resolves this in tests. */
+export type CliSubprocessSpawnFn = (cmd: string, args: readonly string[], opts: {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    timeoutMs: number;
+    firstOutputTimeoutMs?: number;
+}) => Promise<{
+    stdout: string;
+    code: number | null;
+    stderr?: string;
+    timedOut?: boolean;
+    stalledNoOutput?: boolean;
+}>;
+export type CliSubprocessDriverOptions = {
+    /** The coding-agent CLI to spawn (e.g. "claude" or "codex"). */
+    command: string;
+    /** Injected spawn — a real `child_process` spawn in prod, a fake in tests. */
+    spawn: CliSubprocessSpawnFn;
+    /** Per-run wall-clock budget handed to the spawn. Default: 120000ms. */
+    timeoutMs?: number;
+    /** Optional fast-fail deadline (#4994/#5053): killed early and reported distinctly ("stalled", not a generic
+     *  timeout) if the subprocess produces zero stdout before this elapses. Mirrors src/selfhost/ai.ts's
+     *  `firstOutputTimeoutMs`/`resolveClaudeFirstOutputTimeoutMs` pattern, built after a naive single-timeout design
+     *  caused a real production outage against these same claude/codex binaries. Opt-in and backward compatible:
+     *  omitting it leaves behavior exactly as it was before this option existed. */
+    firstOutputTimeoutMs?: number;
+    /** Parent env to allowlist from. Default: `{}` (a real caller passes `process.env`; the default stays pure). */
+    parentEnv?: Record<string, string | undefined>;
+    /** Extra env overlaid on the allowlisted parent (e.g. an auth value the CLI reads). */
+    env?: Record<string, string | undefined>;
+    /** Known secret values (e.g. an injected auth token) to strip from any surfaced output, on top of the well-known
+     *  token-shape patterns. */
+    knownSecrets?: readonly string[];
+    /** Build the CLI argv from a task. Defaults to `defaultClaudeCliArgs`/`defaultCodexCliArgs` based on
+     *  `command` -- a caller overrides this to point at a different real CLI's own flags. */
+    buildArgs?: (task: CodingAgentDriverTask) => readonly string[];
+};
+/** Real, verified `claude -p` non-interactive argv (confirmed against `claude --help` and a live invocation,
+ *  #5135 follow-up -- the previous default argv here used `--max-turns`/`--acceptance-criteria`, neither of
+ *  which is a real `claude` CLI flag, and never passed `-p`/`--print` at all, meaning a spawned `claude`
+ *  process would start an INTERACTIVE session against a subprocess whose stdin is closed).
+ *  - `-p`/`--print` is REQUIRED for non-interactive use; without it `claude` starts an interactive session.
+ *  - `--output-format json` produces a single parseable JSON result on stdout, matching `claudeErrorStatus`'s
+ *    own `JSON.parse(stdout.trim())` assumption (which was already written for this shape, just never
+ *    actually triggered because this flag was never passed).
+ *  - `--permission-mode acceptEdits` is the same edit-permission scope the Agent-SDK driver already uses
+ *    (#4267) -- file edits run unattended inside the scoped worktree, nothing broader.
+ *  There is no turn-budget flag on the real CLI (verified via `claude --help`) and no acceptance-criteria
+ *  flag either -- the coding agent discovers `task.acceptanceCriteriaPath` itself via its own Read tool
+ *  inside the scoped working directory, exactly like the Agent-SDK driver already does (agent-sdk-driver.ts
+ *  never passes it as a distinct option either; only `task.instructions` is forwarded as the prompt there
+ *  too). The wall-clock `timeoutMs` (already implemented) is this provider's only real turn/cost ceiling. */
+export declare function defaultClaudeCliArgs(task: CodingAgentDriverTask): string[];
+/** Real, verified `codex exec` non-interactive argv (confirmed against `codex exec --help`, #5135
+ *  follow-up). `exec` is a REQUIRED subcommand -- without it `codex` starts an interactive session, the same
+ *  class of bug the missing `-p` had for claude. `--json` emits the JSONL event stream
+ *  `codexErrorFromStdout` already parses line-by-line. `--sandbox workspace-write` is codex's own equivalent
+ *  of claude's `acceptEdits` -- the model may write within the workspace, nothing broader. Same "no
+ *  turn-budget flag" and "no acceptance-criteria flag" gaps as claude apply here too. */
+export declare function defaultCodexCliArgs(task: CodingAgentDriverTask): string[];
+/**
+ * Create a {@link CodingAgentDriver} that runs the coding agent as a CLI subprocess. A non-zero or absent exit
+ * code, or a timeout, yields `ok: false` with a redacted error; exit `0` yields `ok: true`. Any subprocess output
+ * kept as a transcript or folded into an error is redacted first.
+ */
+export declare function createCliSubprocessCodingAgentDriver(options: CliSubprocessDriverOptions): CodingAgentDriver;

package/dist/miner/cli-subprocess-driver.js

@@ -0,0 +1,272 @@
+import { buildAllowlistedEnv, redactSecrets } from "../subprocess-env.js";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TRANSCRIPT_CHARS = 8000;
+const MAX_ERROR_DETAIL_CHARS = 500;
+const CODING_AGENT_ENV_ALLOWLIST = [
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "LANG",
+    "LC_ALL",
+    "NODE_EXTRA_CA_CERTS",
+    "NO_PROXY",
+    "PATH",
+    "SSL_CERT_DIR",
+    "SSL_CERT_FILE",
+    "TERM",
+    "https_proxy",
+    "http_proxy",
+    "no_proxy",
+];
+/** Real, verified `claude -p` non-interactive argv (confirmed against `claude --help` and a live invocation,
+ *  #5135 follow-up -- the previous default argv here used `--max-turns`/`--acceptance-criteria`, neither of
+ *  which is a real `claude` CLI flag, and never passed `-p`/`--print` at all, meaning a spawned `claude`
+ *  process would start an INTERACTIVE session against a subprocess whose stdin is closed).
+ *  - `-p`/`--print` is REQUIRED for non-interactive use; without it `claude` starts an interactive session.
+ *  - `--output-format json` produces a single parseable JSON result on stdout, matching `claudeErrorStatus`'s
+ *    own `JSON.parse(stdout.trim())` assumption (which was already written for this shape, just never
+ *    actually triggered because this flag was never passed).
+ *  - `--permission-mode acceptEdits` is the same edit-permission scope the Agent-SDK driver already uses
+ *    (#4267) -- file edits run unattended inside the scoped worktree, nothing broader.
+ *  There is no turn-budget flag on the real CLI (verified via `claude --help`) and no acceptance-criteria
+ *  flag either -- the coding agent discovers `task.acceptanceCriteriaPath` itself via its own Read tool
+ *  inside the scoped working directory, exactly like the Agent-SDK driver already does (agent-sdk-driver.ts
+ *  never passes it as a distinct option either; only `task.instructions` is forwarded as the prompt there
+ *  too). The wall-clock `timeoutMs` (already implemented) is this provider's only real turn/cost ceiling. */
+export function defaultClaudeCliArgs(task) {
+    return ["--print", "--output-format", "json", "--permission-mode", "acceptEdits", task.instructions];
+}
+/** Real, verified `codex exec` non-interactive argv (confirmed against `codex exec --help`, #5135
+ *  follow-up). `exec` is a REQUIRED subcommand -- without it `codex` starts an interactive session, the same
+ *  class of bug the missing `-p` had for claude. `--json` emits the JSONL event stream
+ *  `codexErrorFromStdout` already parses line-by-line. `--sandbox workspace-write` is codex's own equivalent
+ *  of claude's `acceptEdits` -- the model may write within the workspace, nothing broader. Same "no
+ *  turn-budget flag" and "no acceptance-criteria flag" gaps as claude apply here too. */
+export function defaultCodexCliArgs(task) {
+    return ["exec", "--json", "--sandbox", "workspace-write", task.instructions];
+}
+/** Resolve the default argv builder for a known production command; throws for anything else so an
+ *  unrecognized `command` fails at driver-construction time (never silently invokes a binary with no known
+ *  real argv shape) unless the caller supplies an explicit `options.buildArgs` override. */
+function resolveDefaultBuildArgs(command) {
+    if (command === "claude")
+        return defaultClaudeCliArgs;
+    if (command === "codex")
+        return defaultCodexCliArgs;
+    throw new Error(`unsupported_cli_subprocess_command:${command}`);
+}
+/** Best-effort real dollar-cost extraction from a CLI's own stdout. Mirrors src/selfhost/ai.ts's
+ *  `extractCliUsage`/`COST_KEYS` (redeclared here, not imported, per this file's own no-src-import
+ *  convention) but narrowed to just the cost field this driver's `CodingAgentDriverResult` surfaces -- tokens
+ *  and model aren't part of that shape. Tries the whole trimmed stdout as one JSON object first (claude's
+ *  `--output-format json` shape, empirically confirmed to carry `total_cost_usd`, the exact same field name
+ *  the Agent-SDK's own result message carries), then scans line by line (codex's `--json` JSONL stream,
+ *  "still evolving" per src/selfhost/ai.ts's own comment, so multiple real key spellings are tolerated). A
+ *  missing/malformed field means "no cost signal", never an error -- never fabricated. */
+const COST_KEYS = ["total_cost_usd", "totalCostUsd", "cost_usd", "costUsd"];
+function finiteNonNegativeNumber(value) {
+    const n = typeof value === "number" ? value : typeof value === "string" && value.trim() ? Number(value) : NaN;
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function costUsdFromRecord(record) {
+    let best;
+    for (const key of COST_KEYS) {
+        const n = finiteNonNegativeNumber(record[key]);
+        if (n !== undefined)
+            best = Math.max(best ?? 0, n);
+    }
+    return best;
+}
+function extractCostUsd(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return undefined;
+    let best;
+    const tryLine = (text) => {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const n = costUsdFromRecord(parsed);
+                if (n !== undefined)
+                    best = Math.max(best ?? 0, n);
+            }
+        }
+        catch {
+            /* not JSON -- best-effort only */
+        }
+    };
+    tryLine(trimmed);
+    for (const line of trimmed.split(/\r?\n/)) {
+        if (line.trim())
+            tryLine(line);
+    }
+    return best;
+}
+/** Claude Code's `--output-format json` sometimes exits non-zero while still emitting a structured
+ *  `{is_error, api_error_status}` envelope on stdout (e.g. an auth/model error). Ported from
+ *  src/selfhost/ai.ts's `claudeErrorStatus` -- redeclared here rather than imported, per this file's own
+ *  no-src-import convention (see header comment). Returns null on absent/malformed stdout, in which case the
+ *  caller falls back to the generic exit-code error unchanged (#5168). */
+function claudeErrorStatus(stdout) {
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        if (parsed.is_error === true)
+            return String(parsed.api_error_status ?? parsed.subtype ?? "unknown");
+    }
+    catch {
+        /* not a single JSON object -- handled by the caller's generic exit-code fallback */
+    }
+    return null;
+}
+/** Codex's stderr is typically just an uninformative "Reading prompt from stdin..." startup banner; the real
+ *  error (auth failure, unknown model, API error) lands in its JSONL stdout instead. Scans lines in reverse
+ *  (the error object is usually last) and returns the first human-readable detail found, or null. Ported from
+ *  src/selfhost/ai.ts's `codexErrorFromStdout` -- redeclared here (not imported) per this file's own
+ *  no-src-import convention, and returns the RAW detail unredacted; the caller applies this driver's own
+ *  knownSecrets-aware `redactSecrets` at the call site (#5169). */
+function codexErrorFromStdout(stdout) {
+    const lines = stdout.trim().split(/\r?\n/);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = lines[i];
+        if (!line?.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const errorObj = parsed.error;
+            const detail = (typeof parsed.error === "string" && parsed.error) ||
+                (typeof parsed.message === "string" && parsed.message) ||
+                (typeof parsed.msg === "string" && parsed.msg) ||
+                (errorObj && typeof errorObj.message === "string" ? errorObj.message : null) ||
+                null;
+            if (detail)
+                return detail;
+        }
+        catch {
+            /* not JSON -- skip */
+        }
+    }
+    return null;
+}
+/**
+ * Create a {@link CodingAgentDriver} that runs the coding agent as a CLI subprocess. A non-zero or absent exit
+ * code, or a timeout, yields `ok: false` with a redacted error; exit `0` yields `ok: true`. Any subprocess output
+ * kept as a transcript or folded into an error is redacted first.
+ */
+export function createCliSubprocessCodingAgentDriver(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const buildArgs = options.buildArgs ?? resolveDefaultBuildArgs(options.command);
+    const knownSecrets = options.knownSecrets ?? [];
+    return {
+        async run(task) {
+            const env = buildAllowlistedEnv(options.parentEnv ?? {}, CODING_AGENT_ENV_ALLOWLIST, options.env ?? {});
+            const spawned = await options.spawn(options.command, buildArgs(task), {
+                cwd: task.workingDirectory,
+                env,
+                timeoutMs,
+                ...(options.firstOutputTimeoutMs !== undefined
+                    ? { firstOutputTimeoutMs: options.firstOutputTimeoutMs }
+                    : {}),
+            });
+            const transcript = redactSecrets(spawned.stdout, knownSecrets).slice(0, MAX_TRANSCRIPT_CHARS);
+            if (spawned.timedOut && spawned.stalledNoOutput) {
+                // Fast-fail path (#4994/#5053): killed at firstOutputTimeoutMs, well before the full timeoutMs, because
+                // stdout produced no bytes at all. A distinct error (never reusing `${command}_timeout_...`) so this
+                // stall is separately countable in logs/Sentry from a genuine full timeout where the process was at
+                // least emitting output before it was killed.
+                return {
+                    ok: false,
+                    changedFiles: [],
+                    summary: `${options.command} stalled with no stdout within ${options.firstOutputTimeoutMs}ms`,
+                    transcript,
+                    error: `${options.command}_stalled_no_output`,
+                };
+            }
+            if (spawned.timedOut) {
+                return {
+                    ok: false,
+                    changedFiles: [],
+                    summary: `${options.command} timed out after ${timeoutMs}ms`,
+                    transcript,
+                    error: `${options.command}_timeout_${timeoutMs}ms`,
+                };
+            }
+            if (spawned.code !== 0) {
+                if (options.command === "claude") {
+                    const errStatus = claudeErrorStatus(spawned.stdout);
+                    if (errStatus) {
+                        return {
+                            ok: false,
+                            changedFiles: [],
+                            summary: `${options.command} exited non-zero`,
+                            transcript,
+                            error: redactSecrets(`claude_code_error_${errStatus}`, knownSecrets),
+                        };
+                    }
+                }
+                if (options.command === "codex") {
+                    const stderrTrimmed = (spawned.stderr ?? "").trim();
+                    const jsonlDetail = codexErrorFromStdout(spawned.stdout);
+                    if (!jsonlDetail && stderrTrimmed === "Reading prompt from stdin...") {
+                        // codex's JSONL stream carried no structured detail and stderr is ONLY the stdin-reading banner (no
+                        // API/auth error appended) -- auth.json was present at boot-time but is now expired or was deleted.
+                        // A distinct, actionable remediation instead of the generic exit-code string (#5169).
+                        return {
+                            ok: false,
+                            changedFiles: [],
+                            summary: `${options.command} exited non-zero`,
+                            transcript,
+                            error: redactSecrets("codex_no_auth: auth.json missing or expired -- run `codex auth` to authenticate", knownSecrets),
+                        };
+                    }
+                    if (jsonlDetail) {
+                        // Prefer the structured error from codex's JSONL stdout over the uninformative stderr startup
+                        // message -- codex reports auth/model/API failures in its JSON stream, not stderr.
+                        const detail = redactSecrets(jsonlDetail, knownSecrets).slice(0, MAX_ERROR_DETAIL_CHARS);
+                        return {
+                            ok: false,
+                            changedFiles: [],
+                            summary: `${options.command} exited non-zero`,
+                            transcript,
+                            error: `${options.command}_exit_${spawned.code}: ${detail}`,
+                        };
+                    }
+                }
+                const stderr = (spawned.stderr ?? "").trim();
+                const detail = redactSecrets(stderr || `exit ${spawned.code}`, knownSecrets).slice(0, MAX_ERROR_DETAIL_CHARS);
+                return {
+                    ok: false,
+                    changedFiles: [],
+                    summary: `${options.command} exited non-zero`,
+                    transcript,
+                    error: `${options.command}_exit_${spawned.code}: ${detail}`,
+                };
+            }
+            // Claude Code's own documented behavior: `--output-format json` "sometimes exits non-zero", implying
+            // it can ALSO exit 0 while still reporting `is_error: true` in its structured JSON envelope (confirmed
+            // empirically: a live `claude -p --output-format json` invocation returns a real `is_error`/`subtype`
+            // field on every result, success or not). claudeErrorStatus was already written to detect exactly this
+            // shape but, before this fix, was only ever checked on the `code !== 0` branch above -- a code-0 error
+            // envelope silently read as `ok: true`. Checked here, not folded into that branch, since it's a
+            // genuinely different condition (exit code 0).
+            if (options.command === "claude") {
+                const errStatus = claudeErrorStatus(spawned.stdout);
+                if (errStatus) {
+                    return {
+                        ok: false,
+                        changedFiles: [],
+                        summary: `${options.command} exited 0 but reported an error envelope`,
+                        transcript,
+                        error: redactSecrets(`claude_code_error_${errStatus}`, knownSecrets),
+                    };
+                }
+            }
+            const costUsd = extractCostUsd(spawned.stdout);
+            return {
+                ok: true,
+                changedFiles: [],
+                summary: `${options.command} completed for ${task.attemptId}`,
+                transcript,
+                ...(costUsd !== undefined ? { costUsd } : {}),
+            };
+        },
+    };
+}

package/dist/miner/coding-agent-driver.d.ts

@@ -0,0 +1,33 @@
+/** Scoped local task handed to every driver implementation — no GitHub writes, no autonomous continue/stop. */
+export type CodingAgentDriverTask = {
+    attemptId: string;
+    workingDirectory: string;
+    acceptanceCriteriaPath: string;
+    instructions: string;
+    maxTurns: number;
+};
+/** Provider-agnostic result — nothing here assumes a subprocess CLI vs. an Agent SDK `query()` loop. */
+export type CodingAgentDriverResult = {
+    ok: boolean;
+    changedFiles: readonly string[];
+    summary: string;
+    /** Opaque provider transcript for operator inspection; absent when the driver did not run. */
+    transcript?: string | undefined;
+    turnsUsed?: number | undefined;
+    /** Real dollar cost of this driver run, when the provider reports one. Absent (not zero) when the provider
+     *  never got far enough to have a cost, or reports no cost signal at all -- never fabricated. */
+    costUsd?: number | undefined;
+    error?: string | undefined;
+};
+export interface CodingAgentDriver {
+    run(task: CodingAgentDriverTask): Promise<CodingAgentDriverResult>;
+}
+/** Minimal in-memory fake for contract/parity tests — records the last task without IO. */
+export declare function createFakeCodingAgentDriver(impl?: Partial<{
+    run: CodingAgentDriver["run"];
+    lastTask: CodingAgentDriverTask | null;
+}>): CodingAgentDriver & {
+    lastTask: CodingAgentDriverTask | null;
+};
+/** Default-OFF stub driver for factory resolution tests — never touches the filesystem. */
+export declare function createNoopCodingAgentDriver(): CodingAgentDriver;

package/dist/miner/coding-agent-driver.js

@@ -0,0 +1,36 @@
+// `CodingAgentDriver` interface seam (#4262). Mirrors `SelfHostAi` (`src/selfhost/ai.ts:60-63`): a single `run()`
+// method, provider-agnostic task/result types, and injectable deps on concrete implementations (spawn fn, clock,
+// filesystem) rather than hardcoded globals. Implementations MAY perform real IO; this file defines only the
+// contract — orchestration (mode gating, attempt logging, factory selection) lives in sibling miner modules.
+/** Minimal in-memory fake for contract/parity tests — records the last task without IO. */
+export function createFakeCodingAgentDriver(impl = {}) {
+    const state = { lastTask: impl.lastTask ?? null };
+    return {
+        get lastTask() {
+            return state.lastTask;
+        },
+        run: impl.run ??
+            (async (task) => {
+                state.lastTask = task;
+                return {
+                    ok: true,
+                    changedFiles: [],
+                    summary: `fake driver ran ${task.attemptId}`,
+                    turnsUsed: 0,
+                };
+            }),
+    };
+}
+/** Default-OFF stub driver for factory resolution tests — never touches the filesystem. */
+export function createNoopCodingAgentDriver() {
+    return {
+        async run(task) {
+            return {
+                ok: true,
+                changedFiles: [],
+                summary: `noop driver acknowledged ${task.attemptId}`,
+                turnsUsed: 0,
+            };
+        },
+    };
+}

package/dist/miner/coding-agent-invoke.d.ts

@@ -0,0 +1,11 @@
+import type { CodingAgentDriver, CodingAgentDriverResult, CodingAgentDriverTask } from "./coding-agent-driver.js";
+import { type CodingAgentExecutionMode } from "./coding-agent-mode.js";
+import type { AttemptLogEvent } from "./attempt-log.js";
+export type AttemptLogSink = {
+    append(event: AttemptLogEvent): void;
+};
+/**
+ * Invoke a driver under the resolved execution mode. `paused` and `dry_run` never call `driver.run()` — see
+ * `coding-agent-mode.ts` for the dry-run tradeoff documentation.
+ */
+export declare function invokeCodingAgentDriver(driver: CodingAgentDriver, mode: CodingAgentExecutionMode, task: CodingAgentDriverTask, log?: AttemptLogSink | undefined): Promise<CodingAgentDriverResult>;