@henryqw/pi-subagent 27.1.2 → 27.2.1

package/CONTEXT.md

@@ -36,6 +36,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 ### Global limits
 
 - `config/pi-subagent/config.json` is the only user execution-policy source. It owns `maxSubagents`, `maxTurns`, optional `maxTokens`, `maxCorrections`, and child idle/hard timeout.
+- The config loads through `@henryqw/pi-config-store` fields. An unknown key or an invalid bounded limit, timeout, or `roleDefaults` key warns at launch and uses its finite default. An invalid `maxTokens`, or a file that cannot be read or parsed, disables delegation with an error, because the token default is unlimited. Role Markdown files keep per-file exclusion; durable state stays strict.
 - Request fields cannot override or replenish policy. Durable requests store the policy snapshot and cumulative correction count; current config may tighten the correction allowance.
 - Productive execution has no whole-run wall-clock deadline. Long productive work and later resume remain valid. Direct Herdr observation also has no whole-task elapsed deadline; worker idleness is bounded.
 - Child idle/hard runtime, turn/token handling, outer abort, process I/O, status inspection, termination, and cleanup remain independently bounded. Direct Herdr workers use idle limits, not ephemeral child hard runtime.

package/README.md

@@ -45,7 +45,7 @@ Commands are for you. Delegation and state tools and the packaged skill are for
 | `subagent_abort` | tool | Abort an isolated request only when no retained candidates or integration worktrees remain; cannot discard them. |
 | `git_read` | tool | For Role-declared children (not Main): inspect bounded local Git evidence without Bash, tests, network access, or writes. |
 | `pi-subagent` | skill | Guide Main through delegation, authorization, checks, integration, and recovery. |
-| Direct status widget (`D`) | ui | For you in the TUI: show direct worker references (such as `D7.1`), status, Role badges, names, route, task elapsed time, measured session tokens, pending tools, and the latest tool's recorded time. |
+| Direct status widget (`D`) | ui | For you in the TUI: show direct worker references (such as `D7.1`), status, Role badges, names, route, task elapsed time, measured task tokens, pending tools, and the latest tool's recorded time. |
 | Isolated status widget (`I`) | ui | For you in the TUI: show recorded task state, Role/model-class badges, and retained workspaces; readiness does not mean promotion. |
 
 ![Main, its coordinator extension, and a Herdr subagent through checked work, worker failure, and coordinator interruption](./docs/worker-lifecycle.svg)
@@ -56,7 +56,9 @@ The coordinator is extension code that runs in Main's Pi process. It is not anot
 
 The TUI has two separate compact status widgets. Each widget has one row for each visible worker or task. `D` marks direct work, and `I` marks isolated work. Badges such as `[S]` and `[I3]` identify the Role initial. Isolated badges also include the model class: `1` fast, `2` balanced, `3` frontier, `*` fav.
 
-Each direct row starts with a saved direct reference such as `D7.1`. `D7` is the workflow number in this Pi session, and `.1` is the position of the worker in the original request. `/subagent` uses the same reference and name. The Herdr tab label shows them at launch. Numbers continue after reload, and the session never uses a number again. A session switch can move a workflow into a session that already uses its number. In that case, the workflow gets a new number there. An existing Herdr tab keeps its original launch label. The direct widget shows the launched model, thinking level, elapsed time, and measured session tokens (`— tok` until usage is available). Failed rows show before working and completed rows. When rows overflow, `… N more` includes counts by status. The isolated widget shows the recorded task state and any retained workspace. It does not show reliable live model, thinking, or token readings from Herdr. Attention shows before ordinary work, and overflow uses `+N more · /subagent`. An aborted request with visible tasks has its own `request aborted` row. This row does not change the recorded statuses of the tasks. A committed worker without a checked candidate can show attention, not readiness. Status glyphs use the active TUI theme. The text also names the status without color.
+Each direct row starts with a saved direct reference such as `D7.1`. `D7` is the workflow number in this Pi session, and `.1` is the position of the worker in the original request. `/subagent` uses the same reference and name. The Herdr tab label shows them at launch. Numbers continue after reload, and the session never uses a number again. A session switch can move a workflow into a session that already uses its number. In that case, the workflow gets a new number there. An existing Herdr tab keeps its original launch label. The direct widget shows the launched model, thinking level, elapsed time, and measured task tokens (`— tok` until usage is available). Failed rows show before working and completed rows. When rows overflow, `… N more` includes counts by status. The isolated widget shows the recorded task state and any retained workspace. It does not show reliable live model, thinking, or token readings from Herdr. Attention shows before ordinary work, and overflow uses `+N more · /subagent`. An aborted request with visible tasks has its own `request aborted` row. This row does not change the recorded statuses of the tasks. A committed worker without a checked candidate can show attention, not readiness. Status glyphs use the active TUI theme. The text also names the status without color.
+
+For the direct widget and result summaries, measured tokens are the cumulative input and output tokens from completed assistant usage records for the current task turn. Cache-read and cache-write tokens are excluded. A continued worker counts only its new task turn. Missing usage stays unknown. This display count does not change token-limit accounting.
 
 A ready isolated candidate is **not promoted** to Main. To reload the menu and the isolated widget from saved state, choose **Refresh** in `/subagent`. Refresh does not recover or change a request. Use `/subagent` or `subagent_status` for exact identities, failures, and recovery.
 
@@ -111,7 +113,7 @@ Tab creation can time out or return an incomplete or mismatched identity. In tha
 
 Tasks in a write request must return one JSON completion object, such as `{"outcome":"succeeded","answer":"Scoped commit completed."}`. `outcome` must be `succeeded`, `failed`, or `blocked`, and `answer` must be non-empty. A normal final Pi turn is not sufficient. Failure, blocked work, plain text, or a malformed completion stops later dispatch. But admission depends on proved termination, not on the reported outcome. Success is the explicit report of the worker. It is not an independent validation of its changes.
 
-The tool returns a task ID and the first Herdr tab after launch, not the answer. The extension observes each worker and sends one result to Main when the workflow finishes. If Main is busy, Pi queues the result after the current turn. If Main is idle, the result starts a turn. The extension does not report a blocked, stalled, unknown, or truncated result as success. In the result, the line of each launched worker shows its model, thinking level, measured session tokens, and elapsed time, such as `✓ [1/2] Check · worker · provider/model · thinking high · 1.5k tok · 42s`. If Pi recorded no usage, the line shows `tokens unknown`. Failed and stopped workers show the usage that the extension measured until they ended. A worker that the extension skipped before launch shows no usage. The result details contain the same values in each entry as `model`, `thinkingLevel`, `tokens`, and `elapsedMs`. When the token count is unknown, `tokens` is absent. If a task fails after its worker produced text, the result keeps a bounded excerpt marked as partial output. This excerpt is never success. Every worker result delivered to Main starts with a header. The header states that the text is the output of the worker and carries no user authority. Text that imitates harness framing gets an inserted backslash. Examples are `<system-reminder>`-style tags and lines that start with `Human:` or `Assistant:`. Nothing else changes. Isolated status and follow-up answer previews use the same header. A session switch or shutdown stops observation and preserves tab identities for recovery. To inspect exact tabs, agents, and Pi session files, open `/subagent` on the session branch. This includes tabs launched after the first. The menu has one row for each workflow. A single worker shows its reference, Role, and name (`D7.1 · worker · Search audit`). A multi-worker workflow shows its reference and worker count (`D8 · 3 workers`). When you select it, the menu lists each recorded worker by reference, Role, and name with its exact IDs. References and names help you match rows. The extension never uses them to decide ownership. Older records without saved references show their saved allocation label or exact task ID. A `recorded only` row does not prove that its workers run or finished. The menu labels locally observed work separately.
+The tool returns a task ID and the first Herdr tab after launch, not the answer. The extension observes each worker and sends one result to Main when the workflow finishes. If Main is busy, Pi queues the result after the current turn. If Main is idle, the result starts a turn. The extension does not report a blocked, stalled, unknown, or truncated result as success. In the result, the line of each launched worker shows its model, thinking level, measured task tokens, and elapsed time, such as `✓ [1/2] Check · worker · provider/model · thinking high · 1.5k tok · 42s`. If Pi recorded no usage, the line shows `tokens unknown`. Failed and stopped workers show the usage that the extension measured until they ended. A worker that the extension skipped before launch shows no usage. The result details contain the same values in each entry as `model`, `thinkingLevel`, `tokens`, and `elapsedMs`. When the token count is unknown, `tokens` is absent. If a task fails after its worker produced text, the result keeps a bounded excerpt marked as partial output. This excerpt is never success. Every worker result delivered to Main starts with a header. The header states that the text is the output of the worker and carries no user authority. Text that imitates harness framing gets an inserted backslash. Examples are `<system-reminder>`-style tags and lines that start with `Human:` or `Assistant:`. Nothing else changes. Isolated status and follow-up answer previews use the same header. A session switch or shutdown stops observation and preserves tab identities for recovery. To inspect exact tabs, agents, and Pi session files, open `/subagent` on the session branch. This includes tabs launched after the first. The menu has one row for each workflow. A single worker shows its reference, Role, and name (`D7.1 · worker · Search audit`). A multi-worker workflow shows its reference and worker count (`D8 · 3 workers`). When you select it, the menu lists each recorded worker by reference, Role, and name with its exact IDs. References and names help you match rows. The extension never uses them to decide ownership. Older records without saved references show their saved allocation label or exact task ID. A `recorded only` row does not prove that its workers run or finished. The menu labels locally observed work separately.
 
 ### Continue or stop one direct worker
 
@@ -220,11 +222,19 @@ pi-subagent owns `~/.pi/agent/config/pi-subagent/config.json`. If the file is mi
 | `maxCorrections` | Same-worker automatic corrections per isolated request | Safe integer ≥ 0 | `1` |
 | `timeout.idleMinutes` | Direct worker and ephemeral child idle timeout | Positive and within Node's timer range | `10` |
 | `timeout.maxMinutes` | Ephemeral child hard runtime | Greater than idle and within Node's timer range | `30` |
-| `roleDefaults` | Optional `extensions`, `tools`, and `skills` arrays merged into every built-in and user Role, with the same validation as Role fields | Object; unknown keys rejected | None |
+| `roleDefaults` | Optional `extensions`, `tools`, and `skills` arrays merged into every built-in and user Role, with the same validation as Role fields | Object with `extensions`, `tools`, or `skills` | None |
 
 In each merged list, `roleDefaults` entries come first, and the entries of the Role follow. The merge removes duplicates and occurs before resource resolution. Use `roleDefaults` for the provider extension that every child needs. Limits come only from this global file. Request fields cannot override or replenish them. Existing durable requests keep their recorded policy, but a lower current correction limit can tighten recovery. Intentionally, there is no whole-run timeout setting.
 
-Malformed or unreadable JSON, unknown keys, and invalid values block delegation with one actionable warning. The extension preserves the file and never rewrites it automatically.
+A bad config never stops the extension. At launch, and again each time it reads the file (a `delegate_task` call, each later worker of a direct chain, each isolated Role launch, `/subagent roles`, or a status inspection), the extension shows each new problem one time:
+
+- An unknown key shows a warning. The extension ignores the key.
+- A misspelled key that is near a missing key, such as `maxToken` for `maxTokens`, counts as an invalid value of that key. The warning gives the likely key.
+- An invalid value in `maxSubagents`, `maxTurns`, `maxCorrections`, or `timeout` shows a warning. The extension uses the finite default for that key. If `timeout.maxMinutes` is not greater than `timeout.idleMinutes`, the extension uses the default `timeout`.
+- An unknown or invalid key in `roleDefaults` shows a warning. The extension ignores only that key, so Roles get fewer default resources.
+- An invalid or misspelled `maxTokens`, malformed JSON, invalid UTF-8, a file larger than 64 KiB, or an unreadable file shows an error and blocks delegation. The default token limit is unlimited, so the extension does not use a default in these cases. `/subagent` stays available. Correct the file to enable delegation again. The block also applies to work that already runs: the next worker of a direct workflow, or the next Role launch of an isolated request, fails before it starts. A workflow that runs keeps the limits that it started with. If the file had the problem when the session started, also run `/reload`, because the session took its execution limits from the defaults.
+
+No key is required. The extension preserves the file and never rewrites it automatically.
 
 ### Roles
 
@@ -274,6 +284,7 @@ The servers named in `mcps` come only from the global `~/.pi/agent/mcp.json`. In
 | Surface | Type | Purpose |
 | --- | --- | --- |
 | `loadRoleCatalog`, `findRole`, `parseRoleName`, `parseRoleDefaults` | functions | Load built-in and user Roles with `roleDefaults` and per-file errors, then select one by name. |
+| `registerRoleDefaultsReporting(pi, agentDir?)` | function | Reports `roleDefaults` problems at each session start. Returns `report(ctx)`; call it before a lazy `loadRoleCatalog`. Each problem shows one time in each session. |
 | `resolveRoleSkills`, `resolveRoleLaunch`, `resolveConfiguredRoleLaunch` | functions | Resolve effective Pi resources and model routes. |
 | `prepareRoleLaunch`, `finalizeRoleLaunch` | functions | Prepare Role prompts, arguments, and tool policy. |
 | `createEphemeralSubagentExecutor` | function | Run bounded no-session Pi children through a FIFO pool. |

package/dist/direct-herdr.js

@@ -155,7 +155,7 @@ export function directSessionUsage(jsonl, prompt) {
         else if (active && message.role === "assistant") {
             if (message.usage && typeof message.usage === "object") {
                 const usage = message.usage;
-                const values = [usage.input, usage.output, usage.cacheRead, usage.cacheWrite];
+                const values = [usage.input, usage.output];
                 if (values.every((value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0)) {
                     total += values.reduce((sum, value) => sum + value, 0);
                     observed = true;

package/dist/index.d.ts

@@ -94,6 +94,40 @@ export interface ResolvedRoleSkills {
 export declare function parseRoleName(value: unknown, source?: string): RoleName;
 /** Validate `config.json` `roleDefaults` with the same rules as Role fields; `label` prefixes errors. */
 export declare function parseRoleDefaults(value: unknown, label?: string): RoleDefaults;
+export interface SubagentConfig {
+    maxSubagents: number;
+    maxTurns: number;
+    maxTokens: number | undefined;
+    maxCorrections: number;
+    timeout: {
+        idleMinutes: number;
+        maxMinutes: number;
+    };
+    roleDefaults: RoleDefaults;
+}
+export declare const DEFAULT_SUBAGENT_CONFIG: Readonly<SubagentConfig>;
+/**
+ * The user `config.json` store shared by the extension and `loadRoleCatalog`.
+ * Invalid bounded limits and `roleDefaults` keys fall back to defaults; an
+ * invalid `maxTokens` disables the config because its default is unlimited.
+ */
+export declare function createSubagentConfigStore(agentDir?: string): import("@henryqw/pi-config-store").ConfigStore<import("@henryqw/pi-config-store").FieldsValue<{
+    maxSubagents: import("@henryqw/pi-config-store").Field<number>;
+    maxTurns: import("@henryqw/pi-config-store").Field<number>;
+    maxTokens: import("@henryqw/pi-config-store").Field<number | undefined>;
+    maxCorrections: import("@henryqw/pi-config-store").Field<number>;
+    timeout: import("@henryqw/pi-config-store").Field<{
+        idleMinutes: number;
+        maxMinutes: number;
+    }>;
+    roleDefaults: import("@henryqw/pi-config-store").Field<RoleDefaults>;
+}>>;
+/**
+ * Report `roleDefaults` issues at each session start, and return a function that reports them after a lazy
+ * Role catalog load, such as `loadRoleCatalog` or `resolveRoleLaunch`. Every pi-config-store reporter shares
+ * one record, so each issue shows one time in each session, also with the pi-subagent extension active.
+ */
+export declare function registerRoleDefaultsReporting(pi: Pick<ExtensionAPI, "on">, agentDir?: string): (ctx: Pick<ExtensionContext, "hasUI" | "ui">) => void;
 declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer", "scout"];
 export type BuiltinRoleName = (typeof BUILTIN_ROLE_NAMES)[number];
 export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
@@ -101,7 +135,8 @@ export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
  * Package-shipped Roles plus user Roles from `config/pi-subagent`, with
  * `roleDefaults` merged in. A user Role overrides a same-named built-in. Each
  * invalid or duplicate user file is reported and makes its claimed name
- * unavailable without hiding valid Roles. Malformed `roleDefaults` throws.
+ * unavailable without hiding valid Roles. Invalid `roleDefaults` keys are
+ * dropped; a `config.json` that cannot load (for example, malformed JSON) throws.
  */
 export declare function loadRoleCatalog(agentDir?: string): RoleCatalog;
 /** Select one catalog Role, naming invalid files that claim it. */

package/dist/index.js

@@ -2,8 +2,9 @@ import { readFileSync, readdirSync } from "node:fs";
 import { basename, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DefaultPackageManager, getAgentDir, parseFrontmatter, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { extensionConfigDir, extensionConfigPath } from "@henryqw/pi-config-store";
+import { createConfigStore, extensionConfigDir, field, formatConfigIssues, parsers, registerConfigReporting } from "@henryqw/pi-config-store";
 import { hasDisplayControlCharacters } from "./display-text.js";
+import { DEFAULT_MAX_TURNS } from "./ephemeral.js";
 import { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
 import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
@@ -172,27 +173,97 @@ export function parseRoleDefaults(value, label = "roleDefaults") {
         ...(record.skills === undefined ? {} : { skills: stringList(record.skills, "skills", label) }),
     };
 }
-function readRoleDefaults(agentDir) {
-    const path = extensionConfigPath("pi-subagent", agentDir);
-    let raw;
-    try {
-        raw = readFileSync(path, "utf8");
-    }
-    catch (error) {
-        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
-            return {};
-        throw error;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+/** Per-key `roleDefaults`: an unknown key or invalid list is reported and dropped, so fewer resources load. */
+const roleDefaultsField = (raw, report) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("must be a JSON object");
+    const defaults = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!ROLE_DEFAULT_KEYS.includes(key)) {
+            report([key], "unknown key", "unknown-key");
+            continue;
+        }
+        try {
+            Object.assign(defaults, parseRoleDefaults({ [key]: value }));
+        }
+        catch (error) {
+            report([key], error instanceof Error ? error.message : String(error));
+        }
     }
-    // Whole-file validation belongs to the execution policy reader, which blocks delegation.
-    const value = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.roleDefaults : undefined;
-    return value === undefined ? {} : parseRoleDefaults(value, `${path}: roleDefaults`);
+    return defaults;
+};
+export const DEFAULT_SUBAGENT_CONFIG = Object.freeze({
+    maxSubagents: 5,
+    maxTurns: DEFAULT_MAX_TURNS,
+    maxTokens: undefined,
+    maxCorrections: 1,
+    timeout: Object.freeze({ idleMinutes: 10, maxMinutes: 30 }),
+    roleDefaults: Object.freeze({}),
+});
+const timeoutMinutes = parsers.number({ greaterThan: 0, max: 2_147_483_647 / 60_000 });
+const timeoutField = (raw, report) => {
+    const timeout = parsers.object({
+        idleMinutes: field(timeoutMinutes, DEFAULT_SUBAGENT_CONFIG.timeout.idleMinutes),
+        maxMinutes: field(timeoutMinutes, DEFAULT_SUBAGENT_CONFIG.timeout.maxMinutes),
+    })(raw, report);
+    if (timeout.maxMinutes <= timeout.idleMinutes) {
+        throw new Error(`maxMinutes (${timeout.maxMinutes}) must be greater than idleMinutes (${timeout.idleMinutes})`);
+    }
+    return timeout;
+};
+/**
+ * The user `config.json` store shared by the extension and `loadRoleCatalog`.
+ * Invalid bounded limits and `roleDefaults` keys fall back to defaults; an
+ * invalid `maxTokens` disables the config because its default is unlimited.
+ */
+export function createSubagentConfigStore(agentDir = getAgentDir()) {
+    return createConfigStore({
+        extensionId: "pi-subagent",
+        agentDir,
+        fields: {
+            maxSubagents: field(parsers.integer({ min: 1 }), DEFAULT_SUBAGENT_CONFIG.maxSubagents),
+            maxTurns: field(parsers.integer({ min: 1 }), DEFAULT_SUBAGENT_CONFIG.maxTurns),
+            maxTokens: field(parsers.integer({ min: 1 }), undefined, { onInvalid: "disable" }),
+            maxCorrections: field(parsers.integer({ min: 0 }), DEFAULT_SUBAGENT_CONFIG.maxCorrections),
+            timeout: field(timeoutField, DEFAULT_SUBAGENT_CONFIG.timeout),
+            roleDefaults: field(roleDefaultsField, DEFAULT_SUBAGENT_CONFIG.roleDefaults),
+        },
+    });
+}
+/**
+ * Read only `roleDefaults`. The extension reports and enforces the execution limits, so a bad limit does not
+ * break the Role catalog of other consumers; other keys are not this reader's issues.
+ */
+function loadRoleDefaults(agentDir) {
+    const store = createConfigStore({
+        extensionId: "pi-subagent",
+        agentDir,
+        fields: { roleDefaults: field(roleDefaultsField, DEFAULT_SUBAGENT_CONFIG.roleDefaults) },
+    });
+    const loaded = store.loadSync();
+    const issues = loaded.issues.filter(({ key }) => !key || /^roleDefaults(?![\w$])/.test(key));
+    // A file that cannot load has no trusted `roleDefaults`.
+    return issues.some(({ key }) => !key)
+        ? { store, loaded: { status: "disabled", source: loaded.source, issues } }
+        : { store, loaded: { ...loaded, issues } };
+}
+function readRoleDefaults(agentDir) {
+    const { store, loaded } = loadRoleDefaults(agentDir);
+    if (loaded.status !== "ok")
+        throw new Error(`${store.path}: ${formatConfigIssues(loaded.issues)}`);
+    return loaded.value.roleDefaults;
+}
+/**
+ * Report `roleDefaults` issues at each session start, and return a function that reports them after a lazy
+ * Role catalog load, such as `loadRoleCatalog` or `resolveRoleLaunch`. Every pi-config-store reporter shares
+ * one record, so each issue shows one time in each session, also with the pi-subagent extension active.
+ */
+export function registerRoleDefaultsReporting(pi, agentDir = getAgentDir()) {
+    const target = loadRoleDefaults(agentDir).store;
+    const reporter = registerConfigReporting(pi, []);
+    const report = (ctx) => reporter.report(ctx, target, loadRoleDefaults(agentDir).loaded);
+    pi.on("session_start", (_event, ctx) => report(ctx));
+    return report;
 }
 const withDefaults = (defaults, values) => [...new Set([...(defaults ?? []), ...values])];
 function applyRoleDefaults(role, defaults) {
@@ -262,7 +333,8 @@ function claimedRoleName(file) {
  * Package-shipped Roles plus user Roles from `config/pi-subagent`, with
  * `roleDefaults` merged in. A user Role overrides a same-named built-in. Each
  * invalid or duplicate user file is reported and makes its claimed name
- * unavailable without hiding valid Roles. Malformed `roleDefaults` throws.
+ * unavailable without hiding valid Roles. Invalid `roleDefaults` keys are
+ * dropped; a `config.json` that cannot load (for example, malformed JSON) throws.
  */
 export function loadRoleCatalog(agentDir = getAgentDir()) {
     const defaults = readRoleDefaults(agentDir);
@@ -326,13 +398,8 @@ export function findRole(catalog, name) {
     throw new Error(`Unknown Subagent role: ${name}. Available roles: ${catalog.roles.map((candidate) => candidate.name).join(", ") || "none"}.${catalog.errors.length ? ` ${catalog.errors.length} invalid Role file(s); run /subagent roles.` : ""}`);
 }
 export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
-    let config;
-    try {
-        config = loadTaskModelsConfig(agentDir).value;
-    }
-    catch {
-        throw new Error("Couldn't read task model config. Run /task-models.");
-    }
+    // A disabled config throws with the path and the problems.
+    const config = loadTaskModelsConfig(agentDir).value;
     return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName]);
 }
 function resolveConfiguredRoute(ctx, profileName, profile) {

package/extensions/config.ts

@@ -1,158 +1,21 @@
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { createConfigStore, extensionConfigPath } from "@henryqw/pi-config-store";
+import { formatConfigIssues, type ConfigLoad } from "@henryqw/pi-config-store";
 import type { ExecutionPolicySnapshot } from "../dist/schema.js";
-import { parseRoleDefaults, type RoleDefaults } from "@henryqw/pi-subagent";
-
-export interface SubagentTimeoutConfig {
-	/** Minutes a child may stay idle before it is asked to stop. */
-	idleMinutes?: number;
-	/** Hard cap in minutes before a child is killed regardless of activity. */
-	maxMinutes?: number;
-}
-
-export interface SubagentConfig {
-	maxSubagents?: number;
-	maxTurns?: number;
-	maxTokens?: number;
-	maxCorrections?: number;
-	timeout?: SubagentTimeoutConfig;
-	/** Merged into every Role by `loadRoleCatalog`; validated here so malformed values block delegation. */
-	roleDefaults?: RoleDefaults;
-}
-
-export interface LoadedSubagentConfig {
-	source: "file" | "missing";
-	config: SubagentConfig;
-	/** Human-readable problems; malformed files are preserved and delegation fails closed. */
-	error?: string;
-}
+import type { SubagentConfig } from "@henryqw/pi-subagent";
 
 export type EffectiveExecutionPolicy = ExecutionPolicySnapshot;
 
-type ParsedSubagentConfig = Omit<LoadedSubagentConfig, "source">;
-
-const EXTENSION_ID = "pi-subagent";
-const positive = (value: unknown): value is number =>
-	typeof value === "number" && Number.isFinite(value) && value > 0;
-const MAX_TIMER_DELAY_MS = 2_147_483_647;
-export const DEFAULT_TIMEOUT_CONFIG = { idleMinutes: 10, maxMinutes: 30 } as const;
-export const DEFAULT_EXECUTION_POLICY = {
-	maxSubagents: 5,
-	maxTurns: 50,
-	maxCorrections: 1,
-} as const;
-const INTEGER_FIELDS = ["maxSubagents", "maxTurns", "maxTokens"] as const;
-const POLICY_FIELDS = ["maxCorrections"] as const;
-const TIMEOUT_FIELDS = ["idleMinutes", "maxMinutes"] as const;
-
-export const configPath = (agentDir = getAgentDir()): string =>
-	extensionConfigPath(EXTENSION_ID, agentDir);
-
-function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfig {
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-		return { config: {}, error: `${path} must contain a JSON object; delegation is blocked until this file is corrected.` };
-	}
-	const record = parsed as Record<string, unknown>;
-	const problems: string[] = [];
-	const config: SubagentConfig = {};
-	for (const key of Object.keys(record)) {
-		if (![...INTEGER_FIELDS, ...POLICY_FIELDS, "timeout", "roleDefaults"].includes(key as never)) {
-			problems.push(`unknown config key ${JSON.stringify(key)}; expected ${[...INTEGER_FIELDS, ...POLICY_FIELDS].join(", ")}, timeout, roleDefaults`);
-		}
-	}
-	if (record.roleDefaults !== undefined) {
-		try { config.roleDefaults = parseRoleDefaults(record.roleDefaults); }
-		catch (error) { problems.push(error instanceof Error ? error.message : String(error)); }
+/** Resolve one immutable policy. A disabled config blocks delegation. */
+export function resolveExecutionPolicy(path: string, loaded: ConfigLoad<SubagentConfig>): EffectiveExecutionPolicy {
+	if (loaded.status === "disabled") {
+		throw new Error(`${path}: ${formatConfigIssues(loaded.issues)}; delegation is blocked until this file is corrected.`);
 	}
-	for (const key of INTEGER_FIELDS) {
-		const value = record[key];
-		if (value === undefined) continue;
-		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) config[key] = value;
-		else problems.push(`${key} must be a safe integer >= 1, got ${JSON.stringify(value)}`);
-	}
-	if (record.maxCorrections !== undefined) {
-		if (!Number.isSafeInteger(record.maxCorrections) || (record.maxCorrections as number) < 0) {
-			problems.push(`maxCorrections must be a safe integer >= 0, got ${JSON.stringify(record.maxCorrections)}`);
-		} else config.maxCorrections = record.maxCorrections as number;
-	}
-	if (record.timeout !== undefined) {
-		if (!record.timeout || typeof record.timeout !== "object" || Array.isArray(record.timeout)) {
-			problems.push(`timeout must be a JSON object, got ${JSON.stringify(record.timeout)}`);
-		} else {
-			const timeoutRecord = record.timeout as Record<string, unknown>;
-			const timeout: SubagentTimeoutConfig = {};
-			for (const key of TIMEOUT_FIELDS) {
-				const value = timeoutRecord[key];
-				if (value === undefined) continue;
-				if (!positive(value)) problems.push(`timeout.${key} must be a positive number of minutes, got ${JSON.stringify(value)}`);
-				else if (value * 60_000 > MAX_TIMER_DELAY_MS) problems.push(`timeout.${key} exceeds ${MAX_TIMER_DELAY_MS} ms, got ${JSON.stringify(value)} minutes`);
-				else timeout[key] = value;
-			}
-			for (const key of Object.keys(timeoutRecord)) {
-				if (!TIMEOUT_FIELDS.includes(key as keyof SubagentTimeoutConfig)) problems.push(`unknown timeout.${key}; expected ${TIMEOUT_FIELDS.join(", ")}`);
-			}
-			if (Object.keys(timeout).length) config.timeout = timeout;
-		}
-	}
-	if (config.timeout) {
-		const idleMinutes = config.timeout.idleMinutes ?? DEFAULT_TIMEOUT_CONFIG.idleMinutes;
-		const maxMinutes = config.timeout.maxMinutes ?? DEFAULT_TIMEOUT_CONFIG.maxMinutes;
-		if (maxMinutes <= idleMinutes) {
-			problems.push(`timeout.maxMinutes (${maxMinutes}) must be greater than timeout.idleMinutes (${idleMinutes})`);
-			delete config.timeout;
-		}
-	}
-	return {
-		config,
-		error: problems.length ? `${path}: ${problems.join("; ")}; delegation is blocked until this file is corrected.` : undefined,
-	};
-}
-
-/** Resolve one immutable policy. Malformed explicit safety settings fail closed. */
-export function resolveExecutionPolicy(loaded: LoadedSubagentConfig): EffectiveExecutionPolicy {
-	if (loaded.error) throw new Error(loaded.error);
-	const timeout = loaded.config.timeout;
+	const { maxSubagents, maxTurns, maxTokens, maxCorrections, timeout } = loaded.value;
 	return Object.freeze({
-		maxSubagents: loaded.config.maxSubagents ?? DEFAULT_EXECUTION_POLICY.maxSubagents,
-		maxTurns: loaded.config.maxTurns ?? DEFAULT_EXECUTION_POLICY.maxTurns,
-		...(loaded.config.maxTokens === undefined ? {} : { maxTokens: loaded.config.maxTokens }),
-		childIdleMs: (timeout?.idleMinutes ?? DEFAULT_TIMEOUT_CONFIG.idleMinutes) * 60_000,
-		childMaxMs: (timeout?.maxMinutes ?? DEFAULT_TIMEOUT_CONFIG.maxMinutes) * 60_000,
-		maxCorrections: loaded.config.maxCorrections ?? DEFAULT_EXECUTION_POLICY.maxCorrections,
+		maxSubagents,
+		maxTurns,
+		...(maxTokens === undefined ? {} : { maxTokens }),
+		childIdleMs: timeout.idleMinutes * 60_000,
+		childMaxMs: timeout.maxMinutes * 60_000,
+		maxCorrections,
 	});
 }
-
-/** Read untrusted optional config without rewriting it. */
-export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConfig {
-	const path = configPath(agentDir);
-	let validationError: string | undefined;
-	const store = createConfigStore<SubagentConfig>({
-		extensionId: EXTENSION_ID,
-		agentDir,
-		defaults: () => ({}),
-		parse(value) {
-			const parsed = parseSubagentConfig(value, path);
-			validationError = parsed.error;
-			return parsed.config;
-		},
-	});
-	try {
-		const loaded = store.loadSync();
-		return {
-			source: loaded.source,
-			config: loaded.value,
-			...(validationError === undefined ? {} : { error: validationError }),
-		};
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
-		if (code !== undefined && code !== "ERR_ENCODING_INVALID_ENCODED_DATA") throw error;
-		const reason = error instanceof Error ? error.message : String(error);
-		return {
-			source: "file",
-			config: {},
-			error: error instanceof SyntaxError
-				? `${path} is not valid JSON (${reason}); delegation is blocked until this file is corrected.`
-				: `${path} couldn't be read (${reason}); delegation is blocked until this file is corrected.`,
-		};
-	}
-}

package/extensions/isolated.ts

@@ -482,6 +482,8 @@ export interface RegisterIsolatedOptions {
 	executor: EphemeralSubagentExecutor;
 	policy: EffectiveExecutionPolicy;
 	currentPolicy(): EffectiveExecutionPolicy;
+	/** Report new config issues, and throw when the config now blocks delegation, before each deferred Role launch. */
+	beforeRoleLaunch?(ctx: ExtensionContext): void;
 	componentsFactory?: CreateIsolatedComponents;
 }
 
@@ -504,7 +506,12 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 	};
 	const getComponents = () => components ??= componentsFactory({
 		pi,
-		context: latestContext,
+		// The launch runtime reads this context only to resolve a Role launch.
+		context: () => {
+			const ctx = latestContext();
+			options.beforeRoleLaunch?.(ctx);
+			return ctx;
+		},
 		executor: options.executor,
 		policy: options.policy,
 		currentPolicy: options.currentPolicy,

package/extensions/subagent.ts

@@ -1,9 +1,10 @@
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, Text, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { availableTaskModels, loadTaskModelsConfig, modelReference, type ProfileName, registerModelTask, resolveAvailableModel, resolveConfiguredTaskRoute, type ResolvedTaskRoute, taskThinkingLevels } from "@henryqw/pi-task-models";
-import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, DELEGATE_TASK, findRole, formatDuration, loadRoleCatalog, prepareRoleLaunch, resolveRolePackageResources, resolveTaskRoute, ROLE_TOOL_POLICY_FLAG, type Role } from "@henryqw/pi-subagent";
-import { readSubagentConfig, resolveExecutionPolicy, type EffectiveExecutionPolicy } from "./config.ts";
+import { availableTaskModels, loadTaskModelsConfig, modelReference, type ProfileName, registerModelTask, registerTaskModelsConfigReporting, resolveAvailableModel, resolveConfiguredTaskRoute, type ResolvedTaskRoute, taskThinkingLevels } from "@henryqw/pi-task-models";
+import { registerConfigReporting } from "@henryqw/pi-config-store";
+import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, createSubagentConfigStore, DEFAULT_SUBAGENT_CONFIG, DELEGATE_TASK, findRole, formatDuration, loadRoleCatalog, prepareRoleLaunch, resolveRolePackageResources, resolveTaskRoute, ROLE_TOOL_POLICY_FLAG, type Role } from "@henryqw/pi-subagent";
+import { resolveExecutionPolicy, type EffectiveExecutionPolicy } from "./config.ts";
 import { registerCheckoutAdmission } from "./admission.ts";
 import { registerIsolatedExtension } from "./isolated.ts";
 import { directRef, registerSubagentCommand, type DirectDisplay, type DirectTask } from "./subagent-command.ts";
@@ -180,20 +181,45 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	const widgetItems = new Map<string, WidgetItem>();
 	const tokenHandles = new Map<string, DirectHandle>();
 	const samplingTokens = new Set<string>();
-	const loadedConfig = readSubagentConfig();
-	let initialPolicy: EffectiveExecutionPolicy;
-	try {
-		initialPolicy = resolveExecutionPolicy(loadedConfig);
-	} catch {
-		initialPolicy = resolveExecutionPolicy({ source: "missing", config: {} });
-	}
+	const configStore = createSubagentConfigStore();
+	const configReporter = registerConfigReporting(pi, [configStore]);
+	const reportTaskModels = registerTaskModelsConfigReporting(pi);
+	/** Report new issues before a lazy Role catalog, route, or policy read. */
+	const reportConfig = (ctx: Pick<ExtensionContext, "hasUI" | "ui">): void => {
+		configReporter.report(ctx, configStore, configStore.loadSync());
+		reportTaskModels(ctx);
+	};
+	const loadedConfig = configStore.loadSync();
+	// A disabled config blocks each delegation; the executor still needs finite limits.
+	const initialPolicy = resolveExecutionPolicy(configStore.path, loadedConfig.status === "ok" ? loadedConfig
+		: { status: "ok", source: loadedConfig.source, value: DEFAULT_SUBAGENT_CONFIG, issues: [] });
 	const executor = createEphemeralSubagentExecutor({
 		maxConcurrency: initialPolicy.maxSubagents,
 		maxTurns: initialPolicy.maxTurns,
 		maxTokens: initialPolicy.maxTokens,
 		timeout: { idleMs: initialPolicy.childIdleMs, maxMs: initialPolicy.childMaxMs },
 	});
-	const currentPolicy = (): EffectiveExecutionPolicy => resolveExecutionPolicy(readSubagentConfig());
+	// The isolated runner reads the policy lazily without a context, so each read reports through the session's.
+	let latestCtx: ExtensionContext | undefined;
+	const currentPolicy = (): EffectiveExecutionPolicy => {
+		const loaded = configStore.loadSync();
+		if (latestCtx) configReporter.report(latestCtx, configStore, loaded);
+		const policy = resolveExecutionPolicy(configStore.path, loaded);
+		// The executor took its limits from the defaults, which can be unlimited, so a repaired file needs a reload.
+		if (loadedConfig.status === "disabled") {
+			throw new Error(`${configStore.path} was disabled when the session started; run /reload to apply its execution limits.`);
+		}
+		return policy;
+	};
+	/**
+	 * Before a deferred Role launch: report new issues, then revalidate so a now-disabled config blocks the child.
+	 * The workflow keeps the limits that it admitted at entry (direct idle timeout and concurrency, or the durable
+	 * isolated request's recorded policy); a limit change applies to the next workflow.
+	 */
+	const beforeRoleLaunch = (ctx: ExtensionContext): void => {
+		reportConfig(ctx);
+		currentPolicy();
+	};
 	const canWrite = (input: unknown): boolean => {
 		try {
 			const parsed = parseDelegateTask(input);
@@ -222,6 +248,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		executor,
 		policy: initialPolicy,
 		currentPolicy,
+		beforeRoleLaunch,
 	});
 	let directSequence = 0;
 	const directTasks = new Map<string, {
@@ -237,7 +264,6 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		return tab.entryId === saved.entryId && tab.name === saved.name && tab.tabId === saved.tabId
 			&& tab.paneId === saved.paneId && tab.sessionFile === saved.sessionFile;
 	});
-	let latestCtx: ExtensionContext | undefined;
 	let sessionEpoch = 0;
 	// Shutdown still saves outgoing identities; only a session start defers records to its carry loop.
 	let directRecordEpoch = 0;
@@ -311,6 +337,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			if (!current()) throw new Error("Session or branch changed before status inspection.");
 			const snapshot = notices.join("\n");
 			if (Buffer.byteLength(snapshot, "utf8") > 32_000) throw new Error("Status exceeds the 32 KiB inspection limit; use subagent_status for exact evidence.");
+			reportConfig(ctx);
 			const role = findRole(loadRoleCatalog(), "scout");
 			const prepared = await prepareDirectLaunch(role, ctx, { modelClass: "fast" });
 			const herdr = createDirectHerdr(pi, ctx.cwd, currentPolicy().childIdleMs);
@@ -354,6 +381,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		roles(ctx) {
 			const message = (error: unknown) => error instanceof Error ? error.message : String(error);
 			let catalog: ReturnType<typeof loadRoleCatalog>;
+			reportConfig(ctx);
 			try { catalog = loadRoleCatalog(); } catch (error) { return `Role catalog unavailable: ${message(error)}`; }
 			const list = (values: readonly string[] | undefined) => values?.length ? values.join(", ") : "none";
 			const lines = catalog.roles.flatMap((role) => {
@@ -507,13 +535,12 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		}
 		latestCtx = ctx;
 		ensureWidget(ctx);
-		if (loadedConfig.error !== undefined) ctx.ui.notify(loadedConfig.error, "warning");
 		try {
 			if (loadTaskModelsConfig().source === "missing") {
 				ctx.ui.notify("Task model config is missing; run /task-models to configure it.", "warning");
 			}
 		} catch {
-			// Route resolution retains the existing malformed shared-config error.
+			// A disabled shared config throws; the task-models config reporter already shows the path and the problems.
 		}
 	});
 	pi.on("session_shutdown", async (_event, ctx) => {
@@ -620,6 +647,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		},
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			signal?.throwIfAborted();
+			// Isolated requests read the policy in the runner; report it here with the tool's context.
+			reportConfig(ctx);
 			const parsed = parseDelegateTask(params);
 			if (parsed.mode === "isolated") return await isolatedSurface.execute(parsed.request, signal, ctx);
 			const workflow = parsed.workflow;
@@ -719,6 +748,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			directTasks.set(taskId, local);
 			const launch = async (entry: WorkflowEntry, activeSignal: AbortSignal) => {
 				activeSignal.throwIfAborted();
+				// A later worker launches after earlier ones finish; report and revalidate config edits made meanwhile.
+				beforeRoleLaunch(latestCtx ?? ctx);
 				const role = findRole(loadRoleCatalog(), entry.delegation.role);
 				const { modelClass, model } = entry.delegation;
 				const prepared = await prepareDirectLaunch(role, latestCtx ?? ctx, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "27.1.2",
+  "version": "27.2.1",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -66,11 +66,11 @@
     "image": "https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-subagent/example.png"
   },
   "dependencies": {
-    "@henryqw/pi-config-store": "^3.0.0",
+    "@henryqw/pi-config-store": "^4.0.0",
     "@henryqw/pi-herdr": "^0.5.0",
     "@henryqw/pi-multi-codex": "^3.0.0",
     "@henryqw/pi-process": "^0.2.0",
-    "@henryqw/pi-task-models": "^8.0.0",
+    "@henryqw/pi-task-models": "^9.0.0",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {