@ggui-ai/mcp-server 0.25.0 → 0.27.0

package/dist/first-seen.js

@@ -0,0 +1,19 @@
+export function createFirstSeen(capacity) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+        throw new RangeError(`capacity must be a positive integer, got ${capacity}`);
+    }
+    const seen = new Set();
+    return {
+        first(key) {
+            if (seen.has(key))
+                return false;
+            if (seen.size >= capacity) {
+                const oldest = seen.values().next();
+                if (!oldest.done)
+                    seen.delete(oldest.value);
+            }
+            seen.add(key);
+            return true;
+        },
+    };
+}

package/dist/ggui-session-channel/action-ingress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-ingress.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/action-ingress.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAOvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AA+G9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,mBAAmB,CACjB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CA+K1E"}
+{"version":3,"file":"action-ingress.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/action-ingress.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAEhB,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AAOlC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AA+G9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,mBAAmB,CACjB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CA6O1E"}

package/dist/ggui-session-channel/action-ingress.js

@@ -177,13 +177,63 @@ export function createActionIngress(deps) {
         // reaped) degrades to ledger-only with a warn — the WS client has
         // no `ui/message` fallback to branch on, so a new error frame
         // would be vocabulary without a consumer.
+        //
+        // The append's outcome (ggui#1517) is not read here: this path mints
+        // the pipe id per frame (`toConsumeEventEntry`), so a duplicate cannot
+        // arise, and the ledger write is this path's load-bearing one.
+        // The pipe entry (and its minted actionId, which also names the holder of
+        // a oneShot spend, ggui#1424) is built once per frame.
+        const entry = envelope.type === "data:submit" ? toConsumeEventEntry(envelope, sub.sessionId) : null;
+        // ggui#1424 — the channel door refuses a second gesture on a spent
+        // oneShot too, so the server's refusal holds at both doors. The claim is
+        // taken BEFORE the writes under this frame's minted actionId; the answer
+        // decides as it does on the tool door (`claimDispatchSpend` there):
+        // already-spent by another holder whose delivery is marked → refused with
+        // the channel's existing CONTRACT_VIOLATION error frame (#1358), one
+        // violation at `actionSpec.<name>.oneShot`, no ledger row, no pipe entry,
+        // one named line; an unmarked holder is taken over; the same holder, no
+        // holder, a non-oneShot action, a store that answers no claim, or a store
+        // failure (fail-open, named) → the frame goes on as before. The store
+        // enforces `delivered`: the refusal arm reads it only as the store
+        // answers it. Delivery is marked after the writes below.
+        const framePayload = envelope.payload;
+        const oneShotPayload = entry !== null &&
+            activeItem !== undefined &&
+            framePayload !== null &&
+            typeof framePayload === "object" &&
+            !Array.isArray(framePayload) &&
+            typeof framePayload.action === "string"
+            ? { action: framePayload.action, data: framePayload.data }
+            : null;
+        if (oneShotPayload !== null && entry !== null && activeItem !== undefined) {
+            const verdict = await claimChannelSpend(deps, sub.sessionId, activeItem, oneShotPayload, entry.actionId);
+            if (verdict.kind === "refuse") {
+                deps.logger.warn("render_channel_one_shot_refused", {
+                    sessionId: sub.sessionId,
+                    action: oneShotPayload.action,
+                    actionId: entry.actionId,
+                    by: verdict.by,
+                });
+                deps.sendError(ws, "CONTRACT_VIOLATION", `actionSpec.${oneShotPayload.action} is declared oneShot and already fired on this card; a second gesture is refused`, message.requestId, {
+                    error: "contract_violation",
+                    violations: [
+                        {
+                            field: `actionSpec.${oneShotPayload.action}.oneShot`,
+                            keyword: "oneShot",
+                            message: "this one-shot action already fired on this card",
+                            expected: verdict.by,
+                            received: entry.actionId,
+                        },
+                    ],
+                    hint: "The action already fired on this card. Render a new card to fire it again.",
+                });
+                return;
+            }
+        }
         const consumeWrite = (() => {
-            if (deps.pendingEventConsumer === undefined || envelope.type !== "data:submit") {
+            if (deps.pendingEventConsumer === undefined || entry === null) {
                 return Promise.resolve();
             }
-            const entry = toConsumeEventEntry(envelope, sub.sessionId);
-            if (entry === null)
-                return Promise.resolve();
             return deps.pendingEventConsumer.append(sub.sessionId, {
                 // The pipe entry's stable id doubles as the `drain_ack` key —
                 // same convention as the relay path's iframe-supplied id.
@@ -218,10 +268,12 @@ export function createActionIngress(deps) {
             return;
         }
         const seq = ledgerResult.value;
-        // ggui#1223 / #1305 — the gesture is in the ledger, so a committed
-        // `oneShot` now spends its card durably, BEFORE the ack: a client that
-        // holds the ack can reload and find the card spent. FAIL-OPEN, as on the
-        // tool path: a failed record is named and never withholds the ack.
+        // ggui#1223 / #1305 / #1424 — the gesture is in the ledger, so the
+        // holder MARKS its spend delivered (claimed above, before the writes),
+        // BEFORE the ack: a client that holds the ack can reload and find the
+        // card spent. FAIL-OPEN, as on the tool path: a failed record is named
+        // and never withholds the ack. With no pipe entry (the frame did not
+        // parse as a dispatch) the spend is recorded held by nobody, as before.
         if (envelope.type === "data:submit" && activeItem !== undefined) {
             const payload = envelope.payload;
             if (payload !== null &&
@@ -235,6 +287,7 @@ export function createActionIngress(deps) {
                         render: activeItem,
                         action: payload.action,
                         data: payload.data,
+                        ...(entry !== null ? { actionId: entry.actionId, delivered: true } : {}),
                     });
                 }
                 catch (err) {
@@ -254,3 +307,38 @@ export function createActionIngress(deps) {
     }
     return { handleInboundAction };
 }
+async function claimChannelSpend(deps, sessionId, render, payload, actionId) {
+    const claimOnce = async (spend) => {
+        try {
+            return await recordCommittedOneShot({
+                store: deps.renderStore,
+                sessionId,
+                render,
+                action: payload.action,
+                data: payload.data,
+                ...spend,
+            });
+        }
+        catch (err) {
+            deps.logger.warn("render_channel_spent_oneshot_persist_failed", {
+                sessionId,
+                action: payload.action,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return undefined;
+        }
+    };
+    const first = await claimOnce({ actionId });
+    const claim = first?.claim;
+    if (claim === undefined || claim.outcome !== "already-spent" || claim.by === undefined || claim.by === actionId) {
+        return { kind: "proceed" };
+    }
+    if (claim.delivered === true)
+        return { kind: "refuse", by: claim.by };
+    const retaken = await claimOnce({ actionId, reclaimFrom: claim.by });
+    const second = retaken?.claim;
+    if (second === undefined || second.outcome !== "already-spent" || second.by === undefined || second.by === actionId) {
+        return { kind: "proceed" };
+    }
+    return { kind: "refuse", by: second.by };
+}

package/dist/ggui-session-channel/channel-subscriptions.d.ts

@@ -69,7 +69,6 @@ export interface ChannelSubscriptionsDeps {
      * subscriber.
      */
     readonly subscribersByWs: WeakMap<WebSocket, WsSubscriber>;
-    readonly send: Outbound["send"];
     readonly sendChannelError: Outbound["sendChannelError"];
 }
 export interface ChannelSubscriptions {

package/dist/ggui-session-channel/channel-subscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel-subscriptions.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/channel-subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAA4B,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAa9C;;;;;;;GAOG;AACH,MAAM,WAAW,mCAAmC;IAClD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,mCAAmC,GAAG,SAAS,CAAC;IACrE;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,sBAAsB,CACpB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,GACxD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;OAKG;IACH,wBAAwB,CACtB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,qBAAqB,CAAA;KAAE,GAC1D,IAAI,CAAC;CACT;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAiQ/F"}
+{"version":3,"file":"channel-subscriptions.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/channel-subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAA4B,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAa9C;;;;;;;GAOG;AACH,MAAM,WAAW,mCAAmC;IAClD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,mCAAmC,GAAG,SAAS,CAAC;IACrE;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAC3D,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,sBAAsB,CACpB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,GACxD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;OAKG;IACH,wBAAwB,CACtB,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,gBAAgB,GAAG;QAAE,IAAI,EAAE,qBAAqB,CAAA;KAAE,GAC1D,IAAI,CAAC;CACT;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,wBAAwB,GAAG,oBAAoB,CAoQ/F"}

package/dist/ggui-session-channel/channel-subscriptions.js

@@ -68,7 +68,10 @@ export function createChannelSubscriptions(deps) {
             if (sub.ws.readyState !== sub.ws.OPEN)
                 return;
             state.seq += 1;
-            deps.send(sub.ws, {
+            // Through the subscriber's sink, like every data-carrying writer,
+            // so a poll that lands while the subscribe tail is still writing
+            // its replay is held until after it (ggui#1525).
+            sub.sink.write({
                 type: "channel_payload",
                 payload: {
                     sessionId: sub.sessionId,

package/dist/ggui-session-channel/internal-types.d.ts

@@ -3,6 +3,7 @@
  * of the package's public surface — everything publishable is exported
  * (or re-exported) from `../ggui-session-channel.ts`.
  */
+import type { StreamReplayCursor } from './stream-epoch.js';
 import type { AuthResult, BufferedStreamEnvelope } from "@ggui-ai/mcp-server-core";
 import type { JsonObject } from "@ggui-ai/protocol";
 import type { WebSocketMessage } from "@ggui-ai/protocol/transport/websocket";
@@ -30,12 +31,16 @@ export interface SubscriberSink {
     }): void;
     /**
      * Terminate the transport. WS maps `service_restart` → close 1012
-     * (reconnect immediately — same server family is still up) and
+     * (reconnect immediately — same server family is still up),
      * `session_expired` → close 1008 (policy violation — do not blind-
-     * reconnect); SSE ends the response, letting `EventSource`
-     * auto-reconnect hit the HTTP pre-gate for the authoritative verdict.
+     * reconnect), and `internal_error` → close 1011 (the server could not
+     * complete the subscribe; a client reconnects with its ordinary
+     * backoff, since a failure that may repeat must not invite an
+     * immediate retry, ggui#1528). SSE ends the response for every reason,
+     * letting `EventSource` auto-reconnect hit the HTTP pre-gate for the
+     * authoritative verdict.
      */
-    end(reason: "service_restart" | "session_expired"): void;
+    end(reason: "service_restart" | "session_expired" | "internal_error"): void;
 }
 /**
  * Fields shared by every subscriber regardless of transport (one
@@ -48,16 +53,19 @@ interface SubscriberBase {
     readonly identity: AuthResult;
     readonly connectedAt: number;
     /**
-     * Largest outbound `seq` the initial replay (or subscribe snapshot)
-     * covered for this subscriber. Live fan-out skips envelopes with
-     * `seq <= replayCompletedSeq` to prevent double delivery — those
-     * were (or will be) delivered via the replay phase.
+     * The replay boundary: the largest outbound `seq` the initial replay
+     * (or subscribe snapshot) covered for this subscriber, and the epoch
+     * that `seq` counts in (ggui#1531). Live fan-out skips envelopes of the
+     * same epoch with `seq <= replayCursor.seq` to prevent double delivery,
+     * since those were (or will be) delivered via the replay phase. A live
+     * envelope of another epoch means the counter restarted: it is
+     * delivered and moves the cursor (`admitLiveEnvelope`).
      *
-     * For fresh subscribers (no `fromSeq`), this is the stream cursor
-     * at subscribe time; they never see the pre-existing buffer, only
-     * new deliveries.
+     * For fresh subscribers (no `fromSeq`), `seq` is the stream cursor at
+     * subscribe time; they never see the pre-existing buffer, only new
+     * deliveries.
      */
-    readonly replayCompletedSeq: number;
+    readonly replayCursor: StreamReplayCursor;
     /**
      * Per-subscriber live-tail iterator from `streamFanout.subscribe`.
      * Owned by the subscriber for its full lifetime; ending it (via

package/dist/ggui-session-channel/internal-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-types.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/internal-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,MAAM,IAAI,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5E;;;;;;OAMG;IACH,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,IAAI,CAAC;CAC1D;AAED;;;;GAIG;AACH,UAAU,cAAc;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;OASG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACrD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAC5D,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,aAAa,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;CAChD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,iBAAiB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D"}
+{"version":3,"file":"internal-types.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/internal-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,MAAM,IAAI,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5E;;;;;;;;;;OAUG;IACH,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,IAAI,CAAC;CAC7E;AAED;;;;GAIG;AACH,UAAU,cAAc;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACrD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAC5D,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;CAC3B;AAED,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,aAAa,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;CAChD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,iBAAiB,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D"}

package/dist/ggui-session-channel/outbound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"outbound.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/outbound.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"outbound.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/outbound.ts"],"names":[],"mappings":"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"}

package/dist/ggui-session-channel/outbound.js

@@ -11,6 +11,7 @@
  * `GguiSessionChannelServer` interface in `../ggui-session-channel.ts`;
  * inline comments here cover impl-level decisions only.
  */
+import { admitLiveEnvelope } from "./stream-epoch.js";
 import { assertStreamContract } from "@ggui-ai/mcp-server-handlers/renders";
 /**
  * Low-level ws wire write shared by the closure-bound `send` helper and
@@ -43,7 +44,7 @@ export function createWsSink(ws, logger) {
         },
         end: (reason) => {
             try {
-                ws.close(reason === "service_restart" ? 1012 : 1008, reason);
+                ws.close(reason === "service_restart" ? 1012 : reason === "internal_error" ? 1011 : 1008, reason);
             }
             catch {
                 /* best-effort — socket may already be closing */
@@ -204,11 +205,22 @@ export function createOutbound(deps) {
             // subscribe-replay (policy 'all'/'latest') or is deliberately
             // invisible to late subscribers (policy 'none') — never re-send.
             // Unstamped frames were never buffered; replay cannot duplicate
-            // them, so they pass. Non-data frames carry no seq semantics.
-            if (frame.type === "data" &&
-                typeof frame.payload.seq === "number" &&
-                frame.payload.seq <= sub.replayCompletedSeq) {
-                continue;
+            // them, so they pass. A frame of another epoch means the counter
+            // restarted: it passes and moves the subscriber's cursor, by the
+            // same rule as the pump (ggui#1531). Non-data frames carry no seq
+            // semantics.
+            if (frame.type === "data") {
+                const admission = admitLiveEnvelope(sub.replayCursor, frame.payload);
+                if (admission.epochChanged !== undefined) {
+                    deps.logger.info("stream_epoch_changed", {
+                        sessionId,
+                        from: admission.epochChanged.from,
+                        to: admission.epochChanged.to,
+                        transport: sub.transport,
+                    });
+                }
+                if (!admission.deliver)
+                    continue;
             }
             sub.sink.write(frame);
         }

package/dist/ggui-session-channel/stream-epoch.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The live tail's replay boundary, with the stream counter's epoch
+ * (ggui#1531). One rule, shared by the two places a live data frame is
+ * filtered against a subscriber's replay: the in-process pump
+ * (`subscriber-lifecycle.ts`) and the cross-replica direct walk
+ * (`outbound.ts`, `externalBroadcast`).
+ *
+ * A `seq` counts within one counter. When the counter restarts while a
+ * subscriber stays attached (a hosted counter evicted or expired, a
+ * server restarted over a persistent session store), the next frame
+ * arrives at a low `seq` with a new epoch. Filtering it by the old
+ * boundary would drop it, and every later one, with no signal: the
+ * frame of another epoch is delivered instead, and the subscriber moves
+ * to the new epoch with an empty boundary.
+ */
+/**
+ * A subscriber's replay boundary: the latest `seq` its snapshot and
+ * replay covered, and the epoch that `seq` counts in (`undefined` when
+ * the snapshot had none: no counter yet, or a buffer that predates
+ * epochs). Mutable: a live frame of another epoch moves it.
+ */
+export interface StreamReplayCursor {
+    seq: number;
+    epoch: string | undefined;
+    /**
+     * The epochs this cursor has moved away from, newest last, at most
+     * {@link RETIRED_EPOCHS_KEPT}. A late frame of one of them (a
+     * cross-replica frame published just before the restart) is dropped, so
+     * it cannot move the cursor back and empty its boundary again.
+     */
+    retired?: string[];
+}
+/** How many epochs a cursor remembers having left. */
+export declare const RETIRED_EPOCHS_KEPT = 4;
+/** What to do with one live data frame for one subscriber. */
+export interface LiveAdmission {
+    readonly deliver: boolean;
+    /** Set when the frame moved the subscriber to another epoch. */
+    readonly epochChanged?: {
+        readonly from: string;
+        readonly to: string;
+    };
+}
+/**
+ * Decide whether a live data frame reaches a subscriber, and move its
+ * cursor when the frame's epoch differs:
+ *   - an unstamped frame (no `seq`) was never buffered and always passes;
+ *   - a late frame of an epoch the cursor has left is dropped;
+ *   - a frame of another epoch than the cursor's is delivered, and the
+ *     cursor moves to that epoch with an empty boundary (a restart);
+ *   - the first epoch a cursor without one sees is adopted, and its seq
+ *     boundary stands (the snapshot simply had no epoch yet);
+ *   - otherwise a frame at or below the boundary was, or will be, sent
+ *     by the replay, and is skipped.
+ * An absent epoch on the frame is unknown, never a mismatch.
+ */
+export declare function admitLiveEnvelope(cursor: StreamReplayCursor, envelope: {
+    readonly seq?: number;
+    readonly streamEpoch?: string;
+}): LiveAdmission;
+//# sourceMappingURL=stream-epoch.d.ts.map

package/dist/ggui-session-channel/stream-epoch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-epoch.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/stream-epoch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACjE,aAAa,CAcf"}

package/dist/ggui-session-channel/stream-epoch.js

@@ -0,0 +1,47 @@
+/**
+ * The live tail's replay boundary, with the stream counter's epoch
+ * (ggui#1531). One rule, shared by the two places a live data frame is
+ * filtered against a subscriber's replay: the in-process pump
+ * (`subscriber-lifecycle.ts`) and the cross-replica direct walk
+ * (`outbound.ts`, `externalBroadcast`).
+ *
+ * A `seq` counts within one counter. When the counter restarts while a
+ * subscriber stays attached (a hosted counter evicted or expired, a
+ * server restarted over a persistent session store), the next frame
+ * arrives at a low `seq` with a new epoch. Filtering it by the old
+ * boundary would drop it, and every later one, with no signal: the
+ * frame of another epoch is delivered instead, and the subscriber moves
+ * to the new epoch with an empty boundary.
+ */
+/** How many epochs a cursor remembers having left. */
+export const RETIRED_EPOCHS_KEPT = 4;
+/**
+ * Decide whether a live data frame reaches a subscriber, and move its
+ * cursor when the frame's epoch differs:
+ *   - an unstamped frame (no `seq`) was never buffered and always passes;
+ *   - a late frame of an epoch the cursor has left is dropped;
+ *   - a frame of another epoch than the cursor's is delivered, and the
+ *     cursor moves to that epoch with an empty boundary (a restart);
+ *   - the first epoch a cursor without one sees is adopted, and its seq
+ *     boundary stands (the snapshot simply had no epoch yet);
+ *   - otherwise a frame at or below the boundary was, or will be, sent
+ *     by the replay, and is skipped.
+ * An absent epoch on the frame is unknown, never a mismatch.
+ */
+export function admitLiveEnvelope(cursor, envelope) {
+    if (envelope.seq === undefined)
+        return { deliver: true };
+    const epoch = envelope.streamEpoch;
+    if (epoch !== undefined && cursor.retired?.includes(epoch) === true)
+        return { deliver: false };
+    if (epoch !== undefined && epoch !== cursor.epoch) {
+        const from = cursor.epoch;
+        cursor.epoch = epoch;
+        if (from !== undefined) {
+            cursor.retired = [...(cursor.retired ?? []), from].slice(-RETIRED_EPOCHS_KEPT);
+            cursor.seq = 0;
+            return { deliver: true, epochChanged: { from, to: epoch } };
+        }
+    }
+    return { deliver: envelope.seq > cursor.seq };
+}

package/dist/ggui-session-channel/subscribe.d.ts

@@ -2,8 +2,8 @@
  * Subscribe / credential-path family for the live channel — upgrade-
  * time identity resolution across the three auth planes (bearer via
  * the AuthAdapter, ws-token bootstrap, console cookie) and the
- * `subscribe` handler itself: version handshake, bootstrap verify +
- * reconnect-credential mint, identity-default appId resolution,
+ * `subscribe` handler itself: version handshake, bootstrap verify,
+ * identity-default appId resolution,
  * dev-mode render provisioning, replay, registration, and the ack.
  */
 import type { AuthAdapter, AuthResult, GguiSessionStore, GguiSessionStreamBuffer, StoredGguiSession, StreamFanout } from "@ggui-ai/mcp-server-core";
@@ -25,10 +25,11 @@ import type { SubscriberLifecycle } from "./subscriber-lifecycle.js";
  *      (invalid sig, expired, wrong kind, replayed, etc.).
  *   2. The bound `sessionId` MUST match the one on the subscribe
  *      payload. Mismatches are rejected with a clean error.
- *   3. On success, the server mints a reconnect credential via
- *      `issueSessionToken(sessionId, appId)` and returns it in
- *      `AckPayload.sessionToken`. The iframe stores this for WS
- *      reconnects via the normal bearer path.
+ *   3. On success, the subscribe binds to that identity. No reconnect
+ *      credential is minted (ggui#1488): a reconnect presents a live
+ *      `wsToken` again, renewed before it expires through
+ *      `GET /api/sessions/:id/state`, or at any age through
+ *      `ggui_runtime_refresh_ws_token`.
  *
  * Bootstrap auth is MUTUALLY EXCLUSIVE with the upstream `AuthAdapter`
  * bearer path at subscribe time — when a bootstrap token is present,
@@ -67,12 +68,6 @@ export interface GguiSessionChannelBootstrap {
      * kind failures.
      */
     verify(token: string): GguiSessionChannelBootstrapVerifyResult;
-    /**
-     * Mint a longer-lived reconnect credential to return in
-     * `AckPayload.sessionToken`. Called only after a successful
-     * `verify()` on a bootstrap subscribe.
-     */
-    issueSessionToken(sessionId: string, appId: string): string;
 }
 /**
  * Cookie-based authentication for the live-channel upgrade. Used
@@ -128,6 +123,12 @@ export interface SubscribeDeps {
  * `/api/sessions/:sessionId/stream`) runs BEFORE this; the tail trusts
  * `stored` + `identity` as already-authorized.
  */
+/**
+ * A subscribe's credential when it is not the auth adapter's bearer
+ * (ggui#1488): a `wsToken`, or the console cookie. Logged as
+ * `render_channel_subscribed.source`.
+ */
+export type SubscribeCredential = "ws_token" | "console_cookie";
 export type CompleteSubscribeArgs = {
     /** Resolved render row the subscriber binds to. */
     readonly stored: StoredGguiSession;
@@ -139,10 +140,17 @@ export type CompleteSubscribeArgs = {
     readonly sinceSequence?: number;
     /** Stream-buffer cursor — replays `data` frames per policy when set. */
     readonly fromSeq?: number;
+    /** The epoch `fromSeq` was counted in (ggui#1531); read only beside it. */
+    readonly fromEpoch?: string;
     /** Correlates the ack / error frames to a WS request. SSE has none. */
     readonly requestId?: string;
-    /** Bootstrap-minted reconnect credential to stamp on the ack. */
-    readonly sessionToken?: string;
+    /**
+     * The credential the subscribe came on, when it is not the auth
+     * adapter's bearer: a `wsToken` (the bootstrap path, on the WebSocket or
+     * the SSE stream) or the console cookie. Both resolve to a synthetic
+     * identity whose own `source` would misreport them.
+     */
+    readonly credential?: SubscribeCredential;
 } & ({
     readonly transport: "ws";
     /** The socket — kept on the subscriber row for inbound dispatch. */
@@ -168,9 +176,13 @@ export interface SubscribeHandlers {
     /**
      * The transport-neutral subscribe tail, order preserved exactly:
      * stream-cursor snapshot → stream-buffer replay read → StreamFanout
-     * iterator → register (pump starts) → ack → GguiSessionEvent-ledger
-     * replay (`render_event` frames, `resumeId` = ledger seq) →
-     * stream-replay `data` frames. WS `handleSubscribe` calls this after
+     * iterator → register (pump starts; every write to the subscriber's
+     * sink is held until the replay below is written, ggui#1525) → the
+     * first GguiSessionEvent-ledger page read, when `sinceSequence` is set
+     * (before the ack, so a failed read sends none, ggui#1528) → ack →
+     * ledger replay (`render_event` frames, `resumeId` = ledger seq; later
+     * pages read as they go) → stream-replay `data` frames → release of the
+     * held frames. WS `handleSubscribe` calls this after
      * its auth/provision head; SSE attaches call it via
      * `GguiSessionChannelServer.attachExternalSubscriber`.
      *

package/dist/ggui-session-channel/subscribe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscribe.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/subscribe.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subscribe.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/subscribe.ts"],"names":[],"mappings":"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"}