@evandu/super-pi 0.0.0-stage → 0.1.1

package/dist/server/runtime.js

@@ -0,0 +1,1470 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { agentSpawnArgs, readAgents } from "./agents.js";
+import { resolvePiCommand, shellQuote } from "./pi-command.js";
+import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, rosterPayload, } from "./task-tool.js";
+import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
+import { loadConversationImages } from "./upload.js";
+import { describeToolCall, describeToolCallArgs } from "./tool-calls.js";
+/** Deterministic offline runtime used by tests and local UI development. */
+export class WelcomeRuntime {
+    async *answer({ prompt, signal }) {
+        const response = `\u5df2\u6536\u5230\uff1a${prompt}\n\nSuper Pi \u7684 Web \u57fa\u5ea7\u5df2\u7ecf\u8fd0\u884c\u3002\u5f53\u524d\u4f1a\u8bdd\u3001\u6d41\u5f0f\u8f93\u51fa\u3001\u505c\u6b62\u4efb\u52a1\u4e0e\u672c\u5730\u6301\u4e45\u5316\u5747\u53ef\u7528\u3002\n\nPi \u8fd0\u884c\u65f6\u9002\u914d\u5668\u5df2\u51c6\u5907\u5c31\u7eea\uff1a\u914d\u7f6e\u597d Pi \u7684\u6a21\u578b\u8ba4\u8bc1\u540e\uff0cWeb \u754c\u9762\u4f1a\u901a\u8fc7 JSONL RPC \u9a71\u52a8\u771f\u5b9e agent\u3002`;
+        for (const chunk of response.match(/.{1,16}/gsu) ?? []) {
+            if (signal.aborted)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            yield chunk;
+        }
+    }
+    async stop() { }
+    /**
+     * No Pi, so no models. `source` is what turns the picker into a visibly disabled control instead
+     * of an empty list, which would read as "you have no models".
+     */
+    async catalog() {
+        return { source: "unavailable", models: [], levels: [], fetchedAt: new Date().toISOString(), error: "Welcome runtime has no Pi session to ask" };
+    }
+}
+/**
+ * Reads Pi's `queue_update` payload, or returns undefined when the record is not one.
+ *
+ * Filters to real strings rather than passing the arrays through, so a malformed snapshot cannot put
+ * objects into the browser's DOM or into a log line that is supposed to be readable - the same rule
+ * `textList` already applies to Extension UI options. Returns undefined for the wrong `type` too, so the
+ * drain loop can keep using it as the recogniser.
+ */
+export function describePiQueue(record) {
+    if (record.type !== "queue_update")
+        return undefined;
+    return { steering: textList(record.steering) ?? [], followUp: textList(record.followUp) ?? [] };
+}
+const NOTIFY_TYPES = new Set(["info", "warning", "error"]);
+const PLACEMENTS = new Set(["aboveEditor", "belowEditor"]);
+const text = (value) => (typeof value === "string" ? value : undefined);
+/** Keeps only real strings, so a malformed `options` cannot put objects into the browser's DOM. */
+const textList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : undefined;
+/**
+ * Normalizes one `extension_ui_request` record, or returns undefined when the record is not something
+ * Pi's union can produce (wrong `type`, missing `id`, or a method outside the nine). Exports so the
+ * mapping can be tested without spawning Pi.
+ */
+export function describeExtensionUiRequest(record) {
+    if (record.type !== "extension_ui_request" || typeof record.id !== "string" || record.id === "")
+        return undefined;
+    if (typeof record.method !== "string" || !EXTENSION_UI_METHODS.includes(record.method))
+        return undefined;
+    const method = record.method;
+    const request = { requestId: record.id, method, blocking: BLOCKING_UI_METHODS.has(method), title: text(record.title) ?? "" };
+    switch (method) {
+        case "select":
+            request.options = textList(record.options) ?? [];
+            break;
+        case "confirm":
+            request.message = text(record.message) ?? "";
+            break;
+        case "input":
+            request.placeholder = text(record.placeholder);
+            break;
+        case "editor":
+            request.prefill = text(record.prefill);
+            break;
+        // notify reuses `message`; there is no separate notifyTitle in Pi's union.
+        case "notify":
+            request.message = text(record.message) ?? "";
+            request.notifyType = (NOTIFY_TYPES.has(record.notifyType ?? "") ? record.notifyType : "info");
+            break;
+        case "setStatus":
+            request.statusKey = text(record.statusKey) ?? "";
+            request.statusText = text(record.statusText);
+            break;
+        case "setWidget":
+            request.widgetKey = text(record.widgetKey) ?? "";
+            request.widgetLines = textList(record.widgetLines);
+            request.widgetPlacement = (PLACEMENTS.has(record.widgetPlacement ?? "") ? record.widgetPlacement : undefined);
+            break;
+        case "setTitle": break;
+        case "set_editor_text":
+            request.text = text(record.text) ?? "";
+            break;
+    }
+    // Only Pi's blocking methods carry a deadline, and `editor` never does - which is exactly why an
+    // unanswered editor is allowed to wait indefinitely rather than being expired by this host.
+    if (request.blocking && typeof record.timeout === "number" && Number.isFinite(record.timeout) && record.timeout > 0)
+        request.timeoutMs = record.timeout;
+    return request;
+}
+/**
+ * Maps a human's answer onto the one response shape Pi's method accepts. The method decides the shape
+ * rather than the answer, so a client that sends `confirmed` for a `select` (or `value` for a `confirm`)
+ * cannot produce a response Pi would read as a missing field.
+ */
+export function buildExtensionUiResponse(request, answer) {
+    if (answer.cancelled)
+        return { type: "extension_ui_response", id: request.requestId, cancelled: true };
+    if (request.method === "confirm")
+        return { type: "extension_ui_response", id: request.requestId, confirmed: answer.confirmed === true };
+    return { type: "extension_ui_response", id: request.requestId, value: answer.value ?? "" };
+}
+/** One Pi child, its stdout reader, and the single writer to its stdin. */
+export class RpcChannel {
+    child;
+    records = [];
+    /**
+     * Responses a drain loop pulled off the queue before the waiter that wanted them looked.
+     *
+     * THE RACE THIS EXISTS TO SETTLE, and it is not a rare one - it cost this file an intermittent test
+     * failure. One queue serves two kinds of reader: `waitFor`, which is after a specific command's answer by
+     * id, and `next`, which is a turn's drain loop reading whatever arrives first. The loop does not know
+     * which ids someone is waiting for, so it used to take the first record of any kind - including the answer
+     * to a `get_entries` written moments earlier - and the waiter then waited out its whole timeout for a
+     * response that had already been consumed and discarded.
+     *
+     * So the drain loop no longer decides an unmatched response is garbage: it HANDS IT BACK here, and the
+     * waiter finds it whether it got there first or second. Nothing is dropped, and nothing is waited for
+     * twice.
+     */
+    stashed = new Map();
+    buffer = "";
+    /** stderr is kept only to explain an early exit; a well-behaved Pi writes nothing here. */
+    stderr = "";
+    constructor(child) {
+        this.child = child;
+        child.stderr.on("data", (chunk) => { this.stderr += chunk.toString(); });
+        child.stdout.on("data", (chunk) => {
+            this.buffer += chunk.toString("utf8");
+            let newline;
+            while ((newline = this.buffer.indexOf("\n")) >= 0) {
+                const line = this.buffer.slice(0, newline).replace(/\r$/, "");
+                this.buffer = this.buffer.slice(newline + 1);
+                if (!line)
+                    continue;
+                try {
+                    this.records.push(JSON.parse(line));
+                }
+                catch { /* Pi stdout must be JSONL */ }
+            }
+        });
+    }
+    get exitCode() { return this.child.exitCode; }
+    /** Writes one JSONL command. Throws rather than silently dropping: a command Pi never sees is a lie the caller would act on. */
+    write(command) {
+        if (this.child.killed || this.child.stdin.destroyed)
+            throw new Error(`Pi RPC stdin is closed, so ${JSON.stringify(command)} was not sent`);
+        this.child.stdin.write(`${JSON.stringify(command)}\n`);
+    }
+    /**
+     * Returns one record to whoever is waiting for it, after a drain loop read it.
+     *
+     * Called for every response the loop does not consume itself. See `RpcChannel`'s note on `stashed` for why
+     * this is not the same as discarding it - discarding it silently cost a turn its revert boundary.
+     */
+    stash(record) { if (record.type === "response" && typeof record.id === "string")
+        this.stashed.set(record.id, record); }
+    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
+    async next(timeoutMs = 100) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            if (this.records.length)
+                return this.records.shift();
+            if (Date.now() >= deadline)
+                return undefined;
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    /** Sends a command and waits for its response. For one command; use write()+waitFor() to overlap several. */
+    async request(command, timeoutMs) {
+        this.write(command);
+        return this.waitFor(command.id, timeoutMs, command.type);
+    }
+    /**
+     * Returns one response by id, from the queue if it is still there and from the stash if a drain loop got
+     * there first. Removing it from the stash is what keeps a single answer from being handed out twice.
+     */
+    take(id) {
+        const index = this.records.findIndex((record) => record.type === "response" && record.id === id);
+        if (index >= 0)
+            return this.records.splice(index, 1)[0];
+        const stashed = this.stashed.get(id);
+        if (!stashed)
+            return undefined;
+        this.stashed.delete(id);
+        return stashed;
+    }
+    /**
+     * Waits for the response to one command id. Every record that is not that response stays QUEUED in
+     * order, so a caller can have three requests in flight and still read all three answers: whoever
+     * asks first takes its own record and leaves the rest for the drain loop.
+     */
+    async waitFor(id, timeoutMs, what = id) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const record = this.take(id);
+            if (record)
+                return record;
+            // A dead child will never answer, so waiting out the full deadline would only delay the failure.
+            if (this.child.exitCode !== null)
+                throw new Error(`Pi RPC exited (code ${this.child.exitCode}) while waiting for ${what}. ${this.stderr.trim()}`);
+            if (Date.now() >= deadline)
+                throw new Error(`Pi did not answer ${what} within ${timeoutMs}ms`);
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+}
+/**
+ * The commands a freshly spawned Pi must be told before it runs a conversation's turn.
+ *
+ * This is the whole mechanism behind the picker: PiRpcRuntime spawns one Pi process per turn and
+ * kills it afterwards, so there is no long-lived session to poke. Writing these commands onto that
+ * process's stdin before the prompt is what makes a selection REAL - Pi answers `set_model` with
+ * the model it switched to, and the prompt that follows runs on it.
+ *
+ * Model BEFORE level, and the order is load-bearing: `AgentSession.setModel` re-derives the thinking
+ * level for the new model (agent-session.ts:2493), so applying the level first would have Pi undo it
+ * on the very next line.
+ *
+ * A conversation with neither selection produces NO commands, which is what keeps every
+ * pre-picker conversation on Pi's own defaults.
+ */
+export function sessionCommands(conversation) {
+    const commands = [];
+    const model = conversation.model;
+    if (model?.provider && model.modelId)
+        commands.push({ id: "set_model", type: "set_model", ...{ provider: model.provider, modelId: model.modelId } });
+    if (conversation.thinkingLevel)
+        commands.push({ id: "set_thinking_level", type: "set_thinking_level", ...{ level: conversation.thinkingLevel } });
+    return commands;
+}
+/**
+ * Kills a whole process tree on Windows. Pi is launched through a .cmd shim (spawn with shell:true),
+ * so the spawned process is cmd.exe and the real Pi is its grandchild: killing the shim alone leaks
+ * Pi, which keeps holding its working directory and the RPC pipes. No-op on a pid that already died.
+ *
+ * Exported rather than reimplemented per spawner: a second copy is how one of the two ends up killing
+ * only the shim, which is the exact failure this function exists to prevent.
+ */
+export function killTree(pid) {
+    return new Promise((resolve) => {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+        killer.once("exit", () => resolve());
+        killer.once("error", () => resolve());
+    });
+}
+/**
+ * Cuts a Pi session file down to the header plus everything up to and including `boundaryEntryId`.
+ *
+ * ============================ WHAT THIS DESTROYS ============================
+ * **Every entry written after the boundary is gone from disk, permanently, and there is no way to
+ * reconstruct it from this file.** That includes not only the messages a person can see but also Pi's
+ * `tool_call` records, `compaction` summaries, `model_change` and `thinking_level_change` markers, usage
+ * accounting, and anything a future Pi version adds. This is the step the whole revert design is built
+ * around (research §4.2) and the step that cannot be undone by the application - Super Pi has no undo,
+ * and adding one was explicitly left out of scope.
+ *
+ * It does NOT touch the workspace. No file the agent read or wrote is read, written or reverted here.
+ * =============================================================================
+ *
+ * WHY TRUNCATE RATHER THAN ASK PI. Pi's `SessionManager` is append-only by design
+ * (`session-manager.ts:1516-1519`: "Entries cannot be modified or deleted"), and its in-session rewind -
+ * `branch()`, `navigateTree()` - is IN-MEMORY ONLY (`:1573-1584`): `_buildIndex()` re-reads the whole
+ * file on every `open()` and sets the leaf to the last line unconditionally (`:1103-1122`). Super Pi
+ * spawns one Pi per turn and kills it afterwards, so a leaf pointer set in one turn is gone before the
+ * next one starts - a "call `branch()` once" solution would look correct for a turn and then silently
+ * forget (research §5 pitfall 2). Truncating the file is the only version of this that is a durable state
+ * change rather than per-turn bookkeeping that can be skipped exactly once.
+ *
+ * WHY THE FORMAT IS ASSUMED RATHER THAN GUESSED. The shape this relies on - line 0 is the one and only
+ * `type: "session"` header, every other line is one self-contained JSON entry, every entry's `parentId`
+ * already appears earlier in the file, no blank lines, and a trailing newline - was measured against
+ * real Pi by scripts/probe-revert-session-format.mjs, which also proves the `parentId` property that
+ * makes a prefix a VALID session rather than a fragment. That probe is the reason this function may
+ * index by line at all; every one of those claims is re-checked here before anything is written, so a
+ * Pi that changed the format fails loudly instead of producing a file Pi cannot open.
+ *
+ * WHY THE WRITE IS TEMP-THEN-RENAME. Pi appends with a bare `appendFileSync`
+ * (`session-manager.ts:1187`) and makes no atomicity guarantee of its own. Writing the truncated copy
+ * under a different name and renaming it over the original means a reader never observes a half-written
+ * file, and a failure before the rename leaves the original untouched.
+ *
+ * WHY A BACKUP IS KEPT. `.super-pi-revert-backup` is written next to the session file, deliberately not
+ * named `*.jsonl` so Pi's own discovery (`readdirSync` filtered on that suffix,
+ * `session-manager.ts:1881`) never lists it, and deliberately NOT surfaced anywhere as a feature:
+ * Super Pi has no undo and does not pretend to. It exists so that an irreversible, unrecoverable-by-code
+ * operation on a person's conversation history is at least recoverable by hand.
+ *
+ * EXPORTED so it can be tested against a fabricated session file in a temp directory, without Pi and
+ * without touching anybody's real transcript.
+ */
+export async function truncateSessionFile(path, boundaryEntryId, expectedSessionId) {
+    const raw = await readFile(path, "utf8");
+    // Split, then drop the empty segment a trailing newline leaves behind. Probe A measured that the file
+    // DOES end with a newline, so `split` yields one empty tail element; keeping it would append a blank
+    // line to the rewritten file and undo the property the probe just established.
+    const lines = raw.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    if (!lines.length)
+        throw new Error(`Pi 的会话文件是空的，拒绝回退：${path}`);
+    const parsed = lines.map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return undefined;
+        }
+    });
+    // Every claim probe A made, re-checked here because a Pi upgrade may invalidate any of them. Each
+    // failure names the shape that was actually found, because "revert failed" alone sends the reader
+    // looking for their own data instead of at the version mismatch that caused it.
+    // Checked BEFORE the JSON check, so the refusal names the actual defect: a blank line reads as "this
+    // file has a shape my line arithmetic cannot trust", which is what it is, and a bare "not valid JSON"
+    // would send the reader looking for a corrupted file instead.
+    const blank = lines.findIndex((line) => line.trim() === "");
+    if (blank >= 0)
+        throw new Error(`Pi 的会话文件第 ${blank} 行是空行，行号与 entry 号不再一一对应，拒绝回退：${path}`);
+    const unparseable = parsed.findIndex((entry) => entry === undefined);
+    if (unparseable >= 0)
+        throw new Error(`Pi 的会话文件第 ${unparseable} 行不是合法 JSON，这个文件的格式已经变了，拒绝回退以免损坏它：${path}`);
+    const headerLines = parsed.filter((entry) => entry?.type === "session");
+    if (headerLines.length !== 1)
+        throw new Error(`Pi 的会话文件里有 ${headerLines.length} 个 header（应为 1 个），格式已经变了，拒绝回退：${path}`);
+    if (parsed[0]?.type !== "session")
+        throw new Error(`Pi 的会话文件第一行不是 header（实际 type=${JSON.stringify(parsed[0]?.type ?? null)}），格式已经变了，拒绝回退：${path}`);
+    if (parsed[0]?.id !== expectedSessionId)
+        throw new Error(`Pi 的会话文件属于会话 ${JSON.stringify(parsed[0]?.id ?? null)}，不是要回退的会话 ${JSON.stringify(expectedSessionId)}。拒绝截断别人的会话。`);
+    if (!raw.endsWith("\n"))
+        throw new Error(`Pi 的会话文件末尾没有换行，格式已经变了，拒绝回退：${path}`);
+    const boundary = parsed.findIndex((entry, index) => index > 0 && entry?.id === boundaryEntryId);
+    if (boundary < 0)
+        throw new Error(`在这份 Pi 会话记录里找不到要保留的那条消息（entry ${JSON.stringify(boundaryEntryId)}）。这条消息可能是更早的版本写的，Super Pi 当时没有记下它对应 Pi 的哪一条。`);
+    // The `parentId` property probe A measured, enforced at the boundary that matters: every entry still
+    // being KEPT must point at something also being kept. A prefix that violates this is not a session,
+    // and writing it would produce a file Pi either rejects or silently misreads.
+    const kept = new Set();
+    for (let index = 0; index <= boundary; index += 1) {
+        const parent = parsed[index]?.parentId;
+        if (parent !== undefined && parent !== null && !kept.has(parent))
+            throw new Error(`要保留的部分不是自洽的：第 ${index} 行引用了不在保留范围内的 ${JSON.stringify(parent)}，拒绝回退以免产出 Pi 打不开的会话。`);
+        kept.add(parsed[index]?.id);
+    }
+    const rewritten = `${lines.slice(0, boundary + 1).join("\n")}\n`;
+    const backupPath = `${path}.super-pi-revert-backup`;
+    const temporaryPath = `${path}.super-pi-revert-tmp`;
+    await writeFile(backupPath, raw, "utf8");
+    await writeFile(temporaryPath, rewritten, "utf8");
+    await rename(temporaryPath, path);
+    // Re-read rather than trust the write. The claim this whole mechanism rests on is "the file's last
+    // line is now the boundary entry", and `_buildIndex` derives the leaf from exactly that line - so if
+    // the write did not land, nothing downstream would say so until a turn produced wrong context.
+    const verified = (await readFile(path, "utf8")).split("\n").filter((line) => line !== "");
+    const last = verified[verified.length - 1];
+    let lastEntry;
+    try {
+        lastEntry = JSON.parse(last);
+    }
+    catch {
+        lastEntry = undefined;
+    }
+    if (verified.length !== boundary + 1 || lastEntry?.id !== boundaryEntryId) {
+        throw new Error(`截断后的 Pi 会话文件没有以要保留的那条消息结尾（写到 ${verified.length} 行，期望 ${boundary + 1} 行，末行 id=${JSON.stringify(lastEntry?.id ?? null)}）。原始文件仍在 ${backupPath}。`);
+    }
+    return { linesKept: boundary + 1, entriesDropped: lines.length - (boundary + 1) };
+}
+/**
+ * Writes a second Pi session file that begins as an EXACT copy of one, under a different session id.
+ *
+ * ============================ WHAT THIS DOES TO THE ORIGINAL ============================
+ * **Nothing.** The source file is read and never written, never truncated, never renamed. This is the
+ * whole difference from `truncateSessionFile`, and it is the reason a fork is the safe half of this pair
+ * of operations: a revert destroys entries permanently and keeps a hand-recovery backup, while a fork
+ * leaves both files whole and keeps no backup because there is nothing to recover.
+ * ========================================================================================
+ *
+ * WHY A COPY AND NOT PI'S `fork()`. Covered at length on `ClientCommand`'s `conversation.fork`: Pi's fork
+ * always tears down the runtime and switches to the new session (`agent-session-runtime.ts:299-307`), and
+ * Super Pi has no runtime to switch - it spawns one Pi per turn and kills it. The file is the only durable
+ * thing a fork has to produce here, so the file is what gets produced.
+ *
+ * ============================ WHAT THIS DOES TO PI's ENTRY IDS ============================
+ * **Nothing either, and this is a deliberate divergence from Pi's own `createBranchedSession`, which
+ * RENUMBERS `parentId` (`:1655-1666`).** Keeping every id verbatim means every cross-reference already
+ * inside the file stays valid, and research pitfall 6 is exactly why that matters: a Pi entry may point
+ * at other entries by id in ways this code has never enumerated - a `compaction` record carries a
+ * `firstKeptEntryId`, `branch_summary` carries the branch point - and renumbering ids means rewriting every
+ * one of those references correctly, with no way to find them all. Copying the bytes cannot break a
+ * reference because it changes nothing a reference points at. The cost is that the same entry id now
+ * exists in two files; that is safe because `_buildIndex` builds its `byId` map per file (`:1103-1122`),
+ * and Super Pi only ever opens one file per process.
+ *
+ * WHAT THE HEADER CHANGES, and it is two fields. `id` becomes the new conversation's id, because that is
+ * what Pi's lookup matches (`findLocalSessionByExactId` reads the header, probe B) and therefore what makes
+ * `--session-id <forked>` open THIS file rather than silently inventing an empty session with that id
+ * (`main.ts:436-448`, measured: `Warning: No project session found with id '...'`). And `parentSession`
+ * records the file this one came from, which is the same one-line lineage pointer Pi itself writes
+ * (`:1675-1682`) and is not a link - the files share nothing. `cwd`, `version` and `timestamp` are copied
+ * verbatim: `cwd` MUST be identical, because Pi's lookup requires the recorded cwd to equal the one it is
+ * asked from, and the fork always lives in the same workspace as its source.
+ *
+ * THE SAME FORMAT CHECKS AS TRUNCATE, AND FOR THE SAME REASON. Probe A measured this file's shape against
+ * real Pi (`scripts/probe-revert-session-format.mjs`); a Pi upgrade can invalidate any of those claims, so
+ * every one is re-checked before a byte is written and a failure names the shape actually found. Here the
+ * `parentId` property is checked across the WHOLE file rather than across a kept prefix, because the whole
+ * file is what is being copied.
+ *
+ * TEMP-THEN-RENAME, because Pi appends with a bare `appendFileSync` (`:1187`) and the target must never be
+ * observed half-written - a half-written file under the forked id is precisely the "Pi opens an empty
+ * session and the history has vanished with no error anywhere" outcome probe B was about.
+ *
+ * EXPORTED so it can be tested against fabricated session files in a temp directory, without Pi.
+ */
+export async function forkSessionFile(sourcePath, targetPath, expectedSessionId, targetSessionId) {
+    const raw = await readFile(sourcePath, "utf8");
+    const lines = raw.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    if (!lines.length)
+        throw new Error(`Pi 的会话文件是空的，拒绝分叉：${sourcePath}`);
+    const parsed = lines.map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return undefined;
+        }
+    });
+    // The refusal messages name the shape actually found, and say "拒绝分叉" rather than reusing the revert
+    // wording: the reader is looking at a fork button, and a message about 回退 would send them to look for a
+    // control they did not press.
+    const blank = lines.findIndex((line) => line.trim() === "");
+    if (blank >= 0)
+        throw new Error(`Pi 的会话文件第 ${blank} 行是空行，无法安全复制，拒绝分叉：${sourcePath}`);
+    const unparseable = parsed.findIndex((entry) => entry === undefined);
+    if (unparseable >= 0)
+        throw new Error(`Pi 的会话文件第 ${unparseable} 行不是合法 JSON，这个文件的格式已经变了，拒绝分叉以免复制出一个 Pi 打不开的会话：${sourcePath}`);
+    const headerLines = parsed.filter((entry) => entry?.type === "session");
+    if (headerLines.length !== 1)
+        throw new Error(`Pi 的会话文件里有 ${headerLines.length} 个 header（应为 1 个），格式已经变了，拒绝分叉：${sourcePath}`);
+    if (parsed[0]?.type !== "session")
+        throw new Error(`Pi 的会话文件第一行不是 header（实际 type=${JSON.stringify(parsed[0]?.type ?? null)}），格式已经变了，拒绝分叉：${sourcePath}`);
+    // The one that matters most. Copying the wrong file would put one person's conversation into another's
+    // session, and unlike a wrong truncation it would be written as a brand-new file rather than destroying
+    // something - so this check is what stops a fork from being a disclosure.
+    if (parsed[0]?.id !== expectedSessionId)
+        throw new Error(`Pi 的会话文件属于会话 ${JSON.stringify(parsed[0]?.id ?? null)}，不是要分叉的会话 ${JSON.stringify(expectedSessionId)}。拒绝复制别人的会话。`);
+    if (!raw.endsWith("\n"))
+        throw new Error(`Pi 的会话文件末尾没有换行，格式已经变了，拒绝分叉：${sourcePath}`);
+    // Every kept entry must point at another kept entry. The whole file is being copied, so "kept" is all of
+    // it - and a file that violates this is not a session Pi can open.
+    const known = new Set();
+    for (let index = 0; index < parsed.length; index += 1) {
+        const parent = parsed[index]?.parentId;
+        if (parent !== undefined && parent !== null && !known.has(parent))
+            throw new Error(`这个 Pi 会话记录不自洽：第 ${index} 行引用了不存在的 ${JSON.stringify(parent)}，拒绝分叉以免复制出一个 Pi 打不开的会话：${sourcePath}`);
+        known.add(parsed[index]?.id);
+    }
+    // The header is REBUILT rather than string-patched, so the two changed fields are structural and
+    // everything else - including any field a future Pi adds - is carried across untouched. A regex over the
+    // first line would silently drop a field it did not recognise.
+    const header = { ...parsed[0], id: targetSessionId, parentSession: sourcePath };
+    const rewritten = [JSON.stringify(header), ...lines.slice(1)].join("\n") + "\n";
+    const temporaryPath = `${targetPath}.super-pi-fork-tmp`;
+    await writeFile(temporaryPath, rewritten, "utf8");
+    await rename(temporaryPath, targetPath);
+    // Re-read rather than trust the write. The claim this rests on is "a Pi spawned with the new id will
+    // open THIS file and find the whole history in it", and nothing downstream would report a failed write -
+    // the fork would simply appear to work and the model would start from nothing.
+    const verified = (await readFile(targetPath, "utf8")).split("\n").filter((line) => line !== "");
+    let verifiedHeader;
+    try {
+        verifiedHeader = JSON.parse(verified[0]);
+    }
+    catch {
+        verifiedHeader = undefined;
+    }
+    if (verified.length !== lines.length || verifiedHeader?.id !== targetSessionId) {
+        throw new Error(`写入后的 Pi 会话文件不是预期的样子（写到 ${verified.length} 行，期望 ${lines.length} 行，header id=${JSON.stringify(verifiedHeader?.id ?? null)}，期望 ${JSON.stringify(targetSessionId)}）。已放弃，没有创建任何会话。`);
+    }
+    return { entriesCopied: lines.length - 1 };
+}
+/** How long one command may take before the turn is failed rather than left hanging. */
+const SESSION_COMMAND_TIMEOUT_MS = 10_000;
+/** `get_state`/`get_entries` on an idle Pi. Generous, because it only has to answer a question. */
+const LOOKUP_COMMAND_TIMEOUT_MS = 30_000;
+/**
+ * How long a `steer` may go unanswered before the caller is told the outcome is unknown.
+ *
+ * The same budget as any other single Pi command, for the same reason: this is one round-trip to a
+ * local child that is already busy running a turn. It is generous because the child is mid-turn and may
+ * not read stdin promptly - too short a budget would report "unknown" for steers Pi simply had not got
+ * to yet, which is exactly the ambiguity this whole path exists to avoid.
+ */
+const STEER_COMMAND_TIMEOUT_MS = 10_000;
+/**
+ * Reads Pi's `steer` disposition out of its response payload.
+ *
+ * Unknown and missing both become `queued`, which is the CONSERVATIVE default and not a convenience: a
+ * steer Pi could not categorise may or may not already be in the model's context, so it must keep being
+ * treated as "not yet delivered" until a `queue_update` says otherwise. Guessing `handled` would let the
+ * caller drop the message from the dock on the strength of a payload shape we did not recognise.
+ */
+export function describeSteerDisposition(data) {
+    const disposition = data?.disposition;
+    return disposition === "handled" || disposition === "queued" ? disposition : "queued";
+}
+/**
+ * How long a catalog answer is reused. Pi's model list changes when the user edits its config, never
+ * on a timer, so this only trades freshness for the ~400-840ms a probe Pi costs - measured here at
+ * 394ms for all three commands written at once. Ten minutes is long enough that reopening a picker
+ * twice in a session never pays for a second spawn, and short enough that a `pi models add` shows up
+ * the same afternoon.
+ */
+const CATALOG_TTL_MS = 10 * 60_000;
+/** A FAILED catalog is cached for far less time, so one broken Pi cannot be retried on every keystroke of a model switch. */
+const CATALOG_FAILURE_TTL_MS = 30_000;
+const CATALOG_COMMAND_TIMEOUT_MS = 15_000;
+/** Keys Pi's model answers by. Exported so the store and the tests agree with the runtime. */
+export const catalogKey = (selection) => (selection?.provider && selection.modelId ? `${selection.provider}/${selection.modelId}` : "default");
+/**
+ * Where the `task` extension lives, as an ABSOLUTE path.
+ *
+ * Absolute because Pi requires it: `--extension` takes the path verbatim and resolves it against Pi's
+ * own working directory, which is the CONVERSATION's workspace, not this repository. A relative path
+ * would therefore resolve differently for every conversation and fail for all of them except the one
+ * whose workspace happens to be this repo.
+ *
+ * `import.meta.dirname` is the one thing stable across both ways this code runs - `dist/server/` after
+ * `tsc -b`, `src/server/` under `tsx watch` - so two `..` segments reach the repository root either way.
+ *
+ * Returned as a FUNCTION rather than a module constant so a test can assert on the resolution without
+ * this module's import-time filesystem state deciding it, and so the "does it exist" check below is a
+ * warning on a path that is genuinely optional rather than a startup crash on a build that skipped it.
+ */
+export function taskExtensionPath(from = import.meta.dirname) {
+    return resolve(from, "../../agents/super-pi-task/index.ts");
+}
+/** Bridges a Pi session to Super Pi through Pi's documented JSONL RPC protocol. */
+export class PiRpcRuntime {
+    sessionDir;
+    agents;
+    options;
+    runs = new Map();
+    /**
+     * `steer` commands written to a child and not yet answered by Pi, keyed by the command id.
+     *
+     * A steer has to be correlated to a promise rather than fire-and-forget, because Pi's `steer` response
+     * carries a `disposition` that decides whether the message is already in the model's context or still
+     * waiting (`handled` vs `queued`, `rpc-mode.ts:416-419`). Without that answer Super Pi would have to
+     * guess, and both guesses are wrong: reporting a delivered steer as waiting would leave a message
+     * stranded in the dock forever, and reporting a waiting one as delivered would let the user cancel a
+     * message the model is about to act on.
+     */
+    pendingSteers = new Map();
+    /** Distinguishes steer command ids. Never reused, so a late response cannot settle a later steer. */
+    steerSeq = 0;
+    catalogs = new Map();
+    /** In-flight reads, so N clients asking at once cost ONE Pi spawn rather than N. */
+    pendingCatalogs = new Map();
+    /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
+    warnedMissingExtension = false;
+    /**
+     * Agent definitions are read from disk, never cached. A file is cheap to parse, and re-reading it
+     * per turn is the whole point: editing an agent's prompt or tool allowlist changes the NEXT message
+     * with no re-selection and no restart, which a cache would silently prevent.
+     *
+     * `command` is an override for tests and for a Pi installed somewhere unusual; with none given, Pi is
+     * resolved through `resolvePiCommand()` (override -> PATH -> npm's global bin directory), the same
+     * function scripts/probe-agent-real-pi.mjs uses. Resolved ONCE here because it is a filesystem
+     * lookup, and a resolution that could change mid-run would make a turn's spawn line depend on when
+     * it was started.
+     */
+    pi;
+    constructor(sessionDir, command, 
+    /**
+     * Where agent definitions are read from and where their prompt bodies are written. A THIRD positional
+     * parameter rather than part of the second one, so every existing `new PiRpcRuntime(dir, launcher)`
+     * call site keeps its meaning - moving the agent directory into that slot would have silently fed a
+     * launcher's file path in as a directory of agent definitions.
+     */
+    agents = { dir: join(sessionDir, "agents"), promptDir: join(sessionDir, "agent-prompts") }, 
+    /**
+     * How the `task` extension reaches this server. A FOURTH positional parameter for the same reason as
+     * the third: an options bag in one of the earlier slots would silently change what an existing
+     * `new PiRpcRuntime(dir, launcher, { dir, promptDir })` call site means.
+     *
+     * `endpoint` is this server's own listening URL, supplied rather than derived. It is the fix for
+     * hardcoding a port: `SUPER_PI_PORT` is honoured by `index.ts` and by every test that boots on
+     * `freePort()`, so an extension that dialled a fixed number would reach nothing at all. When it is
+     * absent the extension is simply not mounted, and the reason is logged once per turn rather than
+     * swallowed - a task tool that is mysteriously missing is the single hardest failure here to
+     * diagnose from the outside.
+     *
+     * `todoEndpoint` is the `todowrite` endpoint, supplied the same way and for the same reason, and it
+     * is a SEPARATE field rather than a path derived from `endpoint`: the two tools are allowed to be
+     * available independently (a harness that only exercises dispatch does not want a todo writer, and an
+     * older checkout has no todo endpoint at all), and a derived path could not tell "not configured"
+     * from "configured wrong". When it is absent the tool still registers and the extension refuses in
+     * words, which is what `refuseTodo` in core.ts is for.
+     */
+    options = {}) {
+        this.sessionDir = sessionDir;
+        this.agents = agents;
+        this.options = options;
+        this.pi = resolvePiCommand({ command });
+        if (!this.pi.found)
+            console.warn(`PiRpcRuntime: ${this.pi.reason}`);
+    }
+    /**
+     * The agent a conversation runs as, or undefined for Pi's own defaults.
+     *
+     * A missing file is NOT an error: a conversation that names an agent that has since been deleted
+     * degrades to running as Pi itself, with a warning, rather than failing every turn forever. A
+     * `subagent` definition is also ignored here - those are invoked BY a primary agent, never chosen
+     * as the conversation's own role.
+     */
+    async agentFor(conversation) {
+        if (!conversation.agentId)
+            return undefined;
+        const { agents, problems } = await readAgents(this.agents.dir);
+        const agent = agents.find((item) => item.id === conversation.agentId);
+        if (agent)
+            return agent;
+        console.warn(`PiRpcRuntime: conversation ${conversation.id} names agent ${JSON.stringify(conversation.agentId)}, which is not a primary agent in ${this.agents.dir}${problems.length ? ` (${problems.length} file(s) there are not usable agents)` : ""} - running as Pi itself.`);
+        return undefined;
+    }
+    /**
+     * The `--extension` argv for this turn, or `[]` when the task tool is not available.
+     *
+     * Empty in TWO different situations, and both are deliberate rather than merged:
+     *
+     * - No endpoint was configured, so there is nowhere for the extension to dispatch to. Mounting it
+     *   anyway would give the model a tool whose every call fails with a network error.
+     * - The extension file is not on disk. That is a build or checkout problem, and it is warned about
+     *   ONCE rather than every turn, because "your primary agent cannot delegate anything" is worth
+     *   knowing and worth not repeating on every keystroke.
+     */
+    async taskExtensionArgs() {
+        if (!this.options.endpoint)
+            return [];
+        const path = taskExtensionPath();
+        if (!existsSync(path)) {
+            if (!this.warnedMissingExtension) {
+                this.warnedMissingExtension = true;
+                console.warn(`PiRpcRuntime: ${path} does not exist, so the primary agent cannot delegate to sub-agents. The task tool is off for every conversation until it is restored.`);
+            }
+            return [];
+        }
+        return ["--extension", path];
+    }
+    /**
+     * The five values the extension reads out of its own environment. See `task-tool.ts` for why they are
+     * written out on both sides rather than imported.
+     *
+     * The ROSTER is read here, per turn, from the same `readAgents` the picker and the supervisor use -
+     * never from a list written into this file. A sub-agent added while the server is running is therefore
+     * dispatchable on the next message with no restart, which is the same freshness rule `agentFor`
+     * follows for agent files and for the same reason: a human edits those files while the server runs.
+     *
+     * `depth` is `0`, hardcoded, and that is not an oversight: this is the PRIMARY agent's spawn, so it is
+     * definitionally at the top of the tree. `SubagentSupervisor` never passes this function, which is why
+     * no sub-agent process is ever given this environment at all.
+     *
+     * The TODO ENDPOINT is the one value here that is NOT per-turn derived from disk: it is this server's
+     * own address, so it is the same string on every turn and is read once from the constructor's options.
+     */
+    async taskExtensionEnv(conversationId) {
+        const { agents, problems } = await readAgents(this.agents.dir, { mode: "subagent" });
+        for (const problem of problems)
+            console.warn(`PiRpcRuntime: ${this.agents.dir}/${problem.file} is not a usable sub-agent - ${problem.message}`);
+        return {
+            [TASK_ENDPOINT_ENV]: this.options.endpoint ?? "",
+            [TASK_ROSTER_ENV]: rosterPayload(agents),
+            [TASK_CONVERSATION_ENV]: conversationId,
+            [TASK_DEPTH_ENV]: "0",
+            [TODO_ENDPOINT_ENV]: this.options.todoEndpoint ?? "",
+        };
+    }
+    async *answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onToolCall, onToolEnd, images }) {
+        await mkdir(this.sessionDir, { recursive: true });
+        // Normalize first: the picker can hand over forward slashes or a trailing separator, and `resolve`
+        // turns both into one absolute native path. The directory must exist on disk before spawn - a
+        // deleted workspace directory is a visible failure, never a reason to run somewhere else.
+        const childCwd = resolve(cwd);
+        const info = await stat(childCwd).catch(() => undefined);
+        if (!info?.isDirectory())
+            throw new Error(`Workspace directory for conversation ${conversation.id} does not exist or is not a directory: ${childCwd}. Refusing to run Pi in any other directory.`);
+        // The agent's flags go on the SPAWN line, not the wire, because that is the only place Pi reads
+        // them: its RPC command union (rpc-types.ts:20-74) has no prompt and no tools command, so there is
+        // nothing to send after the process is already running. Fetched before the spawn so a definition
+        // error fails the turn loudly instead of starting a Pi that silently ignores it.
+        const agent = await this.agentFor(conversation);
+        // Whether the `task` tool EXISTS is decided first, because that is what decides whether it belongs
+        // on the allowlist. Naming a tool Pi has not registered is meaningless, and doing it anyway would
+        // change the spawn line of a runtime that has no task tool - which is what
+        // `PiRpcRuntime(dir, launcher)` without an endpoint is, and what `agent-mechanism.test.mjs` asserts
+        // a byte-identical spawn line for.
+        //
+        // Why it has to be added at all: Pi filters its registry through `--tools` and only activates a tool
+        // the allowlist allows (agent-session.ts:3567-3574), so a primary agent declaring
+        // `tools: {"*": false, read: true}` would otherwise get an extension tool that is loaded and never
+        // declared - broken with no error. An agent that says `task: false` still wins: `toolFlags` treats an
+        // explicit false as outranking a host extra, which is what makes "this agent does not delegate" true
+        // rather than advisory.
+        const extensionArgs = await this.taskExtensionArgs();
+        // BOTH extension tools, or neither. Naming one while the other goes unmentioned would be a lie in a
+        // different direction: Pi filters its registry through `--tools`, so an agent that declares
+        // `tools: {"*": false, read: true}` gets whichever of the two is on this line and silently not the
+        // other. They also share the extension's existence - `extensionArgs` is non-empty exactly when
+        // `index.ts` is on disk and an endpoint was configured - so there is no case where one is mounted and
+        // the other is not.
+        const agentArgs = await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME] : [] });
+        // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
+        // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
+        if (!this.pi.found)
+            throw new Error(this.pi.reason);
+        // npm exposes global CLIs as .cmd shims on Windows; Node requires a shell to launch those shims.
+        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id, ...extensionArgs, ...agentArgs], {
+            cwd: childCwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: process.platform === "win32",
+            // `env` is passed ONLY when the extension is mounted, because passing `{ ...process.env }` on
+            // every turn would silently replace the child's environment with whatever THIS process has at
+            // spawn time. Inheriting is what an omitted `env` already does, so the two paths differ in nothing
+            // but the four documented additions.
+            ...(extensionArgs.length ? { env: { ...process.env, ...await this.taskExtensionEnv(conversation.id) } } : {}),
+        });
+        const channel = new RpcChannel(child);
+        this.runs.set(conversation.id, { child, channel });
+        const abort = () => { if (!child.killed)
+            child.stdin.write(`${JSON.stringify({ id: "abort", type: "abort" })}\n`); };
+        signal.addEventListener("abort", abort, { once: true });
+        // A blocking request is awaited inside the drain loop, so the loop cannot observe an abort or a
+        // dead child on its own. Both are raced into the wait so a pending question can never outlive the run.
+        const ui = { seen: new Set(), aborted: new Promise((resolve) => { if (signal.aborted)
+                resolve(undefined);
+            else
+                signal.addEventListener("abort", () => resolve(undefined), { once: true }); }), exited: new Promise((resolve) => child.once("exit", () => resolve(undefined))) };
+        try {
+            // The leaf this turn starts from, read from Pi BEFORE anything is written this turn.
+            //
+            // Written, not awaited: Pi queues commands, so this line costs no wall-clock time - it is answered
+            // while the model is thinking, and collected at the end of the turn. Awaiting it here would add a
+            // round trip to every message in exchange for information nothing needs until the turn is over.
+            //
+            // The FIRST turn has no file and no leaf at all, which is why `leafId` may be null: Pi reports it
+            // that way until something has been appended, and the `since` lookup below simply reads everything.
+            let turnStart;
+            if (onUserEntry) {
+                channel.write({ id: "turn_head", type: "get_entries" });
+                // Swallowed HERE rather than awaited below: a Pi that cannot answer this has not failed the turn,
+                // and the alternative - propagating - would turn "this message cannot be a revert boundary" into
+                // "your message failed to send", which is both false and far more alarming.
+                turnStart = channel.waitFor("turn_head", SESSION_COMMAND_TIMEOUT_MS, "get_entries").catch((error) => {
+                    console.warn(`PiRpcRuntime: could not read the leaf before the turn (${error instanceof Error ? error.message : "unknown error"}) - this turn's message may not become a revert boundary.`);
+                    return undefined;
+                });
+            }
+            // The conversation's picker selection, applied to THIS Pi before it sees the prompt. A refusal
+            // is thrown, never downgraded to a warning: a run on some other model than the button says is
+            // exactly the decorative picker this must not be.
+            for (const command of sessionCommands(conversation)) {
+                const response = await channel.request(command, SESSION_COMMAND_TIMEOUT_MS);
+                if (response.success === false)
+                    throw new Error(`Pi rejected ${command.type}: ${response.error ?? "no reason given"}`);
+            }
+            const imagePayloads = this.options.uploadsDir && images?.length
+                ? await loadConversationImages(this.options.uploadsDir, conversation.id, images)
+                : undefined;
+            channel.write({ id: "prompt", type: "prompt", message: prompt, ...(imagePayloads?.length ? { images: imagePayloads } : {}) });
+            let settled = false;
+            // Nothing may be dropped without a trace. Pi emits a wide, open-ended family of agent
+            // session events (tool_call, thinking, compaction_*, auto_retry_*, ...), so an unhandled
+            // record is announced once per distinct type and then tallied instead of logging per event.
+            const announced = new Set();
+            const repeats = new Map();
+            const noteUnhandled = (key) => {
+                if (announced.has(key))
+                    repeats.set(key, (repeats.get(key) ?? 0) + 1);
+                else {
+                    announced.add(key);
+                    console.warn(`PiRpcRuntime: unhandled Pi RPC record ${key} - consumed without action.`);
+                }
+            };
+            while (!settled) {
+                for (;;) {
+                    const record = await channel.next(100);
+                    if (!record)
+                        break;
+                    // A response the loop does not itself consume is not garbage - it is the answer to a command
+                    // somebody wrote on this channel and is waiting for (`get_entries`, and in `readCatalog` the model
+                    // list). Handed to the stash rather than dropped, which is what stopped the loop from eating the
+                    // per-turn entry-id read and leaving this turn's message unrecordable.
+                    if (record.type === "response" && record.id !== "prompt") {
+                        channel.stash(record);
+                        continue;
+                    }
+                    if (record.type === "response" && record.id === "prompt" && record.success === false)
+                        throw new Error(record.error ?? "Pi rejected the prompt");
+                    // A `steer` written while this turn was running, answered here because this loop is the only
+                    // thing reading the child's stdout. Settled rather than ignored: the caller is holding a
+                    // promise on this exact id to learn whether the message is already in the model's context.
+                    if (record.type === "response" && record.id !== "prompt") {
+                        const pending = typeof record.id === "string" ? this.pendingSteers.get(record.id) : undefined;
+                        if (pending) {
+                            this.pendingSteers.delete(record.id);
+                            if (record.success === false)
+                                pending.reject(new Error(`Pi rejected the steer: ${record.error ?? "no reason given"}`));
+                            else
+                                pending.resolve(describeSteerDisposition(record.data) ?? "queued");
+                        }
+                        continue;
+                    }
+                    // Pi's own queue, pushed as a full snapshot whenever it changes. READ, not dropped: this used
+                    // to fall through to `noteUnhandled` and be logged once as an unhandled record type, which is
+                    // the "looks wired up but nothing happens" failure - it is the only signal that a steer was
+                    // really picked up, and Pi emits it before the delivered message on the same stdout stream.
+                    const piQueue = describePiQueue(record);
+                    if (piQueue) {
+                        try {
+                            onPiQueue?.(piQueue);
+                        }
+                        catch (error) {
+                            console.warn(`PiRpcRuntime: the pi queue handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+                        }
+                        continue;
+                    }
+                    // THE PRIMARY AGENT'S TOOL CALLS. Consumed, not announced - the same routing the sub-agent
+                    // supervisor already does for its child (subagents.ts:532-559), on the same two records.
+                    //
+                    // These two used to reach `noteUnhandled` and be logged once each per turn, which is the
+                    // "looks wired up but nothing happens" failure twice over: the warning said the host did not
+                    // understand them, and the host genuinely did not, so a `read` and a two-minute `bash` were the
+                    // same silence on the transcript. Consumed here because they now carry data - which is the
+                    // difference between routing and silencing.
+                    //
+                    // WHAT IS *NOT* CHANGED. Every other record type keeps its existing report, including the inner
+                    // `message_update` events below: a `thinking_delta` still announces itself, because that is a
+                    // documented decision about an event shape rather than an oversight this branch is here to
+                    // repair. Only the two tool records move.
+                    if (record.type === "tool_execution_start") {
+                        // The `args` are READ and summarised, never carried: `describeToolCallArgs` turns an
+                        // arbitrary object into at most six capped strings and a non-string becomes a bare type
+                        // word, because an `edit`'s arguments routinely hold a whole file's replacement text. See
+                        // tool-calls.ts for the argument-vs-transcript line.
+                        const name = record.toolName ?? "unknown";
+                        try {
+                            onToolCall?.({ id: record.toolCallId ?? "", name, detail: describeToolCall(name, record.args), args: describeToolCallArgs(record.args) });
+                        }
+                        catch (error) {
+                            console.warn(`PiRpcRuntime: the tool call handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+                        }
+                        continue;
+                    }
+                    if (record.type === "tool_execution_end") {
+                        // The other half of the same call, and the half that lets a block say whether it finished.
+                        // ONLY `isError` AND `durationMs` CROSS OVER. `result` is never read - `RpcRecord` does not
+                        // even declare it, because for a `read` it is the file's contents and `ToolCallNotice` is
+                        // persisted into `state.json`.
+                        //
+                        // The handler is wrapped for the same reason the queue handler is: a listener that throws
+                        // must cost one tool row, not the whole turn's drain loop.
+                        try {
+                            onToolEnd?.({
+                                id: record.toolCallId ?? "",
+                                name: record.toolName ?? "unknown",
+                                status: record.isError === true ? "error" : "ok",
+                                ...(typeof record.durationMs === "number" && Number.isFinite(record.durationMs) ? { durationMs: Math.max(0, Math.round(record.durationMs)) } : {}),
+                            });
+                        }
+                        catch (error) {
+                            console.warn(`PiRpcRuntime: the tool end handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+                        }
+                        continue;
+                    }
+                    if (record.type === "message_update") {
+                        const event = record.assistantMessageEvent;
+                        // text_delta is the only inner event that drives the visible answer. The rest (thinking,
+                        // tool calls, message_start/end) are consumed here, but still announced once each so an
+                        // event shape this runtime ignores cannot pass unnoticed.
+                        if (event?.type === "text_delta")
+                            yield event.delta ?? "";
+                        else
+                            noteUnhandled(`message_update:${JSON.stringify(event?.type ?? "(missing)")}`);
+                        continue;
+                    }
+                    if (record.type === "extension_ui_request") {
+                        await this.handleExtensionUi(record, child, host, ui);
+                        continue;
+                    }
+                    // Pi already caught this error inside the extension host, so it will never reach us as a
+                    // thrown failure. Every answer spawns its own Pi process, so any extension_error seen while
+                    // draining belongs to the prompt in flight - surface it as a real failure instead of
+                    // letting the turn finish as if nothing happened.
+                    if (record.type === "extension_error") {
+                        console.warn(`PiRpcRuntime: extension_error path=${record.extensionPath ?? "unknown"} event=${record.event ?? "unknown"} error=${record.error ?? "unknown"}`);
+                        throw new Error(`Pi extension error in ${record.extensionPath ?? "unknown path"} (${record.event ?? "unknown event"}): ${record.error ?? "unknown error"}`);
+                    }
+                    if (record.type === "agent_settled") {
+                        settled = true;
+                        continue;
+                    }
+                    noteUnhandled(`type ${JSON.stringify(record.type ?? "(missing type)")}`);
+                }
+                if (!settled && child.exitCode !== null)
+                    throw new Error(`Pi RPC exited before settling (code ${child.exitCode}). ${channel.stderr.trim()}`);
+            }
+            for (const [key, count] of repeats)
+                console.warn(`PiRpcRuntime: ${count} further unhandled record(s) of ${key}.`);
+            // This turn's own slice of Pi's transcript, taken now because after the `finally` below the child is
+            // gone and `answer()` will never be able to ask again.
+            //
+            // `since` is what makes this exact rather than approximate: the entries written after the pre-turn
+            // leaf belong to THIS turn, and the first USER message among them is the one Super Pi just pushed.
+            // Counting messages instead would be wrong the moment a compaction or a `model_change` lands in the
+            // slice - which is exactly research §5 pitfall 6.
+            if (onUserEntry) {
+                await this.recordTurnEntryId(channel, await turnStart, conversation.id, onUserEntry);
+            }
+        }
+        finally {
+            signal.removeEventListener("abort", abort);
+            this.runs.delete(conversation.id);
+            // A steer still unanswered when the turn ends is REJECTED, not left pending. The drain loop above
+            // is the only reader of this child's stdout and it has stopped, so nothing would ever settle that
+            // promise: the caller would wait for a timeout to learn something this process already knows. The
+            // message itself is not lost - Pi drains steering before its loop can end, so anything unanswered
+            // at this point was in practice not delivered, and the caller returns it to its queue.
+            if (this.pendingSteers.size) {
+                for (const [id, pending] of [...this.pendingSteers]) {
+                    this.pendingSteers.delete(id);
+                    pending.reject(new Error(`Pi never answered the steer: the turn ended first.`));
+                }
+            }
+            // The run is not over until the child is actually gone: a process that is still tearing down
+            // still holds a lock on its working directory, so a caller that removes that directory the
+            // moment answer() returns would hit EBUSY on Windows. Kill, then wait for the exit.
+            //
+            // The 5s backstop is load-bearing and matches the two other waits in this file: the kill
+            // precedes the `exit` subscription, so an exit that lands between them is dropped and the promise
+            // never settles. Unbounded, that hangs the turn that asked for it. See readCatalog() for the
+            // measurement.
+            if (child.exitCode === null && child.pid !== undefined) {
+                if (!child.killed) {
+                    if (process.platform === "win32")
+                        await killTree(child.pid);
+                    else
+                        child.kill();
+                }
+                if (child.exitCode === null)
+                    await new Promise((resolve) => { child.once("exit", resolve); setTimeout(resolve, 5000); });
+            }
+        }
+    }
+    /**
+     * Reads back the id of the user message this turn just created, and hands it to the caller.
+     *
+     * `head` is the already-answered pre-turn `get_entries`, whose `leafId` is what makes the second read
+     * exact. Its three possible outcomes are handled differently ON PURPOSE, because they mean different
+     * things and two of them must not produce an id:
+     *
+     * - `leafId: null` - the session was empty, so this IS the first turn and the whole entry list is this
+     *   turn's. Safe to take the first user message from it.
+     * - `leafId: "..."` - read only what came after it. Safe, and the only correct answer for turn two onward.
+     * - no usable answer - Pi never told us where the turn began, so NOTHING in the transcript can be
+     *   attributed to it. Reading everything and taking "the first user message" here would hand back a
+     *   PREVIOUS turn's id, and a revert to that id would silently cut more than the user asked for. So this
+     *   case records nothing and says why.
+     *
+     * Every failure is a warning, never a throw: the turn's answer has already streamed by this point, and
+     * "this message cannot be a revert boundary" is not "your message failed".
+     */
+    async recordTurnEntryId(channel, head, conversationId, onUserEntry) {
+        const before = head?.data;
+        const leaf = before?.leafId;
+        if (leaf !== null && typeof leaf !== "string") {
+            console.warn(`PiRpcRuntime: Pi did not report where turn of conversation ${conversationId} started, so its message was not recorded and cannot be used as a revert boundary.`);
+            return;
+        }
+        try {
+            const id = `turn_tail_${Math.random().toString(36).slice(2, 10)}`;
+            // `since` is omitted, not sent as null, on the first turn: Pi's handler tests
+            // `command.since !== undefined` (`rpc-mode.ts:638`), and an explicit null would be a lookup for an
+            // entry named "null" that fails with an error instead of reading everything.
+            channel.write({ id, type: "get_entries", ...(typeof leaf === "string" ? { since: leaf } : {}) });
+            const tail = await channel.waitFor(id, SESSION_COMMAND_TIMEOUT_MS, "get_entries");
+            if (tail.success === false)
+                throw new Error(tail.error ?? "Pi rejected get_entries");
+            const entries = tail.data?.entries;
+            if (!Array.isArray(entries))
+                throw new Error("get_entries returned no entry list");
+            const firstUser = entries.find((entry) => {
+                const candidate = entry;
+                return candidate?.type === "message" && candidate.message?.role === "user" && typeof candidate.id === "string";
+            });
+            if (typeof firstUser?.id !== "string") {
+                console.warn(`PiRpcRuntime: the entries Pi added for this turn contain no user message, so nothing was recorded as a revert boundary for conversation ${conversationId}.`);
+                return;
+            }
+            await onUserEntry(firstUser.id);
+        }
+        catch (error) {
+            console.warn(`PiRpcRuntime: could not record this turn's Pi entry id for conversation ${conversationId} (${error instanceof Error ? error.message : "unknown error"}) - its message cannot be used as a revert boundary.`);
+        }
+    }
+    /**
+     * Reverts Pi's own transcript to the state right after `boundaryEntryId`.
+     *
+     * ============================ WHAT THIS DESTROYS ============================
+     * Every Pi entry after that boundary, permanently - including tool calls, compaction records, model and
+     * thinking-level markers, and usage accounting, not just the messages Super Pi shows. A copy of the file
+     * as it was is left beside it as `<file>.super-pi-revert-backup`, which Pi never lists because it does
+     * not end in `.jsonl`. There is no undo in the application.
+     *
+     * No workspace file is read, written or restored. That is the whole point of not reaching for OpenCode's
+     * `snapshot/` machinery: its revert rolls the working tree back (`snapshot/index.ts:382-406`), this one
+     * must not, and Super Pi has no reason to build a second git shadow repository to do damage.
+     * =============================================================================
+     *
+     * WHY PI IS ASKED WHICH FILE TO OPEN, rather than this code scanning the session directory.
+     *
+     * The obvious implementation - read the directory, find the `*.jsonl` whose header id matches - is
+     * exactly the one that fails silently, and probe B measured why:
+     *
+     * 1. When Pi cannot find the requested id it does NOT fail. It prints a warning to stderr and opens a
+     *    brand-new session under that same id (`main.ts:436-448`), so a wrong lookup becomes "the history
+     *    has vanished" with no error anywhere in the UI. Measured:
+     *    `Warning: No project session found with id '...'; creating a new session with that id.`
+     * 2. Pi's lookup is not "match the id". With an explicit `--session-dir` it ALSO requires the session's
+     *    recorded `cwd` to equal the one it was asked from (`session-manager.ts:1874-1891`), and probe B
+     *    measured the same id resolving to two different files from two different working directories -
+     *    one of which did not exist on disk.
+     *
+     * So the file is taken from Pi's own `get_state.sessionFile` (`rpc-mode.ts:448-464`), which is the
+     * lookup Pi performed for a real spawn, and then THREE things are checked before a byte is written:
+     * the file exists, its header is the session header, and that header's id is the conversation being
+     * reverted. A miss on any of them refuses, in words, rather than truncating something it is not sure of.
+     *
+     * The cost is one extra Pi spawn, which is why this is a deliberate trade rather than an oversight:
+     * revert is a rare, deliberate act, and a second Pi answers in well under a second. It buys the
+     * elimination of an entire class of "we truncated the wrong file and nothing said so" failures.
+     */
+    async revert({ conversation, cwd, boundaryEntryId }) {
+        if (this.runs.has(conversation.id))
+            throw new Error("这个会话还有一轮任务在跑，先停止它再回退");
+        if (!this.pi.found)
+            throw new Error(this.pi.reason);
+        const childCwd = resolve(cwd);
+        const info = await stat(childCwd).catch(() => undefined);
+        if (!info?.isDirectory())
+            throw new Error(`工作区目录不存在或不是目录，无法在其中找到这个会话的 Pi 记录：${childCwd}`);
+        await mkdir(this.sessionDir, { recursive: true });
+        // NO agent flags and NO extension on this spawn. It sends no prompt and must leave nothing behind:
+        // `SessionManager._persist` only creates a file once a session holds a message
+        // (`session-manager.ts:1160-1170`), so an answer to `get_state` cannot write anything. Adding the
+        // task extension here would mount a tool whose every call fails, since no endpoint is wired up.
+        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id], {
+            cwd: childCwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: process.platform === "win32",
+        });
+        let sessionFile;
+        try {
+            const channel = new RpcChannel(child);
+            const state = await channel.request({ id: "revert_state", type: "get_state" }, LOOKUP_COMMAND_TIMEOUT_MS);
+            if (state.success === false)
+                throw new Error(`Pi 没有回答会话状态：${state.error ?? "未说明原因"}`);
+            const data = state.data;
+            // Pi echoes the id back even when it has just INVENTED a session for it, so this catches a Pi that
+            // did something else entirely rather than the ordinary "no history yet" case below.
+            if (typeof data?.sessionId === "string" && data.sessionId !== conversation.id)
+                throw new Error(`Pi 打开的会话是 ${JSON.stringify(data.sessionId)}，不是要回退的 ${JSON.stringify(conversation.id)}。已放弃，没有改动任何文件。`);
+            if (typeof data?.sessionFile === "string" && data.sessionFile)
+                sessionFile = data.sessionFile;
+            if (channel.stderr.trim())
+                console.warn(`PiRpcRuntime: Pi said this while locating conversation ${conversation.id}: ${channel.stderr.trim()}`);
+        }
+        catch (error) {
+            if (child.exitCode === null && child.pid !== undefined)
+                await killTree(child.pid);
+            await new Promise((resolve) => { child.once("exit", resolve); setTimeout(resolve, 5000); });
+            throw error instanceof Error ? error : new Error(`无法向 Pi 询问会话文件：${String(error)}`);
+        }
+        // The lookup Pi is holding open is finished; it is killed BEFORE the file is touched, for the same
+        // reason `answer()` kills before returning: a process still tearing down can still be appending.
+        if (child.exitCode === null && child.pid !== undefined)
+            await killTree(child.pid);
+        await new Promise((resolve) => { child.once("exit", resolve); setTimeout(resolve, 5000); });
+        if (!sessionFile)
+            throw new Error("Pi 没有报告这个会话的记录文件，已放弃，没有改动任何文件。");
+        const exists = await stat(sessionFile).catch(() => undefined);
+        // Measured, not guessed: Pi answers `get_state` with the path it WOULD use even for a session it has
+        // just created, and that path does not exist until a message has been sent
+        // (`session-manager.ts:1160-1170`). So "reported but absent" is the ordinary reading of "this
+        // conversation has no Pi history yet", and truncating nothing is the correct outcome - but it is
+        // reported, because the alternative is a revert that appears to work and changes nothing.
+        if (!exists?.isFile())
+            throw new Error(`Pi 还没有为这个会话建立记录文件（${sessionFile}），没有可以回退的历史。`);
+        const result = await truncateSessionFile(sessionFile, boundaryEntryId, conversation.id);
+        return { sessionFile, linesKept: result.linesKept, entriesDropped: result.entriesDropped };
+    }
+    /**
+     * Copies Pi's own transcript for one conversation into a second, independent file under a new id.
+     *
+     * THE SAME THREE STEPS AS REVERT, IN THE SAME ORDER, AND FOR THE SAME REASONS: refuse a live turn, ask Pi
+     * which file it uses rather than scanning the directory (probe B measured that a directory scan resolves
+     * the wrong file or a nonexistent one with no error, and that Pi invents an empty session under an id it
+     * cannot find), kill that Pi BEFORE touching anything on disk, and check the file's header against the
+     * conversation being forked before a byte is written. Every one of those paragraphs above still applies
+     * here word for word, because it is the same machinery pointed the other way: revert cuts a file in
+     * place, fork copies a file beside it.
+     *
+     * ============================ WHAT A FORK COPIES ============================
+     * The file, byte for byte, with two header fields changed (`id`, `parentSession` - see `forkSessionFile`).
+     * Entry ids are NOT renumbered, so every message recorded on the source keeps a `piEntryId` that is valid
+     * in the fork too, which is what keeps REVERT working inside a forked conversation.
+     * =============================================================================
+     *
+     * WHAT A FORK DOES NOT COPY, and both omissions are deliberate:
+     *
+     * - **Sub-agent runs.** `SubagentRun.conversationId` points at the conversation that dispatched it, and
+     *   research pitfall 7 is that truncating or duplicating a transcript leaves those records orphaned. A
+     *   forked conversation shows the messages but no child cards from before the fork: the children belong to
+     *   the conversation that started them, they are not listed anywhere once their parent has copied their
+     *   words, and a card in the fork that could not be stopped from the fork would be worse than no card.
+     * - **Queued messages.** Same argument, and narrower: a waiting message belongs to the run in progress,
+     *   and a run is not copied.
+     *
+     * THE EMPTY-CONVERSATION CASE IS NOT AN ERROR. A conversation with no messages has no Pi file at all -
+     * `SessionManager._persist` only creates one once a session holds a message (`:1160-1170`) - so there is
+     * nothing to copy and the fork is a copy of `state.json` alone. That is checked BEFORE any Pi is spawned,
+     * so forking a fresh conversation costs nothing and cannot fail. The converse is refused rather than
+     * tolerated: messages in `state.json` with no Pi file means the two histories were ALREADY out of step,
+     * and copying that into a second conversation would make the disagreement permanent and multiply it.
+     */
+    async fork({ conversation, cwd, forkedConversationId }) {
+        if (this.runs.has(conversation.id))
+            throw new Error("这个会话还有一轮任务在跑，先停止它再分叉");
+        if (!conversation.messages.length)
+            return { entriesCopied: 0 };
+        if (!this.pi.found)
+            throw new Error(this.pi.reason);
+        const childCwd = resolve(cwd);
+        const info = await stat(childCwd).catch(() => undefined);
+        if (!info?.isDirectory())
+            throw new Error(`工作区目录不存在或不是目录，无法在其中找到这个会话的 Pi 记录：${childCwd}`);
+        await mkdir(this.sessionDir, { recursive: true });
+        // The same lookup spawn as `revert`, and the same reason for leaving the agent flags off: this child
+        // sends no prompt and must leave nothing behind.
+        const child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", this.sessionDir, "--session-id", conversation.id], {
+            cwd: childCwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: process.platform === "win32",
+        });
+        let sessionFile;
+        try {
+            const channel = new RpcChannel(child);
+            const state = await channel.request({ id: "fork_state", type: "get_state" }, LOOKUP_COMMAND_TIMEOUT_MS);
+            if (state.success === false)
+                throw new Error(`Pi 没有回答会话状态：${state.error ?? "未说明原因"}`);
+            const data = state.data;
+            if (typeof data?.sessionId === "string" && data.sessionId !== conversation.id)
+                throw new Error(`Pi 打开的会话是 ${JSON.stringify(data.sessionId)}，不是要分叉的 ${JSON.stringify(conversation.id)}。已放弃，没有复制任何文件。`);
+            if (typeof data?.sessionFile === "string" && data.sessionFile)
+                sessionFile = data.sessionFile;
+            if (channel.stderr.trim())
+                console.warn(`PiRpcRuntime: Pi said this while locating conversation ${conversation.id} for a fork: ${channel.stderr.trim()}`);
+        }
+        catch (error) {
+            if (child.exitCode === null && child.pid !== undefined)
+                await killTree(child.pid);
+            await new Promise((resolve) => { child.once("exit", resolve); setTimeout(resolve, 5000); });
+            throw error instanceof Error ? error : new Error(`无法向 Pi 询问会话文件：${String(error)}`);
+        }
+        if (child.exitCode === null && child.pid !== undefined)
+            await killTree(child.pid);
+        await new Promise((resolve) => { child.once("exit", resolve); setTimeout(resolve, 5000); });
+        if (!sessionFile)
+            throw new Error("Pi 没有报告这个会话的记录文件，已放弃，没有复制任何文件。");
+        const exists = await stat(sessionFile).catch(() => undefined);
+        // Reached only when `state.json` HAS messages, so "reported but absent" cannot be the ordinary
+        // no-history-yet reading here - it means the two files have already diverged, and the refusal says so.
+        if (!exists?.isFile())
+            throw new Error(`这个会话在 Super Pi 里有 ${conversation.messages.length} 条消息，但 Pi 的记录文件不存在（${sessionFile}）。两份记录已经不一致，拒绝分叉——否则新会话会带着一份对不上的历史出生。`);
+        // Named after the new id, exactly the way Pi names its own (`${timestamp}_${sessionId}.jsonl`,
+        // `session-manager.ts:1673`), so a directory listing sorts and reads the way Pi's would. The timestamp
+        // is the fork's, not the source's: the file header keeps the SOURCE timestamp verbatim (it is history),
+        // while the filename carries when this copy was made, which is what makes the ordering of a directory
+        // full of forks mean anything.
+        const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+        const target = join(this.sessionDir, `${stamp}_${forkedConversationId}.jsonl`);
+        const result = await forkSessionFile(sessionFile, target, conversation.id, forkedConversationId);
+        return { sessionFile: target, entriesCopied: result.entriesCopied };
+    }
+    /**
+     * Delivers one Extension UI request. One-way methods are pushed to the host and never replied to
+     * (Pi holds no pending entry, so a response would resolve nothing). Blocking methods are handed to
+     * the host and this call is awaited, so Pi stays blocked exactly as long as the human takes.
+     */
+    async handleExtensionUi(record, child, host, run) {
+        const request = describeExtensionUiRequest(record);
+        if (!request) {
+            console.warn(`PiRpcRuntime: extension_ui_request method=${JSON.stringify(record.method ?? null)} id=${JSON.stringify(record.id ?? null)} is not one of Pi's nine Extension UI methods - consumed without reply.`);
+            return;
+        }
+        const reply = (response) => { if (child.killed || child.stdin.destroyed)
+            return; child.stdin.write(`${JSON.stringify(response)}\n`); };
+        if (!request.blocking) {
+            // Deliberately not awaited: these five are fire-and-forget in Pi, and awaiting would stall the
+            // drain loop on a UI that already told us it wants no reply.
+            try {
+                host?.notify(request);
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: extension_ui notify for ${request.method} id=${request.requestId} threw in the host: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+            return;
+        }
+        if (run.seen.has(request.requestId)) {
+            console.warn(`PiRpcRuntime: extension_ui_request method=${request.method} id=${request.requestId} arrived twice - second copy consumed without reply.`);
+            return;
+        }
+        run.seen.add(request.requestId);
+        if (!host) {
+            // No human can be asked, so the honest reply is "cancelled". Auto-answering with options[0] or
+            // confirmed:false would look to Pi exactly like a decision, and the user would never learn a
+            // question was asked of them.
+            console.warn(`PiRpcRuntime: extension_ui_request method=${request.method} id=${request.requestId} has no UI host, so nobody can answer it - cancelled rather than answering on the user's behalf.`);
+            reply({ type: "extension_ui_response", id: request.requestId, cancelled: true });
+            return;
+        }
+        const cancelled = { cancelled: true };
+        let answer;
+        try {
+            answer = await Promise.race([host.ask(request), run.aborted.then(() => cancelled), run.exited.then(() => cancelled)]);
+        }
+        catch (error) {
+            console.warn(`PiRpcRuntime: extension_ui_request method=${request.method} id=${request.requestId} host failed (${error instanceof Error ? error.message : "unknown error"}) - cancelled.`);
+            answer = cancelled;
+        }
+        reply(buildExtensionUiResponse(request, answer));
+    }
+    async stop(conversationId) { const run = this.runs.get(conversationId); if (run && !run.child.killed)
+        run.child.stdin.write(`${JSON.stringify({ id: "abort", type: "abort" })}\n`); }
+    /**
+     * Injects one message into the Pi process that is running right now, at its next turn boundary.
+     *
+     * `steer` and NOT `follow_up`, and NOT `prompt` with a `streamingBehavior`. The three are not
+     * interchangeable and the difference is the whole feature:
+     *
+     * - `steer` is drained at `agent-loop.ts:295`, after `turn_end` and therefore after the current
+     *   assistant message's WHOLE tool-call batch has finished, before the next LLM request. The agent
+     *   stops doing what it was doing at the next boundary instead of at the end of the task. That is
+     *   "插队", and its granularity is a tool BATCH - a long single tool call is not interruptible,
+     *   because Pi offers no preemption.
+     * - `follow_up` is drained at `agent-loop.ts:302`, only once the agent has stopped on its own.
+     * - `prompt` would start a turn, which is the thing that must NOT happen here: this conversation
+     *   already has a turn in flight, and starting a second one is the two-writers-one-session bug.
+     *
+     * NO `set_follow_up_mode` / `set_steering_mode` IS EVER SENT, and that is a hard rule rather than a
+     * default. Both go through `AgentSession.set*Mode`, which mutates `SettingsManager`'s global scope and
+     * calls `save()` (`settings-manager.ts:857-871`), writing to the user's Pi `settings.json`. A host that
+     * merely wanted a different queue depth would permanently rewrite the user's Pi configuration. Pi's
+     * default is already `one-at-a-time` (`agent.ts:247-248`), which is the semantics this wants: one
+     * queued message consumed per boundary.
+     *
+     * REJECTS rather than reporting success when there is no live child, and when Pi does not answer in
+     * time. The caller keeps the message cancellable in the first case because it provably reached no
+     * model; in the second the outcome is genuinely unknown and a `sending` state says so.
+     */
+    async steer(conversationId, message, images) {
+        const run = this.runs.get(conversationId);
+        if (!run)
+            throw new Error(`会话 ${conversationId} 现在没有正在运行的 Pi 进程，无法插队；这条消息仍在队列里，可以等下一轮或取消。`);
+        if (run.child.exitCode !== null || run.child.killed || run.child.stdin.destroyed)
+            throw new Error(`会话 ${conversationId} 的 Pi 进程已经结束，无法插队；这条消息仍在队列里。`);
+        const id = `steer_${++this.steerSeq}`;
+        const imagePayloads = this.options.uploadsDir && images?.length
+            ? await loadConversationImages(this.options.uploadsDir, conversationId, images)
+            : undefined;
+        const answer = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingSteers.delete(id);
+                // NOT rolled back to `queued` here, and the distinction matters. The text is already in Pi's
+                // stdin; Pi may well deliver it at the next boundary, and reporting it as never sent would make
+                // the user see a message they can cancel - and then watch the model act on it anyway.
+                reject(new Error(`Pi 在 ${STEER_COMMAND_TIMEOUT_MS}ms 内没有确认这条插队消息，它可能仍会在下一个工具调用结束时送达；请等这一轮结束再看。`));
+            }, STEER_COMMAND_TIMEOUT_MS);
+            timer.unref();
+            this.pendingSteers.set(id, {
+                resolve: (disposition) => { clearTimeout(timer); resolve(disposition); },
+                reject: (error) => { clearTimeout(timer); reject(error); },
+            });
+        });
+        try {
+            run.channel.write({ id, type: "steer", message, ...(imagePayloads?.length ? { images: imagePayloads } : {}) });
+        }
+        catch (error) {
+            // `write` throws when the pipe is already gone. Settle and unregister here rather than letting a
+            // timeout report a broken stdin ten seconds later as an unexplained silence.
+            const pending = this.pendingSteers.get(id);
+            this.pendingSteers.delete(id);
+            pending?.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+        return answer;
+    }
+    /**
+     * The model/thinking catalog, from Pi, cached.
+     *
+     * Three layers, because a picker opens far more often than Pi can be asked: a TTL cache keyed by
+     * the selection (10 minutes for a good answer, 30 seconds for a failure), an in-flight map so
+     * concurrent callers share one spawn, and - because each read spawns a short-lived Pi that is
+     * killed as soon as it has answered - no long-lived process to keep warm.
+     */
+    async catalog(selection) {
+        const key = catalogKey(selection);
+        const cached = this.catalogs.get(key);
+        const ttl = cached?.value.source === "pi" ? CATALOG_TTL_MS : CATALOG_FAILURE_TTL_MS;
+        if (cached && Date.now() - cached.at < ttl)
+            return cached.value;
+        const inFlight = this.pendingCatalogs.get(key);
+        if (inFlight)
+            return inFlight;
+        const pending = this.readCatalog(selection, key).finally(() => this.pendingCatalogs.delete(key));
+        this.pendingCatalogs.set(key, pending);
+        return pending;
+    }
+    /**
+     * Asks one throwaway Pi for its model list, its thinking levels and its own current selection.
+     *
+     * The three commands are written back to back and only then awaited, so Pi works on them in
+     * parallel - measured at 394ms for all three, against 714ms for the slowest one alone. A Pi
+     * scoped to one conversation's model needs `set_model` FIRST and alone, because thinking levels are
+     * a property of the selected model, not of Pi's default.
+     */
+    async readCatalog(selection, key) {
+        const unavailable = (error) => {
+            console.warn(`PiRpcRuntime: catalog for ${key} could not be read: ${error}`);
+            return { source: "unavailable", models: [], levels: [], fetchedAt: new Date().toISOString(), error };
+        };
+        // Catalog probes get their OWN session directory and a fixed session id: they must never write
+        // into a conversation's transcript, and a fixed id means a refresh reuses one file instead of
+        // leaving a new one behind on every model switch.
+        const directory = join(this.sessionDir, "catalog");
+        await mkdir(directory, { recursive: true });
+        // Same resolution, same refusal, one reason: a picker that cannot be filled because Pi is not
+        // installed must say so in the picker's own error, not report the spawn's ENOENT as Pi's answer.
+        if (!this.pi.found)
+            return unavailable(this.pi.reason);
+        let child;
+        try {
+            child = spawn(shellQuote(this.pi.command), ["--mode", "rpc", "--session-dir", directory, "--session-id", "catalog"], { cwd: directory, stdio: ["pipe", "pipe", "pipe"], shell: process.platform === "win32" });
+        }
+        catch (error) {
+            return unavailable(`could not spawn Pi: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
+        try {
+            const channel = new RpcChannel(child);
+            if (selection?.provider && selection.modelId) {
+                const applied = await channel.request({ id: "catalog_set_model", type: "set_model", provider: selection.provider, modelId: selection.modelId }, CATALOG_COMMAND_TIMEOUT_MS);
+                if (applied.success === false)
+                    throw new Error(applied.error ?? "Pi rejected set_model");
+            }
+            channel.write({ id: "catalog_models", type: "get_available_models" });
+            channel.write({ id: "catalog_levels", type: "get_available_thinking_levels" });
+            channel.write({ id: "catalog_state", type: "get_state" });
+            const models = await channel.waitFor("catalog_models", CATALOG_COMMAND_TIMEOUT_MS, "get_available_models");
+            const levels = await channel.waitFor("catalog_levels", CATALOG_COMMAND_TIMEOUT_MS, "get_available_thinking_levels");
+            const state = await channel.waitFor("catalog_state", CATALOG_COMMAND_TIMEOUT_MS, "get_state");
+            if (models.success === false)
+                throw new Error(models.error ?? "Pi rejected get_available_models");
+            if (levels.success === false)
+                throw new Error(levels.error ?? "Pi rejected get_available_thinking_levels");
+            const options = describeModels(models.data?.models);
+            const levelNames = textList(levels.data?.levels) ?? [];
+            const current = describeModel(state.data?.model);
+            // Narrowed to the three fields ModelSelection declares, because a default is only ever read back
+            // as a button label - the per-model capability fields belong to the list entries, not here.
+            const pick = (model) => (model ? { provider: model.provider, modelId: model.modelId, label: model.label } : undefined);
+            const value = {
+                source: "pi",
+                models: options,
+                levels: levelNames,
+                // Pi's own answer wins. The fallbacks only fire if get_state is missing the model, and they
+                // fall back to Pi's OWN ordering rather than to anything invented here.
+                defaultModel: pick(current) ?? pick(options[0]),
+                defaultThinkingLevel: text(state.data?.thinkingLevel) ?? levelNames[0],
+                fetchedAt: new Date().toISOString(),
+            };
+            if (!value.models.length)
+                return unavailable(`Pi returned no usable models: ${JSON.stringify(models.data?.models)?.slice(0, 200)}`);
+            this.catalogs.set(key, { at: Date.now(), value });
+            return value;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "unknown error";
+            const failed = unavailable(message);
+            this.catalogs.set(key, { at: Date.now(), value: failed });
+            return failed;
+        }
+        finally {
+            // Same rule as answer(): the child is not gone until it is actually gone, because a process
+            // still tearing down still holds a lock on this directory.
+            //
+            // THE 5s BACKSTOP IS NOT OPTIONAL, and the same one already appears twice in this file. The kill
+            // happens first and the `exit` subscription second, so an `exit` that fires in that window is
+            // emitted to nobody and dropped by the EventEmitter - `exitCode` is then updated, but the promise
+            // below never settles. Without the timer that hangs the whole catalog read, so `catalog()` never
+            // returns, so the `workspace.settings` handler never reaches its persist: the 保存 dialog closes
+            // and the setting is silently lost, with no error frame and nothing in the server log. Observed
+            // under load in scripts/workspace-settings-browser.test.mjs, which timed out at 60s with an
+            // accepted command, an empty error channel and an untouched state.json.
+            if (child.exitCode === null && child.pid !== undefined) {
+                if (!child.killed) {
+                    if (process.platform === "win32")
+                        await killTree(child.pid);
+                    else
+                        child.kill();
+                }
+                if (child.exitCode === null)
+                    await new Promise((resolve) => { child.once("exit", resolve); setTimeout(resolve, 5000); });
+            }
+        }
+    }
+}
+/**
+ * Normalizes Pi's `Model[]`, keeping only entries that can actually be sent back as a `set_model`.
+ * Exported so the mapping is testable without a Pi process.
+ *
+ * `imageInput` reads Pi's `input` array, which is where image support is actually declared -
+ * `BaseModel.input: ("text" | "image")[]` at packages/ai/src/types.ts:1124, and Pi's own CLI prints
+ * the very same test as its "images" column (cli/list-models.ts:71, `m.input.includes("image")`).
+ * Copying Pi's predicate rather than inventing one is the point: if Pi ever renames the value or
+ * adds a third modality, Pi's column and this badge change together.
+ *
+ * A MISSING OR MALFORMED `input` READS AS FALSE, and that direction is deliberate. The field's
+ * failure mode is a silent one in both directions - Pi's RPC reader does no schema validation
+ * (rpc-mode.ts:750-783) - so a model with no `input` at all could be a Pi too old to have the
+ * concept, and answering "supports images" for it would invite a picture the model cannot see.
+ * Announcing a capability that turns out to be absent costs the user a confusing turn; declining to
+ * announce one that is present costs them an unlabelled model. Only the first is worth guessing on.
+ */
+export function describeModel(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const model = value;
+    if (typeof model.provider !== "string" || model.provider === "" || typeof model.id !== "string" || model.id === "")
+        return undefined;
+    const label = typeof model.name === "string" && model.name !== "" ? model.name : model.id;
+    // Anything that is not an array of strings is treated as absent rather than searched with
+    // `.includes`, which would throw on a string. Pi's own union makes this unreachable today; the
+    // check is here because this runs against a field read off the wire from a process that does no
+    // validation of its own.
+    const input = Array.isArray(model.input) ? model.input.filter((value) => typeof value === "string") : [];
+    return { provider: model.provider, modelId: model.id, label, detail: `${model.provider}/${model.id}`, reasoning: model.reasoning === true, contextWindow: typeof model.contextWindow === "number" ? model.contextWindow : 0, imageInput: input.includes("image") };
+}
+export function describeModels(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(describeModel).filter((model) => model !== undefined);
+}