pi-subagents 0.82.0 → 0.83.0

package/src/api/background-work.js

@@ -4,7 +4,7 @@ const MAX_PROVIDER_NAME_LENGTH = 128;
 const MAX_PROVIDERS = 100;
 const MAX_ITEM_ID_LENGTH = 256;
 /**
- * A Pi session id is the session file path, which routinely exceeds a short
+ * A session can be identified by its file path, which routinely exceeds a short
  * identity budget in nested worktrees, so it is bounded like the other paths.
  */
 const MAX_SESSION_ID_LENGTH = 4_096;
@@ -120,22 +120,29 @@ export function listBackgroundWorkWakeChannels() {
     }
     return [...channels];
 }
-/** Reconcile and snapshot active provider work owned by one exact Pi session. */
-export function snapshotBackgroundWork(sessionId, nowMs = Date.now()) {
-    validateString(sessionId, "Background-work snapshot sessionId", MAX_SESSION_ID_LENGTH);
+/**
+ * Reconcile and snapshot active provider work owned by one exact Pi session.
+ * `sessionIds` lists that session's identity forms; the first is passed to
+ * providers as `sessionId`, and items keyed by any of them are kept.
+ */
+export function snapshotBackgroundWork(sessionIds, nowMs = Date.now()) {
+    const accepted = [...new Set(sessionIds.map((value) => validateString(value, "Background-work snapshot sessionId", MAX_SESSION_ID_LENGTH)))];
+    const sessionId = accepted[0];
+    if (sessionId === undefined)
+        throw new Error("Background-work snapshot needs at least one session id.");
     const providers = listBackgroundWorkProviders();
     const items = [];
     const identities = new Set();
     for (const provider of providers) {
         try {
-            provider.reconcile?.({ sessionId, nowMs });
+            provider.reconcile?.({ sessionId, sessionIds: [...accepted], nowMs });
         }
         catch (error) {
             throw new Error(`Background-work provider '${provider.name}' reconcile failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
         }
         let active;
         try {
-            active = provider.listActiveWork({ sessionId, nowMs });
+            active = provider.listActiveWork({ sessionId, sessionIds: [...accepted], nowMs });
         }
         catch (error) {
             throw new Error(`Background-work provider '${provider.name}' listActiveWork failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
@@ -153,7 +160,7 @@ export function snapshotBackgroundWork(sessionId, nowMs = Date.now()) {
                 throw new Error(`Background-work provider '${provider.name}' returned duplicate item '${item.id}' for session '${item.sessionId}'.`);
             }
             identities.add(identity);
-            if (item.sessionId === sessionId)
+            if (accepted.includes(item.sessionId))
                 items.push({ provider: provider.name, ...item });
         });
     }

package/src/extension/index.js

@@ -566,8 +566,11 @@ export default function registerSubagentExtension(pi) {
     // Pi sends custom messages to the model as plain user messages, so every model-visible
     // pi-subagents message is wrapped in a marker naming its source. The marker depends only on
     // the message, so history renders the same bytes every turn and cached prefixes stay valid.
+    // It runs on context_with_system, not context: Pi treats any change a context handler makes
+    // to the message list as a rewritten conversation and folds every mid-conversation system
+    // message into the leading one, which misses the prompt cache on every later turn.
     const markedMessageTypes = new Set([...SUBAGENT_MESSAGE_TYPES, "subagent-compaction-resume", SLASH_RESULT_TYPE, SLASH_TEXT_RESULT_TYPE, ADMIN_MESSAGE_TYPE]);
-    pi.on("context", (event) => {
+    pi.on("context_with_system", (event) => {
         const messages = [];
         for (const message of event.messages) {
             if (message.role !== "custom" || !markedMessageTypes.has(message.customType)) {

package/src/extension/public-execution.d.ts

@@ -57,8 +57,8 @@ export type PublicSubagentExecutionNormalization<T> = {
 /** A workflow value containing "/" or "\" is a script path; named workflow resource names contain neither. */
 export declare function isWorkflowScriptPath(workflow: string): boolean;
 /**
- * Model tool calls supply script text only through workflow: true (the reply block) or a script path.
- * workflowScript remains the internal carrier for slash, prompt-workflow, scheduled, RPC, and named-resource launches.
+ * Model tool calls supply script text through workflow: true (the reply block), a script path, or options.script,
+ * which flattenSubagentToolOptions lowers to workflowScript, the internal carrier for every other launch path too.
  */
 export declare function removedModelWorkflowFieldError(params: object): string | undefined;
 export declare function validateWorkflowCapacityOverrides(params: PublicSubagentExecutionParams): string | undefined;

package/src/extension/public-execution.js

@@ -7,8 +7,8 @@ export function isWorkflowScriptPath(workflow) {
     return workflow.includes("/") || workflow.includes("\\");
 }
 /**
- * Model tool calls supply script text only through workflow: true (the reply block) or a script path.
- * workflowScript remains the internal carrier for slash, prompt-workflow, scheduled, RPC, and named-resource launches.
+ * Model tool calls supply script text through workflow: true (the reply block), a script path, or options.script,
+ * which flattenSubagentToolOptions lowers to workflowScript, the internal carrier for every other launch path too.
  */
 export function removedModelWorkflowFieldError(params) {
     if (Object.hasOwn(params, "workflowScript"))
@@ -56,7 +56,7 @@ export function normalizePublicSubagentExecution(params, options = {}) {
         return { ok: false, error: "workflow must be true (the ```js workflow block in this reply), a script path containing '/', or a named workflow resource.", mode: "workflow" };
     }
     const hasNamedWorkflow = typeof workflow === "string" && !isWorkflowScriptPath(workflow);
-    // workflowScript is the internal script carrier; model tool calls cannot set it.
+    // workflowScript is the internal script carrier; model tool calls set it only through options.script.
     if (workflow !== undefined && params.workflowScript !== undefined) {
         return { ok: false, error: "workflow cannot be combined with an internal workflowScript.", mode: "workflow" };
     }

package/src/extension/reply-workflow-script.js

@@ -2,7 +2,9 @@ const WORKFLOW_FENCE = /^```(?:js|javascript) workflow[ \t]*$/;
 const PLAIN_JS_FENCE = /^```(?:js|javascript)[ \t]*$/;
 const OPEN_FENCE = /^(`{3,}|~{3,})/;
 const CLOSE_FENCE = /^(`{3,}|~{3,})[ \t]*$/;
-const FILE_FALLBACK = "Or write the script to a file and pass its path, such as workflow: \"./script.js\".";
+// Through the Claude Agent SDK (pi-claude-bridge#35), text written after a tool call in the same turn reaches the session
+// only as a server summary, which drops fenced blocks; retrying the block fails again. Tool arguments arrive intact.
+const SUMMARY_NOTE = "On some hosts, text written after a tool call in the same turn reaches the session only as a summary without code blocks, so for the rest of this turn pass the script's source as a tool argument: options: { script: \"...\" } in place of workflow: true, with the call's other fields unchanged.";
 /**
  * Pi persists the whole assistant message before running its tool calls, so the
  * message that issued this subagent call is on the branch and carries the script.
@@ -28,7 +30,7 @@ function scriptFromReply(content) {
     if (replyCalls > 1)
         return { error: `This reply has ${replyCalls} subagent calls with workflow: true; a reply can carry only one. Pass other scripts as workflow file paths.` };
     if (!content.some((block) => block.type === "text"))
-        return { error: "The assistant message that issued this call has no text in the session, so the reply's visible text, including any ```js workflow block, never reached it. Write the script to a file and pass its path, such as workflow: \"./script.js\"." };
+        return { error: `The assistant message that issued this call has no text in the session, so the reply's visible text, including any \`\`\`js workflow block, never reached it. ${SUMMARY_NOTE}` };
     const text = content.flatMap((block) => block.type === "text" && typeof block.text === "string" ? [block.text] : []).join("\n");
     const { tagged, plain, unclosed } = workflowBlocks(text);
     if (unclosed)
@@ -37,7 +39,7 @@ function scriptFromReply(content) {
     const blocks = tagged.length > 0 ? tagged : plain.length === 1 ? plain : [];
     if (blocks.length !== 1) {
         const untagged = tagged.length === 0 && plain.length > 1 ? ` This reply has ${plain.length} untagged js blocks; open the script's block with the line "\`\`\`js workflow".` : "";
-        return { error: `workflow: true needs one fenced block in the same reply as the tool call, opened with the exact line "\`\`\`js workflow" and closed with "\`\`\`"; found ${tagged.length}.${untagged} ${FILE_FALLBACK}` };
+        return { error: `workflow: true needs one fenced block in the same reply as the tool call, opened with the exact line "\`\`\`js workflow" and closed with "\`\`\`"; found ${tagged.length}.${untagged} If the block is in your reply: ${SUMMARY_NOTE}` };
     }
     const script = blocks[0];
     if (!script.trim())

package/src/extension/rpc.js

@@ -5,7 +5,7 @@ import { deliverAsyncRunStop } from "../runs/foreground/async-stop-action.js";
 import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.js";
 import { resolveCurrentSessionId } from "../shared/session-identity.js";
 import { ownerSessionIds, ownsRun } from "../runs/shared/run-ownership.js";
-import { DIRS, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_PROCESS_TERMINAL_EVENT, SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, } from "../shared/types.js";
+import { DIRS, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_ASYNC_STARTED_EVENT, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_JOBS_CHANGED_EVENT, SUBAGENT_PROCESS_TERMINAL_EVENT, SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, } from "../shared/types.js";
 import { sanitizeDisplayText, truncateDisplayText } from "../shared/display-text.js";
 import { readStatus } from "../shared/utils.js";
 import { SubagentFlatParams } from "./schemas.js";
@@ -336,8 +336,10 @@ function pingData(ctx, options) {
             request: SUBAGENT_RPC_REQUEST_EVENT,
             replyPrefix: SUBAGENT_RPC_REPLY_EVENT_PREFIX,
             asyncComplete: SUBAGENT_ASYNC_COMPLETE_EVENT,
+            asyncStarted: SUBAGENT_ASYNC_STARTED_EVENT,
             childStatus: SUBAGENT_CHILD_STATUS_EVENT,
             processTerminal: SUBAGENT_PROCESS_TERMINAL_EVENT,
+            jobsChanged: SUBAGENT_JOBS_CHANGED_EVENT,
         },
         session: sessionData(ctx),
     };

package/src/extension/subagent-guide.js

@@ -19,11 +19,10 @@ export const SUBAGENT_GUIDE_TOPICS = [
 const SUBAGENT_GUIDE_SECTION_MAX_CHARS = 8000;
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 // /council must work under `pi --no-skills`, which drops the package skills from context,
-// so this topic serves the council skill together with the references it tells the model to read.
+// so this topic serves the council skill together with the reference it tells the model to read.
 const COUNCIL_FILES = [
     "skills/council-mode/SKILL.md",
     "skills/council-mode/references/pass-contracts.md",
-    "skills/pi-subagents/references/execution-controls.md",
 ];
 function isGuideTopic(value) {
     return SUBAGENT_GUIDE_TOPICS.includes(value);

package/src/extension/subagent-options.js

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { Compile } from "typebox/compile";
+import { Value } from "typebox/value";
 import { closestMatch } from "../shared/edit-distance.js";
 import { removedModelWorkflowFieldError } from "./public-execution.js";
 import { SUBAGENT_OPTION_KEYS, SubagentOptionParams, createSubagentParamsSchema } from "./schemas.js";
@@ -22,6 +23,15 @@ export function flattenSubagentToolOptions(params, disabled) {
     const removedField = removedModelWorkflowFieldError(options);
     if (removedField)
         throw new Error(removedField);
+    // options.script carries script text as a tool argument for hosts that drop the reply's ```js block (SUMMARY_NOTE).
+    const { script, ...rest } = options;
+    if (script !== undefined) {
+        if (typeof script !== "string" || !script.trim())
+            throw new Error("subagent: options.script must be the workflow script's source text.");
+        if (topLevel.workflow !== undefined)
+            throw new Error("subagent: options.script replaces workflow; pass only one of them.");
+        return { ...flattenSubagentToolOptions({ ...topLevel, options: rest }, disabled), workflowScript: script };
+    }
     const entries = Object.entries(options);
     const enabledKeys = SUBAGENT_OPTION_KEYS.filter((key) => !disabled?.params.has(key));
     const unknown = entries.map(([key]) => key).filter((key) => !optionKeys.has(key));
@@ -40,12 +50,15 @@ export function flattenSubagentToolOptions(params, disabled) {
     const disabledKey = entries.find(([key]) => disabled?.params.has(key))?.[0];
     if (disabledKey)
         throw new Error(`subagent option 'options.${disabledKey}' is disabled by config ${disabled.params.get(disabledKey)}.`);
-    if (!optionsValidator.Check(options)) {
-        const errors = [...optionsValidator.Errors(options)].slice(0, 4).map((error) => `options${error.instancePath.replaceAll("/", ".")} ${error.message}`);
+    // Pi converts only the declared top-level parameters ("true" -> true); `options` is an untyped bag in the
+    // tool schema, so its values get the same conversion here. Some providers send nested scalars as strings.
+    const converted = Value.Convert(SubagentOptionParams, structuredClone(options));
+    if (!optionsValidator.Check(converted)) {
+        const errors = [...optionsValidator.Errors(converted)].slice(0, 4).map((error) => `options${error.instancePath.replaceAll("/", ".")} ${error.message}`);
         throw new Error(`subagent: ${errors.join("; ")}.`);
     }
-    const conflicts = entries.filter(([key, value]) => topLevel[key] !== undefined && !isDeepStrictEqual(topLevel[key], value)).map(([key]) => `'${key}'`);
+    const conflicts = Object.entries(converted).filter(([key, value]) => topLevel[key] !== undefined && !isDeepStrictEqual(topLevel[key], value)).map(([key]) => `'${key}'`);
     if (conflicts.length > 0)
         throw new Error(`subagent: ${conflicts.join(", ")} given both at the top level and in options with different values; give each once.`);
-    return { ...topLevel, ...options };
+    return { ...topLevel, ...converted };
 }

package/src/runs/background/async-execution.js

@@ -13,7 +13,7 @@ import { childCacheRetentionEnv } from "../../shared/child-cache-retention.js";
 import { buildEffectiveSystemPrompt } from "../shared/effective-system-prompt.js";
 import { currentCompletionOwnerId } from "../../shared/completion-owner.js";
 import { planChildLaunch, projectChainOutputSchemas, resolveStepBehavior, suppressProgressForReadOnlyTask } from "../shared/child-launch-plan.js";
-import { formatHerdrMachineRunnerUnsupported, resolveMachinePlacement } from "../shared/herdr-machine.js";
+import { formatHerdrMachineRunnerUnsupported, PLACED_RESTORE_UNSUPPORTED, resolveMachinePlacement } from "../shared/herdr-machine.js";
 import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/child-tool-plan.js";
 import { assertClaudeCodeModelScope, isClaudeCodeAdapterId, resolveClaudeCodeOverride } from "../shared/claude-code-adapter.js";
 import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.js";
@@ -1612,6 +1612,9 @@ export function executeAsyncSingle(id, params) {
     const machineUnsupported = formatHerdrMachineRunnerUnsupported({ machine: requestedMachine, agentName: agentConfig.name, runnerType: agentConfig.runner?.type, adapter: agentConfig.runner?.type === "external-cli" ? agentConfig.runner.adapter : undefined, worktree: params.worktree });
     if (machineUnsupported)
         return formatAsyncStartError("single", machineUnsupported);
+    // Refuse before the runner starts; the placed launch would refuse only after the run exists.
+    if (requestedMachine && params.revivalLease)
+        return formatAsyncStartError("single", PLACED_RESTORE_UNSUPPORTED);
     const resolvedLauncher = resolveAgentRunnerLauncher(agentConfig, ctx.runnerLaunchers, requestedMachine);
     if (resolvedLauncher.error)
         return formatAsyncStartError("single", resolvedLauncher.error);

package/src/runs/background/async-job-tracker.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { renderWidget, widgetRenderKey } from "../../tui/render.js";
 import { formatControlNoticeMessage } from "../shared/subagent-control.js";
-import { DIRS, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_CONTROL_EVENT, SUBAGENT_CONTROL_INTERCOM_EVENT, SUBAGENT_STEERING_NOTICE_EVENT, WIDGET_ANIMATION_INTERVAL_MS, } from "../../shared/types.js";
+import { DIRS, SUBAGENT_CHILD_STATUS_EVENT, SUBAGENT_CONTROL_EVENT, SUBAGENT_CONTROL_INTERCOM_EVENT, SUBAGENT_JOBS_CHANGED_EVENT, SUBAGENT_STEERING_NOTICE_EVENT, WIDGET_ANIMATION_INTERVAL_MS, } from "../../shared/types.js";
 import { readStatus, resolveWatchPath } from "../../shared/utils.js";
 import { normalizeParallelGroups } from "./parallel-groups.js";
 import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.js";
@@ -63,6 +63,7 @@ export function createAsyncJobTracker(pi, state, asyncDirRoot, options = {}) {
     };
     const rerenderWidget = (ctx, jobs = Array.from(state.asyncJobs.values())) => {
         options.onJobsChanged?.();
+        pi.events.emit(SUBAGENT_JOBS_CHANGED_EVENT, { version: 1 });
         if (state.widgetsSuspended)
             return;
         renderWidget(ctx, options.widgetEnabled === false ? [] : jobs, options.widgetCollapsed, options.widgetLayout);

package/src/runs/background/async-status.d.ts

@@ -144,6 +144,8 @@ interface AsyncRunListOptions {
     repairScan?: boolean;
     /** This process's completion owner, adopted by an owner-exited workflow repair of a run the session owns; needs `sessionId`. */
     adoptCompletionOwnerId?: string;
+    /** Receives the warning for a skipped corrupt terminal status, so an open TUI can show it as a notice instead of console output. */
+    onCorruptStatus?: (warning: string) => void;
 }
 type TargetedAsyncRunResolution = {
     kind: "exact";

package/src/runs/background/async-status.js

@@ -404,7 +404,7 @@ export function listAsyncRuns(asyncDirRoot, options = {}, observeStatus) {
             }
             if (wantsTerminal) {
                 for (const sessionId of owners ?? [undefined]) {
-                    for (const entry of readRecentTerminalRunIndex(asyncDirRoot, { sessionId, ...(options.entryLimit !== undefined ? { limit: options.entryLimit } : {}) }))
+                    for (const entry of readRecentTerminalRunIndex(asyncDirRoot, { sessionId, onCorruptStatus: options.onCorruptStatus, ...(options.entryLimit !== undefined ? { limit: options.entryLimit } : {}) }))
                         indexed.add(entry);
                 }
             }

package/src/runs/background/auto-drain.js

@@ -1,6 +1,5 @@
-import { snapshotBackgroundWork } from "../../api/background-work.js";
 import { listAsyncRuns } from "./async-status.js";
-import { waitForSubagents, waitRunScopes } from "./subagent-wait.js";
+import { backgroundWorkForSession, waitForSubagents, waitRunScopes } from "./subagent-wait.js";
 export const DEFAULT_AUTO_DRAIN_TIMEOUT_MS = 30 * 60 * 1000;
 function resultText(value) {
     return value.content.map((part) => part.type === "text" ? part.text : "").join(" ").trim();
@@ -14,7 +13,7 @@ function hasOutstandingWork(deps, sessionId, nowMs, observation) {
         includeNested: false,
     }, observation?.status));
     const detachedForeground = [...(deps.state.foregroundRuns?.values() ?? [])].some((run) => run.sessionId === sessionId && run.children.some((child) => child.status === "detached"));
-    return asyncRuns.length > 0 || snapshotBackgroundWork(sessionId, nowMs).items.length > 0 || detachedForeground;
+    return asyncRuns.length > 0 || backgroundWorkForSession(deps, nowMs).items.length > 0 || detachedForeground;
 }
 /** Drain all work owned by the current headless session, including work added while draining. */
 export async function drainOutstandingWork(deps, observation) {

package/src/runs/background/fleet-view.js

@@ -164,7 +164,7 @@ function sessionMessageParts(record) {
         }
         if (entry.type === "toolCall" || entry.type === "tool_call") {
             const name = typeof entry.name === "string" ? entry.name : typeof entry.toolName === "string" ? entry.toolName : "tool";
-            parts.push({ role, kind: "toolCall", name, text: `[tool: ${name}${entry.args === undefined ? "" : ` ${stringifyJsonPreview(entry.args)}`}]` });
+            parts.push({ role, kind: "toolCall", name, text: `[tool: ${name}${entry.arguments === undefined ? "" : ` ${stringifyJsonPreview(entry.arguments)}`}]` });
             continue;
         }
         if (entry.type === "toolResult" || entry.type === "tool_result") {

package/src/runs/background/run-child-session.js

@@ -69,6 +69,8 @@ export function runChildSession(input) {
         let queuedDrainHold = false;
         let compactionStartedReceived = false;
         let afterCompactionSettlement = false;
+        let terminalAgentEndReceived = false;
+        let compactionAfterFinalOpen = false;
         let finalDrainTimer;
         let finalHardFinishTimer;
         let watchdogTailTimer;
@@ -216,7 +218,8 @@ export function runChildSession(input) {
             finalDrainTimer = setTimeout(() => {
                 if (settled || promptSettled)
                     return;
-                if (input.launch.capture.finalDrainHeld() || observeQueuedDrainHold()) {
+                // Pi runs auto-compaction after the final agent_end and only then emits agent_settled.
+                if (input.launch.capture.finalDrainHeld() || observeQueuedDrainHold() || compactionAfterFinalOpen) {
                     finalDrainTimer = undefined;
                     armFinalDrainTimer();
                     return;
@@ -231,16 +234,22 @@ export function runChildSession(input) {
                         return;
                     settle(undefined, true);
                 }, HARD_FINISH_MS);
-                finalHardFinishTimer.unref?.();
             }, FINAL_STOP_GRACE_MS);
-            finalDrainTimer.unref?.();
         }
-        const applyChildLifecycle = (action) => {
+        const applyChildLifecycle = (action, event) => {
             if (action === "cancel-drain") {
-                cleanTerminalAssistantStopReceived = false;
+                // After a clean final stop, a non-retrying agent_end may be the child's last event
+                // (Pi may not emit agent_settled), so it re-arms the drain instead of cancelling it.
+                terminalAgentEndReceived = event?.type === "agent_end" && event.willRetry !== true && cleanTerminalAssistantStopReceived;
                 agentSettledReceived = false;
                 clearFinalDrainTimers();
                 clearWatchdogTailTimer();
+                if (terminalAgentEndReceived) {
+                    startFinalDrain();
+                    return;
+                }
+                cleanTerminalAssistantStopReceived = false;
+                compactionAfterFinalOpen = false;
                 return;
             }
             if (action === "start-drain")
@@ -314,11 +323,18 @@ export function runChildSession(input) {
                 compactionStartedReceived = true;
                 if (agentSettledReceived)
                     afterCompactionSettlement = true;
+                if (terminalAgentEndReceived)
+                    compactionAfterFinalOpen = true;
             }
             if (event.type === "compaction_end" && event.willRetry === true) {
                 compactionStartedReceived = false;
                 afterCompactionSettlement = false;
             }
+            if (event.type === "compaction_end" && event.willRetry !== true && compactionAfterFinalOpen) {
+                compactionAfterFinalOpen = false;
+                clearFinalDrainTimers();
+                startFinalDrain();
+            }
             if (event.type === "turn_start" || event.type === "agent_start" || event.type === "auto_retry_start") {
                 queuedDrainHold = false;
             }
@@ -331,7 +347,7 @@ export function runChildSession(input) {
                 agentSettledReceived = true;
                 afterCompactionSettlement = compactionStartedReceived;
             }
-            applyChildLifecycle(lifecycleAction);
+            applyChildLifecycle(lifecycleAction, event);
             if (isChildWatchdogStatusEvent(event)) {
                 if (!input.childWatchdog)
                     return;

package/src/runs/background/subagent-wait.d.ts

@@ -100,7 +100,7 @@ export interface SubagentWaitDeps {
     };
     /** Injectable provider protocol surfaces for deterministic tests. */
     backgroundWork?: {
-        snapshot(sessionId: string, nowMs: number): BackgroundWorkSnapshot;
+        snapshot(sessionIds: readonly string[], nowMs: number): BackgroundWorkSnapshot;
         wakeChannels(): readonly string[];
     };
     /**
@@ -111,6 +111,7 @@ export interface SubagentWaitDeps {
      */
     events?: WaitEventBus;
 }
+export declare function backgroundWorkForSession(deps: Pick<SubagentWaitDeps, "state" | "backgroundWork">, nowMs: number): BackgroundWorkSnapshot;
 export declare function waitRunScopes(deps: Pick<SubagentWaitDeps, "asyncDirRoot" | "resultsDir" | "nestedRootRunId">): Array<{
     asyncDirRoot: string;
     resultsDir: string;

package/src/runs/background/subagent-wait.js

@@ -181,11 +181,14 @@ function hasSupervisorTool(run) {
 function backgroundWorkIdentity(item) {
     return `${item.provider}\0${item.sessionId}\0${item.id}`;
 }
-function backgroundWorkForSession(deps, nowMs) {
+export function backgroundWorkForSession(deps, nowMs) {
     const sessionId = deps.state.currentSessionId;
     if (!sessionId)
         throw new Error("bg_wait requires an active session identity to scope background work safely.");
-    return deps.backgroundWork?.snapshot(sessionId, nowMs) ?? snapshotBackgroundWork(sessionId, nowMs);
+    // Providers may key items by the session file path or by getSessionId(); accept both.
+    const piSessionId = deps.state.supervisorOwnerSessionId;
+    const sessionIds = piSessionId ? [sessionId, piSessionId] : [sessionId];
+    return deps.backgroundWork?.snapshot(sessionIds, nowMs) ?? snapshotBackgroundWork(sessionIds, nowMs);
 }
 export function waitRunScopes(deps) {
     return [

package/src/runs/background/terminal-run-index.d.ts

@@ -6,4 +6,5 @@ export declare function readRecentTerminalRunIndex(asyncDirRoot: string, options
     sessionId?: string;
     limit?: number;
     endedAfter?: number;
+    onCorruptStatus?: (warning: string) => void;
 }): string[];

package/src/runs/background/terminal-run-index.js

@@ -12,6 +12,35 @@ const TOOL_CALL_INDEX_DIR = "@tool-calls";
 function isTerminalState(state) {
     return state === "complete" || state === "failed" || state === "partial" || state === "paused" || state === "stopped" || state === "rejected";
 }
+function isCorruptStatusError(error, statusPath) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.startsWith(`Failed to parse async status file '${statusPath}'`)
+        || message.startsWith(`Failed to validate async status file '${statusPath}'`);
+}
+// A corrupt indexed status is retried on every read. Emit a warning only when
+// its observed file identity or parse outcome changes, like active-run diagnostics.
+const reportedCorruptTerminalStatus = new Map();
+function warnCorruptTerminalStatus(runId, statusPath, error, onCorruptStatus) {
+    let fileSignature = "unavailable";
+    try {
+        const stat = fs.statSync(statusPath);
+        fileSignature = `${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}:${stat.ino}`;
+    }
+    catch (statError) {
+        if (statError.code !== "ENOENT")
+            throw statError;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const signature = `${fileSignature}\n${message}`;
+    if (reportedCorruptTerminalStatus.get(statusPath) === signature)
+        return;
+    reportedCorruptTerminalStatus.set(statusPath, signature);
+    const warning = `Skipping indexed terminal run '${runId}' with corrupt status at '${statusPath}': ${message}`;
+    if (onCorruptStatus)
+        onCorruptStatus(warning);
+    else
+        console.error(`[pi-subagents] ${warning}`);
+}
 function indexRoot(asyncDirRoot) {
     return path.join(asyncDirRoot, TERMINAL_RUN_INDEX_DIR);
 }
@@ -154,7 +183,17 @@ export function readRecentTerminalRunIndex(asyncDirRoot, options = {}) {
             continue;
         }
         const asyncDir = path.join(asyncDirRoot, entry.runId);
-        const status = readStatus(asyncDir);
+        const statusPath = path.join(asyncDir, "status.json");
+        let status;
+        try {
+            status = readStatus(asyncDir);
+        }
+        catch (error) {
+            if (!isCorruptStatusError(error, statusPath))
+                throw error;
+            warnCorruptTerminalStatus(entry.runId, statusPath, error, options.onCorruptStatus);
+            continue;
+        }
         if (!status || !isTerminalState(status.state) || status.sessionId !== entry.sessionId || (status.runId && status.runId !== entry.runId)) {
             removeInvalidMarker(marker);
             continue;

package/src/runs/foreground/execution.js

@@ -561,6 +561,8 @@ async function runSingleAttempt(runtimeCwd, agent, task, model, options, shared)
         let agentSettledReceived = false;
         let queuedDrainHold = false;
         let compactionStartedReceived = false;
+        let terminalAgentEndReceived = false;
+        let compactionAfterFinalOpen = false;
         let finalDrainTimer;
         let finalHardFinishTimer;
         let watchdogTailTimer;
@@ -608,7 +610,8 @@ async function runSingleAttempt(runtimeCwd, agent, task, model, options, shared)
             finalDrainTimer = setTimeout(() => {
                 if (lifecycleFinished || sessionSettled)
                     return;
-                if (capture.finalDrainHeld() || observeQueuedDrainHold()) {
+                // Pi runs auto-compaction after the final agent_end and only then emits agent_settled.
+                if (capture.finalDrainHeld() || observeQueuedDrainHold() || compactionAfterFinalOpen) {
                     finalDrainTimer = undefined;
                     armFinalDrainTimer();
                     return;
@@ -623,9 +626,7 @@ async function runSingleAttempt(runtimeCwd, agent, task, model, options, shared)
                         return;
                     settle(undefined, true);
                 }, HARD_FINISH_MS);
-                finalHardFinishTimer.unref?.();
             }, FINAL_STOP_GRACE_MS);
-            finalDrainTimer.unref?.();
         };
         function armWatchdogTail() {
             if ((!cleanTerminalAssistantStopReceived && !agentSettledReceived) || watchdogTailTimer || lifecycleFinished || sessionSettled)
@@ -644,12 +645,20 @@ async function runSingleAttempt(runtimeCwd, agent, task, model, options, shared)
             }, childWatchdog?.watchdogTailTimeoutMs ?? 120_000);
             watchdogTailTimer.unref?.();
         }
-        const applyChildLifecycle = (action) => {
+        const applyChildLifecycle = (action, event) => {
             if (action === "cancel-drain") {
-                cleanTerminalAssistantStopReceived = false;
+                // After a clean final stop, a non-retrying agent_end may be the child's last event
+                // (Pi may not emit agent_settled), so it re-arms the drain instead of cancelling it.
+                terminalAgentEndReceived = event?.type === "agent_end" && event.willRetry !== true && cleanTerminalAssistantStopReceived;
                 agentSettledReceived = false;
                 clearFinalDrainTimers();
                 clearWatchdogTailTimer();
+                if (terminalAgentEndReceived) {
+                    startFinalDrain();
+                    return;
+                }
+                cleanTerminalAssistantStopReceived = false;
+                compactionAfterFinalOpen = false;
                 return;
             }
             if (action === "start-drain")
@@ -925,11 +934,18 @@ async function runSingleAttempt(runtimeCwd, agent, task, model, options, shared)
                 compactionStartedReceived = true;
                 if (agentSettledReceived)
                     afterCompactionSettlement = true;
+                if (terminalAgentEndReceived)
+                    compactionAfterFinalOpen = true;
             }
             if (evt.type === "compaction_end" && evt.willRetry === true) {
                 compactionStartedReceived = false;
                 afterCompactionSettlement = false;
             }
+            if (evt.type === "compaction_end" && evt.willRetry !== true && compactionAfterFinalOpen) {
+                compactionAfterFinalOpen = false;
+                clearFinalDrainTimers();
+                startFinalDrain();
+            }
             if (evt.type === "turn_start" || evt.type === "agent_start" || evt.type === "auto_retry_start") {
                 queuedDrainHold = false;
             }
@@ -956,7 +972,7 @@ async function runSingleAttempt(runtimeCwd, agent, task, model, options, shared)
                 agentSettledReceived = true;
                 afterCompactionSettlement = compactionStartedReceived;
             }
-            applyChildLifecycle(lifecycleAction);
+            applyChildLifecycle(lifecycleAction, evt);
             if (isChildWatchdogStatusEvent(evt)) {
                 if (!childWatchdog)
                     return;

package/src/runs/foreground/subagent-executor.js

@@ -17,7 +17,7 @@ import { buildDoctorReport } from "../../extension/doctor.js";
 import { readSubagentGuide } from "../../extension/subagent-guide.js";
 import { isWorkflowScriptPath, normalizePublicSubagentExecution, validateWorkflowCapacityOverrides } from "../../extension/public-execution.js";
 import { readReplyWorkflowScript } from "../../extension/reply-workflow-script.js";
-import { disabledFeatureNotice, disabledFeatureUseError, resolveDisabledFeatureSurface } from "../../shared/disabled-features.js";
+import { disabledFeatureNotice, disabledFeatureSectionNotice, disabledFeatureUseError, resolveDisabledFeatureSurface } from "../../shared/disabled-features.js";
 import { runSync } from "./execution.js";
 import { commandAction } from "./command-action.js";
 import { handleWatchdogToolAction, WATCHDOG_TOOL_ACTIONS } from "../../watchdog/tool-actions.js";
@@ -6689,10 +6689,7 @@ export function createSubagentExecutor(deps) {
             if (action === "guide") {
                 try {
                     const guide = readSubagentGuide(paramsWithResolvedCwd.topic);
-                    const [topic, section] = paramsWithResolvedCwd.topic?.split("/") ?? [];
-                    const fullNotice = topic === "tool-reference" ? disabledFeatureNotice(disabledFeatures) : undefined;
-                    // Sections are capped at 8,000 chars, so they get a one-line pointer instead of the full list.
-                    const notice = fullNotice && section !== undefined ? "Some options and actions documented here are disabled by config in this session; guide topic tool-reference lists them." : fullNotice;
+                    const notice = paramsWithResolvedCwd.topic?.includes("/") ? disabledFeatureSectionNotice(disabledFeatures) : disabledFeatureNotice(disabledFeatures);
                     return {
                         content: [{ type: "text", text: notice ? `${notice}\n\n${guide}` : guide }],
                         details: { mode: "management", results: [] },

package/src/runs/shared/child-launch.js

@@ -45,7 +45,7 @@ function escapeXmlAttr(value) {
 function inheritedCapabilityCeiling(inherited) {
     return inherited?.capabilityCeiling;
 }
-/** Environment values external child extensions read; only the runner applies them. */
+/** Environment values external child extensions read in the runner, which hosts only children. */
 function childProcessEnv(input, toolPlan) {
     const env = {};
     env[PI_SUBAGENT_EXTENSION_BINDINGS_ENV] = encodeExtensionBindings(input.extensionBindings);
@@ -222,7 +222,10 @@ export function buildInProcessChildLaunch(input) {
         requiredExtensions: toolPlan.requiredExtensions,
         ambientExtensions,
         hooks: capturedHooks.hooks,
-        ...(input.host === "runner" ? { processEnv: childProcessEnv(input, toolPlan) } : {}),
+        // A foreground child gets only its own bindings, so it never sees those of the session that launched it.
+        ...(input.host === "runner"
+            ? { processEnv: childProcessEnv(input, toolPlan) }
+            : { processEnv: { [PI_SUBAGENT_EXTENSION_BINDINGS_ENV]: encodeExtensionBindings(input.extensionBindings) }, restoreProcessEnv: true }),
         runtime: config,
         noSkills: !input.inheritSkills,
         noContextFiles: !input.inheritProjectContext,

package/src/runs/shared/child-session.d.ts

@@ -80,6 +80,12 @@ export interface ChildSessionLaunch {
      * window one at a time. An undefined value removes the variable.
      */
     processEnv?: Record<string, string | undefined>;
+    /**
+     * Restore the hosting process's previous values of `processEnv` once that
+     * window ends, so a child hosted in the parent's own process leaves the
+     * parent's environment as it found it.
+     */
+    restoreProcessEnv?: boolean;
     /** The typed runtime config the hooks were built from; informational for factories. */
     runtime: ChildRuntimeConfig;
     onExtensionError?: (error: ChildSessionExtensionError) => void;