commandmate 0.47.2 → 0.49.0

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

@@ -12,11 +12,23 @@
  *
  * So the edge is detected exactly once, here, by {@link observeWaitingEdge}, and
  * everything else either reads {@link getWaitingEpisode} or subscribes with
- * {@link onWaitingTransition}. There is one caller today —
- * `worktree-status-helper`, on the list API's per-instance probe — and it passes
- * the *composed* verdict (scraper OR structured), so a wait that only the
- * agent's own events can see opens an episode exactly like one the screen
- * scraper read.
+ * {@link onWaitingTransition}. The observers are `worktree-status-helper`, on
+ * the list API's per-instance probe — it passes the *composed* verdict (scraper
+ * OR structured), so a wait that only the agent's own events can see opens an
+ * episode exactly like one the screen scraper read — and `response-checker`
+ * (#1790), which opens the episode for a prompt it saved and closes it when it
+ * records a reply.
+ *
+ * Issue #3798 added the agent's own turn transitions as closers: a `stop` that
+ * ended the turn an episode belongs to closes it in the same synchronous step
+ * that records the stop (`waiting-episode-binding`), so a tool whose reply
+ * arrives on a hook closes its wait with no browser open. That needs each
+ * episode to carry an identity and the turn it belongs to; see "identity and
+ * attribution" below. The screen observers — the status probe, the response
+ * poller and now the Auto-Yes poller — go through the same module's
+ * observation tables (`observeWaiting`), which refuse a reading made against an
+ * episode that has moved since the observer started; {@link observeWaitingEdge}
+ * stays for the callers and suites written against #1786.
  *
  * ## Where #1788 / #1790 plug in
  *
@@ -39,46 +51,49 @@
  * @module lib/session/waiting-episode-state
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.onWaitingTransition = onWaitingTransition;
+exports.updateEpisodeKind = exports.replaceEpisode = exports.rebindEpisode = exports.openEpisode = exports.closeEpisode = exports.snapshotEpisodeVersions = exports.onWaitingTransition = exports.onWaitingEpisodeTransition = exports.hasOpenWaitingEpisode = exports.getWaitingEpisodeRecord = exports.getWaitingEpisode = exports.getLastClosedEpisode = exports.getEpisodeVersion = exports.clearWaitingTransitionListeners = exports.clearWaitingEpisodes = void 0;
+exports.registerEpisodeBindingResolver = registerEpisodeBindingResolver;
 exports.observeWaitingEdge = observeWaitingEdge;
-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 waiting_episode_state_ops_1 = require("../../lib/session/waiting-episode-state-ops");
+const waiting_episode_state_store_1 = require("../../lib/session/waiting-episode-state-store");
+var waiting_episode_state_store_2 = require("../../lib/session/waiting-episode-state-store");
+Object.defineProperty(exports, "clearWaitingEpisodes", { enumerable: true, get: function () { return waiting_episode_state_store_2.clearWaitingEpisodes; } });
+Object.defineProperty(exports, "clearWaitingTransitionListeners", { enumerable: true, get: function () { return waiting_episode_state_store_2.clearWaitingTransitionListeners; } });
+Object.defineProperty(exports, "getEpisodeVersion", { enumerable: true, get: function () { return waiting_episode_state_store_2.getEpisodeVersion; } });
+Object.defineProperty(exports, "getLastClosedEpisode", { enumerable: true, get: function () { return waiting_episode_state_store_2.getLastClosedEpisode; } });
+Object.defineProperty(exports, "getWaitingEpisode", { enumerable: true, get: function () { return waiting_episode_state_store_2.getWaitingEpisode; } });
+Object.defineProperty(exports, "getWaitingEpisodeRecord", { enumerable: true, get: function () { return waiting_episode_state_store_2.getWaitingEpisodeRecord; } });
+Object.defineProperty(exports, "hasOpenWaitingEpisode", { enumerable: true, get: function () { return waiting_episode_state_store_2.hasOpenWaitingEpisode; } });
+Object.defineProperty(exports, "onWaitingEpisodeTransition", { enumerable: true, get: function () { return waiting_episode_state_store_2.onWaitingEpisodeTransition; } });
+Object.defineProperty(exports, "onWaitingTransition", { enumerable: true, get: function () { return waiting_episode_state_store_2.onWaitingTransition; } });
+Object.defineProperty(exports, "snapshotEpisodeVersions", { enumerable: true, get: function () { return waiting_episode_state_store_2.snapshotEpisodeVersions; } });
+var waiting_episode_state_ops_2 = require("../../lib/session/waiting-episode-state-ops");
+Object.defineProperty(exports, "closeEpisode", { enumerable: true, get: function () { return waiting_episode_state_ops_2.closeEpisode; } });
+Object.defineProperty(exports, "openEpisode", { enumerable: true, get: function () { return waiting_episode_state_ops_2.openEpisode; } });
+Object.defineProperty(exports, "rebindEpisode", { enumerable: true, get: function () { return waiting_episode_state_ops_2.rebindEpisode; } });
+Object.defineProperty(exports, "replaceEpisode", { enumerable: true, get: function () { return waiting_episode_state_ops_2.replaceEpisode; } });
+Object.defineProperty(exports, "updateEpisodeKind", { enumerable: true, get: function () { return waiting_episode_state_ops_2.updateEpisodeKind; } });
 const logger = (0, logger_1.createLogger)('waiting-episode-state');
-/** compositeKey -> the wait currently in progress for that instance. */
-const 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());
-/**
- * Subscribe to waiting edges.
- *
- * @returns An unsubscribe function. Idempotent — calling it twice is harmless.
- */
-function onWaitingTransition(listener) {
-    listeners.add(listener);
-    return () => {
-        listeners.delete(listener);
-    };
+/** Install the binding resolver `observeWaitingEdge` uses. The last one wins. */
+function registerEpisodeBindingResolver(resolver) {
+    globalThis.__sessionWaitingEpisodeBindingResolver = resolver;
 }
-/** Notify subscribers, containing anything they throw. */
-function emit(transition) {
-    for (const listener of listeners) {
-        try {
-            listener(transition);
-        }
-        catch (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),
-            });
-        }
+function resolveBinding(parts, at) {
+    const resolver = globalThis.__sessionWaitingEpisodeBindingResolver;
+    if (resolver === undefined)
+        return waiting_episode_state_store_1.UNKNOWN_BINDING;
+    try {
+        return resolver(parts, at);
+    }
+    catch (error) {
+        logger.warn('waiting-episode-binding-resolve-failed', {
+            worktreeId: parts.worktreeId,
+            cliToolId: parts.cliToolId,
+            instanceId: parts.instanceId ?? parts.cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return waiting_episode_state_store_1.UNKNOWN_BINDING;
     }
 }
 /**
@@ -89,16 +104,23 @@ function emit(transition) {
  * `since` and emit nothing, so a listener hears one event per wait rather than
  * one per poll.
  *
+ * Issue #3798: an episode opened here is bound by the registered resolver
+ * (`waiting-episode-binding`), so the turn transitions can end it. The
+ * production observers no longer call it: they go through
+ * `waiting-episode-binding`'s `observeWaiting`, which also checks that the
+ * episode has not moved since they started and that the frame does not
+ * predate the close of what it shows.
+ *
  * @returns The episode's `since` while waiting, or null when it is not.
  */
 function observeWaitingEdge({ worktreeId, cliToolId, instanceId, waiting, kind = null, structuredSince = null, now = Date.now(), }) {
-    const key = (0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId);
-    const existing = episodes.get(key);
+    const parts = { worktreeId, cliToolId, instanceId };
+    const key = (0, waiting_episode_state_store_1.keyOf)(parts);
+    const existing = waiting_episode_state_store_1.episodes.get(key);
     if (!waiting) {
         if (existing === undefined)
             return null;
-        episodes.delete(key);
-        emit({ worktreeId, cliToolId, instanceId, waiting: false, since: null, kind: null, at: now });
+        (0, waiting_episode_state_ops_1.closeEpisode)(parts, (0, waiting_episode_state_store_1.metaOf)(existing).episodeId, 'screen-cleared', now);
         return null;
     }
     if (existing !== undefined) {
@@ -109,51 +131,6 @@ function observeWaitingEdge({ worktreeId, cliToolId, instanceId, waiting, kind =
         return existing.since;
     }
     const since = structuredSince ?? now;
-    episodes.set(key, { since, kind });
-    emit({ worktreeId, cliToolId, instanceId, waiting: true, since, kind, at: now });
+    (0, waiting_episode_state_ops_1.openEpisode)(parts, { since, kind, binding: resolveBinding(parts, now), openedBy: 'legacy-edge' }, now);
     return since;
 }
-/**
- * @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 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 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() {
-    episodes.clear();
-}
-/** Drop every subscriber. Test seam, paired with {@link clearWaitingEpisodes}. */
-function clearWaitingTransitionListeners() {
-    listeners.clear();
-}

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

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * The T table (Issue #3798, design §2.4): what one turn transition's outcome
+ * does to the open waiting episode. Pure — it reads the outcome, the episode's
+ * binding and the current generation, and writes nothing. Applying the verdict
+ * is `waiting-episode-binding`'s job (Issue #3864 split it out of there).
+ *
+ * Design: `docs/design/issue-3798-waiting-episode.md`.
+ *
+ * @module lib/session/waiting-episode-verdict
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sameGeneration = sameGeneration;
+exports.verdictForOutcome = verdictForOutcome;
+function sameGeneration(a, b) {
+    if (a.kind === 'none' || b.kind === 'none')
+        return a.kind === b.kind;
+    return a.at === b.at;
+}
+const NONE = { action: 'none' };
+const close = (reason) => ({ action: 'close', reason });
+/** The previous record's turn id, for the D and F columns. Null for `none`. */
+function previousTurnId(previous) {
+    return previous.kind === 'none' ? null : previous.turnId;
+}
+/** T1–T5: a turn opened. */
+function verdictForOpened(outcome, binding) {
+    const { previous, turnId: n, event } = outcome;
+    const asTurnN = { kind: 'turn', generation: outcome.generation, turnId: n };
+    if (binding.kind === 'screen')
+        return NONE;
+    if (binding.kind === 'turn' && binding.turnId === n)
+        return { action: 'unmatched' }; // ※1
+    const p = previousTurnId(previous);
+    const tookOverRecord = previous.kind === 'dialog-only' || previous.kind === 'display-only';
+    // D: the record this turn took over (R3-4). Only T2 / T3 / T4 have one (※5).
+    const isD = binding.kind === 'dialog-only' && binding.recordTurnId === p;
+    // T5 (R1-9): a turn replaced while it was open ends every wait but a screen's.
+    if (previous.kind === 'open-same-session' || previous.kind === 'open-other-session') {
+        return isD ? { action: 'unmatched' } : close('turn-superseded');
+    }
+    // T4 (R2-4): a prompt ends them too; the turn model drops every decision here.
+    if (event === 'user_prompt_submit')
+        return close('turn-superseded');
+    if (binding.kind === 'turn')
+        return close('turn-superseded');
+    if (binding.kind === 'dialog-only') {
+        if (!isD)
+            return close('turn-superseded');
+        return tookOverRecord ? { action: 'rebind', binding: asTurnN } : { action: 'unmatched' }; // T1: ※5
+    }
+    // unattributed — F: nothing opened between the wait and this turn (R2-4).
+    return binding.lastClosedTurnId === p ? { action: 'rebind', binding: asTurnN } : close('turn-superseded');
+}
+/** T9–T11: a stop with no turn open. */
+function verdictForStopWithoutTurn(outcome, binding) {
+    const { previous } = outcome;
+    const p = previousTurnId(previous);
+    switch (previous.kind) {
+        case 'closed':
+            // T9: B (R1-2) and F (R2-1).
+            if (binding.kind === 'turn' && binding.turnId === p)
+                return close('turn-stop');
+            if (binding.kind === 'unattributed' && binding.lastClosedTurnId === p)
+                return close('turn-stop');
+            if (binding.kind === 'dialog-only' && binding.recordTurnId === p)
+                return { action: 'unmatched' }; // ※5
+            return NONE;
+        case 'dialog-only':
+            // T10: D, F and G.
+            if (binding.kind === 'dialog-only' && binding.recordTurnId === p)
+                return close('turn-stop');
+            if (binding.kind === 'unattributed')
+                return close('turn-stop');
+            return NONE;
+        case 'display-only':
+        case 'none':
+            // T11: D (R3-4) and F.
+            if (binding.kind === 'dialog-only' && binding.recordTurnId === p)
+                return close('turn-stop');
+            if (binding.kind === 'unattributed' && binding.lastClosedTurnId === p)
+                return close('turn-stop');
+            return NONE;
+        default:
+            // An open turn is `stopped` / `stop-rejected`, never this outcome.
+            return { action: 'unmatched' };
+    }
+}
+/** T19 / T20 and the rest of the generation fence. */
+function verdictForGenerationFenced(outcome, binding) {
+    // T19 / T20 (R2-8): a session start in the same process keeps a screen.
+    if (outcome.source === 'session-start' && binding.kind === 'screen') {
+        return sameGeneration(binding.generation, outcome.generation)
+            ? NONE
+            : { action: 'rebind', binding: { ...binding, generation: outcome.generation } };
+    }
+    return sameGeneration(binding.generation, outcome.generation) ? NONE : close('generation');
+}
+/** T7. */
+function verdictForRestored(outcome, binding) {
+    // T7: a wait opened under the discarded turn belongs to the one put back.
+    return binding.kind === 'turn' && binding.turnId === outcome.discardedTurnId
+        ? { action: 'rebind', binding: { ...binding, turnId: outcome.restoredTurnId } }
+        : NONE;
+}
+/** T8. */
+function verdictForStopped(outcome, binding) {
+    // T8.
+    return binding.kind === 'turn' && binding.turnId === outcome.turnId ? close('turn-stop') : NONE;
+}
+/** T13. */
+function verdictForSessionEnded(outcome, binding) {
+    // T13.
+    return binding.kind === 'turn' && binding.turnId === outcome.turnId ? close('turn-session-end') : NONE;
+}
+/** T15 / T16. */
+function verdictForDecisionOpened(outcome, binding, current) {
+    // T15 / T16 (R3-6): a dialog the hook reported for a wait the screen showed first.
+    return outcome.recordKind === 'dialog-only' && binding.kind === 'unattributed'
+        ? {
+            action: 'rebind',
+            binding: { kind: 'dialog-only', generation: current, recordTurnId: outcome.recordTurnId, sessionId: null },
+        }
+        : NONE;
+}
+/** T17 / T18. */
+function verdictForDecisionAnswered(outcome, binding) {
+    // T17 / T18 (R3-3): an explicit answer that left nothing pending.
+    if (outcome.before === 0 || outcome.remaining > 0)
+        return NONE;
+    const bound = (binding.kind === 'turn' && binding.turnId === outcome.recordTurnId) ||
+        (binding.kind === 'dialog-only' && binding.recordTurnId === outcome.recordTurnId);
+    return bound ? close('decision-settled') : NONE;
+}
+/** Rows that close a binding of another generation (the I column). */
+const CLOSES_OTHER_GENERATION = new Set([
+    'opened',
+    'stopped',
+    'stop-without-turn',
+    'session-ended',
+]);
+/** The T table (design §2.4): one outcome on the open episode. */
+function verdictForOutcome(outcome, binding, current) {
+    if (outcome.kind === 'generation-fenced')
+        return verdictForGenerationFenced(outcome, binding);
+    if (!sameGeneration(binding.generation, current)) {
+        return CLOSES_OTHER_GENERATION.has(outcome.kind) ? close('generation') : NONE;
+    }
+    switch (outcome.kind) {
+        case 'opened':
+            return verdictForOpened(outcome, binding);
+        case 'restored':
+            return verdictForRestored(outcome, binding);
+        case 'stopped':
+            return verdictForStopped(outcome, binding);
+        case 'stop-without-turn':
+            return verdictForStopWithoutTurn(outcome, binding);
+        case 'session-ended':
+            return verdictForSessionEnded(outcome, binding);
+        case 'decision-opened':
+            return verdictForDecisionOpened(outcome, binding, current);
+        case 'decision-answered':
+            return verdictForDecisionAnswered(outcome, binding);
+        case 'continued':
+        case 'stop-rejected':
+        case 'session-end-rejected':
+        case 'none':
+            // T6, T12, T14, T21.
+            return NONE;
+        default:
+            outcome;
+            return NONE;
+    }
+}

package/dist/server/src/lib/tmux/tmux-capture-cache.js

@@ -24,6 +24,7 @@ exports.isCaptureWindowSaturated = isCaptureWindowSaturated;
 exports.getCaptureGeneration = getCaptureGeneration;
 exports.isCaptureGenerationCurrent = isCaptureGenerationCurrent;
 exports.sliceOutput = sliceOutput;
+exports.sliceCutsHead = sliceCutsHead;
 exports.getCachedCapture = getCachedCapture;
 exports.setCachedCapture = setCachedCapture;
 exports.invalidateCache = invalidateCache;
@@ -87,6 +88,10 @@ function getCache() {
 function getInflight() {
     return (0, global_state_1.getOrInitGlobal)('__tmuxCaptureCacheInflight', () => new Map());
 }
+/** When each in-flight fetch started (Issue #3798), for the callers that join it. */
+function getInflightStartedAt() {
+    return (0, global_state_1.getOrInitGlobal)('__tmuxCaptureCacheInflightStartedAt', () => new WeakMap());
+}
 function getGenerationState() {
     return (0, global_state_1.getOrInitGlobal)('__tmuxCaptureCacheGeneration', () => ({ global: 0, sessions: new Map() }));
 }
@@ -122,8 +127,24 @@ function isCaptureGenerationCurrent(sessionName, generation) {
 // sliceOutput()
 // =========================================================================
 /**
- * Slice output from the end to return the last requestedLines lines.
- * If requestedLines >= total lines, returns the full output.
+ * A capture's rows (Issue #3881 third review N4). tmux ends every row with a
+ * newline, so the last one terminates a row and is not a row of its own: a
+ * 1000-row pane comes back as 1000 rows and a terminator, which `split` makes
+ * 1001 elements.
+ */
+function rowsOf(output) {
+    const terminated = output.endsWith('\n');
+    return { rows: (terminated ? output.slice(0, -1) : output).split('\n'), terminated };
+}
+/**
+ * Slice output from the end to return the last requestedLines rows.
+ * If requestedLines >= total rows, returns the full output.
+ *
+ * Issue #3881 (third review N4): counted in rows, the terminator kept. Counted
+ * in `split` elements, the terminator took one of the requested rows, so a
+ * 1000-row pane asked for 1000 rows lost its first row — on an
+ * alternate-screen pane, the row that says whether the content begins at the
+ * top of the screen.
  *
  * @param fullOutput - Full captured output string
  * @param requestedLines - Number of lines requested from the end
@@ -132,10 +153,21 @@ function isCaptureGenerationCurrent(sessionName, generation) {
 function sliceOutput(fullOutput, requestedLines) {
     if (fullOutput === '')
         return '';
-    const lines = fullOutput.split('\n');
-    if (requestedLines >= lines.length)
+    const { rows, terminated } = rowsOf(fullOutput);
+    if (requestedLines >= rows.length)
         return fullOutput;
-    return lines.slice(-requestedLines).join('\n');
+    return rows.slice(-requestedLines).join('\n') + (terminated ? '\n' : '');
+}
+/**
+ * Whether {@link sliceOutput} drops rows from the top of `fullOutput` (Issue
+ * #3881 third review N4): the one fact about a capture's top that its row count
+ * cannot tell when the window is exactly the pane's height.
+ *
+ * @param fullOutput - Full captured output string
+ * @param requestedLines - Number of lines requested from the end
+ */
+function sliceCutsHead(fullOutput, requestedLines) {
+    return fullOutput !== '' && requestedLines < rowsOf(fullOutput).rows.length;
 }
 // =========================================================================
 // getCachedCapture()
@@ -180,8 +212,10 @@ function getCachedCapture(sessionName, requestedLines) {
  * @param sessionName - tmux session name (cache key)
  * @param output - Captured output string
  * @param capturedLines - Number of lines the output was captured with
+ * @param fetchStartedAt - When the capture began (Issue #3798); every writer
+ *   in this app passes it. Defaults to now, the write time
  */
-function setCachedCapture(sessionName, output, capturedLines) {
+function setCachedCapture(sessionName, output, capturedLines, fetchStartedAt) {
     const cache = getCache();
     const now = Date.now();
     // [SEC4-002] Full sweep: remove all TTL-expired entries
@@ -209,8 +243,22 @@ function setCachedCapture(sessionName, output, capturedLines) {
         output,
         capturedLines,
         timestamp: now,
+        fetchStartedAt: fetchStartedAt ?? now,
     });
 }
+/**
+ * When the cached capture of `sessionName` was started, or null when nothing
+ * live is cached (Issue #3798). Read-only: an expired entry is left for the
+ * next read to evict.
+ *
+ * @param sessionName - tmux session name (cache key)
+ */
+function getCachedCaptureFetchStartedAt(sessionName) {
+    const entry = getCache().get(sessionName);
+    if (!entry || Date.now() - entry.timestamp > exports.CACHE_TTL_MS)
+        return null;
+    return entry.fetchStartedAt;
+}
 // =========================================================================
 // invalidateCache()
 // =========================================================================
@@ -262,10 +310,8 @@ function resetCacheForTesting() {
     globalThis.__tmuxCaptureCache = undefined;
     globalThis.__tmuxCaptureCacheInflight = undefined;
     globalThis.__tmuxCaptureCacheGeneration = undefined;
+    globalThis.__tmuxCaptureCacheInflightStartedAt = undefined;
 }
-// =========================================================================
-// getOrFetchCapture() - singleflight pattern
-// =========================================================================
 /**
  * Get capture output from cache or fetch it.
  * Implements singleflight pattern: concurrent requests for the same session
@@ -277,33 +323,52 @@ function resetCacheForTesting() {
  * @param sessionName - tmux session name
  * @param requestedLines - Number of lines requested
  * @param fetchFn - Function to fetch output on cache miss
+ * @param onServed - Told where the returned frame came from (Issue #3798),
+ *   right before it is returned; not called when the capture throws
+ * @param onSliced - Told whether the slice to `requestedLines` dropped rows
+ *   from the top of what tmux returned (Issue #3881 third review N4,
+ *   {@link sliceCutsHead}), right before it is returned
  * @returns Captured output (sliced to requestedLines)
  */
-async function getOrFetchCapture(sessionName, requestedLines, fetchFn) {
+async function getOrFetchCapture(sessionName, requestedLines, fetchFn, onServed, onSliced) {
     // 1. Check cache first
+    const cachedStartedAt = getCachedCaptureFetchStartedAt(sessionName);
     const cached = getCachedCapture(sessionName, requestedLines);
     if (cached !== null) {
+        if (cachedStartedAt !== null)
+            onServed?.({ fetchStartedAt: cachedStartedAt, source: 'cache' });
+        const entry = getCache().get(sessionName);
+        if (entry)
+            onSliced?.(sliceCutsHead(entry.output, requestedLines));
         return cached;
     }
     // 2. Check for inflight request (singleflight)
     const inflight = getInflight();
     const existingPromise = inflight.get(sessionName);
     if (existingPromise) {
+        const joinedStartedAt = getInflightStartedAt().get(existingPromise);
         const result = await existingPromise;
+        if (joinedStartedAt !== undefined)
+            onServed?.({ fetchStartedAt: joinedStartedAt, source: 'joined' });
+        onSliced?.(sliceCutsHead(result, requestedLines));
         return sliceOutput(result, requestedLines);
     }
     // 3. Create new fetch promise
     // Issue #3734: snapshot the generation before fetchFn() starts
     const generation = getCaptureGeneration(sessionName);
+    const fetchStartedAt = Date.now();
     const fetchPromise = fetchFn();
     inflight.set(sessionName, fetchPromise);
+    getInflightStartedAt().set(fetchPromise, fetchStartedAt);
     try {
         const output = await fetchPromise;
         // Cache non-empty results only [SEC4-007], and only when no invalidation
         // happened while waiting (Issue #3734)
         if (output.length > 0 && isCaptureGenerationCurrent(sessionName, generation)) {
-            setCachedCapture(sessionName, output, exports.CACHE_MAX_CAPTURE_LINES);
+            setCachedCapture(sessionName, output, exports.CACHE_MAX_CAPTURE_LINES, fetchStartedAt);
         }
+        onServed?.({ fetchStartedAt, source: 'fetched' });
+        onSliced?.(sliceCutsHead(output, requestedLines));
         return sliceOutput(output, requestedLines);
     }
     finally {