@evandu/super-pi 0.1.166 → 0.1.168

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-dARLbQ-8.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-C6YWfUu2.css">
+    <script type="module" crossorigin src="/assets/index-C4d7l2t8.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-C3ETe3EL.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/agents.d.ts

@@ -199,6 +199,24 @@ export declare function readAgents(directory: string | readonly string[], option
     mode?: AgentModeFilter;
     builtinDir?: string;
 }): Promise<AgentScan>;
+/**
+ * WHAT KIND OF AGENT IS THIS ID?
+ *
+ * The catalogue is read in halves - the primaries and the subagents - and a question about ONE id
+ * has to be asked of both halves. The answer is the `mode:` frontmatter of the definition that
+ * WINS, which is the same override rule `readAgents` already applies: the first directory to offer
+ * an id owns it.
+ *
+ * `undefined` MEANS "NO SUCH AGENT IN THESE DIRECTORIES", and that is NOT the same as "not
+ * primary". An id nobody has heard of is a CUSTOM agent, and custom agents are legal - §3 keeps
+ * them legal on purpose, so that a project can name an agent the catalogue does not carry yet.
+ * Only an agent that EXISTS and is a subagent is a subagent.
+ *
+ * THE HIDDEN ONES COUNT. `hidden` decides whether a person is SHOWN an agent in a picker, not
+ * whether the agent exists, so a hidden subagent is still a subagent here. A guard that could be
+ * walked around by ticking one box in a frontmatter would not be a guard.
+ */
+export declare function agentModeOf(directories: string | readonly string[], agentId: string): Promise<"primary" | "subagent" | undefined>;
 /** 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

@@ -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
@@ -526,12 +527,13 @@ export async function readAgents(directory, options = {}) {
     // 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 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.
+    // 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
@@ -539,12 +541,39 @@ export async function readAgents(directory, options = {}) {
     // 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.builtin === b.builtin ? a.id.localeCompare(b.id) : a.builtin ? -1 : 1)),
+        agents: orderAgentsForDisplay(agents).filter((agent) => agent.mode === mode),
         problems,
     };
 }
+/**
+ * WHAT KIND OF AGENT IS THIS ID?
+ *
+ * The catalogue is read in halves - the primaries and the subagents - and a question about ONE id
+ * has to be asked of both halves. The answer is the `mode:` frontmatter of the definition that
+ * WINS, which is the same override rule `readAgents` already applies: the first directory to offer
+ * an id owns it.
+ *
+ * `undefined` MEANS "NO SUCH AGENT IN THESE DIRECTORIES", and that is NOT the same as "not
+ * primary". An id nobody has heard of is a CUSTOM agent, and custom agents are legal - §3 keeps
+ * them legal on purpose, so that a project can name an agent the catalogue does not carry yet.
+ * Only an agent that EXISTS and is a subagent is a subagent.
+ *
+ * THE HIDDEN ONES COUNT. `hidden` decides whether a person is SHOWN an agent in a picker, not
+ * whether the agent exists, so a hidden subagent is still a subagent here. A guard that could be
+ * walked around by ticking one box in a frontmatter would not be a guard.
+ */
+export async function agentModeOf(directories, agentId) {
+    const id = agentId.trim();
+    if (!id)
+        return undefined;
+    const dirs = Array.isArray(directories) ? [...directories] : [directories];
+    for (const mode of ["subagent", "primary"]) {
+        const scan = await readAgents(dirs, { mode });
+        if (scan.agents.some((agent) => agent.id === id))
+            return mode;
+    }
+    return undefined;
+}
 /** Only `#rgb` and `#rrggbb`. A `color:` frontmatter value is rendered as a CSS background, so it has to
  *  be a colour and nothing else - accepting an arbitrary string would put author-controlled text into a
  *  style declaration. Anything else is dropped rather than sanitised into something misleading. */

package/dist/server/application/project-service.d.ts

@@ -80,12 +80,56 @@ export type BudgetRaiseResult = {
     /** How many budget exceptions were closed by the raise. */
     resolvedEscalations: number;
 };
+/**
+ * HOW THE SERVICE ASKS WHAT AN AGENT ID IS.
+ *
+ * The employee rule is a fact about the agent DIRECTORY, so the directory is read through the one
+ * reader the server already has (`readAgents`, through `agentModeOf`), and the question is asked of
+ * whoever owns those directories. The service deliberately does not know where the definitions
+ * live: the directories change when the user adds one, and a service that kept its own copy of the
+ * path would answer about a directory that is no longer there.
+ *
+ * `undefined` means "no such agent" - NOT "not primary". An id that is in no directory is a custom
+ * agent, and §3 keeps custom agents legal.
+ */
+export type AgentModeLookup = {
+    agentModeOf(agentId: string): Promise<"primary" | "subagent" | undefined>;
+};
 /** Persist explicit domain fields only; transport credentials never enter project records. */
 export declare class ProjectService {
     private readonly store;
     private readonly orchestrator?;
+    /**
+     * Optional on purpose: a service built without an agent directory cannot tell a subagent from a
+     * custom agent, and it then behaves exactly as it did before this check existed. The real
+     * server always passes one.
+     */
+    private readonly agents?;
     private readonly queues;
-    constructor(store: Store, orchestrator?: (Pick<SessionOrchestratorService, "spawn" | "dispatch"> & Partial<Pick<SessionOrchestratorService, "stopSubtree">>) | undefined);
+    constructor(store: Store, orchestrator?: (Pick<SessionOrchestratorService, "spawn" | "dispatch"> & Partial<Pick<SessionOrchestratorService, "stopSubtree">>) | undefined, 
+    /**
+     * Optional on purpose: a service built without an agent directory cannot tell a subagent from a
+     * custom agent, and it then behaves exactly as it did before this check existed. The real
+     * server always passes one.
+     */
+    agents?: AgentModeLookup | undefined);
+    /**
+     * A PROJECT EMPLOYEE MUST BE A PRIMARY AGENT.
+     *
+     * §1 says a subagent cannot be a project employee: a subagent is a tool-level, one-shot,
+     * invisible call, and a project that leans on one leans on a role the user can never see and
+     * never interrupt. The client only offers primary agents in the candidate list, but a candidate
+     * list is a SUGGESTION - the server is the constraint, and the refusal belongs at the moment the
+     * profile is written, while the reader is still looking at the form. Refusing later (when the
+     * task is dispatched) teaches the reader that the panel accepted something the project cannot
+     * use.
+     *
+     * WHAT IS REFUSED, AND WHAT IS NOT. An agent that EXISTS and is a subagent is refused, and the
+     * message names the slot and the agent, so the reader knows WHICH employee to change. An id that
+     * is in NO directory is a custom agent, and §3 keeps custom agents legal - so it is accepted here,
+     * exactly as it was before this check existed.
+     */
+    private assertEmployee;
     static taskView(task: ProjectTask, project: Pick<Project, "defaultExecutorProfile" | "defaultReviewerProfile">): ProjectTask;
     private filterEscalations;
     private projectView;
@@ -265,8 +309,8 @@ export declare class ProjectService {
      */
     raiseBudgetAndContinue(id: string, workspaceId: string, callerConversationId?: string): Promise<BudgetRaiseResult>;
     addReport(id: string, input: Omit<ProjectReport, "id" | "projectId" | "createdAt">, workspaceId?: string, actor?: string): Promise<ProjectReport>;
-    addEscalation(id: string, input: Pick<ProjectEscalation, "reason" | "severity" | "taskId">, workspaceId?: string, actor?: string): Promise<ProjectEscalation>;
-    resolveEscalation(id: string, escalationId: string, decision: string, status: "resolved" | "dismissed", workspaceId?: string, actor?: string): Promise<ProjectEscalation>;
+    addEscalation(id: string, input: Pick<ProjectEscalation, "reason" | "severity" | "taskId" | "title">, workspaceId?: string, actor?: string): Promise<ProjectEscalation>;
+    resolveEscalation(id: string, escalationId: string, decision: string, status: "resolved" | "dismissed" | "returned", workspaceId?: string, actor?: string): Promise<ProjectEscalation>;
     complete(id: string, summary: string, evidenceRefs: unknown, workspaceId: string, actor?: string): Promise<Project>;
     /**
      * The tasks an initiator hands over with create. A dependency names the TITLE of another task in

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 = {
@@ -171,7 +171,7 @@ const EVENT_TEXT = {
     budget: "预算变更", report: "进展汇报", escalated: "例外升级", decision: "决定",
     completed: "项目完成", ready: "依赖就绪", unreachable: "转述对象不可达",
 };
-const ESCALATION_STATUS_TEXT = { open: "未决", resolved: "已解决", dismissed: "已忽略" };
+const ESCALATION_STATUS_TEXT = { open: "未决", resolved: "已解决", dismissed: "已忽略", returned: "已退回补充材料" };
 const SEVERITY_TEXT = { low: "低", medium: "中", high: "高" };
 const REPORT_KIND_TEXT = {
     progress: "进展", blocked: "阻塞", delivery: "交付", decision_request: "决策请求", review: "复核",
@@ -202,10 +202,43 @@ const lightweight = (p) => p.mode === "lightweight";
 export class ProjectService {
     store;
     orchestrator;
+    agents;
     queues = new Map();
-    constructor(store, orchestrator) {
+    constructor(store, orchestrator, 
+    /**
+     * Optional on purpose: a service built without an agent directory cannot tell a subagent from a
+     * custom agent, and it then behaves exactly as it did before this check existed. The real
+     * server always passes one.
+     */
+    agents) {
         this.store = store;
         this.orchestrator = orchestrator;
+        this.agents = agents;
+    }
+    /**
+     * A PROJECT EMPLOYEE MUST BE A PRIMARY AGENT.
+     *
+     * §1 says a subagent cannot be a project employee: a subagent is a tool-level, one-shot,
+     * invisible call, and a project that leans on one leans on a role the user can never see and
+     * never interrupt. The client only offers primary agents in the candidate list, but a candidate
+     * list is a SUGGESTION - the server is the constraint, and the refusal belongs at the moment the
+     * profile is written, while the reader is still looking at the form. Refusing later (when the
+     * task is dispatched) teaches the reader that the panel accepted something the project cannot
+     * use.
+     *
+     * WHAT IS REFUSED, AND WHAT IS NOT. An agent that EXISTS and is a subagent is refused, and the
+     * message names the slot and the agent, so the reader knows WHICH employee to change. An id that
+     * is in NO directory is a custom agent, and §3 keeps custom agents legal - so it is accepted here,
+     * exactly as it was before this check existed.
+     */
+    async assertEmployee(profile, label) {
+        const agentId = profile?.agentId;
+        if (!agentId || !this.agents)
+            return;
+        const mode = await this.agents.agentModeOf(agentId);
+        if (mode === "subagent") {
+            throw new Error(`${label}.agentId 指向的是 subagent（${agentId}），项目员工必须是 primary：subagent 是一次性的工具级调用，用户在侧栏看不到它的中间步骤，也插不上话。`);
+        }
     }
     static taskView(task, project) {
         const t = { ...task };
@@ -475,10 +508,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 +547,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
@@ -529,12 +575,33 @@ export class ProjectService {
            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),
+        /* 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);
@@ -562,6 +629,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}`;
@@ -689,7 +762,12 @@ export class ProjectService {
         // formula is printed next to the number: a budget nobody can predict is a budget nobody trusts.
         // 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））`);
+        // 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)
@@ -775,6 +853,12 @@ export class ProjectService {
         const defaultLeaderProfile = profile(input.defaultLeaderProfile, "默认 Leader 配置");
         const defaultExecutorProfile = profile(input.defaultExecutorProfile, "默认执行配置");
         const defaultReviewerProfile = profile(input.defaultReviewerProfile, "默认复核配置");
+        // THE PROJECT'S OWN EMPLOYEE DEFAULTS ARE EMPLOYEES TOO. They are the profiles every task
+        // inherits when it names no one, so a subagent written here would become the employee of the
+        // whole project - and it would be refused at every task that inherited it, one by one, long
+        // after the person who wrote it had walked away.
+        await this.assertEmployee(defaultExecutorProfile, "defaultExecutorProfile");
+        await this.assertEmployee(defaultReviewerProfile, "defaultReviewerProfile");
         const initiator = (initiatorConversationId ?? (typeof input.initiatorConversationId === "string" ? input.initiatorConversationId : undefined))?.trim() || undefined;
         const now = stamp();
         const p = { id: `project_${randomUUID()}`, workspaceId, title: text(input.title, "项目标题"), objective: text(input.objective, "项目目标"),
@@ -864,7 +948,7 @@ export class ProjectService {
         });
     }
     async addTask(id, input, workspaceId, actor) {
-        return this.change(id, workspaceId, (p) => {
+        return this.change(id, workspaceId, async (p) => {
             this.live(p);
             const parentTaskId = optional(input.parentTaskId, "父任务 id");
             // A LIGHTWEIGHT PROJECT HAS ONE SESSION, SO IT HAS NO TREE OF TASKS. Decomposing the work
@@ -916,6 +1000,11 @@ export class ProjectService {
                 throw new Error("项目最多 100 个任务，请收敛分工范围");
             const executorProfile = profile(input.executorProfile, "执行配置");
             const reviewerProfile = profile(input.reviewerProfile, "复核配置");
+            // THE EMPLOYEE IS CHECKED BEFORE THE TASK EXISTS. The refusal happens in the write itself,
+            // so a project never carries a task whose employee is a subagent - not even for the moment
+            // between the write and the next read.
+            await this.assertEmployee(executorProfile, "executorProfile");
+            await this.assertEmployee(reviewerProfile, "reviewerProfile");
             const now = stamp();
             const t = { id: `task_${randomUUID()}`, projectId: id, title: text(input.title, "任务标题"), objective: text(input.objective, "任务目标"),
                 status: dependencies.length ? "pending" : "ready", accountableConversationId: manager, parentTaskId, role: input.role ?? "executor", dependencies,
@@ -1081,7 +1170,7 @@ export class ProjectService {
         });
     }
     async updateTask(id, taskId, patch, actor) {
-        const result = await this.change(id, patch.workspaceId, (p) => {
+        const result = await this.change(id, patch.workspaceId, async (p) => {
             this.live(p);
             const t = this.task(p, taskId);
             this.member(p, actor);
@@ -1115,6 +1204,9 @@ export class ProjectService {
                 if (t.ownerConversationId)
                     throw new Error("执行会话已创建，禁止修改执行配置");
                 const ep = profile(patch.executorProfile, "执行配置");
+                // THE CHECK COMES BEFORE THE ASSIGNMENT. The task keeps the employee it had; what it must
+                // not do is end up holding an employee the project is not allowed to have.
+                await this.assertEmployee(ep, "executorProfile");
                 if (ep)
                     t.executorProfile = ep;
                 else
@@ -1124,6 +1216,7 @@ export class ProjectService {
                 if (t.reviewerConversationId)
                     throw new Error("复核会话已创建，禁止修改复核配置");
                 const rp = profile(patch.reviewerProfile, "复核配置");
+                await this.assertEmployee(rp, "reviewerProfile");
                 if (rp)
                     t.reviewerProfile = rp;
                 else
@@ -1192,6 +1285,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();
@@ -1323,7 +1422,7 @@ export class ProjectService {
             if (actor && actor !== p.ownerConversationId && (!t || ![t.ownerConversationId, t.reviewerConversationId, this.manager(p, t)].includes(actor)))
                 throw new Error("仅可汇报本人负责的任务");
             const report = { id: randomUUID(), projectId: id, taskId: t?.id, authorConversationId: actor, kind: input.kind,
-                progress: text(input.progress, "汇报进展"), variance: optional(input.variance, "偏差"), nextStep: optional(input.nextStep, "下一步"), risks: strings(input.risks, "风险"),
+                progress: text(input.progress, "汇报进展"), summary: typeof input.summary === "string" && input.summary.trim() ? text(input.summary, "汇报标题") : undefined, variance: optional(input.variance, "偏差"), nextStep: optional(input.nextStep, "下一步"), risks: strings(input.risks, "风险"),
                 decisionNeeded: optional(input.decisionNeeded, "所需决策"), evidenceRefs: strings(input.evidenceRefs, "证据"), createdAt: stamp() };
             p.reports.push(report);
             if (report.kind === "blocked") {
@@ -1387,6 +1486,10 @@ export class ProjectService {
                 projectId: id,
                 taskId: t?.id,
                 reason: text(input.reason, "升级原因"),
+                /* THE QUESTION IS KEPT BESIDE THE CASE. The title is what the reader decides ON - one
+                   sentence, in the reader's terms - and the reason is the case for it. An escalation
+                   * without a title is still a valid escalation; it simply has to be read in full. */
+                ...(typeof input.title === "string" && input.title.trim() ? { title: text(input.title, "升级标题") } : {}),
                 severity: input.severity,
                 status: "open",
                 requestedByConversationId: actor,
@@ -1395,19 +1498,19 @@ export class ProjectService {
                 createdAt: stamp(),
             };
             p.escalations.push(e);
-            this.event(p, "escalated", e.reason, t?.id, actor);
+            this.event(p, "escalated", e.title ? `${e.title}：${e.reason}` : e.reason, t?.id, actor);
             this.reconcile(p);
             return e;
         }, actor);
         if (supervisorToWake) {
-            await this.wake(supervisorToWake, `下级成员（会话：${actor}，身份：${wakeMemberRole ?? "执行者"}）发起例外升级（ID：${result.id}）：\n原因：${result.reason}\n严重级别：${result.severity}\n请及时处理该例外（调用 project action="resolve_escalation" 记录处理意见），或按需向上级转述升级。`, `例外升级（ID：${result.id}）`, id, workspaceId, actor);
+            await this.wake(supervisorToWake, `下级成员（会话：${actor}，身份：${wakeMemberRole ?? "执行者"}）发起例外升级（ID：${result.id}）：\n${result.title ? `待决问题：${result.title}\n` : ""}原因：${result.reason}\n严重级别：${result.severity}\n请及时处理该例外（调用 project action="resolve_escalation" 记录处理意见），或按需向上级转述升级。`, `例外升级（ID：${result.id}）`, id, workspaceId, actor);
         }
         return result;
     }
     async resolveEscalation(id, escalationId, decision, status, workspaceId, actor) {
         const result = await this.change(id, workspaceId, (p) => {
             this.live(p);
-            if (status !== "resolved" && status !== "dismissed")
+            if (status !== "resolved" && status !== "dismissed" && status !== "returned")
                 throw new Error("升级处理状态不合法");
             const e = p.escalations.find((e) => e.id === escalationId);
             if (!e)
@@ -1430,10 +1533,24 @@ export class ProjectService {
             e.decision = text(decision, "处理意见");
             e.resolvedAt = stamp();
             const decider = audience === "boss" ? "Boss" : "直接上级";
-            this.event(p, "decision", `${decider}决策：${e.decision}`, e.taskId, actor);
+            /* A RETURN IS NOT A DECISION. It says the case was not ready - the reader is being asked
+             * for more material, not for a ruling - so the timeline says so in those words. */
+            this.event(p, "decision", status === "returned"
+                ? `${decider}退回例外，等待补充材料：${e.decision}`
+                : `${decider}决策：${e.decision}`, e.taskId, actor);
             this.reconcile(p);
             return e;
         }, actor);
+        /* THE CASE GOES BACK TO WHO RAISED IT. A returned escalation leaves the inbox without being
+         * answered, so nobody would ever know it was still open - unless the person who raised it is
+         * woken up and told to bring the missing material. This is the one wake that is NOT about a
+         * decision: it is about work coming back. */
+        if (status === "returned") {
+            if (result.requestedByConversationId) {
+                await this.wake(result.requestedByConversationId, `例外已退回，等待对方补充材料（ID：${result.id}）：${result.title ?? result.reason}\n退回意见：${result.decision}\n请补充材料后重新发起升级。`, `例外已退回（ID：${result.id}）`, id, workspaceId, actor);
+            }
+            return result;
+        }
         const p = this.raw(id, workspaceId);
         if (result.audience === "supervisor") {
             if (result.requestedByConversationId) {

package/dist/server/index.js

@@ -9,7 +9,7 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { openStateStore } from "./persistence/open-state-store.js";
 import { PiRpcRuntime, WelcomeRuntime } from "./runtime.js";
-import { resolveAgentDirectories } from "./agents.js";
+import { agentModeOf, resolveAgentDirectories } from "./agents.js";
 import { releaseAllCapabilities } from "./capability.js";
 import { SubagentSupervisor } from "./subagents.js";
 import { SubagentRunRecorder } from "./subagent-runs.js";
@@ -297,7 +297,18 @@ runService.setExecService(execService);
 const scheduledTaskService = new ScheduledTaskService(store, runService, conversationService, broadcaster);
 const sessionLedger = new SessionLedger();
 const sessionOrchestratorService = new SessionOrchestratorService(store, conversationService, runService, sessionLedger, broadcaster);
-const projectService = new ProjectService(store, sessionOrchestratorService);
+/**
+ * THE PROJECT SERVICE IS TOLD HOW TO ASK WHAT AN AGENT IS.
+ *
+ * The employee rule of §1 - "a subagent cannot be a project employee" - is a fact about the agent
+ * DIRECTORY, and the directory is read through the same reader the picker and the runtime use
+ * (`readAgents`, through `agentModeOf`). The directories are asked of the catalogue service
+ * because THEY are the live ones: the user can add an agents directory at any time, and a guard
+ * that read a path captured at startup would answer about a directory that is no longer there.
+ */
+const projectService = new ProjectService(store, sessionOrchestratorService, {
+    agentModeOf: (agentId) => agentModeOf(catalogService.getAgentDirs(), agentId),
+});
 void sessionOrchestratorService.restoreWatchdogs().catch((error) => {
     console.warn("Super Pi: restoring watchdogs failed:", error instanceof Error ? error.message : String(error));
 });

package/dist/server/types.d.ts

@@ -939,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";
 /**
@@ -1011,6 +1011,7 @@ export type ProjectReport = {
     authorConversationId?: string;
     kind: "progress" | "blocked" | "delivery" | "decision_request" | "review";
     progress: string;
+    summary?: string;
     variance?: string;
     nextStep?: string;
     risks?: string[];
@@ -1022,9 +1023,12 @@ export type ProjectEscalation = {
     id: string;
     projectId: string;
     taskId?: string;
-    reason: string;
+    reason: string; /** THE QUESTION, IN ONE SENTENCE. What the Boss has to decide - as opposed to `reason`,
+       *  which is the case for it. The reader decides in a glance, and reads the case only if the
+       *  question is not obvious; an escalation without a title falls back to the reason. */
+    title?: string;
     severity: ProjectRisk;
-    status: "open" | "resolved" | "dismissed";
+    status: "open" | "resolved" | "dismissed" | "returned";
     requestedByConversationId?: string;
     decision?: string;
     createdAt: string;
@@ -1095,6 +1099,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[];