@evandu/super-pi 0.1.70 → 0.1.71

package/dist/server/runtime.js

@@ -1,7 +1,11 @@
 import { spawn } from "node:child_process";
+import { RpcChannel } from "./rpc-channel.js";
+export { RpcChannel } from "./rpc-channel.js";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { mkdir, stat } from "node:fs/promises";
+import { forkSessionFile, truncateSessionFile } from "./session-repository.js";
+export { forkSessionFile, truncateSessionFile } from "./session-repository.js";
 import { resolve, join } from "node:path";
 import { agentSpawnArgs, readAgents } from "./agents.js";
 import { TASK_CAPABILITY_ENV, mintCapability, releaseCapability } from "./capability.js";
@@ -10,6 +14,11 @@ import { TASK_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_END
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
 import { describeToolCall, describeToolCallArgs, describeToolCallInProgress, extractPartialResultText, extractToolResultText, readQuestionCall } from "./tool-calls.js";
+const traceLatency = (conversationId, phase, startedAt, extra = "") => {
+    if (process.env.SUPER_PI_TRACE_LATENCY !== "1")
+        return;
+    console.warn(`[super-pi latency] conversation=${conversationId} phase=${phase} elapsedMs=${Math.round(performance.now() - startedAt)}${extra ? ` ${extra}` : ""}`);
+};
 /** A steer that provably never reached Pi; the caller may safely use the next turn instead. */
 export class SteerUnavailableError extends Error {
 }
@@ -33,6 +42,15 @@ export class WelcomeRuntime {
         return { source: "unavailable", models: [], levels: [], fetchedAt: new Date().toISOString(), error: "Welcome runtime has no Pi session to ask" };
     }
 }
+/**
+ * One record off Pi's JSONL stdout. Deliberately a loose shape with optional fields: Pi emits a wide,
+ * open-ended family of session events, and a type that enumerated all of them would break on the next
+ * Pi release rather than on the next behaviour change.
+ *
+ * Exported so another consumer of `RpcChannel` - the sub-agent supervisor - can read the same records
+ * through the same channel instead of writing a second JSONL reader. Every field below is optional, so
+ * a reader must check before using one.
+ */
 /**
  * Reads Pi's `queue_update` payload, or returns undefined when the record is not one.
  *
@@ -113,111 +131,6 @@ export function buildExtensionUiResponse(request, answer) {
         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.
  *
@@ -257,250 +170,7 @@ export function killTree(pid) {
         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, beforeBoundary = false) {
-    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}`);
-    let boundary = boundaryEntryId === "" ? 0 : parsed.findIndex((entry, index) => index > 0 && entry?.id === boundaryEntryId);
-    if (boundary < 0)
-        throw new Error(`在这份 Pi 会话记录里找不到要保留的那条消息（entry ${JSON.stringify(boundaryEntryId)}）。这条消息可能是更早的版本写的，Super Pi 当时没有记下它对应 Pi 的哪一条。`);
-    const expectedLastId = beforeBoundary ? parsed[boundary - 1]?.id : parsed[boundary]?.id;
-    if (beforeBoundary)
-        boundary -= 1;
-    // Fail closed: a boundary of -1 here means "revert to before the FIRST entry", which would write an
-    // empty session file. The verification below would pass vacuously (0 !== 0 is false), so the refusal
-    // must happen here rather than be trusted to a check that cannot fire.
-    if (boundary < 0)
-        throw new Error(`回退点在第一条消息之前，截断会得到一个空会话文件，拒绝回退：${path}`);
-    // 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 !== expectedLastId || boundary + 1 < 1) {
-        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 };
-}
+// Session-file mutation and validation live behind this boundary; runtime only locates Pi sessions.
 /** 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. */
@@ -725,7 +395,9 @@ export class PiRpcRuntime {
             [TASK_CAPABILITY_ENV]: mintCapability(conversationId),
         };
     }
-    async *answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, images, memoryReview, memorySourceConversationId }) {
+    async *answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, images, memoryReview, memorySourceConversationId }) {
+        const latencyStartedAt = performance.now();
+        traceLatency(conversation.id, "answer.begin", latencyStartedAt);
         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
@@ -788,6 +460,7 @@ export class PiRpcRuntime {
         });
         const channel = new RpcChannel(child);
         this.runs.set(conversation.id, { child, channel });
+        traceLatency(conversation.id, "pi.spawned", latencyStartedAt, `pid=${child.pid ?? "unknown"}`);
         // Same guard as subagents.ts: a destroyed stdin throws synchronously on write, and an abort
         // listener that throws inside a listener would surface as an unhandled error instead of a cancel.
         const abort = () => {
@@ -835,16 +508,21 @@ export class PiRpcRuntime {
             }
             // Resumed Pi sessions can carry a different model than the global default.
             // Check the real get_state result as well, before any prompt reaches the model.
-            if (this.modelValidator) {
+            if (this.modelValidator || onSessionFile) {
                 const actual = await channel.request({ id: "policy_state", type: "get_state" }, SESSION_COMMAND_TIMEOUT_MS);
                 const model = actual.data?.model;
-                await this.modelValidator(validationId, model?.provider && model.id ? { provider: model.provider, modelId: model.id, label: model.name ?? model.id } : undefined);
+                await this.modelValidator?.(validationId, model?.provider && model.id ? { provider: model.provider, modelId: model.id, label: model.name ?? model.id } : undefined);
+                const sessionFile = actual.data?.sessionFile;
+                if (typeof sessionFile === "string" && sessionFile)
+                    await onSessionFile?.(sessionFile);
             }
             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 } : {}) });
+            traceLatency(conversation.id, "prompt.sent", latencyStartedAt);
             let settled = false;
+            let firstPiRecord = true;
             // 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.
@@ -875,6 +553,10 @@ export class PiRpcRuntime {
                     const record = await channel.next(100);
                     if (!record)
                         break;
+                    if (firstPiRecord) {
+                        firstPiRecord = false;
+                        traceLatency(conversation.id, "pi.first-record", latencyStartedAt, `type=${record.type}`);
+                    }
                     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
@@ -1002,7 +684,6 @@ export class PiRpcRuntime {
                     }
                     if (record.type === "message_update") {
                         const event = record.assistantMessageEvent;
-                        console.log(`[runtime] message_update event.type=${JSON.stringify(event?.type)}`);
                         // text_delta is what drives the visible answer, and toolcall_start/delta/end are what make a
                         // call VISIBLE WHILE IT IS BEING WRITTEN.
                         //
@@ -1031,14 +712,18 @@ export class PiRpcRuntime {
                             // between a `read`'s path and a `bash`'s command.
                             const name = toolNames.get(event.contentIndex) ?? "";
                             argumentText.set(event.contentIndex, `${argumentText.get(event.contentIndex) ?? ""}${delta}`);
-                            const detail = describeToolCallInProgress(name, argumentText.get(event.contentIndex) ?? "");
-                            onToolPreparing?.({ contentIndex: event.contentIndex, name, ...(delta ? { delta } : {}), ...(detail ? { detail } : {}) });
+                            // WHAT ARRIVES IS A FRAGMENT; WHAT IS HANDED ON IS THE TEXT SO FAR. The same field on the
+                            // caller's side receives `tool_execution_update`'s output, and Pi sends THAT already
+                            // accumulated - so a caller storing both verbatim would have to append one kind of text and
+                            // replace the other. Accumulating here, where the fragments already are, gives it one kind.
+                            const text = argumentText.get(event.contentIndex) ?? "";
+                            const detail = describeToolCallInProgress(name, text);
+                            onToolPreparing?.({ contentIndex: event.contentIndex, name, ...(text ? { live: text } : {}), ...(detail ? { detail } : {}) });
                         }
                         else if (event?.type === "thinking_delta")
                             onThinking?.(typeof event.delta === "string" ? event.delta : "");
                         else {
                             noteUnhandled(`message_update:${JSON.stringify(event?.type ?? "(missing)")}`);
-                            console.log(`[runtime] message_update not matched: event.type=${JSON.stringify(event?.type)}`);
                         }
                         continue;
                     }
@@ -1055,12 +740,13 @@ export class PiRpcRuntime {
                         throw new Error(`Pi extension error in ${record.extensionPath ?? "unknown path"} (${record.event ?? "unknown event"}): ${record.error ?? "unknown error"}`);
                     }
                     if (record.type === "agent_settled") {
+                        traceLatency(conversation.id, "pi.settled", latencyStartedAt);
                         settled = true;
                         continue;
                     }
                     noteUnhandled(`type ${JSON.stringify(record.type ?? "(missing type)")}`);
                 }
-                if (!settled && child.exitCode !== null)
+                if (!settled && channel.closed)
                     throw new Error(`Pi RPC exited before settling (code ${child.exitCode}). ${channel.stderr.trim()}`);
             }
             for (const [key, count] of repeats)
@@ -1209,6 +895,21 @@ export class PiRpcRuntime {
             throw new Error("这个会话还有一轮任务在跑，先停止它再回退");
         if (!this.pi.found)
             throw new Error(this.pi.reason);
+        // Normal path: this exact worker already asked Pi for get_state before its prompt was sent, so reuse
+        // that locator. `truncateSessionFile` below still proves the header belongs to this conversation and
+        // validates the requested boundary and parent chain before a byte is changed. The cache removes an
+        // otherwise pointless second Pi startup from every ordinary revert.
+        const cached = conversation.piSessionFile;
+        if (cached) {
+            const exists = await stat(cached).catch(() => undefined);
+            if (exists?.isFile()) {
+                const result = await truncateSessionFile(cached, boundaryEntryId, conversation.id, beforeBoundary);
+                return { sessionFile: cached, linesKept: result.linesKept, entriesDropped: result.entriesDropped };
+            }
+        }
+        // Compatibility fallback for conversations created before the live-worker locator existed, or a
+        // transcript that was moved since the last turn. This retains Pi's authoritative lookup rather than
+        // guessing from filenames.
         const childCwd = resolve(cwd);
         const info = await stat(childCwd).catch(() => undefined);
         if (!info?.isDirectory())
@@ -1305,6 +1006,13 @@ export class PiRpcRuntime {
             return { entriesCopied: 0 };
         if (!this.pi.found)
             throw new Error(this.pi.reason);
+        const cached = conversation.piSessionFile;
+        if (cached && (await stat(cached).catch(() => undefined))?.isFile()) {
+            const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+            const target = join(this.sessionDir, `${stamp}_${forkedConversationId}.jsonl`);
+            const result = await forkSessionFile(cached, target, conversation.id, forkedConversationId);
+            return { sessionFile: target, entriesCopied: result.entriesCopied };
+        }
         const childCwd = resolve(cwd);
         const info = await stat(childCwd).catch(() => undefined);
         if (!info?.isDirectory())

package/dist/server/session-repository.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 declare function truncateSessionFile(path: string, boundaryEntryId: string, expectedSessionId: string, beforeBoundary?: boolean): Promise<{
+    linesKept: number;
+    entriesDropped: number;
+}>;
+/**
+ * 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 declare function forkSessionFile(sourcePath: string, targetPath: string, expectedSessionId: string, targetSessionId: string): Promise<{
+    entriesCopied: number;
+}>;