@henryqw/pi-subagent 26.5.1 → 27.1.0

package/dist/runner.js

@@ -7,8 +7,11 @@ import { FileRunStore, ProductiveRunLeaseBusyError } from "./store.js";
 const TRUNCATION_MARKER = "\n[truncated]";
 const TEXT_TASK_PROMPT_MAX_BYTES = 64 * 1024;
 const CHANGESET_TASK_PROMPT_MAX_BYTES = 96 * 1024;
+const CORRECTION_DELIVERY_RESERVE_BYTES = 1024;
 const MAX_WORKER_PROMPTS = 32;
 const MAX_QUEUED_FOLLOWUPS = 16;
+/** One durable follow-up per attempt; the runner itself never commits, stages, stashes, or discards. */
+export const COMMIT_NUDGE_INSTRUCTION = "Your turn ended with uncommitted changes in your worktree. Commit the intended changes now so the worktree is clean, or explain in your reply why they must not be committed. Do not discard work.";
 export const CLEANUP_SAFETY_BUDGET_MS = 30_000;
 export const TERMINATION_SAFETY_BUDGET_MS = 15_000;
 export const STATUS_INSPECTION_BUDGET_MS = 5_000;
@@ -369,6 +372,9 @@ function exactCommandResults(results, checks) {
             && result.args.every((arg, argIndex) => arg === check.args[argIndex]);
     });
 }
+function isCommitNudge(prompt) {
+    return prompt.kind === "followup" && prompt.instruction === COMMIT_NUDGE_INSTRUCTION;
+}
 function correctionEligible(request, attempt) {
     const initial = attempt.prompts[0];
     if (initial?.kind !== "initial" || attempt.prompts.some((prompt) => prompt.kind === "correction" || prompt.status === "ambiguous")
@@ -377,11 +383,13 @@ function correctionEligible(request, attempt) {
     const latestPrompt = attempt.prompts.at(-1);
     if (latestPrompt.status !== "settled")
         return false;
+    // A commit nudge continues its turn; it never consumes the correction window.
+    const assignments = attempt.prompts.filter((prompt) => !isCommitNudge(prompt)).length;
     if (!attempt.candidate) {
-        return attempt.prompts.length === 1 && !attempt.preliminaryChecks && Boolean(initial.failure?.trim());
+        return assignments === 1 && !attempt.preliminaryChecks && Boolean(initial.failure?.trim());
     }
     const checks = attempt.preliminaryChecks;
-    return attempt.prompts.length === 1 && Boolean(checks
+    return assignments === 1 && Boolean(checks
         && checks.phase === "preliminary"
         && exactCommandResults(checks.results, request.checks)
         && sameIdentity(checks.candidate, attempt.candidate)
@@ -403,10 +411,10 @@ export function buildChangesetTaskPrompt(input) {
         && (typeof input.failure !== "string" || !input.failure.trim() || input.failure.trim() !== input.failure || input.failure.includes("\0"))) {
         throw new Error("correction failure must be a non-empty exact string.");
     }
-    if (input.kind === "followup"
+    if ((input.kind === "followup" || input.instruction !== undefined)
         && (typeof input.instruction !== "string" || !input.instruction.trim() || input.instruction.trim() !== input.instruction
             || input.instruction.includes("\0") || input.instruction.length > 32_000)) {
-        throw new Error("follow-up instruction must be non-empty exact text of at most 32000 characters.");
+        throw new Error(`${input.kind === "followup" ? "follow-up" : "correction"} instruction must be non-empty exact text of at most 32000 characters.`);
     }
     const checks = input.task.checks.map((check) => JSON.stringify({ command: check.command, args: check.args })).join("\n");
     const upstreamTaskData = input.contexts.length
@@ -440,6 +448,7 @@ export function buildChangesetTaskPrompt(input) {
         "Required checks (direct command/argv):",
         checks,
         ...(input.kind === "correction" ? ["", "Correction failure:", input.failure] : []),
+        ...(input.kind === "correction" && input.instruction ? ["", "Main's instruction:", input.instruction] : []),
         "",
         "Work only in the exact worktree above. Commit the complete result and leave that worktree clean.",
     ].join("\n");
@@ -572,6 +581,55 @@ export class IsolatedRunner {
         }
         return { requests, invalidIds: inventory.invalidIds, leaseBusy };
     }
+    /** Prune evidence across checkouts. A non-terminal state owns every resource name its saved text
+     * mentions; an unreadable state owns every name its raw text mentions, or every name when unreadable. */
+    async pruneOwnership(checkouts) {
+        const owners = [];
+        let lease;
+        for (const checkout of checkouts) {
+            const root = realpathSync.native(checkout);
+            if (!lease && await this.store.hasProductiveRunLease(root))
+                lease = `productive lease is held by a live run in ${root}`;
+            const { states, invalidIds } = await this.store.list(root);
+            for (const { state } of states) {
+                if (!terminal(state))
+                    owners.push({ label: `owned by ${state.status} request ${state.request.id}`, text: JSON.stringify(state) });
+            }
+            for (const id of invalidIds) {
+                let text;
+                try {
+                    text = await this.store.readRaw(root, id);
+                }
+                catch { /* It may own any name. */ }
+                owners.push({ label: `unreadable state ${id} in ${root} may own it`, text });
+            }
+        }
+        return { ...(lease ? { lease } : {}), owner: (name) => owners.find(({ text }) => text === undefined || text.includes(name))?.label };
+    }
+    /** After pruning, reconcile aborted requests that recorded a removed resource through the guarded abort path. */
+    async reconcilePrunedAborts(checkouts, names) {
+        const lines = [];
+        for (const checkout of checkouts) {
+            const root = realpathSync.native(checkout);
+            const { requests, states } = await this.listRequests(root);
+            for (const [index, state] of states.entries()) {
+                const id = state.request.id;
+                const text = JSON.stringify(state);
+                if (requests[index].status !== "aborted · retained" || !names.some((name) => text.includes(name)))
+                    continue;
+                try {
+                    await this.abort(id, root);
+                    const after = (await this.listRequests(root)).requests.find((request) => request.id === id);
+                    lines.push(after?.status === "aborted" ? `Reconciled cleanup of aborted request ${id}.`
+                        : `Aborted request ${id} still has pending cleanup; inspect subagent_status.`);
+                }
+                catch (error) {
+                    lines.push(`Aborted request ${id} could not be reconciled: ${errorText(error)}`);
+                }
+            }
+        }
+        return lines;
+    }
     canFollowup(root, requestId, taskId) {
         const active = this.activeControl(realpathSync.native(root), requestId, taskId);
         return active !== undefined && active.task.status === "working" && !active.control.isSealed;
@@ -757,6 +815,8 @@ export class IsolatedRunner {
                         throw new Error(`Task ${task.taskId} is not waiting for deliberate attention.`);
                     if (request.action === "verify")
                         throw new Error(`Text task ${task.taskId} cannot be verified.`);
+                    if (request.instruction !== undefined)
+                        throw new Error(`Text task ${task.taskId} retry cannot take a worker instruction.`);
                     if (!textRetryEligible(state, task)) {
                         const attempt = task.attempts.at(-1);
                         if ((attempt && !["failed", "superseded"].includes(attempt.status)) || task.attempts.length >= 2) {
@@ -771,7 +831,7 @@ export class IsolatedRunner {
                 if (task.status !== "needs_attention")
                     throw new Error(`Task ${task.taskId} is not waiting for deliberate attention.`);
                 if (request.action === "retry")
-                    return await this.retry(handle, task, scope);
+                    return await this.retry(handle, task, scope, request.instruction);
                 return await this.verifyRetainedTask(handle, task, scope);
             }
             catch (error) {
@@ -2179,6 +2239,8 @@ export class IsolatedRunner {
         let kind = initialKind;
         let failure = task.failure;
         let instruction = initialInstruction;
+        // A nudge keeps its dirty turn's exact clean pre-prompt lineage.
+        let nudgeFrom;
         for (;;) {
             if (kind === "followup" && instruction === undefined) {
                 throw new Error("Follow-up worker execution requires an exact queued instruction.");
@@ -2195,11 +2257,12 @@ export class IsolatedRunner {
             }
             let preCandidate;
             try {
-                preCandidate = runtimeIdentity(await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectTaskCandidate({
+                preCandidate = nudgeFrom ?? runtimeIdentity(await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectTaskCandidate({
                     root: state.root,
                     task: request,
                     attempt,
                 }, context)), "Pre-prompt candidate identity");
+                nudgeFrom = undefined;
             }
             catch (error) {
                 this.rethrowStopped(error);
@@ -2233,7 +2296,7 @@ export class IsolatedRunner {
                 kind,
                 status: "submitting",
                 preCandidate,
-                ...(kind === "followup" ? { instruction } : {}),
+                ...(instruction !== undefined ? { instruction } : {}),
                 at: nextAttemptEventAt(attempt, this.coordinatorRuntime.now()),
             };
             attempt.prompts.push(prompt);
@@ -2278,6 +2341,19 @@ export class IsolatedRunner {
                 return;
             }
             prompt.status = "settled";
+            if (worker.outcome === "uncommitted") {
+                prompt.failure = boundedRuntimeDiagnostic(worker.diagnostic, "uncommitted worker diagnostic");
+                if (attempt.prompts.some(isCommitNudge)) {
+                    this.attention(task, "The commit nudge was sent, but the worker turn still left uncommitted changes in its worktree; they are retained for inspection.");
+                    await this.saveProductive(handle);
+                    return;
+                }
+                await this.saveProductive(handle);
+                kind = "followup";
+                instruction = COMMIT_NUDGE_INSTRUCTION;
+                nudgeFrom = preCandidate;
+                continue;
+            }
             if (worker.outcome === "blocked") {
                 failure = boundedRuntimeDiagnostic(worker.diagnostic, "blocked worker diagnostic");
                 prompt.failure = failure;
@@ -2522,8 +2598,11 @@ export class IsolatedRunner {
         await this.saveProductive(handle);
         return this.response(handle.state);
     }
-    async retry(handle, task, scope) {
+    async retry(handle, task, scope, instruction) {
         const attempt = task.attempts.at(-1);
+        if (instruction !== undefined && !attempt?.prompts.length) {
+            throw new Error("A retry instruction requires a same-worker correction of a prompted attempt.");
+        }
         if (!attempt) {
             for (const pending of handle.state.tasks) {
                 if (pending.status === "needs_attention" && pending.attempts.length === 0) {
@@ -2538,11 +2617,26 @@ export class IsolatedRunner {
             if (attempt.prompts.some((prompt) => prompt.status === "ambiguous")) {
                 throw new Error("An ambiguous delivered prompt is never replayed.");
             }
-            if (!this.correctionAllowed(handle.state, changesetTaskRequest(handle.state, task.taskId), attempt)) {
+            const request = changesetTaskRequest(handle.state, task.taskId);
+            if (!this.correctionAllowed(handle.state, request, attempt)) {
                 throw new Error("The same-agent correction is unavailable or already used.");
             }
+            // Build the correction before it is recorded: an oversized prompt must not use up the only correction.
+            // The reserve covers the worktree path and turn identity the host adds before delivery.
+            const assignment = buildChangesetTaskPrompt({
+                goal: handle.state.request.goal,
+                contexts: resolveTextTaskContexts(handle.state, request),
+                task: request,
+                kind: "correction",
+                worktreeCwd: allocationByKind(attempt, "agent")?.worktreeCwd ?? "",
+                failure: task.failure,
+                ...(instruction === undefined ? {} : { instruction }),
+            });
+            if (Buffer.byteLength(assignment, "utf8") + CORRECTION_DELIVERY_RESERVE_BYTES > CHANGESET_TASK_PROMPT_MAX_BYTES) {
+                throw new Error(`Worker assignment exceeds ${CHANGESET_TASK_PROMPT_MAX_BYTES} bytes with delivery overhead; shorten the retry instruction.`);
+            }
             task.status = "working";
-            await this.driveWorkerSafely(handle, task, scope, "correction");
+            await this.driveWorkerSafely(handle, task, scope, "correction", instruction);
         }
         else {
             if (attempt.termination || allocationByKind(attempt, "agent")) {

package/dist/schema.d.ts

@@ -121,6 +121,7 @@ export declare const ResumeRequestSchema: Type.TUnion<[Type.TObject<{
     id: Type.TString;
     action: Type.TLiteral<"retry">;
     taskId: Type.TString;
+    instruction: Type.TOptional<Type.TString>;
 }>, Type.TObject<{
     id: Type.TString;
     action: Type.TLiteral<"verify">;
@@ -133,6 +134,7 @@ export declare const ResumeRequestParameters: Type.TObject<{
     id: Type.TString;
     action: Type.TUnion<[Type.TLiteral<"retry">, Type.TLiteral<"verify">, Type.TLiteral<"finalize">]>;
     taskId: Type.TOptional<Type.TString>;
+    instruction: Type.TOptional<Type.TString>;
 }>;
 export type IdOnly = Static<typeof IdOnlySchema>;
 export type CheckCommand = Static<typeof CheckCommandSchema>;
@@ -2389,6 +2391,10 @@ export declare const StatusOutputSchema: Type.TObject<{
             scope: Type.TUnion<[Type.TLiteral<"task">, Type.TLiteral<"final">, Type.TLiteral<"request">]>;
             taskId: Type.TOptional<Type.TString>;
             failure: Type.TOptional<Type.TString>;
+            failedReview: Type.TOptional<Type.TObject<{
+                verdict: Type.TString;
+                verdictTruncated: Type.TBoolean;
+            }>>;
         }>>;
         createdAt: Type.TInteger;
         updatedAt: Type.TInteger;
@@ -2421,6 +2427,7 @@ export declare const StatusOutputSchema: Type.TObject<{
         id: Type.TString;
         action: Type.TLiteral<"retry">;
         taskId: Type.TString;
+        instruction: Type.TOptional<Type.TString>;
     }>, Type.TObject<{
         id: Type.TString;
         action: Type.TLiteral<"verify">;

package/dist/schema.js

@@ -62,7 +62,7 @@ export const ExecuteRequestSchema = Type.Object({
 }, { additionalProperties: false });
 export const IdOnlySchema = Type.Object({ id: IdSchema }, { additionalProperties: false });
 export const ResumeRequestSchema = Type.Union([
-    Type.Object({ id: IdSchema, action: Type.Literal("retry"), taskId: IdSchema }, { additionalProperties: false }),
+    Type.Object({ id: IdSchema, action: Type.Literal("retry"), taskId: IdSchema, instruction: Type.Optional(TextSchema) }, { additionalProperties: false }),
     Type.Object({ id: IdSchema, action: Type.Literal("verify"), taskId: IdSchema }, { additionalProperties: false }),
     Type.Object({ id: IdSchema, action: Type.Literal("finalize") }, { additionalProperties: false }),
 ]);
@@ -75,6 +75,7 @@ export const ResumeRequestParameters = Type.Object({
         ResumeRequestSchema.anyOf[2].properties.action,
     ]),
     taskId: Type.Optional(IdSchema),
+    instruction: ResumeRequestSchema.anyOf[0].properties.instruction,
 }, { additionalProperties: false });
 const AllocationLifecycleFields = {
     generation: Type.Integer({ minimum: 1, maximum: 2 }),
@@ -466,6 +467,7 @@ export const StatusOutputSchema = Type.Object({
             scope: Type.Union([Type.Literal("task"), Type.Literal("final"), Type.Literal("request")]),
             taskId: Type.Optional(IdSchema),
             failure: Type.Optional(Type.String()),
+            failedReview: Type.Optional(Type.Object({ verdict: Type.String(), verdictTruncated: Type.Boolean() })),
         })),
         createdAt: TimestampSchema,
         updatedAt: TimestampSchema,
@@ -635,7 +637,10 @@ export function parseResumeRequest(value) {
     if (!Check(ResumeRequestSchema, value)) {
         throw schemaValidationError("subagent_resume request must match one strict action", Errors(ResumeRequestSchema, value));
     }
-    return value;
+    const request = value;
+    if ("instruction" in request && request.instruction !== undefined)
+        requireExactAllocationText(request.instruction, "Retry instruction");
+    return request;
 }
 export function sameIdentity(left, right) {
     return left.branch === right.branch && left.head === right.head && left.index === right.index && left.tree === right.tree;
@@ -1080,11 +1085,11 @@ export function parseRunState(value) {
             }
             for (let promptIndex = 0; promptIndex < attempt.prompts.length; promptIndex += 1) {
                 const prompt = attempt.prompts[promptIndex];
-                if ((prompt.kind === "followup") !== (prompt.instruction !== undefined)) {
-                    throw new Error(`Follow-up prompt history for ${definition.id} has invalid instruction evidence.`);
+                if (prompt.kind === "followup" ? prompt.instruction === undefined : prompt.kind === "initial" && prompt.instruction !== undefined) {
+                    throw new Error(`Prompt history for ${definition.id} has invalid instruction evidence.`);
                 }
                 if (prompt.instruction !== undefined) {
-                    requireExactAllocationText(prompt.instruction, `Follow-up prompt instruction for ${definition.id}`);
+                    requireExactAllocationText(prompt.instruction, `Prompt instruction for ${definition.id}`);
                 }
                 if (promptIndex === 0)
                     continue;

package/dist/store.d.ts

@@ -48,6 +48,8 @@ export declare class FileRunStore {
         states: RunStateHandle[];
         invalidIds: string[];
     }>;
+    /** Raw text of a state file, for evidence when it does not parse. */
+    readRaw(root: string, id: string): Promise<string>;
     private handle;
 }
 export {};

package/dist/store.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { mkdir, open, readdir, realpath } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { extensionConfigDir, readTextFileBounded, writePrivateTextFileAtomically } from "@henryqw/pi-config-store";
 import { check, lock } from "proper-lockfile";
@@ -272,8 +272,13 @@ export class FileRunStore {
         const entries = await this.stateEntries(root);
         const states = [];
         const invalidIds = [];
-        for (const entry of entries.filter((item) => item.isFile())) {
+        for (const entry of entries) {
             const id = entry.name.slice(0, -5);
+            // A symlink, directory, or other non-regular entry is unreadable state, never absent state.
+            if (!entry.isFile()) {
+                invalidIds.push(id);
+                continue;
+            }
             try {
                 states.push(await this.load(root, id));
             }
@@ -283,6 +288,13 @@ export class FileRunStore {
         }
         return { states, invalidIds };
     }
+    /** Raw text of a state file, for evidence when it does not parse. */
+    async readRaw(root, id) {
+        const path = this.statePath(root, id);
+        if (!(await lstat(path)).isFile())
+            throw new Error(`State entry ${id} is not a regular file.`);
+        return await readTextFileBounded(path, STATE_MAX_BYTES);
+    }
     handle(state, path) {
         return new RunStateHandle(state, path, async (contents) => {
             await this.assertSafeDestination(state.root, path);

package/dist/worktree.d.ts

@@ -24,6 +24,9 @@ export type WorktreePayload = {
     commits?: number;
     dirty?: boolean;
 };
+export declare const WORKTREES_DIRNAME = ".worktrees";
+/** Branches `createChildWorktree` creates for workers and integration checkouts, at `<primary>/.worktrees/<branch basename>`. */
+export declare const OWNED_BRANCH_PATTERN: RegExp;
 export declare class WorktreeSetupError extends Error {
     name: string;
     readonly worktree: WorktreeInfo;

package/dist/worktree.js

@@ -3,8 +3,10 @@ import { existsSync, lstatSync } from "node:fs";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { runGit } from "./git-process.js";
-const WORKTREES_DIRNAME = ".worktrees";
+export const WORKTREES_DIRNAME = ".worktrees";
 const BRANCH_NAMESPACE = "pi-subagent";
+/** Branches `createChildWorktree` creates for workers and integration checkouts, at `<primary>/.worktrees/<branch basename>`. */
+export const OWNED_BRANCH_PATTERN = new RegExp(`^${BRANCH_NAMESPACE}/subagent-[0-9a-f]{24}$`);
 export class WorktreeSetupError extends Error {
     name = "WorktreeSetupError";
     worktree;

package/docs/migration.md

@@ -0,0 +1,163 @@
+# Migrate from 26.x to 27.0.0
+
+Version 27.0.0 changes how direct tasks declare writes, how Role files load, and one library function. Most users must do two things: make sure Main sends `access` on each direct task, and fix Role files that have unknown keys. Use the [checklist](#upgrade-checklist) at the end.
+
+## Direct tasks must declare `access`
+
+Each direct task must now have `access: "read"` or `access: "write"`. A request without `access`, or with another value, fails before launch. The error names the task, for example `tasks[1].access must be "read" or "write" (missing)`.
+
+Main sets `access`, not you. The packaged `pi-subagent` Skill and the tool schema tell Main to do this. You must change requests only if you wrote them yourself, for example in saved prompts, examples, or scripts.
+
+Use `write` when the task can change files, Git state, or external resources. Use `read` for all other tasks. Nothing enforces `read`: there is no sandbox, and a read task keeps all of its Role's tools.
+
+Single task, before:
+
+```json
+{ "mode": "direct", "role": "scout", "name": "Map sign-in flow", "task": "Trace sign-in. Do not edit files." }
+```
+
+Single task, after:
+
+```json
+{ "mode": "direct", "role": "scout", "name": "Map sign-in flow", "task": "Trace sign-in. Do not edit files.", "access": "read" }
+```
+
+Parallel tasks, before:
+
+```json
+{
+  "mode": "direct",
+  "tasks": [
+    { "role": "scout", "name": "Inspect service", "task": "Inspect the service boundary." },
+    { "role": "reviewer", "name": "Inspect tests", "task": "Inspect the test contract." }
+  ]
+}
+```
+
+Parallel tasks, after:
+
+```json
+{
+  "mode": "direct",
+  "tasks": [
+    { "role": "scout", "name": "Inspect service", "task": "Inspect the service boundary.", "access": "read" },
+    { "role": "reviewer", "name": "Inspect tests", "task": "Inspect the test contract.", "access": "read" }
+  ]
+}
+```
+
+Chain, before:
+
+```json
+{
+  "mode": "direct",
+  "chain": [
+    { "role": "scout", "name": "Collect evidence", "task": "Collect exact evidence." },
+    { "role": "implementer", "name": "Apply fix", "task": "Fix the issue in this report and commit it:\n{previous}" }
+  ]
+}
+```
+
+Chain, after:
+
+```json
+{
+  "mode": "direct",
+  "chain": [
+    { "role": "scout", "name": "Collect evidence", "task": "Collect exact evidence.", "access": "read" },
+    { "role": "implementer", "name": "Apply fix", "task": "Fix the issue in this report and commit it:\n{previous}", "access": "write" }
+  ]
+}
+```
+
+## Roles no longer classify writes
+
+In 26.x, pi-subagent used each Role's tools, extensions, and MCP servers to decide if a request could write. A Role with any extension or MCP server counted as a writer. In 27.0.0, only `access` decides this. The results are:
+
+- A request with only `read` tasks does not reserve the checkout, and its tasks return plain text. Its parallel `tasks` run at the same time, up to `maxSubagents`; a `chain` still runs its steps in order. Roles that load a provider extension now run in parallel too.
+- A request with one or more `write` tasks runs its tasks one at a time. It reserves the checkout until all of its workers are proved stopped. Each task must return a JSON completion object, as in 26.x.
+- **Inspect status and recovery** in `/subagent` now works with a `scout` Role that loads extensions or MCP servers. It runs as a read task with the Role's own resources.
+
+## Unknown Role frontmatter keys are rejected
+
+Role Markdown files can only use these frontmatter keys: `name`, `description`, `modelClass`, `tools`, `extensions`, `skills`, and `mcps`. In 26.x, other keys had no effect. In 27.0.0, a file with another key is invalid. The error names the file and the key:
+
+```text
+<file>: unknown Role frontmatter key "color"; expected name, description, modelClass, tools, extensions, skills, mcps.
+```
+
+To fix it, open the file and remove the key. Keys copied from other agent tools often cause this error. Examples are `color` and `model`. For a model, use `modelClass` with `fast`, `balanced`, `frontier`, or `fav`. Main can also select a route or a `model` on each task.
+
+## Role errors are reported per file
+
+In 26.x, one invalid Role file stopped all Roles from loading. In 27.0.0, each file loads on its own:
+
+- Valid Roles load and work.
+- A task that names the Role of an invalid file fails, and the error names that file.
+- Two files with the same `name` make that name unavailable until you remove one.
+
+Run `/subagent roles` to see each Role, its source (built-in, user override, or user), its resolved model route, its resources, and all file errors. This command only reads. It does not need a Herdr pane.
+
+## New `roleDefaults` setting
+
+`~/.pi/agent/config/pi-subagent/config.json` accepts an optional `roleDefaults` object. Its `extensions`, `tools`, and `skills` arrays merge into every built-in and user Role. The defaults come first in each list, and duplicates are removed. Use it for the provider extension that every child needs:
+
+```json
+{
+  "roleDefaults": {
+    "extensions": ["npm:@example/pi-provider"]
+  }
+}
+```
+
+**Warning:** 26.x rejects the `roleDefaults` key, and an unknown key blocks all delegation. Upgrade to 27.0.0 before you add `roleDefaults` to the file.
+
+## Library API: `loadRoles` is replaced
+
+This section applies only if your code imports `@henryqw/pi-subagent`. `loadRoles` is removed. Use `loadRoleCatalog` to load all Roles and `findRole` to select one. The catalog also contains each Role's source and the per-file errors, and it applies `roleDefaults`.
+
+Before:
+
+```ts
+import { loadRoles } from "@henryqw/pi-subagent";
+
+const role = loadRoles().find((candidate) => candidate.name === "scout");
+if (!role) throw new Error("Unknown Role: scout");
+```
+
+After:
+
+```ts
+import { findRole, loadRoleCatalog } from "@henryqw/pi-subagent";
+
+const catalog = loadRoleCatalog();
+const role = findRole(catalog, "scout"); // Throws with the file error if the Role is invalid.
+for (const error of catalog.errors) console.warn(error.message);
+```
+
+## Worker output header and partial output
+
+Each worker result that Main receives now starts with a header. The header tells Main that the text is the worker's output and has no user authority. Text that looks like harness framing gets a backslash, for example `<system-reminder>` tags or lines that start with `Human:` or `Assistant:`. No other text changes. Isolated status previews use the same header.
+
+When a task fails after its worker wrote text, the result keeps a short excerpt marked as partial output. Partial output is never a success.
+
+If you parse worker results, expect the header line before the worker text.
+
+## New features you can use
+
+These features do not need changes to your setup.
+
+- **`continueFrom`**: Main can continue a finished direct worker, for example `"continueFrom": "D7.1"`, with the same Role. The worker resumes its saved Pi session in a new Herdr tab, so it keeps its earlier context. Main uses it for follow-up questions or corrections on the same work. After a continuation, continue the newest reference: an older reference to the same session is refused. For unrelated work, Main starts a fresh task.
+- **Stop this worker**: in `/subagent`, a running workflow with only `read` tasks shows **Stop this worker** for each running worker. It stops only that worker. The other workers continue, and Main receives one result when the workflow finishes. Workflows with a `write` task keep only **Close/cancel-and-release ALL owned workers in this workflow**.
+
+## Upgrade checklist
+
+1. Make a copy of the Role files (`*.md`) and `config.json` in `~/.pi/agent/config/pi-subagent/`.
+2. Remove unknown frontmatter keys, such as `color` or `model`, from each Role file in `~/.pi/agent/config/pi-subagent/`.
+3. Upgrade with `pi install npm:@henryqw/pi-subagent`, then restart Pi.
+4. Run `/subagent roles`. Fix each file error that it shows.
+5. Optional: add `roleDefaults` to `config.json` for resources that every Role needs. Do this only after the upgrade.
+6. Add `access` to each direct task in saved prompts, scripts, or examples that you wrote.
+7. If your code imports the library, replace `loadRoles` with `loadRoleCatalog` and `findRole`.
+8. If you parse worker results, expect the worker output header.
+9. Do a small `read` delegation to make sure that the setup works.