@evandu/super-pi 0.0.0-stage → 0.1.0

package/dist/server/store.js

@@ -0,0 +1,1121 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { normalizeTodos } from "./task-tool.js";
+function id(prefix) { return `${prefix}_${crypto.randomUUID()}`; }
+/** Mints the id a forked conversation will have, BEFORE its Pi transcript exists.
+ *
+ *  Exported because the ordering demands it and no other arrangement provides it. Pi's copied file's header
+ *  `id` has to BE the new conversation's id (it is what `findLocalSessionByExactId` matches), so the id has
+ *  to be decided before the file is written; and the conversation must not exist until the file is safely on
+ *  disk, or a failed write would leave a conversation whose model context is silently empty. The runtime is
+ *  therefore handed the id and the store is handed the same one back. See `ForkRequest.forkedConversationId`. */
+export function newConversationId() { return id("conversation"); }
+function now() { return new Date().toISOString(); }
+const DEFAULT_CONVERSATION_TITLE = "\u65b0\u4f1a\u8bdd";
+/** Whether a value survives a `new Date()` round-trip. `createdAt` is typed string, but state.json only
+ *  has to be JSON to be read back: an old build, an import, or a hand edit owes TypeScript nothing. */
+function parseableTimestamp(value) {
+    return typeof value === "string" && value.length > 0 && !Number.isNaN(new Date(value).getTime());
+}
+/**
+ * The server's own guard, so a poisoned message can only be rendered safe ONCE, at the boundary where
+ * outside data enters: `Store.open` reads state.json blind (`JSON.parse ... as AppState`), so a message
+ * whose `createdAt` is missing or unparseable would otherwise flow into every snapshot and every
+ * broadcast untouched. Why the store and not the client alone: the client's `time()` guard makes one bad
+ * stamp render without crashing, but by then the invalid value has already propagated through state
+ * broadcasts and persisted copies of it keep resurfacing on every restart. Normalizing here - anchored on
+ * the conversation's own updatedAt, falling back to the load instant - keeps the on-disk file untouched
+ * (the next normal persist rewrites it clean) while every snapshot handed out satisfies the declared
+ * type from this point on. The conversation's `updatedAt` was deliberately NOT audited: it feeds string
+ * sorting and a `relativeTime` that already degrades, so a bad one loses at most a sidebar label, and the
+ * type stays required so callers cannot learn to omit it.
+ *
+ * Never rebuilds conversation objects: the normalization is field-deep, so old state files load with no
+ * migration step, exactly like archivedAt and the agent/model keys do.
+ */
+function normalizeMessageTimestamps(state) {
+    const fallback = now();
+    for (const conversation of state.conversations ?? []) {
+        const anchor = parseableTimestamp(conversation.updatedAt) ? conversation.updatedAt : fallback;
+        for (const message of conversation.messages ?? []) {
+            if (parseableTimestamp(message?.createdAt))
+                continue;
+            if (message)
+                message.createdAt = anchor;
+        }
+    }
+    return state;
+}
+/**
+ * Why a run that was still `running` when the file was read is failed rather than left alone.
+ *
+ * Chinese because it lands in the run's `error`, which the card shows to a person; the surrounding
+ * `console.warn` is the developer-facing half of the same fact. It names the cause rather than just the
+ * verdict, because "failed" on its own leaves the reader guessing whether the child crashed, the run
+ * was cut short, or the server simply went away - and those have different fixes.
+ */
+const ORPHANED_RUN_ERROR = "服务器上次退出时这个子进程仍在运行；进程已随服务器消失，本次运行被标记为失败。";
+/**
+ * Startup reconciliation: every run the previous process left `running` is an orphan.
+ *
+ * The reasoning is the same one that applies to any work claimed as in-flight by a process that no
+ * longer exists - the record is a CLAIM, and the claim cannot still be true when nothing is running.
+ * `status` is the only thing that can be wrong about such a record, so it is the only thing changed;
+ * `output`, `usage` and `sessionId` were written before the crash and are still true. `finishedAt` is
+ * the load instant rather than a guess at when the child died, because the file records no death time
+ * and inventing one would be a worse lie than an honest "we noticed this now".
+ *
+ * Mutated in place, like `normalizeMessageTimestamps`: the on-disk file is rewritten by the single
+ * persist `open` performs when this returns a non-empty list, and a state file written before sub-agent
+ * runs existed simply gains the key with no migration step.
+ *
+ * Returns the orphans so the caller can announce each one - a run that failed while nobody was watching
+ * is invisible otherwise, and the user who dispatched it deserves to learn what happened to it.
+ */
+function reconcileSubagentRuns(state) {
+    // `Array.isArray` rather than `?? []`: `state.json` is read blind, so a hand edit or an older build
+    // can leave anything here, and a truthy non-array would then make every iteration below throw on the
+    // first unrelated key of an unrelated failure.
+    const runs = Array.isArray(state.subagentRuns) ? state.subagentRuns : [];
+    state.subagentRuns = runs;
+    const orphaned = [];
+    for (const run of runs) {
+        if (!run || run.status !== "running")
+            continue;
+        run.status = "failed";
+        run.error = ORPHANED_RUN_ERROR;
+        run.finishedAt = now();
+        orphaned.push(run);
+    }
+    return orphaned;
+}
+/**
+ * Why a conversation the previous process left `running` is failed, in the same spirit and for the same
+ * audience as `ORPHANED_RUN_ERROR`: this lands in a field the chat pane renders verbatim, so it names the
+ * cause, states the verdict, and says what to do next. "failed" alone would leave the reader unable to
+ * tell a crash from a stop, and unable to tell whether their work was lost or is still worth resuming.
+ */
+const ORPHANED_CONVERSATION_ERROR = "服务器上次退出时这次任务还在运行，没有跑完就被中断了，已标记为失败。可以直接重新发送任务继续。";
+/**
+ * Startup reconciliation for ORDINARY conversations - the same treatment `reconcileSubagentRuns` gives a
+ * child's run, on the same reasoning: `status: "running"` is a CLAIM that some process was working on this,
+ * and the claim cannot still be true when the process that made it no longer exists. Without this, a server
+ * killed mid-turn leaves a conversation that spins in the UI forever, never settles, and cannot be closed.
+ *
+ * ARCHIVED CONVERSATIONS ARE RECONCILED TOO, and that is a decision rather than an oversight.
+ * `archiveConversation` refuses a running conversation, so an archived one carrying `running` is only
+ * reachable from an older build, a hand edit, or a file copied between installs - which makes it rare, not
+ * impossible. Skipping them would be strictly worse than reconciling them: the row would sit quiet in the
+ * Archived group until someone pressed restore, at which point the SAME unkillable spinner reappears on a
+ * conversation the user had every reason to believe was closed. Reconciling costs one status write and one
+ * reason field on a row nobody is looking at, and it removes a landmine rather than arming one.
+ *
+ * `updatedAt` is deliberately NOT touched, and this is the one place where copying the sub-agent sweep
+ * field-for-field would be wrong: `SubagentRun.finishedAt` is a field that EXISTS to be stamped with the
+ * moment an orphan was noticed, while a conversation has no such field, and `updatedAt` is the opposite of
+ * one - it is the sidebar's recency key. Bumping it would teleport every interrupted conversation to the
+ * top of the list at once, so repairing the file would reorder the UI as a side effect of a repair the user
+ * did not ask for. `archiveConversation` and `renameConversation` both decline to touch it for the same
+ * reason. Repair is not activity.
+ *
+ * `messages` is untouched for the same reason `output`/`usage` are untouched over there: everything in them
+ * was written before the crash and is still true. Only the claim, and the reason the claim is now false, are
+ * wrong.
+ *
+ * Mutated in place and persisted by `open`, exactly like the sub-agent sweep, so a state.json written before
+ * conversations were reconciled simply gains the reason with no migration step, and a record repaired on one
+ * boot is not repaired again on the next.
+ */
+function reconcileConversations(state) {
+    // `Array.isArray` rather than `?? []`, for precisely the reason `reconcileSubagentRuns` does it: state.json
+    // is read blind, and a truthy non-array left by a hand edit would make every iteration below throw on the
+    // first unrelated key of an unrelated failure.
+    const conversations = Array.isArray(state.conversations) ? state.conversations : [];
+    state.conversations = conversations;
+    const orphaned = [];
+    for (const conversation of conversations) {
+        if (!conversation || conversation.status !== "running")
+            continue;
+        conversation.status = "failed";
+        conversation.error = ORPHANED_CONVERSATION_ERROR;
+        orphaned.push(conversation);
+    }
+    return orphaned;
+}
+/**
+ * How many SETTLED sub-agent runs `state.json` keeps, so the file cannot grow without bound.
+ *
+ * WHY A BOUND IS NEEDED AT ALL. `beginSubagentRun` unshifts and nothing ever removes a run, so a long
+ * session that dispatches sub-agents - which is exactly what this feature encourages - would otherwise
+ * accumulate records forever. The file is not a log on disk that costs nothing to grow: it is rewritten
+ * in full on EVERY text delta of EVERY running child (see `SubagentRunRecorder.publish`), cloned into
+ * the browser on every `state` broadcast, and read at startup. A run record is bounded but not small -
+ * `output` is the last assistant message, up to the 50 KB cap of §6, plus the task text and one label
+ * per tool call - so an unbounded array makes every one of those operations slower for everybody.
+ *
+ * WHY 100. It has to be big enough that a person can scroll back through a working day without a card
+ * going missing, and small enough that the worst case stays in the range a JSON file and a browser
+ * snapshot handle comfortably. At 100 settled runs, and a deliberately pessimistic 50 KB per output,
+ * the array is ~5 MB; at 1000 it would be ~50 MB, which is enough to be felt as the app hanging on
+ * every broadcast. 100 is roughly a day's worth of sub-agent work for a person using this as a tool
+ * rather than as a load generator, and a run older than that is still recoverable in full through Pi -
+ * the record carries `sessionId`, and `switch_session` or `export_html` reads the real transcript. So
+ * what the bound costs is a scrollback affordance, not history.
+ *
+ * Exported so a test can assert the bound against the same number the store uses rather than
+ * re-deriving it.
+ */
+export const SUBAGENT_RUN_RETENTION = 100;
+/**
+ * Evicts settled runs down to `SUBAGENT_RUN_RETENTION`, newest first.
+ *
+ * TWO RUNS ARE NEVER EVICTED, and both rules exist because eviction is the one operation here that can
+ * destroy evidence:
+ *
+ * 1. Anything still `running`. That row is the CLAIM that startup reconciliation looks for; removing it
+ *    would silently forget a child that is still out there, which is the exact orphan this whole feature
+ *    was built to make recoverable.
+ * 2. Runs of a conversation that still exists and is not archived, until there is nothing else left to
+ *    drop. The alternatives go first because they are the ones nobody is looking at: the conversation
+ *    was archived or deleted, so there is no transcript for the card to sit under and no `state` the
+ *    user is reading. That is why this is not a plain "keep the newest N" slice - the newest N would
+ *    evict an active conversation's run in favour of an archived one's.
+ *
+ * Mutated in place, like the reconciliation above, and never throws: an `archivedAt` that is not a
+ * string counts as archived rather than as a reason to keep the row.
+ */
+function trimSubagentRuns(runs, conversations) {
+    const settled = runs.filter((run) => run?.status !== "running");
+    // Over the bound by at most the number of live runs, so one pass is enough: everything older than
+    // `keep` settled rows is dropped, and live runs were never in that slice to begin with.
+    const excess = settled.length - SUBAGENT_RUN_RETENTION;
+    if (excess <= 0)
+        return;
+    const live = new Set(conversations.filter((conversation) => conversation && typeof conversation.archivedAt !== "string").map((conversation) => conversation.id));
+    const droppableOldestFirst = [...settled].reverse();
+    const doomed = new Set();
+    for (const run of droppableOldestFirst)
+        if (!live.has(run.conversationId))
+            doomed.add(run.id);
+    for (const run of droppableOldestFirst) {
+        if (doomed.size >= excess)
+            break;
+        if (!doomed.has(run.id))
+            doomed.add(run.id);
+    }
+    runs.splice(0, runs.length, ...runs.filter((run) => !doomed.has(run.id)));
+}
+/**
+ * Startup reconciliation for the follow-up queue: an entry the previous process left `sending` goes
+ * back to `queued`.
+ *
+ * `sending` is one claim only: "this text has been written to a live Pi child's stdin as a `steer` and
+ * Pi has not confirmed delivering it". The claim dies with the process that made it, exactly like the
+ * `running` claims above - the Pi that would have delivered it was a child of the server that is no
+ * longer running, so it can never confirm anything now.
+ *
+ * RETURNING IT TO THE QUEUE, RATHER THAN DROPPING IT OR LEAVING IT SENDING, is the only honest third
+ * option:
+ *
+ * - Dropping it would lose a message the user is looking at in their dock, silently and permanently.
+ * - Leaving it `sending` would show a message as "already handed to the agent, cannot be cancelled"
+ *   that in fact never reached any model and can be cancelled - a UI claiming an irreversible fact
+ *   about a reversible state.
+ * - Re-queueing is TRUE: Pi drains steering before its loop can end (`agent-loop.ts:295`), and it
+ *   emits `queue_update` with the item removed before it emits the delivered `message_start`
+ *   (`agent-session.ts:1116-1136`). A delivered steer is therefore already gone from this list before
+ *   `agent_settled` arrives, so anything still `sending` at the end of a turn provably was not
+ *   delivered. Re-queued, the user sees it again and can steer it into the next turn.
+ *
+ * Mutated in place and persisted by `open`, so a queue written by a build that predates it, or by a
+ * hand edit, is repaired on the first boot rather than read as permanently stuck.
+ *
+ * `changed` is reported separately from `recovered` because they are different repairs with different
+ * consequences: a `recovered` row is a message the user can see and therefore needs announcing, while a
+ * DROPPED row is a broken file that has to be rewritten or it is re-dropped on every single boot. Neither
+ * is worth a persist on its own account - `open` persists once, for all the sweeps together.
+ */
+function reconcileQueuedMessages(state) {
+    // `Array.isArray` rather than `?? []`, for the same reason the two sweeps above do it: state.json is
+    // read blind, and a truthy non-array left by a hand edit would make every call below throw.
+    const queue = Array.isArray(state.queuedMessages) ? state.queuedMessages : [];
+    const missing = !Array.isArray(state.queuedMessages);
+    // An entry that is not a usable QueuedMessage is dropped rather than repaired: every field is
+    // load-bearing (the id is what cancel/steer name, the content is what Pi is handed), so a partial
+    // entry has no safe default and keeping it would put `undefined` text on the wire.
+    const usable = queue.filter((item) => Boolean(item) && typeof item?.id === "string" && typeof item?.conversationId === "string" && typeof item?.content === "string" && (item.state === "queued" || item.state === "sending"));
+    state.queuedMessages = usable;
+    const recovered = [];
+    for (const message of usable) {
+        if (message.state !== "sending")
+            continue;
+        message.state = "queued";
+        recovered.push(message);
+    }
+    return { recovered, changed: missing || usable.length !== queue.length };
+}
+/**
+ * Which messages and which sub-agent runs a revert to `messageId` removes.
+ *
+ * THE BOUNDARY IS AN ARRAY INDEX, NEVER A TIMESTAMP. `store.ts` stamps both halves of a turn with
+ * `now()` at millisecond precision, so a user message and the assistant reply after it very often share
+ * one timestamp - the same reason the browser sorts messages with an explicit `seq` tiebreak
+ * (`App.tsx:870`). Sorting by time and cutting there would cut mid-turn at random. `messages` is append
+ * only and nothing ever reorders it, so its order IS the conversation's order.
+ *
+ * WHICH RUNS ARE DOOMED is decided by `startedAt` against the first removed message's `createdAt`, and
+ * that comparison is safe for the same reason the index is: a child can only be dispatched AFTER the user
+ * message of its turn exists, and both stamps come from this one process's clock. A run at or after the
+ * first removed message's stamp was therefore dispatched by a removed turn; one before it belonged to a
+ * turn that survives.
+ *
+ * Throws rather than returning an empty plan, because every caller would otherwise have to invent its
+ * own message for "that message is not in this conversation" - and a revert that silently did nothing is
+ * the failure this whole feature exists to avoid.
+ */
+function planRevert(state, conversationId, messageId) {
+    const conversation = state.conversations.find((item) => item?.id === conversationId);
+    if (!conversation)
+        throw new Error("会话不存在");
+    const boundaryIndex = conversation.messages.findIndex((item) => item?.id === messageId);
+    if (boundaryIndex < 0)
+        throw new Error("要回退的那条消息不在这个会话里");
+    const boundary = conversation.messages[boundaryIndex];
+    if (!boundary?.piEntryId)
+        throw new Error("这条消息没有对应的 Pi 记录，不能作为回退位置。请在它之后的任意一条消息上回退。");
+    const removed = conversation.messages.slice(boundaryIndex + 1);
+    // Unparseable stamps are compared as 0, i.e. "older than everything", which keeps a corrupted run
+    // record ALIVE rather than deleting a child that may still be the user's most recent work. Deleting on a
+    // guess is the irreversible direction; keeping a stale record costs one card that startup reconciliation
+    // already knows how to explain.
+    const firstRemovedAt = removed.length ? Date.parse(removed[0].createdAt) || 0 : Number.POSITIVE_INFINITY;
+    const doomedRunIds = state.subagentRuns
+        .filter((run) => run?.conversationId === conversationId && (Date.parse(run.startedAt) || 0) >= firstRemovedAt)
+        .map((run) => run.id);
+    return { boundaryIndex, boundaryEntryId: boundary.piEntryId, removedMessageIds: removed.map((item) => item.id), doomedRunIds };
+}
+/**
+ * Brings `state.todos` back to a shape the browser can render, on boot.
+ *
+ * THE SAME REASON `reconcileQueuedMessages` EXISTS, and the same three cases, but nothing here RECOVERS
+ * anything: there is no "still running" claim in a todo list to contradict, because the list is not a
+ * record of a running thing - it is a record of what a model last said it was doing. So there is nothing to
+ * reconcile against a fact and nothing to announce; the sweep exists purely because `state.json` is read
+ * blind by `JSON.parse(...) as AppState` and owes nothing to the declared type.
+ *
+ * What it does buy, and it is not nothing:
+ *
+ * - A hand-edited or half-written `todos` (an object, a string, a list holding `null`) is replaced by the
+ *   empty list rather than reaching the sidebar, where `todos.map` would throw inside React's render and
+ *   unmount the whole tree. That is the `.shell` gone / zero messages / one solid #0d111b frame measured in
+ *   `scripts/message-timestamps.test.mjs` for `createdAt`, one field over.
+ * - A `status` the stylesheet has no rule for is coerced to `pending`, so a typo can never render as the
+ *   completed style by falling through every `===` comparison.
+ * - A missing `id` is filled in, which is what stops two identical lines of text sharing one React key.
+ *
+ * `changed` is reported so `open` persists the repair. Unlike the two sweeps beside it, this one has
+ * nothing to warn about on stdout - a repaired todo list is a fixed file, not a fact the user was shown -
+ * so it is the quietest of the three and deliberately so.
+ */
+function reconcileTodos(state) {
+    // Compared as JSON, before and after, rather than with `changed = missing || ...`: the sweep's whole job
+    // is to make the stored shape match `normalizeTodos`, and that is precisely a "did the bytes move"
+    // question. A boolean assembled from a handful of special cases would go stale the moment a rule is
+    // added to the validator - the sweep would keep repairing the file and stop saying so.
+    const fingerprint = (value) => (value === undefined ? "absent" : JSON.stringify(value) ?? "unserializable");
+    const before = fingerprint(state.todos);
+    const { todos } = normalizeTodos(state.todos);
+    // A key that was present but empty is REMOVED, for the reason `setTodos` deletes it rather than storing
+    // `[]`: absence and emptiness mean the same thing to every reader here, and a store that has never run a
+    // model should not carry a field claiming the model considered a plan and found none.
+    if (todos.length)
+        state.todos = todos;
+    else
+        delete state.todos;
+    return { changed: before !== fingerprint(state.todos) };
+}
+export class Store {
+    filePath;
+    state;
+    constructor(filePath, state) {
+        this.filePath = filePath;
+        this.state = state;
+    }
+    static async open(filePath) {
+        try {
+            const state = JSON.parse(await readFile(filePath, "utf8"));
+            if (!Array.isArray(state.backgroundTasks))
+                state.backgroundTasks = [];
+            // Every sweep runs before the store is constructed, so a single persist below publishes them together.
+            // Reconciling them in separate writes would put a file on disk in which one kind of orphan was fixed
+            // and the other was not - a half-repaired state that still needs a second restart to finish.
+            const orphaned = reconcileSubagentRuns(state);
+            const interrupted = reconcileConversations(state);
+            const requeued = reconcileQueuedMessages(state);
+            const todos = reconcileTodos(state);
+            const store = new Store(filePath, normalizeMessageTimestamps(state));
+            // Persisted here, in `open`, rather than left for the first unrelated write: a reconciled record that
+            // is only rewritten by a later mutation would still read `running` to anything that opened the file
+            // in the meantime, and would be reconciled a SECOND time on the next restart.
+            if (orphaned.length || interrupted.length || requeued.recovered.length || requeued.changed || todos.changed) {
+                for (const run of orphaned)
+                    console.warn(`Super Pi: sub-agent run ${run.id} was still marked running when the last server stopped - it is now failed, because no child process survived it.`);
+                // Announced for the same reason: a conversation that failed while nobody was watching is invisible
+                // otherwise, and the user who was watching a spinner when the server died deserves to learn that
+                // their run is over rather than guessing from the fact that it stopped moving.
+                for (const conversation of interrupted)
+                    console.warn(`Super Pi: conversation ${conversation.id} was still marked running when the last server stopped - it is now failed, because no turn was in flight any more.`);
+                for (const message of requeued.recovered)
+                    console.warn(`Super Pi: queued message ${message.id} of conversation ${message.conversationId} was still marked sending when the last server stopped - it is back in the queue and cancellable again, because the Pi that would have delivered it is gone.`);
+                await store.persist();
+            }
+            return store;
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT")
+                throw error;
+            const createdAt = now();
+            return new Store(filePath, { workspaces: [{ id: "workspace_default", name: "Super Pi", path: process.cwd(), updatedAt: createdAt }], conversations: [], subagentRuns: [], queuedMessages: [], backgroundTasks: [] });
+        }
+    }
+    snapshot() { return structuredClone(this.state); }
+    async createWorkspace(name, path) {
+        const cleanName = name.trim();
+        if (!cleanName || cleanName.length > 80)
+            throw new Error("Workspace name must be 1-80 characters");
+        const cleanPath = path?.trim() || process.cwd();
+        if (cleanPath.length > 500)
+            throw new Error("Workspace path is too long");
+        const workspace = { id: id("workspace"), name: cleanName, path: cleanPath, updatedAt: now() };
+        this.state.workspaces.push(workspace);
+        await this.persist();
+        return structuredClone(workspace);
+    }
+    async renameWorkspace(workspaceId, name) {
+        const cleanName = name.trim();
+        if (!cleanName || cleanName.length > 80)
+            throw new Error("Workspace name must be 1-80 characters");
+        const workspace = this.state.workspaces.find((item) => item.id === workspaceId);
+        if (!workspace)
+            throw new Error("Workspace not found");
+        workspace.name = cleanName;
+        workspace.updatedAt = now();
+        await this.persist();
+        return structuredClone(workspace);
+    }
+    /**
+     * Replaces the workspace's two defaults. `undefined` DELETES the key rather than storing Pi's
+     * default as this app's state - the same convention as setConversationThinking, and for the same
+     * reason: "follow Pi" must be the absence of a value, not a frozen copy of whatever Pi's default
+     * happened to be when the dialog was saved. Only conversations created AFTER this call ever see
+     * the new values; existing ones are not migrated, by design.
+     */
+    /**
+     * Replaces the workspace's defaults. `model`/`thinkingLevel` are ALWAYS sent whole (null clears one of
+     * them); `agentId` is tri-state, which is why it is not part of that pair: a string sets it, `null`
+     * clears it, and `undefined` leaves it alone. Bundling a tri-state field into an "absent means delete"
+     * pair would make any caller that only wanted to change the model silently drop the default agent.
+     *
+     * ONE persist for all three, deliberately. Two writes would publish an intermediate state - the pair
+     * saved but not the agent - and the window between them is observable: a client that reopens the
+     * settings dialog after seeing the first write on disk would mount from a broadcast that has not been
+     * sent yet, and its draft would then be frozen at the stale value. One write, one broadcast, no window.
+     */
+    async setWorkspaceDefaults(workspaceId, defaults) {
+        const workspace = this.state.workspaces.find((item) => item.id === workspaceId);
+        if (!workspace)
+            throw new Error("Workspace not found");
+        if (defaults.model === undefined)
+            delete workspace.defaultModel;
+        else
+            workspace.defaultModel = { provider: defaults.model.provider, modelId: defaults.model.modelId, label: defaults.model.label };
+        if (defaults.thinkingLevel === undefined)
+            delete workspace.defaultThinkingLevel;
+        else
+            workspace.defaultThinkingLevel = defaults.thinkingLevel;
+        if (defaults.agentId === undefined) { /* absent: leave the default agent exactly as it is */ }
+        else if (defaults.agentId === null)
+            delete workspace.defaultAgentId;
+        else
+            workspace.defaultAgentId = defaults.agentId;
+        workspace.updatedAt = now();
+        await this.persist();
+        return structuredClone(workspace);
+    }
+    async deleteWorkspace(workspaceId) {
+        if (!this.state.workspaces.some((item) => item.id === workspaceId))
+            throw new Error("Workspace not found");
+        if (this.state.workspaces.length <= 1)
+            throw new Error("Cannot delete the last workspace");
+        // Cascade: workspaces, conversations and their waiting queues live in one state.json, so this single
+        // atomic persist removes all three together. The queue has to follow: a waiting message is keyed by
+        // conversation id, so an entry left behind would name a conversation that no longer exists and could
+        // never be delivered or cancelled - invisible to the browser AND undeletable from the UI.
+        const doomed = new Set(this.state.conversations.filter((item) => item.workspaceId === workspaceId).map((item) => item.id));
+        this.state.workspaces = this.state.workspaces.filter((item) => item.id !== workspaceId);
+        this.state.conversations = this.state.conversations.filter((item) => item.workspaceId !== workspaceId);
+        this.state.queuedMessages = this.state.queuedMessages.filter((item) => !doomed.has(item.conversationId));
+        await this.persist();
+        return [...doomed];
+    }
+    async createConversation(workspaceId) {
+        const workspace = this.state.workspaces.find((item) => item.id === workspaceId);
+        if (!workspace)
+            throw new Error("Workspace not found");
+        const conversation = { id: id("conversation"), title: DEFAULT_CONVERSATION_TITLE, workspaceId, updatedAt: now(), status: "idle", messages: [] };
+        // INHERITANCE, AS A COPY AT BIRTH. The workspace's defaults are stamped onto the new conversation
+        // here and never consulted again: the session picker edits the conversation's own fields, so an
+        // existing conversation is untouched by later workspace settings, and a workspace edit never
+        // rewrites history. Field by field, never a spread, for the same reason setConversationModel
+        // narrows: the type declares three fields, so three fields are written.
+        if (workspace.defaultModel)
+            conversation.model = { provider: workspace.defaultModel.provider, modelId: workspace.defaultModel.modelId, label: workspace.defaultModel.label };
+        if (workspace.defaultThinkingLevel)
+            conversation.thinkingLevel = workspace.defaultThinkingLevel;
+        if (workspace.defaultAgentId)
+            conversation.agentId = workspace.defaultAgentId;
+        this.state.conversations.unshift(conversation);
+        await this.persist();
+        return structuredClone(conversation);
+    }
+    /**
+     * Copies a conversation into a NEW one, under an id the caller has already minted.
+     *
+     * THE ID IS A PARAMETER, and that is the whole reason this method does not simply mint one: the caller had
+     * to write Pi's copied transcript under that id first (see `ForkRequest.forkedConversationId`), so by the
+     * time this runs the id is already the one on disk. Minting here as well would produce a conversation whose
+     * Pi file belongs to a different, nonexistent conversation - the exact "Pi opens an empty session and the
+     * history has vanished with no error anywhere" failure probe B was about.
+     *
+     * WHAT IS COPIED, FIELD BY FIELD AND NEVER BY A SPREAD, for the same reason `createConversation` writes out
+     * three fields individually: the type declares exactly these, so a spread would quietly start persisting
+     * whatever the next person adds to `Conversation`. The workspace, the model, the thinking level and the
+     * agent are all copied, because a fork that came back on a different model or with no role would not be
+     * the conversation the user forked.
+     *
+     * `title` is copied VERBATIM, unchanged. Not a reason, not a suffix: the fork IS this conversation, and
+     * inventing a name is a product decision the request did not delegate. Renaming it is one click and always
+     * available, which is better than a label nobody chose.
+     *
+     * MESSAGES ARE COPIED WITH FRESH `id`s AND THE ORIGINAL `piEntryId`s. Both halves matter:
+     *
+     * - Fresh ids, because `Message.id` is this store's own handle (`beginAssistantMessage`,
+     *   `appendToolCall` and `appendAssistantDelta` all find a message by it) and a forked conversation that
+     *   answered to its source's ids would be one object wearing two names. Fork the same conversation twice
+     *   and the two copies are distinct records.
+     * - The ORIGINAL `piEntryId`, because that is the whole reason the fork is a fork. Pi's copied file is
+     *   byte-identical apart from two header fields (see `forkSessionFile`), so the source's entry ids are
+     *   present and valid in the fork - and a copied message keeps the ability to be a REVERT boundary in the
+     *   conversation it was copied into. Dropping the ids would produce a fork whose history cannot be
+     *   reverted at all, which is a silent loss of a feature rather than an honest absence.
+     *
+     * `status` is `"idle"` unconditionally, even when the source is running, because the caller refuses a
+     * running source outright (`runtime.fork`) and a conversation that has never run a turn must not be born
+     * claiming to be in one. `error` is NOT copied: it describes a run, and this conversation has had none.
+     *
+     * NOT COPIED, and both omissions are deliberate and both are the same judgement - they belong to a RUN,
+     * and no run was copied: `subagentRuns` are filtered by `conversationId`, so a run dispatched by the source
+     * stays with the source; a run dispatched by the FORK will be filed under the fork's own id and work as
+     * usual. `queuedMessages` likewise, for the same reason (research pitfall 7): a message waiting for a turn
+     * that was never copied must not be re-sent into a different conversation.
+     *
+     * POSITION IS NOT CHOSEN HERE. `unshift` plus the client rendering the sidebar by `updatedAt`
+     * (`byRecency`) puts a fork at the TOP of its workspace group, because `updatedAt` is now - which is the
+     * same position a newly created conversation takes, and the same reason.
+     */
+    async forkConversation(sourceConversationId, forkedConversationId) {
+        const source = this.requireConversation(sourceConversationId);
+        if (source.id === forkedConversationId)
+            throw new Error("Cannot fork a conversation into itself");
+        const conversation = {
+            id: forkedConversationId,
+            title: source.title,
+            workspaceId: source.workspaceId,
+            updatedAt: now(),
+            status: "idle",
+            messages: structuredClone(source.messages).map((message) => ({ ...message, id: id("message") })),
+        };
+        if (source.model)
+            conversation.model = { provider: source.model.provider, modelId: source.model.modelId, label: source.model.label };
+        if (source.thinkingLevel)
+            conversation.thinkingLevel = source.thinkingLevel;
+        if (source.agentId)
+            conversation.agentId = source.agentId;
+        this.state.conversations.unshift(conversation);
+        await this.persist();
+        return structuredClone(conversation);
+    }
+    /**
+     * Archive is a marker, not a move: the conversation keeps its id, workspace, messages and position.
+     * `updatedAt` is deliberately NOT touched, because it drives the sidebar's live timestamp and recency -
+     * bumping it would teleport the row to the top of the list the instant it was archived.
+     *
+     * A running conversation is rejected rather than archived. An archived conversation cannot be opened,
+     * so allowing one would leave a run streaming into a pane the user can no longer reach, along with any
+     * Extension UI question it is blocked on. Refusing keeps the rule honest and leaves stop-then-archive
+     * to the user, which is a visible choice instead of a silent one.
+     */
+    async archiveConversation(conversationId) {
+        const conversation = this.requireConversation(conversationId);
+        if (conversation.archivedAt)
+            return;
+        if (conversation.status === "running")
+            throw new Error("运行中的会话无法归档，请先停止运行");
+        conversation.archivedAt = now();
+        await this.persist();
+    }
+    /** Restoring deletes the key rather than setting it to null, so a fully restored conversation serializes
+     *  byte-identically to one that was never archived. `delete` is legal here because the field is optional. */
+    async unarchiveConversation(conversationId) {
+        const conversation = this.requireConversation(conversationId);
+        if (!conversation.archivedAt)
+            return;
+        delete conversation.archivedAt;
+        await this.persist();
+    }
+    /**
+     * Rename edits the title and NOTHING else. In particular `updatedAt` is deliberately not touched,
+     * for exactly the reason archive is: `updatedAt` is the sidebar's recency key, so bumping it would
+     * teleport the row to the top of the live list because someone retitled it. Renaming is not activity.
+     *
+     * There is no uniqueness check, and there is no status check on purpose. `createWorkspace` does not
+     * reject a duplicate name either, so rejecting one here would make the two paths disagree about the
+     * same question; two rows reading "notes" is a cosmetic problem the user can see and fix. And a
+     * RUNNING conversation stays renameable: the title is display-only, the run is unaffected, and
+     * refusing would mean a conversation could be permanently un-renameable while the agent works.
+     *
+     * Archived conversations are renameable too - archiving folds a row away, it does not delete it, and
+     * the Archived group renders the same name.
+     */
+    async renameConversation(conversationId, name) {
+        const cleanName = name.trim();
+        if (!cleanName || cleanName.length > 80)
+            throw new Error("Conversation name must be 1-80 characters");
+        const conversation = this.requireConversation(conversationId);
+        conversation.title = cleanName;
+        await this.persist();
+        return structuredClone(conversation);
+    }
+    async addUserMessage(conversationId, content, images) {
+        const conversation = this.requireConversation(conversationId);
+        // The browser cannot reach an archived conversation, so this guard exists for any other caller -
+        // a direct WebSocket client, or a future code path. Archiving is the promise that a conversation is
+        // closed, and a closed conversation must not accept a new turn.
+        if (conversation.archivedAt)
+            throw new Error("无法向已归档的会话发送消息，请先恢复该会话");
+        const message = { id: id("message"), role: "user", content, createdAt: now() };
+        if (images && images.length > 0)
+            message.images = structuredClone(images);
+        conversation.messages.push(message);
+        const firstUser = conversation.messages.find((item) => item.role === "user");
+        const autoTitle = firstUser?.content.trim()
+            ? firstUser.content.slice(0, 42)
+            : (firstUser?.images?.length ? "【图片】" : DEFAULT_CONVERSATION_TITLE);
+        conversation.title = autoTitle || DEFAULT_CONVERSATION_TITLE;
+        conversation.updatedAt = message.createdAt;
+        conversation.status = "running";
+        // The reason this conversation was failed - startup reconciliation's note that a previous run was cut
+        // short - describes THAT run, and this line is the moment it stops being the current one. Deleting the
+        // key rather than overwriting it keeps the file byte-identical to a conversation that was never
+        // reconciled, and it is deleted here rather than at settle because the reason is wrong from the instant
+        // the new turn starts: leaving it up would show "was interrupted, marked failed" above a conversation
+        // that is visibly working again.
+        delete conversation.error;
+        await this.persist();
+        return structuredClone(message);
+    }
+    /**
+     * Records the model a conversation runs on. `updatedAt` is deliberately NOT touched, for the same
+     * reason rename does not touch it: it is the sidebar's recency key, and switching model is not
+     * activity in the conversation. No status check either - changing the model of a RUNNING
+     * conversation is allowed, because the selection is read at the START of the next turn, so the
+     * turn in flight is unaffected and refusing would strand a conversation on a model the user can
+     * no longer change until it settles.
+     */
+    async setConversationModel(conversationId, model) {
+        const conversation = this.requireConversation(conversationId);
+        // Built field by field, NEVER `{ ...model }`. A spread copies whatever it is handed, and the
+        // caller in index.ts has a full `ModelOption` in hand (Pi's `detail`, `reasoning`,
+        // `contextWindow` and `imageInput`), so a spread persisted every one of them into a field this
+        // type declares as three: the declared shape would be a lie about the bytes on disk, and anything
+        // reasoning from the type would be reasoning about a file that does not have that shape.
+        //
+        // Pi's capability metadata belongs to the CATALOG, which re-reads it from Pi on every fetch and
+        // therefore cannot go stale. A copy frozen into a conversation would be wrong the moment Pi
+        // changed a model, and nothing anywhere reads it: `sessionCommands` sends only provider and
+        // modelId, and the client renders each option's detail from the catalog list rather than from
+        // the stored selection. Narrowing is free and makes the type true.
+        //
+        // The field count is deliberately not written down here. It changed when `imageInput` landed, and
+        // a comment naming the old number would have kept saying six while the object carried seven -
+        // which is the exact failure this whole note is about, one level up. scripts/session-picker.test.mjs
+        // pins the real key set instead, and re-breaks whenever a field is added.
+        conversation.model = { provider: model.provider, modelId: model.modelId, label: model.label };
+        await this.persist();
+        return structuredClone(conversation);
+    }
+    /** Restoring Pi's own default deletes the key rather than storing Pi's default as this app's state. */
+    async setConversationThinking(conversationId, level) {
+        const conversation = this.requireConversation(conversationId);
+        if (level === undefined)
+            delete conversation.thinkingLevel;
+        else
+            conversation.thinkingLevel = level;
+        await this.persist();
+        return structuredClone(conversation);
+    }
+    /**
+     * Records the agent a conversation runs as. Same three rules as `setConversationModel`: `undefined`
+     * DELETES the key rather than freezing "no agent" as a value, `updatedAt` is untouched because
+     * changing role is not activity in the conversation, and no status check - the agent is read at the
+     * START of the next turn, so the turn in flight is unaffected.
+     */
+    async setConversationAgent(conversationId, agentId) {
+        const conversation = this.requireConversation(conversationId);
+        if (agentId === undefined)
+            delete conversation.agentId;
+        else
+            conversation.agentId = agentId;
+        await this.persist();
+        return structuredClone(conversation);
+    }
+    async beginAssistantMessage(conversationId) { const conversation = this.requireConversation(conversationId); const message = { id: id("message"), role: "assistant", content: "", createdAt: now() }; conversation.messages.push(message); await this.persist(); return structuredClone(message); }
+    async appendAssistantDelta(conversationId, messageId, delta) { const conversation = this.requireConversation(conversationId); const message = conversation.messages.find((item) => item.id === messageId); if (!message)
+        throw new Error("Assistant message not found"); message.content += delta; conversation.updatedAt = now(); await this.persist(); }
+    /**
+     * Appends one tool call to the message it belongs to, and returns the message's whole `toolCalls`
+     * array so the caller can broadcast it as one snapshot.
+     *
+     * WHY AN APPEND AND NOT AN UPDATE, and why the returned array is the whole truth. A turn's calls arrive
+     * one at a time and each one REWRITES a field on a row it has already broadcast - `status` and
+     * `durationMs` land on `tool_execution_end`, minutes or seconds after the row was published by
+     * `tool_execution_start`. So the only thing that can be cheap and correct is: the store owns the array,
+     * the caller sends the array. Handing back the array rather than the one row is what stops the two from
+     * drifting - the caller has nothing to merge, so there is no merge to get wrong, and the event it sends
+     * is the same shape `state` carries on the next broadcast.
+     *
+     * PERSISTED ON EVERY CALL, for the same reason `appendAssistantDelta` is: a block that was on screen
+     * when the browser reloaded has to come back, and a reload that showed a `read` but not the `bash` that
+     * followed it would be worse than showing neither.
+     *
+     * `toolCalls` is CREATED LAZILY, so a message whose turn used no tools stores no empty array - which is
+     * what makes a `state.json` written before call blocks existed read as "this turn used no tools"
+     * instead of as a field it does not understand.
+     */
+    async appendToolCall(conversationId, messageId, call) {
+        const conversation = this.requireConversation(conversationId);
+        const message = conversation.messages.find((item) => item.id === messageId);
+        if (!message)
+            throw new Error("Assistant message not found");
+        const calls = (message.toolCalls ??= []);
+        calls.push(structuredClone(call));
+        conversation.updatedAt = now();
+        await this.persist();
+        return structuredClone(calls);
+    }
+    /**
+     * Fills in the outcome of the call at `index`, or returns the array UNCHANGED when there is no such
+     * index.
+     *
+     * ADDRESSED BY POSITION rather than by Pi's `toolCallId`, and that is the whole reason the caller has
+     * to hold a map. `toolCallId` is an identity only Pi can resolve - it is never persisted on
+     * `ToolCallBlock` - so the caller resolves each end back to the row it started, which is exactly what
+     * `SubagentRunRecorder` does for a card.
+     *
+     * A MISMATCH IS NOT AN ERROR. `tool_execution_end` with no matching start, or one that arrives after the
+     * turn ended, must not fail the turn: the alternative is a store method that throws inside a drain loop,
+     * and the reader would lose the whole turn's transcript over one unresolvable id. Returning the array
+     * unchanged keeps the caller broadcasting what it actually knows.
+     *
+     * Only `status` and `durationMs` are written, and only when they are present on the incoming block - a
+     * second end for a row that already has an outcome must not erase it with an absent field.
+     */
+    async settleToolCall(conversationId, messageId, index, outcome) {
+        const conversation = this.requireConversation(conversationId);
+        const message = conversation.messages.find((item) => item.id === messageId);
+        if (!message)
+            throw new Error("Assistant message not found");
+        const calls = message.toolCalls;
+        const call = calls?.[index];
+        if (!calls || !call)
+            return structuredClone(calls ?? []);
+        if (outcome.status !== undefined)
+            call.status = outcome.status;
+        if (outcome.durationMs !== undefined)
+            call.durationMs = outcome.durationMs;
+        conversation.updatedAt = now();
+        await this.persist();
+        return structuredClone(calls);
+    }
+    async setStatus(conversationId, status) { const conversation = this.requireConversation(conversationId); conversation.status = status; conversation.updatedAt = now(); await this.persist(); }
+    /** The plan a revert would carry out, without carrying it out. The server reads this to stop children first. */
+    planRevert(conversationId, messageId) { return planRevert(this.state, conversationId, messageId); }
+    /**
+     * Records which Pi entry a message became, as reported by Pi while it was still running.
+     *
+     * Only ever set, never cleared: a message that already has an id keeps the one Pi gave it for that
+     * turn, and a second report for the same message is ignored rather than allowed to move the boundary -
+     * a boundary that moved under a user who is looking at it is exactly the silent data loss revert must not
+     * be able to cause. An unknown message id is refused for the same reason `appendAssistantDelta` refuses
+     * one: it means the caller and the store disagree about the conversation, and guessing is worse.
+     */
+    async setMessagePiEntryId(conversationId, messageId, piEntryId) {
+        const conversation = this.requireConversation(conversationId);
+        const message = conversation.messages.find((item) => item.id === messageId);
+        if (!message)
+            throw new Error(`Message not found: ${messageId}`);
+        if (message.piEntryId)
+            return;
+        message.piEntryId = piEntryId;
+        await this.persist();
+    }
+    /**
+     * Reverts the conversation to the state right after `messageId`, in `state.json` only.
+     *
+     * SCOPE, DELIBERATELY NARROW: this touches `messages` and `subagentRuns` and nothing else. It does not
+     * touch the workspace (that is not this process's to touch), it does not create or modify a conversation
+     * (the user's hard requirement: still the same session, same id, same row in the sidebar), and it does
+     * not record a "revert happened" marker - there is no undo to restore one for.
+     *
+     * NOT `updatedAt`. For the same reason rename and archive leave it alone: it is the sidebar's recency key,
+     * so bumping it would teleport the conversation to the top of the list as a side effect of editing its
+     * history. What a person did to a transcript is not activity IN the conversation, and the timestamps of
+     * the surviving messages are untouched, so the pane's own ordering does not move either.
+     *
+     * `planRevert` has already run by the time this is called (the server reads it to stop children), so the
+     * plan is recomputed here rather than passed in - two callers cannot disagree about what a message id
+     * means, and the recomputation is a pure scan of a small array.
+     */
+    async revertMessages(conversationId, messageId) {
+        const plan = planRevert(this.state, conversationId, messageId);
+        const conversation = this.requireConversation(conversationId);
+        conversation.messages.splice(plan.boundaryIndex + 1);
+        if (plan.doomedRunIds.length) {
+            const doomed = new Set(plan.doomedRunIds);
+            this.state.subagentRuns = this.state.subagentRuns.filter((run) => !doomed.has(run.id));
+        }
+        await this.persist();
+        return plan;
+    }
+    requireConversation(conversationId) { const conversation = this.state.conversations.find((item) => item.id === conversationId); if (!conversation)
+        throw new Error("Conversation not found"); return conversation; }
+    // ------------------------------------------------------------- Follow-up queue
+    // The durable waiting list for messages the user sent while the agent was working. Owned HERE and not
+    // by Pi, because Pi's own queue is process memory that Super Pi destroys at the end of every turn -
+    // see `QueuedMessage`. Every method persists on every call, for the reason
+    // `setSubagentRun` does: what a browser reads and what the file holds must never differ, and a
+    // message waiting for a turn that has not started is exactly as durable as the conversation.
+    /**
+     * This conversation's waiting list, oldest first.
+     *
+     * Cloned like every other value this store hands out, because the caller broadcasts it straight to
+     * browsers and the array is mutated in place by the very next enqueue.
+     */
+    listQueuedMessages(conversationId) {
+        return structuredClone(this.state.queuedMessages.filter((item) => item.conversationId === conversationId));
+    }
+    /**
+     * Adds one message to the waiting list and returns it.
+     *
+     * The id is minted here and is the entry's identity for its whole life. Pi matches its own queue by
+     * message TEXT (`agent-session.ts:1123`), so two identical messages are one entry to Pi and two here;
+     * `cancel` and `steer` name the id, which is the only reason "cancel the second of two identical
+     * messages" is expressible at all. `crypto.randomUUID`, like every other id in this store.
+     */
+    async enqueueMessage(conversationId, content, images) {
+        this.requireConversation(conversationId);
+        if (this.state.conversations.find((item) => item.id === conversationId)?.archivedAt)
+            throw new Error("无法向已归档的会话排队消息，请先恢复该会话");
+        const message = { id: id("q"), conversationId, content, state: "queued", createdAt: now() };
+        if (images && images.length > 0)
+            message.images = structuredClone(images);
+        this.state.queuedMessages.push(message);
+        await this.persist();
+        return structuredClone(message);
+    }
+    /**
+     * Removes one waiting message. Returns it, or `undefined` when it is already gone.
+     *
+     * "Already gone" is a no-op rather than an error, and the reason is the same as `SubagentRun.stop`:
+     * the click that sent this was almost always triggered by a dock row the browser has not been told
+     * about yet, so an id that has already been delivered or cancelled is the ordinary case and must not
+     * surface as a failure.
+     *
+     * A `sending` entry REFUSES, because the text is already in a live Pi child's stdin and Pi has no way
+     * to forget one item (its only queue command is `clear_queue`, which clears every one of them,
+     * including follow-ups that have nothing to do with this click). Removing it from this list would not
+     * stop Pi from delivering it - it would make the model act on a message the user believed they had
+     * withdrawn.
+     */
+    async cancelQueuedMessage(conversationId, queueId) {
+        const index = this.state.queuedMessages.findIndex((item) => item.id === queueId && item.conversationId === conversationId);
+        if (index < 0)
+            return undefined;
+        if (this.state.queuedMessages[index].state === "sending")
+            throw new Error("这条消息已经交给 Agent 了，取消不掉（Pi 没有撤回单条队列消息的能力）");
+        const [removed] = this.state.queuedMessages.splice(index, 1);
+        await this.persist();
+        return structuredClone(removed);
+    }
+    /**
+     * Claims one waiting message for delivery to the live Pi process: `queued` becomes `sending`, and the
+     * entry STAYS in the list until Pi reports it delivered.
+     *
+     * The read and the write are adjacent statements with no `await` between them, which is what makes
+     * the claim atomic here. This store has no mutex, and it does not need one: JavaScript runs this
+     * synchronous run-to-completion, so a second caller arriving in the same tick observes the write above
+     * and cannot claim the same entry. Anything that needed to await between reading and writing would
+     * need real serialization instead.
+     *
+     * Throws for an unknown id and for one that is already `sending`, because both mean the caller is
+     * acting on a state the store has already moved past - and the second one means a second steer of the
+     * same message would put the text into Pi twice.
+     */
+    async claimQueuedMessage(conversationId, queueId) {
+        const message = this.state.queuedMessages.find((item) => item.id === queueId && item.conversationId === conversationId);
+        if (!message)
+            throw new Error(`排队消息不存在或已不在队列中：${queueId}`);
+        if (message.state === "sending")
+            throw new Error(`排队消息已经交给 Agent 了：${queueId}`);
+        message.state = "sending";
+        await this.persist();
+        return structuredClone(message);
+    }
+    /**
+     * Puts a `sending` entry back into the queue.
+     *
+     * The one legal use, and it is narrow on purpose: this is called ONLY when we can prove the message
+     * never reached a model - the turn ended while Pi still held it, or the write to Pi's stdin failed
+     * before it left. Pi drains steering before its loop can end and reports the removal before the
+     * delivered message, so a message still `sending` when the child is gone provably was not delivered,
+     * and returning it is a fact rather than a guess. It is deliberately NOT used for "Pi has not answered
+     * yet" (see `steer` in `index.ts`), where the outcome is genuinely unknown and the honest state is
+     * still `sending`.
+     */
+    async releaseQueuedMessage(queueId) {
+        const message = this.state.queuedMessages.find((item) => item.id === queueId);
+        if (!message || message.state !== "sending")
+            return;
+        message.state = "queued";
+        await this.persist();
+    }
+    /**
+     * Removes the OLDEST `count` messages this conversation has in `sending`, and returns them.
+     *
+     * Driven by a COUNT rather than by matching text, and that is the whole point. Pi's `queue_update`
+     * reports only the strings it still holds, and Pi itself identifies which of its entries a delivered
+     * message came from with `indexOf` on that text - so with two identical steered messages, "which one
+     * was delivered" is exactly the question Pi cannot answer. It does not need to be answered: Pi's
+     * steering queue is FIFO and Super Pi only ever steers from the front of this list, so a drop in
+     * `steering.length` from N to N-k means Super Pi's oldest k `sending` entries were delivered, in
+     * order, whatever their text was.
+     */
+    async dropSendingMessages(conversationId, count) {
+        if (count <= 0)
+            return [];
+        const sending = this.state.queuedMessages.filter((item) => item.conversationId === conversationId && item.state === "sending");
+        // Never more than are actually in `sending`: a snapshot that arrives out of order, or a Pi that
+        // clears its own queue, must not be able to remove entries that were never delivered.
+        const doomed = sending.slice(0, Math.min(count, sending.length)).map((item) => item.id);
+        if (!doomed.length)
+            return [];
+        this.state.queuedMessages = this.state.queuedMessages.filter((item) => !doomed.includes(item.id));
+        await this.persist();
+        return structuredClone(sending.slice(0, doomed.length));
+    }
+    /**
+     * Takes the oldest still-`queued` message of this conversation OUT of the list and returns it, for the
+     * next turn to send as its prompt.
+     *
+     * Removing it here, rather than marking it and removing it after the turn, is what bounds the loop:
+     * every pass through the follow-up loop strictly shrinks the list, so the loop cannot run forever
+     * even if a turn succeeds without consuming anything. And removing it BEFORE the spawn is what makes a
+     * crash honest - a server that dies mid-turn has already taken the message out of the file, and
+     * `open` does not put it back, because it may well have been delivered.
+     */
+    async takeNextQueuedMessage(conversationId) {
+        const index = this.state.queuedMessages.findIndex((item) => item.conversationId === conversationId && item.state === "queued");
+        if (index < 0)
+            return undefined;
+        const [taken] = this.state.queuedMessages.splice(index, 1);
+        await this.persist();
+        return structuredClone(taken);
+    }
+    /**
+     * Returns every `sending` message of this conversation to the queue, for the end of a turn.
+     *
+     * See `releaseQueuedMessage` for why this is a fact and not a guess, and `reconcileQueuedMessages` for
+     * why the same treatment is right after a crash. Called both when a turn ends and when the user stops
+     * it: in the stop case the child is killed mid-turn and a steer it was still holding was never
+     * delivered either, so putting it back is what lets the user decide what to do with it instead of
+     * silently dropping a message they typed.
+     */
+    async releaseSendingMessages(conversationId) {
+        let changed = false;
+        for (const message of this.state.queuedMessages) {
+            if (message.conversationId !== conversationId || message.state !== "sending")
+                continue;
+            message.state = "queued";
+            changed = true;
+        }
+        if (changed)
+            await this.persist();
+    }
+    // ------------------------------------------------------------- Sub-agent runs
+    // Records, not transcripts: what lands here is the dispatch, the last assistant message and the
+    // usage - see `SubagentRun` for why the child's own conversation deliberately does not.
+    /**
+     * Records a sub-agent run as `running`, BEFORE the child is spawned.
+     *
+     * The ordering is the whole point of this method existing separately from the spawn. A record created
+     * after the child starts cannot survive the child failing to start, and one created only at the end
+     * leaves nothing behind when the SERVER dies - which is the orphan startup reconciliation exists to
+     * clean up. Writing the claim first is what makes that orphan possible, and therefore recoverable.
+     *
+     * `unshift`, like `createConversation`: the newest run is the one a reader is looking for.
+     *
+     * Trimmed HERE rather than at read time, because the array in memory and the file on disk have to
+     * be the same thing - a store that kept evicted rows until the next unrelated write would put them
+     * back on disk, and one that trimmed on read would show a browser a roster the file still holds.
+     */
+    async beginSubagentRun(run) {
+        if (this.state.subagentRuns.some((item) => item.id === run.id))
+            throw new Error(`Sub-agent run already recorded: ${run.id}`);
+        this.state.subagentRuns.unshift(run);
+        trimSubagentRuns(this.state.subagentRuns, this.state.conversations);
+        await this.persist();
+        // A clone, like every other return here: the caller must not hold a reference to the object this
+        // store mutates in place on the next delta, or a run's "snapshot" would change under it.
+        return structuredClone(run);
+    }
+    async setBackgroundTask(summary) {
+        const existing = this.state.backgroundTasks.find((item) => item.id === summary.id);
+        if (existing)
+            Object.assign(existing, summary);
+        else
+            this.state.backgroundTasks.unshift(summary);
+        await this.persist();
+    }
+    async removeBackgroundTask(id) {
+        this.state.backgroundTasks = this.state.backgroundTasks.filter((item) => item.id !== id);
+        await this.persist();
+    }
+    /**
+     * Applies the fields a run's life can change, and nothing else.
+     *
+     * `Object.assign` is safe HERE in a way it is not in `setConversationModel`, and the difference is the
+     * patch's own type: `SubagentRunUpdate` is a named list of six already-narrowed fields, so there is no
+     * wider object for a spread to smuggle extra keys in from. `undefined` means "no such value" and is
+     * dropped by JSON.stringify, which is how `output`/`error`/`outputTruncated` come to be absent rather
+     * than stored as an empty or null one.
+     *
+     * PERSISTED ON EVERY CALL, exactly as `appendAssistantDelta` is: the record a reader sees in a
+     * `state` broadcast and the record on disk are then never different, and a run that is in flight is
+     * as durable as the conversation it belongs to.
+     */
+    async setSubagentRun(runId, changes) {
+        const run = this.state.subagentRuns.find((item) => item.id === runId);
+        if (!run)
+            throw new Error(`Sub-agent run not found: ${runId}`);
+        Object.assign(run, changes);
+        await this.persist();
+        return structuredClone(run);
+    }
+    /**
+     * Replaces the model's task list, and persists it.
+     *
+     * WHY IT IS A FILE AND NOT PI'S MEMORY, stated once here because it is the whole justification: Pi is
+     * killed unconditionally at the end of every turn (`runtime.ts`) and never writes a tool result it was
+     * given by an extension anywhere durable except the session JSONL, so a list held only in the child
+     * would be gone before a person could look at it - and the sidebar would empty itself at every turn
+     * boundary. The list is therefore part of `state.json` and rides the existing broadcast, which is also
+     * why the browser needs no channel of its own: it already repaints from `state` on every text delta.
+     *
+     * THE PARAMETER IS RE-NORMALIZED HERE, not trusted because the endpoint normalized it. Those are two
+     * different things: `/api/todos` validates a request that crossed a socket, and this validates a value
+     * handed to `setTodos` by any future caller inside this process. A method whose own contract is "call me
+     * with anything" is the only version of this that cannot be broken by the next call site.
+     *
+     * AN EMPTY LIST IS STORED AS ABSENCE, not as `[]`. `normalizeTodos` returns `[]` for a list the model
+     * emptied deliberately, and the two must not be distinguishable: the browser renders `todos: []` and
+     * `todos: undefined` as the same empty state on purpose, and persisting `[]` for a store that has never
+     * seen the tool would make a fresh install claim the model had considered a plan and found none. So the
+     * key is deleted, which also keeps `state.json` free of a field no build before this one wrote.
+     */
+    async setTodos(raw) {
+        const { todos, dropped } = normalizeTodos(raw);
+        if (todos.length)
+            this.state.todos = todos;
+        else
+            delete this.state.todos;
+        await this.persist();
+        return { todos: structuredClone(todos), dropped };
+    }
+    /**
+     * Writes the whole state atomically: a temp file, then a rename over the real one.
+     *
+     * SERIALIZED, because two conversations can genuinely run at once (see workspace-cwd.test.mjs), and
+     * this method was not safe for that: every write used the SAME `${filePath}.tmp`, so two overlapping
+     * persists raced and the loser's rename failed with ENOENT on a file the winner had already moved.
+     * A unique name per write would hide that ENOENT while leaving the real bug in place - whichever rename
+     * landed last would win, and a rename of an OLDER snapshot last would silently discard a newer one.
+     * Queueing keeps both properties: one writer at a time, and last write wins with the newest state.
+     *
+     * A rejected write must not poison the queue, or one failure would reject every later persist as well.
+     */
+    persistQueue = Promise.resolve();
+    async persist() {
+        const write = this.persistQueue.then(async () => {
+            await mkdir(dirname(this.filePath), { recursive: true });
+            const temporaryPath = `${this.filePath}.tmp`;
+            await writeFile(temporaryPath, `${JSON.stringify(this.state, null, 2)}\n`, "utf8");
+            await replaceFile(temporaryPath, this.filePath);
+        });
+        this.persistQueue = write.catch(() => { });
+        await write;
+    }
+}
+/**
+ * How long `replaceFile` keeps retrying a rename that lost a race with a reader. Two seconds is two
+ * orders of magnitude past the measured sub-50ms release, so it exists to absorb a loaded machine and a
+ * virus scanner mid-scan, not to wait out a lock that will never clear.
+ */
+const RENAME_RETRY_MS = 2_000;
+const RENAME_RETRY_STEP_MS = 5;
+/**
+ * Renames `from` over `to`, retrying the WINDOWS SHARING VIOLATION.
+ *
+ * WHY THIS EXISTS, because the failure it fixes was a real defect and not a test artefact. On Windows a
+ * rename onto a file that ANY handle has open fails with EPERM/EACCES: the destination must be held with
+ * FILE_SHARE_DELETE, and a plain reader does not do that. Node's own `readFile` is such a reader, and so
+ * is every indexer, virus scanner and sync client on the machine. So `persist()` threw EPERM, the caller's
+ * mutation stayed only in memory, and the save was LOST - the settings dialog had already closed on send,
+ * so the person who pressed 保存 was told nothing and kept a default that had never been saved.
+ * scripts/workspace-settings-browser.test.mjs reproduced it at roughly 1 save in 5, and every occurrence
+ * read as "the save never arrived" because the refusal travelled to the browser as an error event the
+ * suite did not read, so a refused write and a slow write were indistinguishable for a whole day.
+ *
+ * MEASURED, so the bound is honest rather than hopeful: renaming onto a held-open `state.json` fails on
+ * the first attempt 40 times out of 40 and clears within one 5ms tick of the reader letting go (worst
+ * case 11 attempts). The lock lasts exactly as long as somebody is READING, which is why a bounded
+ * retry is the fix and not a longer sleep: the transient case is short, and a genuinely stuck file is
+ * not a sharing violation. A file that stays contended past the bound still throws, which is the honest
+ * outcome - the store reports a failed write instead of pretending it saved.
+ */
+async function replaceFile(from, to) {
+    const deadline = Date.now() + RENAME_RETRY_MS;
+    for (;;) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            const contended = code === "EPERM" || code === "EACCES" || code === "EBUSY";
+            if (!contended || Date.now() >= deadline)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, RENAME_RETRY_STEP_MS));
+        }
+    }
+}
+export function defaultStorePath(dataDir) { return join(dataDir, "state.json"); }