@hcflabs/pi-subagent 28.2.1 → 28.2.3

package/CONTEXT.md

@@ -28,6 +28,10 @@ A display and continuation reference for one recorded direct worker, such as `D7
 **Continued worker**:
 A new direct worker that resumes a finished worker's saved Pi conversation in a new tab with a new Direct reference.
 
+**Final turn**:
+The latest assistant turn on the exact branch of a worker prompt that Pi did not omit, with a `stop`, `length`, `error`, or `aborted` reason. Only a `stop` Final turn is a success. Pi omits a retried or recovered turn with a `context_edit` entry. The worker session decides completion, not the Herdr agent state.
+_Avoid_: last message, idle state
+
 **Checkout admission**:
 The exclusive permission held by a direct write request that prevents Main and other direct writers from writing to the shared checkout. A request with Repository targets holds the checkout of each target. From a non-Git parent directory, a Main call that can write covers the checkout of every Repository target in it. It remains held until worker termination is proven; read classification is not a sandbox.
 

package/README.md

@@ -238,7 +238,7 @@ Package-owned: `~/.pi/agent/config/pi-subagent/config.json`. Missing files silen
 | `maxTurns` | Provider turns per child | Safe integer ≥ 1 | `50` |
 | `maxTokens` | Optional tokens per child | Safe integer ≥ 1 | Unlimited |
 | `maxCorrections` | Same-worker corrections per isolated request, including Main's `revise` and `retry` corrections | Safe integer ≥ 0 | `1` |
-| `timeout.idleMinutes` | Direct worker and ephemeral child idle timeout | Positive; within Node's timer range | `10` |
+| `timeout.idleMinutes` | Idle timeout for direct workers, settled isolated workers, and ephemeral children | Positive; within Node's timer range | `10` |
 | `timeout.maxMinutes` | Ephemeral child hard runtime | Greater than idle; within Node's timer range | `30` |
 | `roleDefaults` | Shared resources for built-in and user Roles | Object with `extensions`, `tools`, or `skills` arrays; same validation as Role fields | — |
 | `repoSuites` | Full suite for isolated changesets in one repository | Object keyed by the absolute path of the primary checkout. Each value is `{ "command": "<executable>", "args": [...] }` | — |

package/dist/direct-herdr.d.ts

@@ -1,5 +1,6 @@
 import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { PreparedRoleLaunch, ResolvedRoleLaunch } from "./index.ts";
+import { type SessionToolActivity, type SessionUsage } from "./session-turn.ts";
 /** The Role tool that reads a file-backed task packet, or undefined for an inline packet; throws when no tool can read it in full. */
 export declare function directTaskReader(task: string, tools: readonly string[]): "read" | "bash" | undefined;
 /** A prompt is accepted only with the exact pane, agent, cwd and turn identity. */
@@ -24,25 +25,12 @@ export interface DirectHandle {
     focus(): Promise<void>;
     cancel(): Promise<void>;
 }
-export declare function exactDirectTerminalTurn(jsonl: string, prompt: string): boolean;
-/** Refuse continuation unless the saved session's exact recorded turn is terminal and no later user turn exists. */
-export declare function assertSettledDirectSession(sessionFile: string, turn: string): Promise<void>;
-export declare function exactDirectAnswer(jsonl: string, prompt: string, requireSuccess?: boolean): string;
-/** Measured from one session read; each field is absent when no turn record carried it. */
-export interface DirectUsage {
-    tokens?: number;
-    /** Sum of assistant `usage.cost.total`. */
-    cost?: number;
-}
-export interface DirectToolActivity {
-    pending: string[];
-    latest?: {
-        name: string;
-        durationMs?: number;
-    };
-}
-/** One reader per handle; only complete, valid lines advance the byte offset. */
-export declare function createDirectSessionReader(sessionFile: string, prompt: string): Pick<DirectHandle, "usage" | "partialText" | "activity">;
+/** Selects the user prompt text that carries the exact turn identity. */
+export declare const directTurnPrompt: (turn: string) => (text: string) => boolean;
+/** Returns the answer of a successful Final turn. A write-access answer must be a succeeded JSON completion object. */
+export declare function directCompletionAnswer(text: string, requireSuccess: boolean): string;
+export type DirectUsage = SessionUsage;
+export type DirectToolActivity = SessionToolActivity;
 /** `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 { open, readFile, mkdtemp, stat, writeFile } from "node:fs/promises";
+import { open, mkdtemp, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -8,8 +8,11 @@ import { DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
 import { createHerdrClient, hasHerdrErrorCode, herdrCommandFailure, startPiAgent } from "@hcflabs/pi-herdr";
 import { utf8Prefix } from "./ephemeral.js";
 import { assertPrivateLease, PI_SUBAGENT_PROCESS_LEASE, scanProcessLease } from "./process-lease.js";
+import { createSessionActivityReader, readSessionTurn, SESSION_LIMIT } from "./session-turn.js";
 const OPERATION_MS = 30_000;
-const SESSION_LIMIT = 16 * 1024 * 1024;
+/** The longest Herdr wait while the agent is idle or done and the session has no Final turn. */
+const SETTLED_POLL_MS = 1000;
+const WAIT_STATES = ["working", "idle", "done", "blocked", "unknown"];
 // Leave room for boundary instructions below Linux's 128 KiB per-argument limit.
 const INLINE_TASK_BYTES = 64 * 1024;
 const DIRECT_OUTCOMES = ["succeeded", "failed", "blocked"];
@@ -42,80 +45,11 @@ const result = (value, type) => {
         throw new Error(`Herdr returned an unexpected ${type} response.`);
     return response;
 };
-function exactFinalTurn(jsonl, prompt) {
-    const lines = jsonl.trimEnd().split("\n");
-    let userId;
-    let final;
-    let finalId;
-    const parents = new Map();
-    for (const line of lines) {
-        const entry = object(JSON.parse(line), "session entry");
-        if (entry.type === "session")
-            continue;
-        const id = field(entry.id, "session entry id");
-        // Non-message entries also link the exact session branch.
-        if (typeof entry.parentId === "string")
-            parents.set(id, entry.parentId);
-        if (entry.type !== "message")
-            continue;
-        const message = object(entry.message, "session message");
-        if (message.role === "user" && Array.isArray(message.content)
-            && message.content.length === 1 && object(message.content[0], "user content").text === prompt) {
-            userId = id;
-            final = undefined;
-            finalId = undefined;
-        }
-        else if (userId && message.role === "user") {
-            throw new Error("Pi session contains an unexpected user turn after direct delegation.");
-        }
-        else if (userId && message.role === "assistant") {
-            final = message;
-            finalId = id;
-        }
-    }
-    let ancestor = finalId;
-    const seen = new Set();
-    while (ancestor && ancestor !== userId && !seen.has(ancestor)) {
-        seen.add(ancestor);
-        ancestor = parents.get(ancestor);
-    }
-    return userId && ancestor === userId ? final : undefined;
-}
-export function exactDirectTerminalTurn(jsonl, prompt) {
-    const reason = exactFinalTurn(jsonl, prompt)?.stopReason;
-    return reason === "stop" || reason === "error" || reason === "aborted";
-}
 const turnSuffix = (turn) => `\n\nTurn identity: ${turn}`;
-/** Refuse continuation unless the saved session's exact recorded turn is terminal and no later user turn exists. */
-export async function assertSettledDirectSession(sessionFile, turn) {
-    const info = await stat(sessionFile).catch((error) => {
-        throw new Error(`Saved Pi session ${sessionFile} is missing or unreadable`, { cause: error });
-    });
-    if (info.size > SESSION_LIMIT)
-        throw new Error(`Saved Pi session ${sessionFile} exceeds 16 MiB`);
-    const jsonl = await readFile(sessionFile, "utf8");
-    let prompt;
-    for (const line of jsonl.trimEnd().split("\n")) {
-        const entry = JSON.parse(line);
-        const message = entry?.type === "message" ? entry.message : undefined;
-        const text = message?.role === "user" && Array.isArray(message.content) && message.content.length === 1
-            ? message.content[0]?.text : undefined;
-        if (typeof text === "string" && text.endsWith(turnSuffix(turn)))
-            prompt = text;
-    }
-    if (prompt === undefined || !exactDirectTerminalTurn(jsonl, prompt)) {
-        throw new Error(`Saved Pi session ${sessionFile} has no terminal final turn for the recorded prompt; the worker may still be running`);
-    }
-}
-export function exactDirectAnswer(jsonl, prompt, requireSuccess = false) {
-    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) => {
-        const content = object(part, "assistant content");
-        return content.type === "text" && typeof content.text === "string" ? [content.text] : [];
-    }).join("\n");
+/** Selects the user prompt text that carries the exact turn identity. */
+export const directTurnPrompt = (turn) => (text) => text.endsWith(turnSuffix(turn));
+/** Returns the answer of a successful Final turn. A write-access answer must be a succeeded JSON completion object. */
+export function directCompletionAnswer(text, requireSuccess) {
     if (!text.trim())
         throw new Error("Pi persisted an empty final answer.");
     if (!requireSuccess)
@@ -136,141 +70,6 @@ export function exactDirectAnswer(jsonl, prompt, requireSuccess = false) {
         throw new Error(`Direct task reported ${completion.outcome}: ${completion.answer}`);
     return completion.answer;
 }
-class DirectSessionState {
-    active = false;
-    total = 0;
-    observed = false;
-    cost;
-    pending = new Map();
-    latest;
-    texts = [];
-    prompt;
-    constructor(prompt) { this.prompt = prompt; }
-    consume(line) {
-        if (!line.trim())
-            return true;
-        let entry;
-        try {
-            entry = JSON.parse(line);
-        }
-        catch {
-            return false;
-        }
-        if (!entry || entry.type !== "message" || !entry.message || typeof entry.message !== "object")
-            return true;
-        const message = entry.message;
-        if (message.role === "user") {
-            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.cost = undefined;
-                this.pending.clear();
-                this.latest = undefined;
-                this.texts = [];
-            }
-        }
-        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)) {
-                    this.total += values.reduce((sum, value) => sum + value, 0);
-                    this.observed = true;
-                }
-                const cost = usage.cost?.total;
-                if (typeof cost === "number" && Number.isFinite(cost) && cost >= 0)
-                    this.cost = (this.cost ?? 0) + cost;
-            }
-            if (Array.isArray(message.content))
-                for (const part of message.content) {
-                    if (part?.type === "toolCall" && typeof part.id === "string" && typeof part.name === "string") {
-                        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 (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, cost: this.cost,
-            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("")}`;
-    }
-}
-/** 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 {
-            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;
-        }
-        finally {
-            await file.close();
-        }
-    };
-    // 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 usage() {
-            lastUsage = await sample() ? state.usage() : {};
-            return { tokens: lastUsage.tokens, cost: lastUsage.cost };
-        },
-        async partialText(maxChars) {
-            return await sample() ? state.partialText(maxChars) : undefined;
-        },
-    };
-}
 export class DirectAllocationError extends Error {
     allocation;
     constructor(allocation, cause) {
@@ -371,6 +170,8 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                 sessionFile = join(sessionDir, "session.jsonl");
                 leasePath = join(sessionDir, "process.lease");
                 await writeFile(leasePath, "", { flag: "wx", mode: 0o600 });
+                // Pi initializes an existing empty session in place and keeps its private mode.
+                await (await open(sessionFile, "wx", 0o600)).close();
             }
             const turn = randomBytes(16).toString("hex");
             if (reader) {
@@ -432,18 +233,21 @@ 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.`);
-                const session = createDirectSessionReader(sessionFile, prompt);
+                const session = createSessionActivityReader(sessionFile, prompt);
                 return {
                     name, tabId, paneId, sessionFile, prompt,
                     get activity() { return session.activity; },
                     usage: session.usage,
                     partialText: session.partialText,
                     async answer(maxBytes) {
-                        const readAnswer = async () => {
-                            const info = await stat(sessionFile);
-                            if (info.size > SESSION_LIMIT)
-                                throw new Error(`Pi session in tab ${tabId} exceeds 16 MiB; inspect ${sessionFile} for recovery.`);
-                            const text = exactDirectAnswer(await readFile(sessionFile, "utf8"), prompt, requireSuccess);
+                        // The session decides completion. Herdr idle or done only starts a read.
+                        const settledAnswer = async () => {
+                            const final = await readSessionTurn(sessionFile, prompt, { signal });
+                            if (final.state === "absent" || final.state === "running")
+                                return undefined;
+                            if (final.state === "failed")
+                                throw new Error(`${final.failure}. Inspect tab ${tabId} and ${sessionFile} before retrying.`);
+                            const text = directCompletionAnswer(final.answer, requireSuccess);
                             const bytes = Buffer.byteLength(text, "utf8");
                             if (bytes <= maxBytes)
                                 return { text, inline: text };
@@ -453,18 +257,6 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                             await writeFile(file, text, { flag: "wx", mode: 0o600 });
                             return { text, answerFile: file, inline: `${utf8Prefix(text, maxBytes)}\n\n[Answer truncated to ${maxBytes} of ${bytes} bytes; read the full answer at ${file}]` };
                         };
-                        const maybeAnswer = async () => {
-                            try {
-                                return await readAnswer();
-                            }
-                            catch (error) {
-                                if (signal.aborted || !(error instanceof Error)
-                                    || (!('code' in error && error.code === "ENOENT")
-                                        && !error.message.includes("did not persist an exact successful final answer")))
-                                    throw error;
-                                return undefined;
-                            }
-                        };
                         let current = state;
                         let deadline = Date.now() + idleMs;
                         let sessionSize = 0;
@@ -481,10 +273,14 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                                 deadline = Date.now() + idleMs;
                             }
                         };
-                        while (current === "working" || current === "idle") {
-                            // A turn may finish before observation begins (or between waits).
-                            if (current === "idle") {
-                                const answer = await maybeAnswer();
+                        for (;;) {
+                            if (current !== "working" && current !== "idle" && current !== "done") {
+                                throw new Error(`Herdr agent in tab ${tabId} became ${current}; inspect it before retrying.`);
+                            }
+                            // A turn can finish before observation starts or between waits.
+                            // Pi can also omit an error turn and retry it while Herdr reports done.
+                            if (current !== "working") {
+                                const answer = await settledAnswer();
                                 if (answer !== undefined)
                                     return answer;
                             }
@@ -493,14 +289,12 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                             if (remaining <= 0)
                                 throw new Error(`Herdr agent in tab ${tabId} made no progress for ${idleMs}ms; inspect ${sessionFile} before retrying.`);
                             const args = ["agent", "wait", name,
-                                ...(current === "idle" ? ["--until", "working"] : ["--until", "idle"]),
-                                "--until", "done", "--until", "blocked", "--until", "unknown",
-                                "--timeout", String(Math.max(1, Math.min(current === "idle" ? 1000 : OPERATION_MS - 1000, remaining)))];
+                                ...WAIT_STATES.filter((until) => until !== current).flatMap((until) => ["--until", until]),
+                                "--timeout", String(Math.max(1, Math.min(current === "working" ? OPERATION_MS - 1000 : SETTLED_POLL_MS, remaining)))];
                             const waited = await herdr.exec(args, options(signal));
                             if (waited.code !== 0 || waited.killed) {
-                                if (!waited.killed && hasHerdrErrorCode(waited, "timeout")) {
+                                if (!waited.killed && hasHerdrErrorCode(waited, "timeout"))
                                     continue;
-                                }
                                 throw new Error(herdrCommandFailure(args, waited));
                             }
                             const next = inspect(JSON.parse(waited.stdout), "agent_info", name, paneId, tabId);
@@ -508,9 +302,6 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                                 deadline = Date.now() + idleMs;
                             current = next;
                         }
-                        if (current !== "done")
-                            throw new Error(`Herdr agent in tab ${tabId} became ${current}; inspect it before retrying.`);
-                        return readAnswer();
                     },
                     async focus() {
                         // A reused pane ID must not receive focus: the agent identity must match the launch first.

package/dist/herdr-runtime.d.ts

@@ -23,6 +23,8 @@ export interface HerdrHostRuntimeOptions {
     leaseDirectory?: string;
     lsofCommand?: string;
     executionBudget?: () => Omit<EphemeralSubagentExecutionBudget, "startedAt">;
+    /** The time that a settled worker can show a running session without session growth. The default is 10 minutes. */
+    settledIdleMs?: () => number;
 }
 export declare function workspaceLabel(attempt: TaskAttempt): string;
 export declare class HerdrHostRuntime implements HostRuntime {
@@ -37,6 +39,7 @@ export declare class HerdrHostRuntime implements HostRuntime {
     private readonly leaseDirectory;
     private readonly lsofCommand;
     private readonly executionBudget?;
+    private readonly settledIdleMs;
     constructor(options: HerdrHostRuntimeOptions);
     /**
      * Fail-closed Herdr caller/capability gate. This method creates no state or host resource.
@@ -127,9 +130,7 @@ export declare class HerdrHostRuntime implements HostRuntime {
     private removeLeaseArtifacts;
     private assertPrivateLeaseDirectories;
     private workerSessionFile;
-    private sessionFileExists;
-    private privateSessionFile;
-    private workerTurnFinished;
+    private workerSessionTurn;
     private removeWorkerSessionFile;
     private assertLeasePath;
     private scanLease;

package/dist/herdr-runtime.js

@@ -10,7 +10,7 @@ import { buildChangesetTaskPrompt, withTransientLaunch, } from "./runner.js";
 import { runProcess as defaultRunProcess } from "./process.js";
 import { EXECUTION_BUDGET_ENV } from "./ephemeral.js";
 import { assertPrivateLease, PI_SUBAGENT_PROCESS_LEASE, scanProcessLease } from "./process-lease.js";
-import { exactDirectTerminalTurn } from "./direct-herdr.js";
+import { readPrivateSession, readSessionTurn } from "./session-turn.js";
 import { READABLE_BRANCH_PATTERN } from "./worktree.js";
 const MIN_HERDR_VERSION = [0, 9, 3];
 const MIN_HERDR_PROTOCOL = 22;
@@ -19,10 +19,11 @@ const LSOF_OPERATION_CAP_MS = 3_000;
 const PROCESS_INSPECTION_CAP_MS = 3_000;
 const GIT_INSPECTION_CAP_MS = 30_000;
 const STALLED_PROMPT_POLL_MS = 250;
+/** The default time that a settled worker can show a running session without session growth. */
+const DEFAULT_SETTLED_IDLE_MS = 600_000;
 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 CORRELATION_TOKEN_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
@@ -257,7 +258,9 @@ export class HerdrHostRuntime {
     leaseDirectory;
     lsofCommand;
     executionBudget;
+    settledIdleMs;
     constructor(options) {
+        this.settledIdleMs = options.settledIdleMs ?? (() => DEFAULT_SETTLED_IDLE_MS);
         this.inspectInFlightCandidate = options.inspectInFlightTaskCandidate;
         this.execute = options.runProcess ?? defaultRunProcess;
         this.herdr = createHerdrClient(this.execute);
@@ -888,6 +891,8 @@ export class HerdrHostRuntime {
         });
     }
     async reconcileDeliveredPrompt(input, allocation, context, prompt, promptMayBeInFlight = true) {
+        // A settled worker with a running session can wait for a Pi retry. Session growth resets this bound.
+        let settledRunning;
         for (;;) {
             let lifecycle;
             try {
@@ -906,6 +911,7 @@ export class HerdrHostRuntime {
                 return { outcome: "unknown", diagnostic: "Delivered prompt lifecycle is unknown." };
             }
             if (lifecycle.status === "working") {
+                settledRunning = undefined;
                 try {
                     await this.delay(STALLED_PROMPT_POLL_MS, context.signal);
                 }
@@ -938,22 +944,47 @@ export class HerdrHostRuntime {
                 };
             }
             if (SETTLED_AGENT_STATES.has(lifecycle.status)) {
+                let final;
                 try {
-                    if (await this.workerTurnFinished(allocation, prompt)) {
-                        return inspection.valid && !inspection.clean
-                            ? { outcome: "uncommitted", diagnostic: "Worker finished with uncommitted changes in its owned worktree." }
-                            : { outcome: "blocked", diagnostic: "Worker finished without an exact changed clean committed candidate." };
-                    }
+                    final = await this.workerSessionTurn(allocation, prompt, context.signal);
                 }
                 catch (error) {
-                    return { outcome: "unknown", diagnostic: `Worker session evidence cannot be verified: ${error instanceof SyntaxError ? "malformed JSONL" : safeText(error)}` };
+                    if (this.contextInterrupted(context))
+                        return { outcome: "interrupted", diagnostic: "Delivered prompt reconciliation was interrupted." };
+                    return { outcome: "unknown", diagnostic: `Worker session evidence cannot be verified: ${safeText(error)}` };
+                }
+                if (final.state === "succeeded" || final.state === "failed") {
+                    return inspection.valid && !inspection.clean
+                        ? { outcome: "uncommitted", diagnostic: "Worker finished with uncommitted changes in its owned worktree." }
+                        : { outcome: "blocked", diagnostic: "Worker finished without an exact changed clean committed candidate." };
+                }
+                // A running session has no Final turn yet. Pi can omit an error turn and retry it while Herdr reports a settled state.
+                if (final.state === "running") {
+                    let size;
+                    try {
+                        size = (await lstat(this.workerSessionFile(allocation.leasePath, allocation.token))).size;
+                    }
+                    catch (error) {
+                        return { outcome: "unknown", diagnostic: `Worker session evidence cannot be verified: ${safeText(error)}` };
+                    }
+                    const now = this.now();
+                    if (!settledRunning || size !== settledRunning.size)
+                        settledRunning = { since: now, size };
+                    else if (now - settledRunning.since >= this.settledIdleMs()) {
+                        return {
+                            outcome: "unknown",
+                            diagnostic: await this.diagnostic(allocation, context, `Settled worker session made no progress for ${this.settledIdleMs()}ms and has no Final turn.`),
+                        };
+                    }
+                }
+                else
+                    settledRunning = undefined;
+                if (final.state === "absent" && !promptMayBeInFlight) {
+                    return {
+                        outcome: "blocked",
+                        diagnostic: await this.diagnostic(allocation, context, "Settled worker did not produce an exact changed clean committed candidate."),
+                    };
                 }
-            }
-            if (!promptMayBeInFlight && SETTLED_AGENT_STATES.has(lifecycle.status)) {
-                return {
-                    outcome: "blocked",
-                    diagnostic: await this.diagnostic(allocation, context, "Settled worker did not produce an exact changed clean committed candidate."),
-                };
             }
             try {
                 await this.delay(STALLED_PROMPT_POLL_MS, context.signal);
@@ -1139,71 +1170,16 @@ export class HerdrHostRuntime {
         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 workerSessionTurn(allocation, prompt, signal) {
+        const final = await readSessionTurn(this.workerSessionFile(allocation.leasePath, allocation.token), prompt, { signal });
+        // A symbolic link in the lease directories can redirect the session path, so evidence needs private directories.
+        if (final.state !== "absent")
+            await this.assertPrivateLeaseDirectories(allocation.leasePath, false);
+        return final;
     }
     async removeWorkerSessionFile(leasePath, token) {
         const path = this.workerSessionFile(leasePath, token);
-        if (await this.privateSessionFile(path) !== undefined)
+        if (await readPrivateSession(path) !== undefined)
             await unlink(path);
     }
     assertLeasePath(path, token) {

package/dist/session-turn.d.ts

@@ -0,0 +1,68 @@
+/** The largest worker session file that a reader accepts. */
+export declare const SESSION_LIMIT: number;
+declare const STOP_REASONS: readonly ["stop", "length", "toolUse", "error", "aborted"];
+type StopReason = typeof STOP_REASONS[number];
+export type FailedStopReason = Exclude<StopReason, "stop" | "toolUse">;
+/** The prompt text, or a test that selects the prompt text of a user entry. */
+export type PromptMatch = string | ((text: string) => boolean);
+/**
+ * The evidence of one worker prompt in its Pi session.
+ * - `absent`: the file or the prompt entry does not exist.
+ * - `running`: the prompt exists, but its branch has no Final turn.
+ * - `succeeded`: the Final turn has the `stop` reason.
+ * - `failed`: the Final turn has a `length`, `error`, or `aborted` reason.
+ */
+export type SessionTurn = {
+    state: "absent";
+} | {
+    state: "running";
+} | {
+    state: "succeeded";
+    stopReason: "stop";
+    answer: string;
+} | {
+    state: "failed";
+    stopReason: FailedStopReason;
+    errorMessage?: string;
+    failure: string;
+};
+export interface SessionTurnOptions {
+    signal?: AbortSignal;
+    /** Test only. Replaces the delay before the confirm read of an `error` Final turn. */
+    settleMs?: number;
+}
+/** Each field is absent when no turn record carried it. */
+export interface SessionUsage {
+    tokens?: number;
+    /** Sum of assistant `usage.cost.total`. */
+    cost?: number;
+}
+export interface SessionToolActivity {
+    pending: string[];
+    latest?: {
+        name: string;
+        durationMs?: number;
+    };
+}
+export interface SessionActivityReader {
+    usage(): Promise<SessionUsage>;
+    /** Bounded assistant text of this prompt so far. This text is failure evidence only, never completion. */
+    partialText(maxChars: number): Promise<string | undefined>;
+    /** Display-only activity from the last usage() sample. */
+    readonly activity?: SessionToolActivity;
+}
+/** Reads a private session file in bounded chunks. Returns undefined for a missing file. */
+export declare function readPrivateSession(path: string): Promise<Buffer | undefined>;
+/**
+ * Reads the Final turn of the exact worker prompt from its private Pi session file.
+ * An `error` Final turn is a failure only when a second read after about 500 ms shows the same unomitted entry.
+ * Throws for a file that is not private, larger than 16 MiB, or malformed, or that has a later user turn.
+ */
+export declare function readSessionTurn(path: string, prompt: PromptMatch, options?: SessionTurnOptions): Promise<SessionTurn>;
+/**
+ * Samples live usage, tool activity, and partial text of the exact prompt.
+ * Each sample parses only the complete lines after the last byte offset.
+ * A replaced, shrunk, or rewritten file starts a new parse from byte 0.
+ */
+export declare function createSessionActivityReader(path: string, prompt: string): SessionActivityReader;
+export {};

package/dist/session-turn.js

@@ -0,0 +1,339 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { setTimeout as sleep } from "node:timers/promises";
+/** The largest worker session file that a reader accepts. */
+export const SESSION_LIMIT = 16 * 1024 * 1024;
+const CHUNK_BYTES = 64 * 1024;
+/** Pi writes the omission of a retried error turn before its retry delay. A second read after this delay finds that omission. */
+const ERROR_SETTLE_MS = 500;
+const ERROR_MESSAGE_CHARS = 500;
+const STOP_REASONS = ["stop", "length", "toolUse", "error", "aborted"];
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const notPrivate = (path) => `Pi session file ${path} is not private, regular, or bounded`;
+const tooLarge = (path) => new Error(`Pi session file ${path} exceeds the 16 MiB limit.`);
+/** Opens a session file only when it is a regular file of the current user with mode 0600 or stricter. Returns undefined for a missing file. */
+async function openPrivateSession(path) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return undefined;
+        if (code === "ELOOP" || code === "EMLINK")
+            throw new Error(`${notPrivate(path)}: it is a symbolic link.`, { cause: error });
+        throw error;
+    }
+    try {
+        const info = await file.stat();
+        const uid = process.getuid?.();
+        if (!info.isFile())
+            throw new Error(`${notPrivate(path)}: it is not a regular file.`);
+        if ((info.mode & 0o077) !== 0 || (uid !== undefined && info.uid !== uid)) {
+            throw new Error(`${notPrivate(path)}: it must belong to the current user and have mode 0600, with no group or other access.`);
+        }
+        if (info.size > SESSION_LIMIT)
+            throw tooLarge(path);
+        return { file, info };
+    }
+    catch (error) {
+        await file.close();
+        throw error;
+    }
+}
+/** Reads a private session file in bounded chunks. Returns undefined for a missing file. */
+export async function readPrivateSession(path) {
+    const opened = await openPrivateSession(path);
+    if (!opened)
+        return undefined;
+    try {
+        const chunks = [];
+        let bytes = 0;
+        for (;;) {
+            // The file can grow after the size check. Read one byte more than the limit to find that growth.
+            const chunk = Buffer.allocUnsafe(Math.min(CHUNK_BYTES, SESSION_LIMIT + 1 - bytes));
+            const { bytesRead } = await opened.file.read(chunk, 0, chunk.length, null);
+            if (!bytesRead)
+                break;
+            chunks.push(chunk.subarray(0, bytesRead));
+            bytes += bytesRead;
+            if (bytes > SESSION_LIMIT)
+                throw tooLarge(path);
+        }
+        return Buffer.concat(chunks, bytes);
+    }
+    finally {
+        await opened.file.close();
+    }
+}
+function parseLine(line, path, lineNumber) {
+    let entry;
+    try {
+        entry = JSON.parse(line);
+    }
+    catch (error) {
+        throw new Error(`Pi session file ${path} has a malformed entry on line ${lineNumber}.`, { cause: error });
+    }
+    if (!isObject(entry) || typeof entry.type !== "string"
+        // A message entry must carry a message object with a role. A broken payload is not evidence.
+        || (entry.type === "message" && (!isObject(entry.message) || typeof entry.message.role !== "string"))) {
+        throw new Error(`Pi session file ${path} has a malformed entry on line ${lineNumber}.`);
+    }
+    return entry;
+}
+const messageOf = (entry) => entry.type === "message" && isObject(entry.message) ? entry.message : undefined;
+function userText(entry) {
+    const message = messageOf(entry);
+    if (message?.role !== "user" || !Array.isArray(message.content) || message.content.length !== 1)
+        return undefined;
+    const part = message.content[0];
+    return isObject(part) && part.type === "text" && typeof part.text === "string" ? part.text : undefined;
+}
+function entryId(entry, path) {
+    if (typeof entry.id !== "string" || !entry.id)
+        throw new Error(`Pi session file ${path} has an entry without an ID.`);
+    return entry.id;
+}
+/** One read of the session text. `finalId` identifies the Final turn entry. */
+function evaluateTurn(text, path, prompt) {
+    const matches = typeof prompt === "string" ? (value) => value === prompt : prompt;
+    // Pi can still write the last line. Only a line that ends with a newline is complete.
+    const lines = text.split("\n").slice(0, -1);
+    const entries = lines.map((line, index) => parseLine(line, path, index + 1)).filter((entry) => entry.type !== "session");
+    let promptIndex = -1;
+    entries.forEach((entry, index) => {
+        const value = userText(entry);
+        if (value !== undefined && matches(value))
+            promptIndex = index;
+    });
+    if (promptIndex < 0)
+        return { turn: { state: "absent" } };
+    if (entries.slice(promptIndex + 1).some((entry) => messageOf(entry)?.role === "user")) {
+        throw new Error(`Pi session file ${path} contains an unexpected user turn after the worker prompt.`);
+    }
+    const byId = new Map();
+    for (const entry of entries)
+        byId.set(entryId(entry, path), entry);
+    // All entry types link the branch. The latest entry is the leaf of the active branch.
+    const promptEntry = entries[promptIndex];
+    const branch = [];
+    const seen = new Set();
+    let current = entries.at(-1);
+    while (current && current !== promptEntry && !seen.has(current)) {
+        seen.add(current);
+        branch.push(current);
+        current = typeof current.parentId === "string" ? byId.get(current.parentId) : undefined;
+    }
+    if (current !== promptEntry)
+        return { turn: { state: "running" } };
+    branch.reverse();
+    // The latest edit for a target on the branch wins. A null replacement omits the target.
+    const edits = new Map();
+    for (const entry of branch) {
+        if (entry.type !== "context_edit")
+            continue;
+        if (typeof entry.targetId !== "string" || !("replacement" in entry)) {
+            throw new Error(`Pi session file ${path} has a malformed context_edit entry.`);
+        }
+        edits.set(entry.targetId, entry.replacement);
+    }
+    let final;
+    for (const entry of branch) {
+        if (messageOf(entry)?.role === "assistant" && edits.get(entryId(entry, path)) !== null)
+            final = entry;
+    }
+    if (!final)
+        return { turn: { state: "running" } };
+    const message = messageOf(final);
+    const reason = message.stopReason;
+    if (!STOP_REASONS.some((known) => known === reason)) {
+        throw new Error(`Pi session file ${path} has an assistant entry with an unknown stop reason.`);
+    }
+    const finalId = entryId(final, path);
+    if (reason === "toolUse")
+        return { turn: { state: "running" }, finalId };
+    if (reason === "stop") {
+        if (!Array.isArray(message.content))
+            throw new Error(`Pi session file ${path} has an assistant entry without content.`);
+        const answer = message.content.flatMap((part) => isObject(part) && part.type === "text" && typeof part.text === "string" ? [part.text] : []).join("\n");
+        return { turn: { state: "succeeded", stopReason: "stop", answer }, finalId };
+    }
+    const stopReason = reason;
+    const detail = typeof message.errorMessage === "string" && message.errorMessage.trim()
+        ? Array.from(message.errorMessage.trim()).slice(0, ERROR_MESSAGE_CHARS).join("") : undefined;
+    return {
+        turn: { state: "failed", stopReason, ...(detail === undefined ? {} : { errorMessage: detail }),
+            failure: `Pi ended the worker turn with stop reason "${stopReason}"${detail === undefined ? "" : `: ${detail}`}` },
+        finalId,
+    };
+}
+async function readTurnOnce(path, prompt) {
+    const data = await readPrivateSession(path);
+    return data === undefined ? { turn: { state: "absent" } } : evaluateTurn(data.toString("utf8"), path, prompt);
+}
+/**
+ * Reads the Final turn of the exact worker prompt from its private Pi session file.
+ * An `error` Final turn is a failure only when a second read after about 500 ms shows the same unomitted entry.
+ * Throws for a file that is not private, larger than 16 MiB, or malformed, or that has a later user turn.
+ */
+export async function readSessionTurn(path, prompt, options = {}) {
+    let read = await readTurnOnce(path, prompt);
+    for (;;) {
+        if (read.turn.state !== "failed" || read.turn.stopReason !== "error")
+            return read.turn;
+        // Pi can omit the error turn and retry it after Herdr reports the agent done.
+        await sleep(options.settleMs ?? ERROR_SETTLE_MS, undefined, options.signal ? { signal: options.signal } : undefined);
+        const next = await readTurnOnce(path, prompt);
+        if (next.turn.state === "failed" && next.turn.stopReason === "error" && next.finalId === read.finalId)
+            return next.turn;
+        read = next;
+    }
+}
+class ActivityState {
+    active = false;
+    total = 0;
+    observed = false;
+    cost;
+    pending = new Map();
+    latest;
+    texts = [];
+    prompt;
+    constructor(prompt) { this.prompt = prompt; }
+    consume(entry) {
+        const message = messageOf(entry);
+        if (!message)
+            return;
+        if (message.role === "user") {
+            this.active = userText(entry) === this.prompt;
+            if (this.active) {
+                this.total = 0;
+                this.observed = false;
+                this.cost = undefined;
+                this.pending.clear();
+                this.latest = undefined;
+                this.texts = [];
+            }
+        }
+        else if (this.active && message.role === "assistant") {
+            if (isObject(message.usage)) {
+                const usage = message.usage;
+                const values = [usage.input, usage.output];
+                if (values.every((value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0)) {
+                    this.total += values.reduce((sum, value) => sum + value, 0);
+                    this.observed = true;
+                }
+                const cost = isObject(usage.cost) ? usage.cost.total : undefined;
+                if (typeof cost === "number" && Number.isFinite(cost) && cost >= 0)
+                    this.cost = (this.cost ?? 0) + cost;
+            }
+            if (Array.isArray(message.content))
+                for (const part of message.content) {
+                    if (!isObject(part))
+                        continue;
+                    if (part.type === "toolCall" && typeof part.id === "string" && typeof part.name === "string") {
+                        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 (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;
+                }
+            }
+        }
+    }
+    usage() {
+        return { tokens: this.observed ? this.total : undefined, cost: this.cost,
+            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("")}`;
+    }
+}
+/**
+ * Samples live usage, tool activity, and partial text of the exact prompt.
+ * Each sample parses only the complete lines after the last byte offset.
+ * A replaced, shrunk, or rewritten file starts a new parse from byte 0.
+ */
+export function createSessionActivityReader(path, prompt) {
+    let offset = 0;
+    let lineNumber = 0;
+    let previous;
+    let state = new ActivityState(prompt);
+    let lastUsage = {};
+    let reading;
+    const reset = () => { offset = 0; lineNumber = 0; previous = undefined; state = new ActivityState(prompt); };
+    const read = async () => {
+        let opened;
+        try {
+            opened = await openPrivateSession(path);
+        }
+        catch (error) {
+            reset();
+            throw error;
+        }
+        if (!opened) {
+            reset();
+            return;
+        }
+        const { file, info } = opened;
+        try {
+            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))))
+                reset();
+            previous = info;
+            const buffer = Buffer.alloc(info.size - offset);
+            let length = 0;
+            while (length < buffer.length) {
+                const { bytesRead } = await file.read(buffer, length, Math.min(CHUNK_BYTES, buffer.length - length), offset + length);
+                if (!bytesRead)
+                    break;
+                length += bytesRead;
+            }
+            // Only complete lines advance the offset. A malformed complete line stops the parse and throws.
+            let start = 0;
+            for (let end = buffer.indexOf(10); end >= 0 && end < length; end = buffer.indexOf(10, start)) {
+                state.consume(parseLine(buffer.toString("utf8", start, end), path, lineNumber + 1));
+                lineNumber += 1;
+                offset += end + 1 - start;
+                start = end + 1;
+            }
+        }
+        finally {
+            await file.close();
+        }
+    };
+    // Timer samples and failure evidence can request the same file at the same time.
+    const sample = async () => {
+        try {
+            await (reading ??= read().finally(() => { reading = undefined; }));
+        }
+        catch (error) {
+            lastUsage = {};
+            throw error;
+        }
+    };
+    return {
+        get activity() { return lastUsage.activity; },
+        async usage() {
+            await sample();
+            lastUsage = state.usage();
+            return { tokens: lastUsage.tokens, cost: lastUsage.cost };
+        },
+        async partialText(maxChars) {
+            await sample();
+            return state.partialText(maxChars);
+        },
+    };
+}

package/docs/orchestration.md

@@ -127,7 +127,7 @@ The new tab gets a new agent name and reference. Its record points to the same s
 
 A request can continue each worker only one time, and only from the checkout and Herdr workspace where the worker ran. After a continuation, continue the newest reference. The extension refuses an older reference to the same session, because a later turn follows its own turn.
 
-Before launch, the request fails if the reference is unknown or matches more than one record on this session branch. It also fails if the Role is different or a locally active task still owns the session of the worker. A missing session file or a session file larger than 16 MiB also causes failure. The last session turn for the recorded prompt must be finished.
+Before launch, the request fails if the reference is unknown or matches more than one record on this session branch. It also fails if the Role is different or a locally active task still owns the session of the worker. A missing session file, a session file larger than 16 MiB, or a session file that is not private also causes failure. The recorded prompt must have a Final turn.
 
 If Herdr still lists the old agent, the agent must match the recorded name, pane, tab, workspace, and checkout. It must also be idle or done. The extension never closes a working or blocked agent. The extension closes the old pane, then proves pane absence and two empty lease scans.
 
@@ -141,7 +141,13 @@ If the extension cannot prove termination of the stopped worker, the workflow ke
 
 ### Direct results and records
 
-The extension retrieves each final answer from its exact Pi session file, not its possibly truncated screen. Idle, blocked, unknown, or malformed answers fail with recoverable tab and session identities. No whole-run deadline applies.
+The extension retrieves each final answer from its exact Pi session file, not its possibly truncated screen. The worker session decides completion, not the Herdr agent state. A Herdr `idle` or `done` state only starts a read of the session. A Herdr `blocked` or `unknown` state fails at once. A failed Final turn or a malformed session fails with recoverable tab and session identities. No whole-run deadline applies.
+
+The Final turn is the latest assistant turn on the exact branch of the worker prompt that Pi did not omit. Only a `stop` Final turn is a success. A `length`, `error`, or `aborted` Final turn is a failure, and the failure names the stop reason. A `toolUse` turn, or no Final turn, means that the worker is still running. While the worker is running, the extension keeps waiting. The idle timeout applies, and growth of the session file starts the timeout again. Isolated workers use the same rule. When Herdr reports an isolated worker idle or done and its session stays without a Final turn and without growth for the idle timeout, the worker result is `unknown`.
+
+Pi can retry a turn after a provider error, such as HTTP 429, or recover from a `length` turn. Before the retry, Pi writes a `context_edit` entry that omits the old turn, so the old turn is not the Final turn. Herdr can report the agent done before Pi writes this entry. Thus an `error` Final turn is a failure only when a second read after about 500 ms shows the same turn, still not omitted. A `length` Final turn is a failure unless Pi recovers it.
+
+Each session file must be private: a regular file of the current user with mode `0600`, and 16 MiB or smaller. The extension creates each new session file with mode `0600` before it starts Pi. A session file with group or other access, or a symbolic link, causes failure. Continuation of a session file with a wider mode, for example from an older release, fails. The error gives the file path and the `0600` rule.
 
 The tasks in a request share a 40 KiB inline answer budget. Each worker prompt states its share. A longer exact answer is still a success. The result shows a UTF-8-safe prefix and a truncation marker. The marker gives the path of a private `answer-<turn>.md` file beside the session file, which holds the full answer. For a write task, the budget applies to the `answer` field of the completion object. A chain step receives the full answer of the previous step in `{previous}`; the budget applies only to the result for Main. The result details keep `answerFile` for each full-answer file. Recovery text includes these paths outside the output limit, even when checkout notes remove the inline link.
 

package/extensions/isolated.ts

@@ -86,7 +86,8 @@ export const createIsolatedComponents: CreateIsolatedComponents = ({
 		maxMs: null,
 		...(policy.maxTokens === undefined ? {} : { maxTokens: policy.maxTokens }),
 	});
-	const host = new HerdrHostRuntime({ inspectInFlightTaskCandidate: git.inspectInFlightTaskCandidate.bind(git), runProcess, executionBudget });
+	const host = new HerdrHostRuntime({ inspectInFlightTaskCandidate: git.inspectInFlightTaskCandidate.bind(git), runProcess, executionBudget,
+		settledIdleMs: () => currentPolicy().childIdleMs });
 	const coordinator = new RoleLaunchRuntime({
 		pi,
 		context,

package/extensions/subagent.ts

@@ -13,8 +13,18 @@ import { directRef, registerSubagentCommand, type DirectDisplay, type DirectTask
 import { MODEL_CLASS_GUIDANCE } from "./model-class-policy.ts";
 import { compactCost, compactTokens, ENTRY_STATUS_PRESENTATION, formatWorkflowResult, workerOutputForMain, type BackgroundWorkflowTransportDetails, type WorkflowTransportEntry } from "./result-transport.ts";
 import { checkoutNote, DelegateTaskParameters, identifyWorkflowEntries, parseDelegateTask, runForegroundWorkflow, snapshotCheckout, workflowRepos, writesCheckout, type CheckoutSnapshot, type ParsedWorkflow, type WorkflowEntry } from "./workflow.ts";
-import { assertSettledDirectSession, createDirectHerdr, DirectAllocationError, directTaskReader, type DirectAllocation, type DirectHandle, type DirectTab, type DirectToolActivity, type DirectUsage } from "../dist/direct-herdr.js";
+import { createDirectHerdr, DirectAllocationError, directTaskReader, directTurnPrompt, type DirectAllocation, type DirectHandle, type DirectTab, type DirectToolActivity, type DirectUsage } from "../dist/direct-herdr.js";
 import { materializeTransientLaunch } from "../dist/launch-runtime.js";
+import { readSessionTurn } from "../dist/session-turn.js";
+/** Refuse continuation unless the saved session has a Final turn for the recorded turn and no later user turn. */
+async function assertSettledDirectSession(sessionFile: string, turn: string): Promise<void> {
+	const final = await readSessionTurn(sessionFile, directTurnPrompt(turn));
+	if (final.state === "absent") throw new Error(`Saved Pi session ${sessionFile} is missing or unreadable, or has no recorded prompt`);
+	if (final.state === "running") {
+		throw new Error(`Saved Pi session ${sessionFile} has no terminal final turn for the recorded prompt; the worker may still be running`);
+	}
+}
+
 const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 1_000;
 const MAX_WIDGET_ITEMS = 8;

package/package.json

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