@evandu/super-pi 0.1.84 → 0.1.85

package/dist/server/store.js

@@ -297,53 +297,103 @@ function reconcileWorkflows(state) {
     return orphaned;
 }
 /**
- * Startup reconciliation for the follow-up queue: an entry the previous process left `sending` goes
- * back to `queued`.
+ * Startup reconciliation for the waiting messages: one the previous process left `sending` goes back
+ * to `waiting`, and any legacy waiting list is folded back into the transcripts it belonged to.
  *
  * `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:
+ * RETURNING IT TO THE WAITING SET, 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.
+ * - Dropping it would lose a message the user is looking at in their own transcript, silently and
+ *   permanently - and unlike the old separate list, that message is not one entry among several, it is
+ *   the only copy of those words there is.
  * - 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.
+ *   announces the delivery with `message_start` before the turn settles
+ *   (`agent-session.ts:1116-1136`), which this server consumes and applies. So a message still `sending`
+ *   when the process died provably was not delivered. Re-queued, the user sees it again and can steer it
+ *   into the next turn.
+ *
+ * THE LEGACY FOLD IS WHAT MAKES THIS AN UPGRADE RATHER THAN A RESET. A state file written by a build
+ * that kept waiting messages in their own array holds real words the user typed, in a shape this build
+ * no longer reads. Dropping that array would silently lose every message that was waiting at the moment
+ * of the upgrade - and that is the one moment where a reader is most likely to be looking at the queue.
+ * So each legacy entry is appended to its own conversation as a waiting MESSAGE, keeping its id, text
+ * and images, in the order the array had them.
+ *
+ * IT IS ONE-WAY, deliberately: the key is deleted after the fold, so a second boot cannot duplicate
+ * them, and a folded message keeps its `q_`-prefixed id so nothing can mistake one for a message this
+ * build wrote (`claimClientMessageId` only accepts `message_` ids, and a collision there falls back to
+ * a minted id rather than to a fold).
  *
  * 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
+ * consequences: a `recovered` message is one 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;
+function reconcileWaitingMessages(state) {
+    // The legacy array, read blind: `Array.isArray` rather than `?? []`, for the same reason the sweeps
+    // above do it, because a truthy non-array left by a hand edit would make every call below throw.
+    const legacy = state.queuedMessages;
+    const queue = Array.isArray(legacy) ? legacy : [];
+    const hadKey = Array.isArray(legacy);
+    // An entry that is not usable is dropped rather than repaired: every field is load-bearing (the id is
+    // what cancel/steer name, the content is what the user wrote), 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");
+    // DELETED UNCONDITIONALLY, before anything else reads it. The fold below is the only consumer, and
+    // leaving the key in place would re-fold the same words on every single boot.
+    delete state.queuedMessages;
     const recovered = [];
-    for (const message of usable) {
-        if (message.state !== "sending")
+    for (const conversation of state.conversations) {
+        for (const message of conversation.messages) {
+            // A `delivery` on anything but a user message is a broken file: no code path writes one, and
+            // rendering a waiting state on an assistant bubble would be a claim about nothing.
+            if (message.role !== "user") {
+                delete message.delivery;
+                continue;
+            }
+            if (message.delivery !== "sending")
+                continue;
+            message.delivery = "waiting";
+            recovered.push({ conversationId: conversation.id, message });
+        }
+    }
+    const folded = [];
+    for (const entry of usable) {
+        const conversation = state.conversations.find((item) => item.id === entry.conversationId);
+        // An entry naming a conversation that is gone has nowhere to go. That is the one legacy case that is
+        // genuinely dropped, and it is reported through `changed` so the key's removal is written to disk.
+        if (!conversation)
             continue;
-        message.state = "queued";
-        recovered.push(message);
+        const message = {
+            id: entry.id,
+            role: "user",
+            content: entry.content,
+            createdAt: typeof entry.createdAt === "string" ? entry.createdAt : now(),
+            // ALWAYS `waiting`, never the legacy `sending`: the claim died with the process that made it, which
+            // is the same argument the sweep above makes about a message that is genuinely `sending`.
+            delivery: "waiting",
+        };
+        if (entry.images && entry.images.length > 0)
+            message.images = structuredClone(entry.images);
+        if (entry.attachments && entry.attachments.length > 0)
+            message.attachments = structuredClone(entry.attachments);
+        conversation.messages.push(message);
+        folded.push({ conversationId: conversation.id, message });
     }
-    return { recovered, changed: missing || usable.length !== queue.length };
+    return { recovered, folded, changed: hadKey || usable.length !== queue.length || recovered.length > 0 };
 }
 /**
  * Which messages and which sub-agent runs a revert to `messageId` removes.
@@ -390,7 +440,7 @@ function planRevert(state, conversationId, messageId, withdraw = false) {
 /**
  * Brings `state.todosByConversation` back to a shape the browser can render, on boot.
  *
- * THE SAME REASON `reconcileQueuedMessages` EXISTS, and the same three cases, but nothing here RECOVERS
+ * THE SAME REASON `reconcileWaitingMessages` 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
@@ -451,6 +501,18 @@ export class Store {
     static async openRepository(repository) {
         try {
             const state = await repository.load();
+            // A COLLECTION THE FILE DID NOT HAVE IS A REPAIR TOO, and it is counted as one here rather than left
+            // to the sweeps below - which is what this branch used to do by accident. The follow-up queue sweep
+            // reported `changed` for any file without a `queuedMessages` key, so every state written before that
+            // feature shipped was rewritten on its first boot, and a hand-seeded file still is. Deleting the
+            // queue took that side effect with it, and with it the observable fact that a server which had just
+            // defaulted a collection says so on disk.
+            //
+            // The rule is the one already written above the queue sweep: a repaired file has to be rewritten, or
+            // it is repaired again on every single boot - and until it is, anything reading the file sees the
+            // un-normalised shape rather than the one the store is actually running on.
+            const defaulted = ["workspaces", "conversations", "subagentRuns"].filter((key) => !Array.isArray(state[key])).length > 0
+                || !Array.isArray(state.backgroundTasks);
             if (!Array.isArray(state.backgroundTasks))
                 state.backgroundTasks = [];
             // Every sweep runs before the store is constructed, so a single persist below publishes them together.
@@ -459,13 +521,13 @@ export class Store {
             const orphaned = reconcileSubagentRuns(state);
             const orphanedWorkflows = reconcileWorkflows(state);
             const interrupted = reconcileConversations(state);
-            const requeued = reconcileQueuedMessages(state);
+            const requeued = reconcileWaitingMessages(state);
             const todos = reconcileTodos(state);
             const store = new Store(repository, 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 || orphanedWorkflows.length || interrupted.length || requeued.recovered.length || requeued.changed || todos.changed) {
+            if (defaulted || orphaned.length || orphanedWorkflows.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.`);
                 for (const plan of orphanedWorkflows)
@@ -475,8 +537,10 @@ export class Store {
                 // 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.`);
+                for (const entry of requeued.recovered)
+                    console.warn(`Super Pi: message ${entry.message.id} of conversation ${entry.conversationId} was still marked sending when the last server stopped - it is waiting again and cancellable, because the Pi that would have delivered it is gone.`);
+                for (const entry of requeued.folded)
+                    console.warn(`Super Pi: message ${entry.message.id} of conversation ${entry.conversationId} was waiting in the old queue format - it has been moved into that conversation's transcript.`);
                 await store.persist();
             }
             return store;
@@ -500,7 +564,12 @@ export class Store {
                 }
             }
             const createdAt = now();
-            return new Store(repository, { workspaces: [{ id: "workspace_default", name: "Super Pi", path: process.cwd(), updatedAt: createdAt }], conversations: [], subagentRuns: [], queuedMessages: [], backgroundTasks: [] });
+            // NO WRITE HERE, AND THAT IS AN INVARIANT RATHER THAN AN OMISSION: a store with no file behind it
+            // stays lazy, so opening one never creates a file and never has to un-create one. `persistence-
+            // repository.test.mjs` asserts it by reading the path and expecting ENOENT. Repairing an EXISTING
+            // file is the other case and is handled above; this branch invented its contents and says nothing
+            // until something actually happens.
+            return new Store(repository, { workspaces: [{ id: "workspace_default", name: "Super Pi", path: process.cwd(), updatedAt: createdAt }], conversations: [], subagentRuns: [], backgroundTasks: [] });
         }
     }
     async setModelFilterRules(rules) {
@@ -585,14 +654,15 @@ export class Store {
             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.
+        // Cascade: workspaces and conversations live in one state.json, so this single atomic persist removes
+        // both together. A waiting message needs no sweep of its own any more - it is a message inside one of
+        // the conversations being removed, so it goes with its container, which is the whole reason it is a
+        // better shape than an entry keyed by conversation id in a separate array: that array needed this
+        // cascade to avoid naming a conversation that no longer exists, and could not have been trusted to
+        // get it right on its own.
         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];
     }
@@ -679,7 +749,15 @@ export class Store {
             workspaceId: source.workspaceId,
             updatedAt: now(),
             status: "idle",
-            messages: structuredClone(source.messages).map((message) => ({ ...message, id: id("message") })),
+            // A WAITING MESSAGE IS NOT COPIED, and this filter is why the fork still answers "no queued
+            // messages" after the waiting list stopped being a list of its own. Forking is refused while a turn
+            // is running, but a conversation can still be holding messages that were sent during that run and
+            // have not been started; they belong to the run that is in progress and to nothing else. Copying them
+            // would put words in the fork's transcript that Pi's session file - which the fork copies separately -
+            // has no record of, so the two halves of the new conversation would disagree from its first turn.
+            messages: structuredClone(source.messages)
+                .filter((message) => !message.delivery)
+                .map((message) => ({ ...message, id: id("message") })),
         };
         if (source.model)
             conversation.model = { provider: source.model.provider, modelId: source.model.modelId, label: source.model.label };
@@ -743,19 +821,48 @@ export class Store {
         await this.persistMetadata(conversationId);
         return structuredClone(conversation);
     }
-    async addUserMessage(conversationId, content, images, attachments) {
+    /**
+     * Writes ONE user message into the transcript - the single place a user utterance comes into being.
+     *
+     * Two callers exist and they differ only in `delivery`, because whether a send starts a turn or waits
+     * for one is decided by the RUN GUARD in `run-service`, not here. This method records the words and,
+     * if they are waiting, records that they are waiting. Deciding anything about turns would put a second,
+     * contradictory answer next to the guard's.
+     *
+     * `clientId` is the browser's own id for the message it has already drawn. When it is well formed and
+     * not already taken, the message IS that id - which is what lets the optimistic bubble and the stored
+     * message be the same object rather than two that have to be matched up by content afterwards. A
+     * collision falls back to a minted id rather than throwing: the browser is asking for its words to be
+     * kept, and refusing the whole send because an id was already in use would lose them.
+     *
+     * `delivery: "waiting"` ALSO SKIPS EVERY SIDE EFFECT BELOW - no `running`, no title, no `updatedAt`,
+     * no clearing of a failure reason. Those all describe a turn, and a message waiting for one has not
+     * started anything. It is why a conversation holding only waiting messages still reads as idle in the
+     * sidebar, and why the title comes from the first message that was actually asked rather than from
+     * whatever was typed into a box that was not listening yet. `openTurnOnMessage` applies them at the
+     * moment a turn genuinely begins.
+     */
+    async addUserMessage(conversationId, content, images, attachments, options) {
         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() };
+        const message = { id: this.claimClientMessageId(conversation, options?.clientId), role: "user", content, createdAt: now() };
         if (images && images.length > 0)
             message.images = structuredClone(images);
         if (attachments && attachments.length > 0)
             message.attachments = structuredClone(attachments);
+        if (options?.delivery)
+            message.delivery = options.delivery;
         conversation.messages.push(message);
+        // Persisted as a transcript change and nothing more: this is the honest record of "the user said this
+        // and nothing has picked it up yet", and a refresh has to show it in the same place it was sent from.
+        if (message.delivery) {
+            await this.persistMessages(conversation);
+            return structuredClone(message);
+        }
         const firstUser = conversation.messages.find((item) => item.role === "user");
         const autoTitle = firstUser?.content.trim()
             ? firstUser.content.slice(0, 42)
@@ -774,6 +881,20 @@ export class Store {
         await this.persist();
         return structuredClone(message);
     }
+    /**
+     * Takes the browser's id for its own optimistic message, when it is safe to.
+     *
+     * A client that names an id already in this conversation gets a minted one instead: two messages sharing
+     * an id would break `updateToolCall`, `revertMessage` and every per-message write that follows, so
+     * uniqueness within the conversation is worth more than the client getting its own id back in that case.
+     * The `message_` prefix is required so a folded legacy id (which is `q_`-prefixed) can never be adopted.
+     */
+    claimClientMessageId(conversation, clientId) {
+        const usable = typeof clientId === "string" && /^message_[0-9a-f-]{36}$/.test(clientId);
+        if (usable && !conversation.messages.some((message) => message.id === clientId))
+            return clientId;
+        return id("message");
+    }
     /**
      * Appends one background-result message to a conversation, without starting a turn.
      *
@@ -1190,199 +1311,296 @@ export class Store {
     }
     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.
+    // ------------------------------------------------------------- Waiting messages
+    //
+    // A message the user sent while the agent was working WAITS HERE, and "here" is a field on the message
+    // (`MessageDelivery`) rather than a list beside the conversation. Nothing in this section copies text
+    // anywhere, because there is no second copy: the words a user typed live in exactly one place, in the
+    // transcript, from the frame they pressed send until long after the agent answered them.
+    //
+    // ORDER IS THE QUEUE. The waiting messages are the `role: "user"` messages carrying a `delivery`, and
+    // their array order is the order they will be started in - so "put this one first" is a move within
+    // that group, and there is no `priority` flag to disagree with it.
+    //
+    // 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 around it.
     /**
-     * This conversation's waiting list, oldest first.
+     * This conversation's waiting messages, in the order they will be started.
      *
      * 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.
+     * browsers and the array is mutated in place by the very next send.
      */
-    listQueuedMessages(conversationId) {
-        return structuredClone(this.state.queuedMessages.filter((item) => item.conversationId === conversationId));
+    listWaitingMessages(conversationId) {
+        return structuredClone(this.waitingMessages(this.requireConversation(conversationId)));
+    }
+    /** The same list by reference, for callers that only read a field and must not pay for a clone. */
+    waitingMessages(conversation) {
+        return conversation.messages.filter((message) => message.role === "user" && message.delivery);
+    }
+    requireWaitingMessage(conversationId, messageId) {
+        const conversation = this.requireConversation(conversationId);
+        const message = conversation.messages.find((item) => item.id === messageId);
+        if (!message || message.role !== "user" || !message.delivery)
+            throw new Error(`等待中的消息不存在或已被处理：${messageId}`);
+        return { conversation, message };
+    }
+    async persistMessages(conversation) {
+        await this.persistTransaction({ kind: "conversation.messages", conversationId: conversation.id, messages: structuredClone(conversation.messages), updatedAt: conversation.updatedAt });
     }
     /**
-     * Adds one message to the waiting list and returns it.
+     * Claims one waiting message for delivery to the live Pi process: `waiting` becomes `sending`, and the
+     * message STAYS WHERE IT IS - still on screen, still in the transcript, still at the same index.
      *
-     * 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.
+     * 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 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 message.
      */
-    async enqueueMessage(conversationId, content, images, attachments) {
-        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);
-        if (attachments && attachments.length > 0)
-            message.attachments = structuredClone(attachments);
-        this.state.queuedMessages.push(message);
-        await this.persistCollections("queuedMessages");
+    async claimWaitingMessage(conversationId, messageId) {
+        const { conversation, message } = this.requireWaitingMessage(conversationId, messageId);
+        if (message.delivery === "sending")
+            throw new Error("这条消息已经交给 Agent 了（Pi 没有撤回单条队列消息的能力）");
+        message.delivery = "sending";
+        await this.persistMessages(conversation);
         return structuredClone(message);
     }
     /**
-     * Removes one waiting message. Returns it, or `undefined` when it is already gone.
+     * Puts ONE `sending` message back to `waiting`, for the one case that proves Pi never took it.
+     *
+     * 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 announces the delivery before the turn
+     * settles, 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",
+     * where the outcome is genuinely unknown and the honest state is still `sending`.
+     */
+    async releaseWaitingMessage(conversationId, messageId) {
+        const conversation = this.requireConversation(conversationId);
+        const message = conversation.messages.find((item) => item.id === messageId);
+        if (!message || message.delivery !== "sending")
+            return;
+        message.delivery = "waiting";
+        await this.persistMessages(conversation);
+    }
+    /**
+     * Returns every `sending` message of this conversation to `waiting`, for the end of a turn.
+     *
+     * See `releaseWaitingMessage` for why this is a fact and not a guess. 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 - a message they can still see, because it never left the
+     * transcript in the first place.
+     */
+    async releaseSendingMessages(conversationId) {
+        const conversation = this.requireConversation(conversationId);
+        let changed = false;
+        for (const message of this.waitingMessages(conversation)) {
+            if (message.delivery !== "sending")
+                continue;
+            message.delivery = "waiting";
+            changed = true;
+        }
+        if (changed)
+            await this.persistMessages(conversation);
+    }
+    /**
+     * Withdraws one waiting message, by id. 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.
+     * "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 bubble the browser has not been told about
+     * yet, so an id that has already been answered 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
+     * A `sending` message 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.
+     * including follow-ups that have nothing to do with this click). Removing it here would not stop Pi from
+     * delivering it - it would make the model act on a message the user believed they had withdrawn, while
+     * their own transcript quietly lost the words.
      */
-    async cancelQueuedMessage(conversationId, queueId) {
-        const index = this.state.queuedMessages.findIndex((item) => item.id === queueId && item.conversationId === conversationId);
+    async cancelWaitingMessage(conversationId, messageId) {
+        const conversation = this.requireConversation(conversationId);
+        const index = conversation.messages.findIndex((item) => item.id === messageId);
         if (index < 0)
             return undefined;
-        if (this.state.queuedMessages[index].state === "sending")
+        const message = conversation.messages[index];
+        if (message.role !== "user" || !message.delivery)
+            return undefined;
+        if (message.delivery === "sending")
             throw new Error("这条消息已经交给 Agent 了，取消不掉（Pi 没有撤回单条队列消息的能力）");
-        const [removed] = this.state.queuedMessages.splice(index, 1);
-        await this.persistCollections("queuedMessages");
+        const [removed] = conversation.messages.splice(index, 1);
+        await this.persistMessages(conversation);
         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.
+     * Rewrites the words of one waiting message.
+     *
+     * Only legal while nothing has read it. `waiting` means the text is still only in this transcript, so
+     * changing it is changing the whole truth of the message - there is no second copy anywhere that could
+     * fall out of step. `sending` means Pi already holds it, and a message the model is about to answer is
+     * not one the user gets to rewrite after the fact.
      */
-    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";
-        message.priority = true;
-        await this.persistCollections("queuedMessages");
+    async editWaitingMessage(conversationId, messageId, content) {
+        const trimmed = content.trim();
+        if (!trimmed)
+            throw new Error("消息不能为空");
+        const { conversation, message } = this.requireWaitingMessage(conversationId, messageId);
+        if (message.delivery !== "waiting")
+            throw new Error("这条消息已经交给 Agent 了，改不了（Pi 已经收到了原文）");
+        message.content = trimmed;
+        await this.persistMessages(conversation);
         return structuredClone(message);
     }
-    /** Keep a priority request at the front even if the current Pi process has already exited. */
-    async prioritizeQueuedMessage(conversationId, queueId) {
-        const index = this.state.queuedMessages.findIndex((item) => item.id === queueId && item.conversationId === conversationId);
-        if (index < 0)
-            throw new Error(`排队消息不存在或已发出：${queueId}`);
-        const message = this.state.queuedMessages[index];
-        if (message.state === "sending")
+    /**
+     * Moves one waiting message to a new position among the waiting messages.
+     *
+     * `toIndex` is counted over the WAITING messages only, so `0` is the next one the agent will start and
+     * the caller never has to know how many answered messages sit above it. Moving to the front and moving
+     * back are the same operation, which is the point: the old arrangement had a `priority` boolean for the
+     * first and no way at all to express the second, so undoing a priority meant cancelling the message and
+     * retyping it.
+     *
+     * NOTHING CAN GO IN FRONT OF A `sending` MESSAGE. It is already in Pi's stdin and Pi's steering queue
+     * is FIFO, so it will be delivered before anything this server could do about the order. Accepting the
+     * move and then delivering the other one first would be the UI promising an outcome the transport has
+     * already decided, so it is refused instead.
+     */
+    async reorderWaitingMessage(conversationId, messageId, toIndex) {
+        const { conversation, message } = this.requireWaitingMessage(conversationId, messageId);
+        const waiting = this.waitingMessages(conversation);
+        const from = waiting.indexOf(message);
+        const target = Math.max(0, Math.min(Math.trunc(toIndex), waiting.length - 1));
+        if (target === from)
             return structuredClone(message);
-        message.priority = true;
-        await this.persistCollections("queuedMessages");
+        // NOTHING MAY OCCUPY THE `sending` MESSAGE'S SLOT, in either direction. It is already in Pi's stdin and
+        // Pi's steering queue is FIFO, so it is delivered next whatever this method does - meaning a different
+        // message landing in front of it would be a move the UI performed and the transport then ignored, and
+        // moving the `sending` message itself off that spot would be a lie of the same kind.
+        const sendingIndex = waiting.findIndex((item) => item.delivery === "sending");
+        if (sendingIndex >= 0 && (from === sendingIndex || target <= sendingIndex)) {
+            throw new Error(message.delivery === "sending"
+                ? "这条消息已经交给 Agent 了，挪不动（Pi 会先回答已经收到的那条）"
+                : "前面那条消息已经交给 Agent 了，插不过去（Pi 按收到的顺序送达）");
+        }
+        // Permute THE WAITING SLOTS rather than splicing a message to an index. The waiting messages are
+        // usually a suffix of the array, but they are not guaranteed to be one - an assistant message sits
+        // between two of them once a steer has been delivered mid-turn - and an offset derived from "where in
+        // the waiting group am I" would then be computing a position that means nothing. Rewriting the slots in
+        // place is total: it cannot land a message outside the group, and it moves nothing that is not waiting.
+        const slots = waiting.map((item) => conversation.messages.indexOf(item));
+        const reordered = [...waiting];
+        reordered.splice(from, 1);
+        reordered.splice(target, 0, message);
+        slots.forEach((slot, order) => { conversation.messages[slot] = reordered[order]; });
+        await this.persistMessages(conversation);
         return structuredClone(message);
     }
     /**
-     * Puts a `sending` entry back into the queue.
+     * Pi has just delivered one steered message: unmark it and open the answer to it, in ONE write.
      *
-     * 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`.
+     * Oldest rather than matched on text, and that is forced on us by Pi rather than chosen: Pi identifies
+     * its own queued entry by `indexOf` on the message text (`agent-session.ts:1123`), so two identical
+     * steered messages are ONE entry to it and no host-side matching could do better. Position is sufficient
+     * anyway because Pi's steering queue is FIFO and Super Pi only ever steers from the front of the waiting
+     * group.
+     *
+     * ONE WRITE, because the reader must never see the intermediate: a message that has stopped waiting but
+     * has no answer under it yet is the exact broken state this refactor exists to remove, and a browser
+     * that broadcast between the two halves would put it right back on screen.
+     *
+     * WHAT IS DIFFERENT FROM BEFORE, and is the whole point: the message used to be DELETED here. It is now
+     * merely unmarked, with an assistant message spliced in after it. It was on screen the whole time - it
+     * was written into the transcript when the user pressed send, long before Pi ever saw it - and it stays
+     * exactly where it was, now with the agent answering it. Deleting it is what made a steered reply appear
+     * with no question above it.
      */
-    async releaseQueuedMessage(queueId) {
-        const message = this.state.queuedMessages.find((item) => item.id === queueId);
-        if (!message || message.state !== "sending")
-            return;
-        message.state = "queued";
-        await this.persistCollections("queuedMessages");
+    async deliverWaitingMessage(conversationId, agentIdentity) {
+        const conversation = this.requireConversation(conversationId);
+        const index = conversation.messages.findIndex((item) => item.role === "user" && item.delivery === "sending");
+        if (index < 0)
+            return undefined;
+        const user = conversation.messages[index];
+        delete user.delivery;
+        const assistant = { id: id("message"), role: "assistant", content: "", createdAt: now(), ...(agentIdentity ? { agentIdentity: structuredClone(agentIdentity) } : {}) };
+        conversation.messages.splice(index + 1, 0, assistant);
+        await this.persistMessages(conversation);
+        return { user: structuredClone(user), assistant: structuredClone(assistant) };
     }
     /**
-     * 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.
+     * Opens a turn on a message that is ALREADY IN THE TRANSCRIPT: clears its delivery state, applies every
+     * side effect that means "a turn started here", and splices the assistant placeholder in DIRECTLY AFTER
+     * IT.
+     *
+     * THE INSERT POSITION IS THE WHOLE DESIGN. `push` was the old behaviour and it is only correct when the
+     * message being answered is the last thing in the conversation. With two messages waiting, answering
+     * the first by appending puts its reply BELOW the second one, so the reader sees the answer to a
+     * question that is still waiting - a transcript lying about its own order. Splicing at
+     * `indexOf(user) + 1` keeps every waiting message below the reply that belongs to the one above it.
+     *
+     * The side effects - title, `updatedAt`, `status: "running"`, clearing a stale failure - all describe a
+     * TURN rather than a message, which is why `addUserMessage` skips them for a message that is only
+     * waiting. They belong here, at the moment the turn genuinely begins.
      */
-    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.persistCollections("queuedMessages");
-        return structuredClone(sending.slice(0, doomed.length));
+    async openTurnOnMessage(conversationId, messageId, agentIdentity) {
+        const conversation = this.requireConversation(conversationId);
+        const index = conversation.messages.findIndex((item) => item.id === messageId);
+        if (index < 0)
+            throw new Error(`消息不存在或已被撤回：${messageId}`);
+        const user = conversation.messages[index];
+        delete user.delivery;
+        const assistant = { id: id("message"), role: "assistant", content: "", createdAt: now(), ...(agentIdentity ? { agentIdentity: structuredClone(agentIdentity) } : {}) };
+        conversation.messages.splice(index + 1, 0, assistant);
+        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);
+        if (!conversation.titleLocked)
+            conversation.title = autoTitle || DEFAULT_CONVERSATION_TITLE;
+        conversation.updatedAt = user.createdAt;
+        conversation.status = "running";
+        delete conversation.error;
+        await this.persistMessages(conversation);
+        return { user: structuredClone(user), assistant: structuredClone(assistant) };
     }
     /**
-     * Takes the oldest still-`queued` message of this conversation OUT of the list and returns it, for the
+     * Takes the OLDEST still-`waiting` message of this conversation, clearing its delivery state, 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.
+     * Clearing the state and taking the message are the same write on purpose: it bounds the follow-up loop
+     * (every pass strictly shrinks the set of waiting messages, so the loop cannot run forever even if a turn
+     * succeeds without consuming anything) and it is what makes the crash honest - a server that dies
+     * mid-turn has already taken the message out of the waiting set, so startup does not put it back, because
+     * it may well have been delivered.
      */
-    async takeNextQueuedMessage(conversationId) {
-        let index = this.state.queuedMessages.findIndex((item) => item.conversationId === conversationId && item.state === "queued" && item.priority);
-        if (index < 0)
-            index = this.state.queuedMessages.findIndex((item) => item.conversationId === conversationId && item.state === "queued");
-        if (index < 0)
+    async takeNextWaitingMessage(conversationId) {
+        const conversation = this.requireConversation(conversationId);
+        const next = this.waitingMessages(conversation).find((item) => item.delivery === "waiting");
+        if (!next)
             return undefined;
-        const [taken] = this.state.queuedMessages.splice(index, 1);
-        await this.persistCollections("queuedMessages");
-        return structuredClone(taken);
+        delete next.delivery;
+        await this.persistMessages(conversation);
+        return structuredClone(next);
     }
-    /** Removes one still-cancellable row by id so an explicit user action can start it as a new turn. */
-    async takeQueuedMessage(conversationId, queueId) {
-        const index = this.state.queuedMessages.findIndex((item) => item.id === queueId && item.conversationId === conversationId);
-        if (index < 0)
-            throw new Error("这条排队消息已经发出或不存在");
-        if (this.state.queuedMessages[index].state !== "queued")
-            throw new Error("当前轮还没有结束；请先停止或等待它结束，再发送这条消息");
-        const [taken] = this.state.queuedMessages.splice(index, 1);
-        await this.persistCollections("queuedMessages");
-        return structuredClone(taken);
+    /** Takes one specific waiting message by id, so an explicit user action can start it as a new turn. */
+    async takeWaitingMessage(conversationId, messageId) {
+        const { conversation, message } = this.requireWaitingMessage(conversationId, messageId);
+        if (message.delivery !== "waiting")
+            throw new Error("当前轮还没有结束，这条消息已经交给 Agent 了（Pi 没有撤回单条队列消息的能力）");
+        delete message.delivery;
+        await this.persistMessages(conversation);
+        return structuredClone(message);
     }
     /**
-     * Returns every `sending` message of this conversation to the queue, for the end of a turn.
+     * Opens a turn for a message the user chose to be answered now, when the conversation is idle.
      *
-     * 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.
+     * The one place that both claims a specific message and opens its turn, so there is no window between
+     * "the message stopped waiting" and "the turn began" in which a crash would leave a message that is
+     * neither waiting nor answered.
      */
-    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.persistCollections("queuedMessages");
+    async openTurnOnSpecificMessage(conversationId, messageId, agentIdentity) {
+        await this.takeWaitingMessage(conversationId, messageId);
+        return this.openTurnOnMessage(conversationId, messageId, agentIdentity);
     }
-    // ------------------------------------------------------------- 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.
      *