pi-famulus 0.1.9 → 0.2.1

package/src/index.ts

@@ -19,11 +19,12 @@ import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-w
 import { resolveAgent as resolveAgentDef } from "./agents/definition";
 import { createAgentLoader, type AgentLoader } from "./agents/loader";
 import { createBashOverride } from "./bash-override";
+import { cleanupSessionSpillFiles } from "./bounded-output";
 import { createComms, type CommsWithOrigin } from "./comms/comms";
 import { createRegistryCommsHost } from "./comms/registry-host";
-import { createAgentMessageTool, createContactSupervisorTool } from "./comms/tools";
+import { createAgentMessageTool } from "./comms/tools";
 import { registerReplyCommand } from "./comms/reply-command";
-import { describeManagerSearch, getFamulusHome, loadConfig, resolveManagerPath, resolveSubagentConfig } from "./config";
+import { describeManagerSearch, getFamulusHome, loadConfig, resolveManagerPath, resolveSubagentConfig, taskOutputPath } from "./config";
 import { ensureNativeManagerInstalled } from "./native-manager.js";
 import type { TaskExitInfo } from "./format";
 import { EXTENSION_VERSION, ManagerClient, type ManagerEvent, type TaskRecord } from "./manager-client";
@@ -31,11 +32,12 @@ import { createMonitorTool, exitEventFromRecord, MonitorRegistry } from "./monit
 import { admitAgentChild, reregisterAgentLeases } from "./subagent/admission";
 import { NotifyCenter } from "./notify";
 import { onWakeMessageEnd, registryStatusLookup } from "./wake-delivery";
-import { createChildBashTool } from "./subagent/child-bash";
 import { ChildShellTracker, createOverrunNotifier } from "./subagent/overrun";
 import {
   agentEndReason,
   headOf,
+  loadAgentChildRecords,
+  findAgentChildRecord,
   tailOf,
   updateAgentChildMetrics,
   writeAgentChildRecord,
@@ -43,8 +45,13 @@ import {
 } from "./subagent/agent-records";
 import { TranscriptWriter } from "./subagent/transcript";
 import { FleetWidget } from "./subagent/fleet-widget";
-import { WorkIndex, type WorkItem } from "./work-index";
-import { createPiSessionFn, isFamulusChildSession, modelCandidates } from "./subagent/pi-runtime";
+import { printModeDropWarning, WORK_RETAIN_MS, WorkIndex, type WorkItem } from "./work-index";
+import { fileURLToPath } from "node:url";
+import { AGENT_WORK_KINDS, type AgentWorkKind } from "./subagent/types";
+import { isFamulusChildSession, modelCandidates } from "./subagent/pi-runtime";
+import { createHostedSessionFn } from "./subagent/hosted-session";
+import { isHostedChildProcess, registerChildMode } from "./child-mode";
+import { openAttachView, registerAttachCommand } from "./tui/attach-command";
 import { SubagentRegistry } from "./subagent/registry";
 import { InProcessRunner } from "./subagent/runner";
 import { createSubagentTool } from "./subagent/tool";
@@ -56,6 +63,52 @@ import { registerTasksCommand } from "./tui/tasks-command";
 import { stderrPathFor } from "./tui/task-output-paths";
 import { shellWakeTitle } from "./wake";
 
+async function promptIfHostedSession(
+  c: ManagerClient,
+  live: () => ExtensionContext | null,
+  query: { sessionFile?: string | null; sessionId?: string },
+  where: "start" | "switch",
+): Promise<"takeover" | "stay" | "none"> {
+  if (!c.isAvailable() || c.protocolLevel() < 6) return "none";
+  const found = await c.hostedLookup({
+    ...(query.sessionId ? { sessionId: query.sessionId } : {}),
+    ...(query.sessionFile ? { sessionFile: query.sessionFile } : {}),
+  }).catch(() => null);
+  if (!found || found.residency !== "warm" || typeof found.child_id !== "string") return "none";
+  const uiCtx = live();
+  if (!uiCtx) return "none";
+  if (where === "start" && query.sessionId && uiCtx.sessionManager.getSessionId() !== query.sessionId) return "none";
+  if (!uiCtx.hasUI) {
+    uiCtx.ui.notify(
+      "This session file belongs to a warm hosted subagent. Use /attach from the parent, or open it in the TUI to take over.",
+      "warning",
+    );
+    return "stay";
+  }
+  const choice = await uiCtx.ui.select("This session is hosted by pi-famulus", [
+    "Attach to the hosted process",
+    "Take over",
+    "Cancel",
+  ]);
+  if (choice === "Take over") {
+    try {
+      await c.agentTakeover(found.child_id);
+      return "takeover";
+    } catch (err) {
+      uiCtx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      return "stay";
+    }
+  }
+  if (choice === "Attach to the hosted process") {
+    try {
+      await openAttachView(uiCtx, c, found.child_id);
+    } catch (err) {
+      uiCtx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+    }
+  }
+  return "stay";
+}
+
 /** Read only the tail of a task output file for the notification preview (≤ maxChars). */
 export function readPreview(outputPath: string | undefined, maxChars: number): string {
   if (!outputPath) return "";
@@ -64,7 +117,8 @@ export function readPreview(outputPath: string | undefined, maxChars: number): s
   return tail.text.length <= maxChars ? tail.text : tail.text.slice(-maxChars);
 }
 
-function toExitStatus(event: ManagerEvent): TaskExitInfo["status"] {
+/** Map a manager exit event to the background-wake status. Exported for tests. */
+export function toExitStatus(event: ManagerEvent): TaskExitInfo["status"] {
   // The manager died without shutting down; its runner took the task down.
   if (event.end_reason === "manager-crash") return "orphaned";
   if (event.signal) return "killed";
@@ -77,6 +131,10 @@ interface FamulusRuntime {
 }
 
 export default function (pi: ExtensionAPI): void {
+  if (isHostedChildProcess()) {
+    registerChildMode(pi);
+    return;
+  }
   if (isFamulusChildSession(pi)) return;
   // A /reload parked the previous instance's runtime: adopt it so its shells,
   // monitors and subagents keep running (see reload-handoff.ts). Another
@@ -166,6 +224,8 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
    * is mis-labeled as a parent "Background command" wake (§4.2 / §4.6).
    */
   const notifyOnExit = new Set<string>();
+  /** Sessions that already received the crash-recovery notice. */
+  const recoveredSessions = new Set<string>();
   const exitGate = new ExitNotifyGate<ManagerEvent>({ clock });
   const workIndex = new WorkIndex({ clock });
   const patchExited = (taskId: string, event: ManagerEvent): void => {
@@ -235,6 +295,136 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
     }
     return out;
   };
+  /**
+   * Parent-owned shells this process did not start (the previous pi died
+   * while the daemon stayed up). Running ones join the index and get an
+   * exit wake; recent finished ones are delivered the same way.
+   * manager-shutdown / manager-crash leftovers stay for the crash notice.
+   */
+  const adoptParentShells = (tasks: TaskRecord[]): void => {
+    const sid = ctx?.sessionManager.getSessionId() ?? "";
+    const now = clock.now();
+    for (const task of tasks) {
+      if (task.kind !== "shell") continue;
+      if (task.origin?.via === "child-bash") continue;
+      if (sid && task.session_id && task.session_id !== sid) continue;
+      if (workIndex.get(task.task_id) || taskMeta.has(task.task_id)) continue;
+      const startedAt = task.started_at ?? now;
+      taskMeta.set(task.task_id, {
+        kind: "shell",
+        command: task.command ?? "",
+        cwd: task.cwd,
+        startedAt,
+      });
+      if (task.status === "running") {
+        upsertBackgroundTask(task.task_id, startedAt);
+        markNotifyOnExit(task.task_id);
+        continue;
+      }
+      if (task.end_reason === "manager-shutdown" || task.end_reason === "manager-crash") continue;
+      if (task.ended_at != null && now - task.ended_at > WORK_RETAIN_MS) continue;
+      if (task.status !== "completed" && task.status !== "failed" && task.status !== "killed") continue;
+      upsertBackgroundTask(task.task_id, startedAt);
+      deliverExit(task.task_id, exitEventFromRecord(task));
+    }
+  };
+  /**
+   * A running disk record whose hosted process is gone: interrupt the live
+   * handle when this process still holds it (daemon crash), otherwise
+   * write the record. Warm children stay for resume.
+   */
+  const settleDeadHostedChildren = async (
+    sessionId: string,
+    opts: { interruptLive?: boolean } = {},
+  ): Promise<AgentChildRecord[]> => {
+    const manager = client;
+    const registry = subagentRegistry;
+    const center = notifyCenter;
+    const stale = loadAgentChildRecords(home, { sessionId, includeTerminal: false });
+    const lost: AgentChildRecord[] = [];
+    for (const rec of stale) {
+      if (rec.status !== "running" && rec.status !== "pending") continue;
+      const handle = registry?.handle(rec.child_id);
+      // A local admission queue has no hosted process to look up yet.
+      if (handle?.status() === "pending") continue;
+      let live = false;
+      if (manager?.isAvailable() && manager.protocolLevel() >= 6) {
+        const found =
+          await manager.hostedLookup({ sessionId: rec.child_id }).catch(() => null);
+        if (client !== manager || subagentRegistry !== registry || notifyCenter !== center) return [];
+        live = Boolean(found && (found.residency === "warm" || found.activity === "running" || found.activity === "starting"));
+      }
+      if (live) continue;
+      if (handle && (handle.status() === "running" || handle.status() === "pending")) {
+        if (!opts.interruptLive) continue;
+        await handle.interrupt().catch(() => {});
+        if (client !== manager || subagentRegistry !== registry || notifyCenter !== center) return [];
+      } else {
+        writeAgentChildRecord(home, {
+          ...rec,
+          status: "interrupted",
+          ended_at: rec.ended_at ?? clock.now(),
+          end_reason: "interrupted",
+          error: rec.error ?? "parent session ended",
+        });
+      }
+      lost.push(rec);
+    }
+    return lost;
+  };
+  /**
+   * The previous process died. Settle stale running agent records (the child
+   * is gone) and tell the model about that work and about commands the
+   * daemon already ended as manager-shutdown / manager-crash.
+   * A hosted child that is still warm is left for resume.
+   */
+  const recoverCrashedSession = async (sessionId: string): Promise<void> => {
+    if (!sessionId || recoveredSessions.has(sessionId)) return;
+    const manager = client;
+    const center = notifyCenter;
+    recoveredSessions.add(sessionId);
+    const interrupted =
+      await settleDeadHostedChildren(sessionId);
+    if (client !== manager || notifyCenter !== center) return;
+    let killed: TaskRecord[] = [];
+    if (manager?.isAvailable()) {
+      try {
+        const tasks = await manager.list(true);
+        if (client !== manager || notifyCenter !== center) return;
+        killed = tasks.filter((task) => {
+          if (task.session_id && task.session_id !== sessionId) return false;
+          if (task.kind !== "shell") return false;
+          return task.end_reason === "manager-shutdown" || task.end_reason === "manager-crash";
+        });
+      } catch {
+        killed = [];
+      }
+    }
+    if (interrupted.length === 0 && killed.length === 0) {
+      recoveredSessions.delete(sessionId);
+      return;
+    }
+    const lines = [
+      "System wake — not a new user message.",
+      "",
+      "This session was reopened after the previous process ended.",
+    ];
+    for (const rec of interrupted) {
+      lines.push(`Interrupted subagent ${rec.child_id} (${rec.name}).`);
+    }
+    for (const task of killed) {
+      lines.push(`Command ${task.task_id} ended while the session was gone (${task.end_reason ?? task.status}).`);
+    }
+    center?.notify({
+      customType: "pi-famulus-wake",
+      content: lines.join("\n"),
+      details: {
+        kind: "session-recovery",
+        children: interrupted.map((rec) => rec.child_id),
+        tasks: killed.map((task) => task.task_id),
+      },
+    });
+  };
   /**
    * Settle everything the manager reports as ended that we still show live:
    * monitors in the registry and shell/monitor rows in the index. Runs when
@@ -246,6 +436,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
    */
   const syncWithManager = async (): Promise<void> => {
     const c = client;
+    const center = notifyCenter;
     let tasks: TaskRecord[];
     if (c && c.isAvailable()) {
       try {
@@ -260,7 +451,9 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       if (!disk) return;
       tasks = disk;
     }
+    if (client !== c || notifyCenter !== center) return;
     monitorRegistry?.reconcile(tasks);
+    adoptParentShells(tasks);
     for (const task of workIndex.staleLive(tasks)) {
       const event = exitEventFromRecord(task);
       // Route through the gate: if the real task_exited is processed after
@@ -414,6 +607,10 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
     clock,
     syncWithManager: deps.syncWithManager,
   });
+  registerAttachCommand(pi, {
+    getClient: () => client,
+    getRegistry: () => subagentRegistry,
+  });
   famulusInfo = {
     extensionVersion: EXTENSION_VERSION,
     managerPath,
@@ -447,9 +644,11 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
   // M4: comms host bridges the registry and the NotifyCenter. A single Comms
   // instance lives at extension scope (mailbox is per-run namespaced; pending
   // waiters are resolved via dispose() on session_shutdown).
+  let watchResume: (childId: string) => void = () => {};
   const commsHost = createRegistryCommsHost({
     getRegistry: () => subagentRegistry,
     getNotifyCenter: () => notifyCenter,
+    onResumeAccepted: (childId) => watchResume(childId),
   });
   const comms: CommsWithOrigin = createComms(commsHost, {
     decisionTimeoutMs: subagentConfig.decisionTimeoutMs,
@@ -466,11 +665,48 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       defaultTimeoutMs: subagentConfig.timeoutMs,
       defaultConcurrency: subagentConfig.concurrency,
       clock,
+      registerResumeWatch: (watch) => {
+        watchResume = watch;
+      },
       resolveAgent: (name) => {
         const loader = agentLoader;
         if (!loader) return resolveAgentDef([], name); // builtins-only fallback
         return resolveAgentDef(loader.reload().definitions, name);
       },
+      recoverChild: async (childId) => {
+        const registry = subagentRegistry;
+        if (!registry) return undefined;
+        const rec = findAgentChildRecord(home, childId);
+        if (!rec) return undefined;
+        if (registry.handle(rec.child_id)) {
+          return registry.get(rec.run_id);
+        }
+        const workKind = AGENT_WORK_KINDS.includes(rec.work_kind as AgentWorkKind)
+          ? rec.work_kind as AgentWorkKind
+          : undefined;
+        const loader = agentLoader;
+        const agent = resolveAgentDef(loader ? loader.reload().definitions : [], rec.agent);
+        registry.adoptExisting({
+          runId: rec.run_id,
+          childId: rec.child_id,
+          name: rec.name,
+          agent: rec.agent,
+          workKind,
+          startedAt: rec.started_at,
+          prompt: rec.prompt_head,
+        });
+        await registry.attachChild({
+          childId: rec.child_id,
+          runId: rec.run_id,
+          name: rec.name,
+          prompt: rec.prompt_head ?? "",
+          agent,
+          timeoutMs: subagentConfig.timeoutMs,
+          depth: 1,
+          ...(workKind ? { workKind } : {}),
+        });
+        return registry.get(rec.run_id);
+      },
       listModels: () => {
         const current = ctx?.model;
         return modelCandidates({
@@ -546,11 +782,78 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       sessionId: startCtx.sessionManager.getSessionId(),
       managerPath,
       cwd: startCtx.cwd,
+      sessionFile: startCtx.sessionManager.getSessionFile?.(),
       clock,
       log: () => {}, // keep quiet; degradation is surfaced via tools
     });
 
+    // Hosted children run bash in their own process. The parent learns the
+    // foreground shell from task_started (origin child-bash) so overrun wakes
+    // still carry <shell>.
+    const childShells = new ChildShellTracker();
+    const parentSessionId = startCtx.sessionManager.getSessionId();
+    // Bind this session's notify centre and client. After /new /resume /fork
+    // the outer `notifyCenter` is replaced; late events on the old client
+    // must not follow that rebinding.
+    const sessionNotify = notifyCenter;
+    const sessionClient = client;
     client.onEvent((event) => {
+      if (client !== sessionClient) return;
+      const hosted = event as ManagerEvent & {
+        child_id?: string;
+        reason?: string;
+        request_id?: string;
+        message?: string;
+        name?: string;
+        residency?: string;
+        driver?: string;
+        last_text?: string;
+        request?: { type?: string; id?: string; method?: string; title?: string; message?: string };
+      };
+      if (hosted.event === "agent_comms" && hosted.child_id && hosted.request_id) {
+        const reason = hosted.reason === "need_decision" ? "need_decision" : "progress_update";
+        void comms.contactSupervisor(hosted.child_id, reason, hosted.message ?? "").then((reply) => {
+          if (reason === "need_decision") void client?.agentCommsReply(hosted.request_id!, hosted.child_id!, reply).catch(() => {});
+        }).catch(() => {});
+        return;
+      }
+      if (hosted.event === "agent_ui" && hosted.child_id) {
+        const request = hosted.request ?? {};
+        const method = request.method;
+        if (method !== "select" && method !== "confirm" && method !== "input" && method !== "editor") return;
+        const title = typeof request.title === "string" ? request.title : "";
+        const body = typeof request.message === "string" ? request.message : "";
+        sessionNotify?.notify({
+          customType: "pi-famulus-wake",
+          content:
+            `System wake — not a new user message.\n\n` +
+            `Subagent ${hosted.child_id} is waiting for a ${method}` +
+            (title ? `: ${title}` : ".") +
+            (body ? `\n${body}` : ""),
+          details: {
+            kind: "supervisor-request",
+            from: hosted.child_id,
+            method,
+            ...(title ? { title } : {}),
+            ...(body ? { message: body } : {}),
+          },
+        });
+        return;
+      }
+      if (hosted.event === "agent_detach" && hosted.child_id) {
+        sessionNotify?.notify({
+          customType: "pi-famulus-wake",
+          content: `System wake — not a new user message.\n\nThe user talked to ${hosted.name ?? hosted.child_id} directly.\n${hosted.last_text ?? ""}`,
+          details: { kind: "supervisor-update", from: hosted.child_id, name: hosted.name ?? hosted.child_id, message: hosted.last_text ?? "" },
+        });
+        return;
+      }
+      if (hosted.event === "agent_state" && hosted.child_id) {
+        const handle = subagentRegistry?.handle(hosted.child_id) as { pauseStall?: () => void; resumeStall?: () => void } | undefined;
+        if (hosted.driver === "user") handle?.pauseStall?.();
+        else handle?.resumeStall?.();
+        return;
+      }
       if (event.event === "task_started" && event.task_id) {
         const prior = taskMeta.get(event.task_id);
         taskMeta.set(event.task_id, {
@@ -562,6 +865,14 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
               ? { startedAt: prior.startedAt }
               : {}),
         });
+        if (event.origin?.via === "child-bash" && event.origin.child_id) {
+          childShells.start(event.origin.child_id, {
+            taskId: event.task_id,
+            command: event.command ?? "",
+            startedAt: typeof event.ts === "number" ? event.ts : clock.now(),
+            outputPath: taskOutputPath(home, parentSessionId, event.task_id),
+          });
+        }
         if (notifyOnExit.has(event.task_id) && typeof event.ts === "number") {
           upsertBackgroundTask(event.task_id, event.ts);
         }
@@ -584,6 +895,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         return;
       }
       if (event.event === "task_exited" && event.task_id) {
+        childShells.endByTask(event.task_id);
         // A known monitor closes (and patches the index via onExited); an
         // unknown id is buffered in case a monitor start is about to claim it.
         if (monitorRegistry?.handleExit(event.task_id, event)) return;
@@ -595,20 +907,39 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       }
     });
     client.onReconnect(() => {
+      if (client !== sessionClient) return;
       // A daemon restart may drop permits; a same-session rebind may retain
       // them. Keep each kind for idempotent re-registration and mark all local
       // leases pending until the daemon confirms them.
       for (const childId of globalAgentLeases.keys()) pendingAgentLeases.add(childId);
-      void monitorRegistry?.rewatchAll().then(() => syncWithManager());
+      void monitorRegistry?.rewatchAll().then(() => {
+        if (client === sessionClient) return syncWithManager();
+      });
       void (async () => {
-        const manager = client;
-        if (!manager || manager.protocolLevel() < 4) {
+        const manager = sessionClient;
+        if (manager.protocolLevel() < 4) {
           capacityNotice("daemon too old");
           return;
         }
         // The registry and its child ids survive socket reconnects in this
         // extension process; held ids include resumable interrupted children.
         await reconcileAgentLeases(manager);
+        if (client !== manager) return;
+        const sid = parentSessionId;
+        const lost =
+          await settleDeadHostedChildren(sid, { interruptLive: true });
+        if (lost.length > 0) {
+          sessionNotify?.notify({
+            customType: "pi-famulus-wake",
+            content: [
+              "System wake — not a new user message.",
+              "",
+              "The daemon restarted. Hosted children that were running are gone.",
+              ...lost.map((rec) => `Interrupted subagent ${rec.child_id} (${rec.name}).`),
+            ].join("\n"),
+            details: { kind: "session-recovery", children: lost.map((rec) => rec.child_id) },
+          });
+        }
       })().catch(() => {});
     });
 
@@ -633,9 +964,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         "warning",
       );
     }
-    // The foreground shell each child is blocked on, for its overrun wake.
-    const childShells = new ChildShellTracker();
-    const createSession = createPiSessionFn({
+    const createSession = createHostedSessionFn({
       getModelRegistry: () => ctx?.modelRegistry ?? null,
       getModelRuntime: () => {
         const registry = ctx?.modelRegistry as { runtime?: unknown } | null | undefined;
@@ -646,29 +975,10 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       getScopedModels: () => ctx?.scopedModels ?? [],
       getCwd: () => ctx?.cwd ?? process.cwd(),
       getProjectTrusted: () => ctx?.isProjectTrusted() ?? false,
-      customTools: (req) => {
-        const tools: Array<ToolDefinition<any, any, any>> = [
-          // M4: every child can reach the supervisor and its siblings.
-          createContactSupervisorTool(comms, req.childId),
-          createAgentMessageTool(comms, { kind: "child", childId: req.childId, runId: req.runId }, commsHost, clock),
-        ];
-        // The no-background bash variant replaces the built-in bash inside
-        // child sessions (custom tools override builtins by name).
-        tools.push(
-          createChildBashTool({
-            getClient: () => client,
-            home,
-            sessionId: () => ctx?.sessionManager.getSessionId() ?? "",
-            sessionEnv: () => (ctx ? sessionEnv(ctx) : {}),
-            trackTask,
-            childId: req.childId,
-            runId: req.runId,
-            clock,
-            shells: childShells,
-          }),
-        );
-        return tools;
-      },
+      getClient: () => client,
+      getHome: () => home,
+      extensionEntry: fileURLToPath(import.meta.url),
+      piCommand: subagentConfig.piCommand,
     });
     // The registry outlives startCtx across a /reload, which leaves startCtx
     // stale; its closures keep plain values instead.
@@ -724,6 +1034,23 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         // One event per stall detection: an auto-resume follows unless the
         // retry budget (stallRetries) is already spent.
         logEvent("agent.stall", { child_id: childId, attempt });
+        notifyCenter?.notify({
+          customType: "pi-famulus-wake",
+          content:
+            `System wake — not a new user message.\n\n` +
+            `Subagent ${childId} stalled with no activity (attempt ${attempt}); retrying.`,
+          details: { kind: "subagent-stall", child_id: childId, attempt },
+        });
+      },
+      onToolLoop: (childId, toolName, args) => {
+        const argText = args && typeof args === "object" ? JSON.stringify(args) : String(args ?? "");
+        notifyCenter?.notify({
+          customType: "pi-famulus-wake",
+          content:
+            `System wake — not a new user message.\n\n` +
+            `Subagent ${childId} called ${toolName} three times in a row with the same arguments${argText ? `: ${argText}` : "."}`,
+          details: { kind: "subagent-loop", child_id: childId, tool: toolName, args },
+        });
       },
       // Soft deadline: the child keeps running; the parent decides.
       onOverrun: createOverrunNotifier({
@@ -811,6 +1138,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         };
         const endReason = agentEndReason(c.status, c.result);
         if (endReason) rec.end_reason = endReason;
+        if (c.result?.retryAfter !== undefined) rec.retry_after = c.result.retryAfter;
         const transcript = syncTranscript(c.childId);
         if (transcript) {
           rec.transcript = transcript;
@@ -840,12 +1168,16 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       }
     });
     startFleetWidget(startCtx);
+    if (client?.isAvailable()) {
+      await recoverCrashedSession(startCtx.sessionManager.getSessionId());
+    }
 
     // Connect in the background: a cold manager spawn must not stall the
     // first prompt. The cache install, if one is running, finishes first so a
     // missing optional package is not reported before it can be restored.
     // Tools call ensureAvailable() lazily before use.
-    const c = client;
+    if (client !== sessionClient) return;
+    const c = sessionClient;
     void nativeRestore
       .then((path) => {
         if (client !== c || !c) return null;
@@ -856,6 +1188,11 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         if (ok === null || client !== c || !c) return;
         if (ok) {
           if (c.protocolLevel() >= 4) void reconcileAgentLeases(c).catch(() => {});
+          const file = startCtx.sessionManager.getSessionFile?.();
+          const sid = startCtx.sessionManager.getSessionId();
+          void promptIfHostedSession(c, () => ctx, { sessionFile: file, sessionId: sid }, "start").catch(() => {});
+          void syncWithManager();
+          void recoverCrashedSession(sid);
           return;
         }
         // A /reload may have replaced startCtx by now; report to the live one.
@@ -885,6 +1222,8 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
     agentLoader = null;
     monitorRegistry?.disposeAll();
     notifyCenter?.dispose();
+    recoveredSessions.clear();
+    cleanupSessionSpillFiles();
     const current = client;
     client = null;
     if (current) {
@@ -900,6 +1239,14 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
   };
   const runtime: FamulusRuntime = { attach: (host) => binding.attach(host) };
 
+  pi.on("session_before_switch", async (event, switchCtx) => {
+    const file = event.targetSessionFile;
+    if (!file || !client?.isAvailable()) return;
+    const outcome = await promptIfHostedSession(client, () => switchCtx, { sessionFile: file }, "switch");
+    if (outcome === "none" || outcome === "takeover") return;
+    return { cancel: true };
+  });
+
   pi.on("session_shutdown", async (event) => {
     if (event.reason === "reload" && ctx) {
       // Keep the session's shells, monitors and subagents running; the
@@ -912,6 +1259,14 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       parkRuntime({ version: EXTENSION_VERSION, runtime, dispose: teardown });
       return;
     }
+    if (String((ctx as { mode?: string } | null)?.mode) === "print") {
+      const ids = [
+        ...workIndex.list().filter((item) => item.status === "running" || item.status === "pending").map((item) => item.id),
+        ...(subagentRegistry?.activeChildren() ?? []).map((child) => child.childId),
+      ];
+      const warning = printModeDropWarning([...new Set(ids)]);
+      if (warning) process.stderr.write(warning);
+    }
     await teardown();
   });