pi-agent-replicate 0.0.0-stage → 1.4.1

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

@@ -0,0 +1,878 @@
+/**
+ * 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,
+  type ExtensionAPI,
+  type BeforeAgentStartEvent,
+  type BeforeAgentStartEventResult,
+} 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, type SessionWorkSnapshot } from "./session-work.ts";
+import { replicaStopDue } from "./watchdog.ts";
+import { bindSessionRuntime, beginChildSessionMove, readSessionBinding, writeBindingFile } from "./session-binding.ts";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const lifecycleKey = Symbol.for("pi-herdr-subagents.child-lifecycle");
+const lifecycles: WeakSet<object> = (globalThis as any)[lifecycleKey] ??= new WeakSet<object>();
+
+const lifecycleSessions: Set<string> = (globalThis as any)[Symbol.for("pi-herdr-subagents.child-lifecycle-sessions")] ??= new Set<string>();
+/** Extension event facades differ, but one child process still owns one lifecycle. */
+export function hasChildLifecycle(pi: ExtensionAPI): boolean {
+  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.ts";
+
+import { waitForDeliveryDrain } from "./delivery-drain.ts";
+import { createDeliveryLog } from "./delivery-log.ts";
+import {
+  classifySettledOutcome,
+  type AssistantStopReason,
+  type NewestAssistantEntry,
+  type SettledOutcomeKind,
+} from "./settled-contract.ts";
+import {
+  hasUndrainedDescendants,
+  isLineageNodeDrained,
+  lineageFromEnvironment,
+  reduceLineage,
+  type LineageState,
+} from "./lineage.ts";
+export function shouldMarkUserTookOver(agentStarted: boolean): boolean {
+  return agentStarted;
+}
+
+/** Wait until this session's owned descendants have terminal delivery. */
+export async function waitForDescendantDrain(options: {
+  lineage?: { rootDir: string; nodeId?: string; parentNodeId?: string };
+  delay?: (ms: number) => Promise<void>;
+  now?: () => number;
+  onWaitOpen?: (info: { waitedSince: number }) => void;
+  onWaitRelease?: (info: { waitedSince: number; waitedMs: number }) => void;
+  projectWidget?: (projection: unknown) => void;
+  log?: (event: string, fields?: Record<string, unknown>) => void;
+} = {}): Promise<void> {
+  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: string, fields?: Record<string, unknown>) => 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(): boolean {
+  const contextPath = process.env.PI_SUBAGENT_TREE_CONTEXT;
+  if (!contextPath) return false;
+  let context: { treeDir?: string; ownerId?: string };
+  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(): Promise<void> {
+  while (hasPendingOwnedChildren()) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}
+
+
+function settledChildIdFromPrompt(prompt: unknown): string | undefined {
+  if (typeof prompt !== "string" || !/^Subagent .+ settled\.$/m.test(prompt)) return undefined;
+  return prompt.match(/^Delivery: settled:([^:\s]+):/m)?.[1];
+}
+
+
+function settledChildIdFromMessage(message: unknown): string | undefined {
+  if (!message || typeof message !== "object") return undefined;
+  const value = message as {
+    customType?: unknown;
+    content?: unknown;
+    details?: { kind?: unknown; outcome?: unknown; childId?: unknown };
+  };
+  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: LineageState,
+  ownerId: string,
+  settledChildId: string | undefined,
+): boolean {
+  return [...state.nodes.values()].some((child) =>
+    child.parentNodeId === ownerId &&
+    !isLineageNodeDrained(state, child.nodeId) &&
+    (child.nodeId !== settledChildId || child.autoExit !== true)
+  );
+}
+function textFromContent(content: unknown): string {
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (part): part is { type?: string; text?: string } =>
+        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: any[] | undefined,
+): NewestAssistantEntry | null {
+  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 as AssistantStopReason)
+          : 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: any[] | undefined,
+  interruptRequested = false,
+): SettledOutcomeKind | null {
+  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: boolean,
+  messages: any[] | undefined,
+): boolean {
+  const outcome = classifyAutoExitOutcome(messages);
+  return outcome === "clean" || outcome === "empty";
+}
+
+export interface SubagentErrorInfo {
+  errorMessage: string;
+  stopReason: "error";
+}
+
+/**
+ * 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: any[] | undefined,
+): SubagentErrorInfo | null {
+  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: any[] | undefined,
+):
+  | { type: "done" }
+  | { type: "error"; errorMessage: string; stopReason: "error" } {
+  const errorInfo = findLatestAssistantError(messages);
+  return errorInfo ? { type: "error", ...errorInfo } : { type: "done" };
+}
+
+export async function waitForPingAcknowledgement(
+  sessionFile: string,
+  pingId: string,
+  signal?: AbortSignal,
+  intervalMs = 50,
+): Promise<void> {
+  for (;;) {
+    if (signal?.aborted) throw new Error("Help request wait was cancelled");
+    try {
+      const current = JSON.parse(readFileSync(`${sessionFile}.exit`, "utf8")) as { type?: unknown; id?: unknown };
+      if (current.type !== "ping" || current.id !== pingId) return;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || error instanceof SyntaxError) return;
+      throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+export function parseDeniedTools(rawValue: string | undefined): string[] {
+  return (rawValue ?? "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+/** Build one hidden, session-persistent initialization message for requested skills. */
+export function buildSkillInitialization(
+  event: BeforeAgentStartEvent,
+  requestedSkills: string,
+  notify: (message: string, type?: "info" | "warning" | "error") => void,
+): BeforeAgentStartEventResult | undefined {
+  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: string[] = [];
+  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: ExtensionAPI, initialContext?: ExtensionContext): void {
+  const start = (ctx: ExtensionContext) => {
+    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: ExtensionAPI, initialContext: ExtensionContext): void {
+  if (hasChildLifecycle(pi)) return;
+  lifecycles.add(pi.events);
+  const lifecycleSession = process.env.PI_SUBAGENT_SESSION;
+  if (lifecycleSession) lifecycleSessions.add(lifecycleSession);
+  const unsubscribers: Array<() => void> = [];
+  const on: ExtensionAPI["on"] = ((event: any, handler: any) => {
+    const unsubscribe = (pi.on as (event: any, handler: any) => unknown)(event, handler);
+    if (typeof unsubscribe === "function") unsubscribers.push(unsubscribe as () => void);
+    return unsubscribe;
+  }) as ExtensionAPI["on"];
+  let toolNames: string[] = [];
+  let denied: string[] = [];
+  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 as SessionWorkSnapshot : 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: { ui: { setWidget: Function } }, _theme: any) {
+    ctx.ui.setWidget(
+      "subagent-tools",
+      (_tui: any, theme: any) => {
+        const box = new Box(1, 0, (text: string) =>
+          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: string) => theme.fg("dim", name))
+            .join(theme.fg("muted", ", "));
+
+          let deniedLine = "";
+          if (denied.length > 0) {
+            const deniedList = denied
+              .map((name: string) => 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: any[] | undefined;
+  let latestTurnIndex: number | undefined;
+  let settledChildResultId: string | undefined;
+	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<string>(
+    (() => {
+      if (process.env.PI_SUBAGENT_RESUME !== "1") return [];
+      try {
+        const value: unknown = JSON.parse(process.env.PI_SUBAGENT_RESUME_BASELINE_ASSISTANTS ?? "[]");
+        return Array.isArray(value) ? value.filter((id): id is string => 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: ExtensionContext) => {
+    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: ReturnType<typeof setInterval> | undefined;
+  let idleSince: number | undefined;
+  let stopPayload: Record<string, unknown> | undefined;
+  let checkingWork = false;
+  const refreshWork = async (): Promise<void> => {
+    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: Record<string, unknown>) => {
+    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: ExtensionContext) => {
+    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: ExtensionContext) => {
+    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: ExtensionContext,
+    payload: Record<string, unknown>,
+  ): Promise<void> => {
+    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<void>(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 as any).messages as any[] | undefined;
+    const eventTurnIndex = (event as any).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 as { status?: unknown })?.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 as any).turnIndex;
+    recorder.turnStart(latestTurnIndex);
+  });
+
+  on("turn_end", (event) => {
+    recorder.turnEnd((event as any).turnIndex);
+  });
+
+  on("before_provider_request", () => {
+    recorder.beforeProviderRequest();
+  });
+
+  on("after_provider_response", () => {
+    recorder.afterProviderResponse();
+  });
+
+  on("message_start", (event) => {
+    if (replication && work.message((event as any).message)) {
+      closureVersion++;
+      clearStop();
+      latestAgentEndMessages = undefined;
+      persistWork();
+    }
+    settledChildResultId =
+      settledChildIdFromMessage((event as any).message) ?? settledChildResultId;
+  });
+
+  on("message_update", (event) => {
+    recorder.messageUpdate((event as any).assistantMessageEvent?.type);
+  });
+
+  on("tool_execution_start", (event) => {
+    if (replication) { closureVersion++; work.toolStarted(event.toolCallId, event.toolName); }
+    recorder.toolExecutionStart(
+      (event as any).toolCallId,
+      (event as any).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 as any).toolCallId, (event as any).toolName);
+  });
+
+  on("tool_execution_update", (event) => {
+    recorder.toolExecutionUpdate(
+      (event as any).toolCallId,
+      (event as any).toolName,
+    );
+  });
+
+  on("tool_result", (event, ctx) => {
+    if (event.toolName === "pi_extension_dev_reload_self" && !event.isError && (event.details as { queued?: boolean } | undefined)?.queued) reloadPending = true;
+    if (event.toolName === "teleport" && event.isError) { movePending = false; bindSessionRuntime(pi, ctx); }
+    recorder.toolResult((event as any).toolCallId, (event as any).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 as any).toolCallId,
+      (event as any).toolName,
+    );
+  });
+
+  on("message_end", (event, ctx) => {
+    const message = event.message as { customType?: string; details?: { status?: string } };
+    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 as any).reason);
+  });
+
+  // Toggle expand/collapse with Ctrl+J
+  pi.registerShortcut("ctrl+j", {
+    description: "Toggle subagent tools widget",
+    handler: (ctx) => {
+      expanded = !expanded;
+      renderWidget(ctx, null);
+    },
+  });
+
+}