agent-dealer 1.2.7 → 1.2.8

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/reviewer-effect.js

@@ -34,7 +34,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 +196,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 +227,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 +299,7 @@ export async function runReviewerEffect(ctx, deps = defaultDeps) {
                     worktreePath,
                     runtime,
                     policy,
+                    correlationId: deckCorrelationId,
                     verifyCallTool: deps.deckCallTool,
                 });
                 if (!prepared.ok) {

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.test.js

@@ -216,6 +216,20 @@ test("timed_out with infra attempts remaining retries (same bucket as session_fa
         reason: "Developer session timed out.",
     });
 });
+test("NOT-307: an idle-watchdog timed_out routes exactly like a wall-clock timeout", () => {
+    // The idle kill reads as timed_out downstream: same bounded infra retry, same
+    // budget accounting — only the reason (and the failure cause) names the stall.
+    const outcome = {
+        kind: "timed_out",
+        reason: "Developer session made no progress for 20 minutes. (last tool: npm_test) Killed on the idle timeout.",
+    };
+    assert.deepStrictEqual(routeDeveloperOutcome(outcome, INFRA_ATTEMPTS_LEFT), {
+        next: "retry_developer",
+        reason: "Developer session made no progress for 20 minutes. (last tool: npm_test) Killed on the idle timeout.",
+    });
+    assert.deepStrictEqual(routeDeveloperOutcome({ kind: "timed_out" }, INFRA_AT_LIMIT).next, "human_action");
+    assert.deepStrictEqual(routeDeveloperOutcome(outcome, INFRA_AT_LIMIT).next, "human_action");
+});
 test("checks_failed with infra attempts remaining retries (same bucket as session_failed/no_pr)", () => {
     const outcome = { kind: "checks_failed" };
     assert.deepStrictEqual(routeDeveloperOutcome(outcome, INFRA_ATTEMPTS_LEFT), {

package/bundle/server/dist/coordinator/session-timeouts.js

@@ -5,6 +5,36 @@ export function developerSessionTimeoutMs() {
 export function reviewerSessionTimeoutMs() {
     return num("REVIEWER_TIMEOUT_MS", 30 * 60_000);
 }
+/**
+ * NOT-307: silent-child bound for the Muse developer lane only (other runtimes do
+ * not read this). Undefined means the watchdog is disabled. The watchdog ships
+ * ENABLED with a 30-minute default: 20 min risks false kills against the
+ * reported ~39.8 min silent gap in completed-session history; 45 min saves only
+ * 15 of the 60-min wall-clock cap; disabled does not address the observed
+ * 1-hour stalls. The ~39.8 min figure could not be re-verified — historical raw
+ * logs carry replayed `recorded_at`, not arrival times, so it may overstate
+ * true stdout/session.jsonl silence. The value is env-tunable, and the new
+ * per-event `ts`/`durationMs` plus `metadata_json` stall fields will provide
+ * the real gap distribution to recalibrate; a false kill is bounded by timeout
+ * salvage + retry from the branch. `0` disables explicitly. A non-numeric or
+ * negative value falls back to the default with a logged warning rather than
+ * silently disabling the guard (or killing healthy sessions on a typo like
+ * `-1`).
+ */
+export const DEFAULT_MUSE_IDLE_TIMEOUT_MS = 30 * 60_000;
+export function museIdleTimeoutMs() {
+    const raw = process.env.MUSE_IDLE_TIMEOUT_MS;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_MUSE_IDLE_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed === 0)
+        return undefined;
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        console.warn(`[dealer] ignoring invalid MUSE_IDLE_TIMEOUT_MS=${JSON.stringify(raw)} — using default ${DEFAULT_MUSE_IDLE_TIMEOUT_MS}`);
+        return DEFAULT_MUSE_IDLE_TIMEOUT_MS;
+    }
+    return parsed;
+}
 export function sessionTimeoutMsFor(role) {
     return role === "reviewer" ? reviewerSessionTimeoutMs() : developerSessionTimeoutMs();
 }

package/bundle/server/dist/coordinator/usage-cap.integration.test.js

@@ -32,8 +32,8 @@ beforeEach(() => {
     DELETE FROM human_actions;
     DELETE FROM workflow_events;
     DELETE FROM findings;
-    DELETE FROM worker_sessions;
     DELETE FROM artifacts;
+    DELETE FROM worker_sessions;
     DELETE FROM usage_events;
     DELETE FROM workflow_instances;
     DELETE FROM issues;

package/bundle/server/dist/coordinator/worker-loop.js

@@ -83,6 +83,15 @@ function safeCompleteSession(sessionId, status, error) {
     catch (err) {
         console.error("[coordinator] completeSession", sessionId, err);
     }
+    // NOT-305: best-effort actual-use receipt the moment the session goes terminal — a
+    // later issue-completion trigger re-attempts anything still missing, so this never
+    // throws and never changes the session outcome or the issue state.
+    try {
+        void import("./playbook-feedback.js").then(({ collectPlaybookUseReceipt }) => collectPlaybookUseReceipt(sessionId).catch(() => { }));
+    }
+    catch (err) {
+        console.error("[coordinator] playbook receipt", sessionId, err);
+    }
 }
 /**
  * A failed effect (handler threw, or lost its lease mid-run). One transaction, fenced on
@@ -269,10 +278,6 @@ async function processWorkItem(claimed) {
         safeCompleteSession(session.id, "cancelled", { reason: result.reason });
         return;
     }
-    if (result.triggerReflect) {
-        const { triggerIssueReflect } = await import("./reflect-trigger.js");
-        void triggerIssueReflect(claimed.issueId).catch(() => { });
-    }
     // NOT-136: a deck-unavailable session never spawned anything — `cancelled`, not `failed`
     // (which would read as a worker crash) and not `done` (which would claim it ran).
     // NOT-197: a base-fetch failure likewise never spawned (and created no branch).
@@ -298,7 +303,16 @@ async function processWorkItem(claimed) {
             }),
         }
         : undefined;
+    // NOT-305: the session row goes terminal BEFORE the issue-level reflect trigger
+    // below. triggerIssueReflect collects receipts for every terminal session, and
+    // completeSession writes the terminal status synchronously — firing reflect first
+    // would exclude this just-finished session from the signal's worker sessions and
+    // playbook evidence.
     safeCompleteSession(session.id, sessionStatus, errorPayload);
+    if (result.triggerReflect) {
+        const { triggerIssueReflect } = await import("./reflect-trigger.js");
+        void triggerIssueReflect(claimed.issueId).catch(() => { });
+    }
 }
 /**
  * Claims and starts as many work items as free concurrency slots allow, then returns the

package/bundle/server/dist/db/index.js

@@ -131,6 +131,11 @@ export function migrate() {
     if (!workerSessionCols.some((c) => c.name === "process_started_at")) {
         db.exec("ALTER TABLE worker_sessions ADD COLUMN process_started_at TEXT");
     }
+    // NOT-305: opaque Deck correlation UUID per session. Pre-feature rows stay NULL,
+    // which readers treat as "no correlation" (receipt records a skip, never a guess).
+    if (!workerSessionCols.some((c) => c.name === "deck_correlation_id")) {
+        db.exec("ALTER TABLE worker_sessions ADD COLUMN deck_correlation_id TEXT");
+    }
     // NOT-181: the model a session actually ran (Muse's server-confirmed one). Existing rows stay
     // NULL, which every reader treats as "not recorded".
     const usageEventCols = db.prepare("PRAGMA table_info(usage_events)").all();

package/bundle/server/dist/db/schema.sql

@@ -155,6 +155,9 @@ CREATE TABLE IF NOT EXISTS worker_sessions (
   process_pid INTEGER,
   process_owner TEXT,
   process_started_at TEXT,
+  -- NOT-305: opaque Agent Deck correlation UUID, one per session, generated before
+  -- spawn and passed as observability metadata in every runtime's Deck launch config.
+  deck_correlation_id TEXT,
   created_at TEXT NOT NULL,
   started_at TEXT,
   heartbeat_at TEXT,

package/bundle/server/dist/docs-execution-analysis.test.js

@@ -67,6 +67,7 @@ test("the contract defines every phase, taxonomy code, and quality label", () =>
         "provider_capacity_rate_limit",
         "agent_cli_crash",
         "tool_test_timeout",
+        "muse_no_progress",
         "coordinator_crash",
         "validation_failure",
         "publish_git_failure",