@henryqw/pi-subagent 22.2.3 → 23.0.0

package/CONTEXT.md

@@ -13,7 +13,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 - **Main**: the Pi session and checkout coordinating delegated work.
 - **Role**: package or user Markdown defining responsibility, tools, trusted extension sources, Skills, optional MCP names, instructions, and an optional model-class default. Roles do not select isolation.
 - **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, resolved through `pi-task-models`.
-- **Direct task**: one read-only assignment in a Herdr tab in Main's current workspace.
+- **Direct task**: one task using read-only base tools in a Herdr tab in Main's current workspace; trusted extensions and MCP servers are not read-only constrained.
 - **Isolated request**: one durable ID, goal, and checked task graph.
 - **Candidate**: exact clean committed task-worktree identity produced by an isolated changeset worker.
 - **Readiness**: durable proof that one exact live-worker candidate passed its preliminary checks and is sealed for Main's explicit selection; it is not a separate user approval.
@@ -41,7 +41,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 
 ### Direct evidence
 
-- Direct mode admits only Roles proven read-only from declared tools, extensions, and MCP resources. Direct changesets and write-capable Roles require isolated mode.
+- Direct mode admits Roles with known read-only base tools. Extensions and MCP servers are trusted without a read-only guarantee; direct changesets and Roles with write-capable base tools require isolated mode.
 - Each direct worker has a recorded Herdr tab and Pi session identity. The first handle returns before completion; subsequent tab identities remain recoverable on the session branch.
 - An exact settled worker with a bounded final Pi answer produces a follow-up to Main. Blocked, unknown, idle-stalled, truncated, or ambiguous outcomes retain actionable recovery identity. Session replacement never delivers to the wrong Main session.
 
@@ -50,6 +50,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 - Changeset tasks durably record allocation intent before each external side effect. Unknown outcomes are retained and never guessed.
 - One worker remains live across prompts, preliminary checks, follow-up/correction, readiness, Main's staging decisions, combined validation, and guarded promotion. Selected workers terminate after promotion; rejected workers terminate on explicit rejection.
 - Optional same-worker follow-ups are admitted only while a changeset is actively working. After the final checked-evidence save, one synchronous queue-or-seal transition prevents admitted revisions from being lost; the runner never waits for routine input.
+- Worker waves pin Main's committed branch/HEAD/tree, excluding staged, unstaged, and untracked changes; dirty Main permits checked candidate readiness, but branch/HEAD drift blocks dispatch and clean Main is required before staging, combined validation, or promotion.
 - Preliminary checks gate readiness. Any changed candidate invalidates previous readiness and validation.
 - Optional task judgment binds to the exact preliminary candidate. Main selects and orders candidates in a separate owned integration checkout, where final full-suite checks and optional final judgment bind to the clean combined tip before promotion.
 - Promotion requires exact unchanged clean Main and a passing combined generation. Durable promotion evidence precedes selected-worker termination and cleanup; recovery never rolls back a proven promotion.

package/README.md

@@ -19,18 +19,19 @@ Install `pi-mcp-adapter` only when a Role declares an MCP server allowlist:
 pi install npm:pi-mcp-adapter
 ```
 
-## Use
+## Works with
 
-![Main, its coordinator extension, and a Herdr subagent through checked work, worker failure, and coordinator interruption](./docs/worker-lifecycle.svg)
+| Package | Relationship | Purpose |
+| --- | --- | --- |
+| [`@henryqw/pi-task-models`](https://pi.henry.wang/extensions/pi-task-models) | Required | Provides the configured model routes for delegated Roles. |
+| [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) | Required | Loads the MCP servers named in a Role's `mcps` allowlist, only for Roles that declare one. |
 
-The coordinator is extension code running in Main's Pi process, not another agent. It persists the request, launches the Herdr subagent, checks its committed work, and reports saved results; Main chooses what to stage and promote. If a worker fails, the coordinator reports attention after the wave settles, not necessarily immediately while siblings work. If Main's Pi process stops, no follow-up is guaranteed: restart and run `/subagent recover` in the canonical repository to classify orphaned interruptions and send Main one recovery report. Main then uses `subagent_status` for exact evidence and deliberate next actions. A stale `running` state does not prove a worker is still active; interrupted or ambiguous actions are never replayed automatically.
+## Use
 
 Ask Main to delegate a bounded task, such as “Have a scout trace sign-in without editing files.” Main uses `delegate_task`; you receive progress and a result or an actionable failure while Main remains available.
 
 Commands are for you; tools and the packaged skill are for Main. You do not need to call agent tools or manage candidate identities yourself.
 
-In the TUI, the compact widget uses one row per visible agent/task: `D` or `I` marks direct or isolated work, and `[S]` or `[I3]` identifies the Role initial (plus the isolated model class: `1` fast, `2` balanced, `3` frontier, `*` fav). Direct rows show the launched model, thinking level, elapsed time, and measured session tokens (`— tok` until usage is available). Isolated rows show the recorded task state and any retained workspace; their status glyphs use the active TUI theme, while the text still names the status without color. Herdr does not currently provide reliable live model, thinking, or token readings for those rows. Attention appears before ordinary work, with a `+N more` summary when direct rows overflow. A ready isolated candidate is **not promoted** to Main. Use `/subagent` or `subagent_status` for exact identities, failures, and recovery.
-
 | Surface | Type | Purpose |
 | --- | --- | --- |
 | `/subagent` | command | Browse work, launch isolated status inspection in a separate Herdr tab with the `fast` model, or send/edit pending instructions. Requires interactive TUI or RPC; inspection also requires a Herdr-managed pane and a read-only `scout` Role. |
@@ -43,6 +44,12 @@ In the TUI, the compact widget uses one row per visible agent/task: `D` or `I` m
 | `subagent_abort` | tool | Abort an isolated request only when no retained candidates or integration worktrees remain; cannot discard them. |
 | `pi-subagent` | skill | Guide Main through delegation, authorization, checks, integration, and recovery. |
 
+![Main, its coordinator extension, and a Herdr subagent through checked work, worker failure, and coordinator interruption](./docs/worker-lifecycle.svg)
+
+The coordinator is extension code running in Main's Pi process, not another agent. It persists the request, launches the Herdr subagent, checks its committed work, and reports saved results; Main chooses what to stage and promote. If a worker fails, the coordinator reports attention after the wave settles, not necessarily immediately while siblings work. If Main's Pi process stops, no follow-up is guaranteed: restart and run `/subagent recover` in the canonical repository to classify orphaned interruptions and send Main one recovery report. Main then uses `subagent_status` for exact evidence and deliberate next actions. A stale `running` state does not prove a worker is still active; interrupted or ambiguous actions are never replayed automatically.
+
+In the TUI, the compact widget uses one row per visible agent/task: `D` or `I` marks direct or isolated work, and `[S]` or `[I3]` identifies the Role initial (plus the isolated model class: `1` fast, `2` balanced, `3` frontier, `*` fav). Direct rows show the launched model, thinking level, elapsed time, and measured session tokens (`— tok` until usage is available). Isolated rows show the recorded task state and any retained workspace; an aborted request with visible tasks has its own `request aborted` row and does not change their recorded statuses. A committed worker without a checked candidate can still show attention rather than readiness. Status glyphs use the active TUI theme, while the text still names the status without color. Herdr does not currently provide reliable live model, thinking, or token readings for those rows. Attention appears before ordinary work, with a `… N more` summary when direct rows overflow. A ready isolated candidate is **not promoted** to Main. Choose **Refresh** in `/subagent` to reload both the menu and isolated widget from saved state; it does not recover or change a request. Use `/subagent` or `subagent_status` for exact identities, failures, and recovery.
+
 ### How Main routes delegation
 
 Main chooses the mode from your request; you do not need to select one. Words like “direct” and “isolated” can signal your intent, but the work determines the route. Main declares the chosen mode in every `delegate_task` call, and the extension never falls back between modes.
@@ -75,7 +82,7 @@ Parallel: { mode: "direct", tasks: [{ role, name, task, ... }] }
 Chain:    { mode: "direct", chain: [{ role, name, task, ... }] }
 ```
 
-Only Roles with known read-only tools and no extensions or MCP servers may run direct. Write-capable Roles and direct `changeset` tasks are rejected; use isolated mode for implementation. Parallel tasks run independently; chains replace each literal `{previous}` with the preceding successful answer and stop on failure.
+Only Roles whose declared base tools are known read-only may run direct. Configured extensions and MCP servers are trusted and may provide additional tools; use isolated mode when a task needs write-capable base tools or a checked changeset. Parallel tasks run independently; chains replace each literal `{previous}` with the preceding successful answer and stop on failure.
 
 The tool returns a task ID and 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 it after the current turn; if idle, it starts a turn. A blocked, stalled, unknown, or truncated result is not reported as success. Session switch or shutdown stops observation and preserves tab identities for recovery. Open `/subagent` on the session branch to inspect exact tabs, agents, and Pi session files, including tabs launched after the first. A recorded tab may no longer be running; locally observed work is labelled separately.
 
@@ -126,11 +133,11 @@ An isolated request has one durable ID, one goal, and 1–8 typed tasks:
 
 `dependsOn` controls scheduling. `contextFrom` may name completed text tasks and preserves the declared order. Changesets require focused task checks; a graph with changesets requires final checks. A canonical root `package.json` test script is required: the runner adds `pnpm test` to final checks if missing, and Main runs it on the combined integration checkout before promotion. Checks and judgments bind to exact Git identities; candidate drift, Main drift, mutation during validation, ambiguity, or conflicts stop promotion and retain evidence.
 
-`delegate_task`, `subagent_resume`, and `subagent_integrate advance` return a durable request ID after the wave is saved; productive work continues while Main is free. Main can do other work or end its turn instead of sleeping or polling. Pi sends a follow-up in the launching session whenever a checked worker becomes ready, and again when the wave finishes or needs attention. Use `subagent_status` if delivery is missed or you need exact current state.
+`delegate_task`, `subagent_resume`, and `subagent_integrate advance` return a durable request ID after the wave is saved; productive work continues while Main is free. Main can do other work or end its turn instead of sleeping or polling. Pi sends a follow-up in the launching session whenever a checked worker becomes ready or a worker needs attention, and again when the wave finishes. A worker whose exact turn ends without a changed clean commit—including a failed or aborted turn—needs attention, not an inferred candidate; use `subagent_status` for its saved evidence. If delivery is missed, inspect `subagent_status`.
 
-The worker produces a committed candidate without tracked or untracked changes, then runs focused preliminary checks and optional judgment. Ignored generated files do not block candidacy, but prevent automatic worktree cleanup; inspect them before deleting retained work. The runner records each ready candidate immediately but **does not integrate it automatically**. Main can inspect `subagent_status` and use `subagent_stage` to select the exact candidate in an owned integration worktree while siblings are still working; conflicts are resolved there. Stage and resolve are available during an active wave, but rejection and revision wait for the wave to settle. `subagent_integrate` can advance dependent tasks from a staged snapshot, validate the combined tip with full root checks and optional final judgment after the wave settles, and promote it to Main only after exact validation. A definitive failed combined check/review allows one committed correction in the integration checkout followed by another validation. Main must explicitly promote; promotion and cleanup never silently discard retained work.
+Isolated workers can start while Main has staged, unstaged, or untracked changes: they use only Main's pinned committed branch, HEAD, and tree. Those local edits are neither copied into worker worktrees nor stashed, staged, reset, or merged automatically. Main must remain at that committed identity while workers run; branch or HEAD drift blocks new waves. The worker produces a committed candidate without tracked or untracked changes, then runs focused preliminary checks and optional judgment. Ignored generated files do not block candidacy, but prevent automatic worktree cleanup; inspect them before deleting retained work. The runner records each ready candidate immediately but **does not integrate it automatically**. Main can inspect `subagent_status` and use `subagent_stage` to select the exact candidate in an owned integration worktree while siblings are still working; conflicts are resolved there. Stage and resolve are available during an active wave, but rejection and revision wait for the wave to settle. `subagent_integrate` can advance dependent tasks from a staged snapshot, validate the combined tip with full root checks and optional final judgment after the wave settles, and promote it to Main only after exact validation. A definitive failed combined check/review allows one committed correction in the integration checkout followed by another validation. Main must explicitly promote; promotion and cleanup never silently discard retained work.
 
-Open `/subagent` without arguments to pick work by label. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout (including requests launched in other sessions). Pick an isolated request and **Inspect status and recovery** to launch a non-focused Herdr tab with a read-only `scout` Role on the configured `fast` route. Its prompt contains bounded saved status (including retained paths, but not raw launch environment or session transcripts); the analysis stays in that tab and does not queue a Main turn. The tab and session file are recorded for recovery even if launch becomes uncertain. The read-only `subagent_status` tool remains Main's authority for exact identities before any stage or recovery action. If Herdr or the read-only fast route is unavailable, inspection fails without changing the request; Main can use `subagent_status`. Refresh or choose completed/history for older work. Invalid state IDs are warned about and preserved. Outside Git or when isolated inventory is unavailable, direct recovery still works. Browsing does not resume work or change resources.
+Open `/subagent` without arguments to pick work by label. The menu shows direct records on this session branch and isolated requests in the current canonical Git checkout (including requests launched in other sessions). Pick an isolated request and **Inspect status and recovery** to launch a non-focused Herdr tab with a read-only `scout` Role on the configured `fast` route. Unlike ordinary direct delegation, status inspection rejects Roles with extensions or MCP servers because their tools are not verified read-only. Its prompt contains bounded saved status (including retained paths, but not raw launch environment or session transcripts); the analysis stays in that tab and does not queue a Main turn. The tab and session file are recorded for recovery even if launch becomes uncertain. The read-only `subagent_status` tool remains Main's authority for exact identities before any stage or recovery action. If Herdr or the read-only fast route is unavailable, inspection fails without changing the request; Main can use `subagent_status`. Refresh or choose completed/history for older work. Invalid state IDs are warned about and preserved. Outside Git or when isolated inventory is unavailable, direct recovery still works. Browsing does not resume work or change resources.
 
 For a locally active unsealed isolated changeset, choose **Send follow-up instructions** to open a native multiline editor; submission queues the instruction, not a completed revision. Choose **Edit queued instructions** to withdraw *all still-pending* instructions for that selected task before the editor opens. Their full text appears in FIFO order separated by blank lines. Explicit submission queues **one replacement** at the tail. Cancel leaves the withdrawn instructions removed; already-claimed instructions, initial prompts, and automatic corrections cannot be recalled. A worker may seal during editing: failed submission reopens the full submitted text for deliberate editing or copying, never automatically requeues it. Combined text above the single-instruction limit is preserved in the editor but rejected until shortened. Cancelling before withdrawal makes no change. Neither action touches Main's editor or Pi's global Option+Up queue shortcut. No-UI sessions can run `/subagent recover` or use agent tools for individual inspection and recovery.
 
@@ -142,7 +149,7 @@ After a coordinator interruption, run `/subagent recover` once. It acquires the
 
 The following details describe exact identity and retained-work requirements.
 
-Pass the exact `generation`, candidate (`taskId`, `attempt`, `candidate`) and `expectedTip` identities reported by status to stage; pass the generation and combined `expectedTip` to integrate. If Main advances cleanly before promotion, call `subagent_integrate refresh` with the recorded `expectedMain`, old `expectedTip`, and new clean `newMain`. Main must restage selected immutable candidates into the new generation and rerun combined checks. Dirty or divergent Main blocks refresh. Stale identities fail. If integration allocation was uncertain, `subagent_stage resolve` first proves the owned checkout is still at its base before starting the selected merge; otherwise it retains the intent. At most two integration worktrees may remain unreleased per request; a superseded generation is read-only. To release a superseded *clean* integration checkout, call `subagent_integrate` with `{ id, action: "release", generation, expectedTip }`, using that generation's last staged tip (or integration base when no stage completed). To release a rejected candidate after its worker has terminated and all generations using it are released, pass `{ id, action: "release", generation: <latest generation number, or 1>, taskId, attempt, expectedTip: <candidate tip> }`. Release persists each host/checkout/branch step, verifies ownership and cleanliness (including ignored files), and deletes the branch only if its ref still names the exact tip. Dirty, conflicted, changed, or uncertain resources remain for manual inspection; retry the same release after resolving the obstacle. Released checkouts free a retained slot; abort is available after every retained resource is released. Rejection can invalidate dependent work; if fresh dependent execution is impossible, start a new request instead of forcing promotion. Productive requests have no whole-run wall-clock deadline. Resume does not reset the recorded policy or correction count. Child limits, abort signals, process I/O, status inspection, exact termination, and cleanup retain finite safety bounds.
+A checked candidate stays retained if Main is dirty. Staging, combined validation, and promotion require Main to be clean at the pinned committed identity; clean your local edits deliberately before using those actions. No dirty work is replayed or merged automatically. Pass the exact `generation`, candidate (`taskId`, `attempt`, `candidate`) and `expectedTip` identities reported by status to stage; pass the generation and combined `expectedTip` to integrate. If Main advances cleanly before promotion, call `subagent_integrate refresh` with the recorded `expectedMain`, old `expectedTip`, and new clean `newMain`. Main must restage selected immutable candidates into the new generation and rerun combined checks. Dirty or divergent Main blocks refresh. Stale identities fail. If integration allocation was uncertain, `subagent_stage resolve` first proves the owned checkout is still at its base before starting the selected merge; otherwise it retains the intent. At most two integration worktrees may remain unreleased per request; a superseded generation is read-only. To release a superseded *clean* integration checkout, call `subagent_integrate` with `{ id, action: "release", generation, expectedTip }`, using that generation's last staged tip (or integration base when no stage completed). To release a rejected candidate after its worker has terminated and all generations using it are released, pass `{ id, action: "release", generation: <latest generation number, or 1>, taskId, attempt, expectedTip: <candidate tip> }`. Release persists each host/checkout/branch step, verifies ownership and cleanliness (including ignored files), and deletes the branch only if its ref still names the exact tip. Dirty, conflicted, changed, or uncertain resources remain for manual inspection; retry the same release after resolving the obstacle. Released checkouts free a retained slot; abort is available after every retained resource is released. Rejection can invalidate dependent work; if fresh dependent execution is impossible, start a new request instead of forcing promotion. Productive requests have no whole-run wall-clock deadline. Resume does not reset the recorded policy or correction count. Child limits, abort signals, process I/O, status inspection, exact termination, and cleanup retain finite safety bounds.
 
 The extension never pushes, opens a pull request, publishes, deploys, force-cleans recoverable work, or silently falls back to Main.
 
@@ -183,7 +190,18 @@ Children disable ambient extension and Skill discovery. Only declared resources
 
 ## API
 
-The package root exports the Role loader and launch APIs, the FIFO ephemeral executor, child-worktree helpers, exact review and working-change evidence helpers, checked isolated schemas, runtimes, and runner types.
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `loadRoles`, `parseRoleName` | functions | Load and validate built-in and user Roles. |
+| `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. |
+| `createChildWorktree`, `finalizeChildWorktree` | functions | Create and conservatively finalize child worktrees. |
+| `prepareExactReviewEvidence`, `prepareWorkingChangeEvidence` | functions | Prepare private exact review or working-change evidence. |
+| `ExecuteRequestSchema`, `StageRequestSchema`, `IntegrationActionSchema` | schemas | Validate checked request and integration inputs. |
+| `IsolatedRunner`, `FileRunStore` | classes | Run checked work and persist durable request state. |
+| `RoleLaunchRuntime`, `HerdrHostRuntime`, `CheckedGitRuntime` | classes | Supply launch, host, and Git behavior to the runner. |
+| `ExecutionPolicySnapshot`, `RunState`, `CoordinatorRuntime` | types | Describe persisted policy, state, and runner integration. |
 
 `createEphemeralSubagentExecutor` accepts global concurrency, turn/token, idle, and hard-runtime policy. Queued time consumes no child timeout. A run resolves resources only after receiving its permit and accepts abort, output, token, and activity callbacks. Output and diagnostics are bounded.
 
@@ -191,8 +209,8 @@ See [Orchestration and package-author API](./docs/orchestration.md) for the deta
 
 ## State and storage
 
-Durable state is private under `config/pi-subagent/state/`. State v5 rejects v4 and older files rather than migrating them; retain the old state and recover its work manually.
+Durable state is private under `config/pi-subagent/state/`. Isolated worker Pi sessions are precreated with mode `0600` under `config/pi-subagent/leases/` without changing the worker's umask. Reads stop at the 16 MiB limit even if the session grows; an oversized session requires inspection rather than being accepted as completion evidence. Sessions are removed only after exact worker-tab cleanup; retained sessions may contain prompts and answers, so do not share them. State v5 rejects v4 and older files rather than migrating them; retain the old state and recover its work manually.
 
 ## Limits and recovery
 
-Role extensions and MCP servers are trusted executable code, not a sandbox. Select the smallest resource set. Read-only direct Roles cannot write through their declared tools. This is a capability check, not an OS sandbox; external processes and changes to Main's checkout can still make a concurrent read stale. Retained-work reports identify exact resources for deliberate recovery.
+Role extensions and MCP servers are trusted executable code, not a sandbox. Select the smallest resource set. Direct admission checks only declared base tools; extensions and MCP servers can perform writes, including to Main's checkout. Concurrent changes can make a direct worker's read stale. Retained-work reports identify exact resources for deliberate recovery.

package/dist/direct-herdr.d.ts

@@ -11,6 +11,7 @@ export interface DirectHandle {
     usageTokens(): Promise<number | undefined>;
     cancel(): Promise<void>;
 }
+export declare function exactDirectTerminalTurn(jsonl: string, prompt: string): boolean;
 export declare function exactDirectAnswer(jsonl: string, prompt: string, maxBytes?: number): string;
 export declare function directSessionTokens(jsonl: string, prompt: string): number | undefined;
 export type DirectTab = Pick<DirectHandle, "name" | "tabId" | "paneId" | "sessionFile">;

package/dist/direct-herdr.js

@@ -23,7 +23,7 @@ const result = (value, type) => {
         throw new Error(`Herdr returned an unexpected ${type} response.`);
     return response;
 };
-export function exactDirectAnswer(jsonl, prompt, maxBytes = ANSWER_LIMIT) {
+function exactFinalTurn(jsonl, prompt) {
     const lines = jsonl.trimEnd().split("\n");
     let userId;
     let final;
@@ -57,7 +57,15 @@ export function exactDirectAnswer(jsonl, prompt, maxBytes = ANSWER_LIMIT) {
         seen.add(ancestor);
         ancestor = parents.get(ancestor);
     }
-    if (!userId || ancestor !== userId || !final || final.stopReason !== "stop" || !Array.isArray(final.content)) {
+    return userId && ancestor === userId ? final : undefined;
+}
+export function exactDirectTerminalTurn(jsonl, prompt) {
+    const reason = exactFinalTurn(jsonl, prompt)?.stopReason;
+    return reason === "stop" || reason === "error" || reason === "aborted";
+}
+export function exactDirectAnswer(jsonl, prompt, maxBytes = ANSWER_LIMIT) {
+    const final = exactFinalTurn(jsonl, prompt);
+    if (!final || final.stopReason !== "stop" || !Array.isArray(final.content)) {
         throw new Error("Pi did not persist an exact successful final answer for this prompt.");
     }
     const text = final.content.flatMap((part) => {

package/dist/git-runtime.d.ts

@@ -41,6 +41,10 @@ export declare class CheckedGitRuntime implements GitRuntime, TaskCandidateInspe
     inspectMain(input: {
         root: string;
     }, context: OperationContext): Promise<WorkspaceIdentity>;
+    /** Pin the checked-out committed tree without reading or changing Main's dirty index/worktree. */
+    inspectMainBase(input: {
+        root: string;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
     allocateWorktree(input: {
         root: string;
         baseRoot?: string;

package/dist/git-runtime.js

@@ -68,6 +68,22 @@ export class CheckedGitRuntime {
             return await this.inspectWorkspace(input.root, false, context);
         });
     }
+    /** Pin the checked-out committed tree without reading or changing Main's dirty index/worktree. */
+    async inspectMainBase(input, context) {
+        const cwd = input.root;
+        const branch = oneLine(await this.requireGit(["symbolic-ref", "--quiet", "HEAD"], cwd, context), "branch reference");
+        const head = oid(await this.requireGit(["rev-parse", "--verify", "HEAD^{commit}"], cwd, context), "HEAD");
+        const entries = await this.requireGit(["ls-tree", "-r", "-z", head], cwd, context);
+        if (entries.split("\0").some((entry) => entry.startsWith("160000 "))) {
+            throw new Error("Pi Subagent does not support Git repositories containing mode-160000 gitlinks.");
+        }
+        const tree = oid(await this.requireGit(["rev-parse", "--verify", `${head}^{tree}`], cwd, context), "HEAD tree");
+        if (branch !== oneLine(await this.requireGit(["symbolic-ref", "--quiet", "HEAD"], cwd, context), "branch reference")
+            || head !== oid(await this.requireGit(["rev-parse", "--verify", "HEAD^{commit}"], cwd, context), "HEAD")) {
+            throw new Error("Git workspace changed during committed Main inspection.");
+        }
+        return { branch, head, index: tree, tree };
+    }
     async allocateWorktree(input, context) {
         return await this.serializeMainOperation(input.root, context.signal, async () => {
             return await this.allocateWorktreeExclusive(input, context);
@@ -77,7 +93,10 @@ export class CheckedGitRuntime {
         let prepared;
         let createdWorktree;
         const baseRoot = input.baseRoot ?? input.root;
-        const before = await this.inspectWorkspace(baseRoot, false, context);
+        const inspectBase = () => baseRoot === input.root
+            ? this.inspectMainBase({ root: baseRoot }, context)
+            : this.inspectWorkspace(baseRoot, false, context);
+        const before = await inspectBase();
         if (!sameIdentity(before, input.attempt.waveBase)) {
             return { kind: "worktree", outcome: "absent", failure: "Recorded wave snapshot drifted before worktree allocation." };
         }
@@ -88,7 +107,7 @@ export class CheckedGitRuntime {
                     throw new Error("pi-subagent prepared a worktree from a base other than the recorded wave base.");
                 }
                 await input.onPrepared(prepared);
-                const current = await this.inspectWorkspace(baseRoot, false, context);
+                const current = await inspectBase();
                 if (!sameIdentity(current, input.attempt.waveBase)) {
                     throw new Error("Recorded wave snapshot drifted after worktree preparation and before git worktree add.");
                 }
@@ -106,7 +125,7 @@ export class CheckedGitRuntime {
                     possibleResources: [worktree.path, worktree.branch],
                 };
             }
-            const after = await this.inspectWorkspace(baseRoot, false, context);
+            const after = await inspectBase();
             if (!sameIdentity(after, input.attempt.waveBase)) {
                 return {
                     kind: "worktree",

package/dist/herdr-runtime.d.ts

@@ -119,6 +119,11 @@ export declare class HerdrHostRuntime implements HostRuntime {
     private createPrivateLease;
     private removeLeaseArtifacts;
     private assertPrivateLeaseDirectories;
+    private workerSessionFile;
+    private sessionFileExists;
+    private privateSessionFile;
+    private workerTurnFinished;
+    private removeWorkerSessionFile;
     private assertLeasePath;
     private assertPrivateLease;
     private scanLease;

package/dist/herdr-runtime.js

@@ -9,6 +9,7 @@ import { isCleanCommitted, } from "./schema.js";
 import { buildChangesetTaskPrompt, withTransientLaunch, } from "./runner.js";
 import { runProcess as defaultRunProcess } from "./process.js";
 import { EXECUTION_BUDGET_ENV } from "./ephemeral.js";
+import { exactDirectTerminalTurn } from "./direct-herdr.js";
 const MIN_HERDR_VERSION = [0, 9, 0];
 const MIN_HERDR_PROTOCOL = 22;
 const HERDR_OPERATION_CAP_MS = 30_000;
@@ -19,6 +20,7 @@ const STALLED_PROMPT_POLL_MS = 250;
 const HOST_LAYOUT_POLL_MS = 50;
 const HOST_LAYOUT_MAX_POLLS = 40;
 const DIAGNOSTIC_LIMIT = 8 * 1024;
+const SESSION_LIMIT = 16 * 1024 * 1024;
 const LEASE_MODE = 0o600;
 const DIRECTORY_MODE = 0o700;
 const PROCESS_LEASE_ENV = "PI_SUBAGENT_PROCESS_LEASE";
@@ -478,7 +480,7 @@ export class HerdrHostRuntime {
         try {
             if (input.task.kind !== "changeset")
                 throw new Error("Herdr assignment requires a changeset task.");
-            text = buildChangesetTaskPrompt({
+            text = `${buildChangesetTaskPrompt({
                 goal: input.goal,
                 contexts: input.contexts,
                 task: input.task,
@@ -486,7 +488,9 @@ export class HerdrHostRuntime {
                 worktreeCwd: allocation.worktreeCwd,
                 ...(input.failure ? { failure: input.failure } : {}),
                 ...(input.instruction ? { instruction: input.instruction } : {}),
-            });
+            })}\n\nTurn identity: ${input.attempt.correlationToken}:${input.attempt.prompts.length}`;
+            if (Buffer.byteLength(text, "utf8") > 96 * 1024)
+                throw new Error("Worker assignment exceeds 98304 bytes.");
         }
         catch (error) {
             return { outcome: "not_prompted", diagnostic: `Worker assignment was not submitted: ${safeText(error)}` };
@@ -512,7 +516,7 @@ export class HerdrHostRuntime {
         const prompted = await this.herdr.exec(promptArgs, promptOptions);
         if (prompted.code !== 0 || prompted.killed) {
             if (!prompted.killed && !context.signal.aborted && hasHerdrErrorCode(prompted, "agent_prompt_stalled")) {
-                return await this.reconcileDeliveredPrompt(input, allocation, context);
+                return await this.reconcileDeliveredPrompt(input, allocation, context, text);
             }
             return {
                 outcome: prompted.killed || context.signal.aborted ? "interrupted" : "unknown",
@@ -527,12 +531,12 @@ export class HerdrHostRuntime {
             return { outcome: "unknown", diagnostic: `Worker prompt response is malformed: ${safeText(error)}` };
         }
         if (settled.status === "working")
-            return await this.reconcileDeliveredPrompt(input, allocation, context);
+            return await this.reconcileDeliveredPrompt(input, allocation, context, text);
         if (settled.status === "blocked")
             return { outcome: "blocked", diagnostic: await this.diagnostic(allocation, context, "Worker settled as blocked.") };
         if (!SETTLED_AGENT_STATES.has(settled.status))
             return { outcome: "unknown", diagnostic: `Worker prompt did not return a settled state: ${settled.status}.` };
-        return await this.candidateResult(input, allocation, context);
+        return await this.candidateResult(input, allocation, context, text);
     }
     async terminateWorker(input, context) {
         try {
@@ -788,10 +792,16 @@ export class HerdrHostRuntime {
             if (Object.keys(launch.env).some((name) => name !== EXECUTION_BUDGET_ENV || !this.executionBudget)) {
                 throw new Error("Herdr agent launch must not receive caller Role environment variables.");
             }
+            const args = launch.args.filter((arg) => arg !== "--no-session");
+            if (args.length !== launch.args.length - 1)
+                throw new Error("Role launch must contain exactly one --no-session option.");
+            const sessionFile = this.workerSessionFile(allocation.leasePath, allocation.token);
+            // Pi initializes an existing empty session in place, retaining its private mode.
+            await (await open(sessionFile, "wx", 0o600)).close();
             const response = await startPiAgent(this.herdr, {
                 name: allocation.agentName,
                 pane: allocation.paneId,
-                args: launch.args,
+                args: [...args, "--session", sessionFile],
                 options,
                 shouldRetry: () => false,
             });
@@ -812,7 +822,7 @@ export class HerdrHostRuntime {
             }
         });
     }
-    async reconcileDeliveredPrompt(input, allocation, context, promptMayBeInFlight = true) {
+    async reconcileDeliveredPrompt(input, allocation, context, prompt, promptMayBeInFlight = true) {
         for (;;) {
             let lifecycle;
             try {
@@ -862,6 +872,16 @@ export class HerdrHostRuntime {
                     diagnostic: await this.diagnostic(allocation, context, "Delivered prompt settled with a candidate."),
                 };
             }
+            if (SETTLED_AGENT_STATES.has(lifecycle.status)) {
+                try {
+                    if (await this.workerTurnFinished(allocation, prompt)) {
+                        return { outcome: "blocked", diagnostic: "Worker finished without an exact changed clean committed candidate." };
+                    }
+                }
+                catch (error) {
+                    return { outcome: "unknown", diagnostic: `Worker session evidence cannot be verified: ${error instanceof SyntaxError ? "malformed JSONL" : safeText(error)}` };
+                }
+            }
             if (!promptMayBeInFlight && SETTLED_AGENT_STATES.has(lifecycle.status)) {
                 return {
                     outcome: "blocked",
@@ -879,7 +899,7 @@ export class HerdrHostRuntime {
             }
         }
     }
-    async candidateResult(input, allocation, context) {
+    async candidateResult(input, allocation, context, prompt) {
         let inspection;
         try {
             inspection = await this.inspectInFlightCandidate({ root: allocation.worktreeCwd, task: input.task, attempt: input.attempt }, this.childContext(context, GIT_INSPECTION_CAP_MS));
@@ -888,7 +908,7 @@ export class HerdrHostRuntime {
             return { outcome: "unknown", diagnostic: `Settled worker candidate inspection failed: ${safeText(error)}` };
         }
         if (!inspection.valid || !inspection.clean || !this.isExpectedCandidate(input, inspection.candidate)) {
-            return await this.reconcileDeliveredPrompt(input, allocation, context, false);
+            return await this.reconcileDeliveredPrompt(input, allocation, context, prompt, false);
         }
         return {
             outcome: "candidate",
@@ -1021,6 +1041,7 @@ export class HerdrHostRuntime {
         }
         if (!directoryPresent)
             return;
+        await this.removeWorkerSessionFile(allocation.leasePath, token);
         try {
             await rmdir(dirname(allocation.leasePath));
         }
@@ -1047,6 +1068,77 @@ export class HerdrHostRuntime {
         }
         return true;
     }
+    workerSessionFile(leasePath, token) {
+        this.assertLeasePath(leasePath, token);
+        return `${leasePath}.session.jsonl`;
+    }
+    async sessionFileExists(path) {
+        try {
+            await lstat(path);
+            return true;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }
+    async privateSessionFile(path) {
+        let file;
+        try {
+            file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        try {
+            const info = await file.stat();
+            const uid = process.getuid?.();
+            if (!info.isFile() || (info.mode & 0o077) !== 0 || (uid !== undefined && info.uid !== uid)
+                || info.size > SESSION_LIMIT)
+                throw new Error("Worker session file is not private, regular, or bounded.");
+            const chunks = [];
+            let bytes = 0;
+            while (bytes <= SESSION_LIMIT) {
+                const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, SESSION_LIMIT + 1 - bytes));
+                const { bytesRead } = await file.read(chunk, 0, chunk.length, null);
+                if (!bytesRead)
+                    break;
+                chunks.push(chunk.subarray(0, bytesRead));
+                bytes += bytesRead;
+            }
+            if (bytes > SESSION_LIMIT)
+                throw new Error("Worker session file exceeds the 16 MiB limit.");
+            return Buffer.concat(chunks, bytes).toString("utf8");
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async workerTurnFinished(allocation, prompt) {
+        const path = this.workerSessionFile(allocation.leasePath, allocation.token);
+        if (!await this.sessionFileExists(path))
+            return false;
+        await this.assertPrivateLeaseDirectories(allocation.leasePath, false);
+        const session = await this.privateSessionFile(path);
+        if (session === undefined)
+            return false;
+        try {
+            return exactDirectTerminalTurn(session, prompt);
+        }
+        catch (error) {
+            if (error instanceof SyntaxError && !session.endsWith("\n"))
+                return false; // Pi may still be writing the last JSONL entry.
+            throw error;
+        }
+    }
+    async removeWorkerSessionFile(leasePath, token) {
+        const path = this.workerSessionFile(leasePath, token);
+        if (await this.privateSessionFile(path) !== undefined)
+            await unlink(path);
+    }
     assertLeasePath(path, token) {
         const parent = resolve(this.leaseDirectory, token);
         const candidate = resolve(path);

package/dist/launch-runtime.d.ts

@@ -18,7 +18,7 @@ export interface LaunchRuntimeOptions {
         cwd: string;
         root: string;
     }, context: OperationContext): Promise<void>;
-    inspectMain(input: {
+    inspectMainBase(input: {
         root: string;
     }, context: OperationContext): Promise<WorkspaceIdentity>;
     executionBudget?: () => Omit<EphemeralSubagentExecutionBudget, "startedAt">;

package/dist/launch-runtime.js

@@ -167,7 +167,7 @@ export class RoleLaunchRuntime {
         if (input.request.tasks.some((task) => task.kind === "changeset")) {
             await this.options.preflightHost?.({ request: input.request, cwd: input.cwd, root }, context);
         }
-        const main = await this.options.inspectMain({ root }, context);
+        const main = await this.options.inspectMainBase({ root }, context);
         const required = new Map();
         const addRequired = (role, modelClass) => {
             const modelClasses = required.get(role) ?? new Set();

package/dist/runner.d.ts

@@ -201,6 +201,9 @@ export interface GitRuntime {
     inspectMain(input: {
         root: string;
     }, context: OperationContext): Promise<WorkspaceIdentity>;
+    inspectMainBase(input: {
+        root: string;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
     allocateWorktree(input: {
         root: string;
         baseRoot?: string;
@@ -302,6 +305,7 @@ export declare class IsolatedRunner {
             }>;
         }>;
         invalidIds: string[];
+        states: RunState[];
     }>;
     /** Classify orphaned work under the same repository lease as productive execution.
      * Status remains read-only; Main alone chooses any subsequent action. */

package/dist/runner.js

@@ -520,8 +520,8 @@ export class IsolatedRunner {
         this.currentPolicy = currentPolicy;
     }
     async listRequests(root) {
-        const { states, invalidIds } = await this.store.list(root);
-        return { invalidIds, requests: states.map(({ state }) => ({
+        const { states: entries, invalidIds } = await this.store.list(root);
+        return { invalidIds, states: entries.map(({ state }) => state), requests: entries.map(({ state }) => ({
                 id: state.request.id, name: state.request.goal,
                 status: state.status === "completed" && (state.tasks.some((task) => task.kind === "changeset" && task.attempts.some((attempt) => attempt.cleanup.some((step) => step.status !== "completed")))
                     || state.integration.generations.some((generation) => generation.cleanup?.some((step) => step.status !== "completed")
@@ -1237,7 +1237,7 @@ export class IsolatedRunner {
                     && stagedDependencySnapshot(state, task.taskId, action.expectedTip));
                 if (!ready.length)
                     throw new Error("No dependent task is ready on this staged snapshot.");
-                await this.requireExactIntegration(handle, generation, receipts, scope);
+                await this.requireExactIntegration(handle, generation, receipts, scope, true);
                 return await this.run(handle, scope, undefined, action.expectedTip);
             }
             if (action.action === "cleanup") {
@@ -1559,7 +1559,7 @@ export class IsolatedRunner {
             await this.saveProductive(handle);
         }
     }
-    async requireExactIntegration(handle, generation, receipts, scope) {
+    async requireExactIntegration(handle, generation, receipts, scope, allowDirtyMain = false) {
         const root = handle.state.root;
         const worktree = generation.worktree;
         const tip = generation.correction
@@ -1577,7 +1577,8 @@ export class IsolatedRunner {
                 throw new Error("Selected worker has no owned worktree.");
             await this.callProductive(handle, scope, (context) => this.integrationGit.inspectWorker(root, worker, stage.source, context.signal));
         }
-        const main = await this.callProductive(handle, scope, (context) => this.gitRuntime.inspectMain({ root }, context));
+        const main = await this.callProductive(handle, scope, (context) => allowDirtyMain
+            ? this.gitRuntime.inspectMainBase({ root }, context) : this.gitRuntime.inspectMain({ root }, context));
         if (!sameIdentity(main, generation.expectedMain))
             throw new Error("Main changed or became dirty before promotion.");
     }
@@ -1674,7 +1675,7 @@ export class IsolatedRunner {
                 }
                 let actualMain;
                 try {
-                    actualMain = await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectMain({ root: state.root }, context));
+                    actualMain = await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectMainBase({ root: state.root }, context));
                 }
                 catch (error) {
                     this.rethrowStopped(error);
@@ -1694,7 +1695,7 @@ export class IsolatedRunner {
                 }
                 if (stagedSnapshot) {
                     const generation = state.integration.generations.at(-1);
-                    await this.requireExactIntegration(handle, generation, this.stageReceipts(generation), scope);
+                    await this.requireExactIntegration(handle, generation, this.stageReceipts(generation), scope, true);
                 }
                 const wave = {
                     number: state.waves.length + 1,
@@ -1953,14 +1954,22 @@ export class IsolatedRunner {
             const baseRoot = wave.base.head === state.main.head ? state.root : state.integration.generations.at(-1)?.worktree?.path;
             if (!baseRoot)
                 throw new Error("Staged dependency checkout is unavailable.");
-            if (!sameIdentity(await this.gitRuntime.inspectMain({ root: baseRoot }, context), wave.base)) {
+            const inspectBase = baseRoot === state.root ? this.gitRuntime.inspectMainBase.bind(this.gitRuntime) : this.gitRuntime.inspectMain.bind(this.gitRuntime);
+            if (!sameIdentity(await inspectBase({ root: baseRoot }, context), wave.base)) {
                 throw new Error("Staged dependency snapshot drifted before text launch.");
             }
-            const isolated = await createChildWorktree(baseRoot, `${state.request.id}-${task.taskId}-text-${attempt.number}`, undefined, context.signal);
+            const isolated = await createChildWorktree(baseRoot, `${state.request.id}-${task.taskId}-text-${attempt.number}`, undefined, context.signal, async (worktree) => {
+                if (worktree.baseCommit !== wave.base.head || !sameIdentity(await inspectBase({ root: baseRoot }, context), wave.base)) {
+                    throw new Error("Staged dependency snapshot drifted before text worktree creation.");
+                }
+            });
             if (!isolated)
                 throw new Error("Explicit isolated text work requires a Git checkout with a committed HEAD; it never falls back to Main.");
             let result;
             try {
+                if (!sameIdentity(await inspectBase({ root: baseRoot }, context), wave.base)) {
+                    throw new Error("Staged dependency snapshot drifted during text worktree creation.");
+                }
                 const launchHandle = await this.coordinatorRuntime.acquireLaunch(request.role, request.modelClass, context);
                 if (launchHandle.launch.role !== request.role || launchHandle.launch.modelClass !== request.modelClass) {
                     await withTransientLaunch(launchHandle, async () => {
@@ -1994,7 +2003,7 @@ export class IsolatedRunner {
         if (Buffer.byteLength(output, "utf8") > MAX_PERSISTED_RUNTIME_TEXT_BYTES) {
             throw new Error(`Text task executor output exceeds ${MAX_PERSISTED_RUNTIME_TEXT_BYTES} UTF-8 bytes.`);
         }
-        const actualMain = await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectMain({ root: state.root }, context));
+        const actualMain = await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectMainBase({ root: state.root }, context));
         if (!sameIdentity(actualMain, state.main))
             throw new Error("Main drifted during text task execution.");
         const wave = state.waves.at(-1);
@@ -2003,7 +2012,7 @@ export class IsolatedRunner {
             if (!generation?.worktree || generation.status === "superseded" || !sameIdentity(generation.combinedTip, wave.base)) {
                 throw new Error("Staged dependency snapshot was superseded during text task execution.");
             }
-            await this.requireExactIntegration(handle, generation, this.stageReceipts(generation), scope);
+            await this.requireExactIntegration(handle, generation, this.stageReceipts(generation), scope, true);
         }
         attempt.status = "completed";
         attempt.failure = undefined;

package/docs/orchestration.md

@@ -62,7 +62,7 @@ Each entry has:
 
 An explicit model must support the route's thinking level. A launched child is never retried automatically after provider or process failure.
 
-Only Roles with known read-only tools and no extensions or MCP servers may run direct. A direct `changeset` or write-capable Role is rejected; use isolated mode for implementation. Parallel reads run concurrently and report in request order. A chain substitutes only the preceding successful output and stops at its first failure.
+Only Roles whose declared base tools are known read-only may run direct. Configured extensions and MCP servers are trusted and may provide additional tools or write to Main's checkout. A direct `changeset` or Role with write-capable base tools is rejected; use isolated mode for implementation. Parallel tasks run concurrently and report in request order. A chain substitutes only the preceding successful output and stops at its first failure.
 
 The tool returns a handle after the first exact Herdr tab is launched. The remaining tabs are launched asynchronously; their identities are recorded on the session branch. A session-owned observer awaits each exact agent's lifecycle and retrieves its final answer from its Pi session file, not its possibly truncated screen. Idle, blocked, unknown, malformed, or oversized answers fail with recoverable tab/session identity; no whole-run deadline is imposed. `/subagent` shows exact recorded tabs on this session branch, distinguishing locally observed work from unobserved records. A session switch stops observation and carries tab identity into the new branch.
 
@@ -91,9 +91,9 @@ Every task declares `id`, `kind`, `role`, `modelClass`, `requirements`, `deliver
 - `contextFrom` may reference completed text tasks only and preserves declaration order.
 - A graph containing changesets requires final checks. The repository root must have a `package.json` test script; admission prepends canonical `pnpm test` if absent from final checks. Combined validation rejects a changed root test script.
 
-The runner executes ready worker tasks concurrently, inspects clean committed candidates, runs preliminary task checks and optional preliminary judgment, then records ready candidates for Main. **It does not automatically integrate them.** Main selects exact candidates via `subagent_stage` into an owned integration checkout in explicit order. Each stage is a committed merge of the candidate, not a mutation of Main. Conflicts retain the checkout for Main to resolve; `resolve` verifies the exact two-parent merge instead of replaying an uncertain merge. Main can explicitly run dependent tasks from an exact staged tip with `subagent_integrate advance` and stage their results afterward. Independent candidates may be staged without re-running workers.
+Admission and worker-wave dispatch pin Main's exact committed branch, HEAD, and tree without inspecting or modifying its staged, unstaged, or untracked edits. Worker allocation verifies the same committed identity around worktree creation, including resumed waves; staged-dependent waves verify their clean integration snapshot. A dirty Main can therefore produce a checked retained candidate, but branch/HEAD drift stops new waves. The runner executes ready worker tasks concurrently, inspects clean committed candidates, runs preliminary task checks and optional preliminary judgment, then records ready candidates for Main. **It does not automatically integrate them.** Main selects exact candidates via `subagent_stage` into an owned integration checkout in explicit order. Each stage is a committed merge of the candidate, not a mutation of Main. Conflicts retain the checkout for Main to resolve; `resolve` verifies the exact two-parent merge instead of replaying an uncertain merge. Main can explicitly run dependent tasks from an exact staged tip with `subagent_integrate advance` and stage their results afterward. Independent candidates may be staged without re-running workers.
 
-Once all selected work is staged, Main calls `subagent_integrate validate` on the exact clean combined tip. This runs every final check, including `pnpm test`, and optional final judgment in the integration checkout before any Main mutation. A failed check/review can be followed by one Main-authored committed correction in that checkout, recorded with `correct`, then another `validate`. `promote` requires exact passing combined evidence and unchanged Main and uses a guarded update to Main. Only proven promotion leads to selected-worker termination and verified cleanup. A changed candidate, integration tip, or Main identity invalidates prior evidence or blocks promotion; review accepts only exact `PASS`.
+Once all selected work is staged, Main calls `subagent_integrate validate` on the exact clean combined tip. This runs every final check, including `pnpm test`, and optional final judgment in the integration checkout before any Main mutation. A failed check/review can be followed by one Main-authored committed correction in that checkout, recorded with `correct`, then another `validate`. Staging, combined validation, and `promote` require clean Main at the recorded committed identity; they stay blocked by dirty edits even when the checked candidate is retained, and no dirty work is replayed or merged automatically. `promote` requires exact passing combined evidence and unchanged Main and uses a guarded update to Main. Only proven promotion leads to selected-worker termination and verified cleanup. A changed candidate, integration tip, or Main identity invalidates prior evidence or blocks promotion; review accepts only exact `PASS`.
 
 ### Readiness and Main actions
 
@@ -118,7 +118,7 @@ State version 5 is stored privately under:
 <agent-dir>/config/pi-subagent/state/<repository-hash>/<request-id>.json
 ```
 
-Strict parsing rejects unknown properties, malformed evidence, invalid lineage, and old v4 state without migration; preserve old files and recover their work manually. Writes are atomic and repository productive work uses a durable process lease. `delegate_task` and `subagent_resume` acknowledge only after durable state is saved, then continue productive work asynchronously. Completion or attention is sent as a Pi follow-up to the launching session. `subagent_status` is read-only and remains the recovery authority if a follow-up is missed. `subagent_resume` accepts only the continuation reported by state. `subagent_abort` performs exact worker termination and teardown.
+Strict parsing rejects unknown properties, malformed evidence, invalid lineage, and old v4 state without migration; preserve old files and recover their work manually. Writes are atomic and repository productive work uses a durable process lease. `delegate_task` and `subagent_resume` acknowledge only after durable state is saved, then continue productive work asynchronously. A durably recorded worker attention state sends an immediate once-per-transition Pi follow-up to the launching session, even while siblings run; the wave also reports its final outcome. Isolated workers persist a private exact Pi session under the owned process lease so a proved final answer without a changed clean commit becomes attention rather than an indefinitely pending prompt. Missing or mismatched session proof cannot establish completion and never authorizes prompt replay. `subagent_status` is read-only and remains the recovery authority if a follow-up is missed. `subagent_resume` accepts only the continuation reported by state. `subagent_abort` performs exact worker termination and teardown.
 
 Productive execution has no whole-run wall-clock deadline. Long productive work and later resumes remain valid. The request retains its original policy snapshot and correction count; a resume cannot refill them. Current configuration may tighten the correction allowance. Child idle/hard runtime, subprocess I/O, status inspection, termination, cleanup, and outer abort remain bounded independently.
 

package/extensions/admission.ts

@@ -7,7 +7,11 @@ const READ_ONLY_TOOLS = new Set([
 ]);
 
 export function roleCanWrite(role: Role): boolean {
-	return Boolean(role.extensions.length || role.mcps?.length || role.tools.some((tool) => !READ_ONLY_TOOLS.has(tool)));
+	return role.tools.some((tool) => !READ_ONLY_TOOLS.has(tool));
+}
+
+export function roleIsReadOnlyScout(role: Role): boolean {
+	return !roleCanWrite(role) && role.extensions.length === 0 && !role.mcps?.length;
 }
 
 export interface CheckoutAdmission {

package/extensions/isolated.ts

@@ -76,7 +76,7 @@ export const createIsolatedComponents: CreateIsolatedComponents = ({
 		context,
 		resolveRoot,
 		preflightHost: async ({ root }, operation) => await host.preflightHost({ root }, operation),
-		inspectMain: async (input, operation) => await git.inspectMain(input, operation),
+		inspectMainBase: async (input, operation) => await git.inspectMainBase(input, operation),
 		executionBudget,
 	});
 	return {
@@ -117,10 +117,10 @@ export function workspaceWidgetLines(state: RunState): string[] | undefined {
 	const rows = state.tasks.flatMap((taskState) => {
 		const task = state.request.tasks.find((candidate) => candidate.id === taskState.taskId);
 		if (!task) return [];
-		const status = state.status === "aborted" ? "aborted" : workspaceStatus(taskState.status);
+		const status = workspaceStatus(taskState.status);
 		if (taskState.kind === "text") {
 			return taskState.status === "running" || taskState.status === "needs_attention"
-				? [`${status === "attention" ? "!" : status === "aborted" ? "■" : "◌"} I ${workspaceBadge(task.role, task.modelClass)} ${compactWidgetField(task.id)} · ${status === "attention" ? `attention · ${compactWidgetField(taskState.failure ?? status)}` : status}`]
+				? [`${status === "attention" ? "!" : "◌"} I ${workspaceBadge(task.role, task.modelClass)} ${compactWidgetField(task.id)} · ${status === "attention" ? `attention · ${compactWidgetField(taskState.failure ?? status)}` : status}`]
 				: [];
 		}
 		const attempt = taskState.attempts.at(-1);
@@ -136,17 +136,17 @@ export function workspaceWidgetLines(state: RunState): string[] | undefined {
 			: status === "attention" ? `attention · ${compactWidgetField(taskState.failure ?? "needs attention")}` : status;
 		return `${symbol} I ${workspaceBadge(task.role, task.modelClass)} ${compactWidgetField(task.id)} · ${detail}${allocation ? ` · ${compactWidgetField(allocation.label)}` : ""}`;
 	});
-	return rows.length ? rows : undefined;
+	if (!rows.length) return undefined;
+	return state.status === "aborted"
+		? [`■ I ${compactWidgetField(state.request.id)} · request aborted`, ...rows]
+		: rows;
 }
 
-function updateWorkspaceWidget(ctx: ExtensionContext, state: RunState, rowsByRequest: Map<string, string[]>): void {
-	const key = `${state.root}\0${state.request.id}`;
-	const rows = workspaceWidgetLines(state);
-	if (rows) rowsByRequest.set(key, rows);
-	else rowsByRequest.delete(key);
+function renderWorkspaceWidget(ctx: ExtensionContext, rowsByRequest: Map<string, string[]>): void {
 	if (!ctx.hasUI) return;
-	const allRows = [...rowsByRequest.values()].flat().sort((a, b) =>
-		(a.startsWith("!") ? 0 : a.startsWith("◌") ? 1 : 2) - (b.startsWith("!") ? 0 : b.startsWith("◌") ? 1 : 2));
+	const rowOrder = (row: string) => row.startsWith("!") ? 0 : row.startsWith("◌") ? 1
+		: row.endsWith(" · request aborted") ? 2 : 3;
+	const allRows = [...rowsByRequest.values()].flat().sort((a, b) => rowOrder(a) - rowOrder(b));
 	const shown = allRows.length > MAX_WORKSPACE_WIDGET_LINES
 		? [...allRows.slice(0, MAX_WORKSPACE_WIDGET_LINES - 1), `+${allRows.length - MAX_WORKSPACE_WIDGET_LINES + 1} more · /subagent`]
 		: allRows;
@@ -164,7 +164,11 @@ function updateWorkspaceWidget(ctx: ExtensionContext, state: RunState, rowsByReq
 
 function updateWorkspaceWidgetSafely(ctx: ExtensionContext, state: RunState, rowsByRequest: Map<string, string[]>): void {
 	try {
-		updateWorkspaceWidget(ctx, state, rowsByRequest);
+		const key = `${state.root}\0${state.request.id}`;
+		const rows = workspaceWidgetLines(state);
+		if (rows) rowsByRequest.set(key, rows);
+		else rowsByRequest.delete(key);
+		renderWorkspaceWidget(ctx, rowsByRequest);
 	} catch (error) {
 		console.error("Pi Subagent workspace widget update failed.", error);
 	}
@@ -400,7 +404,7 @@ function toolResult(response: RunResponse, ctx: ExtensionContext, rowsByRequest:
 
 export interface IsolatedSurface {
 	execute(params: unknown, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<ReturnType<typeof toolResult>>;
-	inventory(cwd: string): Promise<IsolatedInventory>;
+	inventory(cwd: string, current?: () => boolean): Promise<IsolatedInventory>;
 	recover(cwd: string): Promise<string>;
 	inspect(root: string, requestId: string): Promise<readonly string[]>;
 	canFollowup(root: string, requestId: string, taskId: string): boolean;
@@ -425,6 +429,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 	let latestCtx: ExtensionContext | undefined;
 	let components: IsolatedExtensionComponents | undefined;
 	const workspaceRowsByRequest = new Map<string, string[]>();
+	let savedRevision = 0;
 	const stateListeners = new Set<(state: RunState) => void>();
 	const activeJobs = new Set<AbortController>();
 	const jobOwners = new Map<string, () => boolean>();
@@ -442,6 +447,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		policy: options.policy,
 		currentPolicy: options.currentPolicy,
 		onStateSaved: (state) => {
+			savedRevision += 1;
 			for (const listener of stateListeners) listener(state);
 			const owner = jobOwners.get(`${state.root}\0${state.request.id}`);
 			if (!sessionClosed && (owner === undefined || owner())) {
@@ -501,6 +507,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		activeJobs.add(controller);
 		jobOwners.set(key, canDeliver);
 		const notified = new Set<string>();
+		const attentionNotified = new Set<string>();
 		let candidateListener: ((state: RunState) => void) | undefined;
 		const finish = () => {
 			activeJobs.delete(controller);
@@ -548,6 +555,15 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		candidateListener = (state) => {
 			if (state.root !== root || state.request.id !== id || state.status !== "running" || !canDeliver()) return;
 			latestState = state;
+			for (const task of state.tasks) {
+				if (task.status !== "needs_attention") {
+					attentionNotified.delete(task.taskId);
+					continue;
+				}
+				if (attentionNotified.has(task.taskId)) continue;
+				attentionNotified.add(task.taskId);
+				deliver(`Pi Subagent ${id}: ${task.taskId} needs attention. Inspect subagent_status for the saved worker evidence; do not replay an uncertain prompt.`);
+			}
 			for (const candidate of state.integration.candidates) {
 				const identity = `${candidate.taskId}\0${candidate.attempt}\0${candidate.tip.head}`;
 				if (candidate.decision || notified.has(identity)) continue;
@@ -653,9 +669,20 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		},
 	});
 	return {
-		async inventory(cwd) {
+		async inventory(cwd, current) {
 			const root = await lookupRoot(cwd);
-			return { root, ...await getComponents().runner.listRequests(root) };
+			const revision = savedRevision;
+			const { requests, invalidIds, states } = await getComponents().runner.listRequests(root);
+			if (current?.() && !sessionClosed && revision === savedRevision) {
+				workspaceRowsByRequest.clear();
+				for (const state of states) {
+					const rows = workspaceWidgetLines(state);
+					if (rows) workspaceRowsByRequest.set(`${state.root}\0${state.request.id}`, rows);
+				}
+				try { renderWorkspaceWidget(latestContext(), workspaceRowsByRequest); }
+				catch (error) { console.error("Pi Subagent workspace widget update failed.", error); }
+			}
+			return { root, requests, invalidIds };
 		},
 		async recover(cwd) {
 			const root = await lookupRoot(cwd);

package/extensions/subagent-command.ts

@@ -30,7 +30,7 @@ export interface IsolatedInventory {
  * validation and queue operation. They must not await between those operations. */
 export interface SubagentCommandAdapter {
 	direct(ctx: ExtensionContext): readonly DirectTask[];
-	isolated(cwd: string): Promise<IsolatedInventory>;
+	isolated(cwd: string, current: () => boolean): Promise<IsolatedInventory>;
 	recover(cwd: string): Promise<string>;
 	inspectInTab(root: string, requestId: string, ctx: ExtensionContext, current: () => boolean): Promise<{ tabId: string; name: string; sessionFile: string }>;
 	canFollowup(root: string, requestId: string, taskId: string): boolean;
@@ -94,7 +94,7 @@ export function registerSubagentCommand(pi: ExtensionAPI, adapter: SubagentComma
 				const direct = adapter.direct(ctx);
 				let inventory: IsolatedInventory | undefined;
 				let unavailable: string | undefined;
-				try { inventory = await adapter.isolated(ctx.cwd); }
+				try { inventory = await adapter.isolated(ctx.cwd, current); }
 				catch (error) { unavailable = errorText(error); }
 				if (!valid()) return;
 				if (unavailable) ctx.ui.notify(`Isolated inventory unavailable (${unavailable}). Direct branch recovery remains available; check the canonical Git checkout/configuration.`, "warning");

package/extensions/subagent.ts

@@ -4,7 +4,7 @@ import { type Component, Text, type TUI, truncateToWidth, visibleWidth } from "@
 import { availableTaskModels, loadTaskModelsConfig, modelReference, registerModelTask, resolveAvailableModel, type ResolvedTaskRoute, taskThinkingLevels } from "@henryqw/pi-task-models";
 import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, DELEGATE_TASK, formatDuration, loadRoles, prepareRoleLaunch, ROLE_TOOL_POLICY_FLAG, type Role } from "@henryqw/pi-subagent";
 import { DEFAULT_EXECUTION_POLICY, DEFAULT_TIMEOUT_CONFIG, readSubagentConfig, resolveExecutionPolicy, type EffectiveExecutionPolicy } from "./config.ts";
-import { createCheckoutAdmission, roleCanWrite } from "./admission.ts";
+import { createCheckoutAdmission, roleCanWrite, roleIsReadOnlyScout } from "./admission.ts";
 import { registerIsolatedExtension } from "./isolated.ts";
 import { registerSubagentCommand, type DirectTask } from "./subagent-command.ts";
 import { MODEL_CLASS_GUIDANCE } from "./model-class-policy.ts";
@@ -210,7 +210,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			}
 			return [...grouped.values()];
 		},
-		isolated: (cwd) => isolatedSurface.inventory(cwd),
+		isolated: isolatedSurface.inventory,
 		recover: (cwd) => isolatedSurface.recover(cwd),
 		async inspectInTab(root, id, ctx, current) {
 			const notices = await isolatedSurface.inspect(root, id);
@@ -218,7 +218,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			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.");
 			const role = loadRoles().find((candidate) => candidate.name === "scout");
-			if (!role || roleCanWrite(role)) throw new Error("Status inspection requires a configured read-only scout Role.");
+			if (!role || !roleIsReadOnlyScout(role)) throw new Error("Status inspection requires a configured read-only scout Role without extensions or MCP servers.");
 			const prepared = prepareRoleLaunch(pi, ctx, { role, task: DELEGATE_TASK, modelClass: "fast" });
 			const herdr = createDirectHerdr(pi, ctx.cwd, currentPolicy().childIdleMs);
 			const controller = new AbortController();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "22.2.3",
+  "version": "23.0.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",