@evandu/super-pi 0.1.165 → 0.1.167

package/dist/server/agents.js

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { orderAgentsForDisplay } from "../shared/agent-order.js";
 /**
  * A guard rather than a cast: it is the only thing that lets `tools:` be checked once and then used as
  * a map everywhere without the compiler complaining. It narrows to the index-signature shape that
@@ -392,6 +393,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 +446,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 +472,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 +485,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 +518,30 @@ 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 ORDER IS NOT DECIDED HERE. It is `orderAgentsForDisplay` - the one rule in
+    // `src/shared/agent-order.ts`, which the client applies too. The server orders the whole catalogue it
+    // read and hands out the half that was asked for, so what leaves the server is ALREADY in display
+    // order: the package's own agents first, the conversation roles before the delegated ones, and
+    // alphabetical by id inside each. Every surface that draws a server catalogue therefore inherits that
+    // order instead of guessing it, and the one place that MERGES two catalogues re-applies the same
+    // rule rather than inventing a second one.
+    //
+    // 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: orderAgentsForDisplay(agents).filter((agent) => agent.mode === mode),
         problems,
     };
 }

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

@@ -158,7 +158,7 @@ const REPORT_EVENT_LIMIT = 200;
 // THE WORDS THE REPORT SPEAKS IN. A reader of the report is a person, not a console, so every
 // state and every role is written the way a person would say it out loud.
 const PROJECT_STATUS_TEXT = {
-    planning: "草稿", active: "进行中", blocked: "已阻塞", awaiting_approval: "等待审批",
+    planning: "草稿", awaiting_start: "待启动", active: "进行中", blocked: "已阻塞", awaiting_approval: "等待审批",
     awaiting_review: "等待复核", completed: "已完成", cancelled: "已取消", failed: "失败",
 };
 const TASK_STATUS_TEXT = {
@@ -475,10 +475,22 @@ export class ProjectService {
         const hasLeaderBlockedTask = p.tasks.some((t) => t.status === "blocked" && isLeader(t.blockedReportedByConversationId));
         const lastLeaderProjectReport = [...p.reports].reverse().find((r) => !r.taskId && isLeader(r.authorConversationId));
         const leaderProjectBlocked = lastLeaderProjectReport?.kind === "blocked";
+        /* A PROJECT THAT HAS WORK REGISTERED BUT NO LEADER SESSION YET IS NOT RUNNING.
+           "active" used to mean "there is at least one task", so a project whose tasks were only
+           REGISTERED - nobody had started it, nobody was working on it - claimed on its card to be
+           running while the panel's own team section said there were no sessions at all. The card
+           and the team list contradicted each other, and the card was the one that lied: the
+           project's own status has to say what is true about the project, not what the client
+           happens to translate it into. So the state is split:
+             planning      - nothing has been broken down yet,
+             awaiting_start - the work is registered and the project has NOT been started,
+             active        - the project is started and a leader session exists.
+           A project has a leader session only after `start`, so the leader is the signal - not the
+           task count, and not anything the client sends. */
         p.status = openBoss.some((e) => e.severity === "high") ? "awaiting_approval"
             : openBoss.length || hasLeaderBlockedTask || leaderProjectBlocked ? "blocked"
                 : p.tasks.some((t) => t.status === "awaiting_review") ? "awaiting_review"
-                    : p.tasks.length ? "active" : "planning";
+                    : p.tasks.length ? (p.ownerConversationId ? "active" : "awaiting_start") : "planning";
     }
     resources(p) {
         const state = this.store.snapshot();
@@ -502,7 +514,8 @@ export class ProjectService {
          * initiator's conversation ("shared"). The leader is the root of the project's tree, so it is
          * "project" by the same rule as everybody else - there is no special case for it. */
         const projectTreeId = p.ownerConversationId ? this.store.conversation(p.ownerConversationId)?.treeId : undefined;
-        const sessions = state.conversations.filter((c) => c.workspaceId === p.workspaceId && members.has(c.id)).map((c) => ({
+        const memberConversations = state.conversations.filter((c) => c.workspaceId === p.workspaceId && members.has(c.id));
+        const sessions = memberConversations.map((c) => ({
             id: c.id, title: c.title, status: c.status, tokens: tokens(c.usage), contextPercent: c.contextUsage?.percent,
             // THE TREE SKELETON. The client draws the agents of a project as a tree, and the only
             // thing that knows who spawned whom is the conversation's own parent link. It is sent
@@ -521,12 +534,41 @@ 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`. */
+        /* THE SAME USAGE, TWICE: ONCE IN THE BILLING-EQUIVALENT UNITS THE BUDGET IS SPENT IN, AND
+           ONCE IN THE RAW 1:1 UNITS THE READER'S OWN TOOLING COUNTS IN.
+           The panel used to show only the equivalent number, and the two differ by a factor of
+           two and a half on a real run - so a reader who compared the project's cost with their
+           own dashboard saw two different numbers and no way to tell which one the panel meant.
+           So the raw components are sent as well: 输入 + 输出 + 缓存写入 + 缓存读取, which the reader
+           can add up, and can also feed into the published formula themselves.
+           The equivalent number is computed from the SUMMED components and rounded ONCE, not by
+           adding up each session's own rounded number: that way the formula printed next to the
+           number reproduces the number exactly, instead of being off by a token per session. */
+        const usage = memberConversations.reduce((acc, c) => {
+            if (!c.usage)
+                return acc;
+            acc.input += c.usage.input;
+            acc.output += c.usage.output;
+            acc.cacheRead += c.usage.cacheRead;
+            acc.cacheWrite += c.usage.cacheWrite;
+            return acc;
+        }, { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 });
+        return { tokens: tokens(usage),
             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
             // the sessions. Absent only when the project has no leader session yet.
-            memoryTreeId: projectTreeId, sessions };
+            memoryTreeId: projectTreeId, sessions,
+            // THE RAW 1:1 PICTURE OF THE SAME MONEY, next to the equivalent number it is spent in.
+            usage, rawTokens: usage.input + usage.output + usage.cacheRead + usage.cacheWrite };
     }
     list(workspaceId) {
         const scope = this.workspace(workspaceId);
@@ -554,6 +596,12 @@ export class ProjectService {
             const reason = blockedTask.blockedReason ? `（${blockedTask.blockedReason}）` : "";
             return `项目已阻塞：${blockedTask.title}${reason}`;
         }
+        /* THE WORK IS REGISTERED AND THE PROJECT HAS NOT BEEN STARTED. The task is "ready to
+           dispatch", but dispatching needs a leader and there is no leader until the project is
+           started - so "waiting to dispatch" would point the reader at something nobody can do.
+           The headline says what is true, in the same words the card uses. */
+        if (total > 0 && !p.ownerConversationId)
+            return `已登记 ${total} 个任务，项目待启动`;
         const inProgressTask = p.tasks.find((t) => t.status === "in_progress");
         if (inProgressTask) {
             return `${completed}/${total} 任务完成，正在执行${inProgressTask.title}`;
@@ -679,7 +727,14 @@ 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.
+        // THE RAW 1:1 FIGURE FOLLOWS IT, because the two differ by a factor of two and a half on a
+        // real run, and a reader who checks the project's cost against their own tooling needs to
+        // see both numbers and the parts they are made of.
+        const usage = this.resources(p);
+        lines.push(`- 已用等效 Token：${usage.tokens}（口径：输入 + 输出 + 缓存写入×${CACHE_WRITE_WEIGHT} + 缓存读取×${CACHE_READ_WEIGHT}，取整；含项目内的一次性调用（subagent））`);
+        lines.push(`- 原始口径（1:1）：${usage.rawTokens}（输入 ${usage.usage?.input ?? 0} + 输出 ${usage.usage?.output ?? 0} + 缓存写入 ${usage.usage?.cacheWrite ?? 0} + 缓存读取 ${usage.usage?.cacheRead ?? 0}）`);
         lines.push(`- 任务：共 ${p.tasks.length} 个，已完成 ${p.tasks.filter((t) => t.status === "completed").length} 个`);
         lines.push("", "## 交付与验收", "");
         if (!p.tasks.length)
@@ -1182,6 +1237,12 @@ export class ProjectService {
                 throw new Error("项目完成必须提交最终交付，其他状态由任务和例外推导");
             if (status === "active" && p.escalations.some((e) => e.status === "open"))
                 throw new Error("请先处理未解决的例外");
+            /* A PROJECT WITH NO LEADER SESSION HAS NOTHING RUNNING IN IT. The status is derived from
+               the project's own state, and the API may not push it back into the contradiction that
+               derivation exists to prevent: a project whose tasks were only registered is 待启动, and
+               no caller - the panel included - may call it 执行中 until it has actually been started. */
+            if (status === "active" && !p.ownerConversationId)
+                throw new Error("项目尚未启动，请先启动项目负责人");
             p.status = status;
             if (closed(p))
                 p.closedAt = stamp();

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.
@@ -900,7 +939,7 @@ export type TerminalShell = {
     file: string;
     args: string[];
 };
-export type ProjectStatus = "planning" | "active" | "blocked" | "awaiting_approval" | "awaiting_review" | "completed" | "failed" | "cancelled";
+export type ProjectStatus = "planning" | "awaiting_start" | "active" | "blocked" | "awaiting_approval" | "awaiting_review" | "completed" | "failed" | "cancelled";
 export type ProjectTaskStatus = "pending" | "ready" | "in_progress" | "blocked" | "awaiting_review" | "completed" | "failed" | "cancelled";
 export type ProjectRisk = "low" | "medium" | "high";
 /**
@@ -1056,6 +1095,13 @@ export type Project = {
         usageKnown: boolean;
         activeWorkers: number;
         memoryTreeId?: string;
+        usage?: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+        };
+        rawTokens?: number;
         sessions: {
             id: string;
             title: string;

package/dist/shared/agent-order.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The ONE order agent lists are shown in.
+ *
+ * WHY THERE IS A SINGLE RULE AND NOT A RULE PER SIDE. The picker's list, the settings page's grid, the
+ * sub-agent roster and the project panel's employee candidates are four views of the same catalogue, and
+ * they used to disagree about what a list of agents looks like. The server sorted what it read by
+ * "(built-in first, then id)", and the client re-sorted what the server sent by a rule of its own that
+ * added one more level - "roles before workers". A reader who saw the same agents in two orders had no
+ * way to tell which screen was wrong, because neither was: they were two answers to a question nobody
+ * had asked twice the same way.
+ *
+ * So the rule is stated once, HERE, and both sides apply it. The server imports it to order the
+ * catalogue it reads; the client imports it to order every list it draws. There is no second
+ * implementation to drift, because there is no second implementation.
+ *
+ * THE ORDER IS:
+ *
+ *   1. THE PACKAGE'S OWN agents first, then the user's. The ones that ship with Super Pi are drawn with
+ *      a colour dot, and a dot scattered among the user's own reads as noise rather than as a group.
+ *   2. Inside a group, the CONVERSATION ROLES (mode: primary) before the DELEGATED ones (mode:
+ *      subagent), so a list reads as "the roles, then the workers".
+ *   3. Inside a group and a role, alphabetical by id, so the order never depends on the order the
+ *      filesystem happened to hand the files over in.
+ *
+ * WHY THE FLAG IS NOT GUESSED HERE. "Is this the package's own agent?" is a question about where the app
+ * is installed, and only the server knows that: it reads the definitions and marks them. A client that
+ * tried to work it out from the directory path would be guessing, and would guess wrong the moment the
+ * package is installed somewhere unusual - which is exactly the case where the answer matters.
+ */
+/** The minimum an agent has to carry for this ordering to be able to place it. */
+export type OrderableAgent = {
+    id: string;
+    mode?: "primary" | "subagent";
+    /** True when the definition came from the package's own agents directory. */
+    builtin?: boolean;
+};
+/**
+ * The built-in group first, then the user's, each group by role and then by id.
+ *
+ * An agent with no `builtin` flag at all (an older server, or a hand-built fixture) counts as the
+ * user's, which is the safe direction: it puts the unflagged one where a user's own would sit rather
+ * than promoting it into the group that means "this ships with Super Pi".
+ */
+export declare function orderAgentsForDisplay<T extends OrderableAgent>(agents: readonly T[]): T[];