@te-river/opencode-team-mode 1.6.2 → 1.7.1

package/dist/host/v2.js

@@ -1,10 +1,10 @@
 /**
- * The v2 personality: `Plugin.define({id, setup(ctx)})`.
+ * The v2 personality: `Plugin.define({id, setup(ctx)})` — the only personality
+ * since 1.7.0 (v1 support was removed).
  *
  * `Plugin.define` in @opencode/plugin@2.0.16 is literally `plugin => plugin`,
  * so this module exports the plain object and the v2 SDK never becomes a
- * runtime dependency — which is what keeps the dual-personality package
- * installable by a v1 user who cannot resolve that package at all.
+ * runtime dependency.
  *
  * Scope of this file (milestone M2): build the governed runtime on a
  * filesystem-backed client shim, register the tm_* tools through
@@ -13,17 +13,14 @@
  * session hooks / compaction / description appends (#93), or the browser
  * (#95). Those need this seam proven live first.
  *
- * Two v1 behaviors do not carry over, and both absences are stated rather than
- * discovered later:
+ * Two host limits are stated rather than discovered later:
  *  - creating agents: `AgentEditor` has no `add`, so the six roles must come
  *    from the user's config (the installer writes `agents/*.md`).
- *  - the conservative default-agent promotion: v1 read `cfg.default_agent` and
- *    only filled it when empty or "build".  v2 exposes `default(id)` with NO
- *    getter, so "only if the user did not choose" is not expressible — the
- *    choice is between never promoting and promoting every boot.  The user's
- *    standing instruction (2026-09-25) is that Team is ALWAYS the default, so
- *    this promotes unconditionally; `defaultAgent: false` in the plugin options
- *    opts out, exactly as on v1.
+ *  - the default-agent promotion: `default(id)` has NO getter, so "only if the
+ *    user did not choose" is not expressible — the choice is between never
+ *    promoting and promoting every boot.  The user's standing instruction
+ *    (2026-09-25) is that Team is ALWAYS the default, so this promotes
+ *    unconditionally; `defaultAgent: false` in the plugin options opts out.
  *
  * The official confirmation dialog is absent as well, and for a different
  * reason: probed on the live host, a plugin has no way to raise one.
@@ -31,6 +28,7 @@
  * the v2-worded refusal set below.
  */
 import { agents } from "../agents.js";
+import { normalizeAgentName } from "../identity.js";
 import { DEFAULT_TTL_DAYS, resolveTtlMs, startBlackboardMaintenance } from "../blackboard.js";
 import { parseExtraDeny, resolveEnvProtectMode } from "../envprotect.js";
 import { createTmTools } from "../tm/index.js";
@@ -38,16 +36,20 @@ import { agentVisibilityLine } from "../tm/stats.js";
 import { setAskUnavailableNote } from "../tm/perm-ask.js";
 import { setPrivateSpacePolicy } from "../tm/webfetch.js";
 import { blackboardNote } from "./note.js";
-import { applyV2BackgroundForce, applyV2PermissionGuards, needsCoarseShellAsk } from "./v2-guard.js";
+import { applyV2BackgroundForce, applyV2EnvFileInputGuard, applyV2PermissionGuards, applyV2ShellTimeoutClamp, needsCoarseShellAsk } from "./v2-guard.js";
 import { applyV2EventFeed } from "./v2-events.js";
 import { createV2SessionReader } from "./v2-session-client.js";
 import { applyV2Probe, probeSummary } from "./v2-probe.js";
 import { applyV2NativeOffload } from "./v2-offload.js";
+import { applyV2ProbeChain } from "./v2-probe-chain.js";
 import { applyV2SubagentRegistry, applyV2CompletionWatch } from "./v2-subagent.js";
 import { applyV2BrowserGate, browserGateSummary } from "./v2-browser-gate.js";
 import { seedWebfetchDomains } from "../tm/webfetch.js";
 import { v2CapabilityRows } from "./v2-capabilities.js";
-import { applyV2SessionLayer, removalPlan } from "./v2-session.js";
+import { applyV2SessionLayer, removalPlan, resolveSplitConfig } from "./v2-session.js";
+import { applyV2RetryGovernor, createRetryGovernor, resolveRetryConfig } from "./v2-retry.js";
+import { applyV2ContextPrune, resolvePruneConfig } from "./v2-prune.js";
+import { checkDefaultAgentRole, globalConfigDir } from "./v2-default-agent.js";
 import { createStorageLedgerStore } from "../tm/ledger.js";
 import { createTeamScope } from "./v2-scope.js";
 import { bindV2Tool } from "./v2-tool.js";
@@ -69,8 +71,24 @@ function directoryOf(ctx) {
         return loc.project.directory;
     return process.cwd();
 }
+/** #49 feature 2: the concurrency cap.  Default 3 (matches "at most 3 parallel
+ *  reviewers" and leaves a normal user headroom); `0` disables it.  A missing or
+ *  unparseable value falls back to the default rather than to 0, because a typo
+ *  must not silently turn a safety cap off. */
+export function resolveMaxConcurrentSubagents(env = process.env) {
+    const raw = String(env.TM_MAX_CONCURRENT_SUBAGENTS ?? "").trim();
+    if (!raw)
+        return 3;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return 3;
+    return n;
+}
 export const v2Personality = {
-    id: "team-mode",
+    // #45: the display id (host plugin list) — the npm package name.  NOT the
+    // storage/audit names (`team-mode/selfcheck`, `team-mode/ledger/`,
+    // `team-mode-env-protect`), which stay put so existing data is not orphaned.
+    id: "@te-river/opencode-team-mode",
     async setup(ctx) {
         if (!ctx || typeof ctx.tool?.transform !== "function") {
             // Nothing can be registered without the tool domain.  Say it in the
@@ -80,6 +98,23 @@ export const v2Personality = {
             return;
         }
         const directory = directoryOf(ctx);
+        // ---------- #38 runtime fallback: is the configured default role on disk? ----------
+        // The plugin cannot see config-directory roles through ctx.agent (probed: the
+        // editor snapshot holds only the 7 built-ins), so a `default_agent` naming a
+        // missing role would make the host fall back to `build` SILENTLY.  Reading the
+        // global config from disk is the only way to say so.  Never throws, never
+        // affects startup, and prints only the role name + the file path it looked for.
+        let defaultAgentCheck = { state: "no-config" };
+        try {
+            defaultAgentCheck = checkDefaultAgentRole({ configDir: globalConfigDir() });
+        }
+        catch {
+            defaultAgentCheck = { state: "unreadable" };
+        }
+        if (defaultAgentCheck.state === "missing-role") {
+            console.warn(`[team-mode] 全局配置的 default_agent="${defaultAgentCheck.defaultAgent}" 指向的角色文件不存在（${defaultAgentCheck.roleFile}）：` +
+                "宿主会静默退回 build，会话不再是 Team。重跑 scripts/install.ps1（Windows）或 scripts/install.sh 修复。");
+        }
         // ---------- Team-scope isolation (#22, the user's requirement 2026-09-25) ----------
         // Every v2 hook fires for EVERY agent on this host.  This one object is what
         // each layer asks before it mutates a request, a result, or a permission —
@@ -87,14 +122,24 @@ export const v2Personality = {
         const scope = createTeamScope(Object.keys(agents));
         setAskUnavailableNote(V2_NO_DIALOG_NOTE);
         const options = (ctx.options ?? {});
-        const envProtectMode = options.envProtect ? resolveEnvProtectMode(process.env.TM_ENV_PROTECT) : "off";
+        // R6 is ARMED BY DEFAULT, matching v1 (which was always armed).  The old form
+        // (`options.envProtect ? … : "off"`) made the env-file red line opt-IN, and
+        // `docs/installation-v2.md` never mentioned the option — so a default install
+        // read `.env` in plaintext while AGENTS.md called that rule "hard".  Two
+        // explicit switches turn it off, and only those two: the plugin option
+        // `envProtect:false`, or `TM_ENV_PROTECT=off` (resolved below, which also
+        // fails CLOSED into "strict" for a typo).  On v2 the shell face is `ask`
+        // (the host's own dialog) and the env-FILE face is `deny`; the resolved mode
+        // rides the boot row's `env_protect` field so the user can see which world
+        // they are in.
+        const envProtectMode = options.envProtect === false ? "off" : resolveEnvProtectMode(process.env.TM_ENV_PROTECT);
         const envProtectExtra = parseExtraDeny(process.env.TM_ENV_PROTECT_EXTRA_DENY);
         // ---------- the v2 network policy: no domain gate, IP red line only ----------
-        // The user's standing instruction for v2 (2026-09-25): do not block network
-        // access at all EXCEPT sensitive and internal addresses.  v1's 22-host seed list
-        // existed because v1 could open the host's official per-request dialog; on v2 a
-        // plugin cannot raise one, so an allowlist became a set of pages the agent can
-        // never see and no one can approve -- a gate with no door.  `"*"` therefore
+        // The user's standing instruction (2026-09-25): do not block network
+        // access at all EXCEPT sensitive and internal addresses.  A plugin cannot
+        // raise the host's official per-request dialog, so an allowlist would be a
+        // set of pages the agent can never see and no one can approve -- a gate with
+        // no door.  `"*"` therefore
         // replaces the DEFAULT here, and what still holds absolutely is `checkWebUrl`'s
         // address policy underneath it: link-local / metadata / reserved ranges are a hard
         // deny no config can open (and were never consentable), and private space
@@ -102,9 +147,9 @@ export const v2Personality = {
         // tools, which have no dialog to ask with, and opened only by the host's own
         // `effect:"ask"` for the native tools.  IPv4-mapped and DNS64 spellings are
         // unwrapped before that check, so the notation is not a way around it.
-        // An explicit TM_WEBFETCH_ALLOWED_DOMAINS always wins; this only changes which
-        // default applies, and it is resolved from a COPY of the env so the v1
-        // personality in the same process is untouched.
+        // An explicit TM_WEBFETCH_ALLOWED_DOMAINS always wins; this only changes
+        // which default applies, and it is resolved from a COPY of the env so the
+        // process env itself is untouched.
         const v2Env = { ...process.env };
         if (!String(v2Env.TM_WEBFETCH_ALLOWED_DOMAINS ?? "").trim())
             v2Env.TM_WEBFETCH_ALLOWED_DOMAINS = "*";
@@ -129,9 +174,9 @@ export const v2Personality = {
         // other half of that sentence is that a direct tool definition rides EVERY
         // request (our own estimate for the full set is 9 528 tokens).
         // Delivered as REAL tools by default: the user's call (2026-09-25) was "slim the
-        // description first, then go direct", and the description is now 729 tokens for
-        // tm_browser (was 2 788 for the whole tool), which puts the measured per-role
-        // cost at 2 660 build-class / 4 726 tester / 6 391 researcher / 7 793 lead.
+        // description first, then go direct", and the descriptions are now slim enough
+        // that the measured per-role cost is 2 660 build-class / 4 726 tester /
+        // 6 391 researcher / 7 793 lead.
         // `TM_V2_CODEMODE=off` restores catalog-only for anyone who wants the tokens back
         // — and the boot note says which world this is, because in catalog mode most of
         // our governance text never reaches the model at all.
@@ -145,10 +190,10 @@ export const v2Personality = {
         // and the shutdown line reports both halves: `tools_codemode` (sent) and
         // `tools_in_request` (what the assembled request actually carried).
         const v2CodeModeDirect = /^(1|true|yes|on|direct)$/i.test(String(v2Env.TM_V2_CODEMODE ?? "").trim());
-        // No SDK client in the v1 sense.  v1's `client` carried `file.read`, `find.text`,
-        // `session.*` and `pty.*`; the v2 plugin ctx has no such object, and the fs shim
-        // that used to stand in for the first two went away with `tm_read`/`tm_grep` (the
-        // native tools, governed at `execute.after`, are the file ladder now).
+        // No SDK client.  The v2 plugin ctx carries no `file.read` / `find.text` /
+        // `session.*` / `pty.*` object, and the fs shim that used to stand in for the
+        // first two went away with `tm_read`/`tm_grep` (the native tools, governed at
+        // `execute.after`, are the file ladder now).
         // What IS bridged is the one thing the collect path cannot be honest without:
         // `tm_join` must be able to check whether a named session id is really the
         // caller's child, and a live 2.0.16 run proved that without it the tool reports
@@ -180,13 +225,12 @@ export const v2Personality = {
         const notes = [];
         // ---------- register the governed tools ----------
         const entries = Object.entries(tmRuntime.tools);
-        // v1 keeps tm_ptc_run; v2 does not register it.  The host's own `execute`
-        // (Code Mode) already runs "one program, N governed calls, zero round-trips,
-        // only the aggregate entering the context", and a live session showed our
+        // The retired tools are not registered.  The host's own `execute` (Code
+        // Mode) already runs "one program, N governed calls, zero round-trips, only
+        // the aggregate entering the context", and a live session showed our
         // governed results still come back offloaded through it — so shipping a
         // second batch runner would hand the model two tools for one job.  The
-        // module stays in the tree because the frozen v1 personality needs it, and
-        // the prompts the v2 config files carry are forked by gen-v2-config.mjs.
+        // prompts the config files carry are forked by gen-v2-config.mjs.
         const V2_UNREGISTERED = V1_ONLY_TOOLS;
         const bindings = [];
         const derived = [];
@@ -212,10 +256,10 @@ export const v2Personality = {
         // shape, so name the tools and say how they were obtained.
         const retired = entries.map(([name]) => name).filter((n) => V2_UNREGISTERED.has(n));
         if (retired.length) {
-            // Deliberate absences are said, not silently missing: an agent that reads a
-            // v1 document and finds no `tm_read` needs to learn from the boot log that
-            // this is the design, not a failed install.
-            notes.push(`v2 不注册 ${retired.join("/")} —— 同一件工作交给宿主自己的 read/grep/shell/execute（结果照样被 execute.after 治理），v1 保留这些别名`);
+            // Deliberate absences are said, not silently missing: an agent that looks
+            // for `tm_read` needs to learn from the boot log that this is the design,
+            // not a failed install.
+            notes.push(`不注册 ${retired.join("/")} —— 同一件工作交给宿主自己的 read/grep/shell/execute（结果照样被 execute.after 治理）`);
         }
         if (derived.length) {
             notes.push(`${derived.join("/")} 没有 zod 形状，参数表是从描述符文本推出来的（类型靠 name: type 前缀判定，不是 zod 保证）`);
@@ -250,14 +294,72 @@ export const v2Personality = {
         // ---------- the permission guard (egress red line + R6 per command) ----------
         // Installed BEFORE the agent transform because whether the config still needs
         // the coarse `shell -> ask` escalation depends on this hook being there.
-        const guards = await applyV2PermissionGuards(ctx, { envProtectMode, scope });
+        const guards = await applyV2PermissionGuards(ctx, {
+            envProtectMode,
+            scope,
+            // #49 feature 2: the concurrency cap reads the plugin's ONE children
+            // registry (the same rows tm_join collects), so a session cannot exceed the
+            // cap by dispatching faster than the lead collects.  `0` disables it.
+            runningChildren: (caller) => tmRuntime.runningChildren(caller),
+            maxConcurrent: resolveMaxConcurrentSubagents(v2Env),
+            onConcurrencyDenied: (info) => {
+                try {
+                    tmRuntime.pipelines.store.appendTrajectory({
+                        tool: "host",
+                        step_id: "v2-concurrency",
+                        event: "denied",
+                        caller: info.caller,
+                        cap: info.cap,
+                        running: info.running.length,
+                        ids: info.running.map((c) => c.sessionID).join(","),
+                    });
+                }
+                catch {
+                    /* the trajectory is an extra, never a reason to fail the call */
+                }
+            },
+        });
         // Said out loud because it is a promise with a boundary: the user's rule is
         // that nothing outside Team may be touched, and the honest consequence is that
         // the red lines we inject are therefore NOT protecting a build session either.
         notes.push("已按 Team 作用域收口：工具面裁剪、温度、黑板提示、原生结果卸载、R6 与地址红线、subagent 强制后台，都只对我们六个角色的会话生效；build / plan 等其余模式保持宿主出厂行为（代价：那些会话也不由我们补红线，需要全局红线请让宿主自己的 permission 规则承担）");
         registrations.push(...guards.registrations);
+        // #58: the SAME R6 file-path face, on the seam that sees the whole input.
+        // `permission.evaluate`'s resource for `grep`/`glob` is the PATTERN, not the
+        // search path, so the red line had a hole the width of those two tools —
+        // `read .env` was denied while `grep SECRET in .env` succeeded (2.0.24).
+        const envFileInput = await applyV2EnvFileInputGuard(ctx, { envProtectMode, scope, report: guards.report });
+        registrations.push(...envFileInput.registrations);
         const bgForce = await applyV2BackgroundForce(ctx, { scope });
         registrations.push(...bgForce.registrations);
+        // The shell timeout clamp (issue #6), ported here when the v1 personality was
+        // cut: the host gives `execute.before` a mutable `input`, the same seam
+        // `applyV2BackgroundForce` writes, so the protection survives the deletion —
+        // but only if it is counted, because a clamp nobody can see is a clamp a user
+        // reads as "the tool killed my probe for no reason".
+        const shellTimeout = await applyV2ShellTimeoutClamp(ctx, {
+            probeMs: tmRuntime.config.bashTimeoutProbeMs,
+            maxMs: tmRuntime.config.bashTimeoutMaxMs,
+            readonlyAllowed: tmRuntime.config.bashReadonlyAllowed,
+            scope,
+            onClamp: (info) => {
+                try {
+                    tmRuntime.pipelines.store.appendTrajectory({
+                        tool: "shell",
+                        step_id: "timeout-clamp",
+                        event: "clamped",
+                        via: info.via,
+                        from_ms: info.from,
+                        to_ms: info.to,
+                        sessionID: info.sessionID ?? "",
+                    });
+                }
+                catch {
+                    /* the trajectory is an extra, never a reason to fail the call */
+                }
+            },
+        });
+        registrations.push(...shellTimeout.registrations);
         // JIT governance over the HOST's tools, so the offload promise does not depend
         // on which tool the model happened to pick (see v2-offload.ts for why a
         // per-tool promise is no promise).  Registered BEFORE the probe so the probe's
@@ -265,6 +367,29 @@ export const v2Personality = {
         // teardown is a counter that does not exist.
         const offload = await applyV2NativeOffload(ctx, { pipelines: tmRuntime.pipelines, scope });
         registrations.push(...(await Promise.all(offload.registrations)));
+        // #35: the Code Mode adoption hint.  Registered AFTER the offloader so its
+        // append lands on whatever text the offloader left (a rewritten body or the
+        // host's verbatim one) — the hint only ever ADDS a line, never rewrites.
+        const probeChain = applyV2ProbeChain(ctx, {
+            scope,
+            env: v2Env,
+            onAdvise: (info) => {
+                try {
+                    tmRuntime.pipelines.store.appendTrajectory({
+                        tool: "host",
+                        step_id: "probe-chain",
+                        event: "advised",
+                        native_tool: info.tool,
+                        count: info.count,
+                        sessionID: info.sessionID,
+                    });
+                }
+                catch {
+                    /* the trajectory is an extra, never a reason to fail the call */
+                }
+            },
+        });
+        registrations.push(...(await Promise.all(probeChain.registrations)));
         // The host's own sub-agents, entered into tm_join's registry (decision 4,
         // 2026-09-26).  On v2 every dispatch IS the host's `subagent` tool, so without this
         // the collect side had nothing to collect: tm_join answered 没有待收集的派发 about
@@ -302,6 +427,26 @@ export const v2Personality = {
             allowlist: seedWebfetchDomains(tmRuntime.config.webfetchAllowedDomains),
             scope,
             env: v2Env,
+            // #14: the SERP rate limit's trajectory line.  The gate has no store, so the
+            // sink is wired here — same shape as the shell-timeout clamp's `onClamp`.
+            onSerp: (info) => {
+                try {
+                    tmRuntime.pipelines.store.appendTrajectory({
+                        tool: "browser",
+                        step_id: "serp-loop",
+                        event: info.event,
+                        engine: info.engine,
+                        query: info.query,
+                        host: info.host,
+                        count: info.count,
+                        limit: info.limit,
+                        sessionID: info.sessionID,
+                    });
+                }
+                catch {
+                    /* the trajectory is an extra, never a reason to fail the call */
+                }
+            },
         });
         if (!browserGate.registrations.length) {
             notes.push("原生 browser_* 的门禁没装上（ctx.tool.hook 不可用）：宿主的 45 个浏览器工具在 Team 会话里也不受我们的域名 / 地址规则约束");
@@ -320,6 +465,12 @@ export const v2Personality = {
         /** The role ids the HOST resolved in a real request — the only observation that
          *  separates "installed but invisible to the snapshot" from "not installed". */
         let resolvedAgentIds = () => [];
+        /** #58: `tools_in_request` used to live ONLY on `v2-shutdown`, which the CLI
+         *  never writes — so on a CLI run the field was unobservable.  Late-bound for
+         *  the same reason as the counters: the request layer registers BELOW the
+         *  probe, and a closure that touched a not-yet-initialized `const` would throw
+         *  inside `onSummary`, where the try/catch would swallow the whole row. */
+        let tmInRequestSurface = () => "unobserved";
         /** A3: the in-process observation counters.  Measured today: three runs wrote
          *  ZERO `v2-shutdown` rows, because the CLI path never reaches dispose — so the
          *  final totals have to survive on the throttled surface snapshot too, and a row
@@ -369,6 +520,9 @@ export const v2Personality = {
                         // teardown — dispose is not guaranteed to run, and a run that is
                         // interrupted is exactly the run whose counters someone needs.
                         ...observationCounters("surface"),
+                        // #58: the delivery fact the CLI could never see — it only rode
+                        // `v2-shutdown`, which a CLI run never reaches.
+                        tools_in_request: tmInRequestSurface(),
                         ...summary,
                     });
                 }
@@ -404,7 +558,7 @@ export const v2Personality = {
         // `TM_R6_FINE_ASK=off`, or no hook installed to hand the decision to.
         const escalateShellAsk = envProtectMode !== "off" && needsCoarseShellAsk(process.env, guards.installed);
         // Team is ALWAYS the default (the user's standing instruction — see the
-        // header for why this cannot be the conservative v1 form).  `default()` on
+        // header for why there is no conservative form).  `default()` on
         // an agent that does not exist would just make the host fall back to build
         // silently, so it is gated on the role actually being present, and the
         // refusal to promote is reported rather than hidden.
@@ -423,16 +577,16 @@ export const v2Personality = {
                     const { triples, unmapped } = triplesFromAgentPermission(agents[id]?.permission, { escalateShellAsk, agentName: id });
                     for (const u of unmapped)
                         unmappedActions.add(u);
-                    // `V1_ONLY_TOOLS` is passed as the reclaim set: a triple naming an
-                    // action this personality never registers can only have come from an
-                    // earlier boot, and a permission rule for a tool the host has never
-                    // heard of reads as a capability the user granted.
+                    // `V1_ONLY_TOOLS` is passed as the reclaim set: a triple naming a
+                    // retired action can only have come from an earlier boot, and a
+                    // permission rule for a tool the host has never heard of reads as a
+                    // capability the user granted.
                     const merged = mergeTriples(existing.permissions, triples, V1_ONLY_TOOLS);
                     if (merged.changed)
                         editor.update(id, (a) => { a.permissions = merged.triples; });
                 }
                 if (promoteTeamDefault) {
-                    // `editor.get("team")` returning nothing is NOT evidence the host does
+                    // `editor.get("Team")` returning nothing is NOT evidence the host does
                     // not know the role — the live run is literally executing as `team` while
                     // this snapshot lists only the 7 built-ins, so the transform receives the
                     // agent set from BEFORE the config directory merged.  Gating the
@@ -441,13 +595,13 @@ export const v2Personality = {
                     // the AFTER view is what gets recorded.
                     let ok = true;
                     try {
-                        editor.default("team");
+                        editor.default("Team");
                     }
                     catch {
                         ok = false;
                     }
                     defaultPromoted = ok;
-                    defaultPostCheck = editor.get?.("team") ? "present-after" : "absent-after";
+                    defaultPostCheck = editor.get?.("Team") ? "present-after" : "absent-after";
                 }
                 // Recorded HERE, at the moment of observation.  The host defers this
                 // callback (a live boot reached the trajectory line with
@@ -486,11 +640,14 @@ export const v2Personality = {
                                 return -1;
                             }
                         })(),
-                        agents_editor_ids: (() => {
+                        // The ids the transform callback can SEE — which is the set from BEFORE the config
+                        // directory merges, so it never contains our six roles. Named for what it measures:
+                        // the old name implied "the editor's ids" and the filter made it look truncated
+                        // (2 of 7) when the truth is that the transform runs too early to see them.
+                        agents_editor_ids_at_transform: (() => {
                             try {
                                 return (editor.list?.() ?? [])
                                     .map((a) => String(a?.id ?? "?"))
-                                    .filter((n) => wantedIds.includes(n) || n === "build" || n === "plan")
                                     .join(" ");
                             }
                             catch {
@@ -508,7 +665,7 @@ export const v2Personality = {
             notes.push("ctx.agent.transform 不存在，角色权限矩阵未规范化");
         }
         if (defaultPromoted === false) {
-            notes.push("Team 没有成为默认：editor.default(\"team\") 抛错了");
+            notes.push("Team 没有成为默认：editor.default(\"Team\") 抛错了");
         }
         else if (defaultPromoted && defaultPostCheck !== "present-after") {
             // Measured on a live 2.0.16 standalone boot: the call is accepted, `team` is
@@ -531,14 +688,13 @@ export const v2Personality = {
         // ---------- the request layer ----------
         // The whitelist was only ever a DENY, which stops a call but leaves the
         // tool's description in every request.  Here it becomes a request-level
-        // removal, and the two things v1 baked into the team prompt (the resolved
-        // board root) or into the agent config (temperature) ride the request
+        // removal, and the resolved board root and the temperature ride the request
         // instead — a v2 agent is a config FILE and cannot carry a per-workspace
         // path, and `temperature` is a legacy agent field the runner no longer
-        // sends.  This also starts the blackboard TTL sweeper, which v1 owns and v2
-        // otherwise silently lacked: the note promises a sweep, so shipping it
-        // without the sweeper would be the exact overstated claim this product is
-        // built to refuse.
+        // sends.  This also starts the blackboard TTL sweeper, which this
+        // personality otherwise silently lacked: the note promises a sweep, so
+        // shipping it without the sweeper would be the exact overstated claim this
+        // product is built to refuse.
         const ttlMs = resolveTtlMs(options);
         const ttlDays = Math.round(ttlMs / (24 * 60 * 60 * 1000)) || DEFAULT_TTL_DAYS;
         const note = blackboardNote(startBlackboardMaintenance(directory, ttlMs), ttlDays);
@@ -573,7 +729,70 @@ export const v2Personality = {
                 }
             }
         }
-        const session = await applyV2SessionLayer(ctx, { temperature, note, noteAgents: ["team"], plan, scope });
+        const session = await applyV2SessionLayer(ctx, {
+            temperature,
+            note,
+            noteAgents: ["Team"],
+            plan,
+            scope,
+            // #49 feature 4: 拆分任务.  The layer owns no store, so the trajectory sink
+            // is wired here — same shape as the retry governor's `onEvent`.
+            split: resolveSplitConfig(v2Env),
+            onSplit: (row) => {
+                try {
+                    tmRuntime.pipelines.store.appendTrajectory({ tool: "host", step_id: "v2-split", api: 2, ...row });
+                }
+                catch {
+                    /* the trajectory is an extra, never a reason to fail the call */
+                }
+            },
+        });
+        // #58: point the late-bound reader at the real observation now that the
+        // request layer exists, so `v2-surface` carries `tools_in_request` too.
+        tmInRequestSurface = () => (session.report.tmInRequestSurface ? "tm-in-request" : "catalog-only");
+        // #49 feature 3: 错峰重试.  We have no seam that intercepts the model's own
+        // retry, so this layer only (1) recognises a provider throttle from the event
+        // feed, (2) injects an exact wait into the next request, and (3) denies new
+        // dispatches during the breaker's cooldown.  Registered AFTER the permission
+        // guards so its `evaluate` hook runs after the concurrency cap — both only
+        // ever deny, so whichever fires first keeps its message and the stricter
+        // effect (deny) stands either way.
+        const retryConfig = resolveRetryConfig(v2Env);
+        // The layer owns no store, so the trajectory sink is wired here — same shape
+        // as the shell-timeout clamp's `onClamp` and the SERP guard's `onSerp`.
+        const retrySink = (row) => {
+            try {
+                tmRuntime.pipelines.store.appendTrajectory({ tool: "host", step_id: "v2-retry", api: 2, ...row });
+            }
+            catch {
+                /* the trajectory is an extra, never a reason to fail the call */
+            }
+        };
+        const retryGovernor = createRetryGovernor({ ...retryConfig, onEvent: retrySink });
+        const retry = retryConfig.enabled
+            ? await applyV2RetryGovernor(ctx, { scope, governor: retryGovernor, onEvent: retrySink })
+            : { registrations: [], report: retryGovernor.report };
+        registrations.push(...retry.registrations);
+        // Context Pruning (plan 功能 1, #49): the request layer trims the tool
+        // surface, the HOST decides WHEN to summarize — the plugin's own 75% trigger was
+        // removed in 1.7.1 (see CHANGELOG), and this layer
+        // shrinks the HISTORY itself — settled messages become one-line pointers
+        // (handle / child id / re-run hint) once the session crosses a fraction of
+        // its window.  Registered AFTER the session layer so its `context` hook runs
+        // on the same assembled request, and it never touches a message outside its
+        // plan (the newest message and every hard-protected one stay byte-exact).
+        const prune = await applyV2ContextPrune(ctx, {
+            config: resolvePruneConfig(process.env),
+            scope,
+            onEvent: (row) => {
+                try {
+                    tmRuntime.pipelines.store.appendTrajectory({ tool: "host", step_id: "v2-prune", event: "prune", api: 2, ...row });
+                }
+                catch {
+                    /* a diagnostic that cannot be written never breaks the request it describes */
+                }
+            },
+        });
         // Everything the matrix reports now exists, so the late-bound closure can be
         // pointed at the real observations.
         v2Matrix = () => v2CapabilityRows({
@@ -584,6 +803,23 @@ export const v2Personality = {
             offload,
             sessionHooks: 2,
             temperature,
+            // The prune layer's counters, handed to the matrix so its row can earn `ok` on a
+            // process that actually pruned something. Without this the row could only ever read
+            // `declared`, which is the "wired but never observed" shape the matrix exists to
+            // distinguish from "it ran".
+            prune: {
+                enabled: prune.report.enabled,
+                atPercent: prune.report.atPercent,
+                keepTailPercent: prune.report.keepTailPercent,
+                checked: prune.report.checked,
+                prunedMessages: prune.report.prunedMessages,
+                prunedTokens: prune.report.prunedTokens,
+                below: prune.report.below,
+                noLimit: prune.report.noLimit,
+                foreignSkipped: prune.report.foreignSkipped,
+                threw: prune.report.threw,
+                lastPercent: prune.report.lastPercent,
+            },
             // Both derived, not asserted: "we think v2 has no X" has to come from the
             // object we were handed, so a host that grows the seam shows up here
             // automatically instead of leaving a stale "missing" row forever.
@@ -606,16 +842,23 @@ export const v2Personality = {
             scope,
         });
         registrations.push(...session.registrations);
+        registrations.push(...prune.registrations);
         if (!session.registrations.length) {
             notes.push("ctx.session.hook 不存在：工具面裁剪、温度、黑板根目录三项请求层治理都没装上");
         }
-        // v1 handed the plugin a host `event` hook and pumped every session.idle /
-        // session.error / session.status into the child registry.  This personality had
-        // no subscription at all (#8), so a child that settled two seconds after the
-        // dispatch stayed "running" for the whole wait budget and `tm_join` reported a
-        // state it had never observed — goal #6's failure shape, and a bug rather than
-        // a limitation now that `ctx.event.subscribe()` is measured to work.
-        const feed = await applyV2EventFeed(ctx, { onEvent: (ev) => tmRuntime.observeDispatchEvent(ev) });
+        // This personality had no event subscription at all (#8), so a child that
+        // settled two seconds after the dispatch stayed "running" for the whole wait
+        // budget and `tm_join` reported a state it had never observed — goal #6's
+        // failure shape, and a bug rather than a limitation now that
+        // `ctx.event.subscribe()` is measured to work.
+        const feed = await applyV2EventFeed(ctx, {
+            onEvent: (ev) => tmRuntime.observeDispatchEvent(ev),
+            // #49 feature 3: the retry governor's error tap.  `session.error` is the only
+            // place a provider throttle is published; the governor classifies its text and
+            // arms the next-request directive / the cooldown.  A tap that throws never
+            // closes the feed (the governor itself never throws).
+            onError: (data) => retryGovernor.observeEvent(data),
+        });
         if (!feed.report.active) {
             notes.push(`事件流没接通（${feed.report.stopped ?? "原因未知"}）：tm_join 的结算检测只剩等待预算内的轮询，子代理结算了也要等到超时才报告`);
         }
@@ -627,7 +870,7 @@ export const v2Personality = {
             const ids = new Set(probe.report.agentsSeen);
             for (const id of Object.keys(session.report.removed))
                 ids.add(id);
-            return [...ids].filter((id) => wantedIds.includes(id)).sort();
+            return [...ids].filter((id) => wantedIds.some((w) => normalizeAgentName(w) === normalizeAgentName(id))).sort();
         };
         observationCounters = (source) => ({
             counters_at: source,
@@ -636,12 +879,66 @@ export const v2Personality = {
             guard_shell_matched: guards.report.shellMatched,
             guard_strictened: guards.report.strictened,
             guard_denied: guards.report.denied,
+            guard_envfile_denied: guards.report.envFileDenied,
+            guard_envfile_denied_by_input: guards.report.envFileDeniedByInput,
+            guard_envfile_input_seen: guards.report.envFileInputSeen,
+            guard_envfile_input_threw: guards.report.envFileInputThrew,
+            guard_envfile_input_foreign_skipped: guards.report.envFileInputForeignSkipped,
             guard_foreign_skipped: guards.report.foreignSkipped,
+            // #49 feature 2: the concurrency cap — how many `subagent` evaluations it
+            // looked at, how many it denied, and the peak running count it saw.
+            concurrency_seen: guards.report.concurrencySeen,
+            concurrency_denied: guards.report.concurrencyDenied,
+            concurrency_running_max: guards.report.concurrencyRunningMax,
+            concurrency_threw: guards.report.concurrencyThrew,
             subagent_seen: bgForce.report.seen,
             subagent_forced: bgForce.report.forced,
-            tools_removed: Object.entries(session.report.removed).map(([k, v]) => `${k}=${v}`).join(" "),
+            shell_timeout_seen: shellTimeout.report.seen,
+            shell_timeout_clamped: shellTimeout.report.clamped,
+            shell_timeout_foreign_skipped: shellTimeout.report.foreignSkipped,
+            shell_timeout_threw: shellTimeout.report.threw,
+            // (a) The PLAN, not our hook's own cut.  `session.report.removed` counts what
+            // THIS layer deleted from `event.tools`, and on a live host that is 0 because
+            // the permission layer already excluded the denied names before the request
+            // reached us — so the old field read as "nothing was trimmed" while the boot
+            // row's `request_removed_plan` said `team=7`.  The whitelist's effect on the
+            // request IS the removal, so this reports the plan (aligned with
+            // `request_removed_plan`); the hook's own cut is an implementation detail that
+            // is 0 by design, not a fact the user needs a separate field for.
+            tools_removed: [...plan.entries()].map(([k, v]) => `${k}=${v.size}`).join(" "),
             note_pushed: session.report.notePushed,
             compaction_lines: session.report.compactionLines,
+            // #49 feature 4: 拆分任务 — briefs measured and advice injected.
+            split_seen: session.report.splitSeen,
+            split_advised: session.report.splitAdvised,
+            // #49 Context Pruning — the history-shrinking half of the budget work.
+            prune_enabled: prune.report.enabled,
+            prune_at_percent: prune.report.atPercent,
+            prune_keep_tail_percent: prune.report.keepTailPercent,
+            prune_checked: prune.report.checked,
+            prune_pruned_messages: prune.report.prunedMessages,
+            prune_pruned_tokens: prune.report.prunedTokens,
+            prune_unknown_parts: prune.report.unknownParts,
+            prune_skipped_protected: prune.report.skippedProtected,
+            prune_below: prune.report.below,
+            prune_no_limit: prune.report.noLimit,
+            prune_foreign_skipped: prune.report.foreignSkipped,
+            prune_threw: prune.report.threw,
+            prune_last_percent: prune.report.lastPercent,
+            // #49 feature 3: 错峰重试 — recognition counts, breaker trips, cooldown
+            // denials and the last computed wait, so "we backed off" is a number.
+            retry_enabled: retry.report.enabled,
+            retry_quota_seen: retry.report.quotaSeen,
+            retry_rate_seen: retry.report.rateSeen,
+            retry_transient_seen: retry.report.transientSeen,
+            retry_unknown_seen: retry.report.unknownSeen,
+            retry_break_trips: retry.report.breakTrips,
+            retry_cooldowns: retry.report.cooldowns,
+            retry_last_delay_ms: retry.report.lastDelayMs,
+            retry_directives_injected: retry.report.directivesInjected,
+            retry_cooldown_denied: retry.report.cooldownDenied,
+            retry_foreign_skipped: retry.report.foreignSkipped,
+            retry_threw: retry.report.threw,
             scope_ours: scope.report.ours,
             scope_foreign: scope.report.foreign,
             scope_unknown: scope.report.unknown,
@@ -675,6 +972,8 @@ export const v2Personality = {
             browser_gate_refused: browserGate.report.refused,
             browser_gate_leaked: browserGate.report.leaked,
             browser_gate_held: browserGate.report.held,
+            browser_gate_serp_nav: browserGate.report.serpNav,
+            browser_gate_serp_refused: browserGate.report.serpRefused,
             native_seen: offload.report.seen,
             native_ours: offload.report.ours,
             native_unmatched: offload.report.unmatched,
@@ -683,6 +982,13 @@ export const v2Personality = {
             native_tokens_saved: offload.report.tokensSaved,
             native_capped: offload.report.capped,
             native_report_capped: offload.report.reportCapped,
+            // #35: the Code Mode adoption hint — how many native file/command calls we
+            // saw, and how many results actually carried the appended line.
+            probe_chain_seen: probeChain.report.seen,
+            probe_chain_advised: probeChain.report.advised,
+            probe_chain_reset: probeChain.report.reset,
+            probe_chain_foreign_skipped: probeChain.report.foreignSkipped,
+            probe_chain_threw: probeChain.report.threw,
         });
         const removedPlanSizes = [...plan.entries()].map(([id, set]) => `${id}=${set.size}`).join(" ");
         try {
@@ -725,6 +1031,11 @@ export const v2Personality = {
                 request_temperature: temperature === false ? "off" : temperature,
                 request_removed_plan: removedPlanSizes,
                 board_ttl_days: ttlDays,
+                // #38: the runtime fallback's verdict — "ok" / "missing-role" / "no-default"
+                // / "no-config" / "unreadable".  `default_agent_missing` names the role only
+                // when one is actually missing, so a clean boot prints an empty string.
+                default_agent_check: defaultAgentCheck.state,
+                default_agent_missing: defaultAgentCheck.state === "missing-role" ? defaultAgentCheck.defaultAgent ?? "" : "",
                 env_protect: envProtectMode,
                 note: notes.join(" · "),
             });
@@ -732,9 +1043,9 @@ export const v2Personality = {
         catch {
             /* the trajectory is an extra here, never a reason to fail the boot */
         }
-        // A v1 user reading their own logs would otherwise conclude the plugin was
-        // silently broken: these two facts are the visible difference between the
-        // personalities.
+        // A user reading their own logs would otherwise conclude the plugin was
+        // silently broken: these facts are the visible difference between a working
+        // install and a silent one.
         // A2: three states, ONE definition.  The sentence that used to live here —
         // `配置里缺角色：…` — asserted a fact about files from a snapshot that is blind by
         // construction (`ctx.agent.transform` receives the agent set from before the
@@ -773,11 +1084,55 @@ export const v2Personality = {
                     guard_shell_matched: guards.report.shellMatched,
                     guard_strictened: guards.report.strictened,
                     guard_denied: guards.report.denied,
+                    guard_envfile_denied: guards.report.envFileDenied,
+                    guard_envfile_denied_by_input: guards.report.envFileDeniedByInput,
+                    guard_envfile_input_seen: guards.report.envFileInputSeen,
+                    guard_envfile_input_threw: guards.report.envFileInputThrew,
+                    guard_envfile_input_foreign_skipped: guards.report.envFileInputForeignSkipped,
+                    concurrency_seen: guards.report.concurrencySeen,
+                    concurrency_denied: guards.report.concurrencyDenied,
+                    concurrency_running_max: guards.report.concurrencyRunningMax,
+                    concurrency_threw: guards.report.concurrencyThrew,
                     subagent_seen: bgForce.report.seen,
                     subagent_forced: bgForce.report.forced,
-                    tools_removed: Object.entries(session.report.removed).map(([k, v]) => `${k}=${v}`).join(" "),
+                    shell_timeout_seen: shellTimeout.report.seen,
+                    shell_timeout_clamped: shellTimeout.report.clamped,
+                    shell_timeout_foreign_skipped: shellTimeout.report.foreignSkipped,
+                    shell_timeout_threw: shellTimeout.report.threw,
                     note_pushed: session.report.notePushed,
                     compaction_lines: session.report.compactionLines,
+                    // #49 feature 4: 拆分任务 — the same counter set as the surface row.
+                    split_seen: session.report.splitSeen,
+                    split_advised: session.report.splitAdvised,
+                    // #49 Context Pruning — per-outcome, so "we pruned nothing" is
+                    // distinguishable from "we never found a denominator" (`no_limit`).
+                    prune_enabled: prune.report.enabled,
+                    prune_at_percent: prune.report.atPercent,
+                    prune_keep_tail_percent: prune.report.keepTailPercent,
+                    prune_checked: prune.report.checked,
+                    prune_pruned_messages: prune.report.prunedMessages,
+                    prune_pruned_tokens: prune.report.prunedTokens,
+                    prune_unknown_parts: prune.report.unknownParts,
+                    prune_skipped_protected: prune.report.skippedProtected,
+                    prune_below: prune.report.below,
+                    prune_no_limit: prune.report.noLimit,
+                    prune_no_messages: prune.report.noMessages,
+                    prune_foreign_skipped: prune.report.foreignSkipped,
+                    prune_threw: prune.report.threw,
+                    prune_last_percent: prune.report.lastPercent,
+                    // #49 feature 3: 错峰重试 — the same counter set as the surface row.
+                    retry_enabled: retry.report.enabled,
+                    retry_quota_seen: retry.report.quotaSeen,
+                    retry_rate_seen: retry.report.rateSeen,
+                    retry_transient_seen: retry.report.transientSeen,
+                    retry_unknown_seen: retry.report.unknownSeen,
+                    retry_break_trips: retry.report.breakTrips,
+                    retry_cooldowns: retry.report.cooldowns,
+                    retry_last_delay_ms: retry.report.lastDelayMs,
+                    retry_directives_injected: retry.report.directivesInjected,
+                    retry_cooldown_denied: retry.report.cooldownDenied,
+                    retry_foreign_skipped: retry.report.foreignSkipped,
+                    retry_threw: retry.report.threw,
                     // Accumulates for the whole process, so it can only be written at
                     // teardown: this is the number that answers "did the feed stay alive, and
                     // did the host rename the event types under us after the last upgrade?"
@@ -789,6 +1144,8 @@ export const v2Personality = {
                     browser_gate_refused: browserGate.report.refused,
                     browser_gate_leaked: browserGate.report.leaked,
                     browser_gate_held: browserGate.report.held,
+                    browser_gate_serp_nav: browserGate.report.serpNav,
+                    browser_gate_serp_refused: browserGate.report.serpRefused,
                     browser_gate_note: browserGateSummary(browserGate.report),
                     // What the model could actually call, read off the assembled requests —
                     // the half of the delivery story the sent flag cannot tell.
@@ -845,7 +1202,7 @@ export const v2Personality = {
                     /* a host that already tore down its own registry has nothing left to free */
                 }
             }
-            // tm_browser owns a child process — teardown waits on v1 and must wait here too.
+            // A tool may own a child process — teardown must await it.
             await tmRuntime.dispose();
         };
     },