agent-dealer 0.2.0 → 1.0.0

package/bundle/server/dist/coordinator/failure-reason.test.js

@@ -0,0 +1,234 @@
+// packages/server/src/coordinator/failure-reason.test.ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRESUMED_DEAD_REASON, classifyRunnerLogFailure, parseErrorJsonReason, presumedDeadReclaimReason, reasonForDirtyWorktree, reasonForSessionCrash, reasonForWorkerFailedEvent, } from "./failure-reason.js";
+const 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
+`;
+/** Verbatim CLI captures — see packages/shared/src/fixtures/runtime-auth/README.md. */
+const CAPTURES = path.join(path.dirname(fileURLToPath(import.meta.url)), "../../../shared/src/fixtures/runtime-auth");
+function capture(name) {
+    return fs.readFileSync(path.join(CAPTURES, name), "utf8");
+}
+function writeLog(body) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-fail-reason-"));
+    const logPath = path.join(dir, "session.ndjson");
+    fs.writeFileSync(logPath, body);
+    return logPath;
+}
+/** The NOT-133 sessions' entire log: a spawn that produced nothing but this stderr trailer. */
+function writeAuthDeathLog() {
+    return writeLog(`\n--- stderr ---\n${capture("cursor-agent-print-logged-out.txt")}`);
+}
+test("classifyRunnerLogFailure maps keychain stderr trailer to auth/keychain reason", () => {
+    const logPath = writeLog(`{"type":"assistant"}\n--- stderr ---\n${KEYCHAIN_STDERR}`);
+    const reason = classifyRunnerLogFailure(logPath);
+    assert.ok(reason);
+    assert.match(reason, /keychain|errSecDuplicateItem/i);
+    assert.match(reason, /auth/i);
+});
+test("keychain classification does not depend on the session's recorded runtime", () => {
+    // worker_sessions.runtime is nullable and can disagree with whatever wrote the log; the
+    // keychain signature could only have come from Cursor either way.
+    const logPath = writeLog(`{"type":"assistant"}\n--- stderr ---\n${KEYCHAIN_STDERR}`);
+    for (const runtime of [undefined, "claude_code", "codex_local", "cursor_local"]) {
+        assert.match(classifyRunnerLogFailure(logPath, runtime), /keychain|errSecDuplicateItem/i);
+    }
+});
+test("classifyRunnerLogFailure maps reconnect exhaustion", () => {
+    const logPath = writeLog("stream error: failed to reconnect after 5 attempts\n");
+    assert.match(classifyRunnerLogFailure(logPath), /reconnect exhausted/i);
+});
+test("reasonForDirtyWorktree prefers keychain classification while preserving dirty-tree note", () => {
+    const logPath = writeLog(`\n--- stderr ---\n${KEYCHAIN_STDERR}`);
+    const reason = reasonForDirtyWorktree(logPath);
+    assert.match(reason, /keychain|errSecDuplicateItem/i);
+    assert.match(reason, /Worktree preserved/i);
+});
+test("NOT-133: a cursor session that died on auth is named, not 'failed or crashed'", () => {
+    const reason = reasonForSessionCrash({
+        timedOut: false,
+        logPath: writeAuthDeathLog(),
+        runtime: "cursor_local",
+    });
+    assert.notEqual(reason, "Developer session failed or crashed.");
+    assert.match(reason, /Cursor auth required mid-run/);
+    // The strip has to carry the remediation, not just the diagnosis.
+    assert.match(reason, /cursor-agent login/);
+    assert.match(reason, /CURSOR_API_KEY/);
+});
+test("NOT-133: the same log classifies without being told which runtime wrote it", () => {
+    // The recovery/detail path only has a log path — it must not fall back to the generic reason.
+    assert.match(classifyRunnerLogFailure(writeAuthDeathLog()), /Cursor auth required mid-run/);
+});
+test("NOT-133: codex and claude auth deaths are named too", () => {
+    const codex = classifyRunnerLogFailure(writeLog(`\n--- stderr ---\n${capture("codex-exec-logged-out.txt")}`), "codex_local");
+    assert.match(codex, /Codex auth required mid-run/);
+    assert.match(codex, /codex login/);
+    const claude = classifyRunnerLogFailure(writeLog(`\n--- stderr ---\n${capture("claude-print-logged-out.txt")}`), "claude_code");
+    assert.match(claude, /Claude Code auth required mid-run/);
+    assert.match(claude, /claude auth login/);
+});
+test("NOT-133: a runtime-less Claude log is named Claude, not Cursor", () => {
+    // worker_sessions.runtime is nullable; "Not logged in · Please run /login" is Claude's, but
+    // Cursor's pattern list carries "not logged in" too, so order-of-trial named Cursor here.
+    const reason = classifyRunnerLogFailure(writeLog(`\n--- stderr ---\n${capture("claude-print-logged-out.txt")}`));
+    assert.match(reason, /Claude Code auth required mid-run/);
+    assert.match(reason, /claude auth login/);
+    assert.doesNotMatch(reason, /cursor/i);
+});
+test("NOT-133: a runtime-less Codex log is named Codex, not Cursor", () => {
+    const reason = classifyRunnerLogFailure(writeLog(`\n--- stderr ---\n${capture("codex-exec-logged-out.txt")}`));
+    assert.match(reason, /Codex auth required mid-run/);
+    assert.match(reason, /codex login/);
+    assert.doesNotMatch(reason, /cursor/i);
+});
+test("NOT-133: a runtime-less log that names no CLI reports auth without guessing one", () => {
+    // `cursor-agent status` and `codex login status` both print exactly "Not logged in".
+    const reason = classifyRunnerLogFailure(writeLog(`\n--- stderr ---\n${capture("codex-login-status-logged-out.txt")}`));
+    assert.match(reason, /Runtime auth required mid-run/);
+    assert.match(reason, /cursor-agent login/);
+    assert.match(reason, /codex login/);
+    assert.match(reason, /claude auth login/);
+    // Still better than the thing NOT-133 was filed about.
+    assert.notEqual(reason, "Developer session failed or crashed.");
+});
+test("NOT-133: a recorded runtime still names that CLI for the shared `Not logged in`", () => {
+    const logPath = writeLog(`\n--- stderr ---\n${capture("codex-login-status-logged-out.txt")}`);
+    assert.match(classifyRunnerLogFailure(logPath, "codex_local"), /Codex auth required mid-run/);
+    assert.match(classifyRunnerLogFailure(logPath, "cursor_local"), /Cursor auth required mid-run/);
+});
+test("NOT-133: a log that names its own CLI outranks a wrong recorded runtime", () => {
+    // worker_sessions.runtime can disagree with what ran (nullable column, older rows, an agent
+    // whose runtime was edited between attempts). Telling the operator `cursor-agent login`
+    // because the row said cursor_local, when Claude printed the failure, is the same class of
+    // wrong answer NOT-133 is about — a confident remediation for the wrong CLI.
+    const claudeLog = writeLog(`\n--- stderr ---\n${capture("claude-print-logged-out.txt")}`);
+    for (const wrong of ["cursor_local", "codex_local"]) {
+        const reason = classifyRunnerLogFailure(claudeLog, wrong);
+        assert.match(reason, /Claude Code auth required mid-run/, `recorded ${wrong} must not win`);
+        assert.match(reason, /claude auth login/);
+        assert.doesNotMatch(reason, /cursor|codex/i);
+    }
+    const codexLog = writeLog(`\n--- stderr ---\n${capture("codex-exec-logged-out.txt")}`);
+    assert.match(classifyRunnerLogFailure(codexLog, "cursor_local"), /Codex auth required mid-run/);
+    const cursorLog = writeAuthDeathLog();
+    assert.match(classifyRunnerLogFailure(cursorLog, "claude_code"), /Cursor auth required mid-run/);
+});
+/**
+ * A worker transcript that *discusses* auth failures — the NOT-133 session itself quotes every
+ * capture in this directory — must not be read as one. Every runner spawns its CLI in a
+ * structured output mode, so transcript prose always arrives inside stream events; only
+ * stderr and terminal error events describe how the session died.
+ */
+const TRANSCRIPT_QUOTING_AUTH_PROSE = [
+    JSON.stringify({
+        type: "assistant",
+        message: {
+            content: [
+                {
+                    type: "text",
+                    text: `The classifier missed the real string. Captures:\n` +
+                        `${capture("cursor-agent-print-logged-out.txt")}` +
+                        `${capture("claude-print-logged-out.txt")}` +
+                        `${capture("codex-exec-logged-out.txt")}` +
+                        `${capture("cursor-agent-print-invalid-api-key.txt")}`,
+                },
+            ],
+        },
+    }),
+    // Codex's native JSONL transcript shape carries the same prose in `item.text`.
+    JSON.stringify({
+        type: "item.completed",
+        item: { type: "agent_message", text: capture("claude-print-invalid-api-key.txt") },
+    }),
+    JSON.stringify({ type: "result", is_error: true, result: "exit 1" }),
+].join("\n");
+test("NOT-133: auth prose inside a non-error transcript event is not an auth failure", () => {
+    const logPath = writeLog(`${TRANSCRIPT_QUOTING_AUTH_PROSE}\n`);
+    for (const runtime of [undefined, "cursor_local", "codex_local", "claude_code"]) {
+        assert.equal(classifyRunnerLogFailure(logPath, runtime), null, `transcript prose must not classify as auth for runtime=${runtime}`);
+    }
+    assert.equal(reasonForSessionCrash({ timedOut: false, logPath, runtime: "cursor_local" }), "Developer session failed or crashed.");
+});
+test("NOT-133: the same prose in a terminal error result IS an auth failure", () => {
+    // The narrowed haystack must not lose the signal: a CLI that reports its auth failure as
+    // the session's error result, rather than on stderr, still has to be classified.
+    const logPath = writeLog(`${JSON.stringify({ type: "assistant", message: { content: [{ type: "text", text: "starting" }] } })}\n` +
+        `${JSON.stringify({
+            type: "result",
+            is_error: true,
+            result: capture("cursor-agent-print-logged-out.txt"),
+        })}\n`);
+    assert.match(classifyRunnerLogFailure(logPath), /Cursor auth required mid-run/);
+    assert.match(classifyRunnerLogFailure(logPath, "cursor_local"), /CURSOR_API_KEY/);
+});
+test("NOT-133: a Codex turn.failed error message is classified", () => {
+    const logPath = writeLog(`${JSON.stringify({ type: "thread.started", thread_id: "t1" })}\n` +
+        `${JSON.stringify({
+            type: "turn.failed",
+            error: { message: capture("codex-exec-logged-out.txt") },
+        })}\n`);
+    assert.match(classifyRunnerLogFailure(logPath, "codex_local"), /Codex auth required mid-run/);
+});
+test("NOT-133: an error event carries its message whether nested or flat", () => {
+    // `error` arrives as a bare string in some events and `{ message }` in others; reading
+    // only one shape silently loses the failure and falls back to "failed or crashed".
+    for (const error of [
+        capture("cursor-agent-print-logged-out.txt"),
+        { message: capture("cursor-agent-print-logged-out.txt") },
+    ]) {
+        const logPath = writeLog(`${JSON.stringify({ type: "error", error })}\n`);
+        assert.match(classifyRunnerLogFailure(logPath), /Cursor auth required mid-run/);
+    }
+});
+test("NOT-133: a timestamped plain-text CLI line is still classified", () => {
+    // Not every CLI diagnostic is a JSON event; a bracketed prefix must not make one look
+    // like a transcript line and get skipped.
+    const logPath = writeLog(`[2026-09-16T05:05:53Z] ${capture("cursor-agent-print-logged-out.txt")}`);
+    assert.match(classifyRunnerLogFailure(logPath), /Cursor auth required mid-run/);
+});
+test("NOT-133: a worker.failed event for an auth death carries the auth reason", () => {
+    const reason = reasonForWorkerFailedEvent({
+        outcome: { kind: "session_failed" },
+        routeReason: "Developer session failed or crashed.",
+        logPath: writeAuthDeathLog(),
+        runtime: "cursor_local",
+    });
+    assert.match(reason, /Cursor auth required mid-run/);
+});
+test("reasonForSessionCrash falls back when log is clean", () => {
+    assert.equal(reasonForSessionCrash({ timedOut: false, logPath: writeLog('{"type":"result"}\n') }), "Developer session failed or crashed.");
+});
+test("parseErrorJsonReason reads recovery presumed-dead shape", () => {
+    assert.equal(parseErrorJsonReason(JSON.stringify({ reason: PRESUMED_DEAD_REASON })), PRESUMED_DEAD_REASON);
+});
+test("presumedDeadReclaimReason names the role that is actually being re-run (NOT-129)", () => {
+    // A reviewer item has no branch of its own to publish, so republish is always null for it —
+    // the message must not claim the developer is being re-run, nor mention a branch.
+    const reviewer = presumedDeadReclaimReason("reviewer", null);
+    assert.match(reviewer, /presumed dead/);
+    assert.match(reviewer, /re-running the reviewer/);
+    assert.doesNotMatch(reviewer, /branch|developer/);
+    assert.match(presumedDeadReclaimReason("developer", null), /nothing on the branch to publish, re-running the developer/);
+    assert.match(presumedDeadReclaimReason("developer", { branch: "issue-1", commits: 2, alreadyPushed: false }), /republishing 2 unpushed commits on issue-1/);
+    assert.match(presumedDeadReclaimReason("developer", { branch: "issue-1", commits: 1, alreadyPushed: true }), /issue-1 is already on origin, re-verifying the PR/);
+});
+test("reasonForWorkerFailedEvent prefers explicit outcome.reason", () => {
+    assert.equal(reasonForWorkerFailedEvent({
+        outcome: { kind: "dirty_worktree", reason: "Cursor macOS keychain/auth died mid-run." },
+        routeReason: "generic dirty",
+    }), "Cursor macOS keychain/auth died mid-run.");
+});
+test("reasonForWorkerFailedEvent uses session errorJson for presumed dead", () => {
+    assert.equal(reasonForWorkerFailedEvent({
+        outcome: { kind: "session_failed" },
+        sessionErrorJson: JSON.stringify({ reason: PRESUMED_DEAD_REASON }),
+    }), PRESUMED_DEAD_REASON);
+});

package/bundle/server/dist/coordinator/guidance.js

@@ -0,0 +1,33 @@
+// packages/server/src/coordinator/guidance.ts
+//
+// NOT-64 "guidance semantics": a one-shot developer/reviewer CLI process never inherits a
+// running session (see design doc "Guidance semantics" — every round is a fresh process
+// with a fresh worktree, and resuming a session across a possibly multi-day human-review
+// gap is not a contract these worktree/CLI lifecycles support). So "guidance applies to
+// the next worker" just means: which guidance.added text hasn't been shown to any prompt
+// yet. That's everything added after the issue's previous worker session's own snapshot
+// moment, up through THIS session's own snapshot moment.
+//
+// The upper bound matters: worker-loop.ts marks a session "running" (startSession) and
+// records its `worker.started` event *before* the effect handler's worktree setup and
+// deck bind — both of which take real wall-clock time before this function is actually
+// called to build the prompt. Guidance posted during that setup window arrives after the
+// session is already dispatched and (per the UI contract) must be deferred to the *next*
+// worker, not swept into this one just because the query ran a few seconds late.
+//
+// The window is anchored to each session's `worker.started` event via a rowid cursor, not
+// a `created_at`/`started_at` timestamp: timestamps only have millisecond precision and a
+// guidance event landing in the same millisecond as the cutoff is a real, reproduced
+// collision (review round 2) that a `ts <=` comparison gets wrong either way it's drawn.
+// `workflow_events.rowid` is a strictly monotonic insertion-order integer, so it can never
+// collide regardless of how close two events land in wall-clock time.
+import { listWorkerSessionsForIssue } from "../repository/worker-sessions.js";
+import { listGuidanceMarkdownForIssue, workerStartedEventCursor } from "../repository/workflow-events.js";
+export function guidanceForNextSession(issueId, currentSessionId) {
+    const sessions = listWorkerSessionsForIssue(issueId);
+    const idx = sessions.findIndex((s) => s.id === currentSessionId);
+    const previous = idx > 0 ? sessions[idx - 1] : null;
+    const sinceCursor = previous ? workerStartedEventCursor(previous.id) : null;
+    const untilCursor = workerStartedEventCursor(currentSessionId);
+    return listGuidanceMarkdownForIssue(issueId, sinceCursor, untilCursor);
+}

package/bundle/server/dist/coordinator/guidance.test.js

@@ -0,0 +1,110 @@
+// packages/server/src/coordinator/guidance.test.ts
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-guidance-"));
+const { migrate } = await import("../db/index.js");
+const { BUILTIN_AGENT_CLAUDE_ID, BUILTIN_AGENT_CURSOR_ID } = await import("@agent-dealer/shared");
+const { createIssue } = await import("../repository/issues.js");
+const { createWorkerSession, startSession } = await import("../repository/worker-sessions.js");
+const { appendWorkflowEvent } = await import("../repository/workflow-events.js");
+const { guidanceForNextSession } = await import("./guidance.js");
+before(() => {
+    migrate();
+});
+function seedIssue() {
+    return createIssue({
+        title: "Guidance host issue",
+        repo: "acme/app",
+        developerAgentId: BUILTIN_AGENT_CLAUDE_ID,
+        reviewerAgentId: BUILTIN_AGENT_CURSOR_ID,
+        baseBranch: "main",
+        maxReviewRounds: 3,
+        maxInfraAttempts: 3,
+        source: "manual"
+    }).id;
+}
+/** Mirrors worker-loop.ts's real transaction: create → startSession → the `worker.started`
+ * event, all before the effect handler (and this module) ever runs — so every session a
+ * test creates has the same rowid-cursor anchor `guidanceForNextSession` relies on. */
+function addSession(issueId, role, round) {
+    const session = createWorkerSession({ issueId, role, round, agentId: BUILTIN_AGENT_CLAUDE_ID, runtime: "claude_code" });
+    startSession(session.id);
+    appendWorkflowEvent({ issueId, workerSessionId: session.id, type: "worker.started", actorType: "system", stage: "developing", round });
+    return session;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+test("first session picks up all guidance added before it, since there is no prior session", async () => {
+    const issueId = seedIssue();
+    appendWorkflowEvent({ issueId, type: "guidance.added", actorType: "human", stage: "ready", payload: { markdown: "Pre-start note" } });
+    await sleep(5);
+    const round1Dev = addSession(issueId, "developer", 1);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Dev.id), ["Pre-start note"]);
+});
+test("a later round only sees guidance added since the immediately preceding session", async () => {
+    // Each guidanceForNextSession call happens at the point it actually would in production
+    // — right before that session's own prompt is built, before any *later* guidance exists
+    // — not retroactively after the whole issue history has played out.
+    const issueId = seedIssue();
+    const round1Dev = addSession(issueId, "developer", 1);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Dev.id), []);
+    await sleep(5);
+    appendWorkflowEvent({ issueId, type: "guidance.added", actorType: "human", stage: "developing", payload: { markdown: "During round 1" } });
+    await sleep(5);
+    const round1Reviewer = addSession(issueId, "reviewer", 1);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Reviewer.id), ["During round 1"]);
+    await sleep(5);
+    appendWorkflowEvent({ issueId, type: "guidance.added", actorType: "human", stage: "reviewing", payload: { markdown: "During review" } });
+    await sleep(5);
+    const round2Dev = addSession(issueId, "developer", 2);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round2Dev.id), ["During review"]);
+});
+test("guidance added while a session is running is deferred to the next session, not lost", async () => {
+    const issueId = seedIssue();
+    const round1Dev = addSession(issueId, "developer", 1);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Dev.id), []);
+    await sleep(5);
+    // Simulates guidance posted mid-session — it must not appear for round1Dev (already
+    // spawned) and must appear for whatever session is enqueued next.
+    appendWorkflowEvent({ issueId, type: "guidance.added", actorType: "human", stage: "developing", payload: { markdown: "Mid-session note" } });
+    await sleep(5);
+    const round1Reviewer = addSession(issueId, "reviewer", 1);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Reviewer.id), ["Mid-session note"]);
+});
+// PR #11 review round 1: worker-loop.ts marks a session "running" (startSession) BEFORE
+// its worktree setup and deck bind, both of which take real wall-clock time before
+// guidanceForNextSession is actually called to build the prompt. Guidance posted in that
+// gap must still be deferred to the *next* session, not swept into this one just because
+// the call happened a few seconds late.
+test("guidance posted after the session starts running (but before its prompt is actually built) is deferred to the next session", async () => {
+    const issueId = seedIssue();
+    const round1Dev = addSession(issueId, "developer", 1); // create + startSession + worker.started, atomically
+    // Simulates guidance posted during worktree setup / deck bind, i.e. after the session
+    // already started but before this function is actually invoked for it.
+    appendWorkflowEvent({ issueId, type: "guidance.added", actorType: "human", stage: "developing", payload: { markdown: "Posted during worktree setup" } });
+    // Called "late", as if setup took a few seconds — must not see guidance posted after
+    // this session's own worker.started event.
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Dev.id), []);
+    const round1Reviewer = addSession(issueId, "reviewer", 1);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Reviewer.id), ["Posted during worktree setup"]);
+});
+// PR #11 review round 2: `ts` only has millisecond precision, so a `ts <=` boundary can
+// wrongly include (or a `ts <` boundary wrongly exclude) a guidance event that lands in
+// the exact same millisecond as the session's own snapshot event. No sleeps here at all —
+// everything happens back-to-back so it's likely to collide on `ts` — proving the rowid
+// cursor is what actually decides the boundary, not wall-clock time.
+test("a millisecond-colliding guidance event is still correctly bucketed by insertion order, not timestamp", () => {
+    const issueId = seedIssue();
+    const round1Dev = addSession(issueId, "developer", 1);
+    appendWorkflowEvent({ issueId, type: "guidance.added", actorType: "human", stage: "developing", payload: { markdown: "Right after round1Dev started" } });
+    const round1Reviewer = addSession(issueId, "reviewer", 1);
+    appendWorkflowEvent({ issueId, type: "guidance.added", actorType: "human", stage: "reviewing", payload: { markdown: "Right after round1Reviewer started" } });
+    const round2Dev = addSession(issueId, "developer", 2);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Dev.id), []);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round1Reviewer.id), ["Right after round1Dev started"]);
+    assert.deepStrictEqual(guidanceForNextSession(issueId, round2Dev.id), ["Right after round1Reviewer started"]);
+});

package/bundle/server/dist/coordinator/human-resolution.js

@@ -0,0 +1,88 @@
+/**
+ * The only choices resolveHumanActionOutcome accepts per action type — the stored "response
+ * options." `reflection_interaction_required` and `outbound_delivery_interaction_required`
+ * are listed here only so this map stays total over `HumanActionType`; neither is ever
+ * routed through `resolveHumanActionOutcome` (NOT-94's reflect-trigger.ts and NOT-95's
+ * `resolveOutboundDeliveryAction` resolve them directly — the former runs after the issue is
+ * already `done`, the latter is Run-scoped with no issue/workflow at all; both must never
+ * reopen an issue or enqueue developer/reviewer work).
+ */
+const VALID_CHOICES = {
+    final_review: ["complete", "repair", "close"],
+    attempts_exhausted: ["retry", "close"],
+    policy_escalation: ["resume", "close"],
+    product_scope_decision: ["resume"],
+    deck_interaction_required: ["resume", "close"],
+    reflection_interaction_required: ["retry", "dismiss"],
+    outbound_delivery_interaction_required: ["retry_send", "reject"],
+};
+/**
+ * Validates a raw (actionType, choice) pair against that action type's allowed response
+ * options before it's ever treated as a typed HumanResolution. Returns null for anything
+ * not in the allowed set — callers must reject the request rather than guess at intent.
+ *
+ * `reflection_interaction_required` is deliberately rejected here even though
+ * `VALID_CHOICES` lists it (PR #21 review): it has no corresponding `HumanResolution`
+ * variant, so casting it through would be a type lie, and its only legal resolver is
+ * `resolveReflectionInteractionAction` (reflect-trigger.ts), never `resolveHumanActionOutcome`.
+ * `outbound_delivery_interaction_required` is rejected for the same reason (NOT-95): it is
+ * Run-scoped, has no Issue/workflow_instance to advance, and its only legal resolver is
+ * `resolveOutboundDeliveryAction` (queue/approve-deliver.ts).
+ */
+export function parseHumanResolution(actionType, choice) {
+    if (actionType === "reflection_interaction_required" || actionType === "outbound_delivery_interaction_required") {
+        return null;
+    }
+    if (!(actionType in VALID_CHOICES))
+        return null;
+    if (!VALID_CHOICES[actionType].includes(choice))
+        return null;
+    return { actionType, choice };
+}
+/**
+ * Implements PRD §6.3's human pass-the-ball outcomes: continue, repair, complete, or close.
+ * v1 (open decision #2 in the spec) treats every "resume/retry/repair" choice as starting
+ * another round rather than distinguishing a true resume from a fresh repair round.
+ *
+ * Every branch is explicit — an unrecognized choice throws rather than silently falling
+ * through to "close" (the previous shape's `? X : close` ternaries meant any typo or bad
+ * input silently closed the issue). Callers should validate with parseHumanResolution
+ * first, making these throws unreachable in practice; they exist as defense in depth.
+ */
+export function resolveHumanActionOutcome(resolution) {
+    switch (resolution.actionType) {
+        case "final_review":
+            if (resolution.choice === "complete")
+                return { issueStatus: "done", workflowOutcome: "done", triggerReflect: true };
+            if (resolution.choice === "repair")
+                return { issueStatus: "repairing", startNewRound: true, roundKind: "review" };
+            if (resolution.choice === "close")
+                return { issueStatus: "closed", workflowOutcome: "closed" };
+            throw new Error(`Unrecognized final_review choice: ${resolution.choice}`);
+        case "attempts_exhausted":
+            // A "retry" must grant one more round, not just re-spend the exhausted one —
+            // otherwise the very next changes_requested re-creates attempts_exhausted immediately.
+            if (resolution.choice === "retry")
+                return { issueStatus: "repairing", startNewRound: true, roundKind: "review_grant" };
+            if (resolution.choice === "close")
+                return { issueStatus: "closed", workflowOutcome: "closed" };
+            throw new Error(`Unrecognized attempts_exhausted choice: ${resolution.choice}`);
+        case "policy_escalation":
+            // An infra escalation resuming is not a review-round spend — reset the infra budget instead.
+            if (resolution.choice === "resume")
+                return { issueStatus: "developing", startNewRound: true, roundKind: "infra" };
+            if (resolution.choice === "close")
+                return { issueStatus: "closed", workflowOutcome: "closed" };
+            throw new Error(`Unrecognized policy_escalation choice: ${resolution.choice}`);
+        case "product_scope_decision":
+            return { issueStatus: "developing", startNewRound: true, roundKind: "none" };
+        case "deck_interaction_required":
+            // Same semantics as policy_escalation:resume — an authority/control-plane hiccup is
+            // not a review-round spend; a fresh attempt mints its own new authority when it runs.
+            if (resolution.choice === "resume")
+                return { issueStatus: "developing", startNewRound: true, roundKind: "infra" };
+            if (resolution.choice === "close")
+                return { issueStatus: "closed", workflowOutcome: "closed" };
+            throw new Error(`Unrecognized deck_interaction_required choice: ${resolution.choice}`);
+    }
+}

package/bundle/server/dist/coordinator/human-resolution.test.js

@@ -0,0 +1,72 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveHumanActionOutcome, parseHumanResolution } from "./human-resolution.js";
+// Reviewer finding #8: an unrecognized choice must be rejected, not silently treated as "close".
+test("parseHumanResolution rejects a choice not in that action type's allowed set", () => {
+    assert.equal(parseHumanResolution("final_review", "bogus"), null);
+    assert.equal(parseHumanResolution("attempts_exhausted", "complete"), null); // valid for final_review, not this type
+});
+test("parseHumanResolution rejects an unknown action type", () => {
+    assert.equal(parseHumanResolution("not_a_real_action_type", "complete"), null);
+});
+test("parseHumanResolution accepts a valid (actionType, choice) pair", () => {
+    assert.deepStrictEqual(parseHumanResolution("final_review", "repair"), { actionType: "final_review", choice: "repair" });
+});
+// PR #21 review finding #3: reflection_interaction_required has no HumanResolution variant
+// — it must never parse successfully here even though VALID_CHOICES lists its choices (kept
+// there only so that Record<HumanActionType, ...> stays total). Its only legal resolver is
+// resolveReflectionInteractionAction (reflect-trigger.ts).
+test("parseHumanResolution rejects reflection_interaction_required even though VALID_CHOICES lists its choices", () => {
+    assert.equal(parseHumanResolution("reflection_interaction_required", "retry"), null);
+    assert.equal(parseHumanResolution("reflection_interaction_required", "dismiss"), null);
+});
+test("resolveHumanActionOutcome throws rather than silently closing on an invalid choice reaching it directly", () => {
+    assert.throws(() => resolveHumanActionOutcome({ actionType: "final_review", choice: "bogus" }), /Unrecognized final_review choice/);
+});
+test("final_review complete marks the issue done and triggers reflect", () => {
+    const result = resolveHumanActionOutcome({ actionType: "final_review", choice: "complete" });
+    assert.equal(result.issueStatus, "done");
+    assert.equal(result.workflowOutcome, "done");
+    assert.equal(result.triggerReflect, true);
+});
+test("final_review repair sends the issue back for another round without reflect", () => {
+    const result = resolveHumanActionOutcome({ actionType: "final_review", choice: "repair" });
+    assert.equal(result.issueStatus, "repairing");
+    assert.equal(result.startNewRound, true);
+    assert.equal(result.triggerReflect, undefined);
+});
+test("final_review close closes the workflow without accepting the work", () => {
+    const result = resolveHumanActionOutcome({ actionType: "final_review", choice: "close" });
+    assert.equal(result.issueStatus, "closed");
+    assert.equal(result.workflowOutcome, "closed");
+    assert.equal(result.triggerReflect, undefined);
+});
+test("attempts_exhausted retry starts a new round (v1: equivalent to another repair round)", () => {
+    const result = resolveHumanActionOutcome({ actionType: "attempts_exhausted", choice: "retry" });
+    assert.equal(result.issueStatus, "repairing");
+    assert.equal(result.startNewRound, true);
+});
+test("attempts_exhausted close ends the issue", () => {
+    const result = resolveHumanActionOutcome({ actionType: "attempts_exhausted", choice: "close" });
+    assert.equal(result.issueStatus, "closed");
+});
+test("policy_escalation resume continues development", () => {
+    const result = resolveHumanActionOutcome({ actionType: "policy_escalation", choice: "resume" });
+    assert.equal(result.issueStatus, "developing");
+    assert.equal(result.startNewRound, true);
+});
+test("product_scope_decision resume continues development from the pre-start gate", () => {
+    const result = resolveHumanActionOutcome({ actionType: "product_scope_decision", choice: "resume" });
+    assert.equal(result.issueStatus, "developing");
+});
+test("deck_interaction_required resume starts a fresh infra round, not a review-round spend", () => {
+    const result = resolveHumanActionOutcome({ actionType: "deck_interaction_required", choice: "resume" });
+    assert.equal(result.issueStatus, "developing");
+    assert.equal(result.startNewRound, true);
+    assert.equal(result.roundKind, "infra");
+});
+test("deck_interaction_required close ends the issue", () => {
+    const result = resolveHumanActionOutcome({ actionType: "deck_interaction_required", choice: "close" });
+    assert.equal(result.issueStatus, "closed");
+    assert.equal(result.workflowOutcome, "closed");
+});

package/bundle/server/dist/coordinator/intent-forecast.js

@@ -0,0 +1,13 @@
+const FORECASTS = {
+    ready: () => ({ now: "Ready to start", next: "Start the developer round" }),
+    developing: (i) => ({ now: `Developer implementing round ${i.currentRound}`, next: "Verify the handoff once the session completes" }),
+    reviewing: (i) => ({ now: `Reviewer evaluating round ${i.currentRound}`, next: "Route the reviewer's verdict" }),
+    repairing: (i) => ({ now: `Developer repairing round ${i.currentRound}`, next: "Verify the handoff once the session completes" }),
+    final_review: () => ({ now: "Awaiting final human review", next: "Human resolves: complete, repair, or close" }),
+    needs_human: () => ({ now: "Waiting on a human action", next: "Resolve the open action to resume" }),
+    done: () => ({ now: "Done", next: "" }),
+    closed: () => ({ now: "Closed", next: "" }),
+};
+export function computeIntentForecast(issue) {
+    return FORECASTS[issue.status](issue);
+}

package/bundle/server/dist/coordinator/intent-forecast.test.js

@@ -0,0 +1,34 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { computeIntentForecast } from "./intent-forecast.js";
+const BASE = {
+    id: "i1", source: "manual", externalId: null, externalLabel: null, externalUrl: null,
+    title: "T", description: null, acceptanceCriteria: null, repo: "/r", baseBranch: "main",
+    status: "ready", currentOwner: "system", currentIntent: null,
+    developerAgentId: null, reviewerAgentId: null, maxReviewRounds: 3, currentRound: 1,
+    branch: null, baseSha: null, headSha: null, prNumber: null, prUrl: null,
+    createdAt: "2026-01-01T00:00:00Z", updatedAt: "2026-01-01T00:00:00Z",
+};
+test("ready issue forecasts starting the developer round", () => {
+    const forecast = computeIntentForecast(BASE);
+    assert.match(forecast.now, /Ready/i);
+    assert.match(forecast.next, /developer/i);
+});
+test("developing issue forecasts handoff verification", () => {
+    const forecast = computeIntentForecast({ ...BASE, status: "developing", currentOwner: "developer" });
+    assert.match(forecast.now, /Developer/i);
+    assert.match(forecast.next, /verify|handoff|pr/i);
+});
+test("reviewing issue mentions the round number", () => {
+    const forecast = computeIntentForecast({ ...BASE, status: "reviewing", currentOwner: "reviewer", currentRound: 2 });
+    assert.match(forecast.now, /Reviewer/i);
+    assert.ok(forecast.now.includes("2") || forecast.next.includes("2"));
+});
+test("needs_human issue forecasts waiting on a decision", () => {
+    const forecast = computeIntentForecast({ ...BASE, status: "needs_human", currentOwner: "human" });
+    assert.match(forecast.now, /human|action/i);
+});
+test("done issue has no next step", () => {
+    const forecast = computeIntentForecast({ ...BASE, status: "done" });
+    assert.equal(forecast.next, "");
+});