pi-famulus 0.1.8 → 0.2.0

package/src/native-manager.js

@@ -1,5 +1,9 @@
-import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { accessSync, closeSync, constants, mkdirSync, openSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getSystemErrorMap } from "node:util";
 
 // Filesystem failures mean this optional package is unusable, regardless of the syscall code.
@@ -11,8 +15,10 @@ const resolutionErrorCodes = new Set([
   "ERR_INVALID_MODULE_SPECIFIER", "ERR_UNSUPPORTED_RESOLVE_REQUEST",
 ]);
 
+const modulePath = fileURLToPath(import.meta.url);
 const packageVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const resolveInstalled = createRequire(import.meta.url).resolve;
+const RESTORE_HINT = "not installed; run `npm install --include=optional pi-famulus`";
 
 /** The native optional packages are selected by npm's os/cpu constraints. */
 export function nativePackageName(platform, arch) {
@@ -23,20 +29,263 @@ export function nativePackageName(platform, arch) {
   return `pi-famulus-${packageOs}-${arch}`;
 }
 
+/**
+ * Cache for the exact platform package. `pi update --extensions` reinstalls
+ * with npm, and `omit=optional` (user or project npmrc) deletes optional
+ * dependencies during that install. The cache is outside the famulus runtime
+ * home and outside pi's package tree, so the next update does not remove it.
+ */
+export function nativeCacheDir({
+  version = packageVersion,
+  platform = process.platform,
+  arch = process.arch,
+  env = process.env,
+  home = homedir(),
+} = {}) {
+  const base = platform === "win32"
+    ? join(env.LOCALAPPDATA || join(home, "AppData", "Local"), "pi-famulus", "native")
+    : join(env.XDG_CACHE_HOME || join(home, ".cache"), "pi-famulus", "native");
+  return join(base, version, `${platform}-${arch}`);
+}
+
+function isIgnoredResolveError(error) {
+  return error instanceof SyntaxError || systemErrorCodes.has(error?.code) || resolutionErrorCodes.has(error?.code);
+}
+
+function executableFile(path) {
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile() || stat.size <= 0) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch (error) {
+    if (isIgnoredResolveError(error)) return false;
+    throw error;
+  }
+}
+
+/** Usable exact-version binary inside one package directory, or null. */
+function binaryInPackage(dir, name) {
+  let metadata;
+  try {
+    metadata = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  } catch (error) {
+    if (isIgnoredResolveError(error)) return null;
+    throw error;
+  }
+  if (!metadata || metadata.name !== name || metadata.version !== packageVersion) return null;
+  const exported = metadata.exports?.["./bin/pi-famulus"];
+  const rel = typeof exported === "string" ? exported : metadata.main;
+  if (typeof rel !== "string" || !rel.startsWith("./") || rel.split("/").includes("..")) return null;
+  const binary = join(dir, rel);
+  const root = dir.endsWith(sep) ? dir : dir + sep;
+  if (!binary.startsWith(root)) return null;
+  return executableFile(binary) ? binary : null;
+}
+
+function walkNodeModules(startFile, stopAt) {
+  const dirs = [];
+  let dir = dirname(startFile);
+  const seen = new Set();
+  const boundary = stopAt ? resolve(stopAt) : null;
+  while (!seen.has(dir)) {
+    seen.add(dir);
+    dirs.push(join(dir, "node_modules"));
+    if (boundary && (dir === boundary || !dir.startsWith(boundary.endsWith(sep) ? boundary : boundary + sep))) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return dirs;
+}
+
+function legacyResolve(name, resolve) {
+  const metadata = JSON.parse(readFileSync(resolve(`${name}/package.json`), "utf8"));
+  if (!metadata || metadata.name !== name || metadata.version !== packageVersion) return null;
+  const binary = resolve(`${name}/bin/pi-famulus`);
+  const stat = statSync(binary);
+  if (!stat.isFile() || stat.size <= 0) return null;
+  accessSync(binary, constants.X_OK);
+  return binary;
+}
+
+function searchNative({ platform = process.platform, arch = process.arch, from, stopAt, cacheDir } = {}) {
+  const name = nativePackageName(platform, arch);
+  if (!name) return { name: null, path: null, detail: `unsupported ${platform}/${arch}` };
+  let start = from ?? modulePath;
+  if (!from) {
+    try { start = realpathSync(modulePath); } catch { /* keep the URL path */ }
+  }
+  const seen = new Set();
+  for (const nodeModules of walkNodeModules(start, stopAt)) {
+    const dir = join(nodeModules, name);
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    const binary = binaryInPackage(dir, name);
+    if (binary) return { name, path: binary, detail: "" };
+  }
+  // NODE_PATH and other resolver roots. An explicit `from` is a hermetic walk.
+  if (!from) {
+    try {
+      const resolved = dirname(resolveInstalled(`${name}/package.json`));
+      if (!seen.has(resolved)) {
+        const binary = binaryInPackage(resolved, name);
+        if (binary) return { name, path: binary, detail: "" };
+      }
+    } catch (error) {
+      if (!isIgnoredResolveError(error)) throw error;
+    }
+  }
+  if (cacheDir !== false) {
+    const dir = join(cacheDir ?? nativeCacheDir({ platform, arch }), "node_modules", name);
+    const binary = binaryInPackage(dir, name);
+    if (binary) return { name, path: binary, detail: "" };
+  }
+  return { name, path: null, detail: RESTORE_HINT };
+}
+
 /** Resolve the exact-version optional package without loading native executable bytes. */
-export function resolveNativeManagerPath({ platform = process.platform, arch = process.arch, resolve = resolveInstalled } = {}) {
+export function resolveNativeManagerPath({ platform = process.platform, arch = process.arch, resolve, from, stopAt, cacheDir } = {}) {
   const name = nativePackageName(platform, arch);
   if (!name) return null;
+  // Injected resolvers stay hermetic: tests use them to simulate one install tree.
+  if (resolve) {
+    try {
+      return legacyResolve(name, resolve);
+    } catch (error) {
+      if (isIgnoredResolveError(error)) return null;
+      throw error;
+    }
+  }
+  return searchNative({ platform, arch, from, stopAt, cacheDir }).path;
+}
+
+/** `npm <package> <path>` or why that exact platform package was not usable. */
+export function describeNativeLookup(options) {
+  const name = nativePackageName(options?.platform ?? process.platform, options?.arch ?? process.arch);
+  if (!name) return `npm native manager (unsupported ${options?.platform ?? process.platform}/${options?.arch ?? process.arch})`;
+  if (options?.resolve) {
+    const path = resolveNativeManagerPath(options);
+    return path ? `npm ${name} ${path}` : `npm ${name} (missing or unusable, ignored)`;
+  }
+  const found = searchNative(options);
+  return found.path ? `npm ${name} ${found.path}` : `npm ${name} (${found.detail})`;
+}
+
+function pidAlive(pid) {
   try {
-    const metadata = JSON.parse(readFileSync(resolve(`${name}/package.json`), "utf8"));
-    if (!metadata || metadata.name !== name || metadata.version !== packageVersion) return null;
-    const binary = resolve(`${name}/bin/pi-famulus`);
-    const stat = statSync(binary);
-    if (!stat.isFile() || stat.size <= 0) return null;
-    accessSync(binary, constants.X_OK);
-    return binary;
+    process.kill(pid, 0);
+    return true;
   } catch (error) {
-    if (error instanceof SyntaxError || systemErrorCodes.has(error?.code) || resolutionErrorCodes.has(error?.code)) return null;
-    throw error;
+    return error?.code === "EPERM";
+  }
+}
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** A lock left by a dead process, or held far longer than one npm install, can be replaced. */
+function installLockIsStale(lockPath) {
+  try {
+    const age = Date.now() - statSync(lockPath).mtimeMs;
+    const pid = Number(readFileSync(lockPath, "utf8").trim());
+    if (Number.isInteger(pid) && pid > 0) return !pidAlive(pid) || age > 150_000;
+    return age > 5_000;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * One npm install per cache directory. Another startup either waits until that
+ * install publishes a binary or takes over a stale lock. Returns the open lock,
+ * or null when waiting itself produced a usable binary.
+ */
+function acquireInstallLock(dir, lookup) {
+  mkdirSync(dir, { recursive: true });
+  const lockPath = `${dir}.install.lock`;
+  const deadline = Date.now() + 130_000;
+  while (Date.now() <= deadline) {
+    try {
+      const fd = openSync(lockPath, "wx");
+      try { writeSync(fd, String(process.pid)); } catch { /* the fd is still the lock */ }
+      return { fd, lockPath };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const ready = resolveNativeManagerPath(lookup);
+      if (ready) return null;
+      if (installLockIsStale(lockPath)) {
+        rmSync(lockPath, { force: true });
+        continue;
+      }
+      sleepMs(200);
+    }
+  }
+  return null;
+}
+
+function releaseInstallLock(lock) {
+  if (!lock) return;
+  try { closeSync(lock.fd); } catch { /* already closed */ }
+  rmSync(lock.lockPath, { force: true });
+}
+
+/**
+ * Install the exact platform package into the versioned cache when the
+ * optional dependency is missing. No-ops when a usable binary is already
+ * resolvable. `PI_FAMULUS_NO_NATIVE_FETCH=1`, `PI_OFFLINE=1`, and Vitest skip
+ * the install. Directory, manifest, and npm failures return null so startup
+ * degrades instead of throwing.
+ */
+export function ensureNativeManagerInstalled({
+  platform = process.platform,
+  arch = process.arch,
+  cacheDir,
+  env = process.env,
+  npmCommand,
+  spawn = spawnSync,
+  from,
+  stopAt,
+} = {}) {
+  const lookup = { platform, arch, cacheDir, from, stopAt };
+  try {
+    const existing = resolveNativeManagerPath(lookup);
+    if (existing) return existing;
+    if (!nativePackageName(platform, arch)) return null;
+    if (env.PI_FAMULUS_NO_NATIVE_FETCH === "1" || env.PI_OFFLINE === "1" || env.VITEST) return null;
+    if (cacheDir === false) return null;
+    const dir = cacheDir ?? nativeCacheDir({ platform, arch, env });
+    const lockedLookup = { ...lookup, cacheDir: dir };
+    const lock = acquireInstallLock(dir, lockedLookup);
+    if (!lock) return resolveNativeManagerPath(lockedLookup);
+    try {
+      const manifest = join(dir, "package.json");
+      try {
+        readFileSync(manifest);
+      } catch {
+        writeFileSync(manifest, `${JSON.stringify({ private: true, name: "pi-famulus-native-cache", version: "0.0.0" })}\n`);
+      }
+      const command = npmCommand ?? (platform === "win32" ? "npm.cmd" : "npm");
+      const name = nativePackageName(platform, arch);
+      let result;
+      try {
+        result = spawn(command, [
+          "install", `${name}@${packageVersion}`,
+          "--prefix", dir,
+          "--ignore-scripts", "--no-fund", "--no-audit", "--loglevel=error",
+        ], { timeout: 120_000, windowsHide: true, encoding: "utf8" });
+      } catch {
+        return resolveNativeManagerPath(lockedLookup);
+      }
+      const found = resolveNativeManagerPath(lockedLookup);
+      if (found) return found;
+      if (!result || result.error || result.status !== 0) return null;
+      return null;
+    } finally {
+      releaseInstallLock(lock);
+    }
+  } catch {
+    return null;
   }
 }

package/src/pi-command.ts

@@ -0,0 +1,123 @@
+/**
+ * Find the pi command a hosted subagent should be. The daemon never searches
+ * PATH; the extension resolves it where pi is already running.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename } from "node:path";
+export type PiCommand = { argv: string[] } | { error: string };
+
+export function resolvePiArgv(configured?: string | null, argv: readonly string[] = process.argv): PiCommand {
+  const raw = (configured && configured.trim()) || process.env.PI_FAMULUS_PI?.trim() || "";
+  if (raw) {
+    if (raw.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(raw) as unknown;
+        if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((part) => typeof part === "string" && part.length > 0)) {
+          return { argv: parsed as string[] };
+        }
+      } catch {
+        return { error: `PI_FAMULUS_PI / subagent.piCommand is not a JSON argv array: ${raw}` };
+      }
+      return { error: `PI_FAMULUS_PI / subagent.piCommand is not a JSON argv array: ${raw}` };
+    }
+    return { argv: raw.includes(" ") ? splitCommand(raw) : [raw] };
+  }
+  const fromProcess = runningPiArgv(argv);
+  if (fromProcess) return { argv: fromProcess };
+  const exec = process.execPath;
+  try {
+    const req = createRequire(import.meta.url);
+    const pkg = req.resolve("@earendil-works/pi-coding-agent/package.json");
+    const cli = pkg.replace(/package\.json$/, "dist/cli.js");
+    if (existsSync(cli)) return { argv: [exec, cli] };
+  } catch {
+    // The host did not load pi as a resolvable package.
+  }
+  return {
+    error:
+      "cannot find the pi executable that is running this session. Set subagent.piCommand in config.json or PI_FAMULUS_PI to the pi command.",
+  };
+}
+
+const PARENT_FLAGS = new Set([
+  "-ne",
+  "--no-extensions",
+  "-ns",
+  "--no-skills",
+  "-np",
+  "--no-prompt-templates",
+  "-nc",
+  "--no-context-files",
+  "--offline",
+  "--no-mcp",
+]);
+
+/**
+ * Flags from the pi process that is spawning the subagent. The child is a new
+ * process, so it only sees providers and tools that its own command line loads.
+ * Eval and SDK hosts pass those as `-e` on argv (`-ne` plus an explicit faux
+ * provider extension); forwarding them is what lets the child use the same model.
+ */
+export function parentResourceArgs(argv: readonly string[] = process.argv.slice(2)): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-e" || arg === "--extension") {
+      const value = argv[i + 1];
+      if (value && !value.startsWith("-")) {
+        out.push("-e", value);
+        i++;
+      }
+      continue;
+    }
+    if (PARENT_FLAGS.has(arg)) out.push(arg);
+  }
+  return out;
+}
+
+/**
+ * The pi process that loaded this extension. `node_modules/.bin/pi` is a
+ * symlink (eval and `npm exec`); its path does not contain `pi-coding-agent`,
+ * so matching only that substring misses the process that is actually running.
+ */
+function runningPiArgv(argv: readonly string[]): string[] | null {
+  const entry = argv[1] ?? "";
+  if (!entry || !existsSync(entry)) return null;
+  let real = entry;
+  try {
+    real = realpathSync(entry);
+  } catch {
+    // A broken symlink still has a path; keep the original.
+  }
+  const base = basename(entry).toLowerCase();
+  const namedPi = base === "pi" || base === "pi.cmd" || base === "pi.exe" || entry.includes("pi-coding-agent") || real.includes("pi-coding-agent");
+  if (!namedPi) return null;
+  if (/\.[cm]?js$/i.test(real)) return [process.execPath, real];
+  return [entry];
+}
+
+function splitCommand(raw: string): string[] {
+  const parts: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  for (const ch of raw) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === " ") {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current) parts.push(current);
+  return parts;
+}

package/src/prompts.generated.ts

@@ -5,16 +5,16 @@ export const PROMPTS = {
   "agents.explorer.system-prompt": "You are an explorer agent. Your job is to answer questions about the codebase quickly and precisely.\n\nRules:\n- Return findings, never change code. You are strictly read-only: do not edit, write, or create files.\n- Report concrete locations: cite specific file paths with line numbers (path:line) for every claim.\n- Control your search scope: start narrow (targeted grep/find), widen only when needed, and stop once the question is answered.\n- Prefer a short, factual summary over exhaustive dumps. List what you found and where.",
   "agents.worker.description": "General-purpose executor — completes concrete coding tasks end to end",
   "agents.worker.system-prompt": "You are a worker agent. Your job is to complete the concrete task you were given, end to end.\n\nRules:\n- Do the task, don't just describe it. Make the actual edits and run the actual commands.\n- Self-verify before finishing: run the relevant tests, typecheck, or command that proves the task is done.\n- Stay within the task's scope; do not refactor unrelated code.\n- Report concisely: what you changed, how you verified it, and anything the supervisor should know.",
-  "guidelines.parent": "## Background tasks and notifications (pi-famulus)\n\n- Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind=\"task\"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands.\n- When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. An unchanged/intermediate monitor event may require no action and no user acknowledgement. Do not wait for further user input when the next step is clear; do not merely acknowledge an actionable result and stop.\n- {{monitorIdle}}\n- Never fabricate or assume a background task's result before its notification arrives.\n- Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue.\n- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.\n- Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:\"resume\"}). Supervisor wakes are not user messages — still act on them.",
+  "guidelines.parent": "## Background tasks and notifications (pi-famulus)\n\n- Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind=\"task\"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands.\n- When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. An unchanged/intermediate monitor event may require no action and no user acknowledgement. Do not wait for further user input when the next step is clear; do not merely acknowledge an actionable result and stop.\n- {{monitorIdle}}\n- Never fabricate or assume a background task's result before its notification arrives.\n- Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue.\n- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.\n- Use agent_message to steer a running subagent or to continue an idle one (send starts a new turn), and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). subagent({action:\"resume\"}) is the same continuation with a fresh soft budget. Supervisor wakes are not user messages — still act on them.",
   "guidelines.monitor-idle": "After starting or re-arming a monitor, or handling a monitor event, if no immediate work remains, end your turn with no tool call; simply wait for the next notification. Handling an event does not require a user-visible reply. Do not repeat unchanged/intermediate status or narrate your decision to stay quiet; notify the user when their requested condition is met, their input is needed, or a failure prevents further progress. Read original output with task_output only when details are needed (including paging a truncated preview), never to poll or wait. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield.",
   "guidelines.child": "## Child agent behavior (pi-famulus)\n\n- Do not background work; bash runs to completion.\n- When blocked, use contact_supervisor with need_decision; use progress_update for status.\n- Use agent_message only to communicate with siblings in this same run.\n- Your final message is your result.",
-  "tools.agent_message.description": "Message your subagents. \"send\" steers or queues a running child. Sending to a finished child errors (it does not resume) and points at subagent({ action: \"resume\", run_id, child_id, message }). \"reply\" answers a child's pending decision request; \"broadcast\" steers every running child of a run (to = run_id); \"list\" shows children, pending decision requests, and recent traffic.",
+  "tools.agent_message.description": "Message your subagents. \"send\" steers or queues a running child, and starts a new turn on an idle one. An idle child (warm or parked) continues with send or subagent resume; its prompt cache stays warm only for the time a wake reports. \"reply\" answers a child's pending decision request; \"broadcast\" steers every running child of a run (to = run_id); \"list\" shows children, pending decision requests, and recent traffic.",
   "tools.agent_message.snippet": "Send/reply/broadcast messages to subagents",
   "tools.agent_message.param.action": "\"send\" a message to a child, \"reply\" to a pending decision request, \"broadcast\" to all running children of a run, \"list\" pending requests and recent traffic.",
   "tools.agent_message.param.to": "Target child_id or name (\"send\"/\"reply\"). For \"broadcast\" from the parent session: run_id. Child sessions broadcast to their own run and must omit this.",
   "tools.agent_message.param.message": "Message text.",
-  "tools.agent_message.param.delivery": "\"steer\" (default) delivers to a running child after its current tool call/turn finishes; \"queue\" delivers after its current turn. Sending to a finished child is an error — resume with subagent({action:\"resume\"}).",
-  "tools.agent_message.error.finished-child": "Child {{childId}} ({{name}}) has finished ({{status}}). agent_message does not resume children. Use subagent({ action: \"resume\", run_id: \"{{runId}}\", child_id: \"{{childId}}\", message: \"...\" }).",
+  "tools.agent_message.param.delivery": "\"steer\" (default) delivers to a running child after its current tool call/turn finishes; \"queue\" delivers after its current turn. Sending to an idle child starts a new turn.",
+  "tools.agent_message.error.finished-child": "Child {{childId}} ({{name}}) has finished ({{status}}), and this host cannot start another turn. Use subagent({ action: \"resume\", run_id: \"{{runId}}\", child_id: \"{{childId}}\", message: \"...\" }).",
   "tools.bash.description": "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last {{maxLines}} lines or {{maxKb}}KB (whichever is hit first). Foreground commands that exceed the foreground budget are automatically moved to the background; you will be notified when they complete. Optionally provide a timeout in seconds (hard kill limit), or run_in_background to background immediately.",
   "tools.bash.snippet": "Execute bash commands (ls, grep, find, etc.)",
   "tools.bash.rules": ["You can inspect PI_* environment variables for current model and session details.","Long-running bash commands are moved to the background automatically; do not poll or sleep to wait for them. End your turn (a reply with no tool call) and resume from the task wake when it arrives."],
@@ -23,7 +23,7 @@ export const PROMPTS = {
   "tools.bash.param.run_in_background": "Start the command in the background and return immediately. You will be notified when it completes.",
   "tools.bash.result.backgrounded": "Command \"{{command}}\" moved to background (task_id: {{taskId}}). Output: {{outputPath}}.\nYou will be notified when it completes, even if other commands are still running. Do not poll or sleep: reply to the user now with no tool call, and continue from the <pi-famulus-wake kind=\"task\"> when it arrives.",
   "tools.bash.error.bare-sleep": "Refusing to run a bare sleep/idle-loop command: {{command}}. Do not sleep to wait for background work; completion is delivered via notification. Use the monitor tool to watch for a condition, or run_in_background for long commands.",
-  "tools.child.agent_message.description": "Message sibling subagents in your run, or list pending requests. \"send\" delivers to a running sibling. Sending to a finished sibling errors and does not resume it; resume with subagent({ action: \"resume\", run_id, child_id, message }). \"broadcast\" steers every running sibling in your run; \"list\" shows pending decision requests and recent traffic. Cross-run messaging is rejected.",
+  "tools.child.agent_message.description": "Message sibling subagents in your run, or list pending requests. \"send\" delivers to a running sibling and starts a new turn on an idle one. \"broadcast\" steers every running sibling in your run; \"list\" shows pending decision requests and recent traffic. Cross-run messaging is rejected.",
   "tools.child.agent_message.snippet": "Message sibling subagents in your run",
   "tools.child.bash.description": "Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last {{maxLines}} lines or {{maxKb}}KB (whichever is hit first). The command runs to completion (or the optional timeout in seconds, after which it is killed). There is no background execution inside subagents.",
   "tools.child.bash.snippet": "Execute bash commands (ls, grep, find, etc.)",
@@ -158,11 +158,10 @@ export const PROMPT_SEGMENTS: Record<string, { prompt: PromptId; text?: string;
   "guidelines.no-fabrication": {"prompt":"guidelines.parent","text":"Never fabricate or assume a background task's result before its notification arrives."},
   "guidelines.subagent-handover": {"prompt":"guidelines.parent","text":"Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue."},
   "guidelines.subagent-overrun": {"prompt":"guidelines.parent","text":"A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again."},
-  "guidelines.agent-message": {"prompt":"guidelines.parent","text":"Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:\"resume\"}). Supervisor wakes are not user messages — still act on them."},
+  "guidelines.agent-message": {"prompt":"guidelines.parent","text":"Use agent_message to steer a running subagent or to continue an idle one (send starts a new turn), and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). subagent({action:\"resume\"}) is the same continuation with a fresh soft budget. Supervisor wakes are not user messages — still act on them."},
   "guidelines.monitor-end-turn": {"prompt":"guidelines.monitor-idle","text":"After starting or re-arming a monitor, or handling a monitor event, if no immediate work remains, end your turn with no tool call; simply wait for the next notification. Handling an event does not require a user-visible reply. Do not repeat unchanged/intermediate status or narrate your decision to stay quiet; notify the user when their requested condition is met, their input is needed, or a failure prevents further progress. Read original output with task_output only when details are needed (including paging a truncated preview), never to poll or wait. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield."},
   "child.guidelines": {"prompt":"guidelines.child","text":"## Child agent behavior (pi-famulus)\n\n- Do not background work; bash runs to completion.\n- When blocked, use contact_supervisor with need_decision; use progress_update for status.\n- Use agent_message only to communicate with siblings in this same run.\n- Your final message is your result."},
-  "tooldesc.agent-message-no-resume": {"prompt":"tools.agent_message.description","text":"Sending to a finished child errors (it does not resume) and points at subagent({ action: \"resume\", run_id, child_id, message }). "},
-  "result.agent-message-use-resume": {"prompt":"tools.agent_message.error.finished-child","pattern":"agent_message does not resume children\\. Use subagent\\(\\{ action: \"resume\", run_id: \".*?\", child_id: \".*?\", message: \"\\.\\.\\.\" \\}\\)\\."},
+  "tooldesc.agent-message-no-resume": {"prompt":"tools.agent_message.description","text":"An idle child (warm or parked) continues with send or subagent resume; its prompt cache stays warm only for the time a wake reports. "},
   "tooldesc.bash-autobg": {"prompt":"tools.bash.description","text":"Foreground commands that exceed the foreground budget are automatically moved to the background; you will be notified when they complete. "},
   "rules.pi-env": {"prompt":"tools.bash.rules","text":"You can inspect PI_* environment variables for current model and session details."},
   "rules.bash-no-poll": {"prompt":"tools.bash.rules","text":"Long-running bash commands are moved to the background automatically; do not poll or sleep to wait for them."},