comfyui-mcp 0.49.2 → 0.49.4

package/dist/orchestrator/run-completion-journal.js

@@ -0,0 +1,914 @@
+// Durable-across-the-turn delivery of a render COMPLETION to the panel agent
+// (issue #468).
+//
+// THE FAILURE. `panel_run` queues a render on the user's canvas and tells the
+// agent — in so many words — "end your turn, you WILL be notified when it
+// finishes". That promise is kept by exactly one mechanism: the panel's
+// `agent_event` frame → PanelAgentManager.injectEvent → PanelAgent.queue. That
+// path used to be fire-and-forget in three independent ways:
+//
+//   1. UNCORRELATED. The completion carried no run identity the orchestrator
+//      ever looked at. `panel_run` learns ComfyUI's `prompt_id` (it already
+//      hands it to QueueMonitor.markSelfQueued) but nothing downstream used it,
+//      so a completion could not be tied to the run that was outstanding — and
+//      an outstanding run could never be known to be unanswered.
+//   2. SILENTLY DROPPED with no live agent. injectEvent returns false for a
+//      missing/stopped agent and the caller only logged on success. Nothing
+//      recorded the loss.
+//   3. DIED WITH A QUEUED-BUT-UNREAD ITEM. The event is only really delivered
+//      when channel() splices it into a turn. Everything before that — a
+//      stop()/retire(), a stall-abandoned turn, a takePending() race — discards
+//      it.
+//
+// AUTOMATIC GOAL CONTINUATION is what turns those windows from theoretical into
+// routine. An ordinary single run ends the agent's turn and leaves it idle, so
+// the completion lands in an empty queue and is drained immediately. A
+// continuation keeps the agent BUSY for the whole render: the completion sits in
+// `queue` (window 3) for minutes, and the continuation's own turn churn is
+// exactly what fires the deferred session restarts (effort/model change,
+// comfyui-MCP-env respawn) that applyPendingRestarts defers "until idle" and the
+// self-restart loop — each of which tears the listener down (windows 2 and 3)
+// underneath the very render whose completion is in flight.
+//
+// THE CONTRACT HERE.
+//  • Runs are ticketed by ComfyUI's `prompt_id`, opened by `panel_run`.
+//  • Every completion is CORRELATED ONCE, AT ARRIVAL, by EXACT prompt-id
+//    equality against an open ticket — never by recency, never re-derived later.
+//  • An uncorrelatable completion is still delivered, labelled UNDETERMINED. It
+//    is never swallowed and never allowed to answer for a run it can't be proven
+//    to belong to.
+//  • Undelivered completions are JOURNALED and replayed at the next delivery
+//    opportunity (a fresh agent spawn, a later completion for the same tab).
+//  • An entry is cleared only on a positive ack — the turn that CARRIED it
+//    ended. Handed to an agent that then died, it comes back and is replayed.
+//
+// LOCAL trust domain: this is accidental-loss bookkeeping, not a defense against
+// a hostile panel. Everything is in-memory and process-scoped; an orchestrator
+// restart drops the journal along with the agents it was addressing.
+import { logger } from "../utils/logger.js";
+/** Runs tracked at once. Ample for any real batch; bounded so a long session
+ *  can't grow the map without limit. */
+const MAX_TICKETS = 64;
+/** Undelivered completions held per panel tab. */
+const MAX_ENTRIES_PER_KEY = 32;
+/** Undelivered completions held across ALL tabs — a global ceiling so a session
+ *  that opens and abandons many tabs can't grow the journal without limit. */
+const MAX_ENTRIES_TOTAL = 96;
+/** (tab, run) pairs remembered as already delivered, to suppress a re-sent frame
+ *  after its entry was acked and removed. Comfortably larger than MAX_TICKETS so
+ *  it outlives the tickets that feed it; a resend later than THIS is delivered
+ *  again, but as `foreign` — flagged UNDETERMINED, never as the awaited run. */
+const MAX_DELIVERED_MEMO = 512;
+/** Tabs whose evicted-completion counter is retained. */
+const MAX_DROPPED_KEYS = 64;
+/** How many times a completion may be CARRIED BY A TURN THAT THEN ENDED without a
+ *  provable ack before the journal settles it anyway.
+ *
+ *  Counts turns, NOT queue hand-offs. A hand-off only means the event was queued;
+ *  an agent torn down before it drained its queue never showed the text to
+ *  anyone, so counting those would settle — and lose — a completion that three
+ *  ordinary provider/session replacements had merely shuffled around. The only
+ *  cycle that needs bounding is "dispatched into a turn → that turn ended → its
+ *  result could not be proven to be its own → replay", which a backend that
+ *  declares turn markers but never stamps its results would otherwise repeat
+ *  forever. Each of THOSE put the completion's text into a turn the agent read,
+ *  so settling risks a duplicate, never a loss. */
+const MAX_CARRIED_RELEASES = 3;
+/**
+ * How long an identical ID-LESS completion is still worth FLAGGING as a possible
+ * repeat. Content is the only evidence of sameness these have, and it is not
+ * proof — ComfyUI reuses temp output names (`ComfyUI_temp_*_00001_`) after a
+ * restart, so two genuinely different renders can look identical. Hence the flag
+ * is all it drives: nothing here ever merges or suppresses a completion.
+ */
+const IDLESS_REPEAT_HINT_MS = 10 * 60_000;
+/**
+ * Memo key for an already-delivered run: (tab, prompt id, TICKET GENERATION).
+ *
+ * The generation is what makes this an identity rather than a guess. A prompt id
+ * alone is not one — ComfyUI reuses ids, and a ticket can be evicted and
+ * recreated — so a memo keyed on the id would let run A's delivery suppress run
+ * B's real completion. `gen` is `RunTicket.seq`, or 0 when this tab has no
+ * ticket for the id at all (an unqueued, foreign run).
+ */
+function deliveredKey(key, promptId, gen) {
+    return `${key}|${promptId}|${gen}`;
+}
+/**
+ * Fingerprint for an ID-LESS completion (a panel that forwarded no `prompt_id`).
+ * With no run identity, content is all we have to tell "the panel re-sent the
+ * same frame" from "a second render finished": kind + note + error + the exact
+ * output list. Combined with IDLESS_DEDUPE_WINDOW_MS this collapses a repeat
+ * without letting a later, genuinely different render inherit the suppression.
+ * Filenames are NOT sorted — the panel emits them in output order, and a
+ * different order is a different batch.
+ */
+function idlessFingerprint(key, payload) {
+    const files = (payload.images ?? [])
+        .map((i) => `${i.subfolder ?? ""}/${i.type ?? ""}/${i.filename}`)
+        .join(",");
+    return `${key}|~idless~|${payload.kind ?? ""}|${payload.note ?? ""}|${payload.error ?? ""}|${files}`;
+}
+export class RunCompletionJournalImpl {
+    /** prompt id → ticket. Keyed globally: ComfyUI prompt ids are UUIDs, so an
+     *  exact match is proof of identity on its own and survives a session's tab
+     *  id being rebound between the queue and the completion. */
+    tickets = new Map();
+    /** token → entry (insertion-ordered, which is also delivery order). */
+    entries = new Map();
+    /** (tab, run) pairs whose completion was ACKED — a bounded FIFO memo so a
+     *  panel that re-sends the frame after the entry was removed can't produce a
+     *  second delivery. */
+    delivered = new Set();
+    /** Content fingerprint → delivery time, for ID-LESS completions (which have no
+     *  run identity to memoize). Bounded FIFO + a time window, so an identical
+     *  re-send is suppressed but a later genuinely-different render is not. */
+    idlessSeen = new Map();
+    seq = 0;
+    /** Monotonic ticket-generation counter — see RunTicket.seq. */
+    ticketSeq = 0;
+    /** The generation this tab's ticket for `promptId` is currently on, or 0 when
+     *  it has none. THE run identity: every proof and every merge is keyed on it,
+     *  so an id reused (or a ticket evicted and recreated) can never let one run's
+     *  bookkeeping answer for another's. */
+    generationOf(key, promptId) {
+        const ticket = this.tickets.get(promptId);
+        return ticket && ticket.tabId === key ? ticket.seq : 0;
+    }
+    /** Pull a still-queued completion back off its agent (see setRevoker). */
+    revoke = null;
+    /** Re-deliver a tab's pending completions (after a revoke re-arms one). */
+    reflush = null;
+    /**
+     * Wire the "unsend" hook (#468).
+     *
+     * A completion's WORDING is materialized when it is queued into an agent, so a
+     * correlation the journal later has to WEAKEN — a prompt id reused, a
+     * conversation replaced — would still reach the agent claiming "this is the run
+     * YOU queued". This lets the journal pull the stale copy back (only while it is
+     * still unread) and re-deliver the honest, downgraded version. Returns whether
+     * the item was actually removed.
+     */
+    setRevoker(revoke, reflush) {
+        this.revoke = revoke;
+        this.reflush = reflush ?? null;
+    }
+    /** Re-arm an entry whose correlation just weakened, if its already-queued copy
+     *  can still be pulled back. Once the carrying turn has started the text is in
+     *  the model's context and cannot be recalled — nothing to do but leave it. */
+    reissueAfterDowngrade(entry) {
+        if (entry.state !== "handed_off")
+            return;
+        if (!this.revoke?.(entry.key, entry.token))
+            return;
+        entry.state = "pending";
+        logger.info(`[run-completions] pulled a queued completion back after its correlation weakened — re-delivering it as ${describe(entry.correlation)}`);
+        // Re-queue it immediately with the honest wording; a revoked entry left
+        // merely `pending` would wait for some unrelated later flush.
+        this.reflush?.(entry.key);
+    }
+    /**
+     * A NEW run has taken over `promptId`, so every completion already journaled
+     * under it belongs to an OLDER run. Retire them: superseded (so they can never
+     * be merged into, settle a ticket, or memoize a delivery), downgraded from
+     * `matched` to `foreign` (so they stop claiming to be the run now outstanding),
+     * and re-issued if their queued copy can still be pulled back and re-worded.
+     *
+     * Runs on BOTH openRun paths — a reopen AND a fresh ticket after the old one
+     * was evicted. Only doing it on the reopen left the eviction ordering able to
+     * present an older run's result as the newly queued one's.
+     */
+    retireOlderEntriesFor(promptId) {
+        for (const entry of this.entries.values()) {
+            if (entry.correlation.status === "unidentified" ||
+                entry.correlation.promptId !== promptId ||
+                entry.superseded) {
+                continue;
+            }
+            entry.superseded = true;
+            if (entry.correlation.status === "matched") {
+                entry.correlation = { status: "foreign", promptId: entry.correlation.promptId };
+            }
+            logger.warn(`[run-completions] prompt ${promptId} was queued again while an earlier completion for it was still undelivered — the older entry is superseded (and reported as undetermined) so it can no longer answer for the new run`);
+            entry.ambiguousId = true; // the id now stands for more than one run
+            this.reissueAfterDowngrade(entry);
+        }
+    }
+    /** Has this tab ALREADY seen a completion for this prompt id — delivered (a
+     *  memo from any generation) or still journaled? If so the id is not a fresh
+     *  identity, however long ago that was and whether or not its ticket survives.
+     *  Both stores are bounded, so this is a small scan. */
+    hasHistoryFor(key, promptId) {
+        const prefix = `${key}|${promptId}|`;
+        for (const memo of this.delivered) {
+            if (memo.startsWith(prefix))
+                return true;
+        }
+        for (const entry of this.entries.values()) {
+            if (entry.key === key &&
+                entry.correlation.status !== "unidentified" &&
+                entry.correlation.promptId === promptId) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** `panel_run` queued a render. Returns false when ComfyUI/the panel gave us
+     *  no prompt id — the caller MUST then tell the agent its completion cannot be
+     *  correlated rather than promising a notification it may not be able to
+     *  attribute. */
+    openRun(promptId, meta) {
+        if (typeof promptId !== "string" || !promptId)
+            return false;
+        // NOTE: no memo clearing is needed here. The delivered memo is keyed by
+        // ticket GENERATION, and every path below either bumps the generation (a
+        // reopen) or mints a fresh one (a new ticket), so a newly queued run's memo
+        // key is unused by construction. This used to be a `delete` precisely because
+        // the key was generation-blind — the structural fix removed the need.
+        const existing = this.tickets.get(promptId);
+        if (existing) {
+            // Same prompt id queued again (a re-run of an id ComfyUI reused, or a
+            // duplicate reply): reopen it rather than stacking a second ticket, so one
+            // prompt id always means one run.
+            existing.settled = false;
+            existing.tabId = meta.tabId;
+            existing.queuedAt = Date.now();
+            existing.seq = ++this.ticketSeq; // a NEW generation of this id
+            // The id no longer identifies ONE run. Every completion for it from here
+            // on is unattributable (see RunTicket.reused) — reported UNDETERMINED, and
+            // never suppressed as a duplicate of the other generation.
+            existing.reused = true;
+            this.retireOlderEntriesFor(promptId);
+            return true;
+        }
+        // A FRESH ticket is only a fresh IDENTITY if this tab has no history for the
+        // id. If it does — a delivered memo from an earlier generation, or an entry
+        // still journaled — then ComfyUI has REUSED the id and the ticket was merely
+        // evicted in between. Nothing on the wire separates "run A's late resend"
+        // from "run B's completion" in that state, so the new ticket is born
+        // ambiguous: had it been treated as a clean identity, A's resend would
+        // correlate as B, its ack would settle B, and B's real completion would then
+        // be suppressed by B's own settled flag — misattribution AND loss.
+        const hasHistory = this.hasHistoryFor(meta.tabId, promptId);
+        this.tickets.set(promptId, {
+            promptId,
+            tabId: meta.tabId,
+            seq: ++this.ticketSeq,
+            queuedAt: Date.now(),
+            ...(typeof meta.toNodeId === "number" ? { toNodeId: meta.toNodeId } : {}),
+            settled: false,
+            ...(hasHistory ? { reused: true } : {}),
+        });
+        if (hasHistory) {
+            logger.warn(`[run-completions] prompt ${promptId} was queued again for tab ${meta.tabId.slice(0, 8)} after its ticket had been evicted — this tab already has history for that id, so it is treated as REUSED (every completion for it reported as undetermined)`);
+        }
+        // …and on THIS branch too. A fresh ticket after the old one was evicted is
+        // still a NEW run for an id that already has journaled completions: without
+        // this, an older `matched` entry survives untouched and goes on telling the
+        // agent "this is the run YOU queued" for the id now outstanding.
+        this.retireOlderEntriesFor(promptId);
+        this.trimTickets();
+        return true;
+    }
+    /**
+     * Classify a completion that arrived for panel tab `key` against the open runs.
+     *
+     * TWO conditions, both required: EXACT prompt-id equality AND the ticket must
+     * belong to THIS panel tab. There is deliberately no "the newest outstanding
+     * run" fallback and no cross-tab match, because attributing a completion to
+     * the wrong run — or to a different workflow's agent — is worse than not
+     * attributing it at all. A run whose ticket belongs to another tab reads as
+     * `foreign`, i.e. UNDETERMINED, which is the honest answer.
+     */
+    correlate(key, payload) {
+        const pid = typeof payload.prompt_id === "string" ? payload.prompt_id.trim() : "";
+        if (!pid)
+            return { status: "unidentified" };
+        const ticket = this.tickets.get(pid);
+        // A REUSED id proves nothing: the panel sends only the id, so a completion
+        // for it could belong to either generation. Report it as foreign — real, but
+        // UNDETERMINED — rather than claiming it is the run now outstanding.
+        return ticket && ticket.tabId === key && !ticket.reused
+            ? { status: "matched", promptId: pid }
+            : { status: "foreign", promptId: pid };
+    }
+    /**
+     * Journal a completion addressed to `key`. Correlation is computed here, once.
+     *
+     * DEDUPE, in both directions:
+     *  • IDENTIFIED (matched or foreign) — collapses onto any existing undelivered
+     *    entry for the same key + prompt id, and is suppressed outright once that
+     *    (tab, run) has been acked. One run can never produce two deliveries,
+     *    however many times the panel re-sends it.
+     *  • ID-LESS — there is no run identity, so it dedupes on a CONTENT
+     *    fingerprint within IDLESS_DEDUPE_WINDOW_MS. That is enough to stop a
+     *    re-sent frame producing two turns (the agent double-reporting, or acting
+     *    twice on one output), while a later genuinely different render — or the
+     *    same content long afterwards — is still delivered.
+     * NEVER returns null: a completion is always journaled and always delivered.
+     * The most this does is COLLAPSE onto a twin that nobody has seen yet, or FLAG
+     * one as a possible repeat. Suppression was the source of every loss this file
+     * kept re-growing, because each proof it rested on is bounded and any expiry at
+     * the wrong moment turned a new run's result into a discarded "duplicate".
+     */
+    record(key, payload) {
+        const correlation = this.correlate(key, payload);
+        let idlessRepeat = false;
+        /** This id already stands for more than one run (see RunTicket.reused). */
+        let idReused = false;
+        /** No provable identity for this completion — see the `unprovable` note in
+         *  the identified branch. Never merged into, never suppressed. */
+        let idUnprovable = false;
+        /** Ticket generation this completion belongs to — the run identity (0 = no
+         *  ticket, i.e. a run this tab never queued). */
+        let gen = 0;
+        /** A completion for this run was already delivered. A LABEL, not a veto. */
+        let alreadyDelivered = false;
+        if (correlation.status !== "unidentified") {
+            // Already DELIVERED once (its carrying turn ended, so the entry is gone).
+            // A panel that re-sends the frame must not produce a second delivery — the
+            // dedupe below can't see an entry that no longer exists.
+            // Two independent records of "already delivered": the bounded memo, and the
+            // run TICKET's own `settled` flag. The memo is FIFO-capped, so a busy tab
+            // can age it out and then re-deliver a very late resend; the ticket outlives
+            // it for any run this session actually queued. Either one is proof.
+            const settledTicket = this.tickets.get(correlation.promptId);
+            // Both proofs are DISABLED for a reused id: neither can tell which
+            // generation a completion belongs to, so suppressing on them could swallow
+            // the newer run's real result. A duplicate delivery (labelled UNDETERMINED)
+            // is the correct trade here.
+            idReused = settledTicket?.reused === true && settledTicket.tabId === key;
+            // The memo is keyed by GENERATION, so an older run's delivery can never
+            // suppress a newer one that merely reuses the id (or that got a fresh
+            // ticket after the old one was evicted): different generation, different
+            // key, no match.
+            gen = this.generationOf(key, correlation.promptId);
+            // UNPROVABLE identity — no dedupe of any kind is safe:
+            //  • `reused`: the id stands for more than one run (see RunTicket.reused).
+            //  • gen 0: this tab never ticketed the id, so there is NO generation to
+            //    tell one such completion from another. Every foreign completion would
+            //    share the key `(tab, id, 0)`, which is a bucket, not an identity —
+            //    two genuinely different external renders that reuse a prompt id (a
+            //    ComfyUI restart does exactly that) would merge, and the second would
+            //    be suppressed outright after the first was acked.
+            // Both cases fall back to the standing rule: duplicate over loss, each
+            // delivered on its own and labelled UNDETERMINED.
+            idUnprovable = idReused || gen === 0;
+            // ALREADY-DELIVERED IS A LABEL, NEVER A VETO.
+            //
+            // This used to `return null` — suppressing the completion outright — and
+            // that single decision produced defect after defect, because every proof it
+            // rested on (the memo, the ticket's `settled` flag, the ticket's very
+            // existence) is BOUNDED. Whenever one expired at the wrong moment, a
+            // genuinely new run's completion was mistaken for an old one's resend and
+            // swallowed: exactly the failure this whole file exists to prevent, and the
+            // one the project's rules call worse than a duplicate.
+            //
+            // So the journal now NEVER suppresses an identified completion. It delivers
+            // it FLAGGED as a possible repeat and lets the agent — which can read the
+            // prompt id, see the outputs, and call get_history — decide. No expiry can
+            // turn that into a loss, and the honest failure mode is a second turn
+            // saying "this may be the same render", not silence.
+            if (!idUnprovable &&
+                (this.delivered.has(deliveredKey(key, correlation.promptId, gen)) ||
+                    (settledTicket?.settled === true && settledTicket.tabId === key))) {
+                logger.info(`[run-completions] a completion for ${describe(correlation)} was already delivered to tab ${key.slice(0, 8)} — forwarding this one FLAGGED as a possible repeat (never suppressed)`);
+                alreadyDelivered = true;
+            }
+            // COALESCE ONLY ONTO A `pending` ENTRY. This is the correctness rule, and
+            // it is deliberately a property of the TARGET'S OWN CURRENT STATE — not of
+            // any history that could be evicted out from under it.
+            //
+            // Once an entry is `handed_off` its text is committed to a turn that will
+            // ack and DELETE it. Merging a newer completion into it means the newer one
+            // is never delivered: the queued turn still holds the older text, and its
+            // ack removes the single shared entry. That is a loss, and it is reachable
+            // by several orderings of prompt-id reuse vs. ticket eviction — chasing
+            // those one at a time is how this defect kept coming back, because reuse
+            // DETECTION needs the old ticket, and the ticket is evictable.
+            //
+            // The same predicate already governs the id-less collapse, for the same
+            // reason. The `reused`/`ambiguousId` checks below are now an OPTIMISATION
+            // for better wording (an ambiguous run should read as UNDETERMINED rather
+            // than merge at all), never the thing correctness rests on.
+            //
+            // The target must ALSO be the same GENERATION. A `pending` entry from an
+            // older run of the same id (its ticket evicted, the id then re-queued) is
+            // still a DIFFERENT run: overwriting its payload would drop that run's
+            // result and leave the survivor stamped with the wrong generation, so its
+            // ack could settle neither. Same-state AND same-identity.
+            for (const entry of idUnprovable ? [] : this.entries.values()) {
+                if (entry.key === key &&
+                    entry.state === "pending" && // never merge into text already committed to a turn
+                    (entry.ticketSeq ?? 0) === gen && // …nor across run generations
+                    !entry.superseded && // a re-queued run never merges into the old one's entry
+                    !entry.ambiguousId && // nor into one that arrived under a reused id
+                    entry.correlation.status !== "unidentified" &&
+                    entry.correlation.promptId === correlation.promptId) {
+                    // Safe by the predicate above: this entry is still `pending`, so
+                    // nothing of it has been committed to a turn. Freshening its payload
+                    // replaces a copy nobody has seen — one delivery instead of two, with
+                    // no possibility that an older text acks and deletes the newer news.
+                    entry.payload = payload;
+                    return entry;
+                }
+            }
+        }
+        else {
+            const print = idlessFingerprint(key, payload);
+            const now = Date.now();
+            // NEVER COLLAPSE AN ID-LESS COMPLETION.
+            //
+            // The collapse was the last surviving suppression, and it fails for the
+            // same reason all the others did — its premise is not establishable. For an
+            // identified run, "a twin nobody has seen yet" is a fact: same prompt id,
+            // same ticket generation. For an ID-LESS one there is no id, and ComfyUI
+            // reuses temp output names (this file says exactly that a few hundred lines
+            // up), so "same tab, same content, both pending, within 30s" is PRECISELY
+            // the state two genuinely different renders present. Merging there deletes
+            // one of them, silently.
+            //
+            // So every id-less completion gets its own entry. When an identical one is
+            // already journaled — in ANY state — or was delivered recently, the new one
+            // is FLAGGED `possible_repeat` and the agent decides. That is the same trade
+            // already accepted everywhere else: a duplicate turn beats a lost render,
+            // and a wording optimisation must never be load-bearing for correctness.
+            const twinJournaled = [...this.entries.values()].some((e) => e.key === key && e.correlation.status === "unidentified" && e.fingerprint === print);
+            const seenAt = this.idlessSeen.get(print);
+            const repeatHint = seenAt !== undefined && now - seenAt < IDLESS_REPEAT_HINT_MS;
+            if (seenAt !== undefined && !repeatHint)
+                this.idlessSeen.delete(print); // stale
+            idlessRepeat = repeatHint || twinJournaled;
+            if (idlessRepeat) {
+                logger.info(`[run-completions] tab ${key.slice(0, 8)}: an id-less completion with identical content is already known — forwarding this one FLAGGED as a possible repeat (never merged, never suppressed: content is not identity)`);
+            }
+        }
+        const entry = {
+            token: `rc${++this.seq}`,
+            key,
+            payload,
+            correlation,
+            arrivedAt: Date.now(),
+            attempts: 0,
+            state: "pending",
+            ...(correlation.status === "unidentified"
+                ? { fingerprint: idlessFingerprint(key, payload) }
+                : {}),
+            // One flag, both paths: an identified run whose completion was already
+            // delivered, or an id-less one whose content matches a recent delivery.
+            ...(idlessRepeat || alreadyDelivered ? { possibleRepeat: true } : {}),
+            // Freeze the ambiguity onto the entry — see JournalEntry.ambiguousId.
+            ...(idUnprovable ? { ambiguousId: true } : {}),
+            // …and the GENERATION this completion belongs to, for EVERY identified
+            // entry (not just matched ones): it is what keeps its ack, its memo and any
+            // future merge bound to this run rather than to whatever the id means later.
+            ...(correlation.status !== "unidentified" ? { ticketSeq: gen } : {}),
+        };
+        this.entries.set(entry.token, entry);
+        this.trimEntries(key);
+        return entry;
+    }
+    /** Completions this tab lost to an eviction and has not yet been told about.
+     *  Surfaced on the next delivery so a dropped completion is never silent. */
+    dropped = new Map();
+    /** Count a lost completion for a tab, bounding the map so a churn of one-off
+     *  tabs can't grow it forever (the oldest unreported count is discarded — it
+     *  was already logged at ERROR when it happened). */
+    /**
+     * Record that a completion for `key` was destroyed by an eviction, so the next
+     * delivery to that tab can report it as UNDETERMINED.
+     *
+     * The count is stamped onto a SURVIVING entry for the same tab whenever one
+     * exists — it then rides out on a real delivery and cannot be discarded. The
+     * side map is only for a tab with nothing left to carry it, i.e. a tab whose
+     * next delivery is hypothetical anyway; that is the only thing the bound can
+     * ever discard, and it is logged.
+     */
+    noteDropped(key, count = 1) {
+        if (count <= 0)
+            return;
+        // The carrier must be an entry `deliverPending` will actually READ — i.e. a
+        // PENDING one. A handed-off entry's payload was already built and queued, so
+        // stamping the count on it would attach a warning to text nobody will ever
+        // see again, and `ack()` would then spend it: the eviction would be neither
+        // replayed nor disclosed. With no pending entry the count goes to the side
+        // map, where the next pending delivery for this tab picks it up.
+        const carrier = [...this.entries.values()].find((e) => e.key === key && e.state === "pending");
+        if (carrier) {
+            carrier.disclose = (carrier.disclose ?? 0) + count;
+            return;
+        }
+        this.dropped.set(key, (this.dropped.get(key) ?? 0) + count);
+        while (this.dropped.size > MAX_DROPPED_KEYS) {
+            const victim = this.dropped.keys().next().value;
+            if (victim === undefined)
+                break;
+            const lost = this.dropped.get(victim) ?? 0;
+            this.dropped.delete(victim);
+            logger.error(`[run-completions] discarding the undelivered-completion count (${lost}) for tab ${victim.slice(0, 8)} — over ${MAX_DROPPED_KEYS} agentless tabs are tracking one; that tab will not be told`);
+        }
+    }
+    /** Entries awaiting a delivery attempt for this key, in arrival order. */
+    pending(key) {
+        const out = [];
+        for (const entry of this.entries.values()) {
+            if (entry.key === key && entry.state === "pending")
+                out.push(entry);
+        }
+        return out;
+    }
+    /**
+     * Deliver every pending entry for `key`, in ARRIVAL order, stopping at the
+     * first refusal so a newer completion can never overtake an older one that is
+     * still stuck.
+     *
+     * `inject` returns whether the agent TOOK the payload onto its queue — not
+     * that it was read. The entry stays journaled either way; only `ack` (the turn
+     * that carried it ended) removes it. That is the whole durability property:
+     * hand it to an agent that then dies and it comes back here.
+     *
+     * NOTHING is re-correlated: the payload is stamped with the verdict frozen at
+     * arrival, so a replay can never be re-attributed to a run that started later.
+     */
+    deliverPending(key, inject) {
+        let delivered = 0;
+        for (const entry of this.pending(key)) {
+            // Any completion this tab lost to an eviction rides out on the next one
+            // that DOES get through, so an evicted completion is reported rather than
+            // silently forgotten.
+            // The tab's evicted-completion count: whatever this entry is carrying, plus
+            // anything stranded in the side map from a period when the tab had no entry
+            // to carry it.
+            const lost = (entry.disclose ?? 0) + (this.dropped.get(key) ?? 0);
+            const payload = {
+                ...entry.payload,
+                run_correlation: entry.correlation.status,
+                ...(entry.correlation.status === "unidentified"
+                    ? {}
+                    : { prompt_id: entry.correlation.promptId }),
+                // Second and later attempts ARE re-deliveries — say so, so the agent
+                // reads a replay as "this landed late", not as another render.
+                ...(entry.attempts > 0 ? { replayed: true } : {}),
+                ...(lost > 0 ? { dropped_completions: lost } : {}),
+                ...(entry.possibleRepeat ? { possible_repeat: true } : {}),
+            };
+            const handedOff = inject(payload, entry.token);
+            this.noteAttempt(entry.token, handedOff);
+            if (!handedOff)
+                return { delivered, blockedOn: entry };
+            if (lost > 0) {
+                // CONSOLIDATE onto the entry; do NOT consider the disclosure spent yet.
+                // A hand-off is not consumption: if this agent is stopped before its turn
+                // runs, the entry is released and replayed, and the warning must go with
+                // it. Only `ack()` — the turn that carried it having ended — clears it.
+                entry.disclose = lost;
+                this.dropped.delete(key);
+            }
+            delivered += 1;
+        }
+        return { delivered, blockedOn: null };
+    }
+    /** All still-unacked entries for a key (pending OR handed off) — diagnostics. */
+    outstanding(key) {
+        return [...this.entries.values()].filter((e) => e.key === key);
+    }
+    /** Is ANY completion still undelivered anywhere? The orchestrator's
+     *  self-restart gate reads this: the journal is in-memory, so restarting while
+     *  an entry is outstanding would silently drop a render result the agent was
+     *  promised. */
+    hasOutstanding() {
+        return this.entries.size > 0;
+    }
+    /** Every still-unacked entry, across all tabs — for the last-ditch disclosure
+     *  the orchestrator makes when a fatal self-exit is about to destroy them. */
+    allOutstanding() {
+        return [...this.entries.values()];
+    }
+    /** Record the outcome of a delivery attempt. `handedOff` true = an agent took
+     *  it onto its queue (not yet proof it was read). */
+    noteAttempt(token, handedOff) {
+        const entry = this.entries.get(token);
+        if (!entry)
+            return;
+        entry.attempts += 1;
+        entry.state = handedOff ? "handed_off" : "pending";
+    }
+    /** The turn that CARRIED this completion ended — it genuinely reached the
+     *  agent. Drop the entry and settle its run. */
+    ack(token) {
+        const entry = this.entries.get(token);
+        if (!entry)
+            return;
+        this.entries.delete(token);
+        // The turn that carried it ended, so any eviction disclosure it was carrying
+        // has now actually reached the agent — only here is it spent. (An entry
+        // evicted while still holding one passes it on; see trimEntries.)
+        delete entry.disclose;
+        // A SUPERSEDED entry belongs to a run whose prompt id was queued again. It
+        // was still delivered (its text reached the agent), but it must not settle
+        // the REOPENED ticket — that would present the old result as the new run's —
+        // and must not memoize the id as delivered, which would then suppress the new
+        // run's real completion.
+        if (entry.superseded)
+            return;
+        if (entry.correlation.status !== "unidentified") {
+            // …and do not memoize a REUSED id either. DEFENSE IN DEPTH, not a live
+            // defect: `openRun` already clears the memo on every path, so no reachable
+            // sequence can let a stale one suppress a later legitimate completion (and
+            // therefore no test can fail on this line). It is here because writing a
+            // "we already reported this run" proof about an id that stands for MORE
+            // THAN ONE run is meaningless on its face, and a future caller that opens a
+            // ticket without going through openRun would inherit the trap.
+            const ticket = this.tickets.get(entry.correlation.promptId);
+            // Only a REAL generation is a proof. Generation 0 means this tab never
+            // ticketed the id, so `(tab, id, 0)` is a bucket shared by every foreign
+            // completion for it — memoizing there would let one external render's
+            // delivery suppress a different one that happens to reuse the id.
+            const provable = (entry.ticketSeq ?? 0) > 0;
+            if (provable && !(ticket?.reused === true && ticket.tabId === entry.key)) {
+                // Memoize against THIS entry's own generation, never the id's current
+                // meaning: an older run's ack must not write a proof that then suppresses
+                // the newer run which reused the id (or got a fresh ticket after the old
+                // one was evicted).
+                this.memoDelivered(entry.key, entry.correlation.promptId, entry.ticketSeq ?? 0);
+            }
+        }
+        else if (entry.fingerprint) {
+            // ID-LESS: memoize the CONTENT so a re-sent identical frame after the ack
+            // doesn't produce a second turn. Windowed in record(), bounded here.
+            this.idlessSeen.set(entry.fingerprint, Date.now());
+            while (this.idlessSeen.size > MAX_DELIVERED_MEMO) {
+                const oldest = this.idlessSeen.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.idlessSeen.delete(oldest);
+            }
+        }
+        if (entry.correlation.status === "matched") {
+            const ticket = this.tickets.get(entry.correlation.promptId);
+            // ONLY the exact ticket generation this entry was matched against. Looking
+            // the ticket up by prompt id alone let a late completion for run A settle
+            // whatever ticket that id maps to NOW — run B's — marking B answered by A's
+            // result. See RunTicket.seq.
+            if (ticket && ticket.seq === entry.ticketSeq)
+                ticket.settled = true;
+        }
+    }
+    /**
+     * An agent gave a hand-off back undelivered. Re-arm it for replay.
+     *
+     * `carried` distinguishes the two causes, and ONLY the first is bounded:
+     *  • carried: true  — a turn actually DISPATCHED with this completion in it and
+     *    then ended, but its result could not be proven to be that turn's own. The
+     *    agent read the text. A backend that declares turn markers yet never stamps
+     *    its results would bounce the entry here on every single turn, so after
+     *    MAX_CARRIED_RELEASES we settle rather than loop: a duplicate at worst.
+     *  • carried: false — a teardown handed it back (agent stopped, held mail
+     *    discarded, session died). NOBODY read it. These must never count toward
+     *    the bound, or three ordinary provider/session replacements would settle —
+     *    and lose — a completion that was only ever shuffled between queues.
+     */
+    release(token, opts = {}) {
+        const entry = this.entries.get(token);
+        if (!entry)
+            return;
+        if (opts.carried) {
+            entry.carriedReleases = (entry.carriedReleases ?? 0) + 1;
+            if (entry.carriedReleases >= MAX_CARRIED_RELEASES) {
+                logger.warn(`[run-completions] ${describe(entry.correlation)} was carried by ${entry.carriedReleases} turns that ended without a provable ack — settling it instead of replaying again`);
+                this.ack(token);
+                return;
+            }
+        }
+        entry.state = "pending";
+    }
+    /** Move every entry AND every open run ticket from `from` onto `to` — a panel
+     *  tab-id migration re-keys the agent, and both must move WITH it or a later
+     *  completion for a run queued under the old id reads as foreign. This
+     *  re-addresses, it never broadens: other tabs' state is untouched. */
+    moveKey(from, to) {
+        if (from === to)
+            return;
+        for (const entry of this.entries.values()) {
+            if (entry.key === from)
+                entry.key = to;
+        }
+        for (const ticket of this.tickets.values()) {
+            if (ticket.tabId === from)
+                ticket.tabId = to;
+        }
+        // ALL per-tab state moves, not just the visible two. Leaving the delivered
+        // memo behind would let a post-migration re-send be delivered a SECOND time
+        // (its settled ticket moved, so it still correlates as matched); leaving the
+        // eviction counter behind would silently swallow the "these runs are
+        // undetermined" disclosure it exists to carry.
+        for (const memo of [...this.delivered]) {
+            if (!memo.startsWith(`${from}|`))
+                continue;
+            this.delivered.delete(memo);
+            this.delivered.add(`${to}|${memo.slice(from.length + 1)}`);
+        }
+        const lost = this.dropped.get(from);
+        if (lost !== undefined) {
+            this.dropped.delete(from);
+            this.dropped.set(to, (this.dropped.get(to) ?? 0) + lost);
+        }
+        // The id-less content memo and every entry's fingerprint embed the tab key,
+        // so they must be re-keyed too or a post-migration re-send is delivered
+        // twice — the same defect as the delivered memo above.
+        const fromPrefix = `${from}|~idless~|`;
+        for (const [print, at] of [...this.idlessSeen]) {
+            if (!print.startsWith(fromPrefix))
+                continue;
+            this.idlessSeen.delete(print);
+            this.idlessSeen.set(`${to}|~idless~|${print.slice(fromPrefix.length)}`, at);
+        }
+        for (const entry of this.entries.values()) {
+            if (entry.fingerprint?.startsWith(fromPrefix)) {
+                entry.fingerprint = `${to}|~idless~|${entry.fingerprint.slice(fromPrefix.length)}`;
+            }
+        }
+    }
+    /**
+     * Drop everything belonging to a tab that will never come back — a closed tab,
+     * or the workflow being switched AWAY from.
+     *
+     * Tickets go too, not just entries: a run queued under the old workflow that
+     * finishes AFTER the switch would otherwise still `correlate` as matched (the
+     * ticket map is global) and be delivered to the NEW workflow's agent as "the
+     * run YOU queued". Forgetting the ticket makes that completion read as
+     * foreign — i.e. UNDETERMINED — which is the honest answer.
+     *
+     * Logs every completion that dies unacked; a loss must never be silent.
+     */
+    forget(key) {
+        for (const [token, entry] of [...this.entries]) {
+            if (entry.key !== key)
+                continue;
+            this.entries.delete(token);
+            logger.warn(`[run-completions] dropping an undelivered completion for ${describe(entry.correlation)} — its tab (${key.slice(0, 8)}) is gone`);
+        }
+        for (const [pid, ticket] of [...this.tickets]) {
+            if (ticket.tabId === key)
+                this.tickets.delete(pid);
+        }
+        // An eviction disclosure this tab was still owed dies with it — the tab is
+        // gone, so there is no delivery left to carry it. Say so at ERROR rather than
+        // dropping it silently: the eviction path PROMISES the loss will be reported,
+        // and this is the one place that promise cannot be kept.
+        const owed = this.dropped.get(key) ?? 0;
+        if (owed > 0) {
+            logger.error(`[run-completions] tab ${key.slice(0, 8)} is gone still owed a disclosure for ${owed} evicted completion(s) — it will never be told; treat those runs as UNDETERMINED`);
+        }
+        this.dropped.delete(key);
+        for (const memo of [...this.delivered]) {
+            if (memo.startsWith(`${key}|`))
+                this.delivered.delete(memo);
+        }
+        for (const print of [...this.idlessSeen.keys()]) {
+            if (print.startsWith(`${key}|~idless~|`))
+                this.idlessSeen.delete(print);
+        }
+    }
+    /**
+     * The CONVERSATION that queued this tab's outstanding runs is gone — New chat,
+     * a switch to a historical session, or a workflow replaced in place.
+     *
+     * Drop the tab's run TICKETS but keep its journal entries. A render queued by
+     * the old conversation is still real and its completion is still delivered;
+     * it just can no longer be introduced to the replacement agent as "the run YOU
+     * queued" — it correlates as foreign, i.e. UNDETERMINED. Entries that already
+     * arrived keep the verdict frozen at THEIR arrival, so a completion the old
+     * conversation was owed is still reported to it correctly if it is still
+     * deliverable.
+     */
+    closeRuns(key) {
+        for (const [pid, ticket] of [...this.tickets]) {
+            if (ticket.tabId === key)
+                this.tickets.delete(pid);
+        }
+        // Entries still undelivered were addressed to the conversation that just
+        // went away, so their `matched` verdict no longer holds for whoever receives
+        // them next: DOWNGRADE to foreign. This does not violate "correlated once at
+        // arrival" — a correlation may only ever get WEAKER (matched → foreign),
+        // never stronger, and only in response to an explicit "that conversation is
+        // gone" event. Without it a completion journaled before New chat would be
+        // replayed to the replacement agent as "the run YOU queued".
+        for (const entry of this.entries.values()) {
+            if (entry.key === key && entry.correlation.status === "matched") {
+                entry.correlation = { status: "foreign", promptId: entry.correlation.promptId };
+                // Same as the reused-id downgrade: the queued copy still claims to be the
+                // run this (now-replaced) conversation queued. Recall it if we still can.
+                this.reissueAfterDowngrade(entry);
+            }
+        }
+    }
+    /** Remember (tab, run) as already reported, so a later re-send of the same
+     *  frame is suppressed rather than delivered a second time. Bounded FIFO; the
+     *  run TICKET's `settled` flag is the other record, and an evicted settled
+     *  ticket feeds this one so neither expires before the other. */
+    memoDelivered(key, promptId, gen) {
+        this.delivered.add(deliveredKey(key, promptId, gen));
+        while (this.delivered.size > MAX_DELIVERED_MEMO) {
+            const oldest = this.delivered.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.delivered.delete(oldest);
+        }
+    }
+    /** Test/diagnostic helpers. */
+    ticketFor(promptId) {
+        return this.tickets.get(promptId);
+    }
+    reset() {
+        this.tickets.clear();
+        this.entries.clear();
+        this.dropped.clear();
+        this.delivered.clear();
+        this.idlessSeen.clear();
+        this.seq = 0;
+    }
+    /** Evicted completions this tab has not been told about yet — wherever the
+     *  count currently lives (riding an entry, or the agentless side map). */
+    droppedFor(key) {
+        const carried = [...this.entries.values()]
+            .filter((e) => e.key === key)
+            .reduce((n, e) => n + (e.disclose ?? 0), 0);
+        return carried + (this.dropped.get(key) ?? 0);
+    }
+    trimTickets() {
+        while (this.tickets.size > MAX_TICKETS) {
+            // Prefer evicting a settled ticket; otherwise the oldest. An evicted OPEN
+            // ticket means a later completion for it correlates as "foreign" — i.e.
+            // UNDETERMINED, which is the honest reading once we've forgotten the run.
+            let victim = null;
+            for (const [pid, t] of this.tickets) {
+                if (t.settled) {
+                    victim = pid;
+                    break;
+                }
+            }
+            if (!victim)
+                victim = this.tickets.keys().next().value ?? null;
+            if (!victim)
+                return;
+            // Evicting a SETTLED ticket does not lose the "already reported" proof:
+            // ack() writes it to the delivered memo at the same moment it sets
+            // `settled`, and MAX_DELIVERED_MEMO is deliberately far larger than
+            // MAX_TICKETS so the memo always outlives the ticket that mirrors it.
+            this.tickets.delete(victim);
+        }
+    }
+    /**
+     * Enforce the per-tab and global ceilings.
+     *
+     * EVICTION ORDER matters: an entry already HANDED OFF is sitting in a live
+     * agent's queue and will most likely be read, so it is the cheapest thing to
+     * forget; a still-PENDING entry has reached nobody, so evicting one is a real
+     * loss. Pending entries are therefore evicted last, logged at ERROR, and
+     * COUNTED — the count rides out on the next completion that does get through
+     * (`dropped_completions`), so the agent is told those runs are undetermined
+     * instead of the loss being silent.
+     */
+    trimEntries(key) {
+        const evict = (scope, limit, label) => {
+            let mine = [...this.entries.values()].filter(scope);
+            while (mine.length > limit) {
+                // Prefer an already-handed-off entry: it is at least sitting in a live
+                // agent's queue, so it is the likeliest to land anyway. But a hand-off is
+                // explicitly NOT proof of consumption, so an evicted hand-off is counted
+                // and reported exactly like an evicted pending one — evicting it removes
+                // our ability to replay it if that agent dies first.
+                const victim = mine.find((e) => e.state === "handed_off") ?? mine[0];
+                this.entries.delete(victim.token);
+                mine = mine.filter((e) => e !== victim);
+                // …and PULL ITS QUEUED COPY with it. The journal's cap bounds the
+                // journal; the agent's queue owns the actual payload, so evicting the
+                // record alone left the text queued forever. A panel resending in a tight
+                // loop would then grow that queue without limit while the journal stayed
+                // at 32 — and the whole backlog drains into ONE turn, which is how the
+                // genuine completion gets starved. Revoking keeps the two bounded
+                // together. (No-op once the carrying turn has started; that copy is
+                // already committed and is bounded by the turn instead.)
+                this.revoke?.(victim.key, victim.token);
+                // Its own loss PLUS any disclosure it was carrying for the tab — moved to
+                // whatever survives, so an eviction can never drop the disclosure itself.
+                this.noteDropped(victim.key, 1 + (victim.disclose ?? 0));
+                logger.error(`[run-completions] ${label} — dropped a ${victim.state === "pending" ? "still-undelivered" : "handed-off-but-unconfirmed"} completion for ${describe(victim.correlation)}; the next delivery will report it as undetermined`);
+            }
+        };
+        evict((e) => e.key === key, MAX_ENTRIES_PER_KEY, `journal for tab ${key.slice(0, 8)} exceeded ${MAX_ENTRIES_PER_KEY} undelivered completions`);
+        evict(() => true, MAX_ENTRIES_TOTAL, `journal exceeded ${MAX_ENTRIES_TOTAL} undelivered completions overall`);
+    }
+}
+/** Short human label for a correlation, for logs. */
+export function describe(correlation) {
+    return correlation.status === "unidentified"
+        ? "an unidentified run"
+        : `${correlation.status === "matched" ? "run" : "foreign run"} ${correlation.promptId}`;
+}
+/** Process-wide journal (mirrors the QueueMonitor singleton): `panel_run` opens
+ *  tickets from the tool layer while the orchestrator's panel-event handler
+ *  records and replays completions, with no ctx plumbing between them. */
+export const RunCompletions = new RunCompletionJournalImpl();
+//# sourceMappingURL=run-completion-journal.js.map