agent-dealer 1.2.6 → 1.2.8

package/bundle/server/dist/coordinator/playbook-feedback.js

@@ -0,0 +1,690 @@
+// packages/server/src/coordinator/playbook-feedback.ts
+//
+// NOT-305: Dealer-side playbook-use receipts and failure/correction signals to Deck.
+//
+// Product boundary (NOT-162): Dealer owns worker/run correlation, durable workflow
+// evidence, outcomes, review findings, human retry feedback, and the decision that a
+// failure report exists. Deck owns feedback-signal storage, curation, playbook
+// attribution, patch proposals, and accepted playbook content. Dealer never synthesizes
+// a playbook edit and never attributes a failure to one playbook.
+//
+// Two durable artifacts, both idempotent across retries/restarts:
+//
+// - `playbook_use_receipt`: one per terminal worker session, naming exactly the
+//   playbooks Deck observed that session fetch (via the NOT-304 correlation seam),
+//   plus collection status/error. Never stores prompts, tool arguments/results,
+//   repository names, or issue descriptions — only the fields the design names.
+// - `deck_feedback_signal`: one per failure/correction trigger (human retry,
+//   attempts exhaustion, recurring blocking finding), sent to Deck as a `signal_only`
+//   feedback record with a deterministic source key. Clean runs record receipts only.
+import { parseProfileSnapshot } from "@agent-dealer/shared";
+import { checkAgentDeckHealth } from "../adapters/agent-deck.js";
+import { callDeckTool } from "../adapters/reflect-authority.js";
+import { getIssue } from "../repository/issues.js";
+import { getWorkerSession, listWorkerSessionsForIssue } from "../repository/worker-sessions.js";
+import { createIssueArtifact } from "../repository/artifacts.js";
+import { listArtifactsForIssueByKind } from "../repository/artifacts-for-issue.js";
+import { listFindingsForIssue } from "../repository/findings.js";
+import { listHumanActionsForIssue } from "../repository/human-actions.js";
+const CORRELATION_TOOL_TIMEOUT_MS = 15_000;
+const SIGNAL_TOOL_TIMEOUT_MS = 15_000;
+/**
+ * Bound, read-only Deck correlation operation (the NOT-304 seam): given the opaque
+ * per-session correlation UUID Dealer passed in the launch configuration, returns the
+ * playbooks Deck actually observed that session fetch. Dealer calls it; Deck owns the
+ * usage stream and the attribution.
+ */
+export const DECK_CORRELATION_TOOL = "list_card_usage_by_correlation";
+export const PLAYBOOK_USE_RECEIPT_KIND = "playbook_use_receipt";
+export const DECK_FEEDBACK_SIGNAL_KIND = "deck_feedback_signal";
+const defaultDeps = {
+    checkHealth: checkAgentDeckHealth,
+    callTool: callDeckTool,
+};
+const TERMINAL_SESSION = new Set(["done", "failed", "timed_out", "cancelled"]);
+function sessionDeckId(session) {
+    return parseProfileSnapshot(session.profileSnapshotJson)?.deckId ?? null;
+}
+function parseReceiptContent(contentJson) {
+    if (!contentJson)
+        return null;
+    try {
+        const parsed = JSON.parse(contentJson);
+        if (typeof parsed.workerSessionId !== "string" || !Array.isArray(parsed.playbookIds))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Latest receipt recorded for one session — readers take the latest; a retry after an
+ * earlier `error`/`skipped` row appends a fresh row rather than rewriting history.
+ * (`listArtifactsForIssueByKind` orders newest-first, so the first match wins.) */
+export function latestReceiptForSession(issueId, workerSessionId) {
+    const rows = listArtifactsForIssueByKind(issueId, PLAYBOOK_USE_RECEIPT_KIND);
+    for (const row of rows) {
+        const receipt = parseReceiptContent(row.contentJson);
+        if (receipt?.workerSessionId === workerSessionId)
+            return receipt;
+    }
+    return null;
+}
+/**
+ * Distinct error texts on the latest receipt of each worker session still in
+ * `error` — so the issue-level `reflect_status` can name the actual failure (Deck
+ * offline vs. malformed correlation response) instead of blaming the network for
+ * every receipt error.
+ */
+export function latestReceiptErrors(issueId) {
+    const errors = new Set();
+    for (const session of listWorkerSessionsForIssue(issueId)) {
+        const receipt = latestReceiptForSession(issueId, session.id);
+        if (receipt?.status === "error" && receipt.error)
+            errors.add(receipt.error);
+    }
+    return [...errors];
+}
+function recordReceipt(issueId, workerSessionId, receipt) {
+    createIssueArtifact({
+        issueId,
+        workerSessionId,
+        kind: PLAYBOOK_USE_RECEIPT_KIND,
+        author: "system",
+        content: receipt,
+    });
+    return receipt;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+/**
+ * Parses the NOT-304 correlation response tolerantly on envelope naming (Deck owns the
+ * field names) but strictly on identity: every fetch must name a non-empty playbook ID
+ * string, otherwise the whole response is malformed — guessing IDs would corrupt the
+ * receipt. Returns null on malformed input.
+ */
+export function parseCorrelatedFetches(data) {
+    const root = asRecord(data);
+    if (!root)
+        return null;
+    const raw = root.fetches ?? root.usage ?? root.cards;
+    if (!Array.isArray(raw))
+        return null;
+    const fetches = [];
+    for (const entry of raw) {
+        const record = asRecord(entry);
+        if (!record)
+            return null;
+        const playbookId = asString(record.playbook_id) ?? asString(record.playbookId) ?? asString(record.id);
+        if (!playbookId)
+            return null;
+        fetches.push({
+            playbookId,
+            firstFetchedAt: asString(record.first_fetched_at) ??
+                asString(record.firstFetchedAt) ??
+                asString(record.fetched_at) ??
+                null,
+            lastFetchedAt: asString(record.last_fetched_at) ??
+                asString(record.lastFetchedAt) ??
+                asString(record.fetched_at) ??
+                null,
+        });
+    }
+    return fetches;
+}
+function summarizeFetches(fetches) {
+    const playbookIds = [];
+    const seen = new Set();
+    let first = null;
+    let last = null;
+    for (const fetch of fetches) {
+        if (!seen.has(fetch.playbookId)) {
+            seen.add(fetch.playbookId);
+            playbookIds.push(fetch.playbookId);
+        }
+        for (const stamp of [fetch.firstFetchedAt, fetch.lastFetchedAt]) {
+            if (!stamp)
+                continue;
+            if (first === null || stamp < first)
+                first = stamp;
+            if (last === null || stamp > last)
+                last = stamp;
+        }
+    }
+    return { playbookIds, firstFetchedAt: first, lastFetchedAt: last };
+}
+/**
+ * Same-process guard against concurrent duplicate collection: the session-end probe
+ * in worker-loop.ts and the issue-level trigger both collect for the just-finished
+ * session, and without this the check-then-write below races into two `collected`
+ * rows. Concurrent callers for one session share a single collection. (Cross-process
+ * races remain possible — there is no unique constraint on receipt rows — so readers
+ * always take the latest row per session.)
+ */
+const receiptInflight = new Map();
+export async function collectPlaybookUseReceipt(workerSessionId, deps = defaultDeps) {
+    const inflight = receiptInflight.get(workerSessionId);
+    if (inflight)
+        return inflight;
+    const task = collectPlaybookUseReceiptInner(workerSessionId, deps).finally(() => {
+        if (receiptInflight.get(workerSessionId) === task)
+            receiptInflight.delete(workerSessionId);
+    });
+    receiptInflight.set(workerSessionId, task);
+    return task;
+}
+/**
+ * Records the actual-use receipt for one worker session. Never throws: Deck outages
+ * and malformed responses become an `error`-status receipt (a visible record,
+ * re-attempted by a later reflection trigger), and non-terminal or unknown sessions
+ * return a reason without writing.
+ * Idempotent: a non-empty `collected` receipt is returned as-is; an `error`/`skipped`
+ * row — or a `collected` row naming zero playbooks — is re-attempted and superseded
+ * by a fresh row. An empty list collected at session end is provisional: Deck may
+ * ingest usage asynchronously after the probe, so freezing it would permanently hide
+ * playbooks fetched moments later; the issue-level trigger re-reads until use shows
+ * up (or re-confirms genuinely empty). A later trigger after a restart or Deck
+ * recovery heals the gap without duplicating non-empty collected evidence.
+ */
+async function collectPlaybookUseReceiptInner(workerSessionId, deps = defaultDeps) {
+    const session = getWorkerSession(workerSessionId);
+    if (!session)
+        return { collected: false, reason: "unknown worker session" };
+    if (!TERMINAL_SESSION.has(session.status)) {
+        return { collected: false, reason: "worker session is not terminal" };
+    }
+    const existing = latestReceiptForSession(session.issueId, workerSessionId);
+    if (existing?.status === "collected" && existing.playbookIds.length > 0) {
+        return { collected: true, receipt: existing, duplicate: true };
+    }
+    const deckId = sessionDeckId(session);
+    const base = {
+        workerSessionId,
+        role: session.role,
+        deckId,
+        correlationId: session.deckCorrelationId,
+        runtime: session.runtime,
+        model: session.model,
+        playbookIds: [],
+        firstFetchedAt: null,
+        lastFetchedAt: null,
+        status: "skipped",
+    };
+    if (!deckId) {
+        return {
+            collected: false,
+            reason: recordReceipt(session.issueId, workerSessionId, {
+                ...base,
+                reason: "no deck in session profile snapshot — nothing to correlate",
+            }).reason,
+        };
+    }
+    if (!session.deckCorrelationId) {
+        return {
+            collected: false,
+            reason: recordReceipt(session.issueId, workerSessionId, {
+                ...base,
+                reason: "no deck correlation id on worker session — nothing to correlate",
+            }).reason,
+        };
+    }
+    const healthy = await deps.checkHealth().catch(() => false);
+    if (!healthy) {
+        recordReceipt(session.issueId, workerSessionId, {
+            ...base,
+            status: "error",
+            error: "Agent Deck offline — receipt collection resumes the next time issue reflection runs (a later completion trigger or an explicit reflection retry)",
+        });
+        return { collected: false, reason: "Agent Deck offline" };
+    }
+    const correlated = await deps.callTool({
+        deckId,
+        toolName: DECK_CORRELATION_TOOL,
+        arguments: { correlation_id: session.deckCorrelationId },
+        timeoutMs: CORRELATION_TOOL_TIMEOUT_MS,
+    });
+    if (!correlated.ok) {
+        recordReceipt(session.issueId, workerSessionId, {
+            ...base,
+            status: "error",
+            error: correlated.reason,
+        });
+        return { collected: false, reason: correlated.reason };
+    }
+    const fetches = parseCorrelatedFetches(correlated.data);
+    if (!fetches) {
+        recordReceipt(session.issueId, workerSessionId, {
+            ...base,
+            status: "error",
+            error: "malformed correlation response — no usable playbook fetch list",
+        });
+        return { collected: false, reason: "malformed correlation response" };
+    }
+    const summary = summarizeFetches(fetches);
+    const receipt = recordReceipt(session.issueId, workerSessionId, {
+        ...base,
+        ...summary,
+        status: "collected",
+        ...(summary.playbookIds.length === 0 ? { reason: "no observed playbook use" } : {}),
+    });
+    return { collected: true, receipt, duplicate: false };
+}
+/** Collects receipts for every terminal session of the issue still missing one. */
+export async function collectPlaybookUseReceiptsForIssue(issueId, deps = defaultDeps) {
+    let collected = 0;
+    let pending = 0;
+    let errors = 0;
+    for (const session of listWorkerSessionsForIssue(issueId)) {
+        if (!TERMINAL_SESSION.has(session.status))
+            continue;
+        const result = await collectPlaybookUseReceipt(session.id, deps);
+        if (result.collected && !result.duplicate)
+            collected++;
+        else if (!result.collected) {
+            pending++;
+            if (latestReceiptForSession(session.issueId, session.id)?.status === "error")
+                errors++;
+        }
+    }
+    return { collected, pending, errors };
+}
+// ---------------------------------------------------------------------------
+// Failure/correction signals.
+// ---------------------------------------------------------------------------
+/** Human choices that correct or retry the work (as opposed to accepting/closing it). */
+const CORRECTION_CHOICES = {
+    final_review: ["repair"],
+    attempts_exhausted: ["retry"],
+    policy_escalation: ["resume", "repair", "retry_merge"],
+    product_scope_decision: ["resume"],
+    deck_interaction_required: ["resume"],
+};
+function resolutionChoice(resolutionJson) {
+    if (!resolutionJson)
+        return null;
+    try {
+        const choice = JSON.parse(resolutionJson).choice;
+        return typeof choice === "string" ? choice : null;
+    }
+    catch {
+        return null;
+    }
+}
+function excerpt(text, max = 500) {
+    const trimmed = text?.trim();
+    if (!trimmed)
+        return null;
+    return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+}
+/**
+ * Explicit fallback excerpt when no human stated a reason (recurring blocking
+ * findings, blank retry reasons). Deck rejects a missing/blank
+ * user_feedback_excerpt, so a report must never omit it. Constant text keeps
+ * repeated sends byte-identical for crash-window idempotency.
+ */
+export const NO_HUMAN_FEEDBACK_EXCERPT = "no human feedback — Dealer-observed failure (see failure_summary for observed evidence)";
+/**
+ * Deck's `propose_playbook_patch` input schema (additionalProperties:false).
+ * Dealer may only send these top-level fields; the issue-centric reflection path
+ * sends `signal_only` with `kind` + `rationale` + `evidence` and never
+ * `playbook_id`/`ops` (no attribution, no synthesized edit).
+ */
+const DECK_SIGNAL_TOP_LEVEL_KEYS = new Set([
+    "kind",
+    "rationale",
+    "evidence",
+    "signal_ids",
+    "supersedes",
+    "ops",
+    "playbook_id",
+    "new_playbook",
+]);
+/** Returns null when args satisfy Deck's schema; otherwise a human-readable reason. */
+export function validateSignalOnlyArgs(args) {
+    for (const key of Object.keys(args)) {
+        if (!DECK_SIGNAL_TOP_LEVEL_KEYS.has(key))
+            return `unknown top-level field: ${key}`;
+    }
+    if (args.kind !== "signal_only")
+        return `kind must be "signal_only"`;
+    if (typeof args.rationale !== "string" || !args.rationale.trim()) {
+        return "rationale must be a non-empty string";
+    }
+    const evidence = asRecord(args.evidence);
+    if (!evidence)
+        return "evidence must be an object";
+    for (const key of Object.keys(evidence)) {
+        if (key !== "failure_summary" && key !== "user_feedback_excerpt" && key !== "corrected_output_hint") {
+            return `unknown evidence field: ${key}`;
+        }
+    }
+    if (typeof evidence.failure_summary !== "string" || !evidence.failure_summary.trim()) {
+        return "evidence.failure_summary must be a non-empty string";
+    }
+    // Deck's schema (shared PatchEvidenceContent) requires a non-empty
+    // user_feedback_excerpt on every report — recurring_blocking and blank-reason
+    // reports included. corrected_output_hint stays optional.
+    if (typeof evidence.user_feedback_excerpt !== "string" || !evidence.user_feedback_excerpt.trim()) {
+        return "evidence.user_feedback_excerpt must be a non-empty string";
+    }
+    if ("corrected_output_hint" in evidence &&
+        (typeof evidence.corrected_output_hint !== "string" || !evidence.corrected_output_hint.trim())) {
+        return "evidence.corrected_output_hint must be a non-empty string when present";
+    }
+    if ("playbook_id" in args || "ops" in args)
+        return "signal_only must not carry playbook_id or ops";
+    return null;
+}
+/**
+ * Builds the Deck-stored `signal_only` payload. Every Dealer-owned reference the
+ * inbox needs — deterministic source key, dealer issue/session refs, observed
+ * playbook use (or an explicit `no observed playbook use` line) — lives inside
+ * Deck-stored fields (`rationale` + `evidence.failure_summary`), because Deck's
+ * schema drops anything else. The source key is embedded verbatim so a repeated
+ * send after a crash between the Deck call and the local artifact write is
+ * recognizable as the same report.
+ */
+export function buildSignalOnlyArgs(candidate, opts) {
+    const baseRationale = candidate.trigger === "human_retry"
+        ? "Human correction during Dealer review — reported once as supporting evidence, without attributing the failure to any playbook."
+        : candidate.trigger === "attempts_exhausted"
+            ? "Dealer review attempts were exhausted — reported once as supporting evidence, without attributing the failure to any playbook."
+            : "A blocking review finding recurred across rounds — reported once as supporting evidence, without attributing the failure to any playbook.";
+    const sessionsLine = opts.workerSessionIds.length > 0 ? opts.workerSessionIds.join(", ") : "none";
+    const playbooksLine = opts.playbookIds.length > 0 ? opts.playbookIds.join(", ") : "no observed playbook use";
+    // Deck requires user_feedback_excerpt on every report. Prefer the human's own
+    // words; otherwise the finding's rationale/title excerpt the candidate already
+    // selected; otherwise an explicit no-feedback line (never omitted, never blank).
+    const userFeedbackExcerpt = candidate.userFeedback?.trim() ? candidate.userFeedback : NO_HUMAN_FEEDBACK_EXCERPT;
+    return {
+        kind: "signal_only",
+        rationale: `${baseRationale} ` +
+            `Dealer source ${candidate.sourceKey} | trigger ${candidate.trigger} | ` +
+            `dealer issue ${opts.issueId} | worker sessions ${sessionsLine}.`,
+        evidence: {
+            failure_summary: `${candidate.failure}\n\n` +
+                `Dealer issue: ${opts.issueId}\n` +
+                `Worker sessions: ${sessionsLine}\n` +
+                `Playbooks observed in use: ${playbooksLine}\n` +
+                `Source key: ${candidate.sourceKey}`,
+            user_feedback_excerpt: userFeedbackExcerpt,
+        },
+    };
+}
+/** Deterministic source key — the cross-restart idempotency identity of one report. */
+export function signalSourceKey(issueId, trigger, key) {
+    return `dealer:${issueId}:${trigger}:${key}`;
+}
+function humanRetryCandidates(issueId, alreadyReferencedActionIds) {
+    const candidates = [];
+    for (const action of listHumanActionsForIssue(issueId)) {
+        if (action.status !== "resolved")
+            continue;
+        // One action produces at most one signal, whichever trigger claims it first — a
+        // meaningful failure/correction appears once in Deck's feedback inbox, never once
+        // per trigger that describes the same human decision.
+        if (alreadyReferencedActionIds.has(action.id))
+            continue;
+        const choice = resolutionChoice(action.resolutionJson);
+        if (!choice)
+            continue;
+        if (!CORRECTION_CHOICES[action.actionType]?.includes(choice))
+            continue;
+        const failureParts = [
+            `Human ${choice} on ${action.actionType} (action ${action.id}, resolved by ${action.resolvedBy ?? "unknown"}).`,
+        ];
+        const reason = excerpt(action.reason);
+        if (reason)
+            failureParts.push(`Stated reason: ${reason}`);
+        const question = excerpt(action.question);
+        if (question)
+            failureParts.push(`Asked: ${question}`);
+        candidates.push({
+            trigger: "human_retry",
+            sourceKey: signalSourceKey(issueId, "human_retry", action.id),
+            humanActionId: action.id,
+            failure: failureParts.join(" "),
+            userFeedback: reason,
+        });
+    }
+    return candidates;
+}
+function attemptsExhaustedCandidates(issueId, alreadyReferencedActionIds) {
+    const candidates = [];
+    for (const action of listHumanActionsForIssue(issueId)) {
+        if (action.actionType !== "attempts_exhausted")
+            continue;
+        // A resolved attempts_exhausted:retry is already reported as a human_retry above —
+        // one action produces at most one signal, whichever trigger claims it first.
+        if (alreadyReferencedActionIds.has(action.id))
+            continue;
+        const choice = action.status === "resolved" ? resolutionChoice(action.resolutionJson) : null;
+        candidates.push({
+            trigger: "attempts_exhausted",
+            sourceKey: signalSourceKey(issueId, "attempts_exhausted", action.id),
+            humanActionId: action.id,
+            failure: `Review attempts were exhausted (action ${action.id}, ` +
+                `${action.status === "resolved" ? `human chose ${choice ?? "unknown"}` : "awaiting human decision"}). ` +
+                `Stated reason: ${excerpt(action.reason) ?? "(none recorded)"}`,
+            userFeedback: excerpt(action.reason),
+        });
+    }
+    return candidates;
+}
+function recurringBlockingCandidate(issueId) {
+    const recurring = listFindingsForIssue(issueId).filter((f) => f.status === "recurring" && f.severity === "blocking");
+    if (recurring.length === 0)
+        return null;
+    const lines = recurring.map((f) => `- ${f.fingerprint} (rounds ${f.firstRound}–${f.lastRound}): ${excerpt(f.title, 200) ?? "(untitled)"}`);
+    // No human stated this failure — the closest thing to a feedback excerpt is the
+    // recurring finding's own rationale/title. When even that is blank the builder
+    // falls back to the explicit no-feedback line (Deck still requires the field).
+    const findingFeedback = recurring
+        .map((f) => excerpt(f.rationale) ?? excerpt(f.title, 200))
+        .find((text) => text !== null) ?? null;
+    return {
+        trigger: "recurring_blocking",
+        sourceKey: signalSourceKey(issueId, "recurring_blocking", "issue"),
+        humanActionId: null,
+        failure: `${recurring.length} blocking finding(s) recurred across review rounds:\n${lines.join("\n")}`,
+        userFeedback: findingFeedback,
+    };
+}
+function existingSignalKeys(issueId) {
+    const sentKeys = new Set();
+    const pendingKeys = new Set();
+    const actionIds = new Set();
+    for (const artifact of listArtifactsForIssueByKind(issueId, DECK_FEEDBACK_SIGNAL_KIND)) {
+        try {
+            const content = JSON.parse(artifact.contentJson ?? "{}");
+            if (typeof content.sourceKey === "string") {
+                // Pre-intent rows (written before the pending/sent split) carry
+                // status "sent" or no status at all — both count as delivered.
+                if (content.status === "pending" || content.status === "sending") {
+                    pendingKeys.add(content.sourceKey);
+                }
+                else {
+                    sentKeys.add(content.sourceKey);
+                    // Only a delivered report claims its human action. A pending intent
+                    // reserves the source key (no second pending row) but must not
+                    // suppress the candidate — otherwise the retry the intent exists to
+                    // enable would never be generated.
+                    if (typeof content.humanActionId === "string")
+                        actionIds.add(content.humanActionId);
+                }
+            }
+        }
+        catch {
+            // malformed content — nothing to dedupe on its account
+        }
+    }
+    return { sentKeys, pendingKeys, actionIds };
+}
+function recordSignalIntent(issueId, candidate, opts) {
+    createIssueArtifact({
+        issueId,
+        kind: DECK_FEEDBACK_SIGNAL_KIND,
+        author: "system",
+        content: {
+            sourceKey: candidate.sourceKey,
+            trigger: candidate.trigger,
+            humanActionId: candidate.humanActionId,
+            signalId: null,
+            deckId: opts.deckId,
+            workerSessionIds: opts.workerSessionIds,
+            playbookIds: opts.playbookIds,
+            observedPlaybookUse: opts.playbookIds.length > 0 ? "observed" : "none",
+            failure: candidate.failure,
+            status: "pending",
+        },
+    });
+}
+function recordStatus(issueId, content) {
+    createIssueArtifact({ issueId, kind: "reflect_status", author: "system", content });
+}
+/**
+ * Sends one idempotent `signal_only` Deck report per failure/correction trigger found
+ * in the issue's durable state. Never throws and never changes the issue outcome: a
+ * Deck outage (or malformed response) records a visible, retryable `reflect_status`
+ * and preserves whatever state the issue already reached.
+ *
+ * A clean run — no human correction, no attempts exhaustion, no recurring blocking
+ * finding — sends nothing: receipts alone are the record.
+ */
+export async function reportDeckFailureSignals(issueId, deps = defaultDeps) {
+    const issue = getIssue(issueId);
+    if (!issue)
+        return { sent: [], skipped: [], error: "unknown issue" };
+    const { sentKeys, pendingKeys, actionIds: signalledActions } = existingSignalKeys(issueId);
+    const recurring = recurringBlockingCandidate(issueId);
+    const allCandidates = [
+        ...humanRetryCandidates(issueId, signalledActions),
+        ...attemptsExhaustedCandidates(issueId, signalledActions),
+        ...(recurring ? [recurring] : []),
+    ];
+    const candidates = allCandidates.filter((c) => !sentKeys.has(c.sourceKey));
+    const skipped = allCandidates.filter((c) => sentKeys.has(c.sourceKey)).map((c) => c.sourceKey);
+    if (candidates.length === 0)
+        return { sent: [], skipped };
+    // Supporting evidence is actual use only: the union of collected receipts. No receipt
+    // means the report says `no observed playbook use` — never legacy Agent configuration.
+    const playbookIds = [];
+    const seen = new Set();
+    for (const artifact of listArtifactsForIssueByKind(issueId, PLAYBOOK_USE_RECEIPT_KIND)) {
+        const receipt = parseReceiptContent(artifact.contentJson);
+        if (receipt?.status !== "collected")
+            continue;
+        for (const id of receipt.playbookIds) {
+            if (!seen.has(id)) {
+                seen.add(id);
+                playbookIds.push(id);
+            }
+        }
+    }
+    const workerSessionIds = listWorkerSessionsForIssue(issueId)
+        .filter((s) => TERMINAL_SESSION.has(s.status))
+        .map((s) => s.id);
+    // The deck the sessions actually ran with (frozen snapshots) — no deck, no send.
+    const deckId = [...listWorkerSessionsForIssue(issueId)]
+        .reverse()
+        .map(sessionDeckId)
+        .find((id) => id !== null) ?? null;
+    if (!deckId) {
+        recordStatus(issueId, {
+            status: "skipped",
+            reason: "no deck in worker session snapshots — failure signals have nowhere to go",
+            pendingSignals: candidates.map((c) => c.sourceKey),
+        });
+        return { sent: [], skipped, error: "no deck in worker session snapshots" };
+    }
+    const healthy = await deps.checkHealth().catch(() => false);
+    if (!healthy) {
+        recordStatus(issueId, {
+            status: "failed",
+            reason: "Agent Deck offline — failure signals resume the next time issue reflection runs (a later completion trigger or an explicit reflection retry)",
+            pendingSignals: candidates.map((c) => c.sourceKey),
+        });
+        return { sent: [], skipped, error: "Agent Deck offline" };
+    }
+    const sent = [];
+    let anyFailed = false;
+    for (const candidate of candidates) {
+        // signal_only: a feedback record, never a playbook edit. Only Deck-schema
+        // fields are sent (kind/rationale/evidence) — no playbook_id (no single
+        // attribution), no ops (no synthesized edit), and no Dealer-only top-level
+        // keys. All Dealer refs (source key, issue/session refs, observed playbook
+        // use) live inside the Deck-stored rationale/evidence fields.
+        //
+        // Crash safety: the pending intent row is written BEFORE the Deck call, so a
+        // restart between the call and the sent row reconciles to the same source
+        // key (embedded verbatim in the Deck-stored payload) instead of minting a
+        // second report. A pending row without a sent row is retried, never duplicated
+        // locally; a repeated send after that window carries the identical key.
+        //
+        // Residual risk: if the process dies after Deck ACCEPTED the report but before
+        // the sent row is written, the retry re-sends and Deck stores a duplicate —
+        // Deck does not dedupe on the embedded source key. True exactly-once needs a
+        // Deck-side idempotency key on propose_playbook_patch (follow-up against Deck,
+        // not Dealer); until then the identical key lets a human recognize the repeat
+        // as the same report.
+        if (!pendingKeys.has(candidate.sourceKey)) {
+            recordSignalIntent(issueId, candidate, { deckId, workerSessionIds, playbookIds });
+            pendingKeys.add(candidate.sourceKey);
+        }
+        const signalArgs = buildSignalOnlyArgs(candidate, { issueId, workerSessionIds, playbookIds });
+        const schemaError = validateSignalOnlyArgs(signalArgs);
+        if (schemaError) {
+            anyFailed = true;
+            recordStatus(issueId, {
+                status: "failed",
+                sourceKey: candidate.sourceKey,
+                error: `signal payload rejected by Dealer-side Deck schema check: ${schemaError}`,
+            });
+            continue;
+        }
+        const proposed = await deps.callTool({
+            deckId,
+            toolName: "propose_playbook_patch",
+            arguments: signalArgs,
+            timeoutMs: SIGNAL_TOOL_TIMEOUT_MS,
+        });
+        if (!proposed.ok) {
+            anyFailed = true;
+            recordStatus(issueId, {
+                status: "failed",
+                sourceKey: candidate.sourceKey,
+                error: proposed.reason,
+            });
+            continue;
+        }
+        const signalId = typeof proposed.data?.id === "string" ? proposed.data.id : null;
+        createIssueArtifact({
+            issueId,
+            kind: DECK_FEEDBACK_SIGNAL_KIND,
+            author: "system",
+            content: {
+                sourceKey: candidate.sourceKey,
+                trigger: candidate.trigger,
+                humanActionId: candidate.humanActionId,
+                signalId,
+                deckId,
+                workerSessionIds,
+                playbookIds,
+                observedPlaybookUse: playbookIds.length > 0 ? "observed" : "none",
+                failure: candidate.failure,
+                status: "sent",
+            },
+        });
+        sent.push({ sourceKey: candidate.sourceKey, trigger: candidate.trigger, signalId });
+    }
+    recordStatus(issueId, {
+        status: anyFailed ? (sent.length > 0 ? "partial" : "failed") : "completed",
+        signalsSent: sent.map((s) => s.sourceKey),
+        playbookCount: playbookIds.length,
+    });
+    return { sent, skipped };
+}