comfyui-mcp 0.49.2 → 0.49.4

package/dist/orchestrator/panel-agent.js

@@ -24,6 +24,34 @@ export { fetchSupportedModels, fetchSupportedCommands };
 function msgOf(err) {
     return errorText(err);
 }
+/**
+ * Opening clause naming WHICH run a completion belongs to (#468).
+ *
+ * The whole point is that the agent must never read a completion as the answer
+ * to its own `panel_run` unless the orchestrator PROVED it by exact prompt id.
+ * So:
+ *  • matched      → say so, and name the id.
+ *  • foreign      → real run, real id, but not one this session queued. Say
+ *                   UNDETERMINED and forbid treating it as the awaited render.
+ *  • unidentified → no id at all. Same, plus how to find out for certain.
+ * An event with no correlation field (a legacy/simulated frame) gets the old
+ * neutral wording — unchanged behavior.
+ */
+function runIdentityPreamble(ev) {
+    const pid = typeof ev.prompt_id === "string" && ev.prompt_id.trim() ? ev.prompt_id.trim() : null;
+    switch (ev.run_correlation) {
+        case "matched":
+            return `This is the run YOU queued with panel_run (prompt ${pid}). `;
+        case "foreign":
+            return (`This run (prompt ${pid}) does NOT match any run you queued with panel_run — its origin is UNDETERMINED. ` +
+                `Do NOT treat it as the render you are waiting on; if you are still waiting on your own run, verify it with get_history before acting. `);
+        case "unidentified":
+            return (`The panel reported NO prompt id for this run, so it CANNOT be correlated to the render you queued — its origin is UNDETERMINED. ` +
+                `Do NOT assume it is your run; verify yours with get_history before acting on it. `);
+        default:
+            return pid ? `(prompt ${pid}) ` : ``;
+    }
+}
 /** Idle window for the per-turn freeze watchdog: if a turn that's in flight
  *  receives NO events at all for this long, treat it as stalled. Generous (legit
  *  tool work is slow but still streams progress) and overridable for tests via
@@ -77,6 +105,24 @@ export class PanelAgent {
      *  on a clean turn result (nothing to re-queue) and on stall/rewind (abandoned on
      *  purpose). Null whenever no turn is in flight. */
     inFlight = null;
+    /** Run-completion journal tokens carried by the turn currently in flight
+     *  (#468). Acked when that turn's `result` lands; handed back to the journal
+     *  when the turn is abandoned (stall watchdog) or the agent is stopped. */
+    turnEventTokens = [];
+    /** The turn marker `turnEventTokens` belongs to (#468). A completion is acked
+     *  only by the result of the turn that CARRIED it — see the `result` case. */
+    turnEventTokensMarker = 0;
+    /**
+     * Has the backend produced ANY event for the turn currently in flight?
+     *
+     * This is what "carried" means for #468's bounded replay: the token is
+     * attached at DISPATCH, but the backend may not have consumed the yielded turn
+     * yet (Claude awaits output-image resolution before submitting it). Aborting
+     * in that window — a rewind, or the watchdog on a turn that produced nothing —
+     * means the completion never reached the model, so it must NOT count toward
+     * the settle bound. One event is proof of receipt. Reset at each dispatch.
+     */
+    turnProducedEvents = false;
     /** True while a turn is in flight (working→done). Lets the manager defer a
      *  session-restarting option change (effort) until the turn finishes, instead
      *  of interrupting and silently dropping the in-flight reply. */
@@ -98,15 +144,16 @@ export class PanelAgent {
     // app-server) would otherwise leave the panel "working" forever. This is an
     // IDLE timer (reset on every received event), NOT a hard turn cap: legit tool
     // work is slow but still streams progress/tool events, so only a TRUE stall
-    // (no events at all for the whole window) trips it. On trip we surface a clear
-    // terminal error (the turn's ONE failure report) and route through the guarded
-    // interrupt() flow: the aborted turn's terminal result — or the bounded
-    // interrupt-release fallback if no result ever arrives — advances the turn-gate
-    // at the genuine turn end, so the next queued batch never runs ahead of the
-    // wedged turn settling (#728).
+    // (no events at all for the whole window) trips it. A capable provider first
+    // receives an explicit harness-stall notice, never a synthetic user rejection.
+    // If that recovery is unavailable or remains silent for another window, the
+    // guarded interrupt() flow provides the existing bounded gate-release fallback
+    // so the next queued batch never runs ahead of a wedged turn settling (#728).
     idleTimer = null;
     /** Guards against a trip firing twice / racing a real result for one turn. */
     idleTripped = false;
+    /** A provider-native, non-user-cancel recovery is attempted at most once per turn. */
+    stallRecoverySteered = false;
     /** Tool calls started (item/started) but not yet ended (item/completed). A tool
      *  in flight is legitimate work even when the app-server sends nothing, so the
      *  watchdog defers while this is > 0 — the fix for the #307-review finding that
@@ -225,11 +272,38 @@ export class PanelAgent {
     send(text, opts) {
         if (opts?.title)
             this.title = opts.title;
-        this.queue.push({ text, images: opts?.images, mid: opts?.mid });
+        this.queue.push({
+            text,
+            images: opts?.images,
+            mid: opts?.mid,
+            ...(opts?.completionOnly ? { completionOnly: true } : {}),
+            ...(opts?.eventTokens?.length ? { eventTokens: [...opts.eventTokens] } : {}),
+        });
         const wake = this.waiting;
         this.waiting = null;
         wake?.();
     }
+    /** Hand a set of run-completion journal tokens back as UNDELIVERED (#468), so
+     *  the journal re-arms them for replay instead of letting them die with this
+     *  agent / this abandoned turn. Never throws into the caller's path. */
+    /** Capture-and-clear the in-flight turn in one step. Also the read that
+     *  survives control-flow narrowing (channel() assigns `inFlight` from another
+     *  function, so a direct read after a `= null` looks like `never` to TS). */
+    takeInFlight() {
+        const turn = this.inFlight;
+        this.inFlight = null;
+        return turn;
+    }
+    releaseEventTokens(tokens, opts = {}) {
+        if (!tokens?.length)
+            return;
+        try {
+            this.deps.onEventUndelivered?.(this.tabId, [...tokens], opts);
+        }
+        catch (err) {
+            logger.warn(`[panel-agent ${this.short()}] releasing completion tokens: ${msgOf(err)}`);
+        }
+    }
     /** Rewind the CONVERSATION: fork the session at `anchor` (an assistant UUID
      *  reported via onTurnAnchor) so everything after it is dropped from the agent's
      *  memory, then restart. `anchor` null forks to a fresh session. The edited
@@ -242,12 +316,42 @@ export class PanelAgent {
         // A rewind deliberately DROPS everything after the anchor (the edited message
         // arrives separately), so the interrupted turn's text must NOT be re-queued.
         this.inFlight = null;
+        // The dropped turn may have been carrying a run completion — that is news,
+        // not conversation, so hand it back for replay rather than rewinding it away
+        // (#468).
+        const rewoundTokens = this.turnEventTokens;
+        this.turnEventTokens = [];
+        // CARRIED only if the backend actually RECEIVED this turn. A rewind during
+        // the pre-submission window (Claude resolving output images) aborts a turn
+        // the model never saw, and counting that toward the settle bound could
+        // retire a completion nobody read.
+        this.releaseEventTokens(rewoundTokens, { carried: this.turnProducedEvents });
         // Break the current stream so start()'s loop re-enters and forks.
         void this.backend.interrupt().catch(() => { });
         const wake = this.waiting;
         this.waiting = null;
         wake?.();
     }
+    /**
+     * Pull a still-queued INJECTED COMPLETION back off the queue by its journal
+     * token (#468). Returns true only if it was found and removed — false once the
+     * turn carrying it has started, where the text is already in the model's
+     * context and cannot be recalled.
+     *
+     * Needed because the event's wording is materialized when it is queued: if the
+     * journal later has to WEAKEN that completion's correlation (a prompt id
+     * reused, a conversation replaced), the already-queued copy would still claim
+     * "this is the run YOU queued". Revoking lets the journal re-deliver the
+     * downgraded, honest version instead. Only `completionOnly` items are eligible,
+     * so no user message is ever removed.
+     */
+    revokeEvent(token) {
+        const i = this.queue.findIndex((item) => item.completionOnly && item.eventTokens?.includes(token));
+        if (i < 0)
+            return false;
+        this.queue.splice(i, 1);
+        return true;
+    }
     /** Drop a still-queued message (the user cancelled/edited it before the agent
      *  got to it). Returns true if it was found and removed; false if it was
      *  already dequeued (the turn started — too late to cancel). */
@@ -277,7 +381,14 @@ export class PanelAgent {
      * reached the agent." Only meaningful when a session is live (the manager only
      * calls this for an existing agent, so we never spawn one just for an event).
      */
-    injectEvent(ev) {
+    injectEvent(ev, opts) {
+        // A closed agent's queue is never drained again, so accepting an event here
+        // would silently swallow it (#468). REFUSE — and deliberately do NOT hand the
+        // token back through onEventUndelivered: the caller is the journal's own
+        // flush, which keeps a refused entry pending from the `false` return. Calling
+        // back would recurse (release → flush → inject → release → …).
+        if (this.closed)
+            return false;
         let text = null;
         let images;
         if (ev.kind === "executed") {
@@ -289,6 +400,23 @@ export class PanelAgent {
             const note = typeof ev.note === "string" && ev.note.trim() ? ev.note.trim() : null;
             text =
                 `[panel event] ` +
+                    // #468 — a completion that was journaled and re-delivered says so, so the
+                    // agent reads it as "this landed late", not as a second render.
+                    (ev.replayed
+                        ? `(RE-DELIVERED — this completion could not be handed to you when it arrived.) `
+                        : ``) +
+                    // An eviction dropped older completions for this tab — say so rather than
+                    // let them disappear (#468). The agent must treat those runs as unknown.
+                    (typeof ev.dropped_completions === "number" && ev.dropped_completions > 0
+                        ? `⚠️ ${ev.dropped_completions} EARLIER completion(s) for this tab could not be delivered and were dropped — treat the outcome of those runs as UNDETERMINED and check get_history if you were waiting on one. `
+                        : ``) +
+                    // An id-less completion whose content matches one already reported. We
+                    // will NOT swallow it (identical content is not proof of identity, and a
+                    // swallowed render is a silent loss), so hand the judgement to the agent.
+                    (ev.possible_repeat
+                        ? `⚠️ POSSIBLE REPEAT: a completion with identical outputs was already reported to you recently, and this one carries no prompt id to tell them apart. It may be the same event re-sent, or a second render that produced identical filenames — do NOT count it twice without checking (get_history). `
+                        : ``) +
+                    runIdentityPreamble(ev) +
                     (note
                         ? `${note} `
                         : `A run on the user's canvas just finished and produced ${imgs.length} output image(s): ${names}. `) +
@@ -322,29 +450,42 @@ export class PanelAgent {
             // wakes the agent ONCE, not per file.
             const dl = (ev.downloads ?? []).filter((d) => d && d.name);
             if (dl.length === 0)
-                return;
+                return false;
             const done = dl.filter((d) => d.status === "done").map((d) => d.name);
             const failed = dl.filter((d) => d.status !== "done").map((d) => d.name);
             const parts = [];
+            // This event is raised by the TRANSFER, which finishes BEFORE the placement
+            // check against the connected ComfyUI does. Saying "finished" here would be a
+            // bare success claim during that window (#369) — a model can land in an
+            // install the running server never reads — so the wording says only what the
+            // event actually proves and points at download_status for the verdict.
             if (done.length)
-                parts.push(`finished: ${done.join(", ")}`);
+                parts.push(`transfer completed: ${done.join(", ")}`);
             if (failed.length)
                 parts.push(`FAILED: ${failed.join(", ")}`);
             const plural = dl.length > 1 ? "these downloads" : "it";
             text =
                 `[panel event] Model download ${parts.join("; ")}. ` +
-                    `If you were waiting on ${plural} to continue a task, proceed now — ` +
-                    `call download_status for the exact landed path(s)${failed.length ? " or the error detail" : ""}. ` +
+                    `The bytes finished transferring; whether the connected ComfyUI can actually LOAD ` +
+                    `${plural} is confirmed separately. If you were waiting on ${plural} to continue a task, ` +
+                    `call download_status FIRST for the verified path and placement verdict${failed.length ? " or the error detail" : ""} — ` +
+                    `do not tell the user a model is ready until download_status confirms it. ` +
                     `Otherwise reply with ONE short sentence acknowledging it and no tool calls.`;
         }
         if (!text)
-            return;
+            return false;
         this.busy = true;
         this.deps.onTurn?.(this.tabId, "working"); // event triggers a turn — show working
-        this.queue.push({ text, images });
+        this.queue.push({
+            text,
+            images,
+            completionOnly: true, // the whole item IS the event — safe to drop wholesale
+            ...(opts?.eventToken ? { eventTokens: [opts.eventToken] } : {}),
+        });
         const wake = this.waiting;
         this.waiting = null;
         wake?.();
+        return true;
     }
     /** Push a ComfyUI EXECUTION error into the session with urgency — the "hey,
      *  look at me" path. Renders fail ASYNC (minutes after the agent queued them via
@@ -418,7 +559,9 @@ export class PanelAgent {
     }
     /** Remove and return any unsent queued messages — so a session restart can hand
      *  them to the replacement agent instead of dropping them. Items keep their
-     *  panel `mid`, so re-delivery still flips the right bubble on dequeue (seen). */
+     *  panel `mid`, so re-delivery still flips the right bubble on dequeue (seen),
+     *  AND their run-completion tokens (#468), so a carried-over completion is
+     *  acked by the replacement agent rather than replayed as a duplicate. */
     takePending() {
         const items = this.queue;
         this.queue = [];
@@ -453,10 +596,27 @@ export class PanelAgent {
         // the user wants BOTH the interrupted message and the new one answered. A plain
         // Stop / Ctrl+C / Esc (requeueInFlight=false) must NOT re-queue, or it would
         // silently re-run the turn the user just stopped (double tool actions).
+        // #468 — the interrupted turn's run-completion tokens travel with its text.
+        // Re-queued: they ride the re-queued item and are acked when THAT turn ends.
+        // Dropped (plain Stop): hand them back so the completion is replayed rather
+        // than dying with the turn the user cancelled.
+        const interruptedTokens = this.turnEventTokens;
+        this.turnEventTokens = [];
         if (interrupted && opts.requeueInFlight) {
             // Front of the queue: the interrupted work is addressed before whatever the
-            // user sends next (which is appended after this interrupt is handled).
-            this.queue.unshift({ text: interrupted.text, images: interrupted.images });
+            // user sends next (which is appended after this interrupt is handled). The
+            // ORIGINAL items go back (not one merged item) — the next splice re-joins
+            // them into the same text, while an injected completion stays a separate
+            // `completionOnly` item that a later detach can remove cleanly (#468).
+            this.queue.unshift(...interrupted.items);
+        }
+        else {
+            // UNCARRIED on purpose. This is a plain Stop — a deliberate human act that
+            // does not repeat on its own, so it cannot form the automatic loop the
+            // bound exists to break; settling a completion on the user's third Stop
+            // would be a surprise, not a safeguard. (The stall watchdog and rewind DO
+            // auto-repeat, so those are carried.)
+            this.releaseEventTokens(interruptedTokens);
         }
         // Track the turn this interrupt is aborting (the one holding the gate). The
         // fallback only force-releases while THIS turn is still the one parked on the
@@ -532,6 +692,16 @@ export class PanelAgent {
     async stop() {
         this.closed = true;
         this.inFlight = null; // teardown must not leave a turn that could be re-queued
+        // #468 — every run completion this agent still holds (queued-but-unread, or
+        // carried by the turn we're tearing down) goes BACK to the journal. A tab
+        // that is genuinely gone has its entries dropped explicitly by the
+        // orchestrator (forget); everything else is replayed into the replacement
+        // agent. Done before the awaits below so a concurrent spawn can pick them up.
+        const orphanedTokens = [...this.queue.flatMap((it) => it.eventTokens ?? []), ...this.turnEventTokens];
+        this.turnEventTokens = [];
+        for (const item of this.queue)
+            delete item.eventTokens;
+        this.releaseEventTokens(orphanedTokens);
         this.clearIdleWatchdog(); // don't let a turn watchdog fire after teardown
         const wake = this.waiting;
         this.waiting = null;
@@ -625,11 +795,35 @@ export class PanelAgent {
                 return;
             // Remember the in-flight turn's user text so an interrupt mid-reply can
             // re-queue it (send-now must address BOTH the interrupted and new message).
-            this.inFlight = { text, ...(images.length ? { images } : {}) };
+            // #468 — the run-completion tokens this batch carries. They ride with the
+            // in-flight capture so a crash-requeue keeps them attached, and are ACKED
+            // only when this turn's `result` lands (proof the agent actually read the
+            // completion), not merely because it was spliced off the queue.
+            const carriedTokens = batch.flatMap((it) => it.eventTokens ?? []);
+            // SAFETY NET: the previous turn ended without acking (no result at all, or
+            // only a traceless one the ack gate rejected). Its completions are about to
+            // be overwritten here, so hand them back first — the flush re-queues them
+            // into a LATER turn rather than letting them vanish at the handover.
+            if (this.turnEventTokens.length) {
+                const stale = this.turnEventTokens;
+                this.turnEventTokens = [];
+                // CARRIED only if that turn produced events (proof the backend received
+                // it) — the same rule as the result and abandon paths.
+                this.releaseEventTokens(stale, { carried: this.turnProducedEvents });
+            }
+            this.turnEventTokens = carriedTokens;
+            this.inFlight = {
+                text,
+                ...(images.length ? { images } : {}),
+                ...(carriedTokens.length ? { eventTokens: carriedTokens } : {}),
+                items: batch,
+            };
             this.yieldedTurns += 1; // this batch is turn N
             // Mirror the backend's turn-marker mint: the Nth turn yielded here is the
             // Nth turn the backend reads — its events carry marker N (#728 r3).
             this.currentTurnMarker += 1;
+            this.turnEventTokensMarker = this.currentTurnMarker;
+            this.turnProducedEvents = false; // no proof of receipt yet (#468)
             // Mark the turn in flight AT DISPATCH (not on the first event). Without this
             // the watchdog's `busy` guard would be false for the exact zero-event freeze
             // it's meant to catch, so onTurnStalled() would no-op. (handleEvent's later
@@ -705,6 +899,9 @@ export class PanelAgent {
             this.turnWaiter = null;
             this.currentTurnMarker = 0;
             this.abandonedTurnMarker = 0;
+            // The #468 ack gate mirrors the marker reset: no marker minted by the dead
+            // run can satisfy the new one's first turn.
+            this.turnEventTokensMarker = 0;
             // Drop the prior session's last assistant UUID so a fork can't report a
             // stale (pre-fork) anchor for the first turn of the new session.
             this.lastAssistantUuid = null;
@@ -766,10 +963,17 @@ export class PanelAgent {
                 // in-flight message so the restarted/fresh session actually re-runs it.
                 // Idempotent enough: a duplicate render beats a lost request, and the
                 // quickRestarts give-up guard still bounds a message that crash-loops.
-                if (this.inFlight) {
-                    const interrupted = this.inFlight;
-                    this.inFlight = null;
-                    this.queue.unshift(interrupted);
+                // Read through takeInFlight(): channel() assigns this.inFlight from
+                // another function, which control-flow analysis can't see, so a direct
+                // read here is narrowed to `null` by the `= null` at the top of the loop.
+                const interrupted = this.takeInFlight();
+                if (interrupted) {
+                    // Its run-completion tokens (#468) ride the re-queued items, so they
+                    // are acked when the RE-RUN turn ends — not left dangling on a turn
+                    // whose session died. The ORIGINAL items go back, so a completion
+                    // stays its own `completionOnly` item (never welded into user text).
+                    this.turnEventTokens = [];
+                    this.queue.unshift(...interrupted.items);
                     logger.warn(`[panel-agent ${this.short()}] crash mid-turn — re-queued the interrupted message so it isn't lost`);
                 }
             }
@@ -780,6 +984,18 @@ export class PanelAgent {
             // first turn — gate run-ahead). The gate counters are reset next iteration.
             this.clearIdleWatchdog();
             this.clearInterruptReleaseFallback();
+            // A turn that never produced a `result` (the session just ended) never
+            // acked its run completions. Hand them back so the restarted session
+            // replays them instead of the completion dying with the dead session
+            // (#468). No-op after a clean result or the crash re-queue above.
+            const strandedTokens = this.turnEventTokens;
+            const strandedWereReceived = this.turnProducedEvents;
+            this.turnEventTokens = [];
+            // Same rule again: a session that DID receive this turn (it emitted marked
+            // events) and then died without a terminal result is a bounded replay
+            // cycle — a session that kept dropping before receiving it is not, and
+            // must never count toward the settle bound.
+            this.releaseEventTokens(strandedTokens, { carried: strandedWereReceived });
             if (this.closed)
                 break;
             // Session ended on its own — bound rapid failure loops so a persistently
@@ -823,20 +1039,101 @@ export class PanelAgent {
             this.idleTimer = null;
         }
         this.idleTripped = false;
+        this.stallRecoverySteered = false;
         // The turn ended — drop any tool-busy state so a start whose matching end was
         // never seen (errored/interrupted turn) can't defer the NEXT turn's watchdog.
         this.openToolCalls = 0;
         this.toolBusySince = 0;
     }
+    /** The exact notice injected into capable providers when a harness watchdog
+     *  sees a frozen turn. It must never be conflated with a user cancellation. */
+    static STALL_RECOVERY_NOTICE = "[harness stall notice] This turn stalled with no activity and was detected by the harness. " +
+        "The user did NOT reject or cancel this tool call. Do not tell the user that they stopped it. " +
+        "Inspect side effects if the call may have started; otherwise it is safe to retry the same call.";
+    /** Finish the legacy interruption path after no native stall recovery is
+     *  available. This retains the existing gate/restart safety for old providers. */
+    finishStalledTurn(alreadyReported) {
+        this.busy = false;
+        // The stalled turn is abandoned — don't re-queue its text (a wedged message
+        // could otherwise loop on every interrupt, and it may already have performed
+        // tool side effects).
+        this.inFlight = null;
+        // …but a run COMPLETION the abandoned turn was carrying is not the agent's
+        // work, it's news the agent still needs (#468). Hand its tokens back so the
+        // journal replays them into the next turn instead of losing them with the
+        // turn we just wrote off.
+        //
+        // THIS is the abandon path. The #587 steer path deliberately does NOT come
+        // here: there the turn stays live and keeps carrying its tokens, so releasing
+        // them would replay a completion the live turn still holds.
+        //
+        // CARRIED only if the backend produced at least one event for this turn —
+        // i.e. it demonstrably received the completion and then went silent. A turn
+        // that produced NOTHING never reached the model, so it must not count toward
+        // the settle bound (that freeze is bounded by the self-restart give-up
+        // machinery instead, which tears the agent down rather than quietly retiring
+        // a completion nobody saw).
+        const stalledTokens = this.turnEventTokens;
+        this.turnEventTokens = [];
+        this.releaseEventTokens(stalledTokens, { carried: this.turnProducedEvents });
+        if (!alreadyReported) {
+            this.deps.onSay(this.tabId, "⚠️ The agent stopped responding (the turn stalled with no activity). I've cleared it — please try again.");
+        }
+        this.deps.onTurn?.(this.tabId, "done");
+        // Do NOT completeTurn() here: the gate must stay held until the turn genuinely
+        // ends. interrupt() arms the bounded release fallback and stops the wedged
+        // backend; the aborted turn's `result` (or that fallback) releases the next
+        // queued batch at the right moment. The self-restart loop in start() recovers
+        // the session.
+        void this.interrupt();
+    }
+    /** Attempt one provider-native recovery before the legacy interrupt path.
+     *  A steer is an explicit agent-facing harness notice, not a synthetic user
+     *  rejection. Its short re-arm preserves the ordinary bounded fallback if the
+     *  provider remains frozen after accepting it. */
+    async recoverStalledTurn(stalledMarker, alreadyReported) {
+        const recover = this.backend.recoverStalledTurn;
+        if (!recover || this.stallRecoverySteered) {
+            this.finishStalledTurn(alreadyReported);
+            return;
+        }
+        this.stallRecoverySteered = true;
+        let steered = false;
+        try {
+            steered = await recover.call(this.backend, PanelAgent.STALL_RECOVERY_NOTICE);
+        }
+        catch (err) {
+            logger.debug(`[panel-agent ${this.short()}] stalled-turn recovery: ${msgOf(err)}`);
+        }
+        // The active turn may have completed while the asynchronous steer request was
+        // in flight. Never resurrect a settled or replacement turn.
+        const stillCurrent = !this.closed &&
+            this.busy &&
+            this.currentTurnMarker === stalledMarker &&
+            this.completedTurns < this.yieldedTurns;
+        if (!steered || !stillCurrent) {
+            if (stillCurrent)
+                this.finishStalledTurn(alreadyReported);
+            return;
+        }
+        // The provider accepted the precise notice. Keep the turn authoritative and
+        // allow a second full idle window; if it remains frozen, the next watchdog
+        // trip falls through to the established bounded interrupt/restart recovery.
+        this.idleTripped = false;
+        this.bumpIdleWatchdog();
+        if (!alreadyReported) {
+            this.deps.onSay(this.tabId, "⚠️ The agent stalled with no activity. I sent it a harness-stall notice — you did NOT cancel it; it can inspect state and retry safely.");
+        }
+    }
     /** The current turn produced NO events for the whole idle window → it's frozen.
-     *  Surface a clear error (unless this turn's failure was ALREADY reported — one
-     *  report per turn), clear the "working" indicator, and interrupt via the
-     *  guarded interrupt() flow so the turn-gate opens only when the turn GENUINELY
-     *  ends (the aborted turn's terminal result, or the bounded interrupt-release
-     *  fallback if none arrives) — not synchronously here, which let the next queued
-     *  batch run before the wedged turn had settled. errorSurfaced +
-     *  interruptRequested suppress the follow-up interrupted result's "turn failed"
-     *  line (#728). Idempotent per turn via idleTripped. */
+     *  First send a capable provider an explicit non-user-cancel notice. If that
+     *  is unavailable (or it remains silent through another full window), surface
+     *  the legacy clear + use the guarded interrupt() flow so the turn-gate opens
+     *  only when the turn GENUINELY ends (the aborted turn's terminal result, or the
+     *  bounded interrupt-release fallback if none arrives) — not synchronously here,
+     *  which let the next queued batch run before the wedged turn had settled.
+     *  errorSurfaced + interruptRequested suppress the follow-up interrupted
+     *  result's "turn failed" line (#728). Idempotent per trip via idleTripped. */
     onTurnStalled() {
         if (this.closed || this.idleTripped || !this.busy)
             return;
@@ -860,23 +1157,18 @@ export class PanelAgent {
         // failure. (interrupt() also sets interruptRequested, so the result case
         // treats that result as the interrupt landing, not a new failure.)
         const alreadyReported = this.errorSurfaced;
-        logger.error(`[panel-agent ${this.short()}] turn stalled — no events for ${Math.round(TURN_IDLE_MS / 1000)}s; interrupting${alreadyReported ? " (failure already reported)" : " and surfacing error"}`);
+        const recovery = this.stallRecoverySteered || !this.backend.recoverStalledTurn
+            ? " via legacy interrupt"
+            : " with provider notice";
+        logger.error(`[panel-agent ${this.short()}] turn stalled — no events for ${Math.round(TURN_IDLE_MS / 1000)}s; recovering${recovery}${alreadyReported ? " (failure already reported)" : " and surfacing error"}`);
         this.errorSurfaced = true;
-        this.busy = false;
-        // The stalled turn is abandoned + surfaced as an error — don't re-queue its
-        // text (a wedged message could otherwise loop on every interrupt, and it may
-        // already have performed tool side effects).
-        this.inFlight = null;
-        if (!alreadyReported) {
-            this.deps.onSay(this.tabId, "⚠️ The agent stopped responding (the turn stalled with no activity). I've cleared it — please try again.");
-        }
-        this.deps.onTurn?.(this.tabId, "done");
-        // Do NOT completeTurn() here: the gate must stay held until the turn genuinely
-        // ends. interrupt() arms the bounded release fallback and stops the wedged
-        // backend; the aborted turn's `result` (or that fallback) releases the next
-        // queued batch at the right moment. The self-restart loop in start() recovers
-        // the session.
-        void this.interrupt();
+        const stalledMarker = this.currentTurnMarker;
+        // #468 note: the run-completion tokens this turn is carrying are handed back
+        // in finishStalledTurn(), NOT here. #587 introduced a path where the stall is
+        // recovered by STEERING the provider and the turn stays live — releasing the
+        // tokens on that path would replay the completion into a turn that is still
+        // holding it, i.e. a duplicate. Only the genuinely-abandoned path releases.
+        void this.recoverStalledTurn(stalledMarker, alreadyReported);
     }
     // Handle a canonical AgentEvent from the backend. This is the provider-agnostic
     // half of what used to be route(SDKMessage): all the panel orchestration (turn
@@ -904,6 +1196,21 @@ export class PanelAgent {
             logger.debug(`[panel-agent ${this.short()}] dead-lettered a straggler ${ev.type} from turn ${ev.turn} (current=${this.currentTurnMarker}, abandoned≤${this.abandonedTurnMarker})`);
             return;
         }
+        // Proof the backend RECEIVED the in-flight turn (#468). On a backend that
+        // DECLARES turn markers, only an event stamped with THIS turn counts: #728
+        // deliberately lets UNMARKED events past the dead-letter guard for gate
+        // liveness, and Claude emits an unmarked terminal for a result it cannot
+        // match to any submitted turn — a stale one of those, arriving while the new
+        // turn is still pre-submission, would otherwise "prove" a receipt that never
+        // happened and let the settle bound retire a completion nobody saw.
+        if (this.backend.capabilities.turnMarkers === true) {
+            if (typeof ev.turn === "number" && ev.turn === this.currentTurnMarker) {
+                this.turnProducedEvents = true;
+            }
+        }
+        else {
+            this.turnProducedEvents = true; // nothing to compare against
+        }
         // Any event means the turn is alive — reset the idle watchdog. The `result`
         // case below disarms it entirely (turn ended). Placed before the switch so it
         // covers every event type without per-case bumps.
@@ -1031,6 +1338,50 @@ export class PanelAgent {
                 // Turn completed → nothing to re-queue on a later interrupt. (A clean
                 // completion must NOT have its message re-queued.)
                 this.inFlight = null;
+                // #468 — the turn that CARRIED the run completion(s) has ended, so they
+                // demonstrably reached the model's context. Ack them: the journal drops
+                // them and settles their run tickets. This is the ONLY ack point; every
+                // other exit from a turn hands the tokens back for replay.
+                //
+                // ACK GATE: only THIS turn's own result may ack. On a backend that
+                // DECLARES turn markers, an UNMARKED result is a traceless straggler
+                // (Claude emits one for a result it cannot match to a submitted turn)
+                // that the #728 dead-letter deliberately lets through for gate liveness
+                // — it must not also retire a completion the CURRENT turn is carrying,
+                // or a turn that then stalls would have nothing left to hand back.
+                //
+                // The capability is DECLARED, never inferred from "have I seen a marker
+                // yet": a zero-output turn's straggler arrives BEFORE the replacement
+                // turn stamps anything, so an observation-based gate is unsound in
+                // exactly the window it exists to protect. A backend that declares no
+                // markers keeps the pre-#468 behavior (nothing to compare against).
+                //
+                // Not ackable → hand the tokens BACK right here, so a completion can
+                // never dangle on a turn that has already ended. The journal re-queues
+                // it into a later turn: a duplicate at worst, never a loss.
+                if (this.turnEventTokens.length) {
+                    const carried = this.turnEventTokens;
+                    this.turnEventTokens = [];
+                    const ackable = this.backend.capabilities.turnMarkers !== true ||
+                        (typeof ev.turn === "number" && ev.turn === this.turnEventTokensMarker);
+                    if (ackable) {
+                        try {
+                            this.deps.onEventDelivered?.(this.tabId, carried);
+                        }
+                        catch (err) {
+                            logger.warn(`[panel-agent ${this.short()}] acking completion tokens: ${msgOf(err)}`);
+                        }
+                    }
+                    else {
+                        logger.warn(`[panel-agent ${this.short()}] an unmarked result cannot ack turn ${this.turnEventTokensMarker}'s run completion(s) — handing ${carried.length} back for replay (#468)`);
+                        // CARRIED only with PROOF the backend received this turn — the same
+                        // rule as every other release. An UNMARKED result bypasses the #728
+                        // dead-letter gate, so it may be a straggler from an abandoned turn
+                        // arriving while this one is still pre-submission; counting it would
+                        // let three such stragglers settle a completion nobody ever saw.
+                        this.releaseEventTokens(carried, { carried: this.turnProducedEvents });
+                    }
+                }
                 // Turn ended cleanly → disarm the freeze watchdog. (If it already tripped,
                 // completeTurn() is a capped no-op, so the gate can't double-advance.)
                 this.clearIdleWatchdog();
@@ -1175,6 +1526,8 @@ export class PanelAgentManager {
             onThinking: this.opts.onThinking,
             onToolCall: this.opts.onToolCall,
             onSeen: this.opts.onSeen,
+            onEventDelivered: this.opts.onEventDelivered,
+            onEventUndelivered: this.opts.onEventUndelivered,
             panelServer: this.opts.makePanelServer?.(tabId),
             pluginPath: this.opts.pluginPath,
         }, backend);
@@ -1337,8 +1690,19 @@ export class PanelAgentManager {
         const resume = oldAgent.sessionId ?? undefined;
         const pending = oldAgent.takePending();
         const fresh = this.spawn(tabId, resume); // new agent owns the tab now
-        for (const item of pending)
-            fresh.send(item.text, { images: item.images, mid: item.mid });
+        for (const item of pending) {
+            fresh.send(item.text, {
+                images: item.images,
+                mid: item.mid,
+                // #468 — carry the run-completion tokens over so the replacement agent
+                // acks the completion it inherited (rather than the journal replaying it
+                // as a second copy), AND the completionOnly marker with them: an item
+                // that loses it can no longer be removed from held mail later, so its
+                // text would outlive its token.
+                ...(item.completionOnly ? { completionOnly: true } : {}),
+                ...(item.eventTokens?.length ? { eventTokens: item.eventTokens } : {}),
+            });
+        }
         if (nudge)
             fresh.send(nudge);
         void oldAgent.stop(); // retire the old one; it's no longer mapped
@@ -1349,13 +1713,23 @@ export class PanelAgentManager {
         return this.agents.get(tabId)?.lastStatus ?? null;
     }
     /** Feed a ComfyUI execution event to an EXISTING agent (no-op if none — we
-     *  never spawn an agent just to react to an event). Returns whether delivered. */
-    injectEvent(tabId, ev) {
+     *  never spawn an agent just to react to an event). Returns whether the agent
+     *  TOOK it onto its queue — not that it was read; a run completion carrying an
+     *  `eventToken` is only acked when the turn that delivered it ends (#468). */
+    injectEvent(tabId, ev, opts) {
         const agent = this.agents.get(tabId);
         if (!agent || agent.isStopped)
             return false; // best-effort; don't enqueue into a closed agent
-        agent.injectEvent(ev);
-        return true;
+        return agent.injectEvent(ev, opts);
+    }
+    /** Pull a still-queued injected completion back off a tab's agent by journal
+     *  token (#468), so a weakened correlation can be re-delivered honestly.
+     *  False when there is no such agent or the turn carrying it already started. */
+    revokeEvent(tabId, token) {
+        const agent = this.agents.get(tabId);
+        if (!agent || agent.isStopped)
+            return false;
+        return agent.revokeEvent(token);
     }
     /** Push a ComfyUI execution error to a tab's agent — interrupt the live turn
      *  and front-queue the error so the agent stops and addresses it. */
@@ -1378,10 +1752,29 @@ export class PanelAgentManager {
         const held = this.heldMessages.get(tabId);
         if (held?.length) {
             this.heldMessages.delete(tabId);
-            for (const item of held)
-                agent.send(item.text, { images: item.images, mid: item.mid });
+            for (const item of held) {
+                agent.send(item.text, {
+                    images: item.images,
+                    mid: item.mid,
+                    // #468 — preserve the completionOnly marker across EVERY re-delivery.
+                    // A second consecutive failed start would otherwise return this item to
+                    // held mail unmarked, making its text un-removable by a later detach.
+                    ...(item.completionOnly ? { completionOnly: true } : {}),
+                    ...(item.eventTokens?.length ? { eventTokens: item.eventTokens } : {}),
+                });
+            }
             logger.info(`[panel-orchestrator] tab ${tabId.slice(0, 8)} re-delivering ${held.length} message(s) held from the previous failed start`);
         }
+        // #468 — a fresh agent is mapped and can take mail: replay any run
+        // completions journaled while this key had no live agent. Fired BEFORE
+        // start() so the replay is queued ahead of the session coming up, and after
+        // held mail so ordering stays chronological.
+        try {
+            this.opts.onAgentReady?.(tabId);
+        }
+        catch (err) {
+            logger.warn(`[panel-orchestrator] tab ${tabId.slice(0, 8)} completion replay: ${msgOf(err)}`);
+        }
         // start() now SELF-RESTARTS internally on session-end, so it only settles on
         // an intentional stop() or after it gives up (repeated immediate failures),
         // or it rejects on a hard start failure. In the give-up / reject cases, drop
@@ -1416,11 +1809,7 @@ export class PanelAgentManager {
                 // agent's queue — including the one that triggered it. Capture them
                 // (BEFORE stop(), which closes the agent) for re-delivery by the next
                 // spawn on this key, so nothing dies silently with the doomed agent.
-                const orphaned = agent.takePending();
-                if (orphaned.length) {
-                    this.heldMessages.set(key, [...(this.heldMessages.get(key) ?? []), ...orphaned]);
-                    logger.warn(`[panel-orchestrator] tab ${key.slice(0, 8)} holding ${orphaned.length} undelivered message(s) — re-delivered on the next successful start`);
-                }
+                this.holdOrphanedMail(key, agent.takePending(), "a failed start");
                 // PER-TAB degradation (issue #250): a hard start failure is almost
                 // always a tab-local configuration error — an invalid API key (the
                 // endpoint 401s in prepare()), an unreachable base URL, a missing CLI
@@ -1443,8 +1832,17 @@ export class PanelAgentManager {
                 void agent.stop().catch(() => { });
             }
             else if (gaveUp) {
-                // The bounded self-restart loop gave up — the session keeps dropping. Same
-                // fatal signal: let the orchestrator self-exit + respawn.
+                // The bounded self-restart loop gave up — the session keeps dropping.
+                // Same treatment as the hard-start failure above for the agent's QUEUE
+                // (#468): its still-unread messages — a run completion among them — were
+                // dying here. `settle` only unmapped the agent, so a completion sitting
+                // in its queue stayed `handed_off` in the journal, a state deliverPending
+                // skips: no replay, ever. Capture the queue into held mail (its tokens
+                // ride along, so a respawn re-delivers exactly once) and stop() the agent
+                // so anything left over is handed back.
+                this.holdOrphanedMail(key, agent.takePending(), "an agent that gave up");
+                void agent.stop().catch(() => { });
+                // Fatal signal: let the orchestrator self-exit + respawn.
                 this.opts.onAgentFatal?.(key, "agent session kept dropping (self-restart gave up)");
             }
         };
@@ -1656,13 +2054,126 @@ export class PanelAgentManager {
         }
         return { model: this.modelFor(tabId), effort: this.effortFor(tabId), restarted, deferred };
     }
+    /**
+     * THE SINGLE TEARDOWN SEAM for unbinding a key's agent (#468). Every path that
+     * stops an agent must go through here, so a future third teardown can't
+     * silently re-open the hole that `retire()` had: it preserved `heldMessages`
+     * without releasing the run-completion tokens parked in them, leaving those
+     * entries `handed_off` — a state `deliverPending()` skips — with no agent left
+     * to consume them and no disclosure.
+     *
+     * Held mail is DETACHED from its completion tokens either way: the message
+     * text keeps whatever preservation semantics the caller wants, while ownership
+     * of the completion returns to the journal, which replays it to whatever agent
+     * serves this panel tab next (a different provider's key included — the
+     * journal is keyed by panel tab).
+     *
+     * `dropHeldMail` distinguishes the two callers: reset() is an explicit fresh
+     * start and discards the mail; retire() preserves it for when the workflow is
+     * reopened. Returns the unbound agent (if any) for the caller to stop.
+     */
+    unbindAgent(key, opts) {
+        const agent = this.agents.get(key);
+        this.agents.delete(key);
+        this.detachHeldCompletions(key, opts.reason);
+        if (opts.dropHeldMail)
+            this.heldMessages.delete(key);
+        return agent;
+    }
+    /**
+     * Hand a key's HELD-MAIL run completions back to the journal (#468).
+     *
+     * The completion must leave held mail ENTIRELY, not just lose its token.
+     * Stripping the token alone left the event's TEXT sitting in preserved mail:
+     * `retire()` keeps that mail, so switching Claude→Codex handed the journal's
+     * token to Codex (delivered, correctly) and then switching BACK to Claude
+     * re-delivered the retained text as an ordinary user message — no token, no
+     * `possible_repeat` flag, indistinguishable from a real second completion.
+     * Preservation semantics are for the user's own mail; a completion whose token
+     * has moved on is not that.
+     *
+     * Dropping the item is safe precisely because an injected event is always its
+     * own `completionOnly` item — a re-queued turn restores the original items
+     * rather than one merged blob — so no user message is ever removed with it.
+     *
+     * Every release here is UNCARRIED (the default): nobody read these, so they
+     * must not count toward the journal's bounded replay cycle. Only a turn that
+     * ran and ended is `carried`.
+     */
+    /**
+     * Park a dead agent's unsent mail for the next spawn — but NEVER its injected
+     * completions (#468).
+     *
+     * Held mail is unbounded and the journal's revocation can only reach a LIVE
+     * agent's queue, so a completion parked here is a copy the journal can no
+     * longer count or cap: each failed-start/retry cycle would strand another
+     * capped batch in held mail, and the whole pile eventually drains into one
+     * turn. Completions are revocable by design and the JOURNAL is their record —
+     * so they are handed back instead, and replayed (bounded) into whatever agent
+     * comes next. Only the user's own messages are held.
+     */
+    holdOrphanedMail(key, orphaned, reason) {
+        if (!orphaned.length)
+            return;
+        const completions = orphaned.filter((it) => it.completionOnly);
+        const mail = orphaned.filter((it) => !it.completionOnly);
+        if (mail.length) {
+            this.heldMessages.set(key, [...(this.heldMessages.get(key) ?? []), ...mail]);
+            logger.warn(`[panel-orchestrator] tab ${key.slice(0, 8)} holding ${mail.length} undelivered message(s) from ${reason} — re-delivered on the next successful start`);
+        }
+        const tokens = completions.flatMap((it) => it.eventTokens ?? []);
+        if (!tokens.length)
+            return;
+        logger.warn(`[panel-orchestrator] tab ${key.slice(0, 8)}: ${tokens.length} run completion(s) were queued on ${reason} — returned to the journal (never held) for bounded replay (#468)`);
+        try {
+            this.opts.onEventUndelivered?.(key, tokens);
+        }
+        catch (err) {
+            logger.warn(`[panel-orchestrator] tab ${key.slice(0, 8)} returning orphaned completions: ${msgOf(err)}`);
+        }
+    }
+    detachHeldCompletions(key, reason) {
+        const held = this.heldMessages.get(key);
+        if (!held?.length)
+            return;
+        const tokens = [];
+        const keep = [];
+        for (const item of held) {
+            if (!item.eventTokens?.length) {
+                keep.push(item);
+                continue;
+            }
+            tokens.push(...item.eventTokens);
+            delete item.eventTokens; // the journal owns it now — never ack it twice
+            if (item.completionOnly)
+                continue; // …and the event's text goes with it
+            // Defensive: a token on a non-completionOnly item would mean the item
+            // carries user text too, so it must survive — but then its embedded event
+            // text could be re-delivered untracked. Construction prevents this; log
+            // loudly if it ever happens rather than silently allowing a phantom.
+            logger.error(`[panel-orchestrator] tab ${key.slice(0, 8)} ${reason}: held item carried a completion token but is not completionOnly — keeping its text (#468)`);
+            keep.push(item);
+        }
+        if (keep.length !== held.length)
+            this.heldMessages.set(key, keep);
+        if (!tokens.length)
+            return;
+        logger.warn(`[panel-orchestrator] tab ${key.slice(0, 8)} ${reason}: ${tokens.length} run completion(s) were parked in held mail — returned to the journal for replay (#468)`);
+        try {
+            this.opts.onEventUndelivered?.(key, tokens);
+        }
+        catch (err) {
+            logger.warn(`[panel-orchestrator] tab ${key.slice(0, 8)} releasing held completion tokens: ${msgOf(err)}`);
+        }
+    }
     /** Forget a tab's agent so the next message starts a brand-new session. The
      *  map mutation is synchronous and the old agent is stopped fire-and-forget,
      *  so the caller (e.g. resume_session) can set a new pendingResume right after
      *  without a concurrent send() spawning a non-resumed agent in an await gap. */
     reset(tabId) {
-        const agent = this.agents.get(tabId);
-        this.agents.delete(tabId);
+        // Unbind through the SHARED teardown seam (#468) — it is what guarantees a
+        // run completion parked in held mail is handed back rather than discarded.
+        const agent = this.unbindAgent(tabId, { dropHeldMail: true, reason: "reset" });
         this.pendingResume.delete(tabId);
         // Forget the durable session too — a NEW chat must start fresh, so the disk
         // fallback in send() can't resurrect the conversation the user just cleared.
@@ -1671,7 +2182,6 @@ export class PanelAgentManager {
         this.opts.sessionStore?.clear(tabId);
         this.pendingEffortRestart.delete(tabId); // a reset supersedes any deferred restart
         this.pendingMcpRestart.delete(tabId);
-        this.heldMessages.delete(tabId); // a reset is an explicit fresh start — drop held mail
         // Drop this key's picker override so a provider switch (which reset()s the old
         // key) can't carry the old provider's model/effort into the new backend's spawn.
         this.modelByKey.delete(tabId);
@@ -1687,12 +2197,18 @@ export class PanelAgentManager {
      *  chat — this preserves sessionStore/pendingResume/held mail, so the retired
      *  workflow resumes exactly where it left off when reopened, while its now-stopped
      *  agent can no longer push frames that the bridge migration alias would leak into
-     *  the newly-targeted view. No-op when no live agent owns the key. */
+     *  the newly-targeted view.
+     *
+     *  Held mail is PRESERVED (that is the point) but its run completions are NOT
+     *  (#468): with the agent gone they would sit `handed_off` forever — a state
+     *  `deliverPending()` skips — so a provider switch that retires the key would
+     *  silently swallow them. The shared teardown detaches and returns them, and it
+     *  runs even when no live agent owns the key (a retire with only held mail is
+     *  exactly the case that lost them). */
     retire(tabId) {
-        const agent = this.agents.get(tabId);
+        const agent = this.unbindAgent(tabId, { dropHeldMail: false, reason: "retire" });
         if (!agent)
             return;
-        this.agents.delete(tabId);
         void agent.stop();
         logger.info(`[panel-orchestrator] tab ${tabId.slice(0, 8)} retired (workflow switch on the same socket) — durable session preserved`);
     }
@@ -1702,6 +2218,14 @@ export class PanelAgentManager {
     async stopAll() {
         this.pendingEffortRestart.clear();
         this.pendingMcpRestart.clear();
+        // #468 — go through the same detach seam as reset()/retire() for EVERY key
+        // before dropping held mail. The journal is about to be reported on by the
+        // orchestrator's shutdown disclosure, and an entry still marked `handed_off`
+        // because its token died inside discarded held mail would be missed by the
+        // replay AND read as merely "in flight" rather than lost.
+        for (const key of [...this.heldMessages.keys()]) {
+            this.detachHeldCompletions(key, "shutdown");
+        }
         this.heldMessages.clear();
         await Promise.all([...this.agents.values()].map((a) => a.stop()));
         this.agents.clear();