@hcflabs/pi-subagent 28.3.0 → 28.3.2

package/README.md

@@ -37,7 +37,7 @@ Commands, prompts, and UI are for you. Tools and the packaged skill are for Main
 | `delegate_task` | tool | Start authorized shared-checkout work or a durable isolated checked graph. With `dryRun: true`, check the request and show the resolved plan without a launch. |
 | `subagent_repos` | tool | List the child Git repositories below the Pi working directory and the `repo` selector of each. Read-only. |
 | `subagent_status` | tool | Read saved isolated state, exact identities, failed review verdicts, and allowed continuation. Does not replay work. Supports structured output for `codemode`. |
-| `subagent_resume` | tool | Perform the reported `retry`, `verify`, or `finalize` continuation, not staging or integration. Same-worker correction retries accept optional `instruction` text. |
+| `subagent_resume` | tool | Perform the reported `retry`, `verify`, or `finalize` continuation, not staging or integration. Same-worker correction retries accept optional `instruction` text. `verify` can also adopt a later clean committed candidate from the same settled worker. That candidate must pass its normal checks and judgment. |
 | `subagent_stage` | tool | Stage, resolve, reject, or revise an exact candidate. Rejecting a staged candidate freezes its generation. |
 | `subagent_integrate` | tool | Advance dependents, refresh, validate, correct, promote, reconcile, clean up promotion, or release rejected and superseded resources. |
 | `subagent_abort` | tool | Terminate an isolated request without discarding retained work. Retained candidates and integration work require release or proof of absence. |

package/dist/direct-herdr.js

@@ -216,7 +216,7 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                 onTab({ name, tabId, paneId, sessionFile, leasePath, turn, workspaceId, cwd: workingDir });
                 signal.throwIfAborted();
                 const started = await startPiAgent(herdr, { name, pane: paneId,
-                    args: [...sessionArgs, "--session", sessionFile], options: options(signal), shouldRetry: () => false });
+                    args: [...sessionArgs, "--session", sessionFile], options: options(signal), shouldRetry: () => false, freshPane: true });
                 if (started.code !== 0 || started.killed)
                     throw new Error(`Herdr agent start failed: ${started.stderr.slice(0, 1000)}`);
                 if (inspect(JSON.parse(started.stdout), "agent_started", name, paneId, tabId) !== "idle")

package/dist/herdr-runtime.d.ts

@@ -104,6 +104,20 @@ export declare class HerdrHostRuntime implements HostRuntime {
         outcome: "unknown";
         failure: string;
     }>;
+    /**
+     * Proves that the exact owned worker is settled with a `stop` Final turn on its latest recorded prompt.
+     * The method reads the lifecycle and the session one time. It sends no prompt and closes nothing.
+     */
+    inspectSettledWorker(input: {
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        workerId: string;
+    }, context: OperationContext): Promise<{
+        outcome: "settled";
+    } | {
+        outcome: "active" | "unknown";
+        failure: string;
+    }>;
     private proveAbsentAgentForCleanup;
     cleanupHost(input: {
         requestId: ExecuteRequest["id"];

package/dist/herdr-runtime.js

@@ -23,6 +23,8 @@ const STALLED_PROMPT_POLL_MS = 250;
 const DEFAULT_SETTLED_IDLE_MS = 600_000;
 const HOST_LAYOUT_POLL_MS = 50;
 const HOST_LAYOUT_MAX_POLLS = 40;
+const SHELL_IDLE_POLL_MS = 100;
+const SHELL_IDLE_MAX_POLLS = 100;
 const DIAGNOSTIC_LIMIT = 8 * 1024;
 const LEASE_MODE = 0o600;
 const DIRECTORY_MODE = 0o700;
@@ -663,6 +665,41 @@ export class HerdrHostRuntime {
             return { outcome: "unknown", failure: safeText(error) };
         }
     }
+    /**
+     * Proves that the exact owned worker is settled with a `stop` Final turn on its latest recorded prompt.
+     * The method reads the lifecycle and the session one time. It sends no prompt and closes nothing.
+     */
+    async inspectSettledWorker(input, context) {
+        try {
+            const allocation = ownedIntent(input.attempt, "agent");
+            requireIntentIdentity(allocation, input.attempt);
+            assertAgentIntent(allocation, input.attempt);
+            if (input.workerId !== allocation.agentName)
+                throw new Error("Settled worker inspection does not target the exact saved agent.");
+            this.assertLeasePath(allocation.leasePath, allocation.token);
+            await assertPrivateLease(allocation.leasePath, false);
+            // runWorker adds the prompt count after it records the prompt. So the latest prompt has the identity of the count.
+            const index = input.attempt.prompts.length;
+            if (!index)
+                throw new Error("Settled worker inspection requires a recorded worker prompt.");
+            const lifecycle = await this.waitForAgentLifecycle(allocation, context, true);
+            if (!SETTLED_AGENT_STATES.has(lifecycle.status)) {
+                return { outcome: "active", failure: `The exact worker is not settled: ${lifecycle.status}.` };
+            }
+            const suffix = `\n\nTurn identity: ${input.attempt.correlationToken}:${index}`;
+            const turn = await this.workerSessionTurn(allocation, (text) => text.endsWith(suffix), context.signal);
+            if (turn.state === "succeeded")
+                return { outcome: "settled" };
+            if (turn.state === "failed")
+                return { outcome: "unknown", failure: `The latest worker prompt has no stop Final turn. ${turn.failure}` };
+            return { outcome: "active", failure: turn.state === "running"
+                    ? "The latest worker prompt has no Final turn yet."
+                    : "The worker session has no entry for the latest worker prompt." };
+        }
+        catch (error) {
+            return { outcome: "unknown", failure: safeText(error) };
+        }
+    }
     async proveAbsentAgentForCleanup(allocation, attempt, context) {
         requireIntentIdentity(allocation, attempt);
         assertAgentIntent(allocation, attempt);
@@ -851,7 +888,7 @@ export class HerdrHostRuntime {
         if ((await this.scanLease(allocation.leasePath, allocation.worktreeCwd, context)).length) {
             throw new Error("Agent start requires an empty exact process lease.");
         }
-        await this.assertStartableAgentPane(allocation, context, { requireExclusiveTty: false });
+        await this.assertStartableAgentPane(allocation, context, { requireExclusiveTty: false, awaitIdleShell: true });
         const options = this.processOptions(allocation.worktreeCwd, context, HERDR_OPERATION_CAP_MS);
         const handle = await acquireLaunch();
         return await withTransientLaunch(handle, async (launch) => {
@@ -872,6 +909,7 @@ export class HerdrHostRuntime {
                 args: [...args, "--session", sessionFile],
                 options,
                 shouldRetry: () => false,
+                freshPane: true,
             });
             if (response.code !== 0 || response.killed) {
                 const failure = safeText(herdrCommandFailure(["agent", "start"], response));
@@ -1055,24 +1093,41 @@ export class HerdrHostRuntime {
             || (pane.agent !== undefined && pane.agent !== null) || pane.agent_status !== "unknown") {
             throw new Error("The exact saved agent pane is not empty and startable in its owned worktree.");
         }
-        const processResponse = await this.herdr.json(["pane", "process-info", "--pane", allocation.paneId], this.processOptions(allocation.worktreeCwd, context, HERDR_OPERATION_CAP_MS));
-        const processResult = resultRecord(processResponse, "Herdr agent pane process-info response");
-        if (processResult.type !== "pane_process_info")
-            throw new Error("Herdr agent pane process-info response has the wrong type.");
-        const processInfo = record(processResult.process_info, "Herdr agent pane process-info");
-        const shellPid = processInfo.shell_pid;
-        const foreground = processInfo.foreground_processes;
-        if (exactString(processInfo.pane_id, "Herdr agent process pane ID") !== allocation.paneId
-            || !Number.isSafeInteger(shellPid) || Number(shellPid) <= 0
-            || processInfo.foreground_process_group_id !== shellPid
-            || !Array.isArray(foreground) || foreground.length !== 1) {
-            throw new Error("The exact saved agent pane process state is not an idle foreground shell.");
-        }
-        const shell = record(foreground[0], "Herdr agent pane foreground process");
-        if (shell.pid !== shellPid || shell.cwd !== allocation.worktreeCwd) {
-            throw new Error("The exact saved agent pane foreground process is not its owned idle shell.");
-        }
-        exactString(shell.name, "Herdr agent pane shell name");
+        let shellPid;
+        for (let poll = 0;; poll += 1) {
+            const processResponse = await this.herdr.json(["pane", "process-info", "--pane", allocation.paneId], this.processOptions(allocation.worktreeCwd, context, HERDR_OPERATION_CAP_MS));
+            const processResult = resultRecord(processResponse, "Herdr agent pane process-info response");
+            if (processResult.type !== "pane_process_info")
+                throw new Error("Herdr agent pane process-info response has the wrong type.");
+            const processInfo = record(processResult.process_info, "Herdr agent pane process-info");
+            if (exactString(processInfo.pane_id, "Herdr agent process pane ID") !== allocation.paneId) {
+                throw new Error("The exact saved agent pane process state is not an idle foreground shell.");
+            }
+            shellPid = processInfo.shell_pid;
+            const foreground = processInfo.foreground_processes;
+            const idleGroup = Number.isSafeInteger(shellPid) && Number(shellPid) > 0
+                && processInfo.foreground_process_group_id === shellPid
+                && Array.isArray(foreground) && foreground.length === 1;
+            const shell = idleGroup ? record(foreground[0], "Herdr agent pane foreground process") : undefined;
+            if (shell && shell.pid === shellPid && shell.cwd === allocation.worktreeCwd) {
+                exactString(shell.name, "Herdr agent pane shell name");
+                break;
+            }
+            if (!options.awaitIdleShell) {
+                if (!idleGroup)
+                    throw new Error("The exact saved agent pane process state is not an idle foreground shell.");
+                throw new Error("The exact saved agent pane foreground process is not its owned idle shell.");
+            }
+            if (poll + 1 >= SHELL_IDLE_MAX_POLLS) {
+                const processes = Array.isArray(foreground)
+                    ? foreground.slice(0, 20).map((process) => `${process?.pid}:${process?.name}`).join(", ")
+                    : "malformed";
+                const diagnostic = safeText(`shell_pid=${shellPid}, foreground_process_group_id=${processInfo.foreground_process_group_id}, foreground=[${processes}]`);
+                throw new Error(`The exact saved agent pane process state is not an idle foreground shell. ${diagnostic}`);
+            }
+            // Only fresh allocation waits for shell startup. Recovery requires an immediate safety proof.
+            await this.delay(SHELL_IDLE_POLL_MS, context.signal);
+        }
         if (!options.requireExclusiveTty)
             return;
         // Herdr's foreground list excludes background jobs, so recovery inventories every process on the shell's controlling TTY.

package/dist/index.js

@@ -12,8 +12,6 @@ export { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, } from "./worktree.js";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
-const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;
-const MULTI_CODEX_EXTENSION = fileURLToPath(import.meta.resolve("@hcflabs/pi-multi-codex/extensions/multi-codex.ts"));
 const ROLE_MCP_EXTENSION = fileURLToPath(new URL("../extensions/role-mcp.ts", import.meta.url));
 const ROLE_TOOLS_EXTENSION = fileURLToPath(new URL("../extensions/role-tools.ts", import.meta.url));
 const GIT_READ_EXTENSION = fileURLToPath(new URL("../extensions/git-read.ts", import.meta.url));
@@ -510,7 +508,6 @@ function prepareRoleLaunchFromSkills(ctx, input, skills) {
     }
     const extensions = [
         ...selectedExtensions,
-        ...(CODEX_ALIAS.test(input.route.model.provider) ? [MULTI_CODEX_EXTENSION] : []),
         // Always loaded: it connects the servers that Role extensions register; `mcps` gates only mcp.json.
         ROLE_MCP_EXTENSION,
         ...(role.tools.includes("git_read") ? [GIT_READ_EXTENSION] : []),

package/dist/runner.d.ts

@@ -193,6 +193,20 @@ export interface HostRuntime {
         outcome: "unknown";
         failure: string;
     }>;
+    /**
+     * Optional. Proves that the exact owned worker is settled with a `stop` Final turn on its latest recorded prompt.
+     * Without this method, `verify` cannot adopt a later candidate.
+     */
+    inspectSettledWorker?(input: {
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        workerId: string;
+    }, context: OperationContext): Promise<{
+        outcome: "settled";
+    } | {
+        outcome: "active" | "unknown";
+        failure: string;
+    }>;
     cleanupHost(input: {
         requestId: ExecuteRequest["id"];
         kind: HostCleanupKind;
@@ -437,6 +451,13 @@ export declare class IsolatedRunner {
     private runCheckBatch;
     private runReview;
     private retainCandidate;
+    private lateAdoptionAvailable;
+    /**
+     * Adopts the later clean committed candidate of the same settled worker. It sends no prompt and uses no correction.
+     * A refusal before the candidate is saved throws and changes no state.
+     * Returns a response when the adopted candidate needs attention. Returns undefined when readiness can continue.
+     */
+    private adoptLateCandidate;
     private verifyRetainedTask;
     private retry;
     private finalize;

package/dist/runner.js

@@ -412,6 +412,22 @@ function correctionEligible(request, attempt) {
                 && sameIdentity(attempt.preliminaryReview.tip, attempt.candidate)
                 && sameIdentity(attempt.preliminaryReview.identityAfter, attempt.candidate)));
 }
+/**
+ * True when `verify` can adopt a later candidate of the same settled worker.
+ * The latest prompt settled without a candidate, and no candidate exists in the prompt lineage.
+ * The worker can still leave a candidate after a false finished reading.
+ */
+function lateAdoptionEligible(task, attempt) {
+    const last = attempt.prompts.at(-1);
+    return task.status === "needs_attention"
+        && !attempt.superseded
+        && !attempt.candidate && !attempt.candidateBase
+        && last?.status === "settled" && !last.candidate
+        && !attempt.prompts.some((prompt) => prompt.status === "ambiguous" || prompt.status === "submitting")
+        && !attempt.termination && !attempt.readiness && !attempt.preliminaryChecks && !attempt.preliminaryReview
+        && Boolean(allocationByKind(attempt, "agent")?.agentName && allocationByKind(attempt, "worktree")?.worktree)
+        && last.preCandidate.head === attempt.waveBase.head;
+}
 function terminal(state) {
     return TERMINAL_RUN_STATUSES.some((status) => status === state.status);
 }
@@ -2925,11 +2941,83 @@ export class IsolatedRunner {
         state.integration.candidates.sort((a, b) => state.tasks.findIndex((item) => item.taskId === a.taskId)
             - state.tasks.findIndex((item) => item.taskId === b.taskId));
     }
+    lateAdoptionAvailable(state, task, attempt) {
+        return Boolean(this.hostRuntime.inspectSettledWorker) && !state.integration.candidates.length
+            && lateAdoptionEligible(task, attempt);
+    }
+    /**
+     * Adopts the later clean committed candidate of the same settled worker. It sends no prompt and uses no correction.
+     * A refusal before the candidate is saved throws and changes no state.
+     * Returns a response when the adopted candidate needs attention. Returns undefined when readiness can continue.
+     */
+    async adoptLateCandidate(handle, task, attempt, scope) {
+        const state = handle.state;
+        const request = changesetTaskRequest(state, task.taskId);
+        const last = attempt.prompts.at(-1);
+        if (last.preCandidate.head !== attempt.waveBase.head) {
+            throw new Error("Late candidate adoption requires a prompt lineage that starts at the wave base.");
+        }
+        const workerId = allocationByKind(attempt, "agent").agentName;
+        const branch = `refs/heads/${allocationByKind(attempt, "worktree").worktree.branch}`;
+        const requireSettled = async () => {
+            const result = await this.callProductive(handle, scope, async (context) => await this.hostRuntime.inspectSettledWorker({
+                task: request, attempt, workerId,
+            }, context));
+            if (result.outcome !== "settled") {
+                throw new Error(`Late candidate adoption requires the exact worker to be settled with a stop Final turn on its latest prompt (${result.outcome}): ${boundedRuntimeText(result.failure, "Settled worker failure")}`);
+            }
+        };
+        await requireSettled();
+        const candidate = runtimeIdentity(await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectRetainedTask({
+            root: state.root, task: request, attempt,
+        }, context)), "Late task candidate identity");
+        if (!isCleanCommitted(candidate) || candidate.branch !== branch || candidate.head === attempt.waveBase.head) {
+            throw new Error("Late candidate adoption requires a new clean committed candidate on the owned branch.");
+        }
+        // A second proof after the Git read shows that the worker stayed settled on the same latest prompt.
+        await requireSettled();
+        last.candidate = candidate;
+        attempt.candidate = candidate;
+        attempt.candidateBase = attempt.waveBase;
+        await this.saveProductive(handle);
+        try {
+            attempt.preliminaryChecks = await this.runCheckBatch(handle, request.checks, candidate, "preliminary", scope, task.taskId);
+            await this.saveProductive(handle);
+            if (!attempt.preliminaryChecks.passed) {
+                this.attention(task, sameIdentity(attempt.preliminaryChecks.identityAfter, candidate)
+                    ? "A declared task check failed on the adopted candidate."
+                    : "A declared task check changed the adopted candidate.");
+                await this.saveProductive(handle);
+                return this.response(state);
+            }
+            if (request.judgment) {
+                attempt.preliminaryReview = await this.runReview(handle, request.judgment.criterion, attempt.candidateBase, candidate, request.judgment.role, request.judgment.modelClass, "preliminary", scope, task.taskId);
+                await this.saveProductive(handle);
+                if (!attempt.preliminaryReview.passed) {
+                    this.attention(task, "Preliminary Judgment did not return exact PASS on the adopted candidate.");
+                    await this.saveProductive(handle);
+                    return this.response(state);
+                }
+            }
+        }
+        catch (error) {
+            this.rethrowStopped(error);
+            this.attention(task, `Adopted candidate validation was interrupted: ${errorText(error)}`);
+            await this.saveProductive(handle);
+            throw error;
+        }
+        return undefined;
+    }
     async verifyRetainedTask(handle, task, scope) {
         const attempt = latestAttempt(task);
         if (attempt.prompts.some((prompt) => prompt.status === "ambiguous")) {
             throw new Error("An ambiguous delivered prompt is retained for inspection or explicit abort and is never replayed.");
         }
+        if (!attempt.candidate && this.lateAdoptionAvailable(handle.state, task, attempt)) {
+            const stopped = await this.adoptLateCandidate(handle, task, attempt, scope);
+            if (stopped)
+                return stopped;
+        }
         const candidate = runtimeIdentity(await this.callProductive(handle, scope, async (context) => await this.gitRuntime.inspectRetainedTask({
             root: handle.state.root, task: changesetTaskRequest(handle.state, task.taskId), attempt,
         }, context)), "Retained task candidate identity");
@@ -3334,7 +3422,7 @@ export class IsolatedRunner {
                 else if (attempt && this.correctionAllowed(state, changesetTaskRequest(state, attention.taskId), attempt)) {
                     continuation = { id: state.request.id, action: "retry", taskId: attention.taskId };
                 }
-                else if (hasEvidence) {
+                else if (hasEvidence || (attempt && this.lateAdoptionAvailable(state, attention, attempt))) {
                     continuation = { id: state.request.id, action: "verify", taskId: attention.taskId };
                 }
             }

package/docs/orchestration.md

@@ -281,6 +281,8 @@ Every task declares `id`, `kind`, `role`, `modelClass`, `requirements`, `deliver
 
 Admission and worker-wave dispatch pin Main's exact committed branch, HEAD, and tree without inspecting or modifying its staged, unstaged, or untracked edits. Worker allocation verifies the same committed identity around worktree creation, including resumed waves; staged-dependent waves verify their clean integration snapshot. A dirty Main can therefore produce a checked retained candidate, but branch/HEAD drift stops new waves. The runner executes ready worker tasks concurrently, inspects clean committed candidates, runs preliminary task checks and optional preliminary judgment, then records ready candidates for Main. **It does not automatically integrate them.**
 
+The extension waits up to about 10 seconds for the shell of a new worker pane to finish startup before it starts Pi.
+
 Main selects exact candidates through `subagent_stage` into an owned integration checkout in explicit order. Each stage is a committed merge of the candidate, not a mutation of Main. Conflicts retain the checkout for Main to resolve; `resolve` verifies the exact two-parent merge instead of replaying an uncertain merge. Main can explicitly run dependent tasks from an exact staged tip with `subagent_integrate advance` and stage their results afterward. Independent candidates may be staged without re-running workers.
 
 Once all selected work is staged, Main calls `subagent_integrate validate` on the exact clean combined tip. It acknowledges the durably saved validation intent and continues in the session-owned background, independent of later turn cancellation; session replacement/shutdown still cancels it. A follow-up reports completion; status remains authoritative if delivery is missed. This runs every final check, including `pnpm test`, unless [exact check reuse](#validate-and-promote) applies, and optional final judgment in the integration checkout before any Main mutation. A failed check/review can be followed by one Main-authored committed correction in that checkout, recorded with `correct`, then another `validate`.
@@ -406,6 +408,8 @@ Parsing rejects unknown properties, malformed evidence, invalid lineage, and v4
 
 Isolated workers save private exact Pi sessions under their owned process leases. A proved final answer without a changed clean commit requires attention. Missing or mismatched session proof cannot establish completion and never permits prompt replay.
 
+A worker can leave a clean committed candidate after the runner records its turn as finished without one. `verify` can adopt that candidate after it proves that the same owned worker is settled with a `stop` Final turn on its latest prompt. The candidate then passes the task's normal preliminary checks and judgment before readiness. Adoption sends no prompt and uses no correction. It never replaces a saved candidate. While the same-worker correction is available, the reported continuation is `retry`.
+
 When a finished turn leaves tracked or untracked changes in a valid owned worktree, the runner sends one commit reminder per dispatch try. It saves the reminder before delivery. This uses neither a correction nor a dispatch try. The runner never commits, stages, stashes, or discards. A resulting commit follows normal candidate checks; remaining dirty work requires attention.
 
 `subagent_status` stays read-only and authoritative if delivery fails. Session replacement or shutdown suppresses stale follow-ups and logs the request ID and reason, not prompts or credentials. Synchronous delivery failures report without automatic replay. Pi reports asynchronous `send_message` failures through its runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hcflabs/pi-subagent",
-  "version": "28.3.0",
+  "version": "28.3.2",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -71,8 +71,7 @@
   },
   "dependencies": {
     "@hcflabs/pi-config-store": "^4.0.0",
-    "@hcflabs/pi-herdr": "^0.6.0",
-    "@hcflabs/pi-multi-codex": "^3.0.0",
+    "@hcflabs/pi-herdr": "^0.7.0",
     "@hcflabs/pi-process": "^0.3.0",
     "@hcflabs/pi-repo": "^0.1.0",
     "@hcflabs/pi-task-models": "^9.0.0",