commandmate 0.47.2 → 0.49.0

package/dist/server/src/lib/session/waiting-episode-binding.js

@@ -0,0 +1,276 @@
+"use strict";
+/**
+ * Which turn a waiting episode belongs to, and what the turn transitions do to
+ * it (Issue #3798).
+ *
+ * The episode store (`waiting-episode-state`) knows when a wait began and what
+ * it is bound to; the turn model (`agent-event-turn`) knows how each delivery
+ * moved the instance's turn. This module joins the two:
+ *
+ *  - {@link resolveEpisodeBinding} decides what a new episode is bound to, from
+ *    the turn model as it stands (design §2.4 規則 1). It is registered with the
+ *    store, so an episode `observeWaitingEdge` opens is bound like any other.
+ *  - {@link applyTurnOutcomesToEpisode} is the T table (design §2.4): what a
+ *    transition's outcome does to the open episode. It runs in the synchronous
+ *    step that recorded the delivery (`recordAgentEvent`'s end,
+ *    `beginAgentEventGeneration`, the two `report*Pending`, the duplicate-window
+ *    restore) and never after an `await`, so a closer that resumes later
+ *    cannot reach a wait that opened meanwhile (design §2.5).
+ *  - {@link captureLegacyStopTarget} / {@link settleLegacyStop} are the one
+ *    closer that cannot be synchronous: `/api/hooks/claude-done` names no
+ *    session and awaits a capture and a log before it is done (design 規則 6).
+ *  - {@link planWaitingObservation} / {@link commitWaitingObservation} are the
+ *    tables O-1 and O-2 (design §2.4 規則 3・4・5): what one observer's reading
+ *    of a frame does to the open episode. The three observers — the status
+ *    probe, the response poller and the Auto-Yes poller — fix an
+ *    {@link ObservationStart} before their first `await` and are refused when
+ *    the episode moved meanwhile (I5 (b)), or when the frame was fetched
+ *    before the close of the very confirmation it shows (I6).
+ *
+ * The store is a leaf and does not import this module; this module registers
+ * itself with the store and with the turn model through `globalThis` when it is
+ * loaded. `agent-event-state` imports it, and so does every module that calls
+ * the observation functions — the resolver is registered by the import that
+ * uses it, not by a transitive one (design R2-10, PR 1a review P3-2).
+ *
+ * Design: `docs/design/issue-3798-waiting-episode.md`.
+ *
+ * @module lib/session/waiting-episode-binding
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startWorktreeWaitingObservations = exports.startWaitingObservation = exports.planWaitingObservation = exports.captureObservedFrame = exports.captureFrameTime = exports.resolveEpisodeBinding = exports.verdictForOutcome = void 0;
+exports.applyTurnOutcomesToEpisode = applyTurnOutcomesToEpisode;
+exports.commitWaitingObservation = commitWaitingObservation;
+exports.observeWaiting = observeWaiting;
+exports.captureLegacyStopTarget = captureLegacyStopTarget;
+exports.settleLegacyStop = settleLegacyStop;
+exports.clearWaitingEpisodeBindingState = clearWaitingEpisodeBindingState;
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+const logger_1 = require("../../lib/logger");
+const agent_event_turn_1 = require("../../lib/session/agent-event-turn");
+const waiting_episode_binding_observation_1 = require("../../lib/session/waiting-episode-binding-observation");
+const waiting_episode_binding_resolve_1 = require("../../lib/session/waiting-episode-binding-resolve");
+Object.defineProperty(exports, "resolveEpisodeBinding", { enumerable: true, get: function () { return waiting_episode_binding_resolve_1.resolveEpisodeBinding; } });
+const waiting_episode_state_1 = require("../../lib/session/waiting-episode-state");
+const waiting_episode_verdict_1 = require("../../lib/session/waiting-episode-verdict");
+Object.defineProperty(exports, "verdictForOutcome", { enumerable: true, get: function () { return waiting_episode_verdict_1.verdictForOutcome; } });
+const global_state_1 = require("../global-state");
+const logger = (0, logger_1.createLogger)('waiting-episode-binding');
+/**
+ * compositeKey -> the generation in which a structured `stop` was last
+ * applied. While it names the current generation, the agent's own hook speaks
+ * for the end of its turns and `claude-done` does not close (規則 6).
+ */
+const hookStopGeneration = (0, global_state_1.getOrInitGlobal)('__waitingHookStopGeneration', () => new Map());
+/** Mark that the agent's own hook reported a stop in this generation (規則 6). */
+function noteHookStop(key, outcome) {
+    if (outcome.kind === 'stopped' || outcome.kind === 'stop-without-turn') {
+        hookStopGeneration.set(key, outcome.generation);
+    }
+}
+function applyVerdict(parts, episode, outcome, verdict, at) {
+    const base = { outcome: outcome.kind, episodeId: episode.episodeId };
+    if (verdict.action === 'close') {
+        const closed = (0, waiting_episode_state_1.closeEpisode)(parts, episode.episodeId, verdict.reason, at);
+        if (closed) {
+            logger.info('waiting-episode-closed-by-turn', {
+                worktreeId: parts.worktreeId,
+                cliToolId: parts.cliToolId,
+                instanceId: parts.instanceId ?? parts.cliToolId,
+                episodeId: episode.episodeId,
+                outcome: outcome.kind,
+                reason: verdict.reason,
+            });
+        }
+        return { ...base, action: closed ? 'closed' : 'none', ...(closed ? { reason: verdict.reason } : {}) };
+    }
+    if (verdict.action === 'rebind') {
+        const rebound = (0, waiting_episode_state_1.rebindEpisode)(parts, episode.episodeId, verdict.binding, at);
+        if (rebound) {
+            logger.debug('waiting-episode-rebound', {
+                worktreeId: parts.worktreeId,
+                instanceId: parts.instanceId ?? parts.cliToolId,
+                episodeId: episode.episodeId,
+                outcome: outcome.kind,
+                binding: verdict.binding.kind,
+            });
+        }
+        return { ...base, action: rebound ? 'rebound' : 'none' };
+    }
+    if (verdict.action === 'unmatched') {
+        logger.warn('waiting-episode-unmatched', {
+            worktreeId: parts.worktreeId,
+            instanceId: parts.instanceId ?? parts.cliToolId,
+            episodeId: episode.episodeId,
+            outcome: outcome.kind,
+            binding: episode.binding.kind,
+        });
+    }
+    return { ...base, action: 'none' };
+}
+/**
+ * Apply a delivery's transition outcomes to the instance's open episode
+ * (Issue #3798, design §2.4 T table), in order.
+ *
+ * Called in the synchronous step that produced the outcomes. Never throws: the
+ * turn has been recorded already, and a failure here must not cost the hook
+ * its answer (design §2.6). An episode it leaves open is still closed by the
+ * screen observers.
+ *
+ * @param at - Epoch ms of the change; defaults to now
+ */
+function applyTurnOutcomesToEpisode(parts, outcomes, at = Date.now()) {
+    const effects = [];
+    try {
+        const key = (0, auto_yes_state_1.buildCompositeKey)(parts.worktreeId, parts.cliToolId, parts.instanceId);
+        for (const outcome of outcomes) {
+            noteHookStop(key, outcome);
+            const episode = (0, waiting_episode_state_1.getWaitingEpisodeRecord)(parts.worktreeId, parts.cliToolId, parts.instanceId);
+            if (episode === null) {
+                effects.push({ outcome: outcome.kind, action: 'none', episodeId: null });
+                continue;
+            }
+            const verdict = (0, waiting_episode_verdict_1.verdictForOutcome)(outcome, episode.binding, (0, waiting_episode_binding_resolve_1.generationOf)(parts));
+            effects.push(applyVerdict(parts, episode, outcome, verdict, at));
+        }
+    }
+    catch (error) {
+        logger.warn('waiting-episode-turn-sync-failed', {
+            worktreeId: parts.worktreeId,
+            instanceId: parts.instanceId ?? parts.cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return effects;
+}
+var waiting_episode_binding_observation_2 = require("../../lib/session/waiting-episode-binding-observation");
+Object.defineProperty(exports, "captureFrameTime", { enumerable: true, get: function () { return waiting_episode_binding_observation_2.captureFrameTime; } });
+Object.defineProperty(exports, "captureObservedFrame", { enumerable: true, get: function () { return waiting_episode_binding_observation_2.captureObservedFrame; } });
+Object.defineProperty(exports, "planWaitingObservation", { enumerable: true, get: function () { return waiting_episode_binding_observation_2.planWaitingObservation; } });
+Object.defineProperty(exports, "startWaitingObservation", { enumerable: true, get: function () { return waiting_episode_binding_observation_2.startWaitingObservation; } });
+Object.defineProperty(exports, "startWorktreeWaitingObservations", { enumerable: true, get: function () { return waiting_episode_binding_observation_2.startWorktreeWaitingObservations; } });
+/**
+ * Carry out a plan (design I5 (b)). Each write names the episode the plan was
+ * made about, so a plan committed late changes nothing that moved since.
+ *
+ * @returns What was done — `ignored` also when the episode moved after the plan
+ */
+function commitWaitingObservation(plan) {
+    const obs = plan.observation;
+    const parts = { worktreeId: obs.worktreeId, cliToolId: obs.cliToolId, instanceId: obs.instanceId };
+    try {
+        switch (plan.action) {
+            case 'kept':
+                if (plan.episodeId === null || obs.reading.kind !== 'waiting')
+                    return 'ignored';
+                return (0, waiting_episode_state_1.updateEpisodeKind)(parts, plan.episodeId, obs.reading.waitingKind) ? 'kept' : 'ignored';
+            case 'opened':
+                if (plan.next === null || (0, waiting_episode_state_1.getWaitingEpisodeRecord)(obs.worktreeId, obs.cliToolId, obs.instanceId) !== null) {
+                    return 'ignored';
+                }
+                (0, waiting_episode_state_1.openEpisode)(parts, plan.next, plan.at);
+                return 'opened';
+            case 'replaced':
+                if (plan.next === null || plan.episodeId === null || plan.closeReason === null)
+                    return 'ignored';
+                return (0, waiting_episode_state_1.replaceEpisode)(parts, plan.episodeId, plan.next, plan.closeReason, plan.at) !== null
+                    ? 'replaced'
+                    : 'ignored';
+            case 'rebound':
+                if (plan.binding === null || plan.episodeId === null)
+                    return 'ignored';
+                return (0, waiting_episode_state_1.rebindEpisode)(parts, plan.episodeId, plan.binding, plan.at) ? 'rebound' : 'ignored';
+            case 'closed':
+                if (plan.episodeId === null || plan.closeReason === null)
+                    return 'ignored';
+                return (0, waiting_episode_state_1.closeEpisode)(parts, plan.episodeId, plan.closeReason, plan.at) ? 'closed' : 'ignored';
+            case 'ignored':
+                if (plan.ignoredBecause === 'version' || plan.ignoredBecause === 'stale-frame' || plan.ignoredBecause === 'generation') {
+                    logger.debug('waiting-observation-ignored', {
+                        worktreeId: obs.worktreeId,
+                        instanceId: obs.instanceId ?? obs.cliToolId,
+                        observer: obs.observer,
+                        reading: obs.reading.kind,
+                        because: plan.ignoredBecause,
+                    });
+                }
+                return 'ignored';
+            default:
+                plan.action;
+                return 'ignored';
+        }
+    }
+    catch (error) {
+        logger.warn('waiting-observation-failed', {
+            worktreeId: obs.worktreeId,
+            instanceId: obs.instanceId ?? obs.cliToolId,
+            observer: obs.observer,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return 'ignored';
+    }
+}
+/** {@link planWaitingObservation} and {@link commitWaitingObservation} in one step; the plan with what was done. */
+function observeWaiting(obs) {
+    const plan = (0, waiting_episode_binding_observation_1.planWaitingObservation)(obs);
+    const action = commitWaitingObservation(plan);
+    return action === plan.action ? plan : { ...plan, action };
+}
+/**
+ * Fix the episode a legacy (`claude-done`) stop is about, before its first
+ * capture `await` (design 規則 6). The body read before it cannot be helped: the
+ * worktree id is in the body — a known limit (design §8).
+ */
+function captureLegacyStopTarget(worktreeId, cliToolId, instanceId) {
+    const parts = { worktreeId, cliToolId, instanceId };
+    return {
+        generation: (0, waiting_episode_binding_resolve_1.generationOf)(parts),
+        episodeId: (0, waiting_episode_state_1.getWaitingEpisodeRecord)(worktreeId, cliToolId, instanceId)?.episodeId ?? null,
+    };
+}
+/**
+ * Close the episode a legacy stop was fixed on, if it is still the open one
+ * (design 規則 6). Nothing when the hook reported a stop in this generation
+ * (the hook speaks for the end of turns; closing again is the double close the
+ * rule forbids), when another episode opened meanwhile, or for a screen only a
+ * person drives.
+ *
+ * @param at - Epoch ms; defaults to now
+ */
+function settleLegacyStop(worktreeId, cliToolId, instanceId, target, at = Date.now()) {
+    try {
+        const parts = { worktreeId, cliToolId, instanceId };
+        const key = (0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId);
+        const episode = (0, waiting_episode_state_1.getWaitingEpisodeRecord)(worktreeId, cliToolId, instanceId);
+        if (episode === null)
+            return 'nothing-open';
+        const current = (0, waiting_episode_binding_resolve_1.generationOf)(parts);
+        if (target.episodeId === null ||
+            episode.episodeId !== target.episodeId ||
+            !(0, waiting_episode_verdict_1.sameGeneration)(target.generation, current)) {
+            return 'target-gone';
+        }
+        const hookStop = hookStopGeneration.get(key);
+        if (hookStop !== undefined && (0, waiting_episode_verdict_1.sameGeneration)(hookStop, current))
+            return 'hook-authority';
+        if (episode.binding.kind === 'screen')
+            return 'screen';
+        return (0, waiting_episode_state_1.closeEpisode)(parts, episode.episodeId, 'legacy-stop', at) ? 'closed' : 'target-gone';
+    }
+    catch (error) {
+        logger.warn('waiting-episode-legacy-stop-failed', {
+            worktreeId,
+            instanceId: instanceId ?? cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return 'nothing-open';
+    }
+}
+/** Forget the hook-stop marks. Test seam, called by `clearAgentStopEvents`. */
+function clearWaitingEpisodeBindingState() {
+    hookStopGeneration.clear();
+}
+(0, waiting_episode_state_1.registerEpisodeBindingResolver)(waiting_episode_binding_resolve_1.resolveEpisodeBinding);
+(0, agent_event_turn_1.registerTurnOutcomeSink)((parts, outcomes) => {
+    applyTurnOutcomesToEpisode(parts, outcomes);
+});

package/dist/server/src/lib/session/waiting-episode-state-ops.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * The low-level episode writes: open / close / replace / rebind / updateKind
+ * (Issue #3798). Each one emits through the store's listeners.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openEpisode = openEpisode;
+exports.closeEpisode = closeEpisode;
+exports.replaceEpisode = replaceEpisode;
+exports.rebindEpisode = rebindEpisode;
+exports.updateEpisodeKind = updateEpisodeKind;
+const waiting_episode_state_store_1 = require("../../lib/session/waiting-episode-state-store");
+/**
+ * Open an episode (Issue #3798). Low-level: the caller has decided there is
+ * none open and what it is bound to. Emits the opening edge.
+ */
+function openEpisode(parts, next, at) {
+    const key = (0, waiting_episode_state_store_1.keyOf)(parts);
+    const view = { since: next.since, kind: next.kind };
+    const meta = {
+        episodeId: (0, waiting_episode_state_store_1.nextEpisodeId)(),
+        openedAt: at,
+        boundAt: at,
+        binding: next.binding,
+        openedBy: next.openedBy,
+        promptScreenKey: next.promptScreenKey ?? null,
+    };
+    waiting_episode_state_store_1.episodes.set(key, view);
+    waiting_episode_state_store_1.metas.set(view, meta);
+    (0, waiting_episode_state_store_1.bumpVersion)(key);
+    (0, waiting_episode_state_store_1.emit)({
+        worktreeId: parts.worktreeId,
+        cliToolId: parts.cliToolId,
+        instanceId: parts.instanceId,
+        waiting: true,
+        since: view.since,
+        kind: view.kind,
+        at,
+        cause: 'opened',
+        episodeId: meta.episodeId,
+        previousEpisodeId: null,
+        closeReason: null,
+    });
+    return { ...view, ...meta };
+}
+/**
+ * Close the open episode when it is still `expectedId` (Issue #3798). A closer
+ * that names the episode it decided about cannot close a later one.
+ *
+ * @returns Whether an episode was closed
+ */
+function closeEpisode(parts, expectedId, reason, at) {
+    const key = (0, waiting_episode_state_store_1.keyOf)(parts);
+    const view = waiting_episode_state_store_1.episodes.get(key);
+    if (view === undefined)
+        return false;
+    const meta = (0, waiting_episode_state_store_1.metaOf)(view);
+    if (meta.episodeId !== expectedId)
+        return false;
+    waiting_episode_state_store_1.episodes.delete(key);
+    waiting_episode_state_store_1.lastClosed.set(key, { at, promptScreenKey: meta.promptScreenKey });
+    (0, waiting_episode_state_store_1.bumpVersion)(key);
+    (0, waiting_episode_state_store_1.emit)({
+        worktreeId: parts.worktreeId,
+        cliToolId: parts.cliToolId,
+        instanceId: parts.instanceId,
+        waiting: false,
+        since: null,
+        kind: null,
+        at,
+        cause: 'closed',
+        episodeId: null,
+        previousEpisodeId: meta.episodeId,
+        closeReason: reason,
+    });
+    return true;
+}
+/**
+ * Put a new episode in place of `expectedId` as one operation (Issue #3798):
+ * listeners hear a single opening edge for the new wait and no closing one
+ * in between, so nothing reports "nobody is waiting" mid-swap.
+ *
+ * @returns The new episode, or null when `expectedId` is no longer open
+ */
+function replaceEpisode(parts, expectedId, next, reason, at) {
+    const key = (0, waiting_episode_state_store_1.keyOf)(parts);
+    const old = waiting_episode_state_store_1.episodes.get(key);
+    if (old === undefined)
+        return null;
+    const oldMeta = (0, waiting_episode_state_store_1.metaOf)(old);
+    if (oldMeta.episodeId !== expectedId)
+        return null;
+    waiting_episode_state_store_1.lastClosed.set(key, { at, promptScreenKey: oldMeta.promptScreenKey });
+    const view = { since: next.since, kind: next.kind };
+    const meta = {
+        episodeId: (0, waiting_episode_state_store_1.nextEpisodeId)(),
+        openedAt: at,
+        boundAt: at,
+        binding: next.binding,
+        openedBy: next.openedBy,
+        promptScreenKey: next.promptScreenKey ?? null,
+    };
+    waiting_episode_state_store_1.episodes.set(key, view);
+    waiting_episode_state_store_1.metas.set(view, meta);
+    (0, waiting_episode_state_store_1.bumpVersion)(key);
+    (0, waiting_episode_state_store_1.emit)({
+        worktreeId: parts.worktreeId,
+        cliToolId: parts.cliToolId,
+        instanceId: parts.instanceId,
+        waiting: true,
+        since: view.since,
+        kind: view.kind,
+        at,
+        cause: 'replaced',
+        episodeId: meta.episodeId,
+        previousEpisodeId: oldMeta.episodeId,
+        closeReason: reason,
+    });
+    return { ...view, ...meta };
+}
+/**
+ * Change what the open episode `expectedId` is bound to (Issue #3798). Not an
+ * edge: the wait goes on, so nothing is emitted and `since` stays.
+ *
+ * @returns Whether the episode was rebound
+ */
+function rebindEpisode(parts, expectedId, binding, at) {
+    const key = (0, waiting_episode_state_store_1.keyOf)(parts);
+    const view = waiting_episode_state_store_1.episodes.get(key);
+    if (view === undefined)
+        return false;
+    const meta = (0, waiting_episode_state_store_1.metaOf)(view);
+    if (meta.episodeId !== expectedId)
+        return false;
+    meta.binding = binding;
+    meta.boundAt = at;
+    (0, waiting_episode_state_store_1.bumpVersion)(key);
+    return true;
+}
+/**
+ * Refresh the kind of the open episode `expectedId` (Issue #3798, I10). The
+ * wait goes on: no edge, and the version does not move.
+ *
+ * @returns Whether the episode was still open
+ */
+function updateEpisodeKind(parts, expectedId, kind) {
+    const view = waiting_episode_state_store_1.episodes.get((0, waiting_episode_state_store_1.keyOf)(parts));
+    if (view === undefined || (0, waiting_episode_state_store_1.metaOf)(view).episodeId !== expectedId)
+        return false;
+    view.kind = kind;
+    return true;
+}

package/dist/server/src/lib/session/waiting-episode-state-store.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * The waiting-episode store's state tables, its listeners and the reads
+ * (Issue #1786 / #3798). The single place that initialises each `globalThis` slot.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNKNOWN_BINDING = exports.lastClosed = exports.metas = exports.episodes = void 0;
+exports.nextEpisodeId = nextEpisodeId;
+exports.keyOf = keyOf;
+exports.bumpVersion = bumpVersion;
+exports.onWaitingTransition = onWaitingTransition;
+exports.onWaitingEpisodeTransition = onWaitingEpisodeTransition;
+exports.emit = emit;
+exports.metaOf = metaOf;
+exports.getWaitingEpisodeRecord = getWaitingEpisodeRecord;
+exports.getEpisodeVersion = getEpisodeVersion;
+exports.snapshotEpisodeVersions = snapshotEpisodeVersions;
+exports.getLastClosedEpisode = getLastClosedEpisode;
+exports.getWaitingEpisode = getWaitingEpisode;
+exports.hasOpenWaitingEpisode = hasOpenWaitingEpisode;
+exports.clearWaitingEpisodes = clearWaitingEpisodes;
+exports.clearWaitingTransitionListeners = clearWaitingTransitionListeners;
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+const logger_1 = require("../../lib/logger");
+const global_state_1 = require("../global-state");
+const logger = (0, logger_1.createLogger)('waiting-episode-state');
+/** compositeKey -> the wait currently in progress for that instance. */
+exports.episodes = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodes', () => new Map());
+/** Subscribers to the edge. See the module docblock. */
+const listeners = (0, global_state_1.getOrInitGlobal)('__sessionWaitingTransitionListeners', () => new Set());
+exports.metas = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeMeta', () => new WeakMap());
+const versions = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeVersions', () => new Map());
+exports.lastClosed = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeLastClosed', () => new Map());
+const episodeSeq = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeSeq', () => ({
+    value: 0,
+    nonce: Math.random().toString(36).slice(2, 10),
+}));
+const episodeListeners = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeListeners', () => new Set());
+/** The binding used when no resolver is registered: nothing is known. */
+exports.UNKNOWN_BINDING = {
+    kind: 'unattributed',
+    generation: { kind: 'none' },
+    lastClosedTurnId: null,
+};
+function nextEpisodeId() {
+    episodeSeq.value += 1;
+    return `wep-${episodeSeq.nonce}-${episodeSeq.value}`;
+}
+function keyOf(parts) {
+    return (0, auto_yes_state_1.buildCompositeKey)(parts.worktreeId, parts.cliToolId, parts.instanceId);
+}
+function bumpVersion(key) {
+    versions.set(key, (versions.get(key) ?? 0) + 1);
+}
+/**
+ * Subscribe to waiting edges.
+ *
+ * @returns An unsubscribe function. Idempotent — calling it twice is harmless.
+ */
+function onWaitingTransition(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+/**
+ * Subscribe to waiting edges with the episode's identity (Issue #3798).
+ *
+ * The same crossings `onWaitingTransition` delivers, in the same order, with
+ * the cause, the episode ids and the close reason added.
+ */
+function onWaitingEpisodeTransition(listener) {
+    episodeListeners.add(listener);
+    return () => {
+        episodeListeners.delete(listener);
+    };
+}
+/** Notify subscribers, containing anything they throw. */
+function emit(transition) {
+    const { cause: _cause, episodeId: _id, previousEpisodeId: _prev, closeReason: _reason, ...plain } = transition;
+    for (const listener of listeners) {
+        try {
+            listener(plain);
+        }
+        catch (error) {
+            logListenerFailure(transition, error);
+        }
+    }
+    for (const listener of episodeListeners) {
+        try {
+            listener(transition);
+        }
+        catch (error) {
+            logListenerFailure(transition, error);
+        }
+    }
+}
+function logListenerFailure(transition, error) {
+    logger.error('waiting-transition-listener-failed', {
+        worktreeId: transition.worktreeId,
+        cliToolId: transition.cliToolId,
+        instanceId: transition.instanceId ?? transition.cliToolId,
+        waiting: transition.waiting,
+        error: error instanceof Error ? error.message : String(error),
+    });
+}
+/**
+ * The meta of an episode in the map. An episode put there without one (a test
+ * that wrote the map directly) is given an unattributed identity on first read.
+ */
+function metaOf(view) {
+    let meta = exports.metas.get(view);
+    if (meta === undefined) {
+        meta = {
+            episodeId: nextEpisodeId(),
+            openedAt: view.since,
+            boundAt: view.since,
+            binding: exports.UNKNOWN_BINDING,
+            openedBy: 'legacy-edge',
+            promptScreenKey: null,
+        };
+        exports.metas.set(view, meta);
+    }
+    return meta;
+}
+/** The open episode with its identity and binding, or null (Issue #3798). */
+function getWaitingEpisodeRecord(worktreeId, cliToolId, instanceId) {
+    const view = exports.episodes.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId));
+    if (view === undefined)
+        return null;
+    const meta = metaOf(view);
+    return { since: view.since, kind: view.kind, ...meta, binding: meta.binding };
+}
+/** The instance's episode version: it moves on every open, close, replacement and rebind. */
+function getEpisodeVersion(worktreeId, cliToolId, instanceId) {
+    return versions.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? 0;
+}
+/**
+ * Every instance version of one worktree, as of now (Issue #3798): the status
+ * probe fixes them before it lists the tmux sessions. An instance missing from
+ * the map is at version 0.
+ */
+function snapshotEpisodeVersions(worktreeId) {
+    const prefix = `${worktreeId}${auto_yes_state_1.COMPOSITE_KEY_SEPARATOR}`;
+    const snapshot = new Map();
+    for (const [key, version] of versions) {
+        if (key.startsWith(prefix))
+            snapshot.set(key, version);
+    }
+    return snapshot;
+}
+/** The last episode that ended for this instance, or null. */
+function getLastClosedEpisode(worktreeId, cliToolId, instanceId) {
+    return exports.lastClosed.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? null;
+}
+/**
+ * @returns The wait in progress for this instance, or null when it is not
+ *   waiting. Read-only: observing the edge is {@link observeWaitingEdge}'s job.
+ */
+function getWaitingEpisode(worktreeId, cliToolId, instanceId) {
+    return exports.episodes.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? null;
+}
+/**
+ * Whether **any** instance in this worktree is still waiting (Issue #2001).
+ *
+ * The cross-device dismissal is keyed on the worktree, because that is what the
+ * Service Worker `tag` names (`<worktreeId>:prompt`, `push-sender`): two agent
+ * instances waiting in one worktree share a single notification card on the
+ * phone. So one instance crossing the closing edge is not on its own a reason
+ * to clear that card — the card is still telling the truth until the last of
+ * them has been answered.
+ *
+ * The prefix test is exact rather than heuristic: `buildCompositeKey` puts the
+ * worktree id first and rejects a worktree id containing
+ * {@link COMPOSITE_KEY_SEPARATOR}, so no other worktree's key can start with
+ * `<worktreeId>:`.
+ */
+function hasOpenWaitingEpisode(worktreeId) {
+    const prefix = `${worktreeId}${auto_yes_state_1.COMPOSITE_KEY_SEPARATOR}`;
+    for (const key of exports.episodes.keys()) {
+        if (key.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Drop every episode. Test seam.
+ *
+ * CI runs with `fileParallelism: false`, so one process holds this map for the
+ * whole suite: a test that opens an episode and does not clear it hands the next
+ * file a session that is already waiting.
+ */
+function clearWaitingEpisodes() {
+    exports.episodes.clear();
+    versions.clear();
+    exports.lastClosed.clear();
+}
+/** Drop every subscriber. Test seam, paired with {@link clearWaitingEpisodes}. */
+function clearWaitingTransitionListeners() {
+    listeners.clear();
+    episodeListeners.clear();
+}

package/dist/server/src/lib/session/waiting-episode-state-types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * The types of the waiting-episode store (Issue #1786 / #3798). No runtime
+ * state lives here; `waiting-episode-state` re-exports every public name.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });