pi-subagents 0.82.1 → 0.83.1

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

@@ -153,15 +153,18 @@ function resetExtensionCacheOnReload(loader) {
     loader.loaded = true;
     return true;
 }
+/** Applies `values` to `process.env` and returns a function that puts back the values they replaced. */
 function applyProcessEnv(values) {
     if (!values)
-        return;
+        return () => { };
+    const previous = Object.fromEntries(Object.keys(values).map((name) => [name, process.env[name]]));
     for (const [name, value] of Object.entries(values)) {
         if (value === undefined)
             delete process.env[name];
         else
             process.env[name] = value;
     }
+    return () => applyProcessEnv(previous);
 }
 /**
  * Pi's built-in MCP extension registers server tools with the configured exposure, `codemode` by
@@ -458,7 +461,11 @@ export function createDefaultChildSessionFactory(options = {}) {
                     await commands?.shutdown();
                     const runner = session.extensionRunner;
                     if (runner.hasHandlers("session_shutdown")) {
-                        await Promise.race([runner.emit({ type: "session_shutdown", reason: "quit" }), new Promise((resolve) => setTimeout(resolve, shutdownTimeoutMs).unref?.())]);
+                        // Ref'd so a detached runner with nothing else pending stays alive until the bound
+                        // ends and still publishes its result; cleared as soon as the handlers finish.
+                        let bound;
+                        await Promise.race([runner.emit({ type: "session_shutdown", reason: "quit" }), new Promise((resolve) => { bound = setTimeout(resolve, shutdownTimeoutMs); })])
+                            .finally(() => clearTimeout(bound));
                     }
                 }
                 catch (error) {
@@ -469,8 +476,7 @@ export function createDefaultChildSessionFactory(options = {}) {
                 }
             };
             let inheritedProviders = new Set();
-            const open = async () => {
-                applyProcessEnv(launch.processEnv);
+            const openSession = async () => {
                 if (!resetExtensionCacheOnReload(loader) && (launch.ambientExtensions || launch.extensionPaths.length))
                     launch.onExtensionError?.({ extensionPath: "<loader>", event: "load", error: new Error("pi's extension cache reset is unavailable; extensions loaded into this child share module state with other sessions in this process.") });
                 await loader.reload();
@@ -559,6 +565,16 @@ export function createDefaultChildSessionFactory(options = {}) {
                 }
                 return session;
             };
+            const open = async () => {
+                const restoreEnv = applyProcessEnv(launch.processEnv);
+                try {
+                    return await openSession();
+                }
+                finally {
+                    if (launch.restoreProcessEnv)
+                        restoreEnv();
+                }
+            };
             const opened = loading.catch(() => { }).then(open);
             loading = opened;
             const session = await opened;

package/src/runs/shared/herdr-machine.d.ts

@@ -42,6 +42,8 @@ export interface PreparedHerdrMachineExternalCliRun {
 export declare function resolveHerdrMachinePlacement(input: ResolveHerdrMachinePlacementInput): HerdrMachinePlacement;
 /** `local` resolves to a Rex pane on this machine; a name with a `rex` entry in user settings to a Rex pane on that SSH host; any other value to a Herdr saved machine. */
 export declare function resolveMachinePlacement(input: ResolveHerdrMachinePlacementInput): MachinePlacement;
+/** A placed Pi keeps its transcript on the pane's machine, so it can't start from a local one. */
+export declare const PLACED_RESTORE_UNSUPPORTED = "Pane-native remote Pi does not support fork, resume, or revival; use fresh context.";
 export declare function formatHerdrMachineRunnerUnsupported(input: {
     machine?: string;
     agentName: string;

package/src/runs/shared/herdr-machine.js

@@ -233,6 +233,8 @@ export function resolveMachinePlacement(input) {
         return { machine: { provider: "rex", id: requested, target: settings.rex.ssh, cwd: validateRemoteCwd(remoteMachineCwd(input.stepCwd, settings.cwd, requested), requested) } };
     return resolveHerdrMachinePlacement(input);
 }
+/** A placed Pi keeps its transcript on the pane's machine, so it can't start from a local one. */
+export const PLACED_RESTORE_UNSUPPORTED = "Pane-native remote Pi does not support fork, resume, or revival; use fresh context.";
 export function formatHerdrMachineRunnerUnsupported(input) {
     if (input.machine === undefined)
         return undefined;

package/src/runs/shared/herdr-placed-run.js

@@ -8,6 +8,7 @@ import { encodeHerdrPiFrame, HERDR_PI_MODE_ENV, HERDR_PI_PROTOCOL, HERDR_PI_RUN_
 import { discoverPlacedBridgeManifest } from "./placed-run-owner.js";
 import { RexPlacedRunOwner } from "./rex-pane-host.js";
 import { isRexLocalMachine } from "./rex-machine.js";
+import { PLACED_RESTORE_UNSUPPORTED } from "./herdr-machine.js";
 /** The pane half comes from the host; the bridge half (run, package, protocol, native session, evidence cursor) is host-neutral. */
 export function reconcileHerdrReconnect(identity, candidate, lastEvidenceCursor, host = herdrPaneHost) {
     return host.reconcile(identity, candidate, () => { const bridge = candidate.bridge; if (bridge.runId !== identity.runId || bridge.nativeSessionId !== identity.nativeSessionId || bridge.packageVersion !== packageJson.version || bridge.protocol !== HERDR_PI_PROTOCOL)
@@ -35,16 +36,18 @@ export async function boundedHerdrReconnect(identity, lastEvidenceCursor, attemp
 }
 function safeRunId(value) { const prefix = value?.replace(/[^A-Za-z0-9_-]/gu, "_").slice(0, 48) ?? "run"; return validateHerdrPiRunId(`${prefix}_${randomBytes(8).toString("hex")}`); }
 export function serializeHerdrPiLaunch(launch) {
-    if (launch.storage.kind === "file")
-        throw new Error("Pane-native remote Pi does not support fork, resume, or revival; use fresh context.");
+    // Every child is handed a local session file path; only one that already exists (a fork or a
+    // resumed transcript) asks the pane to restore history. A fresh child's path is never written.
+    if (launch.storage.kind === "file" && fs.existsSync(launch.storage.sessionFile))
+        throw new Error(PLACED_RESTORE_UNSUPPORTED);
     if (launch.extensionPaths.length || launch.requiredExtensions?.length)
         throw new Error("Pane-native remote Pi cannot transfer local extension paths; install/configure pi-subagents on the remote machine.");
     if (launch.processEnv && Object.values(launch.processEnv).some((value) => value !== undefined && value !== "__none__"))
         throw new Error("Pane-native remote Pi cannot transfer local bindings, MCP selections, or process environment.");
     if (launch.runtime.nestedRoute || launch.runtime.fanoutChild || launch.runtime.depth > 1)
         throw new Error("Nested delegation from a pane-native remote Pi is not supported.");
-    if (launch.excludeTools?.length || launch.runtime.permissions || launch.runtime.toolBudget || launch.runtime.requiredExtensions || launch.runtime.requiredTools?.length || launch.runtime.mcpDirectTools?.length)
-        throw new Error("Pane-native remote Pi cannot yet represent exclusions, permission rules, tool budgets, MCP direct tools, or required-tool/extension contracts; remove machine placement.");
+    if (launch.excludeTools?.length || launch.runtime.permissions || launch.runtime.toolBudget || launch.runtime.requiredExtensions || launch.runtime.mcpDirectTools?.length)
+        throw new Error("Pane-native remote Pi cannot yet represent exclusions, permission rules, tool budgets, MCP direct tools, or required-extension contracts; remove machine placement.");
     const resources = launch.remoteResources;
     if (!resources || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(resources.agent) || resources.skills?.some((name) => !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(name)) || resources.toolCeiling?.some((name) => !/^[A-Za-z0-9_-]{1,64}$/u.test(name)) || (resources.reads !== undefined && resources.reads !== false && resources.reads.some((read) => typeof read !== "string" || Buffer.byteLength(read) > 4096)))
         throw new Error("Pane-native remote resources require bounded logical agent, skill, tool, and read names.");
@@ -350,6 +353,10 @@ async function startPlacedPiSession(launch, owner, policy) {
             throw new Error("Remote Pi resource resolution identity mismatch.");
         if (!Array.isArray(configured.tools) || (policy.resources.toolCeiling && configured.tools.some((tool) => !policy.resources.toolCeiling.includes(String(tool)))))
             throw new Error("Remote Pi active-tool ceiling acknowledgement mismatch.");
+        // The remote Pi never receives the runtime contract, so required tools are checked here, against what it activated.
+        const missingRequired = (launch.runtime.requiredTools ?? []).filter((tool) => !configured.tools.includes(tool));
+        if (missingRequired.length)
+            throw new Error(`Remote Pi agent '${policy.resources.agent}' did not activate required tools: ${missingRequired.join(", ")}.`);
         if (launch.model && configured.model !== launch.model.split(":")[0])
             throw new Error(`Remote Pi model '${launch.model}' did not resolve to the requested provider/model.`);
         const identity = { runId, machineId: machine.id, target: isRexLocalMachine(machine) ? machine.id : machine.target, session: owner.host.sessionOf(connection), workspaceId: owned.workspaceId, tabId: owned.tabId, paneId: owned.paneId, terminalId, agentName, nativeSessionId: manifest.nativeSessionId, cwd: machine.cwd, runtimeDir };

package/src/runs/shared/parallel-handoff.d.ts

@@ -23,7 +23,7 @@ export declare function resolveParallelHandoffChild(input: {
     child: ParallelHandoffGroup["children"][number];
 } | undefined;
 export declare function protectRetainedWorktreeForResume(manifestPath: string, runId: string, childIndex: number, signal?: AbortSignal): Promise<string>;
-export declare function resolveRetainedWorktreeCwd(manifestPath: string, runId: string, childIndex: number): string | undefined;
+export declare function resolveRetainedWorktreeCwd(manifestPath: string, runId: string, childIndex: number, recordedWorktreePath?: string): string | undefined;
 export declare function isTerminalParallelHandoffChildStatus(status: unknown): boolean;
 export declare function formatStoredParallelHandoffCleanup(manifestPath: string, manifest?: ParallelHandoffManifest): string;
 export interface ParallelHandoffEvidenceResult {

package/src/runs/shared/parallel-handoff.js

@@ -165,17 +165,18 @@ export async function protectRetainedWorktreeForResume(manifestPath, runId, chil
         return cwd;
     }), { signal }));
 }
-export function resolveRetainedWorktreeCwd(manifestPath, runId, childIndex) {
+export function resolveRetainedWorktreeCwd(manifestPath, runId, childIndex, recordedWorktreePath) {
     const manifest = readParallelHandoffManifest(manifestPath);
-    if (!manifest)
-        return undefined;
-    if (manifest.runId !== runId)
+    if (manifest && manifest.runId !== runId)
         throw new Error(`Managed worktree handoff belongs to run '${manifest.runId}', not '${runId}'.`);
-    const match = manifest.groups
+    const match = manifest?.groups
         .flatMap((group) => group.children.map((child) => ({ group, child })))
         .find(({ child }) => child.index === childIndex);
-    if (!match)
+    if (!manifest || !match) {
+        if (recordedWorktreePath)
+            throw new Error(`Async run '${runId}' child ${childIndex} ran in managed worktree ${recordedWorktreePath}, but its handoff has no resumable record yet. Retry after the run settles; if it already ended, inspect ${manifestPath}.`);
         return undefined;
+    }
     const cleanup = match.group.cleanup.tasks.find((task) => task.index === match.child.taskIndex);
     if (!cleanup)
         throw new Error(`Async run '${runId}' child ${childIndex} has no managed worktree cleanup record.`);
@@ -185,6 +186,9 @@ export function resolveRetainedWorktreeCwd(manifestPath, runId, childIndex) {
     const requiredCwd = path.join(cleanup.path, relativeCwd);
     if (cleanup.worktreeRemoved || cleanup.branchRemoved)
         throw new Error(`Async run '${runId}' required managed worktree was removed: ${requiredCwd}`);
+    // The runner removes the worktree right after this marker, without the locks that guard resume admission.
+    if (cleanup.reason?.includes("pending durable handoff capture"))
+        throw new Error(`Async run '${runId}' child ${childIndex} is still finalizing its managed worktree: ${requiredCwd}. Retry after the run settles; if it already ended, inspect ${manifestPath}.`);
     let worktreeRoot = "";
     let resolvedRequiredCwd = "";
     try {

package/src/runs/shared/subagent-prompt-runtime.js

@@ -669,6 +669,7 @@ export default function registerSubagentPromptRuntime(pi, config, drainObservati
     onRuntimeEvent("session_start", (_event, ctx) => {
         const sessionManager = ctx?.sessionManager;
         waitState.currentSessionId = sessionManager ? resolveCurrentSessionId(sessionManager) : null;
+        waitState.supervisorOwnerSessionId = sessionManager?.getSessionId() || null;
         registerNativeSupervisorClientOnce();
     });
     onRuntimeEvent("agent_start", () => {
@@ -724,30 +725,23 @@ export default function registerSubagentPromptRuntime(pi, config, drainObservati
         onRuntimeEvent("before_provider_headers", (event, ctx) => {
             applyForkSessionAffinity(event?.headers, ctx?.model, config.parentSessionId, readInherited(ctx)?.model);
         });
-    if (config.forkCacheKey)
-        onRuntimeEvent("context_with_system", (event, ctx) => {
-            if (!event || typeof event !== "object" || !("messages" in event) || !Array.isArray(event.messages))
-                return undefined;
-            const fork = readInherited(ctx);
-            if (!fork)
-                return undefined;
-            const messages = projectForkRequest(event.messages, fork.system, fork.forkedAt, { boundary });
-            return messages === event.messages ? undefined : { messages };
-        });
-    onRuntimeEvent("context", (event, ctx) => {
+    // The strip 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, so every later request would miss the prompt cache. The strip
+    // passes system messages through unchanged.
+    onRuntimeEvent("context_with_system", (event, ctx) => {
         if (!event || typeof event !== "object" || !("messages" in event) || !Array.isArray(event.messages))
             return undefined;
-        const forkedAt = config.forkCacheKey ? Date.parse(ctx?.sessionManager?.getHeader()?.timestamp ?? "") : Number.NaN;
-        const messages = stripParentOnlySubagentMessages(event.messages, {
+        const fork = config.forkCacheKey ? readInherited(ctx) : undefined;
+        const stripped = stripParentOnlySubagentMessages(event.messages, {
             sanitizeToolIds: !COMPOSITE_TOOL_ID_APIS.has(ctx?.model?.api ?? ""),
             // Providers that reuse the Codex Responses wire under their own api id (e.g. cliproxyapi-codex-responses) split call_id|item_id the same way.
             preserveBoundedCompositeToolIds: ctx?.model?.api?.endsWith("-codex-responses") === true,
             preserveFanoutToolHistory: config.fanoutChild,
-            ...(Number.isFinite(forkedAt) ? { inheritedBefore: forkedAt } : {}),
+            ...(fork ? { inheritedBefore: fork.forkedAt } : {}),
         });
-        if (messages === event.messages)
-            return undefined;
-        return { messages };
+        const messages = fork ? projectForkRequest(stripped, fork.system, fork.forkedAt, { boundary }) : stripped;
+        return messages === event.messages ? undefined : { messages };
     });
     // pi-intercom asks at session start for this session's intercom ID. Claiming
     // the route there frees the session name for the readable label. An older

package/src/shared/disabled-features.d.ts

@@ -86,6 +86,8 @@ interface FeatureConfig {
 export declare function resolveDisabledFeatureSurface(config: FeatureConfig): DisabledFeatureSurface;
 /** Returns why a request uses a disabled feature, or undefined when every requested field is enabled. */
 export declare function disabledFeatureUseError(request: object, surface: DisabledFeatureSurface, label?: string): string | undefined;
-/** Lists what config disabled, for prepending to static reference docs that describe the full tool. */
+/** Lists what config disabled, for prepending to static guide docs that describe the full tool. */
 export declare function disabledFeatureNotice(surface: DisabledFeatureSurface): string | undefined;
+/** One-line form for guide sections, which are capped at 8,000 chars. */
+export declare function disabledFeatureSectionNotice(surface: DisabledFeatureSurface): string | undefined;
 export {};

package/src/shared/disabled-features.js

@@ -99,14 +99,22 @@ export function disabledFeatureUseError(request, surface, label = "subagent") {
     }
     return undefined;
 }
-/** Lists what config disabled, for prepending to static reference docs that describe the full tool. */
+const WORKFLOW_SCRIPTS_REPLACEMENT = "Instead of workflow scripts, use the top-level tasks or chain fields.";
+/** Lists what config disabled, for prepending to static guide docs that describe the full tool. */
 export function disabledFeatureNotice(surface) {
     if (surface.features.size === 0)
         return undefined;
     const lines = [...surface.features].map((feature) => {
         const { actions, params, disabledBy } = featureSurface(feature);
         const parts = [`options ${params.join(", ")}`, ...(actions.length > 0 ? [`actions ${actions.join(", ")}`] : [])];
-        return `- ${disabledBy}: ${parts.join("; ")}`;
+        return `- ${disabledBy}: ${parts.join("; ")}${feature === "workflow-scripts" ? `. ${WORKFLOW_SCRIPTS_REPLACEMENT}` : ""}`;
     });
-    return `Disabled by config in this session. The reference below still lists these, but calls that use them are rejected:\n${lines.join("\n")}`;
+    return `Disabled by config in this session. The guide below may still describe these, but calls that use them are rejected:\n${lines.join("\n")}`;
+}
+/** One-line form for guide sections, which are capped at 8,000 chars. */
+export function disabledFeatureSectionNotice(surface) {
+    if (surface.features.size === 0)
+        return undefined;
+    const replacement = surface.features.has("workflow-scripts") ? ` ${WORKFLOW_SCRIPTS_REPLACEMENT}` : "";
+    return `Some options and actions are disabled by config in this session; guide topic tool-reference lists them.${replacement}`;
 }

package/src/shared/types.d.ts

@@ -1936,7 +1936,7 @@ export interface AsyncStatus {
         label?: string;
         workflowKey?: string;
         lane?: WorkflowLaneMetadata;
-        /** Display-only worktree path copied at launch; handoff remains authoritative. */
+        /** Worktree path copied at setup; the handoff stays authoritative for the cwd. */
         worktreePath?: string;
         /** Display-only branch copied at launch; handoff remains authoritative. */
         branch?: string;
@@ -2278,7 +2278,7 @@ export interface ActiveAsyncCapacitySnapshot {
 export interface SubagentState {
     baseCwd: string;
     currentSessionId: string | null;
-    /** Exact SDK runtime session ID for supervisor ownership; never a session file path. */
+    /** Exact SDK runtime session ID (`getSessionId()`) for supervisor ownership and background-work matching; never a session file path. */
     supervisorOwnerSessionId?: string | null;
     /** Session for which active status projections were restored successfully. */
     statusProjectionSessionId?: string | null;
@@ -2410,6 +2410,8 @@ export declare const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
 export declare const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
 export declare const SUBAGENT_STEERING_NOTICE_EVENT = "subagent:steering-notice";
 export declare const SUBAGENT_CHILD_STATUS_EVENT = "subagent:child-status";
+/** Payload is only `{ version: 1 }`: a hint for hosts to read `status` again, not a description of the change. */
+export declare const SUBAGENT_JOBS_CHANGED_EVENT = "subagent:jobs-changed";
 export declare const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
 export declare const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
 export interface SubagentChildStatusEvent {

package/src/shared/types.js

@@ -19,6 +19,8 @@ export const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
 export const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
 export const SUBAGENT_STEERING_NOTICE_EVENT = "subagent:steering-notice";
 export const SUBAGENT_CHILD_STATUS_EVENT = "subagent:child-status";
+/** Payload is only `{ version: 1 }`: a hint for hosts to read `status` again, not a description of the change. */
+export const SUBAGENT_JOBS_CHANGED_EVENT = "subagent:jobs-changed";
 export const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
 export const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
 export const FLEET_KEYBINDING_ACTIONS = [