@henryqw/pi-subagent 25.0.0 → 25.0.2

package/README.md

@@ -126,7 +126,9 @@ An isolated request has one durable ID, one goal, and 1–8 typed tasks:
 
 `dependsOn` controls scheduling. `contextFrom` also schedules dependencies and carries completed text outputs in the declared order. Do not repeat the same task in both fields. 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 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`.
+`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. Session replacement or shutdown suppresses stale delivery and logs the request ID and reason, without prompts or credentials. Synchronous delivery failures are reported without automatic replay; Pi reports asynchronous `send_message` failures through its native runtime. If delivery is missed, inspect `subagent_status`.
+
+Completed text answers are saved independently of cleanup. Status and terminal follow-ups include a bounded accepted-answer preview and cleanup evidence. Ignored automatic artifacts can retain a checkout without violating the read-only contract; no ignored files are deleted to make cleanup pass. Tracked or untracked changes, changed checkout identity, or unproved inspection still require attention: the completed answer remains saved but is not accepted as dependency context or retried automatically. Retained text checkouts require deliberate manual inspection and cleanup; a retained checkout alone is not evidence that the Role edited source.
 
 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.
 
@@ -181,7 +183,7 @@ Role Markdown lives in `~/.pi/agent/config/pi-subagent/` and requires frontmatte
 
 Roles describe responsibility and capabilities. They do not choose isolation; each request does. A same-named user Role overrides a built-in Role. The package ships `implementer`, `reviewer`, and `scout`.
 
-Children run with `--no-extensions`, so a Role must list the extension that registers its route model's provider, and only declared resources plus required internal policy adapters load. `builtin:<name>` entries load Pi built-in extensions (`builtin:codemode`, `builtin:tool-search`, `builtin:llama.cpp`) explicitly; `builtin:mcp` is rejected because it would connect every configured server and bypass `mcps`. The servers named in `mcps` come from the global `~/.pi/agent/mcp.json` only; their tools load in the child with direct exposure and are declared to the model as `mcp__<server>__<tool>` once the server connects. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work starts. Main-only delegation and recovery tools plus `ask_question` are excluded from children.
+Children run with `--no-extensions`, so a Role must list the extension that registers its route model's provider, and only declared resources plus required internal policy adapters load. `builtin:<name>` entries load Pi built-in extensions (`builtin:codemode`, `builtin:tool-search`, `builtin:llama.cpp`) explicitly; `builtin:mcp` is rejected because it would connect every configured server and bypass `mcps`. The servers named in `mcps` come from the global `~/.pi/agent/mcp.json` only; their tools load in the child with direct exposure and are declared to the model as `mcp__<server>__<tool>` once the server connects. Pi replaces `-` in server and tool names with `_` and appends a hash suffix when two tool names collide or a name exceeds 64 characters. Each selected entry is checked against Pi's documented `mcpServers` rules before launch, in Main and again in the child: a disabled, malformed, or unknown-transport entry, an invalid server name, two selected names that differ only in `-` and `_`, `auth.provider` over plain HTTP outside `localhost`, `127.0.0.1`, or `[::1]`, or a non-HTTPS `oauth.authServerMetadataUrl` outside those hosts fails the launch with the file path and field. The file is never modified; fix the entry or choose another server. Valid `auth`, `oauth`, and `description` fields are passed through so Pi's native provider auth and OAuth apply. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work starts. Main-only delegation and recovery tools plus `ask_question` are excluded from children.
 
 ## API
 

package/dist/mcp-role.js

@@ -22,17 +22,69 @@ export function parseRoleMcpAllowlist(value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-const isStringRecord = (value) => isRecord(value) && Object.values(value).every((item) => typeof item === "string");
-/** Documented optional fields of an `mcpServers` entry and their shapes (see Pi's docs/mcp.md). */
-const FIELD_CHECKS = {
-    args: [(value) => Array.isArray(value) && value.every((item) => typeof item === "string"), "an array of strings"],
+const isString = (value) => typeof value === "string";
+const isStringRecord = (value) => isRecord(value) && Object.values(value).every(isString);
+const parseUrl = (value) => (typeof value === "string" && URL.canParse(value) ? new URL(value) : undefined);
+// Pi's native MCP rules (core/mcp-servers.ts); `validateMcpServerConfig` is not exported, so they are mirrored here.
+const SERVER_NAME = /^[A-Za-z0-9_-]+$/;
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+const isHttpsOrLoopback = (url) => url !== undefined && (url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname)));
+/** Tool namespace `mcp__<server>` replaces `-` with `_`, so names differing only there collide. */
+const mcpNamespace = (name) => name.replace(/-/g, "_");
+/** Documented `mcpServers` fields (Pi's docs/mcp.md) and their shapes, by transport; dotted keys are nested. */
+const COMMON_CHECKS = {
+    enabled: [(value) => typeof value === "boolean", "a boolean"],
+    timeout: [(value) => typeof value === "number" && Number.isFinite(value) && value > 0, "a positive number"],
+    description: [isString, "a string"],
+};
+const STDIO_CHECKS = {
+    args: [(value) => Array.isArray(value) && value.every(isString), "an array of strings"],
     env: [isStringRecord, "an object of strings"],
+    cwd: [isString, "a string"],
+};
+const HTTP_CHECKS = {
+    url: [(value) => /^https?:$/.test(parseUrl(value)?.protocol ?? ""), "an http or https URL"],
     headers: [isStringRecord, "an object of strings"],
-    cwd: [(value) => typeof value === "string", "a string"],
-    timeout: [(value) => typeof value === "number" && Number.isFinite(value) && value > 0, "a positive number"],
-    enabled: [(value) => typeof value === "boolean", "a boolean"],
     oauth: [isRecord, "an object"],
+    "oauth.clientId": [isString, "a string"],
+    "oauth.clientSecret": [isString, "a string"],
+    "oauth.callbackPort": [(value) => Number.isInteger(value) && value >= 1 && value <= 65535, "a port number"],
+    "oauth.callbackUrl": [(value, server) => {
+            const url = parseUrl(value);
+            const port = server.oauth.callbackPort;
+            return url !== undefined && url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname) && url.search === "" && url.hash === ""
+                && (url.port === "" || port === undefined || Number(url.port) === port);
+        }, "an http URL on localhost, 127.0.0.1, or [::1] without query or fragment, on the \"oauth.callbackPort\" port"],
+    "oauth.scope": [isString, "a string"],
+    "oauth.clientName": [(value) => typeof value === "string" && value.trim() !== "", "a non-empty string"],
+    "oauth.authServerMetadataUrl": [(value) => isHttpsOrLoopback(parseUrl(value)), "an https URL, or http on localhost, 127.0.0.1, or [::1]"],
+    auth: [(value) => isRecord(value) && typeof value.provider === "string" && value.provider !== "", "an object with a non-empty \"provider\" string"],
 };
+/** Validate one selected server against Pi's documented `mcpServers` rules; the native loader is bypassed by `loadConfig`. */
+function validateRoleMcpServer(path, name, value) {
+    const fail = (message) => { throw new Error(`${path}: MCP server "${name}" ${message}`); };
+    if (!SERVER_NAME.test(name))
+        fail("has an invalid name (use letters, digits, \"_\" and \"-\").");
+    if (!isRecord(value))
+        fail("must be an object.");
+    if (value.enabled === false)
+        throw new Error(`${path}: Role MCP server "${name}" is disabled.`);
+    const stdio = typeof value.command === "string" && value.command.trim() !== "" && (value.type === undefined || value.type === "stdio");
+    const http = typeof value.url === "string" && value.url.trim() !== "" && (value.type === undefined || value.type === "http" || value.type === "streamable-http");
+    if (stdio === http)
+        fail("needs either a \"command\" (stdio) or a \"url\" (http or streamable-http).");
+    for (const [field, [valid, shape]] of Object.entries({ ...COMMON_CHECKS, ...(stdio ? STDIO_CHECKS : HTTP_CHECKS) })) {
+        const fieldValue = field.split(".").reduce((parent, key) => (isRecord(parent) ? parent[key] : undefined), value);
+        if (fieldValue !== undefined && !valid(fieldValue, value))
+            fail(`field "${field}" must be ${shape}.`);
+    }
+    // The native transport sends the provider's token to `url`, so Pi only allows it over https or loopback.
+    if (value.auth !== undefined && !isHttpsOrLoopback(parseUrl(value.url))) {
+        fail("field \"auth\" requires \"url\" to use https, or http on localhost, 127.0.0.1, or [::1].");
+    }
+    const { toolExposure: _toolExposure, ...config } = value;
+    return { ...config, exposure: "direct" };
+}
 /**
  * Select the Role's allowlisted servers from the global `mcp.json` in Pi's native `mcpServers`
  * shape; the project `.pi/mcp.json` is ignored. A `--no-extensions` child has no codemode tool, so
@@ -56,23 +108,13 @@ export function loadRoleMcpConfig(agentDir, allowlist) {
     const missing = allowlist.filter((name) => !Object.hasOwn(configured, name));
     if (missing.length)
         throw new Error(`Role MCP servers are not configured: ${missing.join(", ")}.`);
+    const namespaces = new Map();
     const servers = allowlist.map((name) => {
-        const value = configured[name];
-        if (!isRecord(value))
-            throw new Error(`${path}: MCP server "${name}" must be an object.`);
-        if (value.enabled === false)
-            throw new Error(`${path}: Role MCP server "${name}" is disabled.`);
-        const stdio = typeof value.command === "string" && value.command.trim() !== "" && (value.type === undefined || value.type === "stdio");
-        const http = typeof value.url === "string" && value.url.trim() !== "" && (value.type === undefined || value.type === "http" || value.type === "streamable-http");
-        if (stdio === http) {
-            throw new Error(`${path}: MCP server "${name}" needs either a "command" (stdio) or a "url" (http or streamable-http).`);
-        }
-        for (const [field, [valid, shape]] of Object.entries(FIELD_CHECKS)) {
-            if (value[field] !== undefined && !valid(value[field]))
-                throw new Error(`${path}: MCP server "${name}" field "${field}" must be ${shape}.`);
-        }
-        const { toolExposure: _toolExposure, ...config } = value;
-        return { name, config: { ...config, exposure: "direct" }, source: path, scope: "global" };
+        const clash = namespaces.get(mcpNamespace(name));
+        if (clash)
+            throw new Error(`${path}: Role MCP server "${name}" conflicts with "${clash}": names that differ only in "-" and "_" share one tool namespace.`);
+        namespaces.set(mcpNamespace(name), name);
+        return { name, config: validateRoleMcpServer(path, name, configured[name]), source: path, scope: "global" };
     });
     return { servers, autoEnableCodemode: false, errors: [] };
 }

package/dist/runner.js

@@ -1,5 +1,6 @@
 import { readFileSync, realpathSync } from "node:fs";
-import { createChildWorktree, finalizeChildWorktree } from "./worktree.js";
+import { createChildWorktree, finalizeChildWorktree, inspectWorktreeDirty } from "./worktree.js";
+import { runGit } from "./git-process.js";
 import { IntegrationGit } from "./integration-git.js";
 import { checkBatchPasses, CLEANUP_KINDS, isCleanCommitted, MAX_PERSISTED_RUNTIME_TEXT_BYTES, MAX_POSSIBLE_RESOURCES, parseExecuteRequest, parseIntegrationAction, integrationGenerationPasses, parseResumeRequest, parseStageRequest, reviewEvidencePasses, sameIdentity, RUN_STATE_VERSION, } from "./schema.js";
 import { FileRunStore, ProductiveRunLeaseBusyError } from "./store.js";
@@ -526,7 +527,9 @@ export class IsolatedRunner {
         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: ["completed", "aborted"].includes(state.status) && (state.tasks.some((task) => task.kind === "changeset" && task.attempts.some((attempt) => attempt.cleanup.some((step) => step.status !== "completed")))
+                status: ["completed", "aborted"].includes(state.status) && (state.tasks.some((task) => task.kind === "changeset"
+                    ? task.attempts.some((attempt) => attempt.cleanup.some((step) => step.status !== "completed"))
+                    : task.attempts.some((attempt) => attempt.cleanup && attempt.cleanup.outcome !== "pruned"))
                     || state.integration.generations.some((generation) => generation.cleanup?.some((step) => step.status !== "completed")
                         || (generation.worktree && generation.cleanup?.every((step) => step.status === "completed") !== true)))
                     ? `${state.status} · retained` : state.status,
@@ -2035,6 +2038,7 @@ export class IsolatedRunner {
         if (!attempt || attempt.status !== "running")
             throw new Error(`Text task ${task.taskId} has no running attempt.`);
         const prompt = buildTextTaskPrompt(state.request.goal, request, resolveTextTaskContexts(state, request));
+        let checkoutFailure;
         const result = await this.callProductive(handle, scope, async (context) => {
             const wave = state.waves.at(-1);
             if (!wave?.taskIds.includes(task.taskId))
@@ -2071,12 +2075,19 @@ export class IsolatedRunner {
                         prepare: async () => ({ launch, task: prompt, cwd: isolated.cwd }),
                     });
                 });
+                // Read-only evidence excludes ignored artifacts; deletion safety still includes them.
+                const inspection = await inspectWorktreeDirty(isolated.path, runGit, false);
+                const head = await runGit(["rev-parse", "--verify", "HEAD"], isolated.path);
+                const branch = await runGit(["symbolic-ref", "--quiet", "HEAD"], isolated.path);
+                checkoutFailure = inspection.failure ? `read-only checkout inspection failed: ${inspection.failure}`
+                    : inspection.dirty ? "read-only contract violated: tracked or untracked changes remain"
+                        : head.code !== 0 || branch.code !== 0 ? "read-only checkout identity could not be proved"
+                            : head.stdout.trim() !== isolated.baseCommit || branch.stdout.trim() !== `refs/heads/${isolated.branch}`
+                                ? "read-only contract violated: checkout HEAD or branch changed" : undefined;
             }
             finally {
-                const cleanup = await finalizeChildWorktree(isolated);
-                if (cleanup.outcome !== "pruned") {
-                    throw new Error(`Isolated text task changed its checkout; work was retained at ${cleanup.path} on ${cleanup.branch}.`);
-                }
+                // Retention is evidence, not proof of source edits, and must not mask an answer or executor error.
+                attempt.cleanup = await finalizeChildWorktree(isolated);
             }
             return result;
         });
@@ -2091,16 +2102,30 @@ 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.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);
-        if (wave.base.head !== state.main.head) {
-            const generation = state.integration.generations.at(-1);
-            if (!generation?.worktree || generation.status === "superseded" || !sameIdentity(generation.combinedTip, wave.base)) {
-                throw new Error("Staged dependency snapshot was superseded during text task execution.");
+        try {
+            if (checkoutFailure)
+                throw new Error(`Isolated text task ${checkoutFailure}; inspect ${attempt.cleanup.path} on ${attempt.cleanup.branch}.`);
+            if (attempt.cleanup?.outcome === "recovery")
+                throw new Error(`Isolated text task cleanup requires recovery: ${attempt.cleanup.note}`);
+            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);
+            if (wave.base.head !== state.main.head) {
+                const generation = state.integration.generations.at(-1);
+                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, true);
             }
-            await this.requireExactIntegration(handle, generation, this.stageReceipts(generation), scope, true);
+        }
+        catch (error) {
+            this.rethrowStopped(error);
+            // Retain the completed answer without admitting it as dependency context.
+            attempt.status = "completed";
+            attempt.output = { text: output };
+            this.attention(task, `Task dispatch was interrupted: ${errorText(error)}`);
+            throw error;
         }
         attempt.status = "completed";
         attempt.failure = undefined;

package/dist/schema.d.ts

@@ -877,6 +877,24 @@ declare const TextTaskAttemptSchema: Type.TObject<{
     output: Type.TOptional<Type.TObject<{
         text: Type.TString;
     }>>;
+    cleanup: Type.TOptional<Type.TUnion<[Type.TObject<{
+        outcome: Type.TLiteral<"pruned">;
+        path: Type.TString;
+        branch: Type.TString;
+    }>, Type.TObject<{
+        outcome: Type.TLiteral<"retained">;
+        path: Type.TString;
+        branch: Type.TString;
+        commits: Type.TInteger;
+        dirty: Type.TBoolean;
+    }>, Type.TObject<{
+        outcome: Type.TLiteral<"recovery">;
+        path: Type.TString;
+        branch: Type.TString;
+        note: Type.TString;
+        commits: Type.TOptional<Type.TInteger>;
+        dirty: Type.TOptional<Type.TBoolean>;
+    }>]>>;
 }>;
 declare const TextTaskStateSchema: Type.TObject<{
     taskId: Type.TString;
@@ -889,6 +907,24 @@ declare const TextTaskStateSchema: Type.TObject<{
         output: Type.TOptional<Type.TObject<{
             text: Type.TString;
         }>>;
+        cleanup: Type.TOptional<Type.TUnion<[Type.TObject<{
+            outcome: Type.TLiteral<"pruned">;
+            path: Type.TString;
+            branch: Type.TString;
+        }>, Type.TObject<{
+            outcome: Type.TLiteral<"retained">;
+            path: Type.TString;
+            branch: Type.TString;
+            commits: Type.TInteger;
+            dirty: Type.TBoolean;
+        }>, Type.TObject<{
+            outcome: Type.TLiteral<"recovery">;
+            path: Type.TString;
+            branch: Type.TString;
+            note: Type.TString;
+            commits: Type.TOptional<Type.TInteger>;
+            dirty: Type.TOptional<Type.TBoolean>;
+        }>]>>;
     }>>;
     failure: Type.TOptional<Type.TString>;
 }>;
@@ -903,6 +939,24 @@ declare const TaskStateSchema: Type.TUnion<[Type.TObject<{
         output: Type.TOptional<Type.TObject<{
             text: Type.TString;
         }>>;
+        cleanup: Type.TOptional<Type.TUnion<[Type.TObject<{
+            outcome: Type.TLiteral<"pruned">;
+            path: Type.TString;
+            branch: Type.TString;
+        }>, Type.TObject<{
+            outcome: Type.TLiteral<"retained">;
+            path: Type.TString;
+            branch: Type.TString;
+            commits: Type.TInteger;
+            dirty: Type.TBoolean;
+        }>, Type.TObject<{
+            outcome: Type.TLiteral<"recovery">;
+            path: Type.TString;
+            branch: Type.TString;
+            note: Type.TString;
+            commits: Type.TOptional<Type.TInteger>;
+            dirty: Type.TOptional<Type.TBoolean>;
+        }>]>>;
     }>>;
     failure: Type.TOptional<Type.TString>;
 }>, Type.TObject<{
@@ -1717,6 +1771,24 @@ declare const RunStateSchema: Type.TObject<{
             output: Type.TOptional<Type.TObject<{
                 text: Type.TString;
             }>>;
+            cleanup: Type.TOptional<Type.TUnion<[Type.TObject<{
+                outcome: Type.TLiteral<"pruned">;
+                path: Type.TString;
+                branch: Type.TString;
+            }>, Type.TObject<{
+                outcome: Type.TLiteral<"retained">;
+                path: Type.TString;
+                branch: Type.TString;
+                commits: Type.TInteger;
+                dirty: Type.TBoolean;
+            }>, Type.TObject<{
+                outcome: Type.TLiteral<"recovery">;
+                path: Type.TString;
+                branch: Type.TString;
+                note: Type.TString;
+                commits: Type.TOptional<Type.TInteger>;
+                dirty: Type.TOptional<Type.TBoolean>;
+            }>]>>;
         }>>;
         failure: Type.TOptional<Type.TString>;
     }>, Type.TObject<{

package/dist/schema.js

@@ -291,6 +291,17 @@ const TextTaskAttemptSchema = Type.Object({
     status: Type.Union([Type.Literal("running"), Type.Literal("completed"), Type.Literal("failed"), Type.Literal("superseded")]),
     failure: OptionalRuntimeTextSchema,
     output: Type.Optional(TextTaskOutputSchema),
+    cleanup: Type.Optional(Type.Union([
+        Type.Object({ outcome: Type.Literal("pruned"), path: RuntimeTextSchema, branch: RuntimeTextSchema }, { additionalProperties: false }),
+        Type.Object({
+            outcome: Type.Literal("retained"), path: RuntimeTextSchema, branch: RuntimeTextSchema,
+            commits: Type.Integer({ minimum: 0 }), dirty: Type.Boolean(),
+        }, { additionalProperties: false }),
+        Type.Object({
+            outcome: Type.Literal("recovery"), path: RuntimeTextSchema, branch: RuntimeTextSchema, note: RuntimeTextSchema,
+            commits: Type.Optional(Type.Integer({ minimum: 0 })), dirty: Type.Optional(Type.Boolean()),
+        }, { additionalProperties: false }),
+    ])),
 }, { additionalProperties: false });
 const TextTaskStateSchema = Type.Object({
     taskId: IdSchema,
@@ -679,7 +690,7 @@ function validateTextTaskState(taskState) {
             ? "running"
             : "completed";
     if (taskState.status === "needs_attention"
-        ? latest && !["failed", "superseded"].includes(latest.status)
+        ? latest && !["failed", "superseded", "completed"].includes(latest.status)
         : latest?.status !== expectedLatestStatus) {
         throw new Error(`Text task ${taskState.taskId} status ${taskState.status} has an incompatible latest attempt.`);
     }

package/extensions/isolated.ts

@@ -281,16 +281,24 @@ function publicState(state: RunState, preferredTaskId?: string) {
 		status: state.status,
 		accepted: state.accepted,
 		main: state.main,
-		tasks: state.tasks.map((task) => ({
-			taskId: task.taskId, status: task.status,
-			...(task.kind === "changeset" && state.integration.candidates.length ? { attempts: task.attempts.map((attempt) => ({
-				number: attempt.number, superseded: attempt.superseded === true,
-				workerId: attempt.allocations.flatMap((item) => item.kind === "agent" && item.status === "owned" ? [item.agentName] : [])[0],
-				termination: attempt.termination?.status,
-				worktree: attempt.allocations.flatMap((item) => item.kind === "worktree" && item.status === "owned" && item.worktree ? [item.worktree.path] : [])[0],
-				cleanup: attempt.cleanup.filter((step) => step.status !== "completed"),
-			})) } : {}),
-		})),
+		tasks: state.tasks.map((task) => {
+			const textAttempt = task.kind === "text" ? task.attempts.at(-1) : undefined;
+			return {
+				taskId: task.taskId, status: task.status,
+				...(task.status === "completed" && textAttempt?.output ? { output: boundedPublicText(textAttempt.output.text) } : {}),
+				...(textAttempt?.cleanup ? { cleanup: {
+					...textAttempt.cleanup,
+					...(textAttempt.cleanup.outcome === "recovery" ? { note: boundedPublicText(textAttempt.cleanup.note) } : {}),
+				} } : {}),
+				...(task.kind === "changeset" && state.integration.candidates.length ? { attempts: task.attempts.map((attempt) => ({
+					number: attempt.number, superseded: attempt.superseded === true,
+					workerId: attempt.allocations.flatMap((item) => item.kind === "agent" && item.status === "owned" ? [item.agentName] : [])[0],
+					termination: attempt.termination?.status,
+					worktree: attempt.allocations.flatMap((item) => item.kind === "worktree" && item.status === "owned" && item.worktree ? [item.worktree.path] : [])[0],
+					cleanup: attempt.cleanup.filter((step) => step.status !== "completed"),
+				})) } : {}),
+			};
+		}),
 		final: { status: state.final.status },
 		integration: {
 			...(state.integration.refresh ? { refresh: state.integration.refresh } : {}),
@@ -499,9 +507,12 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		const sessionId = ctx.sessionManager?.getSessionId();
 		const key = `${root}\0${id}`;
 		if (jobOwners.has(key)) throw new Error(`Pi Subagent request ${id} is already active in this session runtime.`);
-		const canDeliver = () => !sessionClosed && sessionEpoch === epoch
-			&& ctx.sessionManager?.getSessionId() === sessionId
-			&& latestCtx?.sessionManager?.getSessionId() === sessionId;
+		const deliverySuppression = () => sessionClosed ? "session closed"
+			: sessionEpoch !== epoch ? "session generation changed"
+			: ctx.sessionManager?.getSessionId() !== sessionId ? "launching session changed"
+			: latestCtx?.sessionManager?.getSessionId() !== sessionId ? "current session changed"
+			: undefined;
+		const canDeliver = () => deliverySuppression() === undefined;
 		const controller = new AbortController();
 		activeJobs.add(controller);
 		jobOwners.set(key, canDeliver);
@@ -517,6 +528,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		if (signal?.aborted) abortBeforeAck();
 		else signal?.addEventListener("abort", abortBeforeAck, { once: true });
 		let latestState: RunState | undefined;
+		let durableAcknowledged = false;
 		let accept!: (state: RunState) => void;
 		let reject!: (error: unknown) => void;
 		const durable = new Promise<RunState>((resolve, fail) => { accept = resolve; reject = fail; });
@@ -525,14 +537,19 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 			if (state.root !== root || state.request.id !== id) return;
 			latestState = state;
 			if (!acknowledged(state)) return;
+			durableAcknowledged = true;
 			for (const candidate of state.integration.candidates) notified.add(`${candidate.taskId}\0${candidate.attempt}\0${candidate.tip.head}`);
 			stateListeners.delete(listener);
 			removeTurnAbort();
 			accept(state);
 		};
 		stateListeners.add(listener);
-		const deliver = (text: string, response?: RunResponse) => {
-			if (!canDeliver()) return;
+		const deliver = (kind: "candidate" | "attention" | "terminal", text: string, response?: RunResponse) => {
+			const suppression = deliverySuppression();
+			if (suppression) {
+				console.warn(`Pi Subagent ${id}: ${kind} delivery suppressed (${suppression}); durable request retained.`);
+				return;
+			}
 			const state = response?.state ?? latestState;
 			try {
 				const details = state ? {
@@ -547,13 +564,14 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 					details,
 				}, { triggerTurn: true, deliverAs: "followUp" });
 			} catch {
-				console.error(`Pi Subagent ${id} result delivery failed; use subagent_status to recover.`);
+				console.error(`Pi Subagent ${id}: ${kind} delivery failed (sendMessage threw); use subagent_status to recover. No delivery replayed.`);
 				if (ctx.hasUI) ctx.ui.notify(`Pi Subagent ${id} result delivery failed; use subagent_status to recover.`, "error");
 			}
 		};
 		candidateListener = (state) => {
-			if (state.root !== root || state.request.id !== id || state.status !== "running" || !canDeliver()) return;
+			if (state.root !== root || state.request.id !== id) return;
 			latestState = state;
+			if (state.status !== "running") return;
 			for (const task of state.tasks) {
 				if (task.status !== "needs_attention") {
 					attentionNotified.delete(task.taskId);
@@ -561,13 +579,13 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 				}
 				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.`);
+				deliver("attention", `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;
 				notified.add(identity);
-				deliver(`Pi Subagent ${id}: ${candidate.taskId} ready to integrate. Inspect the exact candidate with subagent_status and stage it now; other workers may still be running.`);
+				deliver("candidate", `Pi Subagent ${id}: ${candidate.taskId} ready to integrate. Inspect the exact candidate with subagent_status and stage it now; other workers may still be running.`);
 			}
 		};
 		stateListeners.add(candidateListener);
@@ -576,21 +594,21 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 				finish();
 				stateListeners.delete(listener);
 				removeTurnAbort();
-				if (!latestState || !acknowledged(latestState)) {
+				if (!durableAcknowledged) {
 					reject(new Error(`Pi Subagent ${id} finished without a durable acknowledgement.`));
 					return;
 				}
-				deliver(`${response.text}\n\nState: ${JSON.stringify(publicState(response.state))}`, response);
+				deliver("terminal", `${response.text}\n\nState: ${JSON.stringify(publicState(response.state))}`, response);
 			},
 			(error: unknown) => {
 				finish();
 				stateListeners.delete(listener);
 				removeTurnAbort();
-				if (!latestState || !acknowledged(latestState)) {
+				if (!durableAcknowledged) {
 					reject(error);
 					return;
 				}
-				deliver(`Pi Subagent ${id} stopped: ${boundedPublicText(error instanceof Error ? error.message : String(error))}. Use subagent_status to inspect the durable request and subagent_resume or subagent_abort for recovery.`);
+				deliver("terminal", `Pi Subagent ${id} stopped: ${boundedPublicText(error instanceof Error ? error.message : String(error))}. Use subagent_status to inspect the durable request and subagent_resume or subagent_abort for recovery.`);
 			},
 		);
 		const state = await durable;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "25.0.0",
+  "version": "25.0.2",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -40,9 +40,9 @@
     "pack:check": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.99.1 <0.100.0",
-    "@earendil-works/pi-coding-agent": ">=0.99.1 <0.100.0",
-    "@earendil-works/pi-tui": ">=0.99.1 <0.100.0",
+    "@earendil-works/pi-ai": ">=0.99.1 <0.100.0 || ^1.0.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.1 <0.100.0 || ^1.0.0",
+    "@earendil-works/pi-tui": ">=0.99.1 <0.100.0 || ^1.0.0",
     "typebox": "^1.3.15"
   },
   "repository": {
@@ -74,9 +74,9 @@
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.99.1",
-    "@earendil-works/pi-coding-agent": "0.99.1",
-    "@earendil-works/pi-tui": "0.99.1",
+    "@earendil-works/pi-ai": "1.0.0",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
     "@types/proper-lockfile": "^4.1.4"
   }
 }