@evandu/super-pi 0.1.165 → 0.1.166

package/dist/client/index.html

@@ -8,8 +8,8 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-BUTxkA3D.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Wtlj0s4R.css">
+    <script type="module" crossorigin src="/assets/index-dARLbQ-8.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-C6YWfUu2.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/agents.d.ts

@@ -175,6 +175,16 @@ export interface ResolveAgentDirectoriesOptions {
     env?: NodeJS.ProcessEnv;
     rootDir?: string;
 }
+/**
+ * The agents directory that ships WITH the package: the definitions Super Pi itself carries.
+ *
+ * WHY IT IS A FUNCTION AND NOT A CONSTANT. The package root is not the same directory in every
+ * layout - it is the repository root in a checkout and the installed package root in an npm install
+ * - so the path is derived from the same `rootDir` the discovery uses, and both sides of the
+ * "is this built-in?" question ask THIS function. If the two ever disagreed, a user agent could be
+ * filed as built-in and a built-in one as the user's, and the picker would sort them wrongly.
+ */
+export declare function builtinAgentsDir(rootDir?: string): string;
 /**
  * Resolves the ordered list of directories to discover agents from:
  * 1. Custom directories configured by the user in app settings (or options)
@@ -187,6 +197,7 @@ export interface ResolveAgentDirectoriesOptions {
 export declare function resolveAgentDirectories(options?: ResolveAgentDirectoriesOptions): string[];
 export declare function readAgents(directory: string | readonly string[], options?: {
     mode?: AgentModeFilter;
+    builtinDir?: string;
 }): Promise<AgentScan>;
 /** Parses one definition file, or returns the reason it is not a usable agent. */
 export declare function parseDefinition(file: string, source: string): AgentDefinition | AgentProblem;

package/dist/server/agents.js

@@ -392,6 +392,18 @@ export function expandTilde(filepath) {
     }
     return filepath;
 }
+/**
+ * The agents directory that ships WITH the package: the definitions Super Pi itself carries.
+ *
+ * WHY IT IS A FUNCTION AND NOT A CONSTANT. The package root is not the same directory in every
+ * layout - it is the repository root in a checkout and the installed package root in an npm install
+ * - so the path is derived from the same `rootDir` the discovery uses, and both sides of the
+ * "is this built-in?" question ask THIS function. If the two ever disagreed, a user agent could be
+ * filed as built-in and a built-in one as the user's, and the picker would sort them wrongly.
+ */
+export function builtinAgentsDir(rootDir) {
+    return resolve(join(rootDir ?? resolve(import.meta.dirname, "../.."), "agents"));
+}
 /**
  * Resolves the ordered list of directories to discover agents from:
  * 1. Custom directories configured by the user in app settings (or options)
@@ -433,11 +445,25 @@ export function resolveAgentDirectories(options = {}) {
         catch {
             // homedir() might throw in restricted sandbox environments
         }
-        const root = options.rootDir ?? resolve(import.meta.dirname, "../..");
-        add(join(root, "agents"));
+        add(builtinAgentsDir(options.rootDir));
     }
     return dirs;
 }
+/**
+ * Whether two paths name the same directory.
+ *
+ * WHY THE COMPARISON IS NOT A PLAIN `===`. The paths that reach here were built by joining and
+ * resolving, so they are already absolute - but Windows paths are case-insensitive and a directory
+ * typed by hand (`d:\agents`) is the same directory as the one the app resolved itself
+ * (`D:\Agents`). Comparing them as strings would call the package's own agents directory "the user's"
+ * and put the built-in agents at the bottom of the picker, which is the defect this whole change is
+ * about.
+ */
+function sameDirectory(left, right) {
+    const a = resolve(left);
+    const b = resolve(right);
+    return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
 export async function readAgents(directory, options = {}) {
     const mode = options.mode ?? "primary";
     const rawDirs = Array.isArray(directory) ? directory : [directory];
@@ -445,6 +471,9 @@ export async function readAgents(directory, options = {}) {
     const agents = [];
     const problems = [];
     const seenIds = new Set();
+    // The directory whose definitions are the PACKAGE'S OWN. Everything else is the user's, and the
+    // two are listed separately so the package's agents can come first (see the sort at the end).
+    const builtinDir = options.builtinDir ?? builtinAgentsDir();
     for (const dir of dirs) {
         let entries;
         try {
@@ -455,6 +484,7 @@ export async function readAgents(directory, options = {}) {
                 continue;
             throw error;
         }
+        const isBuiltin = sameDirectory(dir, builtinDir);
         for (const file of entries.filter((name) => name.toLowerCase().endsWith(".md")).sort()) {
             // A FILE THAT CANNOT BE READ IS THE SAME KIND OF PROBLEM AS ONE THAT CANNOT BE PARSED.
             //
@@ -487,17 +517,31 @@ export async function readAgents(directory, options = {}) {
             else {
                 if (!seenIds.has(parsed.id)) {
                     seenIds.add(parsed.id);
-                    agents.push({ ...parsed, sourceDir: dir });
+                    agents.push({ ...parsed, sourceDir: dir, builtin: isBuiltin });
                 }
             }
         }
     }
     // The half that was NOT asked for is filtered out here rather than marked in the UI: sub-agents are
     // invoked BY an agent and never chosen by a human, so listing one in the picker would promise a role
-    // the runtime cannot honour. The remainder is alphabetical by id, so either roster reads as a list
-    // rather than as a directory listing.
+    // the runtime cannot honour.
+    //
+    // The remainder is the PACKAGE'S OWN agents first, then the user's, each group alphabetical by id.
+    //
+    // WHY THE BUILT-IN GROUP COMES FIRST. The picker used to sort purely by id, which scattered the
+    // package's own agents - the ones drawn with a colour dot - among the user's own with no visible
+    // rule to say which was which. The built-in group is now a group, so the colours read as "these are
+    // the ones that ship with Super Pi" instead of as noise.
+    //
+    // WHY THE GROUP ORDER DOES NOT TOUCH THE OVERRIDE RULE. The rule that decides WHICH definition of
+    // an id survives was applied above, while reading: the first directory to offer an id wins, and the
+    // user's directories are read before the package's own. Sorting here only reorders definitions that
+    // already survived that decision, so a user's copy of a built-in agent still wins - and it is then
+    // listed as the user's, because it IS the user's file.
     return {
-        agents: agents.filter((agent) => agent.mode === mode).sort((a, b) => a.id.localeCompare(b.id)),
+        agents: agents
+            .filter((agent) => agent.mode === mode)
+            .sort((a, b) => (a.builtin === b.builtin ? a.id.localeCompare(b.id) : a.builtin ? -1 : 1)),
         problems,
     };
 }

package/dist/server/application/project-service.js

@@ -521,7 +521,15 @@ export class ProjectService {
            report zero running agents. The concurrency guard is not touched by this: the in-flight task
            it counts (`reserved`) already covers the busy leader, so the cap behaves exactly as before. */
         const leaderIsWorker = lightweight(p) && p.ownerConversationId !== undefined;
-        return { tokens: sessions.reduce((sum, s) => sum + s.tokens, 0) + runs.reduce((sum, r) => sum + tokens(r.usage), 0),
+        /* ONE ACCOUNTING PATH, AND IT IS THE SESSION TREE.
+           The number below is the sum of the member sessions' usage, and NOTHING ELSE. A one-shot call
+           (a sub-agent) used to be added here from the run records on top of that sum, which was a
+           SECOND path to the same money: the run's usage was already inside the conversation's usage
+           (the store folds it in when the run settles), so the same tokens were counted twice.
+           Now it is counted once - through the session - and a project's budget therefore includes what
+           its one-shot calls cost, which is the whole point of a budget a person can predict.
+           See `Store.accountSubagentUsage`. */
+        return { tokens: sessions.reduce((sum, s) => sum + s.tokens, 0),
             usageKnown: sessions.length > 0 && sessions.every((s) => Boolean(this.store.conversation(s.id)?.usage)) && runs.every((r) => Boolean(r.usage)),
             activeWorkers: sessions.filter((s) => (!coordinatorIds.has(s.id) || (leaderIsWorker && s.id === p.ownerConversationId)) && busy(s.status)).length + runs.filter((r) => r.status === "running").length,
             // THE PROJECT'S OWN MEMORY TREE, named once so the client does not have to infer it from
@@ -679,7 +687,9 @@ export class ProjectService {
         lines.push(`- 预算上限：${p.budget?.maxTokens ?? DEFAULT_MAX_TOKENS} Token`);
         // THE USAGE IS REPORTED IN THE SAME BILLING-EQUIVALENT UNITS THE BUDGET IS SPENT IN, and the
         // formula is printed next to the number: a budget nobody can predict is a budget nobody trusts.
-        lines.push(`- 已用等效 Token：${this.resources(p).tokens}（口径：输入 + 输出 + 缓存写入×${CACHE_WRITE_WEIGHT} + 缓存读取×${CACHE_READ_WEIGHT}，取整）`);
+        // The sentence after the formula says what the number INCLUDES - a one-shot call (a sub-agent)
+        // is part of it, so a reader who dispatches children can see what that cost them.
+        lines.push(`- 已用等效 Token：${this.resources(p).tokens}（口径：输入 + 输出 + 缓存写入×${CACHE_WRITE_WEIGHT} + 缓存读取×${CACHE_READ_WEIGHT}，取整；含项目内的一次性调用（subagent））`);
         lines.push(`- 任务：共 ${p.tasks.length} 个，已完成 ${p.tasks.filter((t) => t.status === "completed").length} 个`);
         lines.push("", "## 交付与验收", "");
         if (!p.tasks.length)

package/dist/server/store.d.ts

@@ -924,6 +924,23 @@ export declare class Store {
      * as durable as the conversation it belongs to.
      */
     setSubagentRun(runId: string, changes: SubagentRunUpdate): Promise<SubagentRun>;
+    /**
+     * Adds ONE settled run's usage to the ledger of the conversation that dispatched it.
+     *
+     * CALLED AT THE SETTLE, ONCE PER RUN, and the run's FINAL accumulated usage is what it reads - the
+     * run record already holds the total of every finished message the child produced, so nothing is
+     * re-derived here and no message is counted twice.
+     *
+     * THE FLAG AND THE LEDGER ENTRY ARE WRITTEN IN ONE WRITE, and that is the whole crash-safety
+     * argument: `foldRunUsage` mutates both in the same synchronous block and this persists the state
+     * once, so a server that dies here cannot leave the money counted twice (flag written, entry not)
+     * or not at all (entry written, flag not). A run that was folded already is left alone, so calling
+     * this twice is a no-op rather than a second bill.
+     *
+     * IT PERSISTS THE WHOLE STATE rather than the two rows, because the two rows ARE one fact: the
+     * run's flag and the conversation's ledger entry have to become true together or not at all.
+     */
+    accountSubagentUsage(runId: string): Promise<boolean>;
     /**
      * Replaces the model's task list, and persists it.
      *

package/dist/server/store.js

@@ -105,6 +105,71 @@ function reconcileSubagentRuns(state) {
     }
     return orphaned;
 }
+/**
+ * ONE RUN'S USAGE, FOLDED INTO THE LEDGER OF THE CONVERSATION THAT DISPATCHED IT.
+ *
+ * WHY THE CHILD'S MONEY BELONGS TO THE PARENT'S LEDGER. A one-shot call spends real money on a
+ * child Pi, and the only number a budget is compared against is a conversation's `usage`. A ledger
+ * that held the parent's own turns alone would let a conversation multiply its real cost past its
+ * own cap simply by dispatching children instead of answering - which is precisely what design §5
+ * exists to prevent ("写预算的人必须能自己算出这个数是多少钱"). So the child's FINAL accumulated
+ * usage is added to the parent's, once, when the run settles.
+ *
+ * ONCE, AND ONLY ONCE, AND WHY THE FLAG IS THE WHOLE MECHANISM. A run reports its usage on every
+ * finished assistant message, and the recorder settles the run with the run's TOTAL - so folding
+ * per message would bill every message twice. The fold therefore happens once, on the settled run,
+ * and `usageAccounted` says which side of that line the run is on. The flag and the ledger entry
+ * are written in ONE store write, so a server that dies between them cannot leave the money
+ * counted twice or not at all.
+ *
+ * THE FIELDS ARE ADDED, NOT RE-DERIVED. A conversation's usage and a run's usage are the same
+ * shape (`input` / `output` / `cacheRead` / `cacheWrite` / `cost` / `turns`), so the sum is a sum -
+ * no second pricing formula, and no place where the two could disagree about what a token costs.
+ *
+ * A RUN WITH NO CONVERSATION IS NOT FOLDED, and is not an error: the conversation it belonged to
+ * was deleted while the child was running, so there is no ledger left to add to. Deleting a
+ * conversation deletes its runs too, so the money is not counted twice either - it is simply not
+ * counted, because nobody is left to be billed for it.
+ */
+function foldRunUsage(state, run) {
+    if (!run?.usage || run.usageAccounted)
+        return false;
+    const conversation = (state.conversations ?? []).find((item) => item?.id === run.conversationId);
+    if (!conversation)
+        return false;
+    const previous = conversation.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+    conversation.usage = {
+        input: previous.input + run.usage.input,
+        output: previous.output + run.usage.output,
+        cacheRead: previous.cacheRead + run.usage.cacheRead,
+        cacheWrite: previous.cacheWrite + run.usage.cacheWrite,
+        cost: previous.cost + run.usage.cost,
+        turns: previous.turns + run.usage.turns,
+    };
+    conversation.usageUpdatedAt = now();
+    run.usageAccounted = true;
+    return true;
+}
+/**
+ * THE STARTUP SWEEP FOR RUNS THAT PREDATE THE LEDGER.
+ *
+ * A `state.json` written before the conversation ledger existed holds runs whose usage was never
+ * added to the conversation that dispatched them - because at the time, nothing did that. Left
+ * alone, the project's budget would silently DROP for every project that had already spent money
+ * on one-shot calls, which is the kind of change nobody can explain afterwards.
+ *
+ * So every run that carries usage and has not been accounted for is folded in here, once, on the
+ * next boot. The flag makes the sweep idempotent: a run folded by this sweep is flagged, and the
+ * next boot leaves it alone. Mutated in place, like every other sweep in this file, and persisted
+ * by the single write `open` performs when this reports a change.
+ */
+function foldUnaccountedRunUsage(state) {
+    let folded = 0;
+    for (const run of state.subagentRuns ?? [])
+        if (foldRunUsage(state, run))
+            folded += 1;
+    return folded;
+}
 /**
  * Why a conversation the previous process left `running` is failed, in the same spirit and for the same
  * audience as `ORPHANED_RUN_ERROR`: this lands in a field the chat pane renders verbatim, so it names the
@@ -634,11 +699,15 @@ export class Store {
             const interrupted = reconcileConversations(state);
             const requeued = reconcileWaitingMessages(state);
             const todos = reconcileTodos(state);
+            // THE USAGE SWEEP. A run recorded before the conversation ledger existed has its money sitting in
+            // the run record and nowhere else, so the ledger is brought up to date here - once, and only
+            // for the runs that carry usage and have not been accounted for.
+            const foldedUsage = foldUnaccountedRunUsage(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 (defaulted || orphaned.length || orphanedWorkflows.length || orphanedTasks.changed || interrupted.length || requeued.recovered.length || requeued.changed || todos.changed) {
+            if (defaulted || orphaned.length || orphanedWorkflows.length || orphanedTasks.changed || interrupted.length || requeued.recovered.length || requeued.changed || todos.changed || foldedUsage) {
                 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)
@@ -660,6 +729,10 @@ export class Store {
                     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.`);
+                // Announced, because a budget that silently changed shape is a budget nobody can explain: this
+                // says the money those runs spent is now part of the conversations that dispatched them.
+                if (foldedUsage)
+                    console.warn(`Super Pi: the usage of ${foldedUsage} sub-agent run(s) recorded before the usage ledger existed was added to the conversations that dispatched them.`);
                 await store.persist();
             }
             return store;
@@ -2542,6 +2615,29 @@ export class Store {
         await this.persistTransaction({ kind: "subagent.replace", run: structuredClone(run) });
         return structuredClone(run);
     }
+    /**
+     * Adds ONE settled run's usage to the ledger of the conversation that dispatched it.
+     *
+     * CALLED AT THE SETTLE, ONCE PER RUN, and the run's FINAL accumulated usage is what it reads - the
+     * run record already holds the total of every finished message the child produced, so nothing is
+     * re-derived here and no message is counted twice.
+     *
+     * THE FLAG AND THE LEDGER ENTRY ARE WRITTEN IN ONE WRITE, and that is the whole crash-safety
+     * argument: `foldRunUsage` mutates both in the same synchronous block and this persists the state
+     * once, so a server that dies here cannot leave the money counted twice (flag written, entry not)
+     * or not at all (entry written, flag not). A run that was folded already is left alone, so calling
+     * this twice is a no-op rather than a second bill.
+     *
+     * IT PERSISTS THE WHOLE STATE rather than the two rows, because the two rows ARE one fact: the
+     * run's flag and the conversation's ledger entry have to become true together or not at all.
+     */
+    async accountSubagentUsage(runId) {
+        const run = this.state.subagentRuns.find((item) => item.id === runId);
+        if (!foldRunUsage(this.state, run))
+            return false;
+        await this.persist();
+        return true;
+    }
     /**
      * Replaces the model's task list, and persists it.
      *

package/dist/server/subagent-runs.js

@@ -305,7 +305,7 @@ export class SubagentRunRecorder {
             // `output`; the streamed copy is only a fallback for a child that never sent a `done`.
             const output = result.finalText || streamed;
             const truncated = output.length > PER_TASK_OUTPUT_CAP;
-            return await settle({
+            const settled = await settle({
                 status: "completed",
                 output: truncated ? output.slice(0, PER_TASK_OUTPUT_CAP) : output,
                 // `undefined` rather than `false`: the key is absent on an untruncated run, so it serializes
@@ -321,6 +321,24 @@ export class SubagentRunRecorder {
                 failure: undefined,
                 finishedAt: new Date().toISOString(),
             });
+            // THE CHILD'S MONEY IS THE CALLER'S MONEY, AND IT IS ADDED ONCE.
+            //
+            // The run has just been settled with its FINAL accumulated usage, and that is the number the
+            // dispatching conversation's ledger is given - not one message's worth, and not one addition
+            // per message the child produced. A project budget reads the conversation's ledger, so a child
+            // that is not in there is a child nobody is charged for.
+            //
+            // A FAILURE HERE IS ANNOUNCED AND SWALLOWED: the run record is already on disk, so the work is
+            // real and recorded, and losing the ledger entry must not turn a finished run into a failed one.
+            // The next start folds it in - the startup sweep accounts for every run whose usage has not been
+            // accounted for - so the money is late rather than lost.
+            try {
+                await this.hooks.store.accountSubagentUsage(id);
+            }
+            catch (error) {
+                console.warn(`Super Pi: the usage of sub-agent run ${id} could not be added to the usage of conversation ${conversationId}: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+            return settled;
         }
         catch (error) {
             const stopped = error instanceof SubagentCancelled;

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

@@ -262,7 +262,7 @@ export declare const SESSION_STOP_TOOL_NAME = "session_stop";
 export declare const SESSION_REPORT_TOOL_NAME = "session_report";
 export declare const SESSION_STOP_SUBTREE_TOOL_NAME = "session_stop_subtree";
 /** 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.\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.\n7. Optionally pass 'watchdogTimeoutSeconds' to declare how long YOU are willing to wait for a report before you want to be reminded: a positive number of seconds. If the new session stays silent that long, you receive a '[Watchdog \u63D0\u9192]' message naming it. A report from the child (session_report) restarts the clock; the watchdog never stops the child. Leave it out to run without a watchdog.";
+export declare const SESSION_SPAWN_DESCRIPTION = "Create a child conversation in the current workspace and immediately dispatch its initial task. You can specify a primary agent as the child's role.\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 child 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- Multi-phase or complex work where the user needs each step to be visible and available for inspection or intervention: create a child session with session_spawn.\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 single one-off delegation with a single answer: use 'task'.\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.\n7. Optionally pass 'watchdogTimeoutSeconds' to declare how long YOU are willing to wait for a report before you want to be reminded: a positive number of seconds. If the new session stays silent that long, you receive a '[Watchdog \u63D0\u9192]' message naming it. A report from the child (session_report) restarts the clock; the watchdog never stops the child. Leave it out to run without a watchdog.";
 /** 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

@@ -367,21 +367,22 @@ export const SESSION_STOP_TOOL_NAME = "session_stop";
 export const SESSION_REPORT_TOOL_NAME = "session_report";
 export const SESSION_STOP_SUBTREE_TOOL_NAME = "session_stop_subtree";
 /** Model-facing description for session_spawn. */
-export const SESSION_SPAWN_DESCRIPTION = `Create a new sibling conversation in the current workspace and immediately dispatch its initial task.
+export const SESSION_SPAWN_DESCRIPTION = `Create a child conversation in the current workspace and immediately dispatch its initial task. You can specify a primary agent as the child's role.
 
 DIFFERENCE FROM THE 'task' TOOL:
 - 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.
-- '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.
+- 'session_spawn' creates a real, persistent child 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.
 
 WHEN TO USE THIS:
 - Long-running, multi-phase tracks of work that require ongoing context, multiple turns of dialogue, or independent user visibility.
+- Multi-phase or complex work where the user needs each step to be visible and available for inspection or intervention: create a child session with session_spawn.
 - Parallel work streams (e.g., Track A: backend refactor, Track B: frontend component update) where both need full conversational capabilities.
 - When the user asks you to act as an orchestrator/manager who delegates to multiple sessions.
 
 WHEN NOT TO USE THIS:
 - 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.
 - For running shell commands or build watchers: use 'run_async'.
-- For a linear multi-step subagent pipeline: use 'workflow'.
+- For a single one-off delegation with a single answer: use 'task'.
 
 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.

package/dist/server/types.d.ts

@@ -464,7 +464,17 @@ export type Conversation = {
     status: RunStatus;
     messages: Message[];
     archivedAt?: string;
-    /** Cumulative primary-assistant usage observed since readout collection began; excludes subagents. */
+    /**
+     * Cumulative usage observed for this conversation: its OWN assistant messages AND the one-shot
+     * (sub-agent) calls it dispatched.
+     *
+     * THE SUB-AGENT'S USAGE IS IN HERE ON PURPOSE. A child Pi spends real money, and a budget that
+     * only counts the parent's own turns is a budget that can be multiplied past its own cap by
+     * dispatching children instead of answering - which is exactly what design §5 forbids, because
+     * "写预算的人必须能自己算出这个数是多少钱" is only true if the number includes every call the
+     * conversation made. The child's final accumulated usage is folded in ONCE, when the run settles
+     * (see `Store.accountSubagentUsage`), so the sum here equals what was really spent.
+     */
     usage?: SubagentUsage;
     /** False means cost is only a sum of reported costs, not a complete price (zero is not "free"). */
     usageCostKnown?: boolean;
@@ -601,6 +611,21 @@ export type AgentDefinition = {
     prompt: string;
     /** The directory this agent definition was discovered from. */
     sourceDir?: string;
+    /**
+     * Whether this definition came from the PACKAGE'S OWN agents directory - the ones Super Pi ships -
+     * rather than from a directory the user pointed the app at.
+     *
+     * WHY IT IS DECIDED BY THE SERVER AND NOT BY THE CLIENT. The picker used to interleave the two
+     * kinds alphabetically, so the built-in agents - the ones with a colour dot - were scattered among
+     * the user's own. The client cannot work that out on its own: it is told where each definition came
+     * from, but "is this directory the package's own" is a question about the app's installation, and
+     * only the server knows where it is installed. So the server answers it here, at read time, and the
+     * client just orders by the answer.
+     *
+     * It describes the definition that WON, not the id: when a user's directory shadows a built-in
+     * agent of the same id, the user's file is the one that is listed, and it is the user's.
+     */
+    builtin?: boolean;
 };
 /**
  * What the picker receives. The prompt body is deliberately NOT sent: it is a whole system prompt,
@@ -830,6 +855,20 @@ export type SubagentRun = {
     /** True when `output` was cut for the model's benefit; the browser still saw all of it. */
     outputTruncated?: boolean;
     usage?: SubagentUsage;
+    /**
+     * TRUE once this run's usage has been folded into the usage ledger of the conversation that
+     * dispatched it.
+     *
+     * IT IS THE FLAG THAT MAKES THE FOLD HAPPEN EXACTLY ONCE. The child's money is added to the
+     * parent conversation's `usage` when the run settles, and a project budget reads that ledger -
+     * so a run whose usage were folded twice would be billed twice, and a run whose usage were never
+     * folded would be free. The flag says which side of that line this run is on, and it is written
+     * in the SAME store write as the ledger entry, so there is no window in which the two disagree.
+     *
+     * ABSENT means "not accounted for yet", which is what a `state.json` written before this feature
+     * existed says about every run in it - and what the startup sweep repairs, once, on the next boot.
+     */
+    usageAccounted?: boolean;
     error?: string;
     /**
      * How long the run took, measured by THIS server between writing the `running` row and settling it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.165",
+  "version": "0.1.166",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -48,6 +48,7 @@
     "scripts/stream-transport.test.mjs",
     "scripts/remote-transport.test.mjs",
     "scripts/browser-safe-port.test.mjs",
+    "scripts/agent-picker-order.test.mjs",
     "scripts/inline-thinking.test.mjs",
     "scripts/inline-thinking-close-tag.test.mjs",
     "scripts/pi-session.test.mjs",
@@ -69,6 +70,7 @@
     "scripts/verify-source-text.test.mjs",
     "scripts/runtime-extension-ui.test.mjs",
     "scripts/agent-mechanism.test.mjs",
+    "scripts/builtin-agents-project.test.mjs",
     "scripts/super-pi-tool-names.test.mjs",
     "scripts/agent-wiring.test.mjs",
     "scripts/message-timestamps.test.mjs",
@@ -95,6 +97,7 @@
     "scripts/subagent-noise.test.mjs",
     "scripts/subagent-response-receipt.test.mjs",
     "scripts/subagent-runs.test.mjs",
+    "scripts/subagent-usage-accounting.test.mjs",
     "scripts/ws-flood-regression.test.mjs",
     "scripts/conversation-reconcile.test.mjs",
     "scripts/subagent-dispatch.test.mjs",
@@ -226,7 +229,9 @@
     "scripts/session-report-tool.test.mjs",
     "scripts/session-stop-subtree.test.mjs",
     "scripts/awaiting-background-status.test.mjs",
-    "scripts/project-lifecycle-e2e.test.mjs"
+    "scripts/project-lifecycle-e2e.test.mjs",
+    "scripts/agent-tiers.test.mjs",
+    "scripts/design-principles.test.mjs"
   ],
   "check:browser": [
     "scripts/interrupt-browser.test.mjs",
@@ -260,6 +265,8 @@
     "scripts/workspace-identity-browser.test.mjs",
     "scripts/sidebar-tools-browser.test.mjs",
     "scripts/project-employee-panel-browser.test.mjs",
+    "scripts/project-evidence-panel-browser.test.mjs",
+    "scripts/builtin-agents-project-browser.test.mjs",
     "scripts/tool-runtime-browser.test.mjs",
     "scripts/session-context-menu-browser.test.mjs",
     "scripts/archive-cascade-browser.test.mjs",