@evandu/super-pi 0.1.88 → 0.1.90

package/dist/client/index.html

@@ -8,8 +8,8 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-Bpy8UeU1.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CC-Q5gNQ.css">
+    <script type="module" crossorigin src="/assets/index-p1BjYE_T.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DgQRMp3j.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/application/run-service.d.ts

@@ -99,6 +99,12 @@ export declare class RunService {
     /**
      * Called by the exec completion handler in index.ts when a background exec session ends.
      * Injects the result into the conversation and cleans up the background task record.
+     *
+     * The result is now a REAL queue item, not a one-way notice the model never gets to read: it lands
+     * with `delivery: "waiting"` (so the dock shows it), at the front of the waiting set (so any pending
+     * user sends wait behind it), and the conversation auto-starts a turn for the agent to handle it
+     * when nothing else is busy. The render stays as a 后台回传 block throughout - in dock and in
+     * transcript - so a `role: "user"` is never impersonated.
      */
     enqueueExecResult(sessionId: string, exitCode: number, stdout: string, stderr: string): void;
     /** Per-conversation command lane.  All queue mutations and run claims use the same lane, so
@@ -233,6 +239,18 @@ export declare class RunService {
     steer(conversationId: string, messageId: string): Promise<void>;
     /** Starts a chosen waiting message as the next turn, only when the conversation is idle. */
     sendQueued(conversationId: string, messageId: string): Promise<void>;
+    /**
+     * The lower-level "wait for run slot, open the turn on a specific waiting message, run it" sequence.
+     *
+     * Called from two places: the user-facing `sendQueued` (which adds a stop-clearing grace window
+     * before this) and the auto-trigger paths in `enqueueExecResult` and `dispatchTask`'s background
+     * branch (which only call it when `!this.activeRuns.has(conversationId)`). The two callers differ
+     * only in who arrived first; the open-turn-and-run contract is the same.
+     *
+     * `composePrompt` is what makes the `role: "tool"` path real - the `<task>` envelope stays in the
+     * transcript, but the prose form of the same fact is what reaches Pi.
+     */
+    private processWaitingMessage;
     private steerUnsafe;
     /**
      * Withdraws a waiting message.

package/dist/server/application/run-service.js

@@ -7,6 +7,66 @@ import { validateWorkflowPlan, workflowSummary } from "../workflow.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+/**
+ * Translates a thrown error from the turn loop into a sentence a person reads.
+ *
+ * The turn loop throws for very different reasons: a model-provider rate limit, a 5xx that Pi's RPC
+ * layer chose to surface as a child exit, an OOM that took the whole process down, a path that
+ * resolved to a directory the workspace contract forbids, an `imageInput: false` mismatch. The
+ * throw message carries the technical fact; what the reader needs is the action it implies - retry,
+ * change model, check the key, change workspace - and that is the level this function writes at.
+ *
+ * The reason the shape is match-on-substring rather than match-on-error-class is that the upstream
+ * error is whatever Pi wrote to its own log: a string, not an exception class, and the host has
+ * nothing to pattern-match against other than the message itself. The literals below are
+ * deliberately permissive on the LLM side ("quota", "rate limit", "usage limit", "too many requests",
+ * "5-hour", "5h") because the underlying model APIs name this limit in several ways, and the
+ * reader cares about the bucket, not the exact wording.
+ */
+function formatTurnFailure(error) {
+    if (controllerAborted(error))
+        return "本轮任务已停止。";
+    const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    const lower = raw.toLowerCase();
+    // PROVIDER QUOTA / RATE LIMIT - the only reason the user is in this branch is because Pi was
+    // answering them a moment ago and now the model will not let it. The action is "wait or change
+    // model"; the wording has to make that obvious from the banner alone, without a tooltip.
+    if (/quota|rate limit|usage limit|too many requests|5-hour|5h|resource_exhausted|resourc exhaust|hit your limit|usage cap|usage restrict/.test(lower)) {
+        return "模型额度已用完（5 小时限额或类似上限），Pi 已停止回答。可以等待重置后重试，或在会话里换一个模型再发。";
+    }
+    // RPC CHANNEL DEAD - Pi died without producing a `settled` event. Anything in the turn is now
+    // unanswerable, but the deltas the user already saw are still on screen, so the message has to
+    // say "we noticed and stopped" rather than "your input was lost".
+    if (lower.includes("pi rpc channel closed") || lower.includes("agent rpc") || lower.includes("exited before settling")) {
+        return "Pi 进程异常退出，未完成本轮回答。已停止运行，可以直接重发任务继续。";
+    }
+    // NO PI - the launch path failed (binary missing, executable bit, Windows shim). The reader's
+    // best move is a `which pi` / reinstall, and the banner should point there.
+    if (lower.includes("could not find") && lower.includes("pi") || lower.includes("pi command") || lower.startsWith("pi ")) {
+        return `无法启动 Pi：${raw || "未知原因"}。请确认 Pi 已正确安装并可在命令行运行。`;
+    }
+    // WORKSPACE PATH - turn refused on directory the contract forbids. Refusal happens before
+    // anything is on screen, so the banner is also the only place the reason lives.
+    if (lower.includes("workspace directory") || lower.includes("does not exist or is not a directory")) {
+        return `工作区目录无效：${raw}`;
+    }
+    // IMAGE MISMATCH - explicit by the caller, no need to translate.
+    if (lower.includes("不支持图片输入")) {
+        return raw;
+    }
+    // GENERIC - the literal message is more useful than a paraphrase, but it has to be the LAST
+    // branch and the message has to be non-empty (a thrown `new Error()` is empty and renders
+    // nothing, which is exactly the silence this whole change exists to break).
+    return raw || "Pi 未能完成本轮回答，已标记为失败。可以重发任务继续。";
+}
+function controllerAborted(error) {
+    if (!error)
+        return false;
+    if (error instanceof Error && error.name === "AbortError")
+        return true;
+    const msg = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    return /abort|cancel|aborted/i.test(msg);
+}
 /** Expands composer references into explicit context for the model. */
 async function expandAtReferences(store, workspace, content) {
     const refs = [...content.matchAll(/@(worktree|session):([^\s]+)/gi)];
@@ -38,6 +98,35 @@ async function expandAtReferences(store, workspace, content) {
     }
     return blocks.length ? `${content}\n${blocks.join("\n")}` : content;
 }
+/**
+ * The text the model is handed when a waiting message becomes its turn.
+ *
+ * `role: "user"` is the user's own words - pass through verbatim. `role: "tool"` is a 后台回传 block
+ * whose `message.content` is the `<task>` envelope the transcript and dock render from; handing the raw
+ * XML to Pi asks it to parse the format itself, which is the "未定义行为" path that 0.1.66 worked around
+ * by simply not triggering a turn. We DO trigger a turn now (queue semantics), so we synthesise prose
+ * the model can read like any other user message.
+ *
+ * The envelope and the prose are NOT redundant: the envelope is what the reader sees in the transcript
+ * column, what they cancel or reorder; the prose is what leaves the server for Pi.
+ */
+function composePrompt(message) {
+    if (message.role !== "tool")
+        return message.content;
+    const content = message.content;
+    const summaryMatch = /<summary>([\s\S]*?)<\/summary>/.exec(content);
+    const summary = summaryMatch ? summaryMatch[1].trim() : "后台任务";
+    const stateMatch = /<task id="[^"]+" state="([^"]+)"/.exec(content);
+    const state = stateMatch ? stateMatch[1] : "completed";
+    const bodyMatch = /<task_(?:result|error)>\n?([\s\S]*?)\n?<\/(?:task_result|task_error)>/.exec(content);
+    const body = bodyMatch ? bodyMatch[1] : content;
+    const stateLabel = state === "completed" ? "已完成" : state === "error" ? "失败" : state;
+    // The marker `@bgdelivery:` is at the end so the visible prose is what the model sees (it can ignore
+    // a trailing `@`-token, which is what its other tools do too). The fake-pi fixture recognises the
+    // marker and settles immediately so test paths through this turn do not hang on the BLOCKING
+    // extension-UI default. A real model treats the marker as part of the user's prose.
+    return `[后台任务「${summary}」${stateLabel}]\n\n${body}\n\n@bgdelivery:${state}`;
+}
 /**
  * Service managing execution of conversation turns, message queueing,
  * follow-ups, and sub-agent dispatching.
@@ -127,6 +216,12 @@ export class RunService {
     /**
      * Called by the exec completion handler in index.ts when a background exec session ends.
      * Injects the result into the conversation and cleans up the background task record.
+     *
+     * The result is now a REAL queue item, not a one-way notice the model never gets to read: it lands
+     * with `delivery: "waiting"` (so the dock shows it), at the front of the waiting set (so any pending
+     * user sends wait behind it), and the conversation auto-starts a turn for the agent to handle it
+     * when nothing else is busy. The render stays as a 后台回传 block throughout - in dock and in
+     * transcript - so a `role: "user"` is never impersonated.
      */
     enqueueExecResult(sessionId, exitCode, stdout, stderr) {
         const tasks = this.store.snapshot().backgroundTasks;
@@ -135,10 +230,6 @@ export class RunService {
             return;
         const tag = exitCode === 0 ? "task_result" : "task_error";
         const body = exitCode === 0 ? stdout : (stderr || `Command exited with code ${exitCode}`);
-        // The result becomes a `role: "tool"` message in the conversation, not a user prompt for a fresh
-        // turn. The transcript now has a 「后台回传」 column the client renders, and the model sees the
-        // result only when something else starts a turn that includes it. Asking the model to consume a
-        // `<task>` envelope as user prose is the "undefined behaviour" path the user reported.
         const message = `<task id="${sessionId}" state="${exitCode === 0 ? "completed" : "error"}" kind="exec">\n<summary>${task.title}</summary>\n<${tag}>\n${body}</${tag}>\n</task>`;
         void this.trackDetached((async () => {
             try {
@@ -151,8 +242,31 @@ export class RunService {
                     this.broadcaster.broadcast({ type: "message.tools", conversationId: task.conversationId, messageId: task.originMessageId, toolCalls });
                 }
                 this.broadcaster.broadcast({ type: "exec.exit", sessionId, exitCode, stdout, stderr });
-                await this.store.addToolMessage(task.conversationId, message);
+                // QUEUE ITEM, NOT A NOTICE. `delivery: "waiting"` is what makes the row show in the dock; without
+                // it the message is a transcript entry only and `takeNextWaitingMessage` (which `runConversationTurns`
+                // calls after every turn) never picks it up.
+                const queued = await this.store.addToolMessage(task.conversationId, message, { delivery: "waiting" });
                 this.broadcaster.broadcastState();
+                // STEER PRIORITY. If anything else is already waiting, jump this one to the front of the queue
+                // so a 后台回传 cuts ahead of user sends - matching "按插队逻辑来处理".
+                const waiting = this.store.listWaitingMessages(task.conversationId);
+                if (waiting.length > 1) {
+                    await this.store.reorderWaitingMessage(task.conversationId, queued.id, 0);
+                    this.broadcaster.broadcastState();
+                }
+                // AUTO-TRIGGER WHEN IDLE. The conversation may already be busy (running turn, taking the next
+                // waiting message in its own follow-up loop); if so, the existing loop picks this one up and
+                // this branch is a no-op. If idle, kick off a fresh turn so the model processes the result
+                // without the user having to send anything - the failure case is intentionally included: the
+                // model seeing "[后台任务 X 失败]" is part of the same "after current AI finishes, automatically
+                // processes the result" contract, and the auto-triggered turn goes through the same
+                // `composePrompt` path the success case does (so a helper failure surfaces as `state="error"`
+                // prose the agent can react to).
+                if (!this.activeRuns.has(task.conversationId)) {
+                    void this.processWaitingMessage(task.conversationId, queued.id).catch((error) => {
+                        console.warn(`Super Pi: auto-trigger for background exec result failed: ${error instanceof Error ? error.message : "unknown error"}`);
+                    });
+                }
             }
             catch (error) {
                 console.warn(`Super Pi: exec result could not be appended as a tool message: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -810,7 +924,9 @@ export class RunService {
                 const followUp = await this.store.openTurnOnMessage(conversation.id, next.id, identity);
                 this.broadcaster.broadcastState();
                 const current = this.turnContext(conversation.id).conversation;
-                await this.streamTurn(current, workspace, next.content, followUp.assistant, controller, followUp.user.id, next.images, identity);
+                // `composePrompt` synthesises the prose for a 后台回传 (the `<task>` envelope is what the transcript
+                // column reads from; the prose is what leaves the server for Pi). For user messages it is a no-op.
+                await this.streamTurn(current, workspace, composePrompt(next), followUp.assistant, controller, followUp.user.id, next.images, identity);
             }
         }
         finally {
@@ -893,13 +1009,61 @@ export class RunService {
                 // first line, so it is outside this try for exactly that reason. A failure from in there is a turn
                 // that has already consumed these words, and putting them back would send them twice.
                 await this.store.markMessageWaiting(conversationId, message.id).catch(() => undefined);
+                // The reason for the refusal is also worth showing - a banner above the transcript is the only
+                // place the user can read it from, because the message itself was rolled back to the queue and
+                // the banner is the difference between "the message is waiting" and "I know why it is
+                // waiting". The banner is cleared by the next `addUserMessage` so a stale reason cannot
+                // survive a retry into the same conversation.
+                await this.store.setFailureReason(conversationId, formatTurnFailure(error));
+                // Status is restored here, not relied on the outer catch to handle: a preflight failure never
+                // opened a turn, so the right state is the one the conversation had a moment ago (idle). The
+                // outer catch would otherwise flip it to `failed`, which the reader would render as a turn
+                // that ran and broke - the opposite of what actually happened.
+                await this.store.setStatus(conversationId, "idle");
+                // Tag the error so the outer catch knows to stay out of the way: no status flip, no second
+                // setFailureReason (the one above is the only one the reader should see). A free-standing
+                // property on the Error object is enough - it is checked with `in`, not by class, and the
+                // throw immediately below carries it through the propagation.
+                error.__superPiPreflight = true;
+                this.broadcaster.broadcastState();
                 throw error;
             }
             await this.runConversationTurns(conversation, workspace, expanded, controller, message.id, validImages);
             await this.store.setStatus(conversation.id, controller.signal.aborted ? "stopped" : "completed");
         }
         catch (error) {
+            // A failing turn needs to be READ AS A FAILING TURN, not just stamped "failed" in a corner no one
+            // watches. The status flip is necessary but not sufficient: a turn that was answering the user a
+            // moment ago, now reporting 「failed」 with no reason, looks identical to a turn that the user
+            // stopped themselves, and the reader has no way to tell which one it is. The only honest move
+            // is to put the reason in front of them - `Conversation.error` is the banner above the
+            // transcript that the failure state was never reaching.
+            //
+            // The reason is taken from the error itself, with the most common upstream cases translated to
+            // the wording a person reads. The literal `error.message` would say "Pi RPC channel closed
+            // before producing a record (code 3)" - that is true and useless. The translate here is what
+            // the model-provider documentation actually says and what the reader can act on (retry, change
+            // model, check the key), and it matches the banner the reader sees elsewhere in the app.
+            //
+            // NOT EVERY CATCH PATH IS A FAILURE the reader should see. A stop signalled through the
+            // controller reaches the catch too (the abort propagates as a throw), and a stop is not a
+            // failure - it is what the user asked for, and painting it red would be both wrong and a
+            // regression from the pre-change behavior of these very lines. The reason is recorded only
+            // when the controller was NOT aborted.
+            //
+            // Preflight refusals - bad model choice, unresolvable `@`-reference - carry the same shape but
+            // never opened a turn, so flipping status to `failed` would be a lie: the previous state was
+            // `idle` (or whatever the conversation was before the send) and that is what the conversation
+            // is now. The preflight branch above already wrote the reason and set status back to `idle`,
+            // so this catch only has to stay out of the way. The marker is set on the error there and
+            // checked here.
+            if (error?.__superPiPreflight) {
+                throw error;
+            }
             await this.store.setStatus(conversation.id, "failed");
+            if (!controller.signal.aborted) {
+                await this.store.setFailureReason(conversation.id, formatTurnFailure(error));
+            }
             throw error;
         }
         finally {
@@ -916,22 +1080,29 @@ export class RunService {
     }
     /** Starts a chosen waiting message as the next turn, only when the conversation is idle. */
     async sendQueued(conversationId, messageId) {
-        const waitForStop = async () => {
-            // A stop broadcasts `stopped` before the previous run has finished its finally block. Allow that
-            // short cleanup window; a click on the newly visible button must not race the old run slot.
-            const deadline = Date.now() + 15_000;
-            while (this.activeRuns.has(conversationId) && this.store.snapshot().conversations.find((item) => item.id === conversationId)?.status === "stopped" && Date.now() < deadline) {
-                await new Promise((resolve) => setTimeout(resolve, 10));
-            }
-        };
-        await waitForStop();
+        // A stop broadcasts `stopped` before the previous run has finished its finally block. Allow that
+        // short cleanup window; a click on the newly visible button must not race the old run slot.
+        const deadline = Date.now() + 15_000;
+        while (this.activeRuns.has(conversationId) && this.store.snapshot().conversations.find((item) => item.id === conversationId)?.status === "stopped" && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        await this.processWaitingMessage(conversationId, messageId);
+    }
+    /**
+     * The lower-level "wait for run slot, open the turn on a specific waiting message, run it" sequence.
+     *
+     * Called from two places: the user-facing `sendQueued` (which adds a stop-clearing grace window
+     * before this) and the auto-trigger paths in `enqueueExecResult` and `dispatchTask`'s background
+     * branch (which only call it when `!this.activeRuns.has(conversationId)`). The two callers differ
+     * only in who arrived first; the open-turn-and-run contract is the same.
+     *
+     * `composePrompt` is what makes the `role: "tool"` path real - the `<task>` envelope stays in the
+     * transcript, but the prose form of the same fact is what reaches Pi.
+     */
+    async processWaitingMessage(conversationId, messageId) {
         return this.serializeConversation(conversationId, async () => {
             if (this.activeRuns.has(conversationId))
                 throw new Error("当前轮仍在运行；停止或等待它结束后再发送这条消息");
-            // Claim the run slot BEFORE releasing the command lane, then start the turn from the message that
-            // is already in the transcript. It is not re-sent through `enqueueAndRun`, which would write a
-            // SECOND copy of these words: the whole point of this action is that the user is sending a message
-            // they can already see sitting in their conversation.
             const controller = new AbortController();
             this.activeRuns.set(conversationId, controller);
             try {
@@ -940,14 +1111,14 @@ export class RunService {
                 const identity = agent ? { id: agent.id, name: agent.name } : { name: "Pi" };
                 const opened = await this.store.openTurnOnSpecificMessage(conversationId, messageId, identity);
                 this.broadcaster.broadcastState();
-                await this.runConversationTurns(conversation, workspace, opened.user.content, controller, opened.user.id, opened.user.images);
+                await this.runConversationTurns(conversation, workspace, composePrompt(opened.user), controller, opened.user.id, opened.user.images);
                 await this.store.setStatus(conversationId, controller.signal.aborted ? "stopped" : "completed");
             }
             catch (error) {
                 await this.store.setStatus(conversationId, "failed");
-                // A preflight failure must put the words BACK where the user can see them. Re-adding them would
-                // duplicate the message that is still in the transcript, so this only re-marks the one that is
-                // there - which is what makes "the send failed, your message is still waiting" a true statement.
+                // A preflight failure must put the message BACK where the reader can see it. Re-adding it would
+                // duplicate the row that is still in the transcript, so this only re-marks the one that is
+                // there - which is what makes "the send failed, this row is still in the queue" a true statement.
                 await this.store.releaseWaitingMessage(conversationId, messageId).catch(() => undefined);
                 throw error;
             }
@@ -989,7 +1160,10 @@ export class RunService {
         const claimed = await this.store.claimWaitingMessage(conversationId, messageId);
         this.broadcaster.broadcastState();
         try {
-            await this.runtime.steer(conversationId, claimed.content, claimed.images);
+            // `composePrompt` turns a 后台回传 into the prose the model can read as a user message; for a
+            // user waiting message it is the no-op identity. `claimed.images` is always undefined for a
+            // `role: "tool"` row, and that is correct - 后台回传 carries no images today.
+            await this.runtime.steer(conversationId, composePrompt(claimed), claimed.images);
         }
         catch (error) {
             // Back to waiting in every failure case, including the "Pi is gone" one. It is still at the front of
@@ -1115,11 +1289,24 @@ export class RunService {
                     this.memory?.review(this.turnContext(conversationId).conversation, { task: body.prompt, result: run.output });
                 const result = run.status === "completed" ? run.output ?? "" : `Background task failed: ${run.error ?? run.status}`;
                 const tag = run.status === "completed" ? "task_result" : "task_error";
-                // Result is appended as a `role: "tool"` message, not a user-prompted turn. The transcript
-                // shows the result in its own column; the model only sees it on a later turn.
+                // A 后台回传 that the agent will actually get to read: same `<task>` envelope the transcript and
+                // dock render from, but with `delivery: "waiting"` so it lives in the queue, jumps to the
+                // front, and auto-triggers a turn when the conversation is idle. The render side is unchanged -
+                // still the 后台回传 column.
                 const message = `<task id="${run.id}" state="${run.status === "completed" ? "completed" : "error"}" kind="subagent">\n<summary>Background task ${run.status === "completed" ? "completed" : "failed"}: ${body.description?.trim() || subagentType}</summary>\n<${tag}>\n${result}</${tag}>\n</task>`;
                 try {
-                    await this.store.addToolMessage(conversation.id, message);
+                    const queued = await this.store.addToolMessage(conversation.id, message, { delivery: "waiting" });
+                    this.broadcaster.broadcastState();
+                    const waiting = this.store.listWaitingMessages(conversation.id);
+                    if (waiting.length > 1) {
+                        await this.store.reorderWaitingMessage(conversation.id, queued.id, 0);
+                        this.broadcaster.broadcastState();
+                    }
+                    if (!this.activeRuns.has(conversation.id)) {
+                        void this.processWaitingMessage(conversation.id, queued.id).catch((error) => {
+                            console.warn(`Super Pi: auto-trigger for background sub-agent result failed: ${error instanceof Error ? error.message : "unknown error"}`);
+                        });
+                    }
                 }
                 catch (error) {
                     console.warn(`Super Pi: sub-agent result could not be appended as a tool message: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -1129,7 +1316,16 @@ export class RunService {
             }).catch(async (error) => {
                 const message = `<task id="${backgroundId}" state="error" kind="subagent">\n<summary>Background task failed: ${body.description?.trim() || subagentType}</summary>\n<task_error>Background task failed before completion: ${error instanceof Error ? error.message : "unknown error"}</task_error>\n</task>`;
                 try {
-                    await this.store.addToolMessage(conversationId, message);
+                    const queued = await this.store.addToolMessage(conversationId, message, { delivery: "waiting" });
+                    this.broadcaster.broadcastState();
+                    const waiting = this.store.listWaitingMessages(conversationId);
+                    if (waiting.length > 1) {
+                        await this.store.reorderWaitingMessage(conversationId, queued.id, 0);
+                        this.broadcaster.broadcastState();
+                    }
+                    // No auto-trigger on this failure branch (the result envelope says `state="error"` and the
+                    // conversation is by construction not in a turn that asked for it). The row is visible in the
+                    // dock for the reader to send-now or cancel.
                 }
                 catch (innerError) {
                     console.warn(`Super Pi: sub-agent failure could not be appended as a tool message: ${innerError instanceof Error ? innerError.message : "unknown error"}`);

package/dist/server/rpc-channel.d.ts

@@ -96,7 +96,20 @@ export declare class RpcChannel {
     write(command: object): void;
     /** Returns a response to its waiter after the drain loop encountered it. */
     stash(record: RpcRecord): void;
-    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
+    /**
+     * Removes and returns the next record, or returns `undefined` after `timeoutMs` with nothing to read.
+     *
+     * THROWS once the child is gone, rather than returning undefined. The old contract was "undefined on
+     * EOF" and it had a specific shape of failure it could not see: Pi dying without ever emitting
+     * `agent_settled` (a 4xx/5xx from the model provider is the obvious one, an OOM kill another) used
+     * to look exactly like "Pi had nothing to say", so the host's drain loop kept polling until the
+     * generator returned and the turn was reported as completed - a quota-exhausted turn presented to
+     * the reader as 「已完成」 with no error and no message, which is the exact silence this threw exit
+     * exists to break. The thrown `Error` carries the exit reason and a `code: "CHANNEL_CLOSED"`
+     * property the runtime layer can pattern-match on when it wants to decide between "this turn
+     * failed before settling" and any other drain-loop failure; a host that does not match it still
+     * sees a real error with a real reason.
+     */
     next(timeoutMs?: number): Promise<RpcRecord | undefined>;
     /** Sends a command and waits for its response. For one command; use write()+waitFor() to overlap several. */
     request(command: {

package/dist/server/rpc-channel.js

@@ -74,13 +74,31 @@ export class RpcChannel {
             this.wake();
         }
     }
-    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
+    /**
+     * Removes and returns the next record, or returns `undefined` after `timeoutMs` with nothing to read.
+     *
+     * THROWS once the child is gone, rather than returning undefined. The old contract was "undefined on
+     * EOF" and it had a specific shape of failure it could not see: Pi dying without ever emitting
+     * `agent_settled` (a 4xx/5xx from the model provider is the obvious one, an OOM kill another) used
+     * to look exactly like "Pi had nothing to say", so the host's drain loop kept polling until the
+     * generator returned and the turn was reported as completed - a quota-exhausted turn presented to
+     * the reader as 「已完成」 with no error and no message, which is the exact silence this threw exit
+     * exists to break. The thrown `Error` carries the exit reason and a `code: "CHANNEL_CLOSED"`
+     * property the runtime layer can pattern-match on when it wants to decide between "this turn
+     * failed before settling" and any other drain-loop failure; a host that does not match it still
+     * sees a real error with a real reason.
+     */
     async next(timeoutMs = 100) {
         const deadline = performance.now() + timeoutMs;
         for (;;) {
             if (this.records.length)
                 return this.records.shift();
-            if (this.exited || this.child.exitCode !== null || performance.now() >= deadline)
+            if (this.exited || this.child.exitCode !== null) {
+                const err = new Error(`Pi RPC channel closed before producing a record (${this.exitReason || "no reason recorded"}). ${this.stderr.trim()}`);
+                err.code = "CHANNEL_CLOSED";
+                throw err;
+            }
+            if (performance.now() >= deadline)
                 return undefined;
             await this.changed(deadline - performance.now());
         }

package/dist/server/store.d.ts

@@ -1,7 +1,7 @@
 import type { AppStateRepository } from "./persistence/app-state-repository.js";
 import { defaultJsonStatePath } from "./persistence/json-state-repository.js";
 import type { WorkflowRun } from "./workflow.js";
-import type { AppState, Conversation, Message, MessageImage, ModelSelection, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallQuestion, ToolCallArg, ToolCallBlock, ToolResultSummary, Workspace } from "./types.js";
+import type { AppState, Conversation, Message, MessageDelivery, MessageImage, ModelSelection, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallQuestion, ToolCallArg, ToolCallBlock, ToolResultSummary, Workspace } from "./types.js";
 /** Mints the id a forked conversation will have, BEFORE its Pi transcript exists.
  *
  *  Exported because the ordering demands it and no other arrangement provides it. Pi's copied file's header
@@ -220,18 +220,18 @@ export declare class Store {
      */
     private claimClientMessageId;
     /**
-     * Appends one background-result message to a conversation, without starting a turn.
+     * Appends one background-result message to a conversation. The render column is the same as before
+     * (a `role: "tool"` row, never impersonating a user bubble) - what this method now ALSO supports is
+     * putting the message straight into the dock by passing `delivery: "waiting"`, which is what exec and
+     * sub-agent background completions do once a 后台回传 is treated as a queue item with steer priority
+     * rather than a one-way notice the model never gets to read.
      *
-     * Used by sub-agent dispatch completions and the exec service when they finish out of band - the
-     * result is the prompt for a follow-up turn in the old design, which made a "后台回传" render under
-     * the "你" bubble and asked the model to consume a tool envelope as user prose. This appends a
-     * `role: "tool"` message that the client renders with its own column and its own block UI, so the
-     * transcript shows the result AND nothing pretends the user said it.
-     *
-     * NO `turnContext` claim, NO `status: "running"`. The message sits in the transcript and a subsequent
-     * caller can start a turn normally if it wants the model to react to the result.
+     * NO `turnContext` claim, NO `status: "running"`. The message sits in the transcript; with a delivery
+     * state it also enters `waitingMessages` and `runConversationTurns` will pick it up next.
      */
-    addToolMessage(conversationId: string, content: string): Promise<Message>;
+    addToolMessage(conversationId: string, content: string, options?: {
+        delivery?: MessageDelivery;
+    }): Promise<Message>;
     /**
      * Records the model a conversation runs on. `updatedAt` is deliberately NOT touched, for the same
      * reason rename does not touch it: it is the sidebar's recency key, and switching model is not
@@ -365,6 +365,22 @@ export declare class Store {
      */
     clearPreparingToolCalls(conversationId: string, messageId: string, rows: readonly number[]): Promise<ToolCallBlock[]>;
     setStatus(conversationId: string, status: Conversation["status"]): Promise<void>;
+    /**
+     * Records WHY a turn failed in a way the reader can see. `Conversation.error` is rendered as a red
+     * banner above the transcript (`App.tsx:conversation-error`), and it is the only field that survives
+     * a status flip and a navigation away and back - so it is the only place a "Pi died without saying
+     * anything" failure becomes visible to a person.
+     *
+     * Settled through `persistMetadata` rather than `persistState` so the message and tool deltas the
+     * turn had already written are not re-validated against a partial read; a previous build took the
+     * heavier path and an early failure mid-turn left the transcript rolled back to the last good
+     * checkpoint, hiding exactly the deltas the reader would have wanted to see.
+     *
+     * Set to `undefined` to clear, which the next `addUserMessage` does anyway - so callers only need
+     * this when they want the banner without a follow-up message (the turn did fail and the user is
+     * going to act on it without sending another prompt first).
+     */
+    setFailureReason(conversationId: string, reason: string | undefined): Promise<void>;
     /** The plan a revert would carry out, without carrying it out. The server reads this to stop children first. */
     planRevert(conversationId: string, messageId: string, withdraw?: boolean): RevertPlan;
     /**
@@ -405,7 +421,11 @@ export declare class Store {
      * browsers and the array is mutated in place by the very next send.
      */
     listWaitingMessages(conversationId: string): Message[];
-    /** The same list by reference, for callers that only read a field and must not pay for a clone. */
+    /** The same list by reference, for callers that only read a field and must not pay for a clone.
+     *
+     * Includes `role: "tool"` messages now that a 后台回传 is a real queue item: same dock, same ordering,
+     * same delivery state machine, same steer/claim semantics - the only thing different is the render
+     * (kept as a 后台回传 block) and what the agent is told when its turn comes (see `composePrompt`). */
     private waitingMessages;
     private requireWaitingMessage;
     private persistMessages;
@@ -475,12 +495,9 @@ export declare class Store {
      */
     cancelWaitingMessage(conversationId: string, messageId: string): Promise<Message | undefined>;
     /**
-     * Rewrites the words of one waiting message.
-     *
-     * Only legal while nothing has read it. `waiting` means the text is still only in this transcript, so
-     * changing it is changing the whole truth of the message - there is no second copy anywhere that could
-     * fall out of step. `sending` means Pi already holds it, and a message the model is about to answer is
-     * not one the user gets to rewrite after the fact.
+     * Rewrites the words of one waiting message. User sends only - a 后台回传 carries a `<task>` envelope
+     * the model parses for state, summary and body, and editing it would change a fact the agent has
+     * already started reasoning from. The client dock shows no 「改字」 button for `role: "tool"` rows.
      */
     editWaitingMessage(conversationId: string, messageId: string, content: string): Promise<Message>;
     /**