commandmate 0.47.0 → 0.48.0

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

@@ -0,0 +1,289 @@
+"use strict";
+/**
+ * The observation half of `waiting-episode-binding` (Issue #3798): the
+ * observers' starts, the dating of a captured frame, and the plan of tables
+ * O-1 / O-2. Split out of `waiting-episode-binding` (Issue #3892), which
+ * re-exports all of it and carries the plan out (`commitWaitingObservation`).
+ *
+ * @module lib/session/waiting-episode-binding-observation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startWaitingObservation = startWaitingObservation;
+exports.startWorktreeWaitingObservations = startWorktreeWaitingObservations;
+exports.captureFrameTime = captureFrameTime;
+exports.captureObservedFrame = captureObservedFrame;
+exports.planWaitingObservation = planWaitingObservation;
+const async_hooks_1 = require("async_hooks");
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+const prompt_screen_key_1 = require("../../lib/detection/prompt-screen-key");
+const agent_event_turn_1 = require("../../lib/session/agent-event-turn");
+const waiting_episode_binding_resolve_1 = require("../../lib/session/waiting-episode-binding-resolve");
+const waiting_episode_state_1 = require("../../lib/session/waiting-episode-state");
+const waiting_episode_verdict_1 = require("../../lib/session/waiting-episode-verdict");
+const global_state_1 = require("../global-state");
+/** Where `cli-session` reports a frame's source to the observer it runs for (Issue #3798). */
+function frameMetaSink() {
+    return (0, global_state_1.getOrInitGlobal)('__captureFrameMetaSink', () => new async_hooks_1.AsyncLocalStorage());
+}
+/** Fix the observer's start (design §2.5). Read-only. */
+function startWaitingObservation(worktreeId, cliToolId, instanceId) {
+    return {
+        generation: (0, waiting_episode_binding_resolve_1.generationOf)({ worktreeId, cliToolId, instanceId }),
+        version: (0, waiting_episode_state_1.getEpisodeVersion)(worktreeId, cliToolId, instanceId),
+    };
+}
+/**
+ * Fix the start of every instance of a worktree at once (design §2.5): the
+ * status routes call it before `listSessions()`, so a session that started —
+ * and opened a wait — after the list was taken is not closed as gone by a
+ * probe that did not see it. Instances that have no version or generation yet
+ * are fixed at 0 / none.
+ */
+function startWorktreeWaitingObservations(worktreeId) {
+    const prefix = `${worktreeId}${auto_yes_state_1.COMPOSITE_KEY_SEPARATOR}`;
+    const versions = (0, waiting_episode_state_1.snapshotEpisodeVersions)(worktreeId);
+    const generations = new Map();
+    for (const [key, at] of agent_event_turn_1.generationStartedAt) {
+        if (key.startsWith(prefix))
+            generations.set(key, at);
+    }
+    return {
+        startFor(cliToolId, instanceId) {
+            const key = (0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId);
+            return { generation: (0, agent_event_turn_1.toGenerationRef)(generations.get(key) ?? null), version: versions.get(key) ?? 0 };
+        },
+    };
+}
+/**
+ * When the frame a scraper just read was fetched (design §2.2
+ * `frameCapturedAt`), from `meta` — what the capture reported for that one
+ * frame ({@link captureObservedFrame}). A frame served from the cache, or
+ * joined to a fetch already in flight, is as old as that fetch, and is never
+ * one this observer fetched itself — even when that fetch started in the very
+ * millisecond the observer asked. Only a frame the capture fetched itself,
+ * starting at or after `requestedAt` (the moment the observer asked, after its
+ * start), counts as fetched after the start. A frame nothing was reported for
+ * (a capture module a test replaced) is dated 0, before any close (design
+ * §2.6): it opens no wait I6 would hold back, and closes no `screen`.
+ */
+function captureFrameTime(meta, requestedAt) {
+    if (meta === null)
+        return { frameCapturedAt: 0, frameFetchedAfterStart: false };
+    return {
+        frameCapturedAt: Math.min(meta.fetchStartedAt, requestedAt),
+        frameFetchedAfterStart: meta.source === 'fetched' && meta.fetchStartedAt >= requestedAt,
+    };
+}
+/**
+ * Run one capture for an observer and date the frame it returns (Issue #3798):
+ * `cli-session` reports where THIS call's frame came from through an async
+ * context set up here, so another capture of the same session running at the
+ * same time — a different number of lines, a different text — cannot stand in
+ * for it.
+ */
+async function captureObservedFrame(capture) {
+    const reported = { meta: null };
+    const requestedAt = Date.now();
+    const frame = await frameMetaSink().run((meta) => {
+        reported.meta = meta;
+    }, capture);
+    return { frame, frameTime: captureFrameTime(reported.meta, requestedAt) };
+}
+function screenBinding(generation, originTurnId) {
+    return { kind: 'screen', generation, originTurnId };
+}
+function sameBinding(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    switch (a.kind) {
+        case 'turn':
+            return a.turnId === b.turnId;
+        case 'dialog-only':
+            return a.recordTurnId === b.recordTurnId;
+        default:
+            return true;
+    }
+}
+/** Whether the Auto-Yes poller answered this episode and the screen now shows another confirmation (R1-7, PR 3). */
+function answeredThenAnother(obs, episode, k) {
+    return (obs.freshPrompt === true &&
+        obs.lastAnswer != null &&
+        obs.lastAnswer.episodeId === episode.episodeId &&
+        k !== null &&
+        k !== obs.lastAnswer.screenKey);
+}
+/** Table O-1: a `waiting` reading on the instance's episode (or none). */
+function verdictForWaiting(obs, episode, humanHeld, c, k, current) {
+    if (episode === null)
+        return { action: 'opened', binding: c };
+    const binding = episode.binding;
+    // The row below the table: a binding of another generation is replaced (P3-2).
+    if (!(0, waiting_episode_verdict_1.sameGeneration)(binding.generation, current))
+        return { action: 'replaced', binding: c };
+    if (humanHeld) {
+        if (binding.kind === 'screen')
+            return { action: 'kept' };
+        return { action: 'rebound', binding: screenBinding(current, binding.kind === 'turn' ? binding.turnId : null) };
+    }
+    switch (binding.kind) {
+        case 'turn': {
+            const stillOpen = c.kind === 'turn' && c.turnId === binding.turnId;
+            if (stillOpen)
+                return answeredThenAnother(obs, episode, k) ? { action: 'replaced', binding: c } : { action: 'kept' };
+            if (c.kind === 'turn')
+                return { action: 'replaced', binding: c };
+            // T has ended (stop, screen evidence, the 30-minute stale bound — R2-3):
+            // only another confirmation replaces it.
+            return obs.freshPrompt === true && k !== null && k !== episode.promptScreenKey
+                ? { action: 'replaced', binding: c }
+                : { action: 'kept' };
+        }
+        case 'dialog-only':
+            if (c.kind === 'turn')
+                return { action: 'rebound', binding: c };
+            if (c.kind === 'dialog-only' && c.recordTurnId !== binding.recordTurnId)
+                return { action: 'replaced', binding: c };
+            return { action: 'kept' };
+        case 'unattributed':
+            if (c.kind === 'unattributed') {
+                return answeredThenAnother(obs, episode, k) ? { action: 'replaced', binding: c } : { action: 'kept' };
+            }
+            if (c.kind === 'dialog-only')
+                return { action: 'rebound', binding: c };
+            // c = turn(N): the wait turned out to be N's when it shows the same confirmation (R2-4).
+            return k !== null && k === episode.promptScreenKey
+                ? { action: 'rebound', binding: c }
+                : { action: 'replaced', binding: c };
+        case 'screen':
+            return c.kind === 'turn' && c.turnId === binding.originTurnId
+                ? { action: 'rebound', binding: c }
+                : { action: 'replaced', binding: c };
+        default:
+            binding;
+            return { action: 'kept' };
+    }
+}
+/** Table O-2: the closing side. Null when the reading closes nothing. */
+function closeReasonFor(obs, episode) {
+    const { reading } = obs;
+    if (reading.kind === 'gone')
+        return 'session-gone';
+    if (reading.kind !== 'not-waiting')
+        return null;
+    switch (obs.observer) {
+        case 'status-probe':
+            return 'screen-cleared';
+        case 'response-checker':
+            return 'response-recorded';
+        case 'auto-yes-poller':
+            // A screen only after a frame fetched since it became one (R3-1, P3-1);
+            // any other wait only when the poller answered it (PR 3, 規則 3).
+            if (episode.binding.kind === 'screen') {
+                return obs.frameCapturedAt > Math.max(episode.openedAt, episode.boundAt) ? 'screen-cleared' : null;
+            }
+            return obs.lastAnswer != null && obs.lastAnswer.episodeId === episode.episodeId ? 'poller-answered' : null;
+        default:
+            obs.observer;
+            return null;
+    }
+}
+/** Why the old episode of a replacement ended. */
+function replacedBecause(old, next, current) {
+    if (!(0, waiting_episode_verdict_1.sameGeneration)(old.generation, current))
+        return 'generation';
+    return next.kind === 'turn' || next.kind === 'dialog-only' ? 'turn-superseded' : 'screen-cleared';
+}
+/**
+ * Decide what one observation does to the instance's episode (design §2.4
+ * 規則 3・4・5, tables O-1 / O-2 and preconditions 1–3). Reads the store and
+ * the turn model; writes nothing.
+ */
+function planWaitingObservation(obs) {
+    const at = obs.now ?? Date.now();
+    const parts = { worktreeId: obs.worktreeId, cliToolId: obs.cliToolId, instanceId: obs.instanceId };
+    const episode = (0, waiting_episode_state_1.getWaitingEpisodeRecord)(obs.worktreeId, obs.cliToolId, obs.instanceId);
+    const current = (0, waiting_episode_binding_resolve_1.generationOf)(parts);
+    const base = {
+        observation: obs,
+        action: 'ignored',
+        episodeId: episode?.episodeId ?? null,
+        since: obs.reading.kind === 'waiting' ? episode?.since ?? null : null,
+        next: null,
+        binding: null,
+        closeReason: null,
+        ignoredBecause: null,
+        at,
+    };
+    const ignored = (because) => ({
+        ...base,
+        action: 'ignored',
+        ignoredBecause: because,
+    });
+    // Precondition 1: the observer started in another generation.
+    if (!(0, waiting_episode_verdict_1.sameGeneration)(obs.start.generation, current))
+        return ignored('generation');
+    const versionMoved = obs.start.version !== (0, waiting_episode_state_1.getEpisodeVersion)(obs.worktreeId, obs.cliToolId, obs.instanceId) && obs.freshPrompt !== true;
+    const { reading } = obs;
+    if (reading.kind !== 'waiting') {
+        // Table O-2.
+        if (episode === null)
+            return ignored('nothing-open');
+        if (reading.kind === 'unknown')
+            return ignored('unknown-frame');
+        const reason = closeReasonFor(obs, episode);
+        if (reason === null)
+            return ignored('not-this-observer');
+        if (versionMoved)
+            return ignored('version');
+        return { ...base, action: 'closed', closeReason: reason, since: null };
+    }
+    // Table O-1.
+    const k = reading.promptData !== null ? (0, prompt_screen_key_1.promptScreenKey)(reading.promptData) : null;
+    // 規則 1: a person's screen is `screen` whatever the turn model says, with
+    // the open turn as its origin.
+    const resolved = (0, waiting_episode_binding_resolve_1.resolveEpisodeBinding)(parts, at);
+    const c = reading.humanHeld
+        ? screenBinding(current, resolved.kind === 'turn' ? resolved.turnId : null)
+        : resolved;
+    const verdict = verdictForWaiting(obs, episode, reading.humanHeld, c, k, current);
+    if (verdict.action === 'kept')
+        return { ...base, action: 'kept' };
+    // Precondition 2 (I5 (b) / (d)) and 3 (I6).
+    if (versionMoved)
+        return ignored('version');
+    const lastClosed = (0, waiting_episode_state_1.getLastClosedEpisode)(obs.worktreeId, obs.cliToolId, obs.instanceId);
+    const closedBeforeOwnFetch = obs.frameFetchedAfterStart === true &&
+        obs.start.version === (0, waiting_episode_state_1.getEpisodeVersion)(obs.worktreeId, obs.cliToolId, obs.instanceId);
+    if (lastClosed !== null &&
+        !closedBeforeOwnFetch &&
+        obs.frameCapturedAt <= lastClosed.at &&
+        (k === null || k === lastClosed.promptScreenKey)) {
+        return ignored('stale-frame');
+    }
+    if (verdict.action === 'rebound') {
+        if (episode !== null && sameBinding(episode.binding, verdict.binding))
+            return { ...base, action: 'kept' };
+        return { ...base, action: 'rebound', binding: verdict.binding };
+    }
+    const binding = verdict.binding;
+    const structuredSince = reading.structuredSince;
+    const since = verdict.action === 'opened' || episode === null
+        ? structuredSince ?? at
+        : structuredSince !== null && structuredSince > episode.since
+            ? structuredSince
+            : at;
+    const next = {
+        since,
+        kind: reading.waitingKind,
+        binding,
+        openedBy: obs.observer,
+        promptScreenKey: k,
+    };
+    return {
+        ...base,
+        action: verdict.action,
+        since,
+        next,
+        closeReason: verdict.action === 'replaced' && episode !== null ? replacedBecause(episode.binding, binding, current) : null,
+    };
+}

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

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * What a new waiting episode is bound to, read from the turn model (Issue #3798).
+ * Split out of `waiting-episode-binding` (Issue #3892), which re-exports it.
+ *
+ * @module lib/session/waiting-episode-binding-resolve
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generationOf = generationOf;
+exports.resolveEpisodeBinding = resolveEpisodeBinding;
+const auto_yes_state_1 = require("../../lib/auto-yes-state");
+const agent_event_turn_1 = require("../../lib/session/agent-event-turn");
+function generationOf(parts) {
+    return (0, agent_event_turn_1.toGenerationRef)((0, agent_event_turn_1.currentGeneration)((0, auto_yes_state_1.buildCompositeKey)(parts.worktreeId, parts.cliToolId, parts.instanceId)));
+}
+/**
+ * What an episode opening now is bound to (design §2.4 規則 1).
+ *
+ * Read from the fenced, aged turn record — the same reading `getAgentTurn`
+ * gives every other reader — with the live decisions counted without retiring
+ * the expired ones, so deciding a binding writes nothing a transition would
+ * later read differently.
+ */
+function resolveEpisodeBinding(parts, at) {
+    const generation = generationOf(parts);
+    const turn = (0, agent_event_turn_1.getAgentTurn)(parts.worktreeId, parts.cliToolId, parts.instanceId, at);
+    if (turn === null)
+        return { kind: 'unattributed', generation, lastClosedTurnId: null };
+    if (turn.closedAt === null && turn.openedAt !== null) {
+        return { kind: 'turn', generation, turnId: turn.turnId };
+    }
+    if (turn.closedAt === null && (0, agent_event_turn_1.liveDecisionCount)(turn, at) > 0) {
+        return { kind: 'dialog-only', generation, recordTurnId: turn.turnId, sessionId: turn.sessionId };
+    }
+    // A closed turn, or a record holding no live decision (an `idle_prompt`
+    // display record, or a forecast whose 20 s ran out).
+    return { kind: 'unattributed', generation, lastClosedTurnId: turn.turnId };
+}

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);
+});