agent-dealer 0.2.0 → 1.0.0

package/bundle/shared/dist/runtime-auth-health.d.ts

@@ -0,0 +1,66 @@
+import type { AgentHealthIssue } from "./agents.js";
+import type { Runtime } from "./runtime.js";
+/** Shared remediation for Cursor macOS keychain stuck-auth (NOT-114 / NOT-103). */
+export declare const CURSOR_KEYCHAIN_REMEDIATION: string;
+export declare const CURSOR_KEYCHAIN_HEALTH_ISSUE: AgentHealthIssue;
+/**
+ * Remediations quote both routes the CLI itself offers. The old Cursor message named only
+ * `cursor-agent login`, while the CLI's own logged-out line offers `agent login` *or*
+ * `CURSOR_API_KEY` — an operator running headless needs the second one.
+ */
+export declare const CURSOR_AUTH_REMEDIATION: string;
+export declare const CODEX_AUTH_REMEDIATION = "Run `codex login` (or set OPENAI_API_KEY for automation)";
+export declare const CLAUDE_AUTH_REMEDIATION: string;
+/**
+ * Used when text proves an auth failure but does not say which CLI printed it. All three
+ * runtimes print a bare `Not logged in`, so naming one of them there would be a guess — and
+ * a confidently wrong remediation (`cursor-agent login` for a Codex log) is worse than the
+ * generic crash reason it replaces.
+ */
+export declare const AMBIGUOUS_AUTH_REMEDIATION: string;
+/** Operator-facing runtime names for prose built out of a classification. */
+export declare const RUNTIME_AUTH_LABEL: Record<Runtime, string>;
+/** True when Cursor status/login/stderr indicates a stuck macOS keychain item. */
+export declare function isCursorKeychainStuckOutput(output: string): boolean;
+/**
+ * Classify one runtime's status/login/stderr text.
+ * Cursor's keychain case wins over its plain logged-out case — same symptom, different fix.
+ *
+ * For callers that *know* what they just ran — the health preflight probes one CLI and reads
+ * its output. Callers holding a log plus an unreliable label want
+ * `runtimeAuthClassificationForLog`: several runtimes print the same `Not logged in`, so
+ * "does this read as Cursor's auth failure" is not the same question as "did Cursor write it".
+ */
+export declare function runtimeAuthIssueFromOutput(runtime: Runtime, output: string): AgentHealthIssue | null;
+/**
+ * Classify Cursor auth health from status/login/stderr text.
+ * Also usable by session failure classifiers (NOT-113) for the same remediation string.
+ */
+export declare function cursorAuthIssueFromOutput(output: string): AgentHealthIssue | null;
+/** `runtime: null` means "definitely an auth failure, but the text does not name the CLI". */
+export type RuntimeAuthClassification = {
+    runtime: Runtime | null;
+    issue: AgentHealthIssue;
+};
+/**
+ * Classify a log and say which CLI wrote it, without trusting a caller's label over the
+ * text. The failure-reason classifier reads a spawn log by path and its idea of the runtime
+ * is a hint at best: `worker_sessions.runtime` is nullable, and older rows can disagree with
+ * what actually ran.
+ *
+ * Attribution is deliberately conservative, in this order:
+ *  1. a single vendor anchor in text that also reads as that runtime's auth failure — this
+ *     outranks `recordedRuntime`, because the log naming its own CLI is stronger evidence
+ *     than a row saying what was supposed to run;
+ *  2. otherwise `recordedRuntime`, when its own patterns recognise the text (nothing in the
+ *     log contradicts it, so the caller's label is the best evidence available);
+ *  3. otherwise, an auth failure only one runtime's patterns recognise at all;
+ *  4. otherwise unattributed (`runtime: null`) with the generic remediation.
+ *
+ * Trying the runtimes in a fixed order — or taking `recordedRuntime` at its word — reports
+ * Claude's `Not logged in · Please run /login` as Cursor, because Cursor's list carries the
+ * shared `not logged in` too, and hands the operator `cursor-agent login` for a Claude death.
+ */
+export declare function runtimeAuthClassificationForLog(output: string, recordedRuntime?: Runtime | null): RuntimeAuthClassification | null;
+/** `runtimeAuthClassificationForLog` for callers that hold no runtime label at all. */
+export declare function anyRuntimeAuthIssueFromOutput(output: string): RuntimeAuthClassification | null;

package/bundle/shared/dist/runtime-auth-health.js

@@ -0,0 +1,186 @@
+/** Shared remediation for Cursor macOS keychain stuck-auth (NOT-114 / NOT-103). */
+export const CURSOR_KEYCHAIN_REMEDIATION = "Cursor macOS keychain auth is stuck (errSecDuplicateItem). Delete the item and sign in again: " +
+    "`security delete-generic-password -s cursor-access-token -a cursor-user` then `agent login` " +
+    "(or `cursor-agent login`). See docs/TROUBLESHOOTING.md#cursor-macos-keychain-auth.";
+export const CURSOR_KEYCHAIN_HEALTH_ISSUE = {
+    code: "cursor_keychain",
+    message: CURSOR_KEYCHAIN_REMEDIATION,
+};
+/**
+ * Remediations quote both routes the CLI itself offers. The old Cursor message named only
+ * `cursor-agent login`, while the CLI's own logged-out line offers `agent login` *or*
+ * `CURSOR_API_KEY` — an operator running headless needs the second one.
+ */
+export const CURSOR_AUTH_REMEDIATION = "Cursor is not authenticated — run `cursor-agent login` (the CLI calls it `agent login`), " +
+    "or set CURSOR_API_KEY for automation";
+export const CODEX_AUTH_REMEDIATION = "Run `codex login` (or set OPENAI_API_KEY for automation)";
+export const CLAUDE_AUTH_REMEDIATION = "Claude Code is not authenticated — run `claude auth login` (`/login` inside a session), " +
+    "or set ANTHROPIC_API_KEY for automation";
+/**
+ * Used when text proves an auth failure but does not say which CLI printed it. All three
+ * runtimes print a bare `Not logged in`, so naming one of them there would be a guess — and
+ * a confidently wrong remediation (`cursor-agent login` for a Codex log) is worse than the
+ * generic crash reason it replaces.
+ */
+export const AMBIGUOUS_AUTH_REMEDIATION = "A runtime CLI reported it is not authenticated, but the log does not say which one — " +
+    "check the agent's runtime login: `cursor-agent login`, `codex login`, or `claude auth login`";
+const KEYCHAIN_STUCK_PATTERNS = [
+    /errsecduplicateitem/i,
+    /security exit code 45/i,
+    /keychain item is stuck/i,
+    /couldn't save your login to the macOS keychain/i,
+    /could not save your login to the macOS keychain/i,
+];
+/**
+ * Patterns are matched against raw CLI text, ANSI escapes and all — the captures keep
+ * theirs, and cursor-agent colourises the very lines we key on.
+ */
+const CURSOR_AUTH_PATTERNS = [
+    // `cursor-agent -p` when logged out (cursor-agent-print-logged-out.txt). The string
+    // NOT-133 was filed for: 12 sessions died on it while every pattern here missed.
+    /authentication required/i,
+    // Same line's remediation. Kept as a second anchor because remediation text drifts less
+    // than error prose — if the sentence above is reworded again, this still catches it.
+    /set CURSOR_API_KEY/i,
+    // `cursor-agent status` when logged out (cursor-agent-status-logged-out.txt) — exits 0.
+    /not logged in/i,
+    // `cursor-agent -p` with a bad CURSOR_API_KEY (cursor-agent-print-invalid-api-key.txt).
+    /the provided api key is invalid/i,
+    // Retained from NOT-114. No capture prints these, but removing them could only narrow
+    // coverage of CLI versions nobody has captured.
+    /login required/i,
+    /not authenticated/i,
+];
+const CODEX_AUTH_PATTERNS = [
+    // `codex login status` when logged out (codex-login-status-logged-out.txt) — exits 1.
+    /not logged in/i,
+    // `codex exec` when logged out (codex-exec-logged-out.txt): the session spawns and then
+    // fails every request, so this is what a dead codex session's log actually contains. Every
+    // such line in the capture names the endpoint it was refused by, and that qualifier stays
+    // in the pattern: a bare `401 Unauthorized` is not Codex's voice — the agent's own test run
+    // or curl shares the CLI's stderr, and an unrelated API's 401 must not read as a login.
+    /401 unauthorized[^\n]*api\.openai\.com/i,
+    /missing bearer or basic authentication/i,
+];
+const CLAUDE_AUTH_PATTERNS = [
+    // `claude -p` when logged out (claude-print-logged-out.txt): "Not logged in · Please run /login".
+    /not logged in/i,
+    /please run \/login/i,
+    // `claude auth status` when logged out (claude-auth-status-logged-out.txt) — exits 0, so
+    // the JSON body is the only signal.
+    /"loggedIn"\s*:\s*false/i,
+    // `claude -p` with an invalid ANTHROPIC_API_KEY (claude-print-invalid-api-key.txt).
+    /failed to authenticate/i,
+    /api key is invalid/i,
+];
+/**
+ * Which CLI *wrote* this text, as opposed to what it said. The auth pattern lists above
+ * overlap by design — `not logged in` is printed verbatim by cursor-agent, codex and claude
+ * alike — so they answer "is this an auth failure", never "whose failure is it". These
+ * anchors answer the second question: each names its own vendor, binary or credential
+ * variable, which no other runtime has a reason to print. Anything that matches none of them
+ * (or more than one) is left unattributed rather than guessed at.
+ */
+const RUNTIME_VENDOR_ANCHORS = {
+    // "set CURSOR_API_KEY environment variable" / "run `cursor-agent login`".
+    cursor_local: [/cursor[_-]api[_-]key/i, /cursor-agent\b/i],
+    // "OpenAI Codex v0.154.0", `codex login`, the `codex_api::` tracing target. A bare
+    // `openai` is not an anchor: any runtime's session can talk to api.openai.com.
+    codex_local: [/openai codex/i, /\bcodex\b/i],
+    // "Please run /login", ANTHROPIC_API_KEY, `claude auth login`. A bare `claude` is
+    // deliberately *not* an anchor: Cursor and Codex both name Claude models (`--model
+    // claude-...`), so it identifies a model, not the CLI that printed the line.
+    claude_code: [/anthropic/i, /please run \/login/i, /claude\s+(?:auth\s+)?login/i],
+};
+const AUTH_PATTERNS_BY_RUNTIME = {
+    cursor_local: CURSOR_AUTH_PATTERNS,
+    codex_local: CODEX_AUTH_PATTERNS,
+    claude_code: CLAUDE_AUTH_PATTERNS,
+};
+const ALL_RUNTIMES = ["cursor_local", "codex_local", "claude_code"];
+const REMEDIATION_BY_RUNTIME = {
+    cursor_local: CURSOR_AUTH_REMEDIATION,
+    codex_local: CODEX_AUTH_REMEDIATION,
+    claude_code: CLAUDE_AUTH_REMEDIATION,
+};
+/** Operator-facing runtime names for prose built out of a classification. */
+export const RUNTIME_AUTH_LABEL = {
+    cursor_local: "Cursor",
+    codex_local: "Codex",
+    claude_code: "Claude Code",
+};
+/** True when Cursor status/login/stderr indicates a stuck macOS keychain item. */
+export function isCursorKeychainStuckOutput(output) {
+    return KEYCHAIN_STUCK_PATTERNS.some((re) => re.test(output));
+}
+/**
+ * Classify one runtime's status/login/stderr text.
+ * Cursor's keychain case wins over its plain logged-out case — same symptom, different fix.
+ *
+ * For callers that *know* what they just ran — the health preflight probes one CLI and reads
+ * its output. Callers holding a log plus an unreliable label want
+ * `runtimeAuthClassificationForLog`: several runtimes print the same `Not logged in`, so
+ * "does this read as Cursor's auth failure" is not the same question as "did Cursor write it".
+ */
+export function runtimeAuthIssueFromOutput(runtime, output) {
+    if (runtime === "cursor_local" && isCursorKeychainStuckOutput(output)) {
+        return { ...CURSOR_KEYCHAIN_HEALTH_ISSUE };
+    }
+    if (AUTH_PATTERNS_BY_RUNTIME[runtime].some((re) => re.test(output))) {
+        return { code: "runtime_auth", message: REMEDIATION_BY_RUNTIME[runtime] };
+    }
+    return null;
+}
+/**
+ * Classify Cursor auth health from status/login/stderr text.
+ * Also usable by session failure classifiers (NOT-113) for the same remediation string.
+ */
+export function cursorAuthIssueFromOutput(output) {
+    return runtimeAuthIssueFromOutput("cursor_local", output);
+}
+/**
+ * Classify a log and say which CLI wrote it, without trusting a caller's label over the
+ * text. The failure-reason classifier reads a spawn log by path and its idea of the runtime
+ * is a hint at best: `worker_sessions.runtime` is nullable, and older rows can disagree with
+ * what actually ran.
+ *
+ * Attribution is deliberately conservative, in this order:
+ *  1. a single vendor anchor in text that also reads as that runtime's auth failure — this
+ *     outranks `recordedRuntime`, because the log naming its own CLI is stronger evidence
+ *     than a row saying what was supposed to run;
+ *  2. otherwise `recordedRuntime`, when its own patterns recognise the text (nothing in the
+ *     log contradicts it, so the caller's label is the best evidence available);
+ *  3. otherwise, an auth failure only one runtime's patterns recognise at all;
+ *  4. otherwise unattributed (`runtime: null`) with the generic remediation.
+ *
+ * Trying the runtimes in a fixed order — or taking `recordedRuntime` at its word — reports
+ * Claude's `Not logged in · Please run /login` as Cursor, because Cursor's list carries the
+ * shared `not logged in` too, and hands the operator `cursor-agent login` for a Claude death.
+ */
+export function runtimeAuthClassificationForLog(output, recordedRuntime) {
+    // The keychain signature names Cursor on its own (errSecDuplicateItem / macOS keychain).
+    if (isCursorKeychainStuckOutput(output)) {
+        return { runtime: "cursor_local", issue: { ...CURSOR_KEYCHAIN_HEALTH_ISSUE } };
+    }
+    const matched = ALL_RUNTIMES.filter((r) => AUTH_PATTERNS_BY_RUNTIME[r].some((re) => re.test(output)));
+    if (matched.length === 0)
+        return null;
+    // Anchors are only consulted within the runtimes whose auth prose matched, so a log that
+    // merely mentions another CLI by name cannot steal the attribution.
+    const anchored = matched.filter((r) => RUNTIME_VENDOR_ANCHORS[r].some((re) => re.test(output)));
+    const named = anchored.length === 1
+        ? anchored[0]
+        : recordedRuntime && matched.includes(recordedRuntime)
+            ? recordedRuntime
+            : matched.length === 1
+                ? matched[0]
+                : null;
+    if (named) {
+        return { runtime: named, issue: { code: "runtime_auth", message: REMEDIATION_BY_RUNTIME[named] } };
+    }
+    return { runtime: null, issue: { code: "runtime_auth", message: AMBIGUOUS_AUTH_REMEDIATION } };
+}
+/** `runtimeAuthClassificationForLog` for callers that hold no runtime label at all. */
+export function anyRuntimeAuthIssueFromOutput(output) {
+    return runtimeAuthClassificationForLog(output, null);
+}

package/bundle/shared/dist/runtime-auth-health.test.d.ts

@@ -0,0 +1 @@
+export {};

package/bundle/shared/dist/runtime-auth-health.test.js

@@ -0,0 +1,200 @@
+// packages/shared/src/runtime-auth-health.test.ts
+//
+// NOT-133: these assertions run against verbatim CLI captures (src/fixtures/runtime-auth/),
+// not phrasings a test author guessed at. The bug being regression-tested is exactly the
+// gap that hand-written expectations cannot catch — the old suite asserted "login required"
+// while cursor-agent prints "Authentication required".
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { AMBIGUOUS_AUTH_REMEDIATION, CLAUDE_AUTH_REMEDIATION, CODEX_AUTH_REMEDIATION, CURSOR_AUTH_REMEDIATION, CURSOR_KEYCHAIN_HEALTH_ISSUE, anyRuntimeAuthIssueFromOutput, cursorAuthIssueFromOutput, isCursorKeychainStuckOutput, runtimeAuthClassificationForLog, runtimeAuthIssueFromOutput, } from "./runtime-auth-health.js";
+const FIXTURES = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures/runtime-auth");
+function capture(name) {
+    return fs.readFileSync(path.join(FIXTURES, name), "utf8");
+}
+/**
+ * The NOT-133 stderr, byte for byte. Asserting the capture's own content here means a
+ * fixture silently replaced by a paraphrase fails this test instead of passing quietly.
+ */
+test("the cursor-agent logged-out capture is the string the incident reported", () => {
+    assert.equal(capture("cursor-agent-print-logged-out.txt"), "Error: Authentication required. Please run 'agent login' first, or set CURSOR_API_KEY environment variable.\n");
+});
+test("cursorAuthIssueFromOutput classifies the verbatim cursor-agent logged-out stderr", () => {
+    const issue = cursorAuthIssueFromOutput(capture("cursor-agent-print-logged-out.txt"));
+    assert.equal(issue?.code, "runtime_auth");
+    assert.equal(issue?.message, CURSOR_AUTH_REMEDIATION);
+});
+test("the cursor remediation offers both routes the CLI itself offers", () => {
+    // The old message named only `cursor-agent login` while the CLI offers login *or* an API key.
+    assert.match(CURSOR_AUTH_REMEDIATION, /cursor-agent login/);
+    assert.match(CURSOR_AUTH_REMEDIATION, /agent login/);
+    assert.match(CURSOR_AUTH_REMEDIATION, /CURSOR_API_KEY/);
+});
+test("cursorAuthIssueFromOutput classifies the verbatim `cursor-agent status` logged-out capture", () => {
+    // The admission-gate half: the preflight classifies `status`, not `-p` stderr.
+    const issue = cursorAuthIssueFromOutput(capture("cursor-agent-status-logged-out.txt"));
+    assert.equal(issue?.code, "runtime_auth");
+});
+test("cursorAuthIssueFromOutput classifies a rejected CURSOR_API_KEY", () => {
+    const issue = cursorAuthIssueFromOutput(capture("cursor-agent-print-invalid-api-key.txt"));
+    assert.equal(issue?.code, "runtime_auth");
+});
+test("cursorAuthIssueFromOutput passes a logged-in `cursor-agent status` capture (ANSI included)", () => {
+    assert.equal(cursorAuthIssueFromOutput(capture("cursor-agent-status-logged-in.txt")), null);
+});
+test("codex logged-out captures classify as runtime_auth", () => {
+    for (const name of ["codex-login-status-logged-out.txt", "codex-exec-logged-out.txt"]) {
+        const issue = runtimeAuthIssueFromOutput("codex_local", capture(name));
+        assert.equal(issue?.code, "runtime_auth", `${name} should classify`);
+        assert.equal(issue?.message, CODEX_AUTH_REMEDIATION);
+    }
+});
+test("someone else's 401 is not the runtime's login problem", () => {
+    // A worker shares stderr with everything it spawns, so an unrelated API refusing the
+    // *agent's own* request would otherwise be reported as "run `codex login`". The captured
+    // Codex lines all name the endpoint that refused them; that qualifier is what separates
+    // them from a test suite's 401.
+    const unrelated = "  ✗ POST /v1/things 401 Unauthorized (expected 200)\n" +
+        "1 failing test: Error: request failed with 401 Unauthorized\n";
+    assert.equal(runtimeAuthIssueFromOutput("codex_local", unrelated), null);
+    assert.equal(anyRuntimeAuthIssueFromOutput(unrelated), null);
+    // The real capture is still classified.
+    assert.match(capture("codex-exec-logged-out.txt"), /401 Unauthorized/);
+    assert.equal(runtimeAuthIssueFromOutput("codex_local", capture("codex-exec-logged-out.txt"))?.code, "runtime_auth");
+});
+test("a logged-in `codex login status` capture is not a runtime_auth issue", () => {
+    assert.equal(runtimeAuthIssueFromOutput("codex_local", capture("codex-login-status-logged-in.txt")), null);
+});
+test("claude logged-out captures classify as runtime_auth", () => {
+    for (const name of [
+        "claude-print-logged-out.txt",
+        "claude-print-invalid-api-key.txt",
+        "claude-auth-status-logged-out.txt",
+    ]) {
+        const issue = runtimeAuthIssueFromOutput("claude_code", capture(name));
+        assert.equal(issue?.code, "runtime_auth", `${name} should classify`);
+        assert.equal(issue?.message, CLAUDE_AUTH_REMEDIATION);
+    }
+});
+test("a logged-in `claude auth status` capture is not a runtime_auth issue", () => {
+    assert.equal(runtimeAuthIssueFromOutput("claude_code", capture("claude-auth-status-logged-in.txt")), null);
+});
+test("anyRuntimeAuthIssueFromOutput names the runtime a log came from", () => {
+    const cursor = anyRuntimeAuthIssueFromOutput(capture("cursor-agent-print-logged-out.txt"));
+    assert.equal(cursor?.runtime, "cursor_local");
+    assert.equal(cursor?.issue.message, CURSOR_AUTH_REMEDIATION);
+    const codex = anyRuntimeAuthIssueFromOutput(capture("codex-exec-logged-out.txt"));
+    assert.equal(codex?.runtime, "codex_local");
+    assert.equal(codex?.issue.message, CODEX_AUTH_REMEDIATION);
+    const claude = anyRuntimeAuthIssueFromOutput(capture("claude-print-invalid-api-key.txt"));
+    assert.equal(claude?.runtime, "claude_code");
+    assert.equal(claude?.issue.message, CLAUDE_AUTH_REMEDIATION);
+    assert.equal(anyRuntimeAuthIssueFromOutput(capture("codex-login-status-logged-in.txt")), null);
+});
+test("a Claude log with no recorded runtime is not reported as Cursor", () => {
+    // `Not logged in · Please run /login`. Cursor's pattern list also carries "not logged in",
+    // so trying the runtimes in a fixed order attributed this capture — and Cursor's
+    // remediation — to Cursor. `/login` is Claude's own wording and settles it.
+    const claude = anyRuntimeAuthIssueFromOutput(capture("claude-print-logged-out.txt"));
+    assert.equal(claude?.runtime, "claude_code");
+    assert.equal(claude?.issue.message, CLAUDE_AUTH_REMEDIATION);
+    assert.doesNotMatch(claude.issue.message, /cursor/i);
+});
+test("a Claude `auth status` JSON body with no recorded runtime is attributed to Claude", () => {
+    const claude = anyRuntimeAuthIssueFromOutput(capture("claude-auth-status-logged-out.txt"));
+    assert.equal(claude?.runtime, "claude_code");
+    assert.equal(claude?.issue.message, CLAUDE_AUTH_REMEDIATION);
+});
+test("a Codex exec log with no recorded runtime is attributed to Codex, not Cursor", () => {
+    const codex = anyRuntimeAuthIssueFromOutput(capture("codex-exec-logged-out.txt"));
+    assert.equal(codex?.runtime, "codex_local");
+    assert.doesNotMatch(codex.issue.message, /cursor/i);
+});
+test("a bare `Not logged in` is classified as auth but attributed to no runtime", () => {
+    // cursor-agent status and codex login status print the identical line: the two captures are
+    // byte-for-byte the same, so nothing in the text can name the CLI that wrote it.
+    assert.equal(capture("cursor-agent-status-logged-out.txt"), capture("codex-login-status-logged-out.txt"));
+    for (const name of ["cursor-agent-status-logged-out.txt", "codex-login-status-logged-out.txt"]) {
+        const classified = anyRuntimeAuthIssueFromOutput(capture(name));
+        assert.equal(classified?.issue.code, "runtime_auth", `${name} is still an auth failure`);
+        assert.equal(classified?.runtime, null, `${name} must not be attributed to a runtime`);
+        assert.equal(classified?.issue.message, AMBIGUOUS_AUTH_REMEDIATION);
+        // The generic remediation covers every runtime rather than betting on one.
+        assert.match(classified.issue.message, /cursor-agent login/);
+        assert.match(classified.issue.message, /codex login/);
+        assert.match(classified.issue.message, /claude auth login/);
+    }
+});
+test("a known runtime still gets its own remediation for the shared `Not logged in`", () => {
+    // The ambiguity above only applies when the caller cannot say what ran. The health
+    // preflight always can, and must keep naming the CLI it just probed.
+    const status = capture("cursor-agent-status-logged-out.txt");
+    assert.equal(runtimeAuthIssueFromOutput("cursor_local", status)?.message, CURSOR_AUTH_REMEDIATION);
+    assert.equal(runtimeAuthIssueFromOutput("codex_local", status)?.message, CODEX_AUTH_REMEDIATION);
+});
+test("a log that names its own CLI outranks a conflicting recorded runtime", () => {
+    // The worst outcome of trusting the row: the operator is told to run `cursor-agent login`
+    // because a session row said cursor_local, while the log is Claude's own logged-out line.
+    for (const recorded of ["cursor_local", "codex_local"]) {
+        const claude = runtimeAuthClassificationForLog(capture("claude-print-logged-out.txt"), recorded);
+        assert.equal(claude?.runtime, "claude_code", `recorded ${recorded} must not win`);
+        assert.equal(claude?.issue.message, CLAUDE_AUTH_REMEDIATION);
+        assert.doesNotMatch(claude.issue.message, /cursor|codex/i);
+    }
+    const codex = runtimeAuthClassificationForLog(capture("codex-exec-logged-out.txt"), "claude_code");
+    assert.equal(codex?.runtime, "codex_local");
+    assert.equal(codex?.issue.message, CODEX_AUTH_REMEDIATION);
+    const cursor = runtimeAuthClassificationForLog(capture("cursor-agent-print-logged-out.txt"), "claude_code");
+    assert.equal(cursor?.runtime, "cursor_local");
+    assert.equal(cursor?.issue.message, CURSOR_AUTH_REMEDIATION);
+});
+test("a recorded runtime settles text that names no CLI", () => {
+    // `Not logged in` on its own: no anchor either way, so the caller's label is the best
+    // evidence there is — and beats the generic three-CLI remediation.
+    const shared = capture("codex-login-status-logged-out.txt");
+    assert.equal(runtimeAuthClassificationForLog(shared, "codex_local")?.runtime, "codex_local");
+    assert.equal(runtimeAuthClassificationForLog(shared, "cursor_local")?.runtime, "cursor_local");
+    assert.equal(runtimeAuthClassificationForLog(shared, null)?.runtime, null);
+});
+test("a recorded runtime cannot invent an auth failure that no capture matches", () => {
+    assert.equal(runtimeAuthClassificationForLog(capture("cursor-agent-status-logged-in.txt"), "cursor_local"), null);
+});
+test("a stuck keychain is attributed to Cursor even with no recorded runtime", () => {
+    const classified = anyRuntimeAuthIssueFromOutput(RECONSTRUCTED_KEYCHAIN_STDERR);
+    assert.equal(classified?.runtime, "cursor_local");
+    assert.equal(classified?.issue.code, "cursor_keychain");
+});
+// NOT-114's keychain branch has no capture — the stuck-keychain state cannot be provoked
+// without corrupting the operator's real keychain, so this stays a reconstruction of the
+// reported stderr and is labelled as such rather than filed under fixtures/.
+const RECONSTRUCTED_KEYCHAIN_STDERR = `Cursor couldn't save your login to the macOS keychain (errSecDuplicateItem, security exit code 45).
+The keychain item is stuck. Delete it and sign in again:
+  security delete-generic-password -s cursor-access-token -a cursor-user
+  agent login
+`;
+test("isCursorKeychainStuckOutput detects errSecDuplicateItem", () => {
+    assert.equal(isCursorKeychainStuckOutput(RECONSTRUCTED_KEYCHAIN_STDERR), true);
+});
+test("isCursorKeychainStuckOutput detects security exit code 45", () => {
+    assert.equal(isCursorKeychainStuckOutput("security exit code 45 while saving token"), true);
+});
+test("isCursorKeychainStuckOutput detects keychain item is stuck prose", () => {
+    assert.equal(isCursorKeychainStuckOutput("The keychain item is stuck."), true);
+});
+test("isCursorKeychainStuckOutput ignores healthy status", () => {
+    assert.equal(isCursorKeychainStuckOutput(capture("cursor-agent-status-logged-in.txt")), false);
+    assert.equal(isCursorKeychainStuckOutput(capture("cursor-agent-status-logged-out.txt")), false);
+});
+test("the keychain classification still wins over the plain logged-out one", () => {
+    const issue = cursorAuthIssueFromOutput(RECONSTRUCTED_KEYCHAIN_STDERR);
+    assert.equal(issue?.code, "cursor_keychain");
+    assert.equal(issue?.message, CURSOR_KEYCHAIN_HEALTH_ISSUE.message);
+    assert.match(issue.message, /security delete-generic-password/);
+    assert.match(issue.message, /cursor-access-token/);
+    assert.match(issue.message, /agent login|cursor-agent login/);
+});
+test("cursorAuthIssueFromOutput returns null for clean output", () => {
+    assert.equal(cursorAuthIssueFromOutput("✓ Logged in\n"), null);
+});

package/bundle/shared/dist/runtime-availability.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { Runtime } from "./runtime.js";
+export declare const RuntimeAvailabilityAvailable: z.ZodObject<{
+    available: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    available: true;
+}, {
+    available: true;
+}>;
+export type RuntimeAvailabilityAvailable = z.infer<typeof RuntimeAvailabilityAvailable>;
+export declare const RuntimeAvailabilityCapped: z.ZodObject<{
+    available: z.ZodLiteral<false>;
+    until: z.ZodString;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+    available: false;
+    until: string;
+}, {
+    reason: string;
+    available: false;
+    until: string;
+}>;
+export type RuntimeAvailabilityCapped = z.infer<typeof RuntimeAvailabilityCapped>;
+export declare const RuntimeAvailability: z.ZodDiscriminatedUnion<"available", [z.ZodObject<{
+    available: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    available: true;
+}, {
+    available: true;
+}>, z.ZodObject<{
+    available: z.ZodLiteral<false>;
+    until: z.ZodString;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+    available: false;
+    until: string;
+}, {
+    reason: string;
+    available: false;
+    until: string;
+}>]>;
+export type RuntimeAvailability = z.infer<typeof RuntimeAvailability>;
+export interface RuntimeAvailabilityRecord {
+    runtime: Runtime;
+    unavailableUntil: string;
+    reason: string;
+    evidenceJson: string | null;
+    observedAt: string;
+}

package/bundle/shared/dist/runtime-availability.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export const RuntimeAvailabilityAvailable = z.object({
+    available: z.literal(true),
+});
+export const RuntimeAvailabilityCapped = z.object({
+    available: z.literal(false),
+    until: z.string(),
+    reason: z.string(),
+});
+export const RuntimeAvailability = z.discriminatedUnion("available", [
+    RuntimeAvailabilityAvailable,
+    RuntimeAvailabilityCapped,
+]);

package/bundle/shared/dist/runtime.d.ts

@@ -1,3 +1,3 @@
 import { z } from "zod";
-export declare const Runtime: z.ZodEnum<["claude_code", "cursor_local"]>;
+export declare const Runtime: z.ZodEnum<["claude_code", "cursor_local", "codex_local"]>;
 export type Runtime = z.infer<typeof Runtime>;

package/bundle/shared/dist/runtime.js

@@ -1,2 +1,2 @@
 import { z } from "zod";
-export const Runtime = z.enum(["claude_code", "cursor_local"]);
+export const Runtime = z.enum(["claude_code", "cursor_local", "codex_local"]);

package/bundle/shared/dist/usage-events.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+export declare const UsageEvent: z.ZodObject<{
+    id: z.ZodString;
+    issueId: z.ZodString;
+    workerSessionId: z.ZodString;
+    role: z.ZodEnum<["developer", "reviewer", "legacy"]>;
+    runtime: z.ZodNullable<z.ZodString>;
+    tokensIn: z.ZodNullable<z.ZodNumber>;
+    tokensOut: z.ZodNullable<z.ZodNumber>;
+    costUsd: z.ZodNullable<z.ZodNumber>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    ts: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    issueId: string;
+    role: "developer" | "reviewer" | "legacy";
+    runtime: string | null;
+    workerSessionId: string;
+    ts: string;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    costUsd: number | null;
+    durationMs: number | null;
+}, {
+    id: string;
+    issueId: string;
+    role: "developer" | "reviewer" | "legacy";
+    runtime: string | null;
+    workerSessionId: string;
+    ts: string;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    costUsd: number | null;
+    durationMs: number | null;
+}>;
+export type UsageEvent = z.infer<typeof UsageEvent>;

package/bundle/shared/dist/usage-events.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export const UsageEvent = z.object({
+    id: z.string().uuid(),
+    issueId: z.string().uuid(),
+    workerSessionId: z.string().uuid(),
+    role: z.enum(["developer", "reviewer", "legacy"]),
+    runtime: z.string().nullable(),
+    tokensIn: z.number().int().nullable(),
+    tokensOut: z.number().int().nullable(),
+    costUsd: z.number().nullable(),
+    durationMs: z.number().int().nullable(),
+    ts: z.string(),
+});