pi-famulus 0.1.9 → 0.2.1

package/README.md

@@ -32,7 +32,7 @@ Three things go wrong when an agent has to wait:
 - **A backgrounded command finishes silently.** With pi-famulus, the result is injected into the conversation when the command exits, so the model reacts instead of polling.
 - **A subagent reports "done" while its work still runs.** With pi-famulus, a subagent's `bash` cannot move to the background, and a subagent cannot start subagents or monitors. When it reports done, nothing it started through pi-famulus is still running, unless a command detached itself with `setsid` or left a process running with `&`.
 
-One machine-wide daemon (`pi-famulus`, written in Rust) starts every shell command and monitor, including the ones subagents run, and is their parent. If the daemon crashes or is killed, the process groups it started are stopped, except commands that moved into a new session with `setsid`. Subagents themselves run inside pi.
+One machine-wide daemon (`pi-famulus`, written in Rust) starts every shell command and monitor, including the ones subagents run, and is their parent. If the daemon crashes or is killed, the process groups it started are stopped, except commands that moved into a new session with `setsid`. Subagents themselves are `pi --mode rpc` processes owned by the daemon.
 
 pi-famulus is a pi extension, so it works wherever pi loads extensions: the pi TUI, RPC mode, and agents you build with the pi SDK. Outside the TUI there is no `/tasks` list and no fleet line, but results still wake the agent. Print mode (`pi -p`) exits when the first run ends, so results that arrive later are not seen.
 
@@ -125,7 +125,7 @@ pi-famulus starts and stops processes for you. This section states what it guara
 
 - On Unix, the daemon starts every shell and monitor task in a process group, and is its parent. When the daemon ends (`shutdown`, `kill -9`, panic), each group gets SIGTERM, then SIGKILL 2 seconds later. Windows tasks run in Job Objects and are terminated as a unit when stopped or when the daemon exits.
 - A command that moves a child into a new session (`setsid`) leaves the group and escapes this. A process left running with `&` keeps running until it exits or the daemon stops it.
-- Running work does not survive the last pi session closing. Five seconds after the last session disconnects, the daemon stops what is left and exits. Records, output and transcripts stay on disk for 24 hours.
+- Shells and monitors do not survive the last pi session closing. Five seconds after the last session disconnects, and once no hosted subagent is still warm, the daemon stops what is left and exits. A warm subagent keeps the daemon up after its parent disconnects. It parks at its retention deadline, or earlier when the warm-agent cap needs the slot. Records, output and transcripts stay on disk for 24 hours.
 - A subagent still running when its 30-minute turn budget ends is not killed, unless you set `hardTimeoutMs`. The parent is told and chooses to extend, steer or interrupt it.
 - A subagent with no activity for 5 minutes is resumed once on the same session, with its transcript kept. The timer pauses while a tool runs or a `contact_supervisor` question waits for an answer. If the subagent stalls again, it is marked failed.
 - `monitor` batches output every 200 ms. Rust-framed repeated complete lines from the same monitor are deduplicated for 60 seconds by default after a representative is delivered; legacy/raw fallback previews are not content-deduplicated, and missing metadata, capacity eviction, and omitted representatives fail open. Exact matching is the default, with timestamp normalization opt-in. Previews are bounded; original output remains readable with `task_output`. Deduplication does not count as overload loss. Admitted batches allow a burst of 10 events, then one event every 2 seconds. Batches over that limit are dropped. If at least half the batches are dropped over a 30-second window that holds at least 10 batches, the monitor stops and you are told.
@@ -134,10 +134,10 @@ pi-famulus starts and stops processes for you. This section states what it guara
 ## FAQ
 
 - **How is pi-famulus different from `pi-subagents` or `pi-background-tasks`?** They are alternatives, so choose one. Choose [`pi-subagents`](https://github.com/nicobailon/pi-subagents) for ready-made roles, saved workflows, `/council`, or background subagents in a detached process. Choose [`pi-background-tasks`](https://github.com/ismailsaleekh/pi-background-tasks) for named background shell jobs with output files, a read-only delegated agent, or its Fusion workflows. Choose pi-famulus for one daemon that owns every shell and monitor process across your pi sessions, a shared cap on concurrent subagents, and a CLI for inspecting past runs.
-- **Can I attach to a subagent like a tmux pane?** No. Subagents run inside the agent's process, so you cannot attach to one or take over its session. Steer, resume or interrupt it through the parent, answer its questions with `/reply`, and read what it did with `pi-famulus agent <id> -f`, `show <id>` and `top`.
+- **Can I attach to a subagent like a tmux pane?** Yes. Each subagent is a `pi --mode rpc` process with a pi session id. `/attach <id>` in the pi TUI, or `pi-famulus attach <child id>` from a terminal, talks to that process. Opening a warm hosted session in the pi TUI asks you to attach, take over, or cancel. Without a UI that open is refused. A parked child is not refused: interactive pi can open its session file.
 - **Does it work outside the pi TUI?** Yes. It loads wherever pi loads extensions, including RPC mode (`pi --mode rpc`) and agents built with the pi SDK. Print mode (`pi -p`) loads it too, but exits when the first run ends, so later results are not seen. In an SDK agent, load it through `DefaultResourceLoader` (for example with `additionalExtensionPaths`) and call `session.bindExtensions()`. The real-model eval drives pi in RPC mode.
 - **Can a subagent start its own subagents?** No. Nesting is limited to one level.
-- **What happens to background tasks when pi exits?** Five seconds after the last pi session closes, the daemon stops whatever is still running and exits. Read the records afterwards with `pi-famulus show <id>`.
+- **What happens to background tasks when pi exits?** Five seconds after the last pi session closes, and once no hosted subagent is still warm, the daemon stops whatever is still running and exits. Read the records afterwards with `pi-famulus show <id>`.
 - **Does `/reload` stop running work?** No. Shells, monitors and subagents keep running, and their results still arrive. If the reload loads a different pi-famulus version, the old version's work is stopped first.
 - **Which binary and versions am I running?** Type `/famulus`. It shows the `pi-famulus` binary path and its version, the running manager's version and pid, and the extension version.
 - **Why does my pi bash command hang on long builds?** With pi-famulus, `bash` stops waiting after 20 seconds and moves the command to the background, so the turn continues. To change the limit, set `foregroundBudgetMs` in `~/.pi/agent/pi-famulus/config.json` ([configuration](https://github.com/Leechael/pi-famulus/blob/main/docs/configuration.md)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.9",
+  "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.1.9",
-    "pi-famulus-linux-arm64": "0.1.9",
-    "pi-famulus-darwin-x64": "0.1.9",
-    "pi-famulus-darwin-arm64": "0.1.9",
-    "pi-famulus-win-x64": "0.1.9",
-    "pi-famulus-win-arm64": "0.1.9"
+    "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/child-mode.ts

@@ -0,0 +1,214 @@
+/**
+ * pi-famulus inside a hosted subagent (`PI_FAMULUS_CHILD_ID`).
+ * Registers only the child tools and reports prompt-cache expiry. A second
+ * copy of the extension in the same process (installed package plus `-e`)
+ * returns immediately.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
+import { CHILD_BEHAVIOR_GUIDELINES } from "./behavior-guidelines";
+import { createChildBashTool } from "./subagent/child-bash";
+import { ChildShellTracker } from "./subagent/overrun";
+import { createContactSupervisorTool, createAgentMessageTool } from "./comms/tools";
+import { createComms } from "./comms/comms";
+import type { ChildHandle, ChildStatus, CommsHost } from "./comms/types";
+import { getFamulusHome, loadConfig, resolveManagerPath } from "./config";
+import { ManagerClient } from "./manager-client";
+import { realClock } from "./clock";
+
+const MARKER = Symbol.for("pi-famulus.child-mode");
+
+export function isHostedChildProcess(): boolean {
+  return Boolean(process.env.PI_FAMULUS_CHILD_ID && process.env.PI_FAMULUS_CHILD_TOKEN);
+}
+
+export function registerChildMode(pi: ExtensionAPI): void {
+  const globalState = globalThis as typeof globalThis & { [MARKER]?: boolean };
+  if (globalState[MARKER]) return;
+  globalState[MARKER] = true;
+  const childId = process.env.PI_FAMULUS_CHILD_ID ?? "";
+  const token = process.env.PI_FAMULUS_CHILD_TOKEN ?? "";
+  const runId = process.env.PI_FAMULUS_CHILD_RUN ?? "run_hosted";
+  const home = process.env.PI_FAMULUS_HOME || getFamulusHome();
+  const config = loadConfig(home);
+  const managerPath = resolveManagerPath(config, home);
+  let client: ManagerClient | null = null;
+  let ctx: ExtensionContext | null = null;
+  let stopWarming = false;
+  const shells = new ChildShellTracker();
+  const allow = process.env.PI_FAMULUS_CHILD_TOOLS?.split(",").filter(Boolean);
+  const bashAllowed = !allow || allow.includes("bash");
+
+  interface Peer {
+    childId: string;
+    name: string;
+    runId: string;
+    activity: string;
+  }
+  const peers: Peer[] = [];
+
+  const peerStatus = (peer: Peer): ChildStatus => {
+    if (peer.activity === "running" || peer.activity === "starting") return "running";
+    if (peer.activity === "failed") return "failed";
+    return "completed";
+  };
+
+  const handleFor = (peer: Peer): ChildHandle => ({
+    childId: peer.childId,
+    result: Promise.resolve({ status: "completed", text: "", durationMs: 0 }),
+    steer: async (message: string) => { await client?.agentInput(peer.childId, "prompt_steer", message, childId); },
+    followUp: async (message: string) => { await client?.agentInput(peer.childId, "prompt_follow", message, childId); },
+    resume: async (message: string) => { await client?.agentInput(peer.childId, "prompt", message, childId); },
+    interrupt: async () => { await client?.agentInput(peer.childId, "abort", "", childId); },
+    status: () => peerStatus(peer),
+    lastEventAt: () => Date.now(),
+  });
+
+  const host: CommsHost = {
+    getChild(id) {
+      const peer = peers.find((item) => item.childId === id);
+      if (!peer) return undefined;
+      return { handle: handleFor(peer), runId: peer.runId, name: peer.name, status: peerStatus(peer) };
+    },
+    listChildren() {
+      return peers.map((peer) => ({ childId: peer.childId, runId: peer.runId, name: peer.name, status: peerStatus(peer) }));
+    },
+    sameRun: () => true,
+    notifySupervisor: () => {},
+    resumeChild: async (id, message) => {
+      if (!client) throw new Error("pi-famulus daemon is not connected");
+      client.requireHostedProtocol();
+      // A live signal disables the 30s acquire timer, so a queued permit can wait.
+      const admissionSignal = new AbortController().signal;
+      let queuedBehind: number | null = null;
+      for (;;) {
+        let admission: { granted: boolean; queuedBehind?: number };
+        try {
+          admission = await client.acquireAgent(id, "other", admissionSignal);
+        } catch (err) {
+          const messageText = err instanceof Error ? err.message : String(err);
+          if (messageText.includes("timed out")) {
+            queuedBehind = queuedBehind ?? 0;
+            continue;
+          }
+          throw err;
+        }
+        if (admission.granted) {
+          if (admission.queuedBehind != null) queuedBehind = admission.queuedBehind;
+          break;
+        }
+        queuedBehind = queuedBehind ?? 0;
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+      try {
+        await client.agentInput(id, "prompt", message, childId);
+      } catch (err) {
+        await client.releaseAgent(id).catch(() => {});
+        throw err;
+      }
+      return { queuedBehind };
+    },
+  };
+
+  const refreshPeers = async () => {
+    if (!client?.isAvailable()) return;
+    const listed = await client.agentPeers().catch(() => null);
+    if (!listed) return;
+    peers.splice(0, peers.length, ...listed.map((peer) => ({
+      childId: peer.childId,
+      name: peer.name,
+      runId: peer.runId,
+      activity: peer.activity,
+    })));
+  };
+
+  const comms = createComms(host);
+
+  pi.registerTool({
+    ...createContactSupervisorTool({
+      ...comms,
+      contactSupervisor: async (_from: string, reason: "need_decision" | "progress_update", message: string) => {
+        if (!client) throw new Error("pi-famulus daemon is not connected");
+        return client.agentComms(randomUUID(), reason, message);
+      },
+    } as never, childId),
+    promptGuidelines: [CHILD_BEHAVIOR_GUIDELINES],
+  });
+
+  const messageTool = createAgentMessageTool(comms, { kind: "child", childId, runId }, host, realClock);
+  pi.registerTool({
+    ...messageTool,
+    execute: async (toolCallId, params, signal, onUpdate, toolCtx) => {
+      await refreshPeers();
+      return messageTool.execute(toolCallId, params, signal, onUpdate, toolCtx);
+    },
+  });
+
+  if (bashAllowed) {
+    pi.registerTool(createChildBashTool({
+      getClient: () => client,
+      home,
+      sessionId: () => ctx?.sessionManager.getSessionId() ?? childId,
+      sessionEnv: (): Record<string, string> => {
+        const current = ctx;
+        if (!current) return {};
+        return {
+          PI_SESSION_ID: current.sessionManager.getSessionId(),
+          PI_SESSION_FILE: current.sessionManager.getSessionFile?.() ?? "",
+          PI_PROVIDER: current.model?.provider ?? "",
+          PI_MODEL: current.model?.id ?? "",
+          PI_REASONING_LEVEL: current.thinkingLevel ?? "",
+        };
+      },
+      trackTask: () => {},
+      childId,
+      runId,
+      clock: realClock,
+      shells,
+    }));
+  }
+
+  pi.on("session_start", async (_event, startCtx) => {
+    ctx = startCtx;
+    client = new ManagerClient({
+      home,
+      sessionId: startCtx.sessionManager.getSessionId(),
+      managerPath,
+      piPid: process.pid,
+      cwd: startCtx.cwd,
+      role: "child",
+      childId,
+      token,
+      sessionFile: startCtx.sessionManager.getSessionFile?.(),
+    });
+    await client.connect().catch(() => {});
+    client.onEvent((event) => {
+      const hosted = event as { event?: string; residency?: string };
+      if (hosted.event === "agent_state" && hosted.residency === "parked") stopWarming = true;
+    });
+  });
+
+  pi.on("message_end", async (event) => {
+    if (!client?.isAvailable()) return;
+    const message = (event as { message?: { role?: string; usage?: { cacheWrite1h?: number } } }).message;
+    if (message?.role !== "assistant") return;
+    const model = ctx?.model as { promptCache?: { short?: number; long?: number } } | undefined;
+    const long = process.env.PI_CACHE_RETENTION === "long" || (message.usage?.cacheWrite1h ?? 0) > 0;
+    const seconds = long ? model?.promptCache?.long : model?.promptCache?.short;
+    if (!seconds || seconds <= 0) {
+      await client.agentCache(null, null, null).catch(() => {});
+      return;
+    }
+    await client.agentCache(Date.now() + seconds * 1000, long ? "long" : "short", seconds * 1000).catch(() => {});
+  });
+
+  pi.on("cache_warming_decision", () => {
+    if (stopWarming) return { action: "stop" as const };
+    return undefined;
+  });
+
+  pi.on("session_shutdown", async () => {
+    await client?.close();
+    client = null;
+  });
+}

package/src/comms/comms.ts

@@ -56,7 +56,7 @@ export interface CommsWithOrigin extends Comms {
     message: string,
     delivery: "steer" | "queue",
     from?: string,
-  ): Promise<void>;
+  ): Promise<"running" | "resumed" | "queued">;
   /** Cancel pending decision waiters and timers (session shutdown). */
   dispose(): void;
 }
@@ -129,7 +129,7 @@ export function createComms(host: CommsHost, options: CommsOptions = {}): CommsW
       options.logEvent?.("decision.reply", { child_id: toChildId });
     },
 
-    async send(toChildId, message, delivery, from = "supervisor") {
+    async send(toChildId, message, delivery, from = "supervisor"): Promise<"running" | "resumed" | "queued"> {
       const child = host.getChild(toChildId);
       if (!child) {
         const known =
@@ -142,28 +142,33 @@ export function createComms(host: CommsHost, options: CommsOptions = {}): CommsW
         } else {
           await child.handle.followUp(message);
         }
+        mailbox.append(child.runId, { from, to: toChildId, kind: "send", message });
+        return "running";
       } else if (
         child.status === "completed" ||
         child.status === "failed" ||
         child.status === "interrupted"
       ) {
-        // Lifecycle (resume) belongs to the subagent tool. Resuming here never
-        // wired a completion wake, so the parent hung.
-        throw new Error(
-          fill("tools.agent_message.error.finished-child", {
-            childId: toChildId,
-            name: child.name,
-            status: child.status,
-            runId: child.runId,
-          }),
-        );
+        const resume = host.resumeChild;
+        if (!resume) {
+          throw new Error(
+            fill("tools.agent_message.error.finished-child", {
+              childId: toChildId,
+              name: child.name,
+              status: child.status,
+              runId: child.runId,
+            }),
+          );
+        }
+        const { queuedBehind } = await resume(child.handle.childId, message);
+        mailbox.append(child.runId, { from, to: toChildId, kind: "send", message });
+        return queuedBehind === null ? "resumed" : "queued";
       } else {
         throw new Error(
           `Child ${toChildId} (${child.name}) is ${child.status}; ` +
             "messages can only be delivered to running or finished children.",
         );
       }
-      mailbox.append(child.runId, { from, to: toChildId, kind: "send", message });
     },
 
     async broadcast(runId, message, fromChildId) {

package/src/comms/registry-host.ts

@@ -16,6 +16,8 @@ export interface RegistryHostDeps {
   getNotifyCenter: () => {
     notify(msg: { customType: string; content: string; details?: unknown }): void;
   } | null;
+  /** The subagent tool registers this so a send-to-idle turn wakes the parent. */
+  onResumeAccepted?: (childId: string) => void;
 }
 
 
@@ -69,5 +71,13 @@ export function createRegistryCommsHost(deps: RegistryHostDeps): CommsHost {
         details: wake.details,
       });
     },
+
+    async resumeChild(childId: string, message: string) {
+      const registry = deps.getRegistry();
+      if (!registry) throw new Error("subagent system is not initialized");
+      const accepted = await registry.resumeChild(childId, message);
+      deps.onResumeAccepted?.(childId);
+      return accepted;
+    },
   };
 }

package/src/comms/tools.ts

@@ -295,8 +295,9 @@ export function createAgentMessageTool(
 
       // send
       const delivery = params.delivery ?? "steer";
+      let delivered: "running" | "resumed" | "queued";
       try {
-        await comms.send(target.childId, message, delivery, from);
+        delivered = await comms.send(target.childId, message, delivery, from);
       } catch (err) {
         return errorResult("send", err instanceof Error ? err.message : String(err), {
           to: target.childId,
@@ -304,7 +305,13 @@ export function createAgentMessageTool(
         });
       }
       const how =
-        delivery === "steer" ? "steered into the running child" : "queued for the running child";
+        delivered === "queued"
+          ? "accepted a new turn on the idle child; it is waiting for a machine slot"
+          : delivered === "resumed"
+            ? "started a new turn on the idle child"
+            : delivery === "steer"
+              ? "steered into the running child"
+              : "queued for the running child";
       return okResult("send", `Message to ${target.childId} (${target.name}) ${how}.`, {
         to: target.childId,
         delivery,

package/src/comms/types.ts

@@ -1,8 +1,9 @@
 /**
  * comms types (design doc appendix B, M4).
  *
- * `ChildStatus` / `ChildResult` / `ChildHandle` are structural re-declarations
- * of the appendix B contract. They are intentionally NOT imported from
+ * `ChildStatus` / `ChildResult` / `ChildHandle` follow the appendix B shapes.
+ * `send` returns `"running" | "resumed" | "queued"`; appendix B originally said `Promise<void>`.
+ * These shapes are intentionally NOT imported from
  * `../subagent/types` (M3 is developed in parallel and may not exist yet);
  * any value satisfying these shapes is accepted.
  */
@@ -43,6 +44,10 @@ export interface CommsHost {
   listChildren(): { childId: string; runId: string; name: string; status: ChildStatus }[];
   sameRun(childIdA: string, childIdB: string): boolean;
   notifySupervisor(wake: { content: string; details: FamulusWake }): void;
+  /** Continue an idle child. Absent on test hosts that still reject send-to-finished. `queuedBehind` is null when a slot was free. */
+  resumeChild?(childId: string, message: string): Promise<{ queuedBehind: number | null }>;
+  /** Fired after resumeChild accepts a turn, so the parent can be woken when it settles. */
+  onResumeAccepted?(childId: string): void;
 }
 
 export interface MailboxEntry {
@@ -61,7 +66,8 @@ export interface Comms {
     message: string,
   ): Promise<string>; // need_decision → reply text; progress_update → immediate "ok"
   reply(toChildId: string, message: string): void; // no pending waiter → throw
-  send(toChildId: string, message: string, delivery: "steer" | "queue"): Promise<void>;
+  // "running" steered or queued into a live child; "resumed" an idle child started a turn; "queued" the turn is waiting for a machine slot.
+  send(toChildId: string, message: string, delivery: "steer" | "queue"): Promise<"running" | "resumed" | "queued">;
   broadcast(runId: string, message: string, fromChildId?: string): Promise<string[]>; // delivered childIds
   pendingRequests(): { childId: string; name: string; message: string; sinceMs: number }[];
   log(runId: string, limit?: number): MailboxEntry[]; // default 20, ring 200/run

package/src/config.ts

@@ -48,6 +48,8 @@ export interface FamulusSubagentConfig {
   maxConcurrentChildren?: number;
   /** Max child sessions spawned per hour. */
   spawnBudgetPerHour?: number;
+  /** pi command for hosted subagents: a path, or a JSON argv array. */
+  piCommand?: string;
 }
 
 /** Subagent settings with every field resolved (design doc §4.6 defaults). */
@@ -64,6 +66,7 @@ export interface ResolvedSubagentConfig {
   concurrency: number;
   maxConcurrentChildren: number;
   spawnBudgetPerHour: number;
+  piCommand: string | null;
 }
 
 /**
@@ -88,6 +91,7 @@ export const DEFAULT_SUBAGENT_CONFIG: ResolvedSubagentConfig = {
   concurrency: 4,
   maxConcurrentChildren: 8,
   spawnBudgetPerHour: 32,
+  piCommand: null,
 };
 
 /** Merge defaults <- top-level subagentBudgetMs <- subagent section. */
@@ -124,6 +128,9 @@ export function resolveSubagentConfig(config: FamulusConfig): ResolvedSubagentCo
   if (typeof section.spawnBudgetPerHour === "number" && section.spawnBudgetPerHour >= 1) {
     resolved.spawnBudgetPerHour = Math.floor(section.spawnBudgetPerHour);
   }
+  if (typeof section.piCommand === "string" && section.piCommand.trim()) {
+    resolved.piCommand = section.piCommand.trim();
+  }
   return resolved;
 }
 
@@ -252,6 +259,15 @@ export function loadConfig(home: string = getFamulusHome()): FamulusConfig {
     if (typeof section.spawnBudgetPerHour === "number" && section.spawnBudgetPerHour >= 1) {
       subagent.spawnBudgetPerHour = section.spawnBudgetPerHour;
     }
+    if (Array.isArray(section.piCommand) && section.piCommand.length > 0 && section.piCommand.every((part) => typeof part === "string" && part.length > 0)) {
+      subagent.piCommand = JSON.stringify(section.piCommand);
+    } else if (typeof section.piCommand === "string" && section.piCommand.trim()) {
+      subagent.piCommand = section.piCommand.trim();
+    } else if ("piCommand" in section) {
+      // Present but not a usable command. An empty argv makes spawn fail
+      // instead of quietly using whichever pi is running this session.
+      subagent.piCommand = "[]";
+    }
     config.subagent = subagent;
   }
   return config;

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 } : {}),
     })),
   });