@hyperdrive.bot/paseo-server 0.3.38 → 0.3.40

package/README.md

@@ -24,7 +24,7 @@ npm run dev
 - **Vite Dev Server** (port 5173) - Hot-reload React UI in development
 - **WebSocket** (`/ws`) - Real-time bidirectional communication
 - **Agent** - STT → LLM → TTS pipeline with terminal control
-- **Daemon** - tmux-based terminal management (in-process)
+- **Daemon** - node-pty terminal management (in-process)
 
 ## Development
 
@@ -57,7 +57,7 @@ npm start
 
 **⏳ In Progress** (Phase 3):
 
-- Terminal control (tmux integration)
+- Terminal control (node-pty integration)
 
 **📋 Planned** (Phases 4-9):
 
@@ -92,7 +92,7 @@ PASEO_HOME=~/.paseo-blue PASEO_LISTEN=127.0.0.1:7777 npm run dev
 
 - **Server**: Express, TypeScript, ws (WebSocket)
 - **Client**: React 18, Vite, TypeScript
-- **Terminal**: tmux (via child_process)
+- **Terminal**: node-pty (in-process PTY) + @xterm/headless (screen model)
 - **AI**: OpenAI (LLM + TTS), Deepgram (STT)
 
 ## Testing

package/dist/server/server/agent/providers/claude/agent.d.ts

@@ -296,6 +296,16 @@ export declare class ClaudeAgentSession implements AgentSession {
      * Scoped to questions on purpose: a plan dialog's options are the CLI's and version-
      * dependent, so guessing an index there could approve an implementation nobody chose.
      */
+    /**
+     * Surface a delivery-path notice to whoever sent the message.
+     *
+     * Uses the same synthetic-timeline-message channel executeRewindTurn() already uses, so
+     * this needs no protocol change and renders in every client that renders a turn today.
+     * The alternative, PtyQuery.emit(), is the SDK message stream, where the only shapes
+     * available are `result` messages -- and a result ENDS the turn, which is the opposite
+     * of what a "still queued" notice means.
+     */
+    private emitPtyNotice;
     private handlePtyDialogChange;
     /** Map the app's chosen answer back to the dialog's option index and press the keys. */
     private answerPtyDialogFromPermission;

package/dist/server/server/agent/providers/claude/agent.js

@@ -2568,6 +2568,7 @@ export class ClaudeAgentSession {
                     : undefined,
                 logger: this.logger,
                 onDialogChange: (dialog) => this.handlePtyDialogChange(dialog),
+                onNotice: (text) => this.emitPtyNotice(text),
             });
             this.activeTransport = ptySession.transport;
             this.query = ptySession.query;
@@ -3660,6 +3661,22 @@ export class ClaudeAgentSession {
      * Scoped to questions on purpose: a plan dialog's options are the CLI's and version-
      * dependent, so guessing an index there could approve an implementation nobody chose.
      */
+    /**
+     * Surface a delivery-path notice to whoever sent the message.
+     *
+     * Uses the same synthetic-timeline-message channel executeRewindTurn() already uses, so
+     * this needs no protocol change and renders in every client that renders a turn today.
+     * The alternative, PtyQuery.emit(), is the SDK message stream, where the only shapes
+     * available are `result` messages -- and a result ENDS the turn, which is the opposite
+     * of what a "still queued" notice means.
+     */
+    emitPtyNotice(text) {
+        this.notifySubscribers({
+            type: "timeline",
+            provider: "claude",
+            item: { type: "assistant_message", text },
+        });
+    }
     handlePtyDialogChange(dialog) {
         if (!dialog) {
             const pendingId = this.ptyDialogRequestId;

package/dist/server/server/agent/providers/claude/pty-session-launcher.d.ts

@@ -25,6 +25,8 @@ export interface CreatePtySessionOptions {
     };
     /** Surfaces TUI question/plan dialogs so the provider can raise a permission request. */
     onDialogChange?: (dialog: PtyInteractiveDialog | null) => void;
+    /** Sender-facing notice from the delivery path (see PtyQueryOptions.onNotice). */
+    onNotice?: (text: string) => void;
 }
 export interface PtySession {
     transport: PtyTransport;

package/dist/server/server/agent/providers/claude/pty-session-launcher.js

@@ -56,6 +56,7 @@ export async function createPtySession(opts) {
         sessionId: opts.sessionId,
         logger: opts.logger,
         ...(opts.onDialogChange ? { onDialogChange: opts.onDialogChange } : {}),
+        ...(opts.onNotice ? { onNotice: opts.onNotice } : {}),
     });
     opts.logger.debug({ pid: transport.context().pid, sessionId: opts.sessionId, transcriptPath }, "PTY claude session spawned");
     return { transport, query, transcriptPath, systemPromptFilePath };

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

@@ -1,6 +1,6 @@
 import type { Logger } from "pino";
 import type { ModelInfo, SDKMessage, SDKSystemMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
-import type { PtyTransport } from "./pty.js";
+import { type PtyTransport } from "./pty.js";
 /** An interactive TUI dialog the user has to answer for the turn to continue. */
 export interface PtyInteractiveDialog {
     toolUseId: string;
@@ -31,6 +31,16 @@ export interface PtyQueryOptions {
      * the real options instead of an inert tool chip nobody can answer.
      */
     onDialogChange?: (dialog: PtyInteractiveDialog | null) => void;
+    /**
+     * Called with a short, sender-facing sentence when paseo knows something the person who
+     * sent the message cannot see. Today that is exactly one thing: the message was accepted
+     * but QUEUED behind a running turn, so the spinner they are looking at means "waiting in
+     * line", not "working on it".
+     *
+     * Everything PtyQuery already knew about this went to recordLine(), which appends to
+     * ~/.paseo/pty-recordings/<id>.log and reaches nobody.
+     */
+    onNotice?: (text: string) => void;
 }
 export declare class PtyQuery implements AsyncGenerator<SDKMessage, void> {
     private readonly transport;
@@ -40,11 +50,18 @@ export declare class PtyQuery implements AsyncGenerator<SDKMessage, void> {
     private readonly logger;
     private readonly reader;
     private readonly onDialogChange;
+    private readonly onNotice;
+    /** One queued notice per message, not one per retry. Reset by deliverPrompt(). */
+    private queuedNoticeSent;
     private readonly outQueue;
     private readonly outResolvers;
     private done;
     private readonly readyPromise;
     private offReadyData;
+    /** Unsubscribes the transport exit tap. Teardown MUST call this. */
+    private offExitTap;
+    /** Set once the agent process has exited; the two remaining "still running" claims read it. */
+    private transportExited;
     /**
      * Cancels the readiness gate and its timers.
      *
@@ -120,6 +137,16 @@ export declare class PtyQuery implements AsyncGenerator<SDKMessage, void> {
      * agent running by the time the input loop sees it: silence here is a forever-spinner.
      */
     private buildNothingDeliverableResult;
+    /**
+     * " The session itself is still running." -- but only when it is.
+     *
+     * The exit tap fixes the in-flight turn and the stall message. These two other results
+     * asserted the same thing unconditionally and are reachable after the process is gone, so
+     * they need the same correction. Wording matches buildExitedResult: no "aborted", and
+     * "status" rather than "code", so isAbortError() cannot swallow it and
+     * buildTurnFailedEvent() cannot scrape a phantom exit code out of it.
+     */
+    private stillRunningClause;
     /** Tell the provider the dialog state changed; never let a listener throw into the loop. */
     private notifyDialogChange;
     /** The dialog the TUI is waiting on, if any. */
@@ -192,6 +219,19 @@ export declare class PtyQuery implements AsyncGenerator<SDKMessage, void> {
      * pasted chip is dropped the same way. Best-effort: a transport that cannot take raw
      * keys just leaves the composer as it was.
      */
+    /**
+     * Is the TUI currently showing its "queued messages" footer?
+     *
+     * This reads a CLI STATUS LINE, not a rendering of our own text. The distinction matters
+     * because this file has (rightly) burned four incidents on trusting renderings as proof
+     * of DELIVERY -- bytes, then echoed text, then a raw probe, then a paste chip. Delivery
+     * is still proved by one thing only, a matching `user` record. The footer answers a
+     * different and much cheaper question: is a turn running right now. The CLI is the
+     * authority on that, and it prints the answer.
+     */
+    private queuedFooterVisible;
+    /** Tell the sender their message is in line, once per message. */
+    private notifyQueued;
     private clearComposer;
     /**
      * Deliver a prompt and prove it, or say it failed. See docs/pty-delivery.md.
@@ -318,6 +358,24 @@ export declare class PtyQuery implements AsyncGenerator<SDKMessage, void> {
      */
     private readTerminalTail;
     private buildResult;
+    /**
+     * The agent process exited. Fail any in-flight turn immediately and end the query.
+     *
+     * Unlike a stall there is nothing to wait for: no retry, no recovery, no later transcript
+     * activity. Emitting here rather than letting the stall timer fire turns a ten-minute wait
+     * plus a false "still running" into an immediate, accurate failure, and finishing the query
+     * stops the layer above treating this transport as a live destination for prompts.
+     */
+    private onTransportExit;
+    /**
+     * A non-success `result` for an agent that exited.
+     *
+     * Wording constraints match {@link buildStalledResult}: `isAbortError()` drops results
+     * matching /\baborted\b/i and `buildTurnFailedEvent()` scrapes /\bcode\s+(\d+)\b/i for an
+     * exit code, so this says "status", never "code", and never says "aborted". It also must
+     * NOT claim the session is still running, which is the exact lie this change deletes.
+     */
+    private buildExitedResult;
     private buildStalledResult;
     interrupt(): Promise<void>;
     setPermissionMode(): Promise<void>;

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

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { PtyExitedError } from "./pty.js";
 import { TranscriptSdkReader } from "./transcript-sdk-reader.js";
 /**
  * PtyQuery — a `Query`-shaped adapter over an interactive `claude` PTY.
@@ -102,6 +103,33 @@ const RECEIPT_EXACT_MATCH_BELOW_CHARS = 12;
 const RECEIPT_WINDOW_MS = 4000;
 /** A queued message can only land when the running turn ends, so wait far longer for it. */
 const QUEUED_RECEIPT_WINDOW_MS = 10 * 60000;
+/**
+ * The TUI's own words for "your message is in the queue".
+ *
+ * A message typed while a turn is running is QUEUED by claude, and a queued message
+ * appends NO `user` record until the running turn ends -- so the one delivery oracle
+ * (receiptSince) cannot fire, by construction, for minutes at a time. The old test for
+ * "is a turn running" was `lastTranscriptAt > attemptStartedAt`, i.e. "did the transcript
+ * grow during my 4s window". That is a proxy, and it reads FALSE whenever the running
+ * turn is simply quiet for four seconds (thinking, or one slow tool call). When it reads
+ * false the loop concludes the terminal is deaf and retypes.
+ *
+ * Retyping a QUEUED message is not idempotent: the composer is empty (the text already
+ * left it), so Ctrl+U clears nothing and the retype either stacks a second queued copy or
+ * concatenates onto text the clear failed to kill. Observed live 2026-08-20 on session
+ * 0b1ec622, four retries logged at 18:28:13 / 18:29:59 / 18:30:06 / 18:30:14 / 18:30:27,
+ * producing these transcript records:
+ *
+ *   mint another xpmint another xp
+ *   a new one with another cpf: 76797678153, caixaa new one with another cpf: ...
+ *
+ * The terminal was stating the answer the whole time. Paseo's own turn heartbeat captured
+ * it at 18:30:15: `... Press up to edit queued messages - esc to interrupt`. This reads
+ * that footer instead of inferring it from file growth.
+ */
+const QUEUED_FOOTER_RE = /Press up to edit queued messages/i;
+/** How much of the tail to scan for the footer. It is repainted on every frame. */
+const QUEUED_FOOTER_SCAN_CHARS = 2000;
 /** Backoff between retype attempts against a deaf terminal. */
 const DEAF_RETRY_INITIAL_MS = 2000;
 const DEAF_RETRY_MAX_MS = 60000;
@@ -211,11 +239,17 @@ function monotonicNowMs() {
 }
 export class PtyQuery {
     constructor(opts) {
+        /** One queued notice per message, not one per retry. Reset by deliverPrompt(). */
+        this.queuedNoticeSent = false;
         // output queue → async iterator
         this.outQueue = [];
         this.outResolvers = [];
         this.done = false;
         this.offReadyData = null;
+        /** Unsubscribes the transport exit tap. Teardown MUST call this. */
+        this.offExitTap = null;
+        /** Set once the agent process has exited; the two remaining "still running" claims read it. */
+        this.transportExited = null;
         /**
          * Cancels the readiness gate and its timers.
          *
@@ -270,6 +304,7 @@ export class PtyQuery {
         this.logger = opts.logger;
         this.stallTimeoutMs = opts.stallTimeoutMs ?? TURN_STALL_TIMEOUT_MS;
         this.onDialogChange = opts.onDialogChange ?? null;
+        this.onNotice = opts.onNotice ?? null;
         this.reader = new TranscriptSdkReader({
             transcriptPath: opts.transcriptPath,
             onMessage: (m) => this.onTranscriptMessage(m),
@@ -281,6 +316,12 @@ export class PtyQuery {
         // 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));
+        // Learn about the agent process dying the moment it happens. Without this tap the only
+        // thing that ever noticed was the stall backstop, ten minutes later, and it then told the
+        // user the session was "still running and may recover" - of a process that had already
+        // printed its farewell banner and exited. The stall timer is for a live agent that is
+        // slow; it is the wrong instrument for a dead one.
+        this.offExitTap = this.transport.onExit((code, signal) => this.onTransportExit(code, signal));
         // 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
@@ -437,6 +478,8 @@ export class PtyQuery {
         this.offReadyData?.();
         this.offTerminalTap?.();
         this.offTerminalTap = null;
+        this.offExitTap?.();
+        this.offExitTap = null;
         this.stopHeartbeat();
         this.recordLine("--- PtyQuery detached ---");
         try {
@@ -503,6 +546,13 @@ export class PtyQuery {
                     this.emit(this.buildCommandRejectedResult(notice));
                     continue;
                 }
+                if (delivery === "exited") {
+                    // Dead, not deaf. `continue`, never `break`: the exit tap is what ends this query,
+                    // and breaking here would instead leave the input channel undrained, so a resend
+                    // would sit unread and the sender would watch a spinner - the symptom being fixed.
+                    this.emit(this.buildExitedResult(this.transportExited?.code ?? null, this.transportExited?.signal ?? null));
+                    continue;
+                }
                 if (delivery === "undelivered") {
                     // No transcript receipt for the whole budget: the message never became a turn,
                     // nothing was queued, and only the sender can decide what to do next.
@@ -590,11 +640,27 @@ export class PtyQuery {
             is_error: true,
             errors: [
                 `Your message had nothing the terminal transport could deliver: no text, and no ` +
-                    `image it could stage to disk. Nothing was sent, so please resend it with text. ` +
-                    `The session itself is still running.`,
+                    `image it could stage to disk. Nothing was sent, so please resend it with text.` +
+                    `${this.stillRunningClause()}`,
             ],
         };
     }
+    /**
+     * " The session itself is still running." -- but only when it is.
+     *
+     * The exit tap fixes the in-flight turn and the stall message. These two other results
+     * asserted the same thing unconditionally and are reachable after the process is gone, so
+     * they need the same correction. Wording matches buildExitedResult: no "aborted", and
+     * "status" rather than "code", so isAbortError() cannot swallow it and
+     * buildTurnFailedEvent() cannot scrape a phantom exit code out of it.
+     */
+    stillRunningClause() {
+        if (!this.transportExited)
+            return " The session itself is still running.";
+        return (` The agent process has exited, so the session is NOT running any more and will not ` +
+            `recover on its own; the conversation is still on disk, recover it with ` +
+            `"paseo import ${this.sessionId}".`);
+    }
     /** Tell the provider the dialog state changed; never let a listener throw into the loop. */
     notifyDialogChange() {
         if (!this.onDialogChange)
@@ -697,8 +763,7 @@ export class PtyQuery {
             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}`,
+                    `Nothing was sent, so please send it again.${this.stillRunningClause()}${tailLine}`,
             ],
         };
     }
@@ -788,9 +853,60 @@ export class PtyQuery {
      * pasted chip is dropped the same way. Best-effort: a transport that cannot take raw
      * keys just leaves the composer as it was.
      */
+    /**
+     * Is the TUI currently showing its "queued messages" footer?
+     *
+     * This reads a CLI STATUS LINE, not a rendering of our own text. The distinction matters
+     * because this file has (rightly) burned four incidents on trusting renderings as proof
+     * of DELIVERY -- bytes, then echoed text, then a raw probe, then a paste chip. Delivery
+     * is still proved by one thing only, a matching `user` record. The footer answers a
+     * different and much cheaper question: is a turn running right now. The CLI is the
+     * authority on that, and it prints the answer.
+     */
+    queuedFooterVisible() {
+        return QUEUED_FOOTER_RE.test(this.terminalTail.slice(-QUEUED_FOOTER_SCAN_CHARS));
+    }
+    /** Tell the sender their message is in line, once per message. */
+    notifyQueued() {
+        if (this.queuedNoticeSent)
+            return;
+        this.queuedNoticeSent = true;
+        try {
+            this.onNotice?.("Your message was accepted and is queued behind the turn this session is already " +
+                "running. It will start as soon as that turn finishes.");
+        }
+        catch (err) {
+            this.logger.debug({ err }, "PtyQuery: queued notice callback threw");
+        }
+    }
     async clearComposer() {
         try {
-            await this.transport.writeRaw?.("\u0015");
+            // Ctrl+E (end of line), Ctrl+U (kill to start), Ctrl+K (kill to end).
+            //
+            // Ctrl+U alone was not enough. In a readline-style buffer it kills from the CURSOR
+            // to the start of the line: it empties the composer only when the cursor already
+            // sits at the end, and it never touches what is after the cursor. Live 2026-08-20 a
+            // retype landed ON TOP of text a Ctrl+U was supposed to have killed, which is how
+            // session 0b1ec622 got these into its transcript:
+            //
+            //   mint another xpmint another xp
+            //   a new one with another cpf: 76797678153, caixaa new one with another cpf: ...
+            //
+            // This sequence is cursor-position independent and idempotent: all three keys are
+            // no-ops on an already empty composer, so it cannot damage the common case. Each
+            // gets its own beat, because the TUI only processes keys as fast as its input loop
+            // drains them.
+            //
+            // It makes the clear far more likely to succeed. It does NOT prove the composer is
+            // empty, and this file deliberately has no way to prove that: every signal for it is
+            // a rendering, and renderings are what four earlier incidents taught it not to
+            // trust. The real protection against duplication is not retyping at all once the
+            // text has demonstrably left the composer -- the queued-footer guard in
+            // deliverPrompt(), which removes the case behind every duplicate observed so far.
+            for (const key of ["\u0005", "\u0015", "\u000b"]) {
+                await this.transport.writeRaw?.(key);
+                await delay(60);
+            }
             await delay(120);
         }
         catch (err) {
@@ -809,12 +925,18 @@ export class PtyQuery {
      * running turn is never retyped - that is the one way to send it twice.
      */
     async deliverPrompt(text) {
+        this.queuedNoticeSent = false;
         const fingerprint = PtyQuery.fingerprint(text);
         const watermark = this.transcriptSize();
         const deadline = monotonicNowMs() + READY_BUSY_MAX_WAIT_MS;
         let backoff = DEAF_RETRY_INITIAL_MS;
         let attempt = 0;
         while (!this.done && monotonicNowMs() < deadline) {
+            // Re-checked every attempt, not once up front: the child can die between attempts and
+            // this loop's budget is ten minutes. Retrying into a corpse is what produced the
+            // "no delivery receipt; retrying" storms that ended at the 20-retry cap.
+            if (this.transportExited)
+                return "exited";
             attempt += 1;
             const attemptStartedAt = monotonicNowMs();
             // Empty the input box first: whatever an earlier attempt may have left there is
@@ -822,7 +944,17 @@ export class PtyQuery {
             // became nine stacked paste blocks in production.
             if (attempt > 1)
                 await this.clearComposer();
-            await this.transport.write(text);
+            try {
+                await this.transport.write(text);
+            }
+            catch (err) {
+                // The transport now refuses a write into a dead pty. Without this catch the rejection
+                // escapes deliverPrompt into the input loop's handler, which only logs "input loop
+                // ended" -- so the sender would watch a spinner and never be told anything.
+                if (err instanceof PtyExitedError)
+                    return "exited";
+                throw err;
+            }
             const submitted = await this.submitTurn(text, watermark, fingerprint);
             if (submitted === "rejected")
                 return "rejected";
@@ -833,15 +965,35 @@ export class PtyQuery {
                 return "delivered";
             }
             // No receipt. Is a turn actually RUNNING (so our text is queued behind it), or was
-            // the Enter simply swallowed? File growth cannot tell those apart: claude writes
-            // `attachment` and other bookkeeping records on its own schedule, and treating that
-            // as "queued" would sit here for ten minutes while the prompt was never submitted
-            // (the 2026-08-01 bug, in reverse). Real SDK messages arriving IS a running turn.
-            if (this.lastTranscriptAt > attemptStartedAt) {
+            // the Enter simply swallowed? Two independent signals, ORed on purpose:
+            //
+            //   - the TUI's own queued footer, which is the CLI stating the fact outright, and
+            //   - real SDK messages arriving during this attempt, the original heuristic.
+            //
+            // File growth alone cannot tell queued from swallowed: claude writes `attachment`
+            // and other bookkeeping records on its own schedule, and treating that as "queued"
+            // would sit here for ten minutes while the prompt was never submitted (the
+            // 2026-08-01 bug, in reverse). But it also misses the common case, a running turn
+            // that is quiet for the four-second receipt window, and the cost of missing it is a
+            // retype that corrupts the queued prompt. The footer settles that case directly.
+            if (this.queuedFooterVisible() || this.lastTranscriptAt > attemptStartedAt) {
                 this.recordLine("--- no receipt yet; queued behind a running turn ---");
+                // Say so where the sender can see it. Once per message, not once per poll.
+                this.notifyQueued();
                 const late = await pollUntil(() => this.receiptSince(watermark, fingerprint), QUEUED_RECEIPT_WINDOW_MS, 500);
                 if (late)
                     return "delivered";
+                // Queued, and still no receipt after the full window. Do NOT fall through to the
+                // retype: the text is demonstrably out of the composer, so retyping cannot undo
+                // anything and can only stack a duplicate.
+                //
+                // "unconfirmed", never "undelivered". They are not interchangeable here:
+                // `undelivered` makes the caller emit buildSubmitFailedResult(), whose text is
+                // "Nothing was sent, so please send it again" -- a lie about a message sitting in
+                // claude's queue, and an instruction that produces the exact duplicate this branch
+                // exists to prevent. `unconfirmed` means "accepted, start not observed", which is
+                // true, and the stall backstop is already the right net for it.
+                return "unconfirmed";
             }
             this.logger.warn({ sessionId: this.sessionId, attempt, nextRetryMs: backoff }, "PtyQuery: no delivery receipt for the prompt; retrying");
             this.recordLine(`--- no delivery receipt (attempt ${attempt}); retrying in ${Math.round(backoff / 1000)}s ---`);
@@ -1324,7 +1476,62 @@ export class PtyQuery {
         };
         return result;
     }
+    /**
+     * The agent process exited. Fail any in-flight turn immediately and end the query.
+     *
+     * Unlike a stall there is nothing to wait for: no retry, no recovery, no later transcript
+     * activity. Emitting here rather than letting the stall timer fire turns a ten-minute wait
+     * plus a false "still running" into an immediate, accurate failure, and finishing the query
+     * stops the layer above treating this transport as a live destination for prompts.
+     */
+    onTransportExit(code, signal) {
+        // Recorded before the `done` bail: the wording helpers and the delivery guards must know
+        // the process is gone even when the query had already been torn down.
+        this.transportExited ?? (this.transportExited = { code, signal });
+        if (this.done)
+            return;
+        const wasInFlight = this.turnInFlight;
+        this.turnInFlight = false;
+        this.clearStallTimer();
+        this.logger.error({ sessionId: this.sessionId, exitCode: code, exitSignal: signal, wasInFlight }, "PtyQuery: the agent process exited");
+        this.recordLine(`--- agent process exited (status ${code ?? "none"}, signal ${signal ?? "none"}) ---`);
+        if (wasInFlight) {
+            this.numTurns += 1;
+            this.emit(this.buildExitedResult(code, signal));
+        }
+        this.finish();
+    }
+    /**
+     * A non-success `result` for an agent that exited.
+     *
+     * Wording constraints match {@link buildStalledResult}: `isAbortError()` drops results
+     * matching /\baborted\b/i and `buildTurnFailedEvent()` scrapes /\bcode\s+(\d+)\b/i for an
+     * exit code, so this says "status", never "code", and never says "aborted". It also must
+     * NOT claim the session is still running, which is the exact lie this change deletes.
+     */
+    buildExitedResult(code, signal) {
+        const base = this.buildResult("process_exited");
+        const how = signal ? `on signal ${signal}` : `with status ${code ?? "unknown"}`;
+        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: [
+                `The agent process exited ${how} before finishing this turn, so the session is NOT ` +
+                    `running any more and will not recover on its own. The conversation is still on ` +
+                    `disk: recover it with "paseo import ${this.sessionId}", then restore the agent's ` +
+                    `model, thinking budget and permission mode, which import does not carry over.` +
+                    tailLine,
+            ],
+        };
+    }
     buildStalledResult(silentForMs, terminalTail) {
+        // A dead process is not a stall, and must never be described as one that "may recover".
+        if (this.transportExited) {
+            return this.buildExitedResult(this.transportExited.code, this.transportExited.signal);
+        }
         const minutes = Math.round(silentForMs / 60000);
         const base = this.buildResult("stall_timeout");
         // The last thing the terminal showed is usually the whole diagnosis ("Compacting

package/dist/server/server/agent/providers/claude/transport/pty.d.ts

@@ -28,6 +28,23 @@ export interface PtyInputEvent {
 /** Install (or clear, with null) the input-provenance sink. */
 export declare function setPtyInputSink(sink: ((event: PtyInputEvent) => void) | null): void;
 export declare function __setNodePtyForTesting(stub: NodePtyModule | null): void;
+/**
+ * Thrown when something tries to write to a pty whose process has already exited.
+ *
+ * This has a dedicated type because the two failure modes read identically at the call site
+ * and must not: "never spawned" is a programming error, while "already exited" is a normal
+ * runtime event that the layer above has to react to by failing the turn. Before this class
+ * existed, `doWrite` happily called `_pty.write()` on a dead pty, node-pty swallowed it, and
+ * `waitForEcho()`'s fixed timer reported success - so paseo typed prompts into a corpse for
+ * fourteen retries and then told the user "the session itself is still running".
+ */
+export declare class PtyExitedError extends Error {
+    readonly code = "PTY_EXITED";
+    /** How the process died, so a caller can report it without a second lookup. */
+    readonly exitCode: number | null;
+    readonly exitSignal: NodeJS.Signals | null;
+    constructor(op: string, exitCode?: number | null, exitSignal?: NodeJS.Signals | null);
+}
 export declare class PtyTransport implements AgentTransport {
     private _pty;
     private _cwd;
@@ -35,11 +52,26 @@ export declare class PtyTransport implements AgentTransport {
     private _rows;
     private _killed;
     private _exited;
+    private _exitInfo;
+    private exitHandlers;
     private injectChain;
     private hookHandlers;
     private hookBuffer;
     private bridgeClose;
     private systemPromptFilePath;
+    /**
+     * Has the child process exited?
+     *
+     * Public because guarding the write paths fixes the symptom but leaves the question
+     * unanswerable: `_exited` was private, so no caller could ask a transport whether its
+     * child was alive without provoking an error. `AgentTransport` now declares it.
+     */
+    get exited(): boolean;
+    /** Exit status once the child is gone, else null. */
+    get exitInfo(): {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | null;
     /**
      * Bridge-side / test entry point — push a hook event into this transport's
      * stream. If no `onHookEvent` handler is registered yet, the event is