agent-dealer 1.2.13 → 1.2.14

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

@@ -20,6 +20,7 @@ import { getAgent } from "../repository/agents.js";
 import { githubIssuesSync, invalidateMuseHealthCache } from "../adapters/agent-health.js";
 import { recordMuseCapabilityOverride } from "../adapters/muse-capability.js";
 import { createIssueArtifact, latestIssueArtifact } from "../repository/artifacts.js";
+import { listSourceAttachments } from "../repository/source-attachments.js";
 import { cancelWorkItem, enqueueWorkItem, finishWorkItem, getWorkItem, getWorkItemByIdempotencyKey, listWorkItemsForIssue, } from "../repository/work-items.js";
 import { completeSession, getActiveWorkerSessionForIssue, getWorkerSession, listWorkerSessionsForIssue } from "../repository/worker-sessions.js";
 import { killRunProcess } from "../runners/spawn-cli.js";
@@ -31,6 +32,7 @@ import { routeDeveloperOutcome, routeReviewerOutcome, } from "./routing.js";
 import { projectDeveloperRoute, projectReviewerRoute } from "./projection.js";
 import { MERGE_CONFLICT_FILES_EVIDENCE_KEY, MERGE_FAILURE_EVIDENCE_KEY, MERGE_FAILURE_RESPONSE_OPTIONS, PUSH_DIVERGENCE_EVIDENCE_KEY, PUSH_DIVERGENCE_RESPONSE_OPTIONS, WORKTREE_BLOCKER_EVIDENCE_KEY, normalizeResolutionNote, parseHumanResolution, resolveHumanActionOutcome, } from "./human-resolution.js";
 import { AUTO_MERGE_INTENT, finalizeAutoMerge } from "./auto-merge.js";
+import { triggerLinearPostMerge } from "./linear-merge-verify.js";
 import { conflictRepairSpent, queueConflictRepairRound } from "./merge-conflict-sync.js";
 import { OPERATOR_VERIFICATION_ARTIFACT_KIND, OPERATOR_VERIFICATION_RESPONSE_OPTIONS, } from "./operator-criteria.js";
 import { externalMergeStateForIssue } from "./external-merge.js";
@@ -60,7 +62,17 @@ export function getTaskSnapshot(issue) {
             // Snapshots frozen before NOT-306 carry no contract — derive it from the
             // frozen source description so old workflows still render what they ran.
             if (parsed.executionContract === undefined) {
-                return { ...parsed, executionContract: tryCompileContract(parsed.description) };
+                return {
+                    ...parsed,
+                    executionContract: tryCompileContract(parsed.description),
+                    // NOT-364: pre-attachment snapshots carry no manifest — empty, not live
+                    // rows, so a running workflow never gains inputs mid-flight.
+                    sourceAttachments: parsed.sourceAttachments ?? [],
+                };
+            }
+            // NOT-364: pre-attachment snapshots carry no manifest — same rule.
+            if (parsed.sourceAttachments === undefined) {
+                return { ...parsed, sourceAttachments: [] };
             }
             return parsed;
         }
@@ -76,6 +88,9 @@ export function getTaskSnapshot(issue) {
         baseBranch: issue.baseBranch,
         workflowVersion: WORKFLOW_VERSION,
         executionContract: tryCompileContract(issue.description),
+        // Live-field fallback is pre-freeze by definition (no workflow owns a
+        // snapshot yet) — current rows are exactly what the freeze would capture.
+        sourceAttachments: listSourceAttachments(issue.id),
     };
 }
 /**
@@ -243,6 +258,9 @@ function freezeTaskSnapshot(issue) {
             baseBranch: issue.baseBranch,
             workflowVersion: WORKFLOW_VERSION,
             executionContract: tryCompileContract(issue.description),
+            // NOT-364: freeze the attachment manifest with the text — later Linear
+            // edits cannot silently change the inputs repair rounds see.
+            sourceAttachments: listSourceAttachments(issue.id),
         },
     });
 }
@@ -2043,8 +2061,19 @@ export async function resolveHumanActionAndAdvanceAsync(actionId, resolvedBy, ch
         externalMergeState,
         note: opts?.note,
     });
-    if (!result.ok || !result.pendingMerge)
+    if (!result.ok || !result.pendingMerge) {
+        // NOT-362: the sync core may have landed a terminal merge without going
+        // through finalize (external-merge close-as-done) — confirm the Linear
+        // source post-check. Fire-and-forget: never blocks the response, and the
+        // check itself never touches the issue's status. Non-Linear issues return
+        // unchecked with no network call.
+        if (result.ok && result.issueStatus === "done") {
+            const doneAction = getHumanAction(actionId);
+            if (doneAction?.issueId)
+                triggerLinearPostMerge(doneAction.issueId);
+        }
         return result;
+    }
     const action = getHumanAction(actionId);
     if (!action?.issueId) {
         return { ok: false, code: 500, error: "Human action missing issue after merge park" };
@@ -2540,7 +2569,12 @@ export async function abortIssueAsync(issueId, resolvedBy, deps = defaultAbortDe
     catch {
         externalMergeState = undefined;
     }
-    return abortIssue(issueId, resolvedBy, deps, { externalMergeState });
+    const aborted = abortIssue(issueId, resolvedBy, deps, { externalMergeState });
+    // NOT-362: an abort that landed as `done` means the PR was merged outside
+    // Dealer — same post-check as every other terminal merged transition.
+    if (aborted.ok && aborted.issueStatus === "done")
+        triggerLinearPostMerge(issueId);
+    return aborted;
 }
 /**
  * NOT-196 pre-read for the async close entry: returns a PR merge state only when this

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

@@ -19,6 +19,7 @@ import path from "node:path";
 import { parsePhaseBudget, parseProfileSnapshot, roleCeiling } from "@agent-dealer/shared";
 import { CONFLICTING_FILES_MAX, runMergeConflictSync } from "./merge-conflict-sync.js";
 import { getTaskSnapshot } from "./commands.js";
+import { materializeSourceAttachments, SourceAttachmentError, } from "./source-attachments.js";
 import { extractOperatorCriteria } from "./operator-criteria.js";
 import { buildDeveloperPrompt } from "./prompts.js";
 import { guidanceForNextSession } from "./guidance.js";
@@ -912,13 +913,16 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
         intent,
         payload,
     });
-    // issue.branch is only ever written on a verified clean_handoff (design: it's ground
-    // truth, not agent self-report), so a first-round attempt after an earlier retryable
+    // issue.branch is ground truth for the branch NAME (written on a verified
+    // clean_handoff, or seeded from Linear's branchName at intake — NOT-362), but
+    // not for the branch's EXISTENCE: a seeded branch has no local ref and the
+    // remote never saw it. A first-round attempt after an earlier retryable
     // failure in the SAME round (no_pr/session_failed/timed_out/checks_failed all remove
     // their worktree but leave the local branch ref behind) would otherwise re-run
     // `git worktree add -b <same name>` and fail with "branch already exists" — a review
     // round reproduced this directly. Check the branch itself, not just issue.branch, and
-    // reuse it (preserving whatever local commits it already carries) when it's there.
+    // reuse it (preserving whatever local commits it already carries) when it's there
+    // (resolveDeveloperWorktree cuts a nonexistent reuse-path branch fresh from base).
     const branchName = issue.branch ?? `issue-${issue.id}`;
     let repoPath;
     let desiredWorktreePath;
@@ -942,7 +946,11 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
     catch (err) {
         return { kind: "adapter_failure", reason: `repository checkout failed: ${String(err)}` };
     }
-    const reuseBranch = issue.branch != null || (await branchExists(repoPath, branchName));
+    // NOT-362: a seeded issue.branch names a branch that exists nowhere yet — the
+    // local ref is the only existence signal honest enough for reuse accounting
+    // below (a seeded name must not count as "prior commits to reuse").
+    const localBranchPreexists = await branchExists(repoPath, branchName);
+    const reuseBranch = issue.branch != null || localBranchPreexists;
     let worktreePath;
     // NOT-172: whether the retry-resolution reused an existing checkout (source for
     // the retry-reuse record emitted once the retry begins).
@@ -1066,6 +1074,25 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
     milestone("worktree.ready", `Developer · worktree ready (round ${round})`, {
         worktreePath: shortWorktreePath(worktreePath),
     });
+    // NOT-364: re-materialize the FROZEN attachment manifest's durable files
+    // under `.agent-dealer-inputs/linear/` for every attempt — first, repair,
+    // and retry rounds all see the same bytes at the same prompt-listed,
+    // git-ignored path. A missing or corrupt blob fails closed (no spawn on
+    // partial inputs) instead of running the session without its ticket files.
+    try {
+        const materialized = materializeSourceAttachments(worktreePath, taskSnapshot.sourceAttachments);
+        if (materialized.length > 0) {
+            milestone("inputs.materialized", `Developer · source attachments ready (round ${round})`, {
+                files: materialized.map((m) => m.relativePath),
+            });
+        }
+    }
+    catch (err) {
+        const reason = err instanceof SourceAttachmentError
+            ? err.message
+            : `source attachment materialization failed: ${String(err)}`;
+        return { kind: "adapter_failure", reason };
+    }
     // NOT-172: capture the worktree HEAD as this session's input-SHA baseline before
     // the agent spawns — developer work items are never enqueued with an input SHA,
     // so without this the sampler's HEAD diff (and the session_end fallback) have
@@ -1264,7 +1291,7 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
                         worktreePath,
                         baseRef: `origin/${baseBranch}`,
                     }).catch(() => null);
-                    if ((ahead !== null && ahead > 0) || (ahead === null && issue.branch != null)) {
+                    if ((ahead !== null && ahead > 0) || (ahead === null && localBranchPreexists)) {
                         reuseKinds.push("commit");
                     }
                 }
@@ -1498,7 +1525,7 @@ export async function runDeveloperEffect(ctx, deps = defaultDeps) {
                     worktreePath,
                     baseRef: `origin/${baseBranch}`,
                 }).catch(() => null);
-                if ((endAhead !== null && endAhead > 0) || (endAhead === null && issue.branch != null)) {
+                if ((endAhead !== null && endAhead > 0) || (endAhead === null && localBranchPreexists)) {
                     emitCheckpointObserved({
                         issueId: issue.id,
                         workflowInstanceId: instance.id,

package/bundle/server/dist/coordinator/linear-merge-verify.js

@@ -0,0 +1,382 @@
+// packages/server/src/coordinator/linear-merge-verify.ts
+//
+// NOT-362: when Dealer merges an approved PR for a `source = linear` issue, the
+// Linear issue it came from must either advance, or a human must be told it did
+// not. Linear's GitHub integration normally drives that (attaching the PR and
+// moving the issue out of Backlog), but on repositories the integration does
+// not cover nothing fires and Dealer recorded nothing — the issue sat stale
+// with zero evidence anywhere.
+//
+// The check runs after the coordinator's terminal merged transition
+// (finalizeAutoMerge's `done`, plus the external-merge close-as-`done` paths):
+// re-read the Linear issue over a bounded retry window and treat it as advanced
+// when its state type left `backlog`/`unstarted` or its attachments contain the
+// merged PR URL. Every outcome is recorded as an issue artifact (both
+// directions — a stale source issue appears in history instead of being
+// inferred from absence). A stale issue with `linear.syncEnabled` gets exactly
+// one fallback write to the team's completed state plus the Dealer comment,
+// reusing linear-sync's writer; when the fallback is unavailable or fails, one
+// open `policy_escalation` names the Linear identifier, the merged PR URL and
+// the observed state (idempotent re-raise by stable request id).
+//
+// Safety: this module never touches the Dealer issue's status, never blocks
+// the merge, and never throws — every `done` landing triggers it fire-and-forget
+// (`triggerLinearPostMerge`), so the bounded retry window never holds the merge
+// caller. The raised action is a notice, not a gate: it resolves through a
+// dedicated acknowledge/re-check resolution (no active workflow to advance on a
+// `done` issue), and advancing the Linear issue by hand then re-checking clears
+// it when the re-read verifies.
+import { createIssueArtifact } from "../repository/artifacts.js";
+import { listArtifactsForIssueByKind } from "../repository/artifacts-for-issue.js";
+import { createHumanAction, findOpenHumanActionByRequestId, getHumanAction, resolveHumanAction, } from "../repository/human-actions.js";
+import { getIssue } from "../repository/issues.js";
+import { getLinearIntakeConfig } from "../repository/intake-settings.js";
+import { linearGraphqlRequest } from "../adapters/linear-graphql.js";
+import { buildDoneComment, dealerIssueUrl, postLinearIssueComment, resolveCompletedStateId, setLinearIssueState, } from "../adapters/linear-sync.js";
+/** Issue-artifact kind for every post-merge verification outcome. */
+export const LINEAR_MERGE_VERIFY_ARTIFACT_KIND = "linear_merge_verify";
+/** Stable request id for the stale-source human action — re-runs dedupe onto it. */
+export function linearMergeStaleRequestId(issueId) {
+    return `linear-merge-stale:${issueId}`;
+}
+/** Bounded retry window so the GitHub integration has time to act. */
+export const LINEAR_POST_MERGE_READ_DELAYS_MS = [0, 10_000, 30_000];
+async function defaultPostMergeReader(externalId) {
+    const data = (await linearGraphqlRequest({
+        operation: "readLinearPostMergeState",
+        query: `query PostMergeState($id: String!) {
+      issue(id: $id) {
+        identifier
+        url
+        state { name type }
+        team { id }
+        attachments(first: 50) { nodes { url } }
+      }
+    }`,
+        variables: { id: externalId },
+        timeoutMs: 15_000,
+    }));
+    if (!data.issue)
+        throw new Error(`Linear issue not found: ${externalId}`);
+    const urls = (data.issue.attachments?.nodes ?? [])
+        .map((n) => n?.url)
+        .filter((u) => typeof u === "string" && u.length > 0);
+    return {
+        identifier: data.issue.identifier ?? null,
+        linearUrl: data.issue.url ?? null,
+        stateName: data.issue.state?.name ?? null,
+        stateType: data.issue.state?.type ?? null,
+        teamId: data.issue.team?.id ?? null,
+        attachmentUrls: urls,
+        prAttached: false,
+        advancedViaState: false,
+    };
+}
+let postMergeReader = defaultPostMergeReader;
+/** Test hook — inject a fake Linear reader so tests never hit the network. */
+export function setPostMergeReaderForTests(fn) {
+    postMergeReader = fn ?? defaultPostMergeReader;
+}
+let readDelaysMs = LINEAR_POST_MERGE_READ_DELAYS_MS;
+/** Test hook — shrink the retry window (e.g. `[0, 0]`) so tests stay fast. */
+export function setPostMergeDelaysForTests(delays) {
+    readDelaysMs = delays ?? LINEAR_POST_MERGE_READ_DELAYS_MS;
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        // Unref'd: this check is fire-and-forget off every `done` landing and must
+        // never hold the merge caller — or a test runner's process — open on its own.
+        const timer = setTimeout(resolve, ms);
+        if (typeof timer.unref === "function")
+            timer.unref();
+    });
+}
+/** State types that still mean "the integration has not acted". */
+function isStaleStateType(stateType) {
+    const t = (stateType ?? "").toLowerCase();
+    return t === "" || t === "backlog" || t === "unstarted";
+}
+function fallbackAlreadyWritten(issueId) {
+    for (const artifact of listArtifactsForIssueByKind(issueId, LINEAR_MERGE_VERIFY_ARTIFACT_KIND)) {
+        try {
+            if (JSON.parse(artifact.contentJson ?? "null")?.fallback === "written") {
+                return true;
+            }
+        }
+        catch {
+            // A row this module did not write — ignore, never treat as a guard.
+        }
+    }
+    return false;
+}
+function dismissOpenStaleAction(issueId, note) {
+    const open = findOpenHumanActionByRequestId(issueId, "policy_escalation", linearMergeStaleRequestId(issueId));
+    if (open) {
+        try {
+            resolveHumanAction(open.id, "system", { choice: "dismissed", note });
+        }
+        catch {
+            // Resolving the notice must never fail the verification.
+        }
+    }
+}
+function staleReasonText(opts) {
+    const observed = opts.unreadable
+        ? `could not be re-read (${opts.unreadable})`
+        : `still ${opts.stateName ?? "unknown state"}${opts.stateType ? ` (${opts.stateType})` : ""}`;
+    return (`Linear ${opts.identifier} ${observed} after the merged PR ${opts.prUrl ?? "(no PR URL recorded)"}. ` +
+        `Linear's GitHub integration did not advance it, so advance it by hand. ` +
+        `The Dealer issue itself is done and stays done — this action is a notice, not a gate.`);
+}
+/**
+ * Re-read the Linear source issue after a merged terminal transition and either
+ * confirm it advanced, advance it once via the conditional fallback, or raise
+ * the one human action. Records an artifact in every direction. Never throws
+ * and never touches the Dealer issue's status.
+ */
+// NOT-362 round 3: per-issue in-flight guard. The stale fallback records
+// `fallback: "written"` only via the artifact written *after* the Linear state
+// + comment mutations, so two overlapping checks for one issue (finalize's
+// done-already branch re-entered by recovery, or abort/resolve racing
+// finalize) could both observe stale and each write. Concurrent checks for one
+// issue join the in-flight run instead of running twice; sequential re-runs
+// still execute and stay single-write via the artifact guard.
+const verifyInflightByIssue = new Map();
+export async function verifyLinearPostMerge(issueId) {
+    const inflight = verifyInflightByIssue.get(issueId);
+    if (inflight)
+        return inflight;
+    const pending = verifyLinearPostMergeInner(issueId).then((result) => result, (err) => ({ checked: false, reason: err instanceof Error ? err.message : String(err) }));
+    verifyInflightByIssue.set(issueId, pending);
+    try {
+        return await pending;
+    }
+    finally {
+        if (verifyInflightByIssue.get(issueId) === pending)
+            verifyInflightByIssue.delete(issueId);
+    }
+}
+async function verifyLinearPostMergeInner(issueId) {
+    const issue = getIssue(issueId);
+    if (!issue || issue.source !== "linear" || !issue.externalId) {
+        return { checked: false, reason: "not a Linear-sourced issue" };
+    }
+    const linearId = issue.externalId;
+    const prUrl = issue.prUrl;
+    let observation = null;
+    let readError = null;
+    for (let attempt = 0; attempt < readDelaysMs.length; attempt += 1) {
+        if (readDelaysMs[attempt] > 0)
+            await sleep(readDelaysMs[attempt]);
+        try {
+            const read = await postMergeReader(linearId);
+            const advancedViaState = !isStaleStateType(read.stateType);
+            const prAttached = prUrl != null && read.attachmentUrls.includes(prUrl);
+            observation = { ...read, prAttached, advancedViaState };
+            if (advancedViaState || prAttached)
+                break;
+        }
+        catch (err) {
+            readError = err instanceof Error ? err.message : String(err);
+        }
+    }
+    const identifier = observation?.identifier ?? issue.externalLabel ?? linearId;
+    const reads = observation
+        ? {
+            stateName: observation.stateName,
+            stateType: observation.stateType,
+            prAttached: observation.prAttached,
+        }
+        : { error: readError };
+    if (observation && (observation.advancedViaState || observation.prAttached)) {
+        const advancedVia = observation.advancedViaState ? "state" : "attachment";
+        createIssueArtifact({
+            issueId,
+            kind: LINEAR_MERGE_VERIFY_ARTIFACT_KIND,
+            author: "system",
+            content: {
+                check: "post_merge",
+                linearId,
+                identifier,
+                prUrl,
+                reads,
+                outcome: "advanced",
+                advancedVia,
+            },
+        });
+        dismissOpenStaleAction(issueId, `Linear ${identifier} advanced (${advancedVia}); notice cleared.`);
+        return { checked: true, advanced: true, advancedVia };
+    }
+    // Stale (or unreadable): the fallback fires only after the integration has
+    // demonstrably not acted — an unreadable issue never reaches the writer.
+    const syncEnabled = getLinearIntakeConfig().syncEnabled && Boolean(process.env.LINEAR_API_KEY);
+    const teamId = observation?.teamId ?? null;
+    let fallback = "skipped";
+    if (syncEnabled && teamId && !fallbackAlreadyWritten(issueId)) {
+        try {
+            const stateId = await resolveCompletedStateId(teamId);
+            if (!stateId) {
+                fallback = "unavailable:no-completed-state";
+            }
+            else {
+                // State first, comment second: a rejected state write then posts no
+                // comment, so re-runs do not stack "marked done" comments that were
+                // never true. (A comment failure after a successful state write still
+                // records `failed:…` and the re-run rewrites the same state —
+                // idempotent — before retrying the comment.)
+                const label = issue.externalLabel ?? identifier;
+                await setLinearIssueState(linearId, stateId);
+                await postLinearIssueComment(linearId, buildDoneComment(label, dealerIssueUrl(issueId), "View issue"));
+                fallback = "written";
+                dismissOpenStaleAction(issueId, `Dealer fallback advanced Linear ${identifier}; notice cleared.`);
+            }
+        }
+        catch (err) {
+            fallback = `failed:${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    else if (fallbackAlreadyWritten(issueId)) {
+        fallback = "already_recorded";
+    }
+    else if (!syncEnabled) {
+        fallback = "unavailable:sync-disabled";
+    }
+    else if (!teamId) {
+        fallback = "unavailable:no-team";
+    }
+    let actionId = null;
+    if (fallback !== "written" && fallback !== "already_recorded") {
+        const reason = staleReasonText({
+            identifier,
+            prUrl,
+            stateName: observation?.stateName ?? null,
+            stateType: observation?.stateType ?? null,
+            unreadable: observation ? null : readError,
+        });
+        const requestId = linearMergeStaleRequestId(issueId);
+        const open = findOpenHumanActionByRequestId(issueId, "policy_escalation", requestId);
+        if (open) {
+            actionId = open.id;
+        }
+        else {
+            const action = createHumanAction({
+                issueId,
+                workflowInstanceId: null,
+                actionType: "policy_escalation",
+                reason,
+                question: reason,
+                evidence: {
+                    linearMergeStale: true,
+                    linearId,
+                    identifier,
+                    linearUrl: observation?.linearUrl ?? null,
+                    prUrl,
+                    observedStateName: observation?.stateName ?? null,
+                    observedStateType: observation?.stateType ?? null,
+                    fallback,
+                },
+                // Acknowledge/re-check only: the Dealer issue is already `done`, so
+                // there is no workflow to resume — resolve through
+                // resolveLinearMergeStaleAction, never the workflow state machine.
+                responseOptions: [
+                    { choice: "acknowledge", label: "Acknowledge" },
+                    { choice: "recheck", label: "Re-check Linear" },
+                ],
+                requestId,
+            });
+            actionId = action.id;
+        }
+    }
+    createIssueArtifact({
+        issueId,
+        kind: LINEAR_MERGE_VERIFY_ARTIFACT_KIND,
+        author: "system",
+        content: {
+            check: "post_merge",
+            linearId,
+            identifier,
+            prUrl,
+            reads,
+            outcome: "stale",
+            fallback,
+            actionId,
+        },
+    });
+    return { checked: true, advanced: false, fallback, actionId };
+}
+/**
+ * Fire-and-forget entry for every `done` landing (merge finalize, external-merge
+ * close, abort resolutions) — never throws, never holds the caller. The check's
+ * bounded retry window (tens of seconds plus read timeouts) must not hold the
+ * merge caller: finalizeAutoMerge is awaited while holding the reviewer session
+ * and slot, and the final_review:merge HTTP path must not wait on it either.
+ */
+const postMergeInflight = new Set();
+export function triggerLinearPostMerge(issueId) {
+    const pending = verifyLinearPostMerge(issueId).catch((err) => {
+        console.error(`[linear-merge-verify] post-merge check for ${issueId} failed:`, err);
+        return { checked: false, reason: "trigger caught" };
+    });
+    postMergeInflight.add(pending);
+    void pending.finally(() => {
+        postMergeInflight.delete(pending);
+    });
+}
+/**
+ * Test hook — await every post-merge check a test triggered through the
+ * fire-and-forget entry, so assertions on artifacts/actions do not race it.
+ * Loops until none remain (a re-check resolution can trigger another).
+ */
+export async function drainLinearPostMergeForTests() {
+    for (let guard = 0; guard < 25 && postMergeInflight.size > 0; guard += 1) {
+        await Promise.all([...postMergeInflight]);
+    }
+}
+/** True when the action is this module's stale-source notice (any status). */
+export function isLinearMergeStaleAction(action) {
+    if (action.actionType !== "policy_escalation" || !action.evidenceJson)
+        return false;
+    try {
+        return JSON.parse(action.evidenceJson).linearMergeStale === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Dedicated resolution for the stale-source notice. The Dealer issue is already
+ * `done` — there is no active workflow for the generic resolver to advance, so
+ * this resolves the notice directly (the reflection_interaction_required
+ * precedent in routes/human-actions.ts):
+ * - `acknowledge` (plus legacy `close`/`dismiss` labels): close the notice.
+ * - `recheck`: close the notice and re-run the post-merge verification
+ *   fire-and-forget — a human who advanced the Linear issue by hand gets a
+ *   fresh verdict (and a verification artifact) instead of a stuck notice. A
+ *   still-stale issue raises one new action only when the fallback did not
+ *   already write; an already-recorded fallback stays quiet.
+ */
+export function resolveLinearMergeStaleAction(actionId, resolvedBy, choice) {
+    const action = getHumanAction(actionId);
+    if (!action)
+        return { ok: false, code: 404, error: "Human action not found" };
+    if (!isLinearMergeStaleAction(action)) {
+        return { ok: false, code: 400, error: `Action ${actionId} is not a Linear post-merge notice` };
+    }
+    if (!action.issueId)
+        return { ok: false, code: 500, error: "Human action has no issue" };
+    if (action.status !== "open")
+        return { ok: false, code: 409, error: "Human action already resolved" };
+    if (choice !== "acknowledge" && choice !== "dismiss" && choice !== "close" && choice !== "recheck") {
+        return {
+            ok: false,
+            code: 400,
+            error: `Invalid choice "${choice}" for Linear post-merge notice (acknowledge or recheck)`,
+        };
+    }
+    resolveHumanAction(actionId, resolvedBy, { choice });
+    const rechecked = choice === "recheck";
+    if (rechecked)
+        triggerLinearPostMerge(action.issueId);
+    const issue = getIssue(action.issueId);
+    return { ok: true, issueStatus: issue?.status ?? "done", rechecked };
+}