pi-agent-replicate 0.0.0-stage → 1.4.1

package/pi-extension/subagents/subagent-done.js

@@ -0,0 +1,805 @@
+/**
+ * Extension loaded into sub-agents.
+ * - Shows agent identity + available tools as a styled widget above the editor (toggle with Ctrl+J)
+ * - Saves completion and closes replicas only after their session work drains
+ */
+import { stripFrontmatter, } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { SessionWork, workFacts } from "./session-work.js";
+import { replicaStopDue } from "./watchdog.js";
+import { bindSessionRuntime, beginChildSessionMove, readSessionBinding, writeBindingFile } from "./session-binding.js";
+const lifecycleKey = Symbol.for("pi-herdr-subagents.child-lifecycle");
+const lifecycles = globalThis[lifecycleKey] ??= new WeakSet();
+const lifecycleSessions = globalThis[Symbol.for("pi-herdr-subagents.child-lifecycle-sessions")] ??= new Set();
+/** Extension event facades differ, but one child process still owns one lifecycle. */
+export function hasChildLifecycle(pi) {
+    return lifecycles.has(pi.events) || !!process.env.PI_SUBAGENT_SESSION && lifecycleSessions.has(process.env.PI_SUBAGENT_SESSION);
+}
+import { dirname, join } from "node:path";
+import { createSubagentActivityRecorder } from "./activity.js";
+import { waitForDeliveryDrain } from "./delivery-drain.js";
+import { createDeliveryLog } from "./delivery-log.js";
+import { classifySettledOutcome, } from "./settled-contract.js";
+import { hasUndrainedDescendants, isLineageNodeDrained, lineageFromEnvironment, reduceLineage, } from "./lineage.js";
+export function shouldMarkUserTookOver(agentStarted) {
+    return agentStarted;
+}
+/** Wait until this session's owned descendants have terminal delivery. */
+export async function waitForDescendantDrain(options = {}) {
+    const lineage = options.lineage ?? lineageFromEnvironment();
+    if (!lineage)
+        return;
+    const childId = lineage.nodeId ?? lineage.parentNodeId;
+    if (!childId)
+        return;
+    const sessionFile = process.env.PI_SUBAGENT_SESSION;
+    const persistentLog = sessionFile
+        ? createDeliveryLog({ logPath: join(dirname(sessionFile), "subagent-delivery.log"), now: options.now })
+        : undefined;
+    const record = options.log ?? ((event, fields) => persistentLog?.record(event, fields));
+    await waitForDeliveryDrain({
+        isDrained: () => !hasUndrainedDescendants(reduceLineage(lineage.rootDir), childId),
+        delay: options.delay,
+        now: options.now,
+        onWaitOpen: (info) => {
+            options.projectWidget?.({ state: "waiting-on-descendants", childId });
+            record("drain-wait-open", { childId, phase: "drain", waitedSince: info.waitedSince });
+            options.onWaitOpen?.(info);
+        },
+        onWaitRelease: (info) => {
+            record("drain-wait-release", { childId, phase: "drain", ...info });
+            options.onWaitRelease?.(info);
+        },
+    });
+}
+function hasPendingOwnedChildren() {
+    const contextPath = process.env.PI_SUBAGENT_TREE_CONTEXT;
+    if (!contextPath)
+        return false;
+    let context;
+    try {
+        context = JSON.parse(readFileSync(contextPath, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (!context.treeDir || !context.ownerId)
+        return false;
+    const nodesDir = join(context.treeDir, "nodes");
+    return existsSync(nodesDir) && readdirSync(nodesDir).some((file) => {
+        if (!file.endsWith(".json"))
+            return false;
+        try {
+            const node = JSON.parse(readFileSync(join(nodesDir, file), "utf8"));
+            return node.ownerId === context.ownerId && node.status !== "settled";
+        }
+        catch {
+            return true;
+        }
+    });
+}
+async function waitForOwnedChildren() {
+    while (hasPendingOwnedChildren()) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+function settledChildIdFromPrompt(prompt) {
+    if (typeof prompt !== "string" || !/^Subagent .+ settled\.$/m.test(prompt))
+        return undefined;
+    return prompt.match(/^Delivery: settled:([^:\s]+):/m)?.[1];
+}
+function settledChildIdFromMessage(message) {
+    if (!message || typeof message !== "object")
+        return undefined;
+    const value = message;
+    if (value.customType !== "subagent_result")
+        return undefined;
+    if (value.details?.kind === "settled" &&
+        (value.details.outcome === "clean" || value.details.outcome === "empty") &&
+        typeof value.details.childId === "string") {
+        return value.details.childId;
+    }
+    return settledChildIdFromPrompt(value.content);
+}
+function hasOtherUndrainedDescendants(state, ownerId, settledChildId) {
+    return [...state.nodes.values()].some((child) => child.parentNodeId === ownerId &&
+        !isLineageNodeDrained(state, child.nodeId) &&
+        (child.nodeId !== settledChildId || child.autoExit !== true));
+}
+function textFromContent(content) {
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((part) => part != null && typeof part === "object")
+        .filter((part) => part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text ?? "")
+        .join("");
+}
+/** Convert the latest assistant message into the frozen settled contract. */
+export function newestAssistantEntry(messages) {
+    if (!messages || messages.length === 0)
+        return null;
+    const latest = messages[messages.length - 1];
+    if (latest?.role === "user")
+        return null;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg?.role !== "assistant")
+            continue;
+        const text = typeof msg.text === "string" ? msg.text : textFromContent(msg.content);
+        const contentLength = text.length;
+        return {
+            id: typeof msg.id === "string" && msg.id ? msg.id : `assistant-${i}`,
+            text: text || null,
+            contentLength,
+            stopReason: typeof msg.stopReason === "string"
+                ? msg.stopReason
+                : undefined,
+            errorMessage: typeof msg.errorMessage === "string" ? msg.errorMessage : undefined,
+            empty: contentLength === 0,
+        };
+    }
+    return null;
+}
+/** Decide whether a settled response is allowed to close an auto-exit child. */
+export function classifyAutoExitOutcome(messages, interruptRequested = false) {
+    const assistant = newestAssistantEntry(messages);
+    if (!assistant)
+        return null;
+    return classifySettledOutcome({ assistant, interruptRequested });
+}
+/**
+ * Compatibility predicate retained for callers that only have an agent_end
+ * snapshot. The decision is now intentionally made at agent_settled.
+ */
+export function shouldAutoExitOnAgentEnd(_userTookOver, messages) {
+    const outcome = classifyAutoExitOutcome(messages);
+    return outcome === "clean" || outcome === "empty";
+}
+/**
+ * If the last assistant message in the turn ended with `stopReason: "error"`
+ * (typically auto-retry exhausted on an overload / rate limit / server error),
+ * return its error info so the parent orchestrator can surface a clear
+ * failure instead of silently treating the run as completed.
+ *
+ * Returns `null` when the latest assistant turn completed normally or was
+ * aborted by the user (handled separately by shouldAutoExitOnAgentEnd).
+ */
+export function findLatestAssistantError(messages) {
+    if (!messages)
+        return null;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg?.role !== "assistant")
+            continue;
+        if (msg.stopReason !== "error")
+            return null;
+        const raw = typeof msg.errorMessage === "string" ? msg.errorMessage.trim() : "";
+        return {
+            errorMessage: raw ||
+                "Subagent agent loop ended with stopReason=error (no errorMessage field).",
+            stopReason: "error",
+        };
+    }
+    return null;
+}
+export function buildCompletionSidecar(messages) {
+    const errorInfo = findLatestAssistantError(messages);
+    return errorInfo ? { type: "error", ...errorInfo } : { type: "done" };
+}
+export async function waitForPingAcknowledgement(sessionFile, pingId, signal, intervalMs = 50) {
+    for (;;) {
+        if (signal?.aborted)
+            throw new Error("Help request wait was cancelled");
+        try {
+            const current = JSON.parse(readFileSync(`${sessionFile}.exit`, "utf8"));
+            if (current.type !== "ping" || current.id !== pingId)
+                return;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || error instanceof SyntaxError)
+                return;
+            throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}
+export function parseDeniedTools(rawValue) {
+    return (rawValue ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+/** Build one hidden, session-persistent initialization message for requested skills. */
+export function buildSkillInitialization(event, requestedSkills, notify) {
+    const names = [...new Set(requestedSkills
+            .split(",")
+            .map((name) => name.trim())
+            .filter(Boolean))];
+    if (names.length === 0)
+        return undefined;
+    const catalog = event.systemPromptOptions.skills ?? [];
+    const blocks = [];
+    for (const name of names) {
+        const skill = catalog.find((candidate) => candidate.name === name);
+        if (!skill) {
+            notify(`Unable to load requested skill "${name}": not found in Pi's resolved skill catalog.`, "warning");
+            continue;
+        }
+        try {
+            const body = stripFrontmatter(readFileSync(skill.filePath, "utf8")).trim();
+            blocks.push(`<skill name="${skill.name}" location="${skill.filePath}">\n` +
+                `References are relative to ${skill.baseDir}.\n\n${body}\n</skill>`);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            notify(`Unable to load requested skill "${name}": ${reason}`, "warning");
+        }
+    }
+    if (blocks.length === 0)
+        return undefined;
+    return {
+        message: {
+            customType: "subagent_skill_initialization",
+            content: [{ type: "text", text: blocks.join("\n\n") }],
+            display: false,
+        },
+    };
+}
+/** Install child lifecycle only after this runtime opens its own persisted binding. */
+export default function subagentLifecycle(pi, initialContext) {
+    const start = (ctx) => {
+        const file = ctx.sessionManager.getSessionFile();
+        const binding = file ? readSessionBinding(file) : undefined;
+        // Startup checks inherit the child's environment, not ownership of its session.
+        if (!binding?.child || binding.sessionId !== ctx.sessionManager.getSessionId())
+            return;
+        installChildLifecycle(pi, ctx);
+    };
+    if (initialContext)
+        start(initialContext);
+    else {
+        // This explicitly loaded extension is last in the replica argv. Keep this
+        // hook on its own facade even if the main extension owns the lifecycle.
+        pi.on("before_agent_start", (_event, ctx) => {
+            const file = ctx.sessionManager.getSessionFile();
+            const binding = file ? readSessionBinding(file) : undefined;
+            if (!binding?.child || binding.sessionId !== ctx.sessionManager.getSessionId()) return;
+            const environment = binding.child.environment;
+            if (environment.PI_SUBAGENT_REPLICATION !== "1") return;
+            const promptFile = environment.PI_SUBAGENT_REPLICATION_PROMPT_FILE;
+            if (!promptFile) throw new Error("Replica system prompt is missing.");
+            return { systemPrompt: readFileSync(promptFile, "utf8") };
+        });
+        pi.on("session_start", (_event, ctx) => start(ctx));
+    }
+}
+function installChildLifecycle(pi, initialContext) {
+    if (hasChildLifecycle(pi))
+        return;
+    lifecycles.add(pi.events);
+    const lifecycleSession = process.env.PI_SUBAGENT_SESSION;
+    if (lifecycleSession)
+        lifecycleSessions.add(lifecycleSession);
+    const unsubscribers = [];
+    const on = ((event, handler) => {
+        const unsubscribe = pi.on(event, handler);
+        if (typeof unsubscribe === "function")
+            unsubscribers.push(unsubscribe);
+        return unsubscribe;
+    });
+    let toolNames = [];
+    let denied = [];
+    let expanded = false;
+    // Read subagent identity from env vars (set by parent orchestrator)
+    const subagentName = process.env.PI_SUBAGENT_NAME ?? "";
+    const subagentAgent = process.env.PI_SUBAGENT_AGENT ?? "";
+    const deniedToolsValue = process.env.PI_DENY_TOOLS;
+    const autoExit = process.env.PI_SUBAGENT_AUTO_EXIT === "1";
+    const inheritedBinding = process.env.PI_SUBAGENT_SESSION ? readSessionBinding(process.env.PI_SUBAGENT_SESSION) : undefined;
+    const replication = process.env.PI_SUBAGENT_REPLICATION === "1" || inheritedBinding?.child?.environment.PI_SUBAGENT_REPLICATION === "1";
+    const treeOwner = process.env.PI_SUBAGENT_TREE_OWNER === "1";
+    const savedWork = [...initialContext.sessionManager.getBranch()].reverse().find(entry => entry.type === "custom" && entry.customType === "replica-session-work");
+    const work = new SessionWork(initialContext.sessionManager.getSessionId(), savedWork?.type === "custom" ? savedWork.data : undefined);
+    let savedWorkText = JSON.stringify(work.snapshot());
+    let closureVersion = 0;
+    const persistWork = () => {
+        if (!replication || !runtimeActive)
+            return;
+        const snapshot = work.snapshot(), text = JSON.stringify(snapshot);
+        if (text !== savedWorkText) {
+            pi.appendEntry("replica-session-work", snapshot);
+            savedWorkText = text;
+        }
+    };
+    const recorder = createSubagentActivityRecorder({
+        runningChildId: process.env.PI_SUBAGENT_ID,
+        activityFile: process.env.PI_SUBAGENT_ACTIVITY_FILE,
+        settledEventsFile: process.env.PI_SUBAGENT_SETTLED_EVENTS_FILE,
+    });
+    function renderWidget(ctx, _theme) {
+        ctx.ui.setWidget("subagent-tools", (_tui, theme) => {
+            const box = new Box(1, 0, (text) => theme.bg("toolSuccessBg", text));
+            const label = subagentAgent || subagentName;
+            const agentTag = label
+                ? theme.bold(theme.fg("accent", `[${label}]`))
+                : "";
+            if (expanded) {
+                // Expanded: full tool list + denied
+                const countInfo = theme.fg("dim", ` — ${toolNames.length} available`);
+                const hint = theme.fg("muted", "  (Ctrl+J to collapse)");
+                const toolList = toolNames
+                    .map((name) => theme.fg("dim", name))
+                    .join(theme.fg("muted", ", "));
+                let deniedLine = "";
+                if (denied.length > 0) {
+                    const deniedList = denied
+                        .map((name) => theme.fg("error", name))
+                        .join(theme.fg("muted", ", "));
+                    deniedLine = "\n" + theme.fg("muted", "denied: ") + deniedList;
+                }
+                const content = new Text(`${agentTag}${countInfo}${hint}\n${toolList}${deniedLine}`, 0, 0);
+                box.addChild(content);
+            }
+            else {
+                // Collapsed: one-line summary
+                const countInfo = theme.fg("dim", ` — ${toolNames.length} tools`);
+                const deniedInfo = denied.length > 0
+                    ? theme.fg("dim", " · ") +
+                        theme.fg("error", `${denied.length} denied`)
+                    : "";
+                const hint = theme.fg("muted", "  (Ctrl+J to expand)");
+                const content = new Text(`${agentTag}${countInfo}${deniedInfo}${hint}`, 0, 0);
+                box.addChild(content);
+            }
+            return box;
+        }, { placement: "aboveEditor" });
+    }
+    let latestAgentEndMessages;
+    let latestTurnIndex;
+    let settledChildResultId;
+    let skillInitializationComplete = false;
+    // Resumed sessions replay the previous turn during startup. Do not publish
+    // that historical settlement as the new resume completion.
+    let resumeTurnStarted = process.env.PI_SUBAGENT_RESUME !== "1";
+    let resumeInputSeen = process.env.PI_SUBAGENT_RESUME !== "1";
+    const resumeBaselineAssistantIds = new Set((() => {
+        if (process.env.PI_SUBAGENT_RESUME !== "1")
+            return [];
+        try {
+            const value = JSON.parse(process.env.PI_SUBAGENT_RESUME_BASELINE_ASSISTANTS ?? "[]");
+            return Array.isArray(value) ? value.filter((id) => typeof id === "string") : [];
+        }
+        catch {
+            return [];
+        }
+    })());
+    // Parent-side interrupt bookkeeping is intentionally separate. Until the
+    // parent wires an explicit interrupt request, an abort remains open and is
+    // classified as an unexpected abort for delivery purposes.
+    let interruptRequested = false;
+    let agentStarted = false;
+    let movePending = false;
+    let reloadPending = false;
+    let runtimeActive = true;
+    let intervened = false;
+    const mechanicalInterruptPath = process.env.PI_SUBAGENT_SESSION
+        ? `${process.env.PI_SUBAGENT_SESSION}.mechanical-interrupt`
+        : undefined;
+    // Show widget + status bar on session start
+    const start = (ctx) => {
+        bindSessionRuntime(pi, ctx);
+        skillInitializationComplete = ctx.sessionManager.getBranch().some((entry) => entry.type === "custom_message" && entry.customType === "subagent_skill_initialization");
+        recorder.sessionStart();
+        toolNames = pi.getAllTools().map((tool) => tool.name).sort();
+        denied = parseDeniedTools(deniedToolsValue);
+        const allow = process.env.PI_SUBAGENT_TOOLS?.split(",").filter(Boolean);
+        pi.setActiveTools(pi.getActiveTools().filter((name) => !denied.includes(name) && (!allow?.length || allow.includes(name))));
+        renderWidget(ctx, null);
+    };
+    on("session_start", (_event, ctx) => start(ctx));
+    if (initialContext)
+        start(initialContext);
+    on("session_before_compact", (event) => {
+        idleSince = undefined;
+        recorder.compactionStart({
+            reason: event.reason,
+            willRetry: event.willRetry,
+        });
+    });
+    on("session_compact", (event) => {
+        recorder.compactionSucceeded({
+            reason: event.reason,
+            willRetry: event.willRetry,
+        });
+    });
+    on("session_compact_failed", (event) => {
+        recorder.compactionFailed({
+            reason: event.reason,
+            willRetry: event.willRetry,
+            aborted: event.aborted,
+            errorMessage: event.errorMessage,
+        });
+    });
+    on("input", () => {
+        closureVersion++;
+        idleSince = undefined;
+        resumeInputSeen = true;
+        if (shouldMarkUserTookOver(agentStarted))
+            intervened = true;
+        recorder.input();
+    });
+    on("before_agent_start", (event, ctx) => {
+        settledChildResultId =
+            settledChildIdFromPrompt(event.prompt) ?? settledChildResultId;
+        if (replication) {
+            closureVersion++;
+            clearStop();
+            interruptRequested = false;
+        }
+        // Each run needs fresh agent_end evidence; never reuse a prior clean turn.
+        latestAgentEndMessages = undefined;
+        latestTurnIndex = undefined;
+        resumeTurnStarted = true;
+        recorder.beforeAgentStart();
+        if (replication) {
+            const promptFile = process.env.PI_SUBAGENT_REPLICATION_PROMPT_FILE;
+            if (!promptFile)
+                throw new Error("Replica system prompt is missing.");
+            return { systemPrompt: readFileSync(promptFile, "utf8") };
+        }
+        if (skillInitializationComplete)
+            return;
+        skillInitializationComplete = true;
+        const requestedSkills = process.env.PI_SUBAGENT_SKILLS;
+        if (requestedSkills === undefined)
+            return;
+        return buildSkillInitialization(event, requestedSkills, (message, type) => ctx.ui.notify(message, type));
+    });
+    on("agent_start", () => {
+        agentStarted = true;
+        recorder.agentStart();
+    });
+    let exitRequested = false;
+    let stopTimer;
+    let idleSince;
+    let stopPayload;
+    let checkingWork = false;
+    const refreshWork = async () => {
+        const completed = await work.refreshProcesses();
+        if (!runtimeActive)
+            return;
+        persistWork();
+        if (completed.length) {
+            closureVersion++;
+            clearStop();
+            latestAgentEndMessages = undefined;
+            pi.sendMessage({
+                customType: "replica-work-completion", display: false,
+                content: `Session-owned processes exited: ${completed.join(", ")}. No exit status was recorded here. Inspect their saved output before giving your final result.`,
+                details: { pids: completed },
+            }, { triggerTurn: true, deliverAs: "followUp" });
+        }
+    };
+    const stopFile = process.env.PI_SUBAGENT_SESSION
+        ? `${process.env.PI_SUBAGENT_SESSION}.replica-stop`
+        : undefined;
+    const clearStop = () => {
+        idleSince = undefined;
+        // A terminal failure survives follow-up turns needed to drain owned work.
+        if (stopPayload?.type === "error")
+            return;
+        stopPayload = undefined;
+        if (stopFile)
+            rmSync(stopFile, { force: true });
+    };
+    const rememberStop = (payload) => {
+        if (stopPayload?.type === "error")
+            payload = stopPayload;
+        stopPayload = payload;
+        // The exit sidecar remains authoritative if this retry checkpoint cannot be saved.
+        if (stopFile) {
+            try {
+                writeBindingFile(stopFile, { payload, stoppedAt: Date.now() });
+            }
+            catch { }
+        }
+    };
+    const armStopTimer = (ctx) => {
+        if (!replication || stopTimer)
+            return;
+        stopTimer = setInterval(async () => {
+            if (checkingWork || !runtimeActive || exitRequested || !resumeTurnStarted || !resumeInputSeen)
+                return;
+            checkingWork = true;
+            try {
+                await refreshWork();
+                if (!runtimeActive)
+                    return;
+                const lineage = lineageFromEnvironment();
+                const descendants = !!lineage && hasUndrainedDescendants(reduceLineage(lineage.rootDir), lineage.nodeId);
+                const idle = ctx.isIdle();
+                const pendingMessages = ctx.hasPendingMessages();
+                if (!idle || pendingMessages || movePending || reloadPending || descendants || work.pending) {
+                    idleSince = undefined;
+                    return;
+                }
+                if (!latestAgentEndMessages && !stopPayload)
+                    return;
+                idleSince ??= Date.now();
+                if (!replicaStopDue({ now: Date.now(), idleSince, idle, pendingMessages, moving: movePending, descendants }))
+                    return;
+                const payload = stopPayload ?? { type: "error", errorMessage: "Replica stopped without saved settlement evidence." };
+                rememberStop(payload);
+                void finishAfterDrain(ctx, payload);
+            }
+            catch (error) {
+                ctx.ui.notify(`Session work could not be checked: ${String(error)}`, "error");
+            }
+            finally {
+                checkingWork = false;
+            }
+        }, 1000);
+        stopTimer.unref();
+    };
+    const restoreStopTimer = (ctx) => {
+        if (replication && stopFile && existsSync(stopFile) && process.env.PI_SUBAGENT_RESUME !== "1") {
+            try {
+                const saved = JSON.parse(readFileSync(stopFile, "utf8"));
+                if (!["done", "error"].includes(saved.payload?.type) || !Number.isFinite(saved.stoppedAt))
+                    throw new Error("Invalid stopped-state checkpoint");
+                stopPayload = saved.payload;
+                idleSince = saved.stoppedAt;
+            }
+            catch {
+                stopPayload = { type: "error", errorMessage: "Replica stopped-state checkpoint could not be read." };
+                idleSince = Date.now();
+            }
+        }
+        armStopTimer(ctx);
+    };
+    on("session_start", (_event, ctx) => restoreStopTimer(ctx));
+    if (initialContext)
+        restoreStopTimer(initialContext);
+    const finishAfterDrain = async (ctx, payload) => {
+        if (exitRequested || replication && work.pending)
+            return;
+        exitRequested = true;
+        const version = closureVersion;
+        try {
+            const lineage = lineageFromEnvironment();
+            if (lineage && hasUndrainedDescendants(reduceLineage(lineage.rootDir), lineage.nodeId))
+                await waitForDescendantDrain();
+            if (treeOwner)
+                await waitForOwnedChildren();
+            if (replication) {
+                // Let queued completion input start its turn before the final ownership check.
+                await new Promise(resolve => setImmediate(resolve));
+                await refreshWork();
+                if (version !== closureVersion || work.pending || movePending || !ctx.isIdle() || ctx.hasPendingMessages())
+                    return;
+            }
+            if (!runtimeActive || reloadPending)
+                return;
+            const sessionFile = process.env.PI_SUBAGENT_SESSION;
+            if (sessionFile) {
+                try {
+                    writeBindingFile(`${sessionFile}.exit`, { ...payload, summary: payload.summary ?? newestAssistantEntry(latestAgentEndMessages)?.text });
+                }
+                catch (error) {
+                    if (replication) {
+                        ctx.ui.notify(`Replica completion could not be saved: ${String(error)}`, "error");
+                        return;
+                    }
+                    // Retained callers can still use the wrapper sentinel.
+                }
+            }
+            ctx.shutdown();
+        }
+        finally {
+            exitRequested = false;
+        }
+    };
+    on("agent_end", (event, ctx) => {
+        // Boundary messages commit directly to history without message_start.
+        // This run consumed them before producing its final response.
+        if (replication) {
+            for (const entry of ctx.sessionManager.getBranch()) {
+                if (entry.type === "custom_message")
+                    work.message(entry);
+            }
+            persistWork();
+        }
+        armStopTimer(ctx);
+        latestAgentEndMessages = event.messages;
+        const eventTurnIndex = event.turnIndex;
+        if (typeof eventTurnIndex === "number")
+            latestTurnIndex = eventTurnIndex;
+        const assistant = newestAssistantEntry(latestAgentEndMessages);
+        if (assistant?.stopReason === "aborted") {
+            const mechanical = Boolean(mechanicalInterruptPath && existsSync(mechanicalInterruptPath));
+            if (mechanicalInterruptPath)
+                rmSync(mechanicalInterruptPath, { force: true });
+            interruptRequested = true;
+            if (!mechanical)
+                intervened = true;
+        }
+        recorder.agentEndWaiting();
+    });
+    on("agent_settled", (_event, ctx) => {
+        // A queued self-reload owns the next continuation, not this acknowledgement.
+        if (reloadPending || !runtimeActive)
+            return;
+        // Cancellation receipts are passive. They may be appended after agent_end
+        // and must release ownership without starting a turn after an explicit Stop.
+        if (replication) {
+            for (const entry of ctx.sessionManager.getBranch()) {
+                if (entry.type === "custom" && entry.customType === "web-search:cancelled" && entry.data?.status === "cancelled")
+                    work.toolResult(entry.data);
+            }
+            persistWork();
+        }
+        const outcome = classifyAutoExitOutcome(latestAgentEndMessages, interruptRequested);
+        const assistant = newestAssistantEntry(latestAgentEndMessages);
+        if (!outcome || !assistant) {
+            if (replication && resumeTurnStarted && !movePending) {
+                const payload = { type: "error", errorMessage: "Replica stopped without a final assistant response." };
+                rememberStop(payload);
+                return finishAfterDrain(ctx, stopPayload ?? payload);
+            }
+            return;
+        }
+        if (resumeBaselineAssistantIds.has(assistant.id)) {
+            // Pi replays the previous assistant turn while opening a resumed session.
+            // Its settlement is not the follow-up requested by the parent.
+            return;
+        }
+        if (!resumeTurnStarted || (process.env.PI_SUBAGENT_RESUME === "1" && !resumeInputSeen))
+            return;
+        if ((!replication && intervened) || movePending)
+            return;
+        const observedSettledChildId = settledChildResultId;
+        settledChildResultId = undefined;
+        const terminalAutoExit = autoExit && (replication || outcome === "clean" || outcome === "empty");
+        const lineage = lineageFromEnvironment();
+        const lineageState = lineage ? reduceLineage(lineage.rootDir) : undefined;
+        const anyDescendantPending = terminalAutoExit &&
+            !!lineage &&
+            !!lineageState &&
+            hasUndrainedDescendants(lineageState, lineage.nodeId);
+        const descendantPending = terminalAutoExit &&
+            !!lineage &&
+            !!lineageState &&
+            hasOtherUndrainedDescendants(lineageState, lineage.nodeId, observedSettledChildId);
+        const waitsForChildResult = !treeOwner && descendantPending && (!replication || outcome === "clean");
+        recorder.agentSettled({
+            outcome,
+            assistantId: assistant.id,
+            stopReason: assistant.stopReason,
+            errorMessage: assistant.errorMessage,
+            empty: assistant.empty,
+            turnIndex: latestTurnIndex,
+            autoExit: terminalAutoExit && !waitsForChildResult,
+            publish: !waitsForChildResult && (treeOwner || !anyDescendantPending),
+        });
+        if (!terminalAutoExit || waitsForChildResult)
+            return;
+        const summary = assistant.text?.trim();
+        const payload = replication && stopPayload?.type === "error"
+            ? stopPayload
+            : replication && (outcome !== "clean" || !summary)
+                ? { type: "error", errorMessage: assistant.errorMessage ?? (outcome === "intentional-abort" || outcome === "unexpected-abort" ? "Replica was interrupted." : "Replica returned no required summary.") }
+                : { type: "done", ...(replication ? { summary: assistant.text } : {}) };
+        if (replication)
+            rememberStop(payload);
+        // Pi checks the shutdown flag after awaiting its settled handlers.
+        return finishAfterDrain(ctx, payload);
+    });
+    on("turn_start", (event) => {
+        latestTurnIndex = event.turnIndex;
+        recorder.turnStart(latestTurnIndex);
+    });
+    on("turn_end", (event) => {
+        recorder.turnEnd(event.turnIndex);
+    });
+    on("before_provider_request", () => {
+        recorder.beforeProviderRequest();
+    });
+    on("after_provider_response", () => {
+        recorder.afterProviderResponse();
+    });
+    on("message_start", (event) => {
+        if (replication && work.message(event.message)) {
+            closureVersion++;
+            clearStop();
+            latestAgentEndMessages = undefined;
+            persistWork();
+        }
+        settledChildResultId =
+            settledChildIdFromMessage(event.message) ?? settledChildResultId;
+    });
+    on("message_update", (event) => {
+        recorder.messageUpdate(event.assistantMessageEvent?.type);
+    });
+    on("tool_execution_start", (event) => {
+        if (replication) {
+            closureVersion++;
+            work.toolStarted(event.toolCallId, event.toolName);
+        }
+        recorder.toolExecutionStart(event.toolCallId, event.toolName);
+    });
+    on("tool_call", (event, ctx) => {
+        if (event.toolName === "teleport" && ["jump", "back"].includes(String(event.input.action))) {
+            movePending = true;
+            const file = ctx.sessionManager.getSessionFile();
+            const binding = file && readSessionBinding(file);
+            if (binding)
+                beginChildSessionMove(binding);
+        }
+        recorder.toolCall(event.toolCallId, event.toolName);
+    });
+    on("tool_execution_update", (event) => {
+        recorder.toolExecutionUpdate(event.toolCallId, event.toolName);
+    });
+    on("tool_result", (event, ctx) => {
+        if (event.toolName === "pi_extension_dev_reload_self" && !event.isError && event.details?.queued)
+            reloadPending = true;
+        if (event.toolName === "teleport" && event.isError) {
+            movePending = false;
+            bindSessionRuntime(pi, ctx);
+        }
+        recorder.toolResult(event.toolCallId, event.toolName);
+    });
+    on("tool_execution_end", async (event) => {
+        if (replication) {
+            // tool_result handlers can still transform receipts, including nested calls.
+            for (const fact of workFacts(event.result)) {
+                // Inspection is not a process launch or proof of job ownership.
+                const inspection = ["read", "search", "select"].includes(event.toolName);
+                if (!event.isError)
+                    work.toolResult(fact, inspection, event.toolName, event.toolCallId);
+                if (!inspection)
+                    await work.trackProcesses(fact);
+            }
+            work.toolEnded(event.toolCallId);
+            persistWork();
+        }
+        recorder.toolExecutionEnd(event.toolCallId, event.toolName);
+    });
+    on("message_end", (event, ctx) => {
+        const message = event.message;
+        if (message.customType === "pi-reload-self" && message.details?.status === "blocked")
+            reloadPending = false;
+        if (message.customType === "pi-agent-teleport-failure") {
+            movePending = false;
+            bindSessionRuntime(pi, ctx);
+        }
+    });
+    on("session_shutdown", (event) => {
+        runtimeActive = false;
+        if (stopTimer)
+            clearInterval(stopTimer);
+        if (replication && event.reason === "quit" && !movePending) {
+            const sessionFile = process.env.PI_SUBAGENT_SESSION;
+            if (sessionFile && !existsSync(`${sessionFile}.exit`)) {
+                writeBindingFile(`${sessionFile}.exit`, { type: "error", errorMessage: "Replica closed without a saved completion." });
+            }
+        }
+        for (const unsubscribe of unsubscribers)
+            unsubscribe();
+        lifecycles.delete(pi.events);
+        if (lifecycleSession)
+            lifecycleSessions.delete(lifecycleSession);
+        recorder.sessionShutdown(event.reason);
+    });
+    // Toggle expand/collapse with Ctrl+J
+    pi.registerShortcut("ctrl+j", {
+        description: "Toggle subagent tools widget",
+        handler: (ctx) => {
+            expanded = !expanded;
+            renderWidget(ctx, null);
+        },
+    });
+}