@henryqw/pi-subagent 25.0.1 → 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.
 

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.1",
+  "version": "25.0.2",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",