@evandu/super-pi 0.1.145 → 0.1.147

package/dist/server/session-tree-scope.js

@@ -0,0 +1,337 @@
+/** The depth cap on an ancestor walk. A tree deeper than this is a bug, not a reason to hang. */
+const MAX_ANCESTOR_DEPTH = 64;
+/**
+ * The chain of ancestors of a conversation, starting with the conversation itself.
+ *
+ * A dangling parent (one whose conversation is gone) simply ends the chain, and a cycle is cut by
+ * the depth cap: the walk is for the message, so it must terminate whatever the data says.
+ */
+const ancestorChain = (store, conversationId) => {
+    const chain = [];
+    const seen = new Set();
+    let current = conversationId;
+    while (current && !seen.has(current) && chain.length < MAX_ANCESTOR_DEPTH) {
+        seen.add(current);
+        chain.push(current);
+        current = store.conversation(current)?.parentConversationId;
+    }
+    return chain;
+};
+/**
+ * The relation between two sessions, in the tree.
+ *
+ * READ ONLY. This classifies a pair for the sake of the refusal message; it never grants access.
+ */
+export const classifySessionRelation = (store, callerConversationId, targetConversationId) => {
+    if (callerConversationId === targetConversationId)
+        return "self";
+    const callerChain = ancestorChain(store, callerConversationId);
+    const targetChain = ancestorChain(store, targetConversationId);
+    if (targetChain[1] === callerConversationId)
+        return "direct-child";
+    // The caller sits somewhere above the target: the target is a descendant, a level down or more.
+    if (targetChain.indexOf(callerConversationId) > 0)
+        return "descendant";
+    // The target sits above the caller.
+    if (callerChain.indexOf(targetConversationId) > 0)
+        return "ancestor";
+    // The target has no parent at all: it is the root of another tree.
+    if (targetChain.length === 1)
+        return "other-root";
+    // A shared ancestor means the same chart; without one, another department.
+    const shared = targetChain.slice(1).find((id) => callerChain.slice(1).includes(id));
+    return shared ? "peer" : "unrelated";
+};
+/** The session between the caller and the target, when the target is a descendant of it. */
+const intermediateSession = (store, callerConversationId, targetConversationId) => {
+    const chain = ancestorChain(store, targetConversationId);
+    const index = chain.indexOf(callerConversationId);
+    return index > 1 ? chain[index - 1] : undefined;
+};
+/** The nearest session both the caller and the target descend from, when there is one. */
+const commonAncestorSession = (store, callerConversationId, targetConversationId) => {
+    const callerChain = ancestorChain(store, callerConversationId);
+    const targetChain = ancestorChain(store, targetConversationId);
+    return targetChain.slice(1).find((id) => callerChain.slice(1).includes(id));
+};
+/**
+ * The reason a pair was refused, in the words of the relation that was found.
+ *
+ * The reader is a model about to retry, or a person reading a log: the message says which relation
+ * was found (peer, grandchild, ancestor, another tree, another department) and what the rule is, so
+ * a retry with a different target is an informed one.
+ *
+ * The three subjects read differently on purpose. Refusing to DISPATCH a peer and refusing to
+ * LIST a peer's subordinates are the same boundary, but they are not the same mistake, and a
+ * reader who is told which one they made can fix the right thing.
+ */
+const relationReason = (relation, subject, callerConversationId, targetConversationId, verb, intermediateId, ancestorId) => {
+    if (subject === "list-children") {
+        switch (relation) {
+            case "direct-child":
+                return `列出 ${targetConversationId} 的下属属于跨级查询，跨级不被允许。`;
+            case "descendant":
+                return intermediateId
+                    ? `${targetConversationId} 是 ${callerConversationId} 的隔级下属（中间隔着 ${intermediateId}），跨级列出下属不被允许。`
+                    : `${targetConversationId} 是 ${callerConversationId} 的隔级下属，跨级列出下属不被允许。`;
+            case "ancestor":
+                return `${callerConversationId} 不能列出自己上级的下属。`;
+            case "peer":
+                return ancestorId
+                    ? `${targetConversationId} 是 ${callerConversationId} 的平级会话（两者的共同上级是 ${ancestorId}），列出别人的下属属于越权。`
+                    : `${targetConversationId} 是 ${callerConversationId} 的平级会话，列出别人的下属属于越权。`;
+            case "other-root":
+                return `${targetConversationId} 是一个独立的顶层会话，它的下属不属于 ${callerConversationId}。`;
+            case "unrelated":
+                return `${targetConversationId} 与 ${callerConversationId} 不在同一条会话树上（${targetConversationId} 不是 ${callerConversationId} 的直接下属），跨部门不被允许。`;
+            case "self":
+                return `会话不是自己的下属。`;
+        }
+    }
+    if (subject === "declare-parent") {
+        switch (relation) {
+            case "descendant":
+                return `${targetConversationId} 是 ${callerConversationId} 的隔级下属，不能被重新声明为 ${callerConversationId} 的直接下属。`;
+            case "ancestor":
+                return `${callerConversationId} 不能把会话 ${targetConversationId} 声明为自己的下属。`;
+            case "peer":
+                return `${targetConversationId} 是 ${callerConversationId} 的平级会话，不能被 ${callerConversationId} 收编为自己的下属。`;
+            case "other-root":
+                return `${targetConversationId} 是一个独立的顶层会话，不能被 ${callerConversationId} 声明为下属。`;
+            case "unrelated":
+                return `${targetConversationId} 与 ${callerConversationId} 不在同一条会话树上，不能被 ${callerConversationId} 声明为下属。`;
+            case "direct-child":
+            case "self":
+                return `会话不是自己的下属。`;
+        }
+    }
+    switch (relation) {
+        case "self":
+            return `会话不是自己的下属。`;
+        case "direct-child":
+            return `${targetConversationId} 是 ${callerConversationId} 的直接子会话。`;
+        case "descendant":
+            return intermediateId
+                ? `${targetConversationId} 是 ${callerConversationId} 的隔级下属（中间隔着 ${intermediateId}），跨级${verb}不被允许。`
+                : `${targetConversationId} 是 ${callerConversationId} 的隔级下属，跨级${verb}不被允许。`;
+        case "ancestor":
+            return `${callerConversationId} 不能${verb}自己的上级。`;
+        case "peer":
+            return ancestorId
+                ? `${targetConversationId} 是 ${callerConversationId} 的平级会话（两者的共同上级是 ${ancestorId}），不在 ${callerConversationId} 的直接下属中。`
+                : `${targetConversationId} 是 ${callerConversationId} 的平级会话，不在 ${callerConversationId} 的直接下属中。`;
+        case "other-root":
+            return `${targetConversationId} 是一个独立的顶层会话，不属于 ${callerConversationId}。`;
+        case "unrelated":
+            return `${targetConversationId} 与 ${callerConversationId} 不在同一条会话树上（${targetConversationId} 不是 ${callerConversationId} 的直接下属），跨部门${verb}不被允许。`;
+    }
+};
+/**
+ * Writes the refusal for a pair that is not allowed to be reached.
+ *
+ * The three shapes, because the three failures are different failures:
+ *   - managing a session      -> 「不能调度/读取/停止/恢复会话 X」
+ *   - listing a session's kids -> 「不能列出会话 X 的下属」
+ *   - claiming a parent        -> 「不能把会话 X 声明为自己的下属」
+ */
+export const describeScopeRefusal = (options) => {
+    const { store, callerConversationId, targetConversationId, verb, subject } = options;
+    const relation = classifySessionRelation(store, callerConversationId, targetConversationId);
+    const intermediateId = intermediateSession(store, callerConversationId, targetConversationId);
+    const ancestorId = commonAncestorSession(store, callerConversationId, targetConversationId);
+    const reason = relationReason(relation, subject, callerConversationId, targetConversationId, verb, intermediateId, ancestorId);
+    if (subject === "list-children") {
+        return `调用方会话 ${callerConversationId} 不能列出会话 ${targetConversationId} 的下属：${reason}只能列出自己直接创建的子会话。`;
+    }
+    if (subject === "declare-parent") {
+        return `调用方会话 ${callerConversationId} 不能把会话 ${targetConversationId} 声明为自己的下属：${reason}创建会话的父会话必须是调用方自己。`;
+    }
+    return `调用方会话 ${callerConversationId} 不能${verb}会话 ${targetConversationId}：${reason}只能${verb}自己直接创建的子会话。`;
+};
+/** The refusal for a caller that cannot be identified at all. */
+const missingCallerRefusal = (callerConversationId) => ({
+    ok: false,
+    status: 403,
+    error: callerConversationId
+        ? `调用方会话 ${callerConversationId} 不存在或未关联有效工作区，拒绝编排操作。`
+        : "调用方会话为空，拒绝编排操作。",
+});
+/**
+ * Checks that the caller may manage the target: the target must be the caller's DIRECT child.
+ *
+ * The workspace check is NOT part of this rule and is NOT removed by it - a conversation has to be
+ * in the caller's workspace AND in the caller's own subtree. The workspace refusal comes first
+ * because it is the older, coarser boundary, and its message names the two workspaces.
+ */
+export const verifyDirectChildScope = (options) => {
+    const { store, callerConversationId, targetConversationId } = options;
+    const verb = options.verb ?? "调度";
+    const caller = callerConversationId?.trim();
+    if (!caller)
+        return missingCallerRefusal(callerConversationId);
+    const callerConversation = store.conversation(caller);
+    if (!callerConversation?.workspaceId)
+        return missingCallerRefusal(caller);
+    const target = store.conversation(targetConversationId);
+    if (!target) {
+        return { ok: false, status: 400, error: `找不到会话：${targetConversationId}` };
+    }
+    if (target.workspaceId !== callerConversation.workspaceId) {
+        return {
+            ok: false,
+            status: 403,
+            error: `调用方会话 ${caller} 所在工作区为 ${callerConversation.workspaceId}，目标会话 ${targetConversationId} 所在工作区为 ${target.workspaceId}，拒绝跨工作区操作。目标会话必须属于调用方工作区。`,
+        };
+    }
+    // THE RULE, IN ONE LINE. The target's tree edge must point at the caller, exactly.
+    if (target.parentConversationId !== caller) {
+        return {
+            ok: false,
+            status: 403,
+            error: describeScopeRefusal({
+                store,
+                callerConversationId: caller,
+                targetConversationId,
+                verb,
+                subject: "manage",
+            }),
+        };
+    }
+    return { ok: true };
+};
+/**
+ * Checks that the caller may list a parent's children.
+ *
+ * The rule is EQUALITY, not parenthood: the parent whose children are listed must be the caller
+ * itself, so the only sessions on the list are the caller's own direct children. Listing the
+ * children of the caller's own child would be listing grandchildren, which is the cross-level reach
+ * this whole rule exists to refuse.
+ */
+export const verifyListParentScope = (options) => {
+    const { store, callerConversationId, requestedParentId } = options;
+    const caller = callerConversationId?.trim();
+    if (!caller)
+        return missingCallerRefusal(callerConversationId);
+    const callerConversation = store.conversation(caller);
+    if (!callerConversation?.workspaceId)
+        return missingCallerRefusal(caller);
+    const requested = requestedParentId?.trim();
+    // No parent named: the caller's own children are what gets listed.
+    if (!requested)
+        return { ok: true };
+    const parentConversation = store.conversation(requested);
+    if (parentConversation && parentConversation.workspaceId !== callerConversation.workspaceId) {
+        return {
+            ok: false,
+            status: 403,
+            error: `调用方会话 ${caller} 所在工作区为 ${callerConversation.workspaceId}，请求的父会话 ${requested} 所在工作区为 ${parentConversation.workspaceId}，拒绝跨工作区查询。父会话必须属于调用方工作区。`,
+        };
+    }
+    if (requested === caller)
+        return { ok: true };
+    return {
+        ok: false,
+        status: 403,
+        error: describeScopeRefusal({
+            store,
+            callerConversationId: caller,
+            targetConversationId: requested,
+            verb: "列出",
+            subject: "list-children",
+        }),
+    };
+};
+/**
+ * Checks that the caller may REPORT to the target: the target must be the caller's DIRECT PARENT.
+ *
+ * THE REPORTING LINE IS THE TREE EDGE, READ BACKWARDS. Every other rule in this file asks "may this
+ * session manage that one?" - and the answer is always about a session's subordinates. A report is the
+ * one message that travels UP, so the rule is inverted: a child reports to the session that owns it,
+ * the one whose id is the child's `parentConversationId`, and to nobody else.
+ *
+ * WHY THE INVERSION IS NOT A LOOPHOLE. A peer is somebody else's child, an ancestor is above the
+ * caller's own parent, a grandchild is below the caller, and a session in another workspace is another
+ * department. Every one of them would put one branch's news into another branch's inbox, and the inbox
+ * is where a parent's NEXT ACTION is decided - so a report that crossed a branch would be a stranger's
+ * news steering the wrong supervisor.
+ *
+ * THE RECIPIENT IS DERIVED, NOT CHOSEN. This check exists for the case where a caller NAMES a
+ * recipient at all: the server derives the parent from the tree and this refuses anything else, so a
+ * model cannot redirect its own report up or sideways.
+ */
+export const verifyReportTargetScope = (options) => {
+    const { store, callerConversationId, targetConversationId } = options;
+    const caller = callerConversationId?.trim();
+    if (!caller)
+        return missingCallerRefusal(callerConversationId);
+    const callerConversation = store.conversation(caller);
+    if (!callerConversation?.workspaceId)
+        return missingCallerRefusal(caller);
+    const target = store.conversation(targetConversationId);
+    if (!target) {
+        return { ok: false, status: 400, error: `找不到会话：${targetConversationId}` };
+    }
+    if (target.workspaceId !== callerConversation.workspaceId) {
+        return {
+            ok: false,
+            status: 403,
+            error: `调用方会话 ${caller} 所在工作区为 ${callerConversation.workspaceId}，目标会话 ${targetConversationId} 所在工作区为 ${target.workspaceId}，拒绝跨工作区汇报。汇报对象必须与调用方在同一工作区。`,
+        };
+    }
+    // THE RULE, INVERTED. The caller's own parent edge must point at the target.
+    if (callerConversation.parentConversationId === targetConversationId) {
+        return { ok: true };
+    }
+    const relation = classifySessionRelation(store, caller, targetConversationId);
+    const reason = relation === "self"
+        ? `会话 ${caller} 不能向自己汇报`
+        : relation === "ancestor"
+            ? `${targetConversationId} 是 ${caller} 的上级会话，但不是它的直属父会话`
+            : relation === "descendant"
+                ? `${targetConversationId} 是 ${caller} 的下属会话`
+                : relation === "peer"
+                    ? `${targetConversationId} 与 ${caller} 是平级会话`
+                    : relation === "other-root"
+                        ? `${targetConversationId} 是另一个树的顶层会话`
+                        : `${targetConversationId} 与 ${caller} 不在同一条会话树上`;
+    return {
+        ok: false,
+        status: 403,
+        error: `子会话 ${caller} 只能向自己的直属父会话汇报：${reason}。汇报对象由服务端按会话树决定，调用方不能指定。`,
+    };
+};
+/**
+ * Checks the parent a new session is created under.
+ *
+ * The parent edge is written onto the new conversation at birth, and the result callback follows
+ * that edge home. A caller that names somebody ELSE as the parent would therefore rewrite that
+ * session's reporting line - putting the victim's result into the caller's inbox - so the parent
+ * must be the caller. An empty parent means a top-level session, which is what the user's own "+"
+ * creates and what a session with no owner legitimately is.
+ */
+export const verifySpawnParentScope = (options) => {
+    const { store, callerConversationId, requestedParentId } = options;
+    const caller = callerConversationId?.trim();
+    if (!caller)
+        return missingCallerRefusal(callerConversationId);
+    const callerConversation = store.conversation(caller);
+    if (!callerConversation?.workspaceId)
+        return missingCallerRefusal(caller);
+    const requested = requestedParentId?.trim();
+    // No parent named: a top-level session, owned by nobody and reportable to nobody.
+    if (!requested)
+        return { ok: true };
+    if (requested === caller)
+        return { ok: true };
+    return {
+        ok: false,
+        status: 403,
+        error: describeScopeRefusal({
+            store,
+            callerConversationId: caller,
+            targetConversationId: requested,
+            verb: "调度",
+            subject: "declare-parent",
+        }),
+    };
+};

package/dist/server/store.d.ts

@@ -3,6 +3,7 @@ import { defaultJsonStatePath } from "./persistence/json-state-repository.js";
 import type { ScheduledTask } from "./scheduled-tasks.js";
 import type { WorkflowRun } from "./workflow.js";
 import type { AppState, Conversation, Message, MessageDelivery, MessageImage, ModelSelection, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallQuestion, ToolCallArg, ToolCallBlock, ToolResultSummary, Workspace } from "./types.js";
+import type { TurnUsageReadout } from "./conversation-usage.js";
 /** Mints the id a forked conversation will have, BEFORE its Pi transcript exists.
  *
  *  Exported because the ordering demands it and no other arrangement provides it. Pi's copied file's header
@@ -119,6 +120,8 @@ export declare class Store {
      */
     workspaceForConversation(conversationId: string): Workspace | undefined;
     workspace(workspaceId: string): Workspace | undefined;
+    /** Read every workspace as detached shallow copies. */
+    workspaces(): Workspace[];
     /** Read the app-wide default without cloning conversations or transcripts. */
     defaultModel(): ModelSelection | undefined;
     /** Read one detached conversation for lifecycle operations. */
@@ -271,6 +274,7 @@ export declare class Store {
         thinkingLevel?: string | null;
         modelNotice?: string;
         agentNotice?: string;
+        cwd?: string;
         parentConversationId?: string;
         origin?: "user" | "orchestrator";
     }): Promise<Conversation>;
@@ -388,6 +392,24 @@ export declare class Store {
      * whatever was typed into a box that was not listening yet. `openTurnOnMessage` applies them at the
      * moment a turn genuinely begins.
      */
+    /**
+     * Writes ONE INSTRUCTION INTO THE TRANSCRIPT AS SOMETHING THE SYSTEM SAID.
+     *
+     * `addUserMessage` above is the only way a person's words come into being, and everything written
+     * through it wears the reader's own name and the reader's bubble. That is right for a person and
+     * wrong for the orchestrator: when a primary agent dispatches a task to a child session, the
+     * child receives an ORDER, not something the reader typed - and the child transcript showed it
+     * under the reader's avatar, so the reader saw their own name on an instruction they never wrote.
+     *
+     * The role is `tool` for a reason that is not cosmetic: `tool` is already the product's word for
+     * "the system delivered this", it renders as the 系统 side of the transcript rather than as a
+     * person, and Pi's queue already knows how to hand a `tool` message to a model (see
+     * `composePrompt` in the run service). So the instruction reaches the model the same way, and the
+     * reader sees who spoke.
+     */
+    addAgentMessage(conversationId: string, content: string, options?: {
+        delivery?: Message["delivery"];
+    }): Promise<Message>;
     addUserMessage(conversationId: string, content: string, images?: MessageImage[], attachments?: import("./types.js").MessageAttachments, options?: {
         clientId?: string;
         delivery?: Message["delivery"];
@@ -578,6 +600,8 @@ export declare class Store {
      */
     clearPreparingToolCalls(conversationId: string, messageId: string, rows: readonly number[]): Promise<ToolCallBlock[]>;
     setStatus(conversationId: string, status: Conversation["status"]): Promise<void>;
+    /** Commit once at turn end; metadata transactions work for both JSON and SQLite repositories. */
+    recordConversationUsage(conversationId: string, readout: TurnUsageReadout): Promise<void>;
     /**
      * Records WHY a turn failed in a way the reader can see. `Conversation.error` is rendered as a red
      * banner above the transcript (`App.tsx:conversation-error`), and it is the only field that survives
@@ -594,6 +618,17 @@ export declare class Store {
      * going to act on it without sending another prompt first).
      */
     setFailureReason(conversationId: string, reason: string | undefined): Promise<void>;
+    /**
+     * Records WHY THIS CONVERSATION'S LAST ANSWER IS INCOMPLETE, in a way the reader can see.
+     *
+     * `Conversation.warning` is a different fact from `Conversation.error`: the run did not break, the
+     * answer was cut short by the model's output budget. The reader's next move is different too - a
+     * failed turn asks them to retry, a truncated one asks them to let the model continue - so the two
+     * are kept apart rather than sharing one field and one colour.
+     *
+     * Set to `undefined` to clear, which the next `addUserMessage` does anyway.
+     */
+    setWarningReason(conversationId: string, reason: string | undefined): Promise<void>;
     /** The plan a revert would carry out, without carrying it out. The server reads this to stop children first. */
     planRevert(conversationId: string, messageId: string, withdraw?: boolean): RevertPlan;
     /**

package/dist/server/store.js

@@ -153,7 +153,7 @@ function reconcileConversations(state) {
         // was sent) and the server died before any settled state was recorded. A conversation that was in
         // either of those two states when the process went away has a half-open turn whose outcome nobody
         // can determine from the file alone - exactly the situation this sweep exists to remove.
-        if (!conversation || (conversation.status !== "running" && conversation.status !== "waiting"))
+        if (!conversation || (conversation.status !== "running" && conversation.status !== "waiting" && conversation.status !== "awaiting_background"))
             continue;
         conversation.status = "failed";
         conversation.error = ORPHANED_CONVERSATION_ERROR;
@@ -722,6 +722,10 @@ export class Store {
         const workspace = this.state.workspaces.find((item) => item.id === workspaceId);
         return workspace ? { ...workspace } : undefined;
     }
+    /** Read every workspace as detached shallow copies. */
+    workspaces() {
+        return this.state.workspaces.map((item) => ({ ...item }));
+    }
     /** Read the app-wide default without cloning conversations or transcripts. */
     defaultModel() {
         const model = this.state.defaultModel;
@@ -1103,6 +1107,8 @@ export class Store {
             // the sidebar draws after a restart is the tree that was true when each session was opened.
             // Written only when present, so a conversation created without them (the user's own "+") reads
             // as a top-level one on every code path, including every state.json from before this field.
+            if (configuration.cwd)
+                conversation.cwd = configuration.cwd;
             if (configuration.parentConversationId)
                 conversation.parentConversationId = configuration.parentConversationId;
             if (configuration.origin)
@@ -1212,6 +1218,8 @@ export class Store {
             conversation.thinkingLevel = source.thinkingLevel;
         if (source.agentId)
             conversation.agentId = source.agentId;
+        if (source.cwd)
+            conversation.cwd = source.cwd;
         this.state.conversations.unshift(conversation);
         await this.persist();
         return structuredClone(conversation);
@@ -1230,7 +1238,7 @@ export class Store {
         const conversation = this.requireConversation(conversationId);
         if (conversation.archivedAt)
             return;
-        if (conversation.status === "running")
+        if (conversation.status === "running" || conversation.status === "awaiting_background")
             throw new Error("运行中的会话无法归档，请先停止运行");
         conversation.archivedAt = now();
         await this.persistMetadata(conversationId);
@@ -1350,6 +1358,32 @@ export class Store {
      * whatever was typed into a box that was not listening yet. `openTurnOnMessage` applies them at the
      * moment a turn genuinely begins.
      */
+    /**
+     * Writes ONE INSTRUCTION INTO THE TRANSCRIPT AS SOMETHING THE SYSTEM SAID.
+     *
+     * `addUserMessage` above is the only way a person's words come into being, and everything written
+     * through it wears the reader's own name and the reader's bubble. That is right for a person and
+     * wrong for the orchestrator: when a primary agent dispatches a task to a child session, the
+     * child receives an ORDER, not something the reader typed - and the child transcript showed it
+     * under the reader's avatar, so the reader saw their own name on an instruction they never wrote.
+     *
+     * The role is `tool` for a reason that is not cosmetic: `tool` is already the product's word for
+     * "the system delivered this", it renders as the 系统 side of the transcript rather than as a
+     * person, and Pi's queue already knows how to hand a `tool` message to a model (see
+     * `composePrompt` in the run service). So the instruction reaches the model the same way, and the
+     * reader sees who spoke.
+     */
+    async addAgentMessage(conversationId, content, options) {
+        const conversation = this.requireConversation(conversationId);
+        if (conversation.archivedAt)
+            throw new Error("无法向已归档的会话下发指令，请先恢复该会话");
+        const message = { id: id("message"), role: "tool", content, createdAt: now() };
+        if (options?.delivery)
+            message.delivery = options.delivery;
+        conversation.messages.push(message);
+        await this.persistMessages(conversation);
+        return structuredClone(message);
+    }
     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 -
@@ -1391,6 +1425,10 @@ export class Store {
         // the new turn starts: leaving it up would show "was interrupted, marked failed" above a conversation
         // that is visibly working again.
         delete conversation.error;
+        // THE SAME IS TRUE OF THE TRUNCATION WARNING. It describes the answer that was cut short, and a
+        // new turn is the reader answering that situation - so the notice belongs to the turn that just
+        // ended, not to the conversation from now on.
+        delete conversation.warning;
         // AN INCREMENTAL WRITE, NOT A FULL ONE. This line was the last full-state write on the hot path
         // of every message, and it was in front of the broadcast that tells the browser a turn has
         // started - so the size of the WHOLE state was the delay between clicking send and the stream
@@ -1836,6 +1874,26 @@ export class Store {
         return structuredClone(calls);
     }
     async setStatus(conversationId, status) { const conversation = this.requireConversation(conversationId); conversation.status = status; conversation.updatedAt = now(); await this.persistMetadata(conversationId); }
+    /** Commit once at turn end; metadata transactions work for both JSON and SQLite repositories. */
+    async recordConversationUsage(conversationId, readout) {
+        const conversation = this.requireConversation(conversationId);
+        if (readout.usage) {
+            const previous = conversation.usage;
+            const total = { ...readout.usage };
+            if (previous)
+                for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"])
+                    total[key] += previous[key];
+            conversation.usage = total;
+            conversation.usageCostKnown = (conversation.usageCostKnown ?? true) && readout.costKnown;
+        }
+        if (readout.contextUsage)
+            conversation.contextUsage = { ...readout.contextUsage };
+        else
+            delete conversation.contextUsage;
+        if (readout.usage || readout.contextUsage)
+            conversation.usageUpdatedAt = now();
+        await this.persistMetadata(conversationId);
+    }
     /**
      * Records WHY a turn failed in a way the reader can see. `Conversation.error` is rendered as a red
      * banner above the transcript (`App.tsx:conversation-error`), and it is the only field that survives
@@ -1860,6 +1918,25 @@ export class Store {
         conversation.updatedAt = now();
         await this.persistMetadata(conversationId);
     }
+    /**
+     * Records WHY THIS CONVERSATION'S LAST ANSWER IS INCOMPLETE, in a way the reader can see.
+     *
+     * `Conversation.warning` is a different fact from `Conversation.error`: the run did not break, the
+     * answer was cut short by the model's output budget. The reader's next move is different too - a
+     * failed turn asks them to retry, a truncated one asks them to let the model continue - so the two
+     * are kept apart rather than sharing one field and one colour.
+     *
+     * Set to `undefined` to clear, which the next `addUserMessage` does anyway.
+     */
+    async setWarningReason(conversationId, reason) {
+        const conversation = this.requireConversation(conversationId);
+        if (reason === undefined)
+            delete conversation.warning;
+        else
+            conversation.warning = reason;
+        conversation.updatedAt = now();
+        await this.persistMetadata(conversationId);
+    }
     /** The plan a revert would carry out, without carrying it out. The server reads this to stop children first. */
     planRevert(conversationId, messageId, withdraw = false) { return planRevert(this.state, conversationId, messageId, withdraw); }
     /**
@@ -2340,6 +2417,14 @@ export class Store {
             Object.assign(existing, summary);
         else
             this.state.backgroundTasks.unshift(summary);
+        if (summary.conversationId && summary.status === "running") {
+            const conv = this.state.conversations.find((c) => c.id === summary.conversationId);
+            if (conv && conv.status !== "running" && conv.status !== "waiting") {
+                conv.status = "awaiting_background";
+                conv.updatedAt = now();
+                await this.persistMetadata(conv.id);
+            }
+        }
         await this.persistCollections("backgroundTasks");
     }
     async removeBackgroundTask(id) {

package/dist/server/task-tool.d.ts

@@ -251,13 +251,14 @@ export declare function todoSummary(todos: readonly TodoItem[]): string;
  * `agents/super-pi-task/core.ts` is the other end; `scripts/task-tool.test.mjs` asserts the two copies agree.
  */
 export declare const ORCHESTRATOR_ENDPOINT_ENV = "SUPER_PI_ORCHESTRATOR_ENDPOINT";
+export declare const ORCHESTRATOR_WORKSPACE_ENV = "SUPER_PI_ORCHESTRATOR_WORKSPACE";
 /** Tool names registered with Pi. */
 export declare const SESSION_SPAWN_TOOL_NAME = "session_spawn";
 export declare const SESSION_STATUS_TOOL_NAME = "session_status";
 export declare const SESSION_DISPATCH_TOOL_NAME = "session_dispatch";
 export declare const SESSION_STOP_TOOL_NAME = "session_stop";
 /** Model-facing description for session_spawn. */
-export declare const SESSION_SPAWN_DESCRIPTION = "Create a new sibling conversation in the current workspace and immediately dispatch its initial task.\n\nDIFFERENCE FROM THE 'task' TOOL:\n- The 'task' tool delegates to a transient, one-shot subagent process (scout, critic, patcher) that runs once, returns its final text, and terminates. It has no conversation history and does not appear in the workspace sidebar.\n- 'session_spawn' creates a real, persistent sibling CONVERSATION in Super Pi. It appears in the sidebar, retains multi-turn message history, can receive follow-up messages via session_dispatch, can be inspected via session_status, and can be stopped via session_stop. The user can also switch to it in the Web UI.\n\nWHEN TO USE THIS:\n- Long-running, multi-phase tracks of work that require ongoing context, multiple turns of dialogue, or independent user visibility.\n- Parallel work streams (e.g., Track A: backend refactor, Track B: frontend component update) where both need full conversational capabilities.\n- When the user asks you to act as an orchestrator/manager who delegates to multiple sessions.\n\nWHEN NOT TO USE THIS:\n- For one-off, focused delegation with a single answer: use 'task' (with scout/critic/patcher). It is faster, cheaper, and returns directly to your transcript.\n- For running shell commands or build watchers: use 'run_async'.\n- For a linear multi-step subagent pipeline: use 'workflow'.\n\nUsage notes:\n1. Spawning is ASYNCHRONOUS by default: it creates the conversation, enqueues the initial task, and returns the new conversationId immediately. The sibling session runs in the background.\n2. The initial task should provide clear context and goals since the new session starts with a fresh conversation history.\n3. Use session_status with the returned conversationId to check progress, or session_dispatch to send further messages.\n4. The new session reports completion to its DIRECT parent automatically. 'parentConversationId' optionally selects that parent; by default it is the calling session.";
+export declare const SESSION_SPAWN_DESCRIPTION = "Create a new sibling conversation in the current workspace and immediately dispatch its initial task.\n\nDIFFERENCE FROM THE 'task' TOOL:\n- The 'task' tool delegates to a transient, one-shot subagent process (scout, critic, patcher) that runs once, returns its final text, and terminates. It has no conversation history and does not appear in the workspace sidebar.\n- 'session_spawn' creates a real, persistent sibling CONVERSATION in Super Pi. It appears in the sidebar, retains multi-turn message history, can receive follow-up messages via session_dispatch, can be inspected via session_status, and can be stopped via session_stop. The user can also switch to it in the Web UI.\n\nWHEN TO USE THIS:\n- Long-running, multi-phase tracks of work that require ongoing context, multiple turns of dialogue, or independent user visibility.\n- Parallel work streams (e.g., Track A: backend refactor, Track B: frontend component update) where both need full conversational capabilities.\n- When the user asks you to act as an orchestrator/manager who delegates to multiple sessions.\n\nWHEN NOT TO USE THIS:\n- For one-off, focused delegation with a single answer: use 'task' (with scout/critic/patcher). It is faster, cheaper, and returns directly to your transcript.\n- For running shell commands or build watchers: use 'run_async'.\n- For a linear multi-step subagent pipeline: use 'workflow'.\n\nUsage notes:\n1. Spawning is ASYNCHRONOUS by default: it creates the conversation, enqueues the initial task, and returns the new conversationId immediately. The sibling session runs in the background.\n2. The initial task should provide clear context and goals since the new session starts with a fresh conversation history.\n3. Use session_status with the returned conversationId to check progress, or session_dispatch to send further messages.\n4. The new session reports completion to its DIRECT parent automatically. 'parentConversationId' optionally selects that parent; by default it is the calling session.\n5. The new session always belongs to the calling session's workspace. Pass 'cwd' as a workspace-relative subdirectory (for example, 'packages/a') when it should work below the workspace root; absolute paths and traversal are rejected.\n6. Optionally pass 'model' to choose which model the NEW session runs on: {\"provider\":\"...\",\"modelId\":\"...\"} - the same \"provider/modelId\" pair the model picker shows, and BOTH halves are required. Leave 'model' out and the new session starts on the workspace default model.";
 /** Model-facing description for session_status. */
 export declare const SESSION_STATUS_DESCRIPTION = "Inspect the progress, run state, and latest activity of sibling conversations created by the orchestrator.\n\nWHEN TO USE THIS:\n- To check whether a spawned sibling conversation is still running, has finished (idle), is stopped, or encountered an error.\n- To read the latest assistant progress snippet without bloating your context with the session's entire raw message transcript.\n- To list all sibling conversations under your coordination when conversationId is omitted.\n\nUsage notes:\n1. When 'conversationId' is provided: returns a compact summary for that specific session, including its run status ('idle', 'running', 'waiting', 'stopped', 'failed'), messageCount, turnCount, lastAssistantSnippet, lastUserSnippet, activeTool, and error (if any).\n2. When 'conversationId' is omitted: returns a summary list of sibling conversations whose direct parent is 'parentConversationId' (the calling session by default).\n3. By default it never returns full transcripts; concise summaries keep your context window lean. Set 'includeOutput' with a conversationId to read the final output from its result file, capped to the last 64Ki characters with an explicit truncation notice.";
 /** Model-facing description for session_dispatch. */

package/dist/server/task-tool.js

@@ -356,6 +356,7 @@ export function todoSummary(todos) {
  * `agents/super-pi-task/core.ts` is the other end; `scripts/task-tool.test.mjs` asserts the two copies agree.
  */
 export const ORCHESTRATOR_ENDPOINT_ENV = "SUPER_PI_ORCHESTRATOR_ENDPOINT";
+export const ORCHESTRATOR_WORKSPACE_ENV = "SUPER_PI_ORCHESTRATOR_WORKSPACE";
 /** Tool names registered with Pi. */
 export const SESSION_SPAWN_TOOL_NAME = "session_spawn";
 export const SESSION_STATUS_TOOL_NAME = "session_status";
@@ -382,7 +383,9 @@ Usage notes:
 1. Spawning is ASYNCHRONOUS by default: it creates the conversation, enqueues the initial task, and returns the new conversationId immediately. The sibling session runs in the background.
 2. The initial task should provide clear context and goals since the new session starts with a fresh conversation history.
 3. Use session_status with the returned conversationId to check progress, or session_dispatch to send further messages.
-4. The new session reports completion to its DIRECT parent automatically. 'parentConversationId' optionally selects that parent; by default it is the calling session.`;
+4. The new session reports completion to its DIRECT parent automatically. 'parentConversationId' optionally selects that parent; by default it is the calling session.
+5. The new session always belongs to the calling session's workspace. Pass 'cwd' as a workspace-relative subdirectory (for example, 'packages/a') when it should work below the workspace root; absolute paths and traversal are rejected.
+6. Optionally pass 'model' to choose which model the NEW session runs on: {"provider":"...","modelId":"..."} - the same "provider/modelId" pair the model picker shows, and BOTH halves are required. Leave 'model' out and the new session starts on the workspace default model.`;
 /** Model-facing description for session_status. */
 export const SESSION_STATUS_DESCRIPTION = `Inspect the progress, run state, and latest activity of sibling conversations created by the orchestrator.
 

package/dist/server/terminal.d.ts

@@ -104,6 +104,7 @@ export type TerminalCommand = {
     type: "terminal.open";
     sessionId: string;
     workspaceId: string;
+    cwd?: string;
     cols?: number;
     rows?: number;
 } | {

package/dist/server/terminal.js

@@ -52,6 +52,7 @@ import { createRequire } from "node:module";
 import { existsSync, accessSync, constants } from "node:fs";
 import { delimiter, join } from "node:path";
 import { isLocalOrPrivateAddress } from "./http-server.js";
+import { resolveSessionCwd } from "./session-cwd.js";
 let ptyModule;
 let ptyLoadFailure;
 /**
@@ -305,10 +306,11 @@ export class TerminalService {
                 send({ type: "terminal.error", sessionId: command.sessionId, message: "工作区不存在，无法打开终端。" });
                 return;
             }
+            const cwd = await resolveSessionCwd(workspace.path, command.cwd);
             // A workspace whose directory was deleted or renamed must not spawn a shell in `process.cwd()`,
             // which would silently run the terminal in the SERVER's directory instead of an error.
-            if (!existsSync(workspace.path)) {
-                send({ type: "terminal.error", sessionId: command.sessionId, message: `工作区目录不存在：${workspace.path}` });
+            if (!existsSync(cwd)) {
+                send({ type: "terminal.error", sessionId: command.sessionId, message: `会话工作目录不存在：${cwd}` });
                 return;
             }
             const pty = loadPty();
@@ -319,7 +321,7 @@ export class TerminalService {
                 name: "xterm-256color",
                 cols: clamp(command.cols, MIN_COLS, MAX_COLS, 80),
                 rows: clamp(command.rows, MIN_ROWS, MAX_ROWS, 24),
-                cwd: workspace.path,
+                cwd,
                 env: { ...process.env, TERM: "xterm-256color" },
             });
             const session = { pty: child, closed: false, killed: false, pending: "" };