agent-dealer 1.2.7 → 1.2.9

package/bundle/server/dist/coordinator/reflect-trigger.test.js

@@ -1,31 +1,30 @@
 // packages/server/src/coordinator/reflect-trigger.test.ts
 //
-// NOT-64: triggerIssueReflect is the lightweight (no agent-spawn) reflect fired on
-// final_review:complete. Network calls to Agent Deck are faked via the injectable
-// `deps` seam.
-//
-// NOT-106: Deck calls go through launch-fixed deck headers via `deps.callTool`
-// (adapters/reflect-authority.ts) — no mint.
+// NOT-305: triggerIssueReflect records completion evidence — actual-use receipts for
+// every terminal worker session plus one idempotent `signal_only` Deck report per
+// failure/correction trigger. It never proposes a playbook patch (`kind: update`) and
+// never appends generic `Notes` items.
 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";
+import { DECK_CORRELATION_TOOL, validateSignalOnlyArgs } from "./playbook-feedback.js";
 process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-reflect-"));
-const { migrate, getDb } = await import("../db/index.js");
+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 { createAgent } = await import("../repository/agents.js");
-const { createWorkerSession } = await import("../repository/worker-sessions.js");
+const { createWorkerSession, completeSession } = await import("../repository/worker-sessions.js");
 const { buildProfileSnapshot, serializeProfileSnapshot } = await import("./profile-snapshot.js");
-const { appendWorkflowEvent } = await import("../repository/workflow-events.js");
-const { createIssueArtifact } = await import("../repository/artifacts.js");
+const { createHumanAction, resolveHumanAction } = await import("../repository/human-actions.js");
 const { listArtifactsForIssue, listArtifactsForIssueByKind } = await import("../repository/artifacts-for-issue.js");
-const { listHumanActionsForIssue, createHumanAction } = await import("../repository/human-actions.js");
+const { listHumanActionsForIssue } = await import("../repository/human-actions.js");
 const { triggerIssueReflect, resolveReflectionInteractionAction } = await import("./reflect-trigger.js");
 before(() => {
     migrate();
 });
+const DECK = "11111111-1111-4111-a111-111111111111";
 function seedIssue(developerAgentId) {
     return createIssue({
         title: "Reflect issue",
@@ -38,14 +37,11 @@ function seedIssue(developerAgentId) {
         source: "manual",
     });
 }
-function seedFinalDeveloperSession(issueId, agent, overrides) {
-    if (overrides.playbookIds !== undefined) {
-        getDb()
-            .prepare("UPDATE agents SET playbook_ids_json = ? WHERE id = ?")
-            .run(JSON.stringify(overrides.playbookIds), agent.id);
-    }
-    const snapshot = { ...buildProfileSnapshot(agent, "developer"), deckId: overrides.deckId };
-    return createWorkerSession({
+/** Terminal developer session on a NOT-149 profile: snapshot names the deck, no playbook IDs anywhere. */
+function seedTerminalDeveloperSession(issueId, agent) {
+    assert.equal(agent.playbookIdsJson, null);
+    const snapshot = { ...buildProfileSnapshot(agent, "developer"), deckId: DECK };
+    const session = createWorkerSession({
         issueId,
         role: "developer",
         round: 1,
@@ -53,185 +49,125 @@ function seedFinalDeveloperSession(issueId, agent, overrides) {
         runtime: agent.runtime,
         profileSnapshotJson: serializeProfileSnapshot(snapshot),
     });
+    completeSession(session.id, { status: "done" });
+    return session;
 }
-async function waitFor(predicate, timeoutMs = 2000, intervalMs = 5) {
-    const start = Date.now();
-    while (!predicate()) {
-        if (Date.now() - start > timeoutMs)
-            throw new Error("waitFor: timed out waiting for predicate");
-        await new Promise((r) => setTimeout(r, intervalMs));
-    }
-}
-/** Default deps: healthy deck, get_playbook/propose_playbook_patch both succeed. */
-function makeDeps(overrides) {
-    return {
+/** Default deps: healthy deck, correlation succeeds, signal_only succeeds. */
+function makeDeps(overrides = {}) {
+    const calls = [];
+    const deps = {
         checkHealth: overrides.checkHealth ?? (async () => true),
         callTool: (async (opts) => {
-            if (opts.toolName === "get_playbook") {
-                const playbookId = opts.arguments.playbook_id;
-                return overrides.getPlaybook
-                    ? overrides.getPlaybook(playbookId)
-                    : { ok: true, data: { id: playbookId, title: `Playbook ${playbookId}`, body: "" } };
+            calls.push({ toolName: opts.toolName, args: opts.arguments });
+            if (opts.toolName === DECK_CORRELATION_TOOL) {
+                return { ok: true, data: overrides.correlationData ?? { fetches: overrides.fetches ?? [] } };
             }
             if (opts.toolName === "propose_playbook_patch") {
-                const playbookId = opts.arguments.playbook_id;
-                const rationale = opts.arguments.rationale;
-                return overrides.proposePatch
-                    ? overrides.proposePatch(playbookId, rationale)
-                    : { ok: true, data: { id: `patch-${playbookId}`, playbookId } };
+                if (opts.arguments.kind !== "signal_only") {
+                    throw new Error(`issue-centric reflection must only send signal_only, got ${opts.arguments.kind}`);
+                }
+                const schemaError = validateSignalOnlyArgs(opts.arguments);
+                if (schemaError) {
+                    throw new Error(`signal payload violates Deck schema: ${schemaError}`);
+                }
+                return overrides.propose
+                    ? overrides.propose(opts.arguments)
+                    : { ok: true, data: { id: `sig-${calls.length}` } };
             }
             throw new Error(`unexpected tool call: ${opts.toolName}`);
         }),
     };
+    return { deps, calls };
+}
+function sentSignals(issueId) {
+    return listArtifactsForIssueByKind(issueId, "deck_feedback_signal")
+        .map((a) => JSON.parse(a.contentJson))
+        .filter((s) => s.status === "sent");
+}
+async function waitFor(predicate, timeoutMs = 2000, intervalMs = 5) {
+    const start = Date.now();
+    while (!predicate()) {
+        if (Date.now() - start > timeoutMs)
+            throw new Error("waitFor: timed out waiting for predicate");
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
 }
-test("skips when the developer profile has no deck configured and no session snapshot exists", async () => {
+test("skips when the issue has no terminal sessions and no failure triggers", async () => {
     const issue = seedIssue(BUILTIN_AGENT_CLAUDE_ID);
-    const result = await triggerIssueReflect(issue.id);
+    const { deps, calls } = makeDeps();
+    const result = await triggerIssueReflect(issue.id, deps);
     assert.equal(result, "skipped");
+    assert.deepStrictEqual(calls, []);
 });
-test("uses the frozen session snapshot's deck/playbooks, not the live (possibly edited) agent profile", async () => {
-    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: "22222222-2222-4222-a222-222222222222" });
+test("a clean completed run records the actual-use receipt and sends no signal", async () => {
+    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: DECK });
     const issue = seedIssue(dev.id);
-    seedFinalDeveloperSession(issue.id, dev, {
-        deckId: "11111111-1111-4111-a111-111111111111",
-        playbookIds: ["pb-1", "pb-2"],
-    });
-    const calledDeckIds = [];
-    const proposed = [];
-    const deps = makeDeps({
-        proposePatch: (playbookId) => {
-            proposed.push(playbookId);
-            return { ok: true, data: { id: `patch-${playbookId}`, playbookId } };
-        },
-    });
-    const wrapped = {
-        ...deps,
-        callTool: (async (opts) => {
-            calledDeckIds.push(opts.deckId);
-            return deps.callTool(opts);
-        }),
-    };
-    const result = await triggerIssueReflect(issue.id, wrapped);
-    assert.equal(result, "triggered");
-    assert.ok(calledDeckIds.every((id) => id === "11111111-1111-4111-a111-111111111111"));
-    assert.deepStrictEqual(proposed.sort(), ["pb-1", "pb-2"]);
-});
-test("falls back to the live agent profile when the developer session has no frozen snapshot (legacy row)", async () => {
-    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: "33333333-3333-4333-a333-333333333333" });
-    getDb()
-        .prepare("UPDATE agents SET playbook_ids_json = ? WHERE id = ?")
-        .run(JSON.stringify(["pb-live"]), dev.id);
-    const issue = seedIssue(dev.id);
-    createWorkerSession({ issueId: issue.id, role: "developer", round: 1, agentId: dev.id, runtime: "claude_code" });
-    const proposed = [];
-    const deps = makeDeps({
-        proposePatch: (playbookId) => {
-            proposed.push(playbookId);
-            return { ok: true, data: { id: "patch", playbookId } };
-        },
-    });
+    const session = seedTerminalDeveloperSession(issue.id, dev);
+    const { deps, calls } = makeDeps({ fetches: [{ playbook_id: "pb-1" }, { playbook_id: "pb-2" }] });
     const result = await triggerIssueReflect(issue.id, deps);
     assert.equal(result, "triggered");
-    assert.deepStrictEqual(proposed, ["pb-live"]);
+    const receipts = listArtifactsForIssueByKind(issue.id, "playbook_use_receipt").map((a) => JSON.parse(a.contentJson));
+    assert.equal(receipts.length, 1);
+    assert.deepStrictEqual(receipts[0].playbookIds, ["pb-1", "pb-2"]);
+    assert.equal(receipts[0].workerSessionId, session.id);
+    assert.deepStrictEqual(calls.filter((c) => c.toolName === "propose_playbook_patch"), []);
+    assert.deepStrictEqual(listArtifactsForIssueByKind(issue.id, "deck_feedback_signal"), []);
+    assert.deepStrictEqual(sentSignals(issue.id), []);
 });
-test("the legacy-row fallback also honors a profile with only the singular legacy playbookId", async () => {
-    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: "44444444-4444-4444-a444-444444444444" });
-    getDb().prepare("UPDATE agents SET playbook_id = ? WHERE id = ?").run("pb-legacy", dev.id);
+test("a human correction produces one signal_only report; a restart sends nothing more", async () => {
+    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: DECK });
     const issue = seedIssue(dev.id);
-    createWorkerSession({ issueId: issue.id, role: "developer", round: 1, agentId: dev.id, runtime: "claude_code" });
-    const proposed = [];
-    const deps = makeDeps({
-        proposePatch: (playbookId) => {
-            proposed.push(playbookId);
-            return { ok: true, data: { id: "patch", playbookId } };
-        },
+    seedTerminalDeveloperSession(issue.id, dev);
+    const action = createHumanAction({
+        issueId: issue.id,
+        actionType: "final_review",
+        reason: "Needs a repair round.",
+        question: "Repair?",
     });
-    const result = await triggerIssueReflect(issue.id, deps);
-    assert.equal(result, "triggered");
-    assert.deepStrictEqual(proposed, ["pb-legacy"]);
+    resolveHumanAction(action.id, "operator", { choice: "repair" });
+    const { deps, calls } = makeDeps({ fetches: [{ playbook_id: "pb-1" }] });
+    assert.equal(await triggerIssueReflect(issue.id, deps), "triggered");
+    const proposes = () => calls.filter((c) => c.toolName === "propose_playbook_patch");
+    assert.equal(proposes().length, 1);
+    assert.equal(proposes()[0].args.kind, "signal_only");
+    // Simulated restart: idempotent, no duplicate Deck report.
+    assert.equal(await triggerIssueReflect(issue.id, deps), "skipped");
+    assert.equal(proposes().length, 1);
+    assert.equal(sentSignals(issue.id).length, 1);
 });
-test("skips when the deck is offline, and records why — never calls Deck tools", async () => {
-    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: "11111111-1111-4111-a111-111111111111" });
+test("records a visible failure and preserves state when the deck is offline", async () => {
+    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: DECK });
     const issue = seedIssue(dev.id);
-    seedFinalDeveloperSession(issue.id, dev, {
-        deckId: "11111111-1111-4111-a111-111111111111",
-        playbookIds: ["pb-1"],
-    });
-    const deps = {
-        checkHealth: async () => false,
-        callTool: (async () => {
-            throw new Error("should not be called");
-        }),
-    };
+    seedTerminalDeveloperSession(issue.id, dev);
+    const { deps, calls } = makeDeps({ checkHealth: async () => false });
     const result = await triggerIssueReflect(issue.id, deps);
-    assert.equal(result, "skipped");
+    assert.equal(result, "failed");
+    assert.deepStrictEqual(calls, []);
     const artifacts = listArtifactsForIssue(issue.id);
-    assert.ok(artifacts.some((a) => a.kind === "reflect_status" && JSON.parse(a.contentJson).reason === "Agent Deck offline"));
+    assert.ok(artifacts.some((a) => a.kind === "reflect_status" || (a.kind === "playbook_use_receipt" && JSON.parse(a.contentJson).status === "error")));
 });
-test("posts one patch per playbook, using the implementation conclusion and review history as rationale", async () => {
-    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+test("a retry after a failed signal send re-sends exactly once, never duplicating", async () => {
+    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: DECK });
     const issue = seedIssue(dev.id);
-    seedFinalDeveloperSession(issue.id, dev, {
-        deckId: "11111111-1111-4111-a111-111111111111",
-        playbookIds: ["pb-1", "pb-2"],
-    });
-    createIssueArtifact({
-        issueId: issue.id,
-        kind: "implementation_conclusion",
-        author: "agent",
-        content: { text: "Implemented the widget using the shared component." },
-    });
-    appendWorkflowEvent({
+    seedTerminalDeveloperSession(issue.id, dev);
+    const action = createHumanAction({
         issueId: issue.id,
-        type: "review.submitted",
-        actorType: "reviewer",
-        stage: "reviewing",
-        payload: { verdict: "changes_requested" },
-    });
-    appendWorkflowEvent({
-        issueId: issue.id,
-        type: "review.submitted",
-        actorType: "reviewer",
-        stage: "reviewing",
-        payload: { verdict: "approved" },
-    });
-    const proposed = [];
-    const deps = makeDeps({
-        proposePatch: (playbookId, rationale) => {
-            proposed.push(playbookId);
-            assert.match(rationale, /2 review round\(s\)/);
-            assert.match(rationale, /changes_requested → approved/);
-            assert.match(rationale, /Implemented the widget using the shared component\./);
-            return { ok: true, data: { id: `patch-${playbookId}`, playbookId } };
-        },
-    });
-    const result = await triggerIssueReflect(issue.id, deps);
-    assert.equal(result, "triggered");
-    assert.deepStrictEqual(proposed.sort(), ["pb-1", "pb-2"]);
-    const artifacts = listArtifactsForIssue(issue.id);
-    assert.equal(artifacts.filter((a) => a.kind === "playbook_patch").length, 2);
-});
-test("a retry after a mid-loop failure does not re-propose a playbook that already succeeded", async () => {
-    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
-    const issue = seedIssue(dev.id);
-    seedFinalDeveloperSession(issue.id, dev, {
-        deckId: "11111111-1111-4111-a111-111111111111",
-        playbookIds: ["pb-ok", "pb-fail"],
+        actionType: "final_review",
+        reason: "Needs a repair round.",
+        question: "Repair?",
     });
-    let failPbFail = true;
-    const proposedCalls = [];
-    const deps = makeDeps({
-        proposePatch: (playbookId) => {
-            proposedCalls.push(playbookId);
-            if (playbookId === "pb-fail" && failPbFail) {
-                return { ok: false, kind: "infra_failure", reason: "temporary deck error" };
-            }
-            return { ok: true, data: { id: `patch-${playbookId}`, playbookId } };
-        },
+    resolveHumanAction(action.id, "operator", { choice: "repair" });
+    let failPropose = true;
+    const { deps, calls } = makeDeps({
+        propose: () => failPropose
+            ? { ok: false, kind: "infra_failure", reason: "temporary deck error" }
+            : { ok: true, data: { id: "sig-1" } },
     });
+    const proposes = () => calls.filter((c) => c.toolName === "propose_playbook_patch");
     const first = await triggerIssueReflect(issue.id, deps);
-    assert.equal(first, "triggered");
-    assert.deepStrictEqual(proposedCalls, ["pb-ok", "pb-fail"]);
+    assert.equal(first, "triggered"); // the receipt still recorded
+    assert.equal(proposes().length, 1);
+    assert.equal(sentSignals(issue.id).length, 0);
     createHumanAction({
         issueId: issue.id,
         actionType: "reflection_interaction_required",
@@ -243,11 +179,12 @@ test("a retry after a mid-loop failure does not re-propose a playbook that alrea
         ],
     });
     const parkedAction = listHumanActionsForIssue(issue.id).find((a) => a.actionType === "reflection_interaction_required" && a.status === "open");
-    failPbFail = false;
+    failPropose = false;
     const resolved = resolveReflectionInteractionAction(parkedAction.id, "operator", "retry", deps);
     assert.equal(resolved.ok, true);
-    await waitFor(() => proposedCalls.length >= 3);
-    assert.deepStrictEqual(proposedCalls, ["pb-ok", "pb-fail", "pb-fail"]);
+    await waitFor(() => sentSignals(issue.id).length >= 1);
+    assert.equal(proposes().length, 2);
+    assert.equal(sentSignals(issue.id).length, 1);
 });
 test("resolveReflectionInteractionAction:dismiss closes the action without further Deck calls", async () => {
     const issue = seedIssue(BUILTIN_AGENT_CLAUDE_ID);
@@ -289,36 +226,48 @@ test("resolveReflectionInteractionAction rejects an invalid choice and already-r
     const alreadyResolved = resolveReflectionInteractionAction(parkedAction.id, "operator", "retry");
     assert.equal(alreadyResolved.ok, false);
 });
-test("already-proposed playbook ids are skipped even behind a flood of other artifacts", async () => {
-    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: "00000000-0000-4000-a000-000000000099" });
+test("reflect_status names a malformed correlation response instead of blaming an offline Deck", async () => {
+    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: DECK });
     const issue = seedIssue(dev.id);
-    seedFinalDeveloperSession(issue.id, dev, {
-        deckId: "11111111-1111-4111-a111-111111111111",
-        playbookIds: ["pb-ok", "pb-next"],
-    });
-    createIssueArtifact({
+    seedTerminalDeveloperSession(issue.id, dev);
+    const { deps } = makeDeps({ correlationData: { unexpected: "shape" } });
+    const result = await triggerIssueReflect(issue.id, deps);
+    assert.equal(result, "failed");
+    const statuses = listArtifactsForIssueByKind(issue.id, "reflect_status").map((a) => JSON.parse(a.contentJson));
+    assert.ok(statuses.length > 0);
+    const text = statuses.map((s) => `${s.reason ?? ""} ${s.error ?? ""}`).join("\n");
+    assert.match(text, /malformed/i);
+    assert.doesNotMatch(text, /offline/i);
+});
+test("reflect_status still says offline when the receipt error really is a Deck outage", async () => {
+    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: DECK });
+    const issue = seedIssue(dev.id);
+    seedTerminalDeveloperSession(issue.id, dev);
+    const { deps } = makeDeps({ checkHealth: async () => false });
+    assert.equal(await triggerIssueReflect(issue.id, deps), "failed");
+    const statuses = listArtifactsForIssueByKind(issue.id, "reflect_status").map((a) => JSON.parse(a.contentJson));
+    assert.ok(statuses.some((s) => /offline/i.test(`${s.reason ?? ""} ${s.error ?? ""}`)));
+});
+test("never calls propose_playbook_patch with kind:update and never writes Notes items", async () => {
+    const dev = createAgent({ name: `dev-${Math.random()}`, runtime: "claude_code", deckId: DECK });
+    const issue = seedIssue(dev.id);
+    seedTerminalDeveloperSession(issue.id, dev);
+    const action = createHumanAction({
         issueId: issue.id,
-        kind: "playbook_patch",
-        author: "system",
-        content: { patchId: "existing", playbookId: "pb-ok", status: "proposed" },
+        actionType: "attempts_exhausted",
+        reason: "Rounds spent.",
+        question: "Close?",
     });
-    for (let i = 0; i < 30; i++) {
-        createIssueArtifact({
-            issueId: issue.id,
-            kind: "developer_transcript",
-            author: "system",
-            content: { n: i },
-        });
+    resolveHumanAction(action.id, "operator", { choice: "close" });
+    const { deps, calls } = makeDeps({ fetches: [{ playbook_id: "pb-9" }] });
+    await triggerIssueReflect(issue.id, deps);
+    for (const call of calls) {
+        if (call.toolName !== "propose_playbook_patch")
+            continue;
+        assert.notEqual(call.args.kind, "update");
+        assert.equal(call.args.kind, "signal_only");
+        const ops = call.args.ops;
+        assert.ok(!ops || !ops.some((op) => op.section === "Notes"));
     }
-    const proposed = [];
-    const deps = makeDeps({
-        proposePatch: (playbookId) => {
-            proposed.push(playbookId);
-            return { ok: true, data: { id: `patch-${playbookId}`, playbookId } };
-        },
-    });
-    const result = await triggerIssueReflect(issue.id, deps);
-    assert.equal(result, "triggered");
-    assert.deepStrictEqual(proposed, ["pb-next"]);
-    assert.equal(listArtifactsForIssueByKind(issue.id, "playbook_patch").length, 2);
+    assert.equal(listArtifactsForIssueByKind(issue.id, "playbook_patch").length, 0);
 });

package/bundle/server/dist/coordinator/repair-cycle.integration.test.js

@@ -197,6 +197,7 @@ test("developer round 1 → reviewer changes_requested → developer round 2 on
     assert.equal(issue.status, "final_review", "the cycle must end at a human final_review, not stuck or escalated");
     assert.equal(issue.currentRound, 2, "exactly one genuine repair round — changes_requested — was spent");
     assert.equal(issue.infraAttempts, 0, "nothing in this run was an infra failure");
+    assert.equal(issue.ciAttempts, 0, "nothing in this run was a CI failure either");
     assert.ok(listHumanActionsForIssue(issueId).find((a) => a.actionType === "final_review" && a.status === "open"));
     // Same branch reused across both rounds — never re-created.
     const branch = issueBranchName(issueId);

package/bundle/server/dist/coordinator/reviewer-effect.js

@@ -26,6 +26,7 @@ import os from "node:os";
 import path from "node:path";
 import { parseProfileSnapshot, roleCeiling } from "@agent-dealer/shared";
 import { getTaskSnapshot } from "./commands.js";
+import { extractOperatorCriteria } from "./operator-criteria.js";
 import { buildReviewerPrompt, formatDiffForPrompt, TOTAL_DIFF_LIMIT } from "./prompts.js";
 import { guidanceForNextSession } from "./guidance.js";
 import { realReviewerSpawn, reviewerSessionLogPath } from "./spawn.js";
@@ -34,7 +35,7 @@ import { createRoleWorktree, safeRemoveWorktree, isWorktreeClean, mergeBase, fet
 import { ensureIssueRepoCheckout, roleWorktreePathForResolution, resolveCheckoutBaseBranch, } from "../adapters/managed-repo.js";
 import { prepareWorkerDeckConnection, releaseWorkerDeckConnection } from "../adapters/agent-deck-bind.js";
 import { realGithubAdapter } from "../adapters/github.js";
-import { getWorkerSession, patchRunningSession, recordSessionProcess } from "../repository/worker-sessions.js";
+import { getOrAssignSessionCorrelationId, getWorkerSession, patchRunningSession, recordSessionProcess } from "../repository/worker-sessions.js";
 import { COORDINATOR_PROCESS_OWNER, readProcessStartTime } from "./process-liveness.js";
 import { reviewerSessionTimeoutMs } from "./session-timeouts.js";
 import { getWorkItem } from "../repository/work-items.js";
@@ -196,6 +197,11 @@ function renderReviewBody(result, marker) {
         `**Evidence assessment**`,
         result.evidenceAssessment,
     ];
+    // NOT-306: the exit-predicate verdict rides with the review when the task
+    // carried an execution contract; legacy reviews simply omit the section.
+    if (result.exitPredicateAssessment?.trim()) {
+        lines.push(``, `**Exit predicate assessment**`, result.exitPredicateAssessment);
+    }
     if (result.findings.length) {
         lines.push(``, `**Findings**`);
         for (const f of result.findings) {
@@ -222,6 +228,9 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
         return { kind: "session_failed" };
     const session = getWorkerSession(sessionId);
     const snapshot = parseProfileSnapshot(session?.profileSnapshotJson);
+    // NOT-305: opaque per-session Deck correlation UUID, persisted before spawn and
+    // carried as observability metadata in the materialized launch config below.
+    const deckCorrelationId = session?.deckCorrelationId ?? getOrAssignSessionCorrelationId(sessionId);
     const taskSnapshot = getTaskSnapshot(issue);
     const runtime = snapshot?.runtime ?? "claude_code";
     const round = workItem.round;
@@ -291,6 +300,7 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
                     worktreePath,
                     runtime,
                     policy,
+                    correlationId: deckCorrelationId,
                     verifyCallTool: deps.deckCallTool,
                 });
                 if (!prepared.ok) {
@@ -327,6 +337,10 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
             const { truncated: diffTruncated, omittedPaths } = formatDiffForPrompt(diff);
             const openFindings = listFindingsForIssue(issue.id).filter((f) => f.status === "open" || f.status === "recurring");
             const guidance = guidanceForNextSession(issue.id, sessionId);
+            // NOT-314: the frozen snapshot's operator criteria — the reviewer must not
+            // treat missing operator evidence as a defect (Dealer gates the merge), but
+            // the probe and doc must exist. Rendered only when non-empty.
+            const operatorCriteria = extractOperatorCriteria(taskSnapshot.acceptanceCriteria);
             const prompt = buildReviewerPrompt({
                 taskSnapshot,
                 round: workItem.round,
@@ -339,6 +353,7 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
                 worktreePath,
                 deckId: snapshot?.deckId ?? null,
                 guidance: guidance.length ? guidance : undefined,
+                operatorCriteria: operatorCriteria.length > 0 ? operatorCriteria : undefined,
             });
             // NOT-83 review finding — see developer-effect.ts's identical check for the full
             // rationale: re-verify this item is still leased right before the real spawn, since an

package/bundle/server/dist/coordinator/reviewer-result.js

@@ -14,6 +14,12 @@ export const ReviewerResult = z.object({
     headSha: z.string(),
     acceptanceCriteriaAssessment: z.string(),
     evidenceAssessment: z.string(),
+    /**
+     * NOT-306: whether the frozen exit predicate held at the reviewed tip. The
+     * reviewer sets this when the task carries an execution contract; legacy
+     * contract-free tasks omit it (optional so older outputs still parse).
+     */
+    exitPredicateAssessment: z.string().optional(),
     findings: z.array(ReviewerFinding),
     risks: z.array(z.string()),
     /** Present only when verdict is "escalated" and the reviewer identifies a missing product call. */

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

@@ -1,4 +1,5 @@
 // packages/server/src/coordinator/routing.ts
+import { DEFAULT_MAX_CI_ATTEMPTS } from "@agent-dealer/shared";
 import { normalizeReviewerResult } from "./reviewer-result.js";
 /** Default N for NOT-147: escalate empty-tip timeout/crash after this many failures (one auto-retry). */
 export const DEFAULT_NO_PROGRESS_INFRA_ATTEMPTS = 2;
@@ -14,6 +15,13 @@ function roundsRemain(limits) {
 export function infraAttemptsRemain(limits) {
     return limits.infraAttempts < limits.maxInfraAttempts;
 }
+/**
+ * NOT-313: the one definition of "is there CI-repair budget left", mirroring
+ * {@link infraAttemptsRemain}. Absent counters read as a fresh default budget.
+ */
+export function ciAttemptsRemain(limits) {
+    return (limits.ciAttempts ?? 0) < (limits.maxCiAttempts ?? DEFAULT_MAX_CI_ATTEMPTS);
+}
 export function routeDeveloperOutcome(outcome, limits) {
     switch (outcome.kind) {
         case "clean_handoff":
@@ -103,7 +111,6 @@ export function routeDeveloperOutcome(outcome, limits) {
                 : { next: "human_action", actionType: "policy_escalation", reason: `${reason} (infra-attempt limit reached).` };
         }
         case "no_pr":
-        case "checks_failed":
         case "deck_failure": {
             // Unified infra-failure policy: the session/environment failed to produce a
             // reviewable result at all — bounded auto-retry on max_infra_attempts, decoupled
@@ -113,6 +120,30 @@ export function routeDeveloperOutcome(outcome, limits) {
                 ? { next: "retry_developer", reason }
                 : { next: "human_action", actionType: "policy_escalation", reason: `${reason} (infra-attempt limit reached).` };
         }
+        case "checks_failed": {
+            // NOT-313: a failing CI check is the expected feedback loop, not an
+            // infrastructure failure — bounded on max_ci_attempts, never the infra
+            // budget. The retry reason names the attempt number so the next session's
+            // prompt reads "CI repair attempt N of M"; the escalation names the same
+            // count plus the failing checks (via the NOT-252 enrichment), never the
+            // infra-attempt text. policy_escalation (not attempts_exhausted) so a human
+            // "resume" resets budgets without spending a review round.
+            const spent = limits.ciAttempts ?? 0;
+            const max = limits.maxCiAttempts ?? DEFAULT_MAX_CI_ATTEMPTS;
+            const base = checksFailedDetails(outcome);
+            if (ciAttemptsRemain(limits)) {
+                return {
+                    next: "retry_developer",
+                    reason: `CI repair attempt ${spent + 1} of ${max}: ${base}`,
+                    budget: "ci",
+                };
+            }
+            return {
+                next: "human_action",
+                actionType: "policy_escalation",
+                reason: `CI checks still failing after ${spent} repair attempts (limit ${max}). ${base}`,
+            };
+        }
         case "session_failed":
         case "timed_out": {
             // Same infra budget as above, plus NOT-147: empty tip after N timeout/crashes → human
@@ -140,6 +171,11 @@ export function routeDeveloperOutcome(outcome, limits) {
             // NOT-197: a hard-down network is not retryable on the infra-attempt timescale, and
             // nothing was spawned, so there is no attempt to charge. Wait for the network instead.
             return { next: "defer_work", reason: outcome.reason };
+        case "checks_pending":
+            // NOT-311: slow or not-yet-registered CI is not a developer failure — the
+            // session ended cleanly with a pushed branch and an open PR. Wait on backoff
+            // and re-poll; the deferral path (not this route) enforces the wait ceiling.
+            return { next: "defer_work", reason: outcome.reason };
     }
 }
 function infraFailureReason(outcome) {
@@ -150,17 +186,20 @@ function infraFailureReason(outcome) {
             return outcome.reason ?? "Developer session failed or crashed.";
         case "timed_out":
             return outcome.reason ?? "Developer session timed out.";
-        case "checks_failed":
-            // NOT-252: prefer the sanitized enrichment the effect threaded into `details`
-            // (failing check names + bounded untrusted excerpt at the verified head SHA).
-            // Blank/absent details keep today's exact generic reason.
-            return outcome.details?.trim() ? outcome.details : "Developer's PR checks failed.";
         case "adapter_failure":
             return `Git/GitHub verification failed: ${outcome.reason}`;
         case "deck_failure":
             return `Agent Deck ${outcome.reason}`;
     }
 }
+/**
+ * NOT-252: prefer the sanitized enrichment the effect threaded into `details`
+ * (failing check names + bounded untrusted excerpt at the verified head SHA).
+ * Blank/absent details keep the exact generic reason.
+ */
+function checksFailedDetails(outcome) {
+    return outcome.details?.trim() ? outcome.details : "Developer's PR checks failed.";
+}
 /**
  * NOT-147: when a timeout/crash left the branch with zero commits ahead of base, stop
  * burning full agent spawns after N failures (default 2 = one auto-retry). Only trips when