@evandu/super-pi 0.1.146 → 0.1.148

package/dist/server/pi-session-pool.js

@@ -25,6 +25,7 @@ import { join } from "node:path";
 import { createPiSession, sameFingerprint, superPiExtensionPaths, superPiSkillPaths, } from "./pi-session.js";
 /** How long an idle session survives before it is evicted. */
 const IDLE_EVICTION_MS = 10 * 60_000;
+const MAX_LIVE_SESSIONS = Math.max(4, Number.parseInt(process.env.SUPER_PI_MAX_LIVE_SESSIONS ?? "32", 10) || 32);
 /**
  * The environment variable the session's credential travels in.
  *
@@ -119,6 +120,7 @@ export class PiSessionPool {
      * tool allowlist has changed.
      */
     async acquire(request) {
+        await this.evictOverflow(request.conversationId);
         const fingerprint = this.fingerprintOf(request);
         const existing = this.sessions.get(request.conversationId);
         if (existing) {
@@ -182,6 +184,20 @@ export class PiSessionPool {
             throw error;
         }
     }
+    /** Keep an accidental session fan-out from retaining one full transcript context per conversation. */
+    async evictOverflow(exceptConversationId) {
+        if (this.sessions.size < MAX_LIVE_SESSIONS)
+            return;
+        const candidates = [...this.sessions.entries()]
+            .filter(([id, entry]) => id !== exceptConversationId && !entry.building)
+            .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt);
+        while (this.sessions.size >= MAX_LIVE_SESSIONS && candidates.length) {
+            const [conversationId] = candidates.shift();
+            if (process.env.SUPER_PI_TRACE_LATENCY === "1")
+                console.warn(`[super-pi latency] conversation=${conversationId} phase=session.max-live-evict`);
+            await this.evict(conversationId);
+        }
+    }
     async build(request, fingerprint) {
         const creation = {
             cwd: request.cwd,

package/dist/server/runtime.js

@@ -18,12 +18,13 @@ import { TASK_CAPABILITY_ENV, mintCapability, releaseCapability } from "./capabi
 import { resolvePiCommand, shellQuote } from "./pi-command.js";
 import { PiSessionPool, repositoryRootFrom } from "./pi-session-pool.js";
 import { describeDeliveredUserMessage, describePiQueue, handleSessionEvent, TurnQueue } from "./pi-session-events.js";
+import { LengthExceededError } from "./turn-failure.js";
 // The queue/steer recognisers live in pi-session-events.ts, where the SESSION path's bridge can use
 // them; the one-shot drain loop below reads the same records through the same two functions, so both
 // paths recognise a delivery identically. Re-exported because they were part of this module's surface.
 export { describeDeliveredUserMessage, describePiQueue } from "./pi-session-events.js";
 import { createPiSession, createSdkCatalog, piSdkAvailable, resolveTranscriptFile, superPiExtensionPaths } from "./pi-session.js";
-import { TASK_CONVERSATION_ENV, PARENT_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, SCHEDULED_TASK_ENDPOINT_ENV, SCHEDULED_TASK_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, ORCHESTRATOR_ENDPOINT_ENV, ORCHESTRATOR_WORKSPACE_ENV, SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, rosterPayload, } from "./task-tool.js";
+import { TASK_CONVERSATION_ENV, PARENT_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, SCHEDULED_TASK_ENDPOINT_ENV, SCHEDULED_TASK_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, ORCHESTRATOR_ENDPOINT_ENV, ORCHESTRATOR_WORKSPACE_ENV, SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, SESSION_REPORT_TOOL_NAME, rosterPayload, } from "./task-tool.js";
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
 import { describeToolCall, describeToolCallArgs, describeToolCallInProgress, extractPartialResultText, extractToolResultText, readQuestionCall } from "./tool-calls.js";
@@ -1259,7 +1260,7 @@ export class PiRpcRuntime {
         if (process.env.SUPER_PI_FEISHU_ENDPOINT)
             names.push(FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME);
         if (this.options.orchestratorEndpoint)
-            names.push(SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME);
+            names.push(SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, SESSION_REPORT_TOOL_NAME);
         return names;
     }
     /**
@@ -1478,7 +1479,7 @@ export class PiRpcRuntime {
         // allowlist and naming a tool Pi has not registered would change the spawn line for every other
         // mode. The prompt asks for a bare JSON array and nothing else; if the model spends a turn on a
         // tool call anyway the reranker times out and falls back to the lexical order.
-        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, SCHEDULED_TASK_TOOL_NAME, "question", "tool_register", ...(this.options.orchestratorEndpoint ? [SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME] : [])] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME, KNOWLEDGE_IMPORT_TOOL_NAME] : []), ...(documentsEnabled ? [DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME] : []), ...(webEnabled ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME] : []), ...(feishuEnabled ? [FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME] : [])] });
+        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, SCHEDULED_TASK_TOOL_NAME, "question", "tool_register", ...(this.options.orchestratorEndpoint ? [SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, SESSION_REPORT_TOOL_NAME] : [])] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME, KNOWLEDGE_IMPORT_TOOL_NAME] : []), ...(documentsEnabled ? [DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME] : []), ...(webEnabled ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME] : []), ...(feishuEnabled ? [FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME] : [])] });
         // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
         // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
         if (!this.pi.found)
@@ -1604,7 +1605,7 @@ export class PiRpcRuntime {
                 if (reason === "aborted")
                     throw new Error(outcome.errorMessage || "Pi 意外中止了本轮回答。");
                 if (reason === "length")
-                    throw new Error(outcome.errorMessage || "模型输出达到本轮长度上限，回答未完成。");
+                    throw new LengthExceededError(outcome.errorMessage || "模型输出达到本轮长度上限，回答未完成。");
             };
             let firstPiRecord = true;
             // Nothing may be dropped without a trace. Pi emits a wide, open-ended family of agent

package/dist/server/session-tree-scope.d.ts

@@ -0,0 +1,125 @@
+import type { Store } from "./store.js";
+/**
+ * THE SESSION TREE'S SCOPE RULE.
+ *
+ * A session may only manage its DIRECT children: the sessions whose `parentConversationId` is
+ * exactly its own id. Nothing else. A grandchild is a level away, a peer sits in somebody else's
+ * branch, an ancestor is above - none of them is this session's subordinate, so none of them may be
+ * dispatched to, read, stopped or resumed by it. A workspace is NOT an organisation chart: two
+ * supervisors can sit in the same workspace without being each other's subordinates.
+ *
+ * WHY THE RULE IS ONE LINE. The tree edge is written on the conversation itself at birth
+ * (`parentConversationId`), so "is this session my child?" is a comparison, not a walk. The walk up
+ * the chain exists for ONE purpose only: writing a refusal that says WHY, so the reader knows
+ * whether it asked for a peer, a grandchild or somebody else's department. The walk NEVER decides
+ * anything - a refusal is a refusal because the parent is not the caller, never because the walk
+ * came back empty.
+ *
+ * WHY THIS MATTERS AT ALL. The result callback of a dispatched session goes back to the session that
+ * OWNS it - the one whose id is the target's `parentConversationId`. If a session could dispatch to
+ * a session it does not own, that session's result would report to somebody else, and the tree the
+ * user sees in the sidebar would stop being the tree the work actually flows through. Making the
+ * target's parent be the caller is what keeps "who gave the order is who gets the report" true by
+ * construction.
+ */
+/** How the caller and the target relate in the session tree. Computed for the MESSAGE only. */
+export type SessionRelation = "self" | "direct-child" | "descendant" | "ancestor" | "peer" | "other-root" | "unrelated";
+/** The outcome of a scope check: allowed, or a refusal with the status code and the reason. */
+export type ScopeVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/** The verb a refusal is about, so the message reads like the action that was refused. */
+export type ScopeVerb = "调度" | "读取" | "停止" | "恢复" | "列出" | "看护";
+/** What the caller was trying to reach: a session to manage, a session's children, or a parent to claim. */
+export type ScopeSubject = "manage" | "list-children" | "declare-parent";
+/** The narrow slice of the store this file needs. */
+type ConversationReader = Pick<Store, "conversation">;
+/**
+ * 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 declare const classifySessionRelation: (store: ConversationReader, callerConversationId: string, targetConversationId: string) => SessionRelation;
+/**
+ * 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 declare const describeScopeRefusal: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    targetConversationId: string;
+    verb: ScopeVerb;
+    subject: ScopeSubject;
+}) => string;
+/**
+ * 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 declare const verifyDirectChildScope: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    targetConversationId: string;
+    verb?: ScopeVerb;
+}) => ScopeVerdict;
+/**
+ * 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 declare const verifyListParentScope: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    requestedParentId?: string;
+}) => ScopeVerdict;
+/**
+ * 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 declare const verifyReportTargetScope: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    targetConversationId: string;
+}) => ScopeVerdict;
+/**
+ * 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 declare const verifySpawnParentScope: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    requestedParentId?: string;
+}) => ScopeVerdict;
+export {};

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

@@ -120,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. */
@@ -616,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;
     /**