pi-famulus 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-famulus",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Keep your main agent's context clean: subagents on cheaper models, long bash in the background, and monitors that wake the agent. One Rust daemon runs the shells.",
   "keywords": [
     "pi-package",
@@ -54,12 +54,12 @@
     "pi-famulus": "./bin/pi-famulus.js"
   },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.2.0",
-    "pi-famulus-linux-arm64": "0.2.0",
-    "pi-famulus-darwin-x64": "0.2.0",
-    "pi-famulus-darwin-arm64": "0.2.0",
-    "pi-famulus-win-x64": "0.2.0",
-    "pi-famulus-win-arm64": "0.2.0"
+    "pi-famulus-linux-x64": "0.2.1",
+    "pi-famulus-linux-arm64": "0.2.1",
+    "pi-famulus-darwin-x64": "0.2.1",
+    "pi-famulus-darwin-arm64": "0.2.1",
+    "pi-famulus-win-x64": "0.2.1",
+    "pi-famulus-win-arm64": "0.2.1"
   },
   "pi": {
     "extensions": [
@@ -70,7 +70,7 @@
     "deps": "nub install --frozen-lockfile --node-linker hoisted",
     "prompts": "node scripts/build-prompts.ts",
     "test": "vitest run",
-    "test:compat": "vitest run tests/unit/impl-child-resource-isolation.test.ts tests/unit/impl-child-tools.test.ts tests/unit/impl-child-guidelines.test.ts tests/unit/impl-subagent-lifecycle.test.ts tests/unit/impl-steering-drain.test.ts tests/unit/impl-model-spec.test.ts tests/unit/impl-eval-fixes.test.ts tests/integration/behavior-guidelines.test.ts",
+    "test:compat": "vitest run tests/unit/impl-child-resource-isolation.test.ts tests/unit/impl-child-tools.test.ts tests/unit/impl-child-guidelines.test.ts tests/unit/impl-subagent-lifecycle.test.ts tests/unit/impl-steering-drain.test.ts tests/unit/impl-model-spec.test.ts tests/unit/impl-eval-fixes.test.ts tests/unit/impl-hosted-child-failure.test.ts tests/unit/impl-hosted-child-rate-limit.test.ts tests/unit/impl-hosted-child-stuck.test.ts tests/unit/impl-hosted-child-tool-allowlist.test.ts tests/unit/impl-hosted-child-tool-activity.test.ts tests/unit/impl-hosted-child-ui-dialog.test.ts tests/unit/impl-hosted-child-steering.test.ts tests/unit/impl-hosted-docs.test.ts tests/integration/behavior-guidelines.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

package/src/bounded-output.ts

@@ -7,11 +7,26 @@
  * buffer or string on the event loop.
  */
 import { randomUUID } from "node:crypto";
-import { createWriteStream, type WriteStream } from "node:fs";
+import { createWriteStream, unlinkSync, type WriteStream } from "node:fs";
 import type { Readable } from "node:stream";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+/** Spill files created this process; unlinked on session shutdown. */
+const sessionSpillFiles = new Set<string>();
+
+/** Forget and delete every overflow file this session wrote. */
+export function cleanupSessionSpillFiles(): void {
+  for (const path of sessionSpillFiles) {
+    try {
+      unlinkSync(path);
+    } catch {
+      // already gone, or never created
+    }
+  }
+  sessionSpillFiles.clear();
+}
+
 export interface BoundedOutputOptions {
   /** Spill to a temp file once total bytes exceed this. */
   maxBytes: number;
@@ -122,6 +137,7 @@ export class BoundedOutput {
 
   private openSpill(): void {
     this.path = join(tmpdir(), `${this.opts.tempFilePrefix ?? "pi-famulus-bash"}-${randomUUID()}.log`);
+    sessionSpillFiles.add(this.path);
     const stream = createWriteStream(this.path);
     stream.on("error", () => {
       this.streamFailed = true;

package/src/format.ts

@@ -228,6 +228,8 @@ export interface SubagentChildInfo {
   status: "pending" | "running" | "completed" | "failed" | "interrupted";
   text: string;
   error?: string;
+  endReason?: "model-error" | "rate-limit";
+  retryAfter?: number;
   /** Non-fatal caveat from the child run (e.g. an adapted model spec). */
   warning?: string;
   /** Task prompt that was sent to this child. */
@@ -287,6 +289,8 @@ export function formatSubagentNotification(info: SubagentNotificationInfo): Form
       prompt: capPrompt(child.prompt ?? ""),
       result: capTail(child.text),
       ...(child.error ? { error: child.error } : {}),
+      ...(child.endReason ? { endReason: child.endReason } : {}),
+      ...(child.retryAfter !== undefined ? { retryAfter: child.retryAfter } : {}),
       ...(child.warning ? { warning: child.warning } : {}),
     })),
   });

package/src/index.ts

@@ -19,6 +19,7 @@ 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 } from "./comms/tools";
@@ -35,6 +36,8 @@ import { ChildShellTracker, createOverrunNotifier } from "./subagent/overrun";
 import {
   agentEndReason,
   headOf,
+  loadAgentChildRecords,
+  findAgentChildRecord,
   tailOf,
   updateAgentChildMetrics,
   writeAgentChildRecord,
@@ -42,8 +45,9 @@ import {
 } from "./subagent/agent-records";
 import { TranscriptWriter } from "./subagent/transcript";
 import { FleetWidget } from "./subagent/fleet-widget";
-import { WorkIndex, type WorkItem } from "./work-index";
+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";
@@ -113,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";
@@ -219,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 => {
@@ -288,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
@@ -299,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 {
@@ -313,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
@@ -533,6 +673,40 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         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({
@@ -618,7 +792,13 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
     // 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;
@@ -628,6 +808,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         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";
@@ -636,8 +817,31 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         }).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) {
-        notifyCenter?.notify({
+        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 ?? "" },
@@ -703,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(() => {});
     });
 
@@ -811,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({
@@ -898,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;
@@ -927,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;
@@ -946,6 +1191,8 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
           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.
@@ -975,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) {
@@ -1010,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();
   });
 

package/src/manager-client.ts

@@ -18,7 +18,7 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.2.0";
+const EXTENSION_VERSION = "0.2.1";
 export { EXTENSION_VERSION };
 // 5: speaks per-kind agent admission and queued acquire.
 const PROTOCOL = 6;
@@ -637,6 +637,8 @@ export class ManagerClient {
   async close(): Promise<void> {
     this.intentionalClose = true;
     this.state = "disconnected";
+    this.eventHandlers.clear();
+    this.reconnectHandlers.clear();
     this.failAllPending(new Error("manager client closed"));
     const socket = this.socket;
     this.socket = null;

package/src/notify.ts

@@ -311,4 +311,5 @@ export class NotifyCenter {
     }
     onDelivered?.(sourcePreview ?? (details?.kind === "monitor" ? (message.details as { event?: string }).event : undefined));
   }
+
 }

package/src/prompts.generated.ts

@@ -49,7 +49,7 @@ export const PROMPTS = {
   "tools.subagent.rules": ["When a <pi-famulus-wake kind=\"subagent-handover\"> arrives, read <prompt> and <result> immediately and continue: subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer children that are still running. Do not wait for the rest of the run.","Subagent runs that exceed the foreground budget continue in the background; you are notified per finished child and again when the run completes — do not poll.","A failed subagent does not fail the whole run; inspect per-subagent sections in the result.","<pi-famulus-wake> is a system wake, not a user reply. kind=subagent-handover is one child; kind=subagent-done is the whole run."],
   "tools.subagent.param.tasks": "Start new subagents in parallel. Use only when action is omitted. For any action call, omit tasks entirely; do not supply placeholder tasks.",
   "tools.subagent.param.tasks.agent": "Agent definition name (default: worker)",
-  "tools.subagent.param.tasks.prompt": "Task prompt for this subagent",
+  "tools.subagent.param.tasks.prompt": "Task prompt for this subagent. The child is a new process: it cannot see this conversation, so the prompt must be self-contained.",
   "tools.subagent.param.tasks.name": "Display name (default: agent name + ordinal)",
   "tools.subagent.param.work_kind": "Explicit planned workload class for machine-wide admission (default: other)",
   "tools.subagent.param.chain": "Start a new sequential chain (always awaited). Use only when action is omitted. For any action call, omit chain entirely.",

package/src/subagent/agent-records.ts

@@ -32,6 +32,8 @@ export interface AgentChildRecord {
   error?: string;
   /** Why the child ended (terminal statuses only). */
   end_reason?: AgentEndReason;
+  /** Seconds until a rate-limited provider may be retried, when known. */
+  retry_after?: number;
   /** Task prompt without the agent preamble, capped. */
   prompt_head?: string;
   /** Tail of the final result text, capped. */
@@ -58,6 +60,7 @@ export type AgentEndReason =
   | "completed"
   | "failed"
   | "model-error"
+  | "rate-limit"
   | "stalled"
   | "timeout"
   | "interrupted"
@@ -66,10 +69,11 @@ export type AgentEndReason =
 /** Map a terminal child status + result to the end_reason recorded on disk. */
 export function agentEndReason(
   status: AgentChildRecord["status"],
-  result: { error?: string; endReason?: "model-error" } | undefined,
+  result: { error?: string; endReason?: "model-error" | "rate-limit" } | undefined,
 ): AgentEndReason | undefined {
   if (status === "completed") return "completed";
   if (status === "failed") {
+    if (result?.endReason === "rate-limit") return "rate-limit";
     if (result?.endReason === "model-error") return "model-error";
     return result?.error === "stalled" ? "stalled" : "failed";
   }
@@ -174,6 +178,42 @@ function parseRecord(raw: string): AgentChildRecord | null {
 }
 
 /** Load agent child records from disk (all sessions under home). */
+/** Hosted children the daemon still has warm. They outlive a gone parent session. */
+export function warmHostedChildIds(home: string): Set<string> {
+  const out = new Set<string>();
+  try {
+    const { pid } = JSON.parse(readFileSync(join(home, "manager.pid"), "utf8")) as { pid?: unknown };
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return out;
+    try {
+      process.kill(pid, 0);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EPERM") return out;
+    }
+  } catch {
+    return out;
+  }
+  let files: string[];
+  try {
+    files = readdirSync(join(home, "agents")).filter((name) => name.endsWith(".json"));
+  } catch {
+    return out;
+  }
+  for (const file of files) {
+    try {
+      const value = JSON.parse(readFileSync(join(home, "agents", file), "utf8")) as {
+        residency?: string;
+        child_id?: string;
+      };
+      if (value.residency === "warm" && typeof value.child_id === "string") {
+        out.add(value.child_id);
+      }
+    } catch {
+      // skip bad hosted records
+    }
+  }
+  return out;
+}
+
 export function loadAgentChildRecords(
   home: string,
   opts: { sessionId?: string; includeTerminal?: boolean; connectedSessionIds?: ReadonlySet<string> } = {},
@@ -189,6 +229,7 @@ export function loadAgentChildRecords(
   } catch {
     return [];
   }
+  const warm = opts.connectedSessionIds === undefined ? new Set<string>() : warmHostedChildIds(home);
   const out: AgentChildRecord[] = [];
   for (const sid of sessionIds) {
     const dir = agentRecordsDir(home, sid);
@@ -205,7 +246,9 @@ export function loadAgentChildRecords(
         const disconnected =
           opts.connectedSessionIds !== undefined && !opts.connectedSessionIds.has(rec.session_id);
         const shown: AgentChildRecord =
-          disconnected && (rec.status === "pending" || rec.status === "running")
+          disconnected &&
+          (rec.status === "pending" || rec.status === "running") &&
+          !warm.has(rec.child_id)
             ? { ...rec, status: "interrupted" }
             : rec;
         const terminal =
@@ -220,6 +263,12 @@ export function loadAgentChildRecords(
   return out;
 }
 
+/** One child by id or name, across every session under home. */
+export function findAgentChildRecord(home: string, childIdOrName: string): AgentChildRecord | undefined {
+  const recs = loadAgentChildRecords(home, { includeTerminal: true });
+  return recs.find((rec) => rec.child_id === childIdOrName) ?? recs.find((rec) => rec.name === childIdOrName);
+}
+
 export function isAgentStatusActive(status: AgentChildRecord["status"]): boolean {
   return status === "pending" || status === "running";
 }

package/src/subagent/hosted-session.ts

@@ -66,10 +66,10 @@ export function createHostedSessionFn(deps: HostedSessionDeps): CreateSessionFn
       "--thinking", String(thinking),
       "--append-system-prompt", promptFile,
       ...(trustInherited ? [] : [deps.getProjectTrusted?.() ? "-a" : "-na"]),
-      ...(req.agent.tools ? ["--tools", req.agent.tools.join(",")] : []),
+      ...(req.agent.tools ? ["--tools", hostedChildTools(req.agent.tools).join(",")] : []),
     ];
     const env = { ...process.env } as Record<string, string>;
-    if (req.agent.tools) env.PI_FAMULUS_CHILD_TOOLS = req.agent.tools.join(",");
+    if (req.agent.tools) env.PI_FAMULUS_CHILD_TOOLS = hostedChildTools(req.agent.tools).join(",");
     env.PI_FAMULUS_CHILD_RUN = req.runId;
     env.PI_FAMULUS_CHILD_NAME = req.name;
     const spawned = await client.agentSpawn({
@@ -80,14 +80,7 @@ export function createHostedSessionFn(deps: HostedSessionDeps): CreateSessionFn
       cwd,
       env,
     });
-    let warning = model.warning;
-    try {
-      await client.agentInput(req.childId, "set_steering_mode", "all", "parent");
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const note = `Steering mode was not set (${message}); queued input may wait until the current turn ends.`;
-      warning = warning ? `${warning} ${note}` : note;
-    }
+    const warning = model.warning;
     await client.agentWatch(req.childId);
     const session = new HostedRpcSession(client, req.childId, {
       warning,
@@ -108,6 +101,7 @@ class HostedRpcSession implements ChildSessionAdapter {
   private readonly unsubscribe: () => void;
   private streaming = false;
   private lastText = "";
+  private lastFailure: { stopReason: "error" | "aborted"; errorMessage?: string } | undefined;
   private turns: { role: string; text: string }[] = [];
   private usage: ChildTokenUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
   private settle: (() => void) | null = null;
@@ -172,6 +166,10 @@ class HostedRpcSession implements ChildSessionAdapter {
     return this.lastText || undefined;
   }
 
+  getLastAssistantFailure(): { stopReason: "error" | "aborted"; errorMessage?: string } | undefined {
+    return this.lastFailure;
+  }
+
   getConversation() {
     return this.turns.map((turn) => ({ ...turn }));
   }
@@ -216,6 +214,9 @@ class HostedRpcSession implements ChildSessionAdapter {
       };
       if (event.activity === "running") this.streaming = true;
       if (event.activity === "idle" || event.activity === "failed") {
+        if (event.activity === "failed" && !this.lastFailure) {
+          this.lastFailure = { stopReason: "error", errorMessage: "hosted child process failed" };
+        }
         this.streaming = false;
         this.settle?.();
         this.settle = null;
@@ -223,7 +224,20 @@ class HostedRpcSession implements ChildSessionAdapter {
       return;
     }
     if (event.event !== "agent_rpc" || !event.record || typeof event.record !== "object") return;
-    const record = event.record as { type?: string; message?: { role?: string; content?: { type?: string; text?: string }[]; usage?: Record<string, unknown> }; toolCallId?: string };
+    const record = event.record as {
+      type?: string;
+      message?: {
+        role?: string;
+        content?: { type?: string; text?: string }[];
+        usage?: Record<string, unknown>;
+        stopReason?: string;
+        errorMessage?: string;
+      };
+      toolCallId?: string;
+      toolName?: string;
+      args?: unknown;
+      isError?: boolean;
+    };
     const type = record.type ?? "";
     if (type === "agent_start") this.streaming = true;
     if (type === "agent_settled") {
@@ -237,6 +251,18 @@ class HostedRpcSession implements ChildSessionAdapter {
         this.lastText = text;
         this.turns.push({ role: "assistant", text });
       }
+      const stopReason = record.message.stopReason;
+      if (stopReason === "error" || stopReason === "aborted") {
+        this.lastFailure = {
+          stopReason,
+          ...(record.message.errorMessage ? { errorMessage: record.message.errorMessage } : {}),
+        };
+        if (record.message.errorMessage) {
+          this.turns.push({ role: "assistant error", text: record.message.errorMessage });
+        }
+      } else {
+        this.lastFailure = undefined;
+      }
       const usage = record.message.usage;
       if (usage) {
         this.usage.input += num(usage.input);
@@ -249,10 +275,21 @@ class HostedRpcSession implements ChildSessionAdapter {
       const text = (record.message.content ?? []).map((part) => part.text ?? "").join("");
       if (text) this.turns.push({ role: "user", text });
     }
+    if (type === "tool_execution_end") {
+      const name = record.toolName ?? "tool";
+      const text = record.args === undefined ? name : `${name} ${JSON.stringify(record.args)}`;
+      this.turns.push({
+        role: record.isError ? `tool ${name} error` : `tool ${name}`,
+        text,
+      });
+    }
     const adapted: ChildSessionEvent = {
       type,
       ...(record.message?.role ? { role: record.message.role } : {}),
       ...(record.toolCallId ? { toolCallId: record.toolCallId } : {}),
+      ...(record.toolName ? { toolName: record.toolName } : {}),
+      ...(record.args !== undefined ? { args: record.args } : {}),
+      ...(record.isError !== undefined ? { isError: record.isError } : {}),
     };
     for (const listener of this.listeners) listener(adapted);
   }
@@ -262,6 +299,15 @@ function num(value: unknown): number {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+const SUPERVISOR_TOOLS = ["contact_supervisor", "agent_message"];
+
+/** Agent allowlists still keep the two supervisor tools. */
+export function hostedChildTools(tools: string[]): string[] {
+  const kept = new Set(tools);
+  for (const name of SUPERVISOR_TOOLS) kept.add(name);
+  return [...kept];
+}
+
 /** Request id for a child→parent decision. */
 export function newCommsRequestId(): string {
   return `rq_${randomUUID().slice(0, 8)}`;

package/src/subagent/registry.ts

@@ -342,6 +342,84 @@ export class SubagentRegistry implements RunRegistry {
   // M3 extensions beyond Appendix B
   // -------------------------------------------------------------------------
 
+  /**
+   * Reconstruct a run/child the previous parent process wrote to disk
+   * so resume can reattach by child_id.
+   */
+  adoptExisting(info: {
+    runId: string;
+    childId: string;
+    name: string;
+    agent: string;
+    workKind?: string;
+    startedAt?: number;
+    prompt?: string;
+  }): void {
+    if (this.children.has(info.childId)) return;
+    let run = this.runs.get(info.runId);
+    if (!run) {
+      run = {
+        runId: info.runId,
+        kind: "tasks",
+        status: "interrupted",
+        createdAt: info.startedAt ?? this.now(),
+        children: [],
+      };
+      this.runs.set(info.runId, run);
+    }
+    const child: InternalChild = {
+      childId: info.childId,
+      runId: info.runId,
+      name: info.name,
+      agent: info.agent,
+      workKind: info.workKind ?? "other",
+      status: "interrupted",
+      startedAt: info.startedAt ?? this.now(),
+      endedAt: this.now(),
+      turn: 1,
+      queueMs: 0,
+      prompt: info.prompt,
+    };
+    run.children.push(child);
+    this.children.set(child.childId, child);
+    this.emit(run);
+  }
+
+  /** Bind a live hosted session to an adopted child without sending its first prompt. */
+  async attachChild(req: ChildRunRequest): Promise<ChildHandle> {
+    const child = this.children.get(req.childId);
+    if (!child) throw new Error(`unknown child ${req.childId} (adoptExisting first)`);
+    const runner = this.runner;
+    if (!runner?.attach) {
+      throw new Error(`subagent ${req.childId} has no live session to resume`);
+    }
+    child.prompt = req.taskPrompt ?? req.prompt;
+    child.preamble = req.agent.systemPrompt || undefined;
+    child.model = req.model ?? req.agent.model;
+    let handle: ChildHandle;
+    try {
+      handle = await runner.attach(req, (startingHandle) => {
+        child.handle = startingHandle;
+      });
+    } catch (error) {
+      const failed = child.handle as DisposableChildHandle | undefined;
+      child.handle = undefined;
+      await failed?.dispose?.();
+      throw error;
+    }
+    if (!this.children.has(child.childId)) return handle;
+    child.handle = handle;
+    handle.result.then((result) => this.settleChild(child.childId, result));
+    const resolved = handle.resolvedModel();
+    if (resolved) {
+      const thinking = handle.effectiveThinkingLevel?.();
+      child.model = `${resolved}${thinking ? `:${thinking}` : ""}`;
+    }
+    const run = this.runs.get(child.runId);
+    if (run) this.emit(run);
+    return handle;
+  }
+
   /** Allocate a pending child inside a run. Returns the child id. */
   addChild(runId: string, info: { name: string; agent: string; workKind?: string }): string {
     const run = this.runs.get(runId);

package/src/subagent/runner.ts

@@ -87,6 +87,8 @@ export interface InProcessRunnerOptions {
   stallRetryDelayMs?: number;
   /** Called on every stall detection (before any retry), with the 1-based attempt. */
   onStall?: (childId: string, attempt: number) => void;
+  /** Same tool name and arguments three times in a row. */
+  onToolLoop?: (childId: string, toolName: string, args: unknown) => void;
   /** Overrun reminder interval (ms). Default 10 minutes. */
   overrunRepeatMs?: number;
   /** Abort ceiling per user turn (ms). 0/absent = off: the soft deadline never aborts. */
@@ -116,6 +118,20 @@ function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/** 429 / rate-limit text is recorded separately from other model errors. */
+export function classifyModelFailure(message: string): {
+  endReason: "model-error" | "rate-limit";
+  retryAfter?: number;
+} {
+  const rateLimited = /\b429\b|rate[\s-]?limit|too many requests/i.test(message);
+  if (!rateLimited) return { endReason: "model-error" };
+  const retry = /retry[\s-]?after[:\s]+(\d+)/i.exec(message);
+  return {
+    endReason: "rate-limit",
+    ...(retry ? { retryAfter: Number(retry[1]) } : {}),
+  };
+}
+
 export class InProcessRunner implements ChildRunner {
   private readonly opts: InProcessRunnerOptions;
 
@@ -129,6 +145,13 @@ export class InProcessRunner implements ChildRunner {
     await handle.launch();
     return handle;
   }
+
+  async attach(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<DisposableChildHandle> {
+    const handle = new InProcessChildHandle(req, this.opts);
+    onHandle?.(handle);
+    await handle.attachIdle();
+    return handle;
+  }
 }
 
 class InProcessChildHandle implements DisposableChildHandle {
@@ -138,6 +161,9 @@ class InProcessChildHandle implements DisposableChildHandle {
   private readonly stallRetries: number;
   private readonly stallRetryDelayMs: number;
   private readonly onStall?: (childId: string, attempt: number) => void;
+  private readonly onToolLoop?: (childId: string, toolName: string, args: unknown) => void;
+  private lastToolKey: string | null = null;
+  private lastToolCount = 0;
   private readonly overrunRepeatMs: number;
   private readonly hardTimeoutMs: number;
   private readonly onOverrun?: (tick: OverrunTick) => void;
@@ -233,6 +259,7 @@ class InProcessChildHandle implements DisposableChildHandle {
       ? Math.max(0, Math.floor(rawDelay))
       : DEFAULT_STALL_RETRY_DELAY_MS;
     this.onStall = opts.onStall;
+    this.onToolLoop = opts.onToolLoop;
     const rawRepeat = opts.overrunRepeatMs ?? DEFAULT_OVERRUN_REPEAT_MS;
     this.overrunRepeatMs =
       Number.isFinite(rawRepeat) && rawRepeat > 0
@@ -331,6 +358,27 @@ class InProcessChildHandle implements DisposableChildHandle {
     await this.beginGeneration(this.req.prompt, true);
   }
 
+  /**
+   * Bind an already-hosted session so resume() can send the next turn.
+   * The previous parent died; this generation is interrupted, not prompted.
+   */
+  async attachIdle(): Promise<void> {
+    this.sessionCreation = this.createSession(this.req);
+    const created =
+      await this.sessionCreation;
+    this.sessionCreation = null;
+    if (this.disposed) return;
+    this.session = created;
+    this.resolvedModel_ = created.resolvedModel;
+    this.unsubscribe = this.session.subscribe((event) => this.handleSessionEvent(event));
+    this.settle(this.generation, {
+      status: "interrupted",
+      text: this.session.getLastAssistantText() ?? "",
+      error: "parent session ended",
+      durationMs: 0,
+    });
+  }
+
   async steer(message: string): Promise<void> {
     if (this.status_ !== "running" || !this.session) {
       throw new Error(`subagent ${this.req.childId} is not running (status: ${this.status_})`);
@@ -480,11 +528,10 @@ class InProcessChildHandle implements DisposableChildHandle {
       text: this.status_ === "pending" ? "" : this.partialText(),
       durationMs: this.now() - this.startedAt,
     });
-    try {
-      await this.session?.abort();
-    } catch {
-      // abort is best-effort; the result is already settled
-    }
+    // Resume may be accepted as soon as the interrupted result is visible.
+    // Drain this abort just like a timeout/stall abort before prompting again.
+    this.abortPromise = this.session ? this.session.abort().catch(() => {}) : null;
+    await this.abortPromise;
   }
 
   dispose(): void | Promise<void> {
@@ -690,11 +737,14 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (!this.isCurrent(gen)) return;
     const failure = session?.getLastAssistantFailure?.();
     if (failure) {
+      const error = failure.errorMessage?.trim() || `Model stopped with ${failure.stopReason}`;
+      const classified = classifyModelFailure(error);
       this.settle(gen, {
         status: "failed",
         text: this.partialText(),
-        error: failure.errorMessage?.trim() || `Model stopped with ${failure.stopReason}`,
-        endReason: "model-error",
+        error,
+        endReason: classified.endReason,
+        ...(classified.retryAfter !== undefined ? { retryAfter: classified.retryAfter } : {}),
         durationMs: this.now() - this.startedAt,
       });
       return;
@@ -871,7 +921,7 @@ class InProcessChildHandle implements DisposableChildHandle {
     this.toolStartedAt = null;
   }
 
-  private handleSessionEvent(event: { type: string; role?: string; toolCallId?: string; usage?: { input: number; output: number } }): void {
+  private handleSessionEvent(event: { type: string; role?: string; toolCallId?: string; toolName?: string; args?: unknown; usage?: { input: number; output: number } }): void {
     const now = this.now();
     const active = this.status_ === "running";
     let currentToolEvent = false;
@@ -915,6 +965,7 @@ class InProcessChildHandle implements DisposableChildHandle {
       if (currentToolEvent) {
         this.toolDepth++;
         this.clearStall();
+        this.noteToolCall(event.toolName, event.args);
       }
       return;
     }
@@ -931,6 +982,22 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (this.toolDepth === 0 && !this.decisionPaused) this.armStall(this.generation);
   }
 
+  private noteToolCall(toolName: string | undefined, args: unknown): void {
+    const name = toolName ?? "";
+    const key = `${name}\0${JSON.stringify(args ?? null)}`;
+    if (this.lastToolKey === key) this.lastToolCount += 1;
+    else {
+      this.lastToolKey = key;
+      this.lastToolCount = 1;
+    }
+    if (this.lastToolCount !== 3 || !name) return;
+    try {
+      this.onToolLoop?.(this.req.childId, name, args);
+    } catch {
+      // loop observers must not break the child
+    }
+  }
+
   private release(terminal = true): void {
     const release = this.releaseSlot;
     if (terminal) this.releaseSlot = null;

package/src/subagent/tool.ts

@@ -142,6 +142,8 @@ export interface SubagentToolDeps {
   /** Selectable models for action:"models" (§4.6); absent → action errors. */
   /** Receives the watcher for turns started by agent_message send. */
   registerResumeWatch?: (watch: (childId: string) => void) => void;
+  /** Rebuild a child this session no longer holds so resume can use child_id. */
+  recoverChild?: (childId: string) => Promise<RunRecord | undefined>;
   listModels?: () => {
     provider: string;
     id: string;
@@ -228,6 +230,8 @@ function toNotificationInfo(record: RunRecord, now: number) {
       status: c.status,
       text: c.result?.text ?? "",
       error: c.result?.error,
+      ...(c.result?.endReason !== undefined ? { endReason: c.result.endReason } : {}),
+      ...(c.result?.retryAfter !== undefined ? { retryAfter: c.result.retryAfter } : {}),
       ...(c.result?.warning !== undefined ? { warning: c.result.warning } : {}),
       ...(c.prompt !== undefined ? { prompt: c.prompt } : {}),
     })),
@@ -563,11 +567,16 @@ export function createSubagentTool(
       };
     }
 
-    const record = params.run_id
+    let record = params.run_id
       ? requireRun(registry, params.run_id)
       : params.child_id
         ? resolveRunByChild(registry, params.child_id)
         : undefined;
+    if (params.child_id && !params.run_id && action === "resume" && deps.recoverChild &&
+      (!record || !registry.findChild(record.runId, params.child_id))) {
+      record =
+        await deps.recoverChild(params.child_id);
+    }
     if (!record) {
       if (params.child_id && !params.run_id) {
         throw new Error(`unknown child "${params.child_id}" (no run in this session holds it)`);

package/src/subagent/types.ts

@@ -46,7 +46,9 @@ export interface ChildResult {
   /** Non-fatal caveat, e.g. agent-definition model fell back to parent model. */
   warning?: string;
   /** Set when the model itself stopped with an error (provider failure). */
-  endReason?: "model-error";
+  endReason?: "model-error" | "rate-limit";
+  /** Seconds until a rate-limited provider may be retried, when known. */
+  retryAfter?: number;
   /**
    * Total generations run (1 + resumes + stall retries). Omitted when 1.
    * Note: a user resume() also increments this; use `stalls` to count
@@ -102,6 +104,9 @@ export interface ChildSessionEvent {
   role?: string;
   /** Pi's stable tool-call id, used to pair execution start/end events. */
   toolCallId?: string;
+  toolName?: string;
+  args?: unknown;
+  isError?: boolean;
   usage?: ChildTokenUsage;
 }
 
@@ -178,6 +183,8 @@ export type CreateSessionFn = (req: ChildRunRequest) => Promise<ChildSessionAdap
 
 export interface ChildRunner {
   start(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<ChildHandle>;
+  /** Reattach a child the daemon still hosts, without sending its first prompt. */
+  attach?(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<ChildHandle>;
 }
 
 /**

package/src/work-index.ts

@@ -11,6 +11,12 @@ export type WorkKind = "shell" | "monitor" | "agent";
 export const WORK_RETAIN_MS = 10 * 60 * 1000;
 export const WORK_FINISHED_CAP = 50;
 
+/** stderr line when print mode drops live work and still exits 0. */
+export function printModeDropWarning(ids: string[]): string | null {
+  if (ids.length === 0) return null;
+  return `pi-famulus: print mode is ending; stopping ${ids.length} background item(s) (${ids.join(", ")}). The process still exits 0.\n`;
+}
+
 export interface WorkItem {
   id: string;
   kind: WorkKind;