@henryqw/pi-subagent 27.4.3 → 27.4.5

package/README.md

@@ -13,11 +13,7 @@ pi install npm:@henryqw/pi-task-models
 pi install npm:@henryqw/pi-subagent
 ```
 
-Run `/task-models` and configure the `fast`, `balanced`, `frontier`, and `fav` routes you use. Direct writer termination proof requires native `lsof`.
-
-### Upgrade from 26.x
-
-Version 27.0.0 requires direct tasks to declare `access` and rejects unknown Role frontmatter keys. The library replaces `loadRoles` with `loadRoleCatalog` and `findRole`. Read [Migrate from 26.x to 27.0.0](./docs/migration.md).
+Configure the profiles that your Roles use in `/task-models`. Direct writer termination proof requires native `lsof`.
 
 ## Works with
 
@@ -48,7 +44,7 @@ Commands and UI are for you. Tools and the packaged skill are for Main, except `
 | Direct status widget (`D`) | ui | Show direct references, names, Role badges, status, routes, elapsed time, measured task tokens, and tool activity in the TUI. |
 | Isolated status widget (`I`) | ui | Show recorded task state, Role/model-class badges, and retained workspaces in the TUI. Readiness does not mean promotion. |
 
-`delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only. Main must make these decisions visibly; `codemode` scripts can call only `subagent_status`. Delegation and continuation tools use plain-object parameter schemas, including for providers that omit root-union tools. Each mode and action still requires its exact arguments.
+`delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only. Main must make these decisions visibly; `codemode` scripts can call only `subagent_status`.
 
 ### Direct workflow
 
@@ -76,9 +72,7 @@ Every task requires `access: "read"` or `access: "write"`. Declare `write` for f
 
 Read requests run parallel tasks up to `maxSubagents`. Chains run in order, replace literal `{previous}` with the preceding successful answer, and stop on failure. Any `write` task makes the whole request serial and reserves checkout admission until all owned workers stop.
 
-Direct writes change Main's checkout immediately, including dirty checkouts. They have no automatic checks, rollback, or isolated integration guarantee. Specify permitted paths, actions, and exclusions. Preserve unrelated edits and staged changes; authorize commits and external actions explicitly.
-
-While admission is held, competing direct writers and Main writes fail. A direct writer also cannot start during a Main call that can write, including Bash or nested `codemode` writes. Main calls do not block each other; reads never wait. Use isolated mode to keep Main free to write.
+Direct writes change Main's checkout immediately, including dirty checkouts, and have no automatic checks or rollback. Preserve unrelated edits. See [Direct contract](./docs/orchestration.md#direct-contract) for write scope and checkout-admission rules.
 
 Tasks in write requests must return one JSON completion object:
 
@@ -94,6 +88,8 @@ To continue a finished worker, add `"continueFrom": "D7.1"` with the same `role`
 
 ### Isolated workflow
 
+![Isolated workers commit checked candidates; Main stages ready work while siblings run, advances dependents, validates the combined tip, and explicitly promotes](./docs/orchestration-architecture.svg)
+
 Use isolated mode for checked implementation. An isolated request has one durable ID, one goal, and 1 to 8 text or changeset tasks:
 
 ```json
@@ -120,13 +116,14 @@ Use isolated mode for checked implementation. An isolated request has one durabl
 
 Workers use Main's pinned committed branch, HEAD, and tree, not staged, unstaged, or untracked edits. Branch or HEAD changes block new waves. Candidates must be committed with no tracked or untracked changes. Ignored generated files permit candidacy but prevent automatic cleanup.
 
-1. Start the request and keep its durable ID. Main can work or end its turn without polling.
-2. Inspect ready candidates with `subagent_status`. Main can stage exact candidates while siblings run and resolve conflicts there.
-3. Use `subagent_integrate advance` for dependents on a staged snapshot.
-4. After the wave settles, validate the combined integration tip with final checks and any final judgment.
-5. Explicitly promote passing work into unchanged, clean Main.
+Keep the durable ID; Main can work or end its turn without polling. Inspect ready candidates with `subagent_status`.
+
+- `subagent_stage` stages exact candidates while siblings run; resolve conflicts in the integration checkout.
+- `subagent_integrate advance` runs dependents on a staged snapshot.
+- `subagent_integrate validate` checks the combined integration tip after the wave settles, with final checks and any final judgment.
+- `subagent_integrate promote` explicitly promotes passing work.
 
-Checks and judgments bind to exact Git identities. Staging, combined validation, and promotion require clean Main at the pinned identity. Changed identities, conflicts, or uncertain outcomes block promotion and preserve evidence. A definitive combined check or review failure permits one committed integration correction and another validation.
+Readiness requires preliminary checks and any task `judgment`; it does not permit promotion. Checks and judgments bind to exact Git identities. Staging, combined validation, and promotion require unchanged, clean Main at the pinned identity. Changed identities, conflicts, or uncertain outcomes block promotion and preserve evidence. A definitive combined check or review failure permits one committed integration correction, recorded with `subagent_integrate correct`, and another validation.
 
 The extension sends follow-ups when a candidate becomes ready, a worker needs attention, and the wave finishes. A missed follow-up does not authorize replay. Read [Isolated contract](./docs/orchestration.md#isolated-contract) and [Exact integration actions](./docs/orchestration.md#exact-integration-actions) for graph, judgment, revision, refresh, and release details.
 
@@ -134,9 +131,7 @@ The extension sends follow-ups when a candidate becomes ready, a worker needs at
 
 Open `/subagent` to browse direct work on this session branch and isolated requests in the current canonical Git checkout, including other sessions. **Refresh** reloads saved status without recovery or mutation. Invalid state IDs stay preserved with a warning. Direct recovery remains available outside Git or without isolated inventory.
 
-**Inspect status and recovery** opens a separate unfocused Herdr tab using the configured `scout` Role and `fast` route. It requires a Herdr-managed pane. The model receives bounded saved status, including retained paths, but not raw launch environment or session transcripts. Its analysis stays in that tab and does not start a Main turn. Missing Herdr, Role, or route fails without changing the request; Main can use `subagent_status` instead.
-
-For locally active unsealed changesets, **Send follow-up instructions** queues a revision. **Edit queued instructions** withdraws all pending instructions before opening the editor; cancel leaves them removed. Already-claimed instructions cannot be recalled. Submission queues one replacement, and late submissions can fail after sealing. Read [Inspect and revise active work](./docs/orchestration.md#inspect-and-revise-active-work) before editing queued instructions.
+Inspection needs a Herdr pane, the configured `scout` Role, and the `fast` route. If it cannot start, the request stays unchanged; Main can use `subagent_status` to read state. See [Inspect and revise active work](./docs/orchestration.md#inspect-and-revise-active-work) for inspection and follow-up details.
 
 See [Status widgets](./docs/orchestration.md#status-widgets) for reference numbering, token counts, and activity metrics, and [Choose a delegation mode](./docs/orchestration.md#choose-a-delegation-mode) for routing guidance.
 

package/dist/direct-herdr.d.ts

@@ -32,6 +32,8 @@ export declare function directSessionUsage(jsonl: string, prompt: string): {
 };
 /** The last `maxChars` of assistant text in the exact prompt's turn; ignores a partial trailing entry. */
 export declare function directPartialText(jsonl: string, prompt: string, maxChars: number): string | undefined;
+/** One reader per handle; only complete, valid lines advance the byte offset. */
+export declare function createDirectSessionReader(sessionFile: string, prompt: string): Pick<DirectHandle, "usageTokens" | "partialText" | "activity">;
 /** `turn` is the prompt's random turn identity; it proves which session turn a record owns.
  * `workspaceId` and `cwd` bind the record to its launching Herdr workspace and checkout. */
 export type DirectTab = Pick<DirectHandle, "name" | "tabId" | "paneId" | "sessionFile"> & {

package/dist/direct-herdr.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { readFile, mkdtemp, stat, writeFile } from "node:fs/promises";
+import { open, readFile, mkdtemp, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -122,99 +122,150 @@ export function exactDirectAnswer(jsonl, prompt, maxBytes = ANSWER_LIMIT, requir
         throw new Error(`Direct task reported ${completion.outcome}: ${completion.answer}`);
     return completion.answer;
 }
-// Ignore a partial trailing JSONL entry while the child is writing it.
-export function directSessionUsage(jsonl, prompt) {
-    let active = false;
-    let total = 0;
-    let observed = false;
-    const pending = new Map();
-    let latest;
-    for (const line of jsonl.split("\n")) {
+class DirectSessionState {
+    active = false;
+    total = 0;
+    observed = false;
+    pending = new Map();
+    latest;
+    texts = [];
+    prompt;
+    constructor(prompt) { this.prompt = prompt; }
+    consume(line) {
         if (!line.trim())
-            continue;
+            return true;
         let entry;
         try {
             entry = JSON.parse(line);
         }
         catch {
-            break;
+            return false;
         }
         if (!entry || entry.type !== "message" || !entry.message || typeof entry.message !== "object")
-            continue;
+            return true;
         const message = entry.message;
         if (message.role === "user") {
-            active = Array.isArray(message.content) && message.content.length === 1
-                && message.content[0]?.text === prompt;
-            if (active) {
-                total = 0;
-                observed = false;
-                pending.clear();
-                latest = undefined;
+            this.active = Array.isArray(message.content) && message.content.length === 1
+                && message.content[0]?.text === this.prompt;
+            if (this.active) {
+                this.total = 0;
+                this.observed = false;
+                this.pending.clear();
+                this.latest = undefined;
+                this.texts = [];
             }
         }
-        else if (active && message.role === "assistant") {
+        else if (this.active && message.role === "assistant") {
             if (message.usage && typeof message.usage === "object") {
                 const usage = message.usage;
                 const values = [usage.input, usage.output];
                 if (values.every((value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0)) {
-                    total += values.reduce((sum, value) => sum + value, 0);
-                    observed = true;
+                    this.total += values.reduce((sum, value) => sum + value, 0);
+                    this.observed = true;
                 }
             }
             if (Array.isArray(message.content))
                 for (const part of message.content) {
                     if (part?.type === "toolCall" && typeof part.id === "string" && typeof part.name === "string") {
-                        pending.set(part.id, part.name);
+                        this.pending.set(part.id, part.name);
+                    }
+                    else if (part?.type === "text" && typeof part.text === "string" && part.text.trim()) {
+                        this.texts.push(part.text);
                     }
                 }
         }
-        else if (active && message.role === "toolResult" && typeof message.toolCallId === "string") {
-            const name = pending.get(message.toolCallId);
-            if (name === undefined)
-                continue;
-            pending.delete(message.toolCallId);
-            latest = { name };
-            if (typeof message.durationMs === "number" && Number.isFinite(message.durationMs) && message.durationMs >= 0) {
-                latest.durationMs = message.durationMs;
+        else if (this.active && message.role === "toolResult" && typeof message.toolCallId === "string") {
+            const name = this.pending.get(message.toolCallId);
+            if (name !== undefined) {
+                this.pending.delete(message.toolCallId);
+                this.latest = { name };
+                if (typeof message.durationMs === "number" && Number.isFinite(message.durationMs) && message.durationMs >= 0) {
+                    this.latest.durationMs = message.durationMs;
+                }
             }
         }
+        return true;
+    }
+    usage() {
+        return { tokens: this.observed ? this.total : undefined,
+            activity: this.pending.size || this.latest ? { pending: [...this.pending.values()], latest: this.latest } : undefined };
+    }
+    partialText(maxChars) {
+        const chars = Array.from(this.texts.join("\n").trim());
+        if (!chars.length)
+            return undefined;
+        return chars.length <= maxChars ? chars.join("") : `…${chars.slice(-maxChars).join("")}`;
     }
-    return { tokens: observed ? total : undefined,
-        activity: pending.size || latest ? { pending: [...pending.values()], latest } : undefined };
+}
+function parseDirectSession(jsonl, prompt) {
+    const state = new DirectSessionState(prompt);
+    for (const line of jsonl.split("\n"))
+        if (!state.consume(line))
+            break;
+    return state;
+}
+// Ignore a partial trailing JSONL entry while the child is writing it.
+export function directSessionUsage(jsonl, prompt) {
+    return parseDirectSession(jsonl, prompt).usage();
 }
 /** The last `maxChars` of assistant text in the exact prompt's turn; ignores a partial trailing entry. */
 export function directPartialText(jsonl, prompt, maxChars) {
-    let active = false;
-    let texts = [];
-    for (const line of jsonl.split("\n")) {
-        if (!line.trim())
-            continue;
-        let entry;
+    return parseDirectSession(jsonl, prompt).partialText(maxChars);
+}
+/** One reader per handle; only complete, valid lines advance the byte offset. */
+export function createDirectSessionReader(sessionFile, prompt) {
+    let offset = 0;
+    let previous;
+    let state = new DirectSessionState(prompt);
+    let lastUsage = {};
+    let reading;
+    const read = async () => {
+        const file = await open(sessionFile, "r");
         try {
-            entry = JSON.parse(line);
-        }
-        catch {
-            break;
-        }
-        if (!entry || entry.type !== "message" || !entry.message || typeof entry.message !== "object")
-            continue;
-        const message = entry.message;
-        if (message.role === "user") {
-            active = Array.isArray(message.content) && message.content.length === 1
-                && message.content[0]?.text === prompt;
-            if (active)
-                texts = [];
+            const info = await file.stat();
+            if (info.size > SESSION_LIMIT) {
+                previous = info;
+                return false;
+            }
+            if (previous && (info.dev !== previous.dev || info.ino !== previous.ino || info.size < previous.size
+                || (info.size === previous.size && (info.mtimeMs !== previous.mtimeMs || info.ctimeMs !== previous.ctimeMs)))) {
+                offset = 0;
+                state = new DirectSessionState(prompt);
+            }
+            previous = info;
+            const buffer = Buffer.alloc(info.size - offset);
+            let length = 0;
+            while (length < buffer.length) {
+                const { bytesRead } = await file.read({ buffer, offset: length, length: buffer.length - length, position: offset + length });
+                if (!bytesRead)
+                    break;
+                length += bytesRead;
+            }
+            let start = 0;
+            for (let end = buffer.indexOf(10); end >= 0 && end < length; end = buffer.indexOf(10, start)) {
+                if (!state.consume(buffer.toString("utf8", start, end)))
+                    break;
+                offset += end + 1 - start;
+                start = end + 1;
+            }
+            return true;
         }
-        else if (active && message.role === "assistant" && Array.isArray(message.content)) {
-            for (const part of message.content)
-                if (part?.type === "text" && typeof part.text === "string" && part.text.trim())
-                    texts.push(part.text);
+        finally {
+            await file.close();
         }
-    }
-    const chars = Array.from(texts.join("\n").trim());
-    if (!chars.length)
-        return undefined;
-    return chars.length <= maxChars ? chars.join("") : `…${chars.slice(-maxChars).join("")}`;
+    };
+    // Timer samples and failure evidence can request the same file at the same time.
+    const sample = () => reading ??= read().finally(() => { reading = undefined; });
+    return {
+        get activity() { return lastUsage.activity; },
+        async usageTokens() {
+            lastUsage = await sample() ? state.usage() : {};
+            return lastUsage.tokens;
+        },
+        async partialText(maxChars) {
+            return await sample() ? state.partialText(maxChars) : undefined;
+        },
+    };
 }
 export class DirectAllocationError extends Error {
     allocation;
@@ -371,28 +422,12 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                 const state = inspect(accepted, "agent_prompted", name, paneId, tabId);
                 if (state === "blocked" || state === "unknown")
                     throw new Error(`Herdr agent became ${state}; inspect it before retrying.`);
-                let lastUsageSize = -1;
-                let lastUsage = {};
+                const session = createDirectSessionReader(sessionFile, prompt);
                 return {
                     name, tabId, paneId, sessionFile, prompt,
-                    get activity() { return lastUsage.activity; },
-                    async usageTokens() {
-                        const info = await stat(sessionFile);
-                        if (info.size > SESSION_LIMIT) {
-                            lastUsage = {};
-                            return undefined;
-                        }
-                        if (info.size !== lastUsageSize) {
-                            lastUsage = directSessionUsage(await readFile(sessionFile, "utf8"), prompt);
-                            lastUsageSize = info.size;
-                        }
-                        return lastUsage.tokens;
-                    },
-                    async partialText(maxChars) {
-                        if ((await stat(sessionFile)).size > SESSION_LIMIT)
-                            return undefined;
-                        return directPartialText(await readFile(sessionFile, "utf8"), prompt, maxChars);
-                    },
+                    get activity() { return session.activity; },
+                    usageTokens: session.usageTokens,
+                    partialText: session.partialText,
                     async answer(maxBytes) {
                         const readAnswer = async () => {
                             const info = await stat(sessionFile);