@hyperdrive.bot/paseo-server 0.3.11 → 0.3.12

package/dist/server/server/agent/providers/claude/transport/pty-query.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { TranscriptSdkReader } from "./transcript-sdk-reader.js";
 /**
  * PtyQuery — a `Query`-shaped adapter over an interactive `claude` PTY.
@@ -23,8 +24,48 @@ import { TranscriptSdkReader } from "./transcript-sdk-reader.js";
  * of `Query` methods (rewindFiles, readFile, …) is unsupported on the PTY path; the
  * instance is cast `as unknown as Query` at the seam.
  */
-const READY_FIRST_DATA_SETTLE_MS = 1500;
-const READY_MAX_WAIT_MS = 12000;
+/**
+ * Readiness is "the terminal stopped talking", not "the terminal said something".
+ *
+ * This used to schedule a settle 1500ms after EVERY chunk, and because settling is
+ * idempotent the first chunk always won: readiness fired 1.5s after the first byte no
+ * matter how much boot output was still streaming. The splash banner is a first byte, so
+ * on a slow start (seven MCP servers to connect) paseo began typing into a terminal that
+ * was not accepting input yet, and the prompt was lost outright. Observed 2026-08-01: a
+ * session whose entire recording was the splash line, then 70s of failed Enters.
+ *
+ * Resetting the timer on each chunk makes it a real debounce, so it settles once output
+ * has actually gone quiet. The ceiling is correspondingly generous, because waiting a few
+ * extra seconds costs nothing next to losing the message.
+ */
+const READY_QUIET_SETTLE_MS = 1500;
+const READY_MAX_WAIT_MS = 60000;
+/**
+ * How long the idle prompt must hold before we believe it. The TUI repaints its footer
+ * mid-turn, so a single frame without the busy marker is a flicker, not idleness.
+ */
+const READY_IDLE_STABLE_MS = 400;
+/**
+ * Absolute ceiling on waiting for a busy terminal to go idle. Only reached while the TUI is
+ * actively telling us it is working, so it is a backstop against a wedged agent, not a boot
+ * budget. Matches the turn-stall backstop deliberately: both answer "this terminal claims to
+ * be working but never finished".
+ */
+const READY_BUSY_MAX_WAIT_MS = 10 * 60000;
+/** The TUI prints this in its footer for exactly as long as a turn is running. */
+const BUSY_MARKER = "esc to interrupt";
+/**
+ * Footer fragments that only render when the input box is accepting typing. Matched against
+ * the rolling tail, and only believed when {@link BUSY_MARKER} is absent, because the busy
+ * footer contains some of these too (`… · esc to interrupt · ← for agents`).
+ */
+const IDLE_PROMPT_MARKERS = [
+    "for agents",
+    "for shortcuts",
+    "bypass permissions",
+    "shift+tab to cycle",
+    "for commands",
+];
 const TURN_END_IDLE_MS = 700;
 const TERMINAL_STOP_REASONS = new Set(["end_turn", "stop_sequence", "max_tokens"]);
 /**
@@ -48,6 +89,66 @@ const TERMINAL_STOP_REASONS = new Set(["end_turn", "stop_sequence", "max_tokens"
  * with `stallTimeoutMs`; `0` disables the backstop entirely.
  */
 const TURN_STALL_TIMEOUT_MS = 10 * 60000;
+/**
+ * How much terminal text to keep for diagnosis. The TUI is the only place that says what
+ * claude is actually doing while it is quiet ("Compacting conversation…", a retry notice,
+ * a prompt), and PtyQuery otherwise unsubscribes from it once the readiness gate settles,
+ * so a stall investigation has nothing to read.
+ *
+ * A rolling tail rather than a live log on purpose: the TUI redraws constantly (spinner
+ * frames, cursor moves), so streaming it would flood the daemon log for no benefit. This
+ * keeps only the last few KB and emits it exactly once, when a turn is declared stalled.
+ */
+const TERMINAL_TAIL_MAX_CHARS = 4000;
+/** Chars of the tail to include in the user-facing stall message; the rest goes to the log. */
+const TERMINAL_TAIL_EXCERPT_CHARS = 300;
+/**
+ * Telemetry. The PTY path had none: a session that went quiet left no record of what it had
+ * been doing, and four distinct failure modes (prompt never submitted, stall after a
+ * compaction, never finished booting, genuinely waiting on the model) were indistinguishable
+ * from each other and from a slow turn. Each of the three below exists to separate them.
+ */
+/** Heartbeat cadence while a turn is outstanding. Cheap: one line per turn per interval. */
+const LIVENESS_HEARTBEAT_MS = 30000;
+/**
+ * The claude TUI's post-interrupt modal. A cancelled turn leaves the terminal sitting on
+ * `Interrupted · What should Claude do instead?`, and in that state Enter answers the dialog
+ * instead of submitting a turn, so every subsequent prompt is swallowed whole and the retry
+ * loop in submitTurn cannot win. Observed live 2026-08-01: a turn was cancelled at 16:56:08
+ * and the next message failed all five submit attempts 35s later.
+ *
+ * Matched against the terminal tail rather than guessed at, and acted on only while the
+ * sighting is recent, because sending ESC blindly would interrupt a healthy running turn.
+ */
+const INTERRUPT_PROMPT_MARKER = "what should claude do instead";
+/** How long a sighting stays actionable. Beyond this, assume the modal is long gone. */
+const INTERRUPT_PROMPT_TTL_MS = 5 * 60000;
+/**
+ * Full-session terminal recording, written next to the daemon log under
+ * `$PASEO_HOME/pty-recordings/<sessionId>.log`.
+ *
+ * The 4KB in-memory tail only survives to the next stall and holds seconds of history once
+ * the spinner is running; a session that failed at boot produced 579 chars total. A file
+ * keeps the whole run, so a failure can be read backwards afterwards instead of inferred.
+ * Capped and truncated rather than rotated: this is diagnostic data, the recent past is what
+ * matters, and an unbounded file on a long-running agent is its own incident.
+ */
+const RECORDING_MAX_BYTES = 4 * 1024 * 1024;
+/** Keep this much when the cap is hit, so a truncation never leaves an empty file. */
+const RECORDING_KEEP_BYTES = 1024 * 1024;
+/**
+ * Monotonic milliseconds for every liveness comparison here.
+ *
+ * Never Date.now(): a stepping wall clock silently breaks all of them. Measured on this
+ * machine, the clock oscillated +/-48.6s roughly six times a minute, which made the
+ * readiness gate believe its 60s budget had elapsed after ~11s and type the user's prompt
+ * into a terminal that was still working, losing the message. The tell was an overshoot of
+ * 3641ms on a loop that ticks every 500ms: real elapse cannot overshoot by more than one
+ * tick, a clock step can.
+ */
+function monotonicNowMs() {
+    return performance.now();
+}
 export class PtyQuery {
     constructor(opts) {
         // output queue → async iterator
@@ -55,6 +156,15 @@ export class PtyQuery {
         this.outResolvers = [];
         this.done = false;
         this.offReadyData = null;
+        /**
+         * Cancels the readiness gate and its timers.
+         *
+         * Teardown MUST call this. A query closed before the gate settles used to leave its
+         * deadline interval running, so a session that attached and detached in the same
+         * millisecond still logged "readiness gate hit its timeout" a full minute later, warning
+         * about a terminal nobody was waiting on and leaking a timer per closed session.
+         */
+        this.cancelReadiness = null;
         // turn-end tracking
         this.turnEndTimer = null;
         this.lastStopReason = null;
@@ -63,6 +173,22 @@ export class PtyQuery {
         this.numTurns = 0;
         this.stallTimer = null;
         this.turnInFlight = false;
+        // terminal tail (see TERMINAL_TAIL_MAX_CHARS)
+        this.terminalTail = "";
+        this.offTerminalTap = null;
+        // telemetry
+        this.startedAt = monotonicNowMs();
+        this.recordingPath = null;
+        this.recordingBytes = 0;
+        this.ptyBytesTotal = 0;
+        this.ptyBytesAtLastBeat = 0;
+        this.lastMeaningfulLine = "";
+        this.lastTranscriptAt = 0;
+        this.heartbeatTimer = null;
+        this.readySettledBy = null;
+        /** Last time the TUI footer said a turn was running. 0 = never seen. */
+        this.lastBusyAt = 0;
+        this.interruptPromptAt = 0;
         this.transport = opts.transport;
         this.input = opts.input;
         this.sessionId = opts.sessionId;
@@ -73,18 +199,117 @@ export class PtyQuery {
             transcriptPath: opts.transcriptPath,
             onMessage: (m) => this.onTranscriptMessage(m),
         });
+        // Keep a rolling tail of terminal output. Registered BEFORE the readiness tap below so
+        // that looksIdle() sees the CURRENT chunk: handlers fire in registration order, and
+        // with the order reversed an idle prompt in the final frame was never noticed, because
+        // readiness inspected a tail that did not yet contain it. This one lives for the whole
+        // session so a stall has something to explain itself with. Chunks arrive already redacted (PtyTransport.onData
+        // runs redactChunk), so nothing further is needed here.
+        this.offTerminalTap = this.transport.onData((chunk) => this.appendTerminalTail(chunk));
+        // The executor stays trivial and settlement lives outside it, so there is exactly one
+        // resolve() call in the file. Timers and handlers below all funnel through settle(),
+        // which is guarded by `settled`; expressing that inside the executor tripped
+        // promise/no-multiple-resolved, and the rule is right that multiple resolve paths in an
+        // executor are hard to audit.
+        let resolveReady = () => { };
         this.readyPromise = new Promise((resolve) => {
-            let settled = false;
-            const finish = () => {
-                if (settled)
-                    return;
-                settled = true;
-                this.offReadyData?.();
-                resolve();
-            };
-            this.offReadyData = this.transport.onData(() => setTimeout(finish, READY_FIRST_DATA_SETTLE_MS));
-            setTimeout(finish, READY_MAX_WAIT_MS);
+            resolveReady = resolve;
         });
+        let settled = false;
+        // Single resolve site. Both the normal outcomes and teardown funnel through here, so
+        // the promise provably resolves once no matter which timer or path gets there first.
+        const settle = (by) => {
+            if (settled)
+                return;
+            settled = true;
+            this.readySettledBy = by === "cancelled" ? null : by;
+            this.offReadyData?.();
+            clearTimeout(quietTimer ?? undefined);
+            clearTimeout(idleTimer ?? undefined);
+            clearInterval(deadlineTimer);
+            // A torn-down query never had a readiness problem, so it reports nothing.
+            if (by !== "cancelled") {
+                // Settling on the timeout means claude never produced output that looked like a
+                // booted TUI, so the prompt about to be typed may go into a terminal that is not
+                // listening yet and be lost outright. Loud on purpose.
+                const level = by === "timeout" ? "warn" : "debug";
+                this.logger[level]({
+                    sessionId: this.sessionId,
+                    settledBy: by,
+                    elapsedMs: monotonicNowMs() - this.startedAt,
+                    ptyBytes: this.ptyBytesTotal,
+                    sawBusyMarker: this.lastBusyAt > 0,
+                    lastLine: this.lastMeaningfulLine.slice(-120),
+                }, by === "timeout"
+                    ? "PtyQuery: readiness gate hit its timeout, claude may not be accepting input yet"
+                    : "PtyQuery: readiness settled on terminal output");
+            }
+            resolveReady();
+        };
+        const finish = settle;
+        this.cancelReadiness = () => settle("cancelled");
+        let quietTimer = null;
+        let idleTimer = null;
+        this.offReadyData = this.transport.onData(() => {
+            // Two independent paths to ready, because a PtyQuery attaches to a LONG-LIVED
+            // terminal, not only to a fresh boot (observed 2026-08-01: nine attach/detach
+            // cycles on one session's PTY).
+            //
+            //  - quiet:       nothing has been painted for a while. Correct for a cold boot.
+            //  - idle-prompt: the footer positively shows an input box and no busy marker.
+            //
+            // Quiet ALONE is wrong on re-attach: if the agent is mid-turn the spinner repaints
+            // at a couple of KB/s forever, so "went quiet" can never fire and the gate used to
+            // fall through to its timeout and type into a working terminal. That was the real
+            // cause of the lost prompts, and it is why absence-of-output cannot be the only
+            // signal here.
+            if (quietTimer)
+                clearTimeout(quietTimer);
+            quietTimer = setTimeout(() => finish("quiet"), READY_QUIET_SETTLE_MS);
+            quietTimer.unref?.();
+            if (this.looksIdle()) {
+                // Hold the idle read briefly: the footer repaints mid-turn and a single frame
+                // without the busy marker is a flicker, not idleness.
+                if (!idleTimer) {
+                    idleTimer = setTimeout(() => {
+                        if (this.looksIdle())
+                            finish("idle-prompt");
+                        idleTimer = null;
+                    }, READY_IDLE_STABLE_MS);
+                    idleTimer.unref?.();
+                }
+            }
+            else if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = null;
+            }
+        });
+        // The deadline is conditional on evidence, not a flat budget. Only a terminal showing
+        // NO sign of life gets cut off at the short budget.
+        //
+        // Liveness is "has this PTY ever produced output", NOT "did the busy footer repaint
+        // recently". An earlier version keyed on the footer and timed out anyway on a session
+        // that was plainly working (60017ms, 78991 bytes, sawBusyMarker true but outside the
+        // window). Measured across captured sessions, the gap between footer repaints has a
+        // median of 37.7s and a p90 of 483s, so no recency window is defensible.
+        //
+        // Reaching this branch at all already proves the terminal is streaming: the quiet
+        // timer above resolves readiness after 1.5s of silence, so if we are still un-ready
+        // the quiet timer must be getting reset continuously. A genuinely dead terminal never
+        // fires onData, never arms the quiet timer, and never records a byte, which is exactly
+        // the case the short budget exists for.
+        const deadlineTimer = setInterval(() => {
+            const waited = monotonicNowMs() - this.startedAt;
+            if (this.ptyBytesTotal > 0) {
+                if (waited >= READY_BUSY_MAX_WAIT_MS)
+                    finish("timeout");
+                return;
+            }
+            if (waited >= READY_MAX_WAIT_MS)
+                finish("timeout");
+        }, 500);
+        deadlineTimer.unref?.();
+        this.openRecording();
         if (opts.initMessage)
             this.emit(opts.initMessage);
         this.reader.start();
@@ -124,12 +349,17 @@ export class PtyQuery {
         if (this.done)
             return;
         this.done = true;
+        this.cancelReadiness?.();
         if (this.turnEndTimer)
             clearTimeout(this.turnEndTimer);
         this.turnEndTimer = null;
         this.turnInFlight = false;
         this.clearStallTimer();
         this.offReadyData?.();
+        this.offTerminalTap?.();
+        this.offTerminalTap = null;
+        this.stopHeartbeat();
+        this.recordLine("--- PtyQuery detached ---");
         try {
             this.reader.stop();
         }
@@ -152,35 +382,173 @@ export class PtyQuery {
                 const text = extractUserText(userMessage);
                 if (!text)
                     continue;
-                this.turnStartedAt = Date.now();
+                this.turnStartedAt = monotonicNowMs();
+                // Clear a modal BEFORE typing, not after: text typed into the interrupt prompt is
+                // consumed by the dialog, so recovering at submit time is already too late.
+                await this.clearInterruptPrompt();
                 await this.transport.write(text);
                 await delay(200);
-                await this.submitTurn();
+                const started = await this.submitTurn();
+                if (!started && this.done)
+                    break;
+                if (!started && !this.looksIdle()) {
+                    // NOT a lost message. The TUI accepts keystrokes into a queue while a turn is
+                    // running and only writes the user line when that turn ends, which can be far
+                    // longer than submitTurn() waits. Observed live: reported failed at 23:04:40,
+                    // delivered at 23:04:57. Telling the user it was lost is worse than saying
+                    // nothing, because they resend and the agent gets it twice.
+                    //
+                    // A busy terminal has accepted the input, so treat the turn as started and let
+                    // the stall backstop be the thing that notices if it never runs.
+                    this.recordLine("--- submit queued behind a running turn ---");
+                }
+                else if (!started) {
+                    // Idle terminal, five Enters, still no user line: the prompt genuinely did not
+                    // land and only the user can resend it.
+                    this.recordLine("--- submit failed: prompt never became a turn ---");
+                    this.emit(this.buildSubmitFailedResult());
+                    continue;
+                }
                 // The turn is now claude's to answer; start the liveness clock. submitTurn() has
-                // already confirmed claude accepted it (the transcript grew), so from here on
-                // silence means a stall, not a slow start.
+                // confirmed claude accepted it (a real user line landed), so from here on silence
+                // means a stall, not a slow start.
                 this.turnInFlight = true;
                 this.armStallTimer();
+                this.startHeartbeat();
             }
         }
         catch (err) {
             this.logger.warn({ err }, "PtyQuery input loop ended");
         }
     }
+    /**
+     * The message the user sees when the terminal would not take their prompt.
+     *
+     * Only reachable while the query is still live (teardown breaks out before this), so it
+     * always describes a message that genuinely did not land and that only the user can
+     * resend. Shaped as a normal result so it renders in the timeline rather than being
+     * buried in the daemon log.
+     */
+    buildSubmitFailedResult() {
+        const base = this.buildResult("submit_failed");
+        const excerpt = this.terminalTail.slice(-TERMINAL_TAIL_EXCERPT_CHARS).trim();
+        const tailLine = excerpt ? ` Last terminal output: ${JSON.stringify(excerpt)}.` : "";
+        return {
+            ...base,
+            subtype: "error_during_execution",
+            is_error: true,
+            errors: [
+                `Your message did not reach the agent: the terminal would not accept it. ` +
+                    `Nothing was sent, so please send it again. The session itself is still ` +
+                    `running.${tailLine}`,
+            ],
+        };
+    }
     /**
      * Press Enter to submit the composed prompt, and CONFIRM the turn actually started by
-     * watching the transcript grow — claude appends the user message to <sid>.jsonl the
-     * instant it accepts a turn. During boot the TUI intermittently swallows the first Enter
-     * (a "what's new" notice / MCP-auth warning steals focus), so retry until it takes.
+     * watching for the USER LINE claude appends to <sid>.jsonl the instant it accepts a turn.
+     * During boot the TUI intermittently swallows the first Enter (a "what's new" notice /
+     * MCP-auth warning steals focus), so retry until it takes.
+     *
+     * The confirmation used to be `transcriptSize() > before`, which is any growth at all.
+     * That is not specific to the turn starting: claude writes `attachment`, `last-prompt`
+     * and other bookkeeping lines on its own schedule, so a swallowed Enter that happened to
+     * coincide with unrelated writes read as success. Observed in production 2026-08-01: a
+     * session logged 157 consecutive `attachment` lines and NOT ONE `user` line, yet
+     * submitTurn returned on the first attempt. The prompt stayed unsent in the TUI composer,
+     * paseo set turnInFlight and waited on a turn that had never begun, and the agent showed
+     * a spinner until the liveness backstop fired ten minutes later. The retry loop below was
+     * always right; the thing it was checking was not.
+     */
+    /**
+     * Dismiss the post-interrupt modal if the terminal is showing one. ESC is only sent on a
+     * recent sighting: on an idle prompt it is harmless, but on a live turn it would interrupt
+     * real work, so a stale marker must never trigger it.
      */
+    async clearInterruptPrompt() {
+        if (!this.interruptPromptAt)
+            return;
+        if (monotonicNowMs() - this.interruptPromptAt > INTERRUPT_PROMPT_TTL_MS) {
+            this.interruptPromptAt = 0;
+            return;
+        }
+        this.logger.warn({ sessionId: this.sessionId, lastLine: this.lastMeaningfulLine.slice(-120) }, "PtyQuery: terminal is showing the post-interrupt prompt, dismissing it before submitting");
+        this.recordLine("--- dismissing post-interrupt prompt before submit ---");
+        for (let attempt = 0; attempt < 3 && this.interruptPromptAt && !this.done; attempt++) {
+            const seenAt = this.interruptPromptAt;
+            await this.transport.writeRaw?.("\u001b");
+            await delay(250);
+            // The marker only refreshes while the modal is still drawing; if it stopped, we are out.
+            if (this.interruptPromptAt === seenAt) {
+                this.interruptPromptAt = 0;
+                return;
+            }
+        }
+        this.interruptPromptAt = 0;
+    }
     async submitTurn() {
         const before = this.transcriptSize();
         for (let attempt = 0; attempt < 5 && !this.done; attempt++) {
             await this.transport.writeRaw?.("\r");
-            if (await pollUntil(() => this.transcriptSize() > before, 2500, 150))
-                return;
+            if (await pollUntil(() => this.sawUserLineSince(before), 2500, 150))
+                return true;
+        }
+        // Say WHICH it is. A busy terminal has queued the keystrokes and will run them when the
+        // current turn ends, so warning identically for both trained every reader (and the
+        // alerting built on this line) to treat a normal queue as a lost message.
+        const queued = !this.looksIdle();
+        this.logger[queued ? "info" : "warn"]({
+            sessionId: this.sessionId,
+            queuedBehindRunningTurn: queued,
+            lastLine: this.lastMeaningfulLine.slice(-120),
+        }, queued
+            ? "PtyQuery: prompt queued behind a running turn, no user line yet"
+            : "PtyQuery: turn did not start after submit retries");
+        return false;
+    }
+    /**
+     * True once a real `user` line has been appended past `offset`. Reads only the bytes
+     * added since then, so it stays cheap on a transcript that can reach tens of MB.
+     * `isMeta` user lines are claude's own bookkeeping and do not mean a turn started.
+     */
+    sawUserLineSince(offset) {
+        let fd = null;
+        try {
+            const size = this.transcriptSize();
+            if (size <= offset)
+                return false;
+            fd = fs.openSync(this.transcriptPath, "r");
+            const length = size - offset;
+            const buffer = Buffer.alloc(length);
+            fs.readSync(fd, buffer, 0, length, offset);
+            for (const line of buffer.toString("utf8").split("\n")) {
+                if (!line.trim())
+                    continue;
+                try {
+                    // A trailing partial line simply fails to parse; the next poll sees it whole.
+                    const parsed = JSON.parse(line);
+                    if (parsed?.type === "user" && !parsed.isMeta)
+                        return true;
+                }
+                catch {
+                    /* partial or non-JSON line */
+                }
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (fd !== null) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
         }
-        this.logger.warn({ sessionId: this.sessionId }, "PtyQuery: turn did not start after submit retries");
     }
     transcriptSize() {
         try {
@@ -200,6 +568,9 @@ export class PtyQuery {
                 this.lastUsage = beta.usage;
         }
         // Any transcript activity proves the turn is alive; push the stall deadline out.
+        this.lastTranscriptAt = monotonicNowMs();
+        // Real turn activity means the modal is gone, whatever the tail still remembers.
+        this.interruptPromptAt = 0;
         this.armStallTimer();
         this.scheduleTurnEndCheck();
     }
@@ -218,6 +589,7 @@ export class PtyQuery {
         // The turn ended on its own; stand the liveness backstop down before emitting.
         this.turnInFlight = false;
         this.clearStallTimer();
+        this.stopHeartbeat();
         this.emit(this.buildResult(stop));
         // reset so a stale terminal reason can't re-fire before the next assistant turn
         this.lastStopReason = null;
@@ -250,14 +622,165 @@ export class PtyQuery {
         if (this.done || !this.turnInFlight)
             return;
         this.turnInFlight = false;
+        this.stopHeartbeat();
         const silentForMs = this.stallTimeoutMs;
+        const terminalTail = this.readTerminalTail();
+        this.recordLine(`--- STALLED after ${silentForMs}ms of transcript silence ---`);
         this.logger.error({
             sessionId: this.sessionId,
             transcriptPath: this.transcriptPath,
             silentForMs,
+            // The whole point of the tap: whatever the TUI was showing while it went quiet.
+            terminalTail,
         }, "PtyQuery: turn stalled, no transcript activity within the liveness budget");
         this.numTurns += 1;
-        this.emit(this.buildStalledResult(silentForMs));
+        this.emit(this.buildStalledResult(silentForMs, terminalTail));
+    }
+    /**
+     * Append terminal output to the rolling tail.
+     *
+     * Scrubbed and filtered on the way IN, not on the way out, because the TUI's spinner
+     * redraws at a few hundred bytes/second: a raw buffer holds only a second or two of
+     * history and would evict the one line worth reading. Keeping only lines that carry
+     * letters or digits means a message like "Compacting conversation…" survives minutes of
+     * animation. Verified against a real stall: the raw tail was 163 chars of pure spinner.
+     */
+    /**
+     * True when the rolling tail's last frame looks like an input box waiting for typing.
+     *
+     * Deliberately requires the busy marker to be ABSENT rather than trusting the prompt
+     * markers alone: the working footer renders as `… · esc to interrupt · ← for agents`, so
+     * "for agents" on its own is present in both states and would read a mid-turn terminal
+     * as idle.
+     */
+    looksIdle() {
+        const tail = this.terminalTail.slice(-400).toLowerCase();
+        if (!tail)
+            return false;
+        if (tail.includes(BUSY_MARKER))
+            return false;
+        if (this.lastBusyAt > 0 && monotonicNowMs() - this.lastBusyAt < READY_IDLE_STABLE_MS)
+            return false;
+        return IDLE_PROMPT_MARKERS.some((m) => tail.includes(m));
+    }
+    appendTerminalTail(chunk) {
+        if (!chunk)
+            return;
+        this.ptyBytesTotal += chunk.length;
+        const text = stripTerminalControl(chunk);
+        if (!text)
+            return;
+        // Read the busy marker off the raw stripped text, NOT the filtered tail below:
+        // isProgressNoise() drops a line that is only the footer, which is exactly the frame
+        // that proves a turn is running.
+        if (text.toLowerCase().includes(BUSY_MARKER))
+            this.lastBusyAt = monotonicNowMs();
+        for (const rawLine of text.split("\n")) {
+            const line = rawLine.trim();
+            if (!line || !/[a-z0-9]/i.test(line))
+                continue;
+            if (isProgressNoise(line))
+                continue;
+            // de-dupe consecutive identical redraws of the same line
+            if (this.terminalTail.endsWith(line + "\n"))
+                continue;
+            this.terminalTail += line + "\n";
+            this.lastMeaningfulLine = line;
+            if (line.toLowerCase().includes(INTERRUPT_PROMPT_MARKER)) {
+                this.interruptPromptAt = monotonicNowMs();
+            }
+            this.recordLine(line);
+        }
+        if (this.terminalTail.length > TERMINAL_TAIL_MAX_CHARS) {
+            this.terminalTail = this.terminalTail.slice(-TERMINAL_TAIL_MAX_CHARS);
+        }
+    }
+    // ---- telemetry ------------------------------------------------------------
+    /** Open `$PASEO_HOME/pty-recordings/<sessionId>.log`. Best-effort: never fail a session. */
+    openRecording() {
+        try {
+            const home = process.env.PASEO_HOME;
+            if (!home)
+                return;
+            const dir = path.join(home, "pty-recordings");
+            fs.mkdirSync(dir, { recursive: true });
+            this.recordingPath = path.join(dir, `${this.sessionId}.log`);
+            this.recordingBytes = this.safeSize(this.recordingPath);
+            this.recordLine(`--- PtyQuery attached, transcript=${this.transcriptPath} ---`);
+            this.logger.debug({ sessionId: this.sessionId, recordingPath: this.recordingPath }, "PtyQuery: recording terminal output");
+        }
+        catch {
+            this.recordingPath = null;
+        }
+    }
+    recordLine(line) {
+        if (!this.recordingPath)
+            return;
+        try {
+            const entry = `${new Date().toISOString()} ${line}\n`;
+            fs.appendFileSync(this.recordingPath, entry);
+            this.recordingBytes += entry.length;
+            if (this.recordingBytes > RECORDING_MAX_BYTES) {
+                // Keep the recent past, drop the rest. Diagnostics, not an audit trail.
+                const kept = fs.readFileSync(this.recordingPath).subarray(-RECORDING_KEEP_BYTES);
+                fs.writeFileSync(this.recordingPath, kept);
+                this.recordingBytes = kept.length;
+            }
+        }
+        catch {
+            this.recordingPath = null;
+        }
+    }
+    safeSize(p) {
+        try {
+            return fs.statSync(p).size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * While a turn is outstanding, emit one line every {@link LIVENESS_HEARTBEAT_MS} with
+     * enough state to tell the failure modes apart without waiting for the stall budget:
+     * terminal bytes since the last beat (0 means the TUI is frozen, not thinking), seconds
+     * since the transcript last grew, and the last meaningful line on screen.
+     */
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.ptyBytesAtLastBeat = this.ptyBytesTotal;
+        this.heartbeatTimer = setInterval(() => this.beat(), LIVENESS_HEARTBEAT_MS);
+        this.heartbeatTimer.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+    }
+    beat() {
+        if (this.done || !this.turnInFlight) {
+            this.stopHeartbeat();
+            return;
+        }
+        const ptyBytesSinceLastBeat = this.ptyBytesTotal - this.ptyBytesAtLastBeat;
+        this.ptyBytesAtLastBeat = this.ptyBytesTotal;
+        this.logger.info({
+            sessionId: this.sessionId,
+            event: "pty.turn.heartbeat",
+            turnAgeMs: this.turnStartedAt ? monotonicNowMs() - this.turnStartedAt : 0,
+            ptyBytesSinceLastBeat,
+            secondsSinceTranscript: this.lastTranscriptAt
+                ? Math.round((monotonicNowMs() - this.lastTranscriptAt) / 1000)
+                : null,
+            readySettledBy: this.readySettledBy,
+            lastLine: this.lastMeaningfulLine.slice(-160),
+        }, "PtyQuery: turn in flight");
+    }
+    /**
+     * The tail as readable text: ANSI/OSC sequences dropped and runs of whitespace collapsed,
+     * because a raw TUI capture is mostly cursor movement and redraw padding.
+     */
+    readTerminalTail() {
+        return this.terminalTail.trim().slice(-TERMINAL_TAIL_MAX_CHARS);
     }
     buildResult(stopReason) {
         const usage = (this.lastUsage ?? {
@@ -269,7 +792,7 @@ export class PtyQuery {
         const result = {
             type: "result",
             subtype: "success",
-            duration_ms: this.turnStartedAt ? Date.now() - this.turnStartedAt : 0,
+            duration_ms: this.turnStartedAt ? Math.round(monotonicNowMs() - this.turnStartedAt) : 0,
             duration_api_ms: 0,
             is_error: false,
             num_turns: this.numTurns,
@@ -284,18 +807,13 @@ export class PtyQuery {
         };
         return result;
     }
-    /**
-     * A non-success `result` for a stalled turn. agent.ts's `appendResultEvents()` turns any
-     * `subtype !== "success"` into a `turn_failed` carrying `errors.join("\n")`, which is what
-     * puts a real message in front of the user.
-     *
-     * Wording matters: `isAbortError()` suppresses results whose errors match /\baborted\b/i,
-     * and `buildTurnFailedEvent()` scrapes /\bcode\s+(\d+)\b/i for an exit code. Avoid both so
-     * this neither gets swallowed nor reports a phantom exit code.
-     */
-    buildStalledResult(silentForMs) {
+    buildStalledResult(silentForMs, terminalTail) {
         const minutes = Math.round(silentForMs / 60000);
         const base = this.buildResult("stall_timeout");
+        // The last thing the terminal showed is usually the whole diagnosis ("Compacting
+        // conversation…", a retry notice), so lead the message with it when we have one.
+        const excerpt = (terminalTail ?? "").slice(-TERMINAL_TAIL_EXCERPT_CHARS).trim();
+        const tailLine = excerpt ? ` Last terminal output: ${JSON.stringify(excerpt)}.` : "";
         return {
             ...base,
             subtype: "error_during_execution",
@@ -303,8 +821,7 @@ export class PtyQuery {
             errors: [
                 `No response from the claude PTY session for ${minutes} min. ` +
                     `The turn was accepted but produced no output, so it was marked failed. ` +
-                    `The underlying session is still running and may recover; check the provider ` +
-                    `endpoint and credentials, then retry.`,
+                    `The underlying session is still running and may recover.${tailLine}`,
             ],
         };
     }
@@ -349,10 +866,70 @@ function extractUserText(message) {
     }
     return "";
 }
+/**
+ * Drop ANSI/OSC sequences and remaining control chars. Scanned by code point rather than a
+ * regex so the source carries no control characters and avoids no-control-regex (same
+ * approach as sanitizeUploadFilename).
+ */
+function stripTerminalControl(src) {
+    const ESC = 0x1b;
+    const BEL = 0x07;
+    const out = [];
+    for (let i = 0; i < src.length; i++) {
+        const code = src.charCodeAt(i);
+        if (code === ESC) {
+            const next = src[i + 1];
+            if (next === "[") {
+                i += 2;
+                while (i < src.length && !isCsiFinal(src.charCodeAt(i)))
+                    i++;
+            }
+            else if (next === "]") {
+                i += 2;
+                while (i < src.length && src.charCodeAt(i) !== BEL && src.charCodeAt(i) !== ESC)
+                    i++;
+                if (i < src.length && src.charCodeAt(i) === ESC)
+                    i++;
+            }
+            else {
+                i += 1;
+            }
+            continue;
+        }
+        if (code === 0x0a) {
+            out.push("\n");
+            continue;
+        }
+        if (code === 0x09) {
+            out.push(" ");
+            continue;
+        }
+        if (code <= 0x1f || code === 0x7f)
+            continue;
+        out.push(src[i]);
+    }
+    return out.join("").replace(/[ ]{2,}/g, " ");
+}
+/**
+ * True for the TUI's own progress chrome: spinner frames, the elapsed-time counter and
+ * token tickers. These redraw constantly and carry no diagnostic value, and keeping them
+ * would evict the lines that do.
+ */
+function isProgressNoise(line) {
+    if (/^[^a-z]*\d+m?\s*\d*s\)?[^a-z]*$/i.test(line))
+        return true;
+    if (/^\W*(esc to interrupt|ctrl\+[a-z])\W*$/i.test(line))
+        return true;
+    const letters = (line.match(/[a-z]/gi) ?? []).length;
+    return letters < 3;
+}
+function isCsiFinal(code) {
+    return code >= 0x40 && code <= 0x7e;
+}
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function pollUntil(cond, timeoutMs, intervalMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
+    const deadline = monotonicNowMs() + timeoutMs;
+    while (monotonicNowMs() < deadline) {
         if (cond())
             return true;
         await delay(intervalMs);