pi-famulus 0.1.2 → 0.1.4

package/src/notify.ts

@@ -14,7 +14,7 @@
  *   ever delivered once.
  */
 import { formatMonitorEvent, formatTaskNotification, type TaskExitInfo } from "./format";
-import { FAMULUS_WAKE_CUSTOM_TYPE, type WakeItem } from "./wake";
+import { FAMULUS_WAKE_CUSTOM_TYPE, stampWakeAsOf, wakeIds, type WakeItem } from "./wake";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 
@@ -88,6 +88,8 @@ export class NotifyCenter {
    */
   notify(message: NotifyMessage, opts: { passive?: boolean; quietEvents?: boolean } = {}): void {
     if (this.disposed) return;
+    // Stamped on arrival: a held passive notice keeps the time it was built.
+    message = stampWakeAsOf(message, this.clock.now());
     const wake = message.details as { kind?: string; id?: string } | undefined;
     if (wake?.kind === "monitor" && typeof wake.id === "string") this.flushMonitor(wake.id, opts.quietEvents);
     if (!opts.passive) {
@@ -203,14 +205,12 @@ export class NotifyCenter {
   }
 
   private deliver(message: NotifyMessage, passive = false): void {
+    // Wakes built here (task batches, monitor events) are stamped now.
+    message = stampWakeAsOf(message, this.clock.now());
     const msg = { ...message, display: true };
-    const details = message.details as { kind?: string; id?: string; taskId?: string; tasks?: { id: string }[]; children?: { childId: string }[]; childId?: string; from?: string; eventCount?: number } | undefined;
+    const details = message.details as { kind?: string; eventCount?: number } | undefined;
     if (details?.kind) {
-      const ids = details.kind === "task"
-        ? (details.tasks ?? []).map((task) => task.id)
-        : details.kind === "subagent-done"
-          ? (details.children ?? []).map((child) => child.childId)
-          : [details.id ?? details.taskId ?? details.childId ?? details.from].filter((id): id is string => Boolean(id));
+      const ids = wakeIds(details);
       this.deps.logEvent?.("wake.emit", {
         kind: details.kind,
         ids,

package/src/prompts.generated.ts

@@ -0,0 +1,183 @@
+// Generated by scripts/build-prompts.ts from prompts/. Do not edit; run `npm run prompts`.
+
+export const PROMPTS = {
+  "agents.explorer.description": "Fast read-only codebase exploration — finds files, symbols, and answers structure questions",
+  "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. Do not wait for further user input when the next step is clear; do not merely acknowledge 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.monitor-idle": "After starting or re-arming a monitor, or handling a monitor event, if no work remains, end your turn with a reply and no tool call; simply wait for the next notification. 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.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.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."],
+  "tools.bash.param.command": "The bash command to execute",
+  "tools.bash.param.timeout": "Hard kill timeout in seconds (optional, no default timeout)",
+  "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.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.)",
+  "tools.child.bash.param.command": "The bash command to execute",
+  "tools.child.bash.param.timeout": "Hard kill timeout in seconds (optional, no default timeout)",
+  "tools.child.bash.error.bare-sleep": "Refusing to run a bare sleep/idle-loop command: {{command}}. Sleeping to wait for work is never useful: run the actual command directly, or report back to the supervisor if you are blocked.",
+  "tools.child.contact_supervisor.description": "Contact the supervisor (parent agent). Use reason \"need_decision\" when you are blocked and need the parent to decide — the call blocks until the parent replies (10 minute timeout, after which you must decide yourself). Use reason \"progress_update\" for a fire-and-forget status note.",
+  "tools.child.contact_supervisor.snippet": "Ask the parent agent for a decision or report progress",
+  "tools.child.contact_supervisor.param.reason": "\"need_decision\" blocks until the supervisor (parent agent) replies; \"progress_update\" is fire-and-forget.",
+  "tools.child.contact_supervisor.param.message": "Message for the supervisor.",
+  "tools.monitor.description": "Start a background monitor process whose stdout lines are injected back to you as <pi-famulus-wake kind=\"monitor\"> messages (batched over 200ms, rate-limited). The command must be line-buffered: each event must be a single line. It must keep running and follow its source, e.g. `tail -n +1 -F file | grep --line-buffered PATTERN`; a command that reads once and exits (a plain grep or cat) only reports what is there now. Add `-m1` to grep to stop after the first match. Silence is not success: write the command so failures also produce lines (e.g. grep for both success and error patterns). Events arrive as system wakes (not new user messages). Handle each <pi-famulus-wake kind=\"monitor\"> before other work. Do not poll. {{monitorIdle}}",
+  "tools.monitor.snippet": "Watch a command's line stream and get injected events",
+  "tools.monitor.rules": ["Use the monitor tool to watch for conditions instead of running sleep/poll loops in bash.","{{monitorIdle}}","When woken by a <pi-famulus-wake kind=\"monitor\">, handle the <event> before doing anything else — it is not a new user request and not user confirmation."],
+  "tools.monitor.param.command": "Command producing one event per line on stdout. Must be line-buffered (e.g. use `stdbuf -oL` / `grep --line-buffered` where needed).",
+  "tools.monitor.param.description": "Short human-readable description of what is being watched",
+  "tools.monitor.param.timeout_ms": "Stop the monitor after this many milliseconds (default {{defaultMs}}, min {{minMs}}, max {{maxMs}})",
+  "tools.monitor.param.persistent": "Keep the monitor alive until the session ends (no timeout). Default false.",
+  "tools.monitor.result.started": "You will get a <pi-famulus-wake kind=\"monitor\"> for each event, and a notice when it exits or times out. Do not poll it (task_list, task_output, or reading what it watches) or sleep. {{monitorIdle}}",
+  "tools.subagent.description": "Run subagents in parallel (tasks) or sequentially (chain with {previous}/{outputs.<label>} interpolation). By default the call waits up to a foreground budget (default 45s); longer runs continue in the background. Each child that finishes while others are still running wakes you with <pi-famulus-wake kind=\"subagent-handover\"> (its prompt and result). The whole run wakes you with <pi-famulus-wake kind=\"subagent-done\">. Never poll or sleep to wait. A subagent still running past its timeout_ms is not stopped; it wakes you with <pi-famulus-wake kind=\"subagent-overrun\"> so you can extend, steer, or interrupt it. Use action=list/get/status/interrupt/resume/steer/extend to manage existing runs.",
+  "tools.subagent.snippet": "Fan out subagents in parallel or sequence them in a chain",
+  "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.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.",
+  "tools.subagent.param.chain.agent": "Agent definition name (default: worker)",
+  "tools.subagent.param.chain.prompt": "Prompt for this step; {previous} and {outputs.<label>} interpolate earlier results",
+  "tools.subagent.param.chain.label": "Label for referencing this step's output later",
+  "tools.subagent.param.async": "Return immediately with a run_id; completion arrives via notification",
+  "tools.subagent.param.concurrency": "Max parallel subagents for tasks (default 4)",
+  "tools.subagent.param.fail_fast": "Cancel not-yet-started subagents on first failure (already-started ones finish)",
+  "tools.subagent.param.model": "Model override for all subagents: fuzzy (\"haiku\"), qualified (\"provider/id\"), optionally with \":<thinking>\" suffix ({{thinkingLevels}}; an unknown suffix is dropped with a warning when the base resolves; an unknown base still errors). Default: current model. Use action:\"models\" to list selectable values.",
+  "tools.subagent.param.timeout_ms": "Time budget per subagent turn in ms (default 1800000, max {{maxMs}}). Passing it does not stop the subagent: you get <pi-famulus-wake kind=\"subagent-overrun\"> and choose extend, steer, or interrupt. With resume: the resumed turn's budget. With extend: the new budget from now.",
+  "tools.subagent.param.action": "Manage an existing run (or list selectable models) instead of starting a new one. When action is set, omit tasks and chain entirely; these launch-only fields are not required placeholders for control calls.",
+  "tools.subagent.param.run_id": "Target run for action",
+  "tools.subagent.param.child_id": "Target child (id or name) for steer/interrupt/resume/extend",
+  "tools.subagent.param.message": "Message content for steer/resume",
+  "tools.subagent.result.backgrounded": "Started {{count}} subagent(s) in run {{runId}}. {{reason}}\nWhile others are still running, each finished subagent arrives as <pi-famulus-wake kind=\"subagent-handover\"> with that child's prompt and result. Read it and continue: 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 whole run. Do not poll. <pi-famulus-wake kind=\"subagent-done\"> arrives when every subagent in the run has finished. Use subagent({action:\"get\", run_id:\"{{runId}}\"}) if you need the full record.",
+  "tools.subagent.result.extended": "Extended subagent {{name}} ({{childId}}) in run {{runId}}: the next <pi-famulus-wake kind=\"subagent-overrun\"> comes in {{next}} if it is still running. Its result arrives as a wake when it finishes; do not poll.",
+  "tools.subagent.result.extended.hard-ceiling": "The configured hard ceiling (hardTimeoutMs) is not moved: it stops this subagent in {{remaining}}.",
+  "tools.subagent.result.resumed": "Resumed subagent {{name}} ({{childId}}) in run {{runId}}. {{queued}}You will be notified via <pi-famulus-wake kind=\"subagent-handover\"> if others are still running, otherwise via <pi-famulus-wake kind=\"subagent-done\"> when it completes. Do not poll.",
+  "tools.subagent.error.resume-queued": "subagent {{name}} ({{childId}}) is already queued and starts when a subagent slot frees; its result arrives as a wake when it finishes. Do not resume it again.",
+  "tools.task_list.description": "List background work this session started: shell/monitor tasks and subagent children. Work from other pi sessions is never shown.",
+  "tools.task_list.snippet": "List background shell/monitor tasks and subagents",
+  "tools.task_list.param.all": "Also include finished work (default: running only). Always limited to this session.",
+  "tools.task_list.hint.running": "Running work wakes you with a <pi-famulus-wake> when it finishes. Reply to the user now with no tool call instead of checking again.",
+  "tools.task_output.description": "Read output of a background task. Without a cursor, returns the tail of the output plus the current file pointer; pass the returned next_cursor as cursor for incremental reads. Not a way to wait: a running task wakes you when it finishes, so reply with no tool call instead of calling this again.",
+  "tools.task_output.snippet": "Read background task output",
+  "tools.task_output.param.task_id": "Task id, e.g. sh_a1b2c3d4",
+  "tools.task_output.param.cursor": "Byte offset to read from (for incremental reads). Omit to read the tail of the output.",
+  "tools.task_output.param.max_bytes": "Maximum bytes to return (default 65536)",
+  "tools.task_output.hint.still-running": "The task is still running. Reply to the user now with no tool call; a <pi-famulus-wake> arrives when it finishes.",
+  "tools.task_output.error.no-new-output": "No new output from {{taskId}} since your last read. {{hint}}",
+  "tools.task_stop.description": "Stop a running background task (SIGTERM to the process group, SIGKILL after a 2s grace).",
+  "tools.task_stop.snippet": "Stop a background task",
+  "tools.task_stop.param.task_id": "Task id to stop, e.g. sh_a1b2c3d4",
+  "wakes.lead-in": "System wake — not a new user message. Handle this <pi-famulus-wake> before other work.",
+  "wakes.handover.changed-active": "Its result arrives as a new wake when it finishes.",
+  "wakes.done.changed-active": "The run is active again; another subagent-done arrives when it finishes.",
+  "wakes.overrun.summary": "{{name}} has run {{elapsed}} in this turn, past its {{budget}} budget, and is still running{{shell}}.",
+  "wakes.overrun.summary-shell": "; it is waiting on a shell command that has run {{elapsed}}",
+  "wakes.overrun.actions": "give it more time with subagent({ action: \"extend\", run_id: \"{{runId}}\", child_id: \"{{childId}}\", timeout_ms: <ms from now> }); redirect it with agent_message({ action: \"send\", to: \"{{childId}}\", message: \"<instruction>\" }); or stop it with subagent({ action: \"interrupt\", run_id: \"{{runId}}\", child_id: \"{{childId}}\" }).",
+  "wakes.overrun.options": "It has not been stopped. Extend only when progress or a known, still-useful silent workload justifies more time within the user's timing constraints; a child shell timeout is not evidence of progress and is not, by itself, a reason to extend past the requested timeframe. Choose one: {{actions}} If you do none of these, it keeps running and the next reminder is scheduled in {{next}}; its result arrives as usual when it finishes.",
+  "wakes.overrun.options-ceiling": "It has not been stopped yet, but the configured hard ceiling stops it in {{ceiling}}, and extend does not move that ceiling. Choose one: {{actions}} {{noAction}} Its result, or the interruption, arrives as a wake.",
+  "wakes.overrun.ceiling-no-action-reminder": "If you do none of these, it keeps running and the next reminder is scheduled in {{next}}, until the hard ceiling stops it in {{ceiling}}.",
+  "wakes.overrun.ceiling-no-action": "If you do none of these, it keeps running until the hard ceiling stops it.",
+  "wakes.request.reply-with": "agent_message { action: \"reply\", to: \"{{from}}\", message: \"<your decision>\" }",
+} as const;
+
+export type PromptId = keyof typeof PROMPTS;
+
+/** Placeholder names of each template prompt. */
+export interface PromptVars {
+  "guidelines.parent": "monitorIdle";
+  "tools.agent_message.error.finished-child": "childId" | "name" | "status" | "runId";
+  "tools.bash.description": "maxLines" | "maxKb";
+  "tools.bash.result.backgrounded": "command" | "taskId" | "outputPath";
+  "tools.bash.error.bare-sleep": "command";
+  "tools.child.bash.description": "maxLines" | "maxKb";
+  "tools.child.bash.error.bare-sleep": "command";
+  "tools.monitor.description": "monitorIdle";
+  "tools.monitor.rules": "monitorIdle";
+  "tools.monitor.param.timeout_ms": "defaultMs" | "minMs" | "maxMs";
+  "tools.monitor.result.started": "monitorIdle";
+  "tools.subagent.param.model": "thinkingLevels";
+  "tools.subagent.param.timeout_ms": "maxMs";
+  "tools.subagent.result.backgrounded": "count" | "runId" | "reason";
+  "tools.subagent.result.extended": "name" | "childId" | "runId" | "next";
+  "tools.subagent.result.extended.hard-ceiling": "remaining";
+  "tools.subagent.result.resumed": "name" | "childId" | "runId" | "queued";
+  "tools.subagent.error.resume-queued": "name" | "childId";
+  "tools.task_output.error.no-new-output": "taskId" | "hint";
+  "wakes.overrun.summary": "name" | "elapsed" | "budget" | "shell";
+  "wakes.overrun.summary-shell": "elapsed";
+  "wakes.overrun.actions": "runId" | "childId";
+  "wakes.overrun.options": "actions" | "next";
+  "wakes.overrun.options-ceiling": "ceiling" | "actions" | "noAction";
+  "wakes.overrun.ceiling-no-action-reminder": "next" | "ceiling";
+  "wakes.request.reply-with": "from";
+}
+
+/** Fill a template prompt; every placeholder must be given. */
+export function fill<K extends keyof PromptVars>(id: K, vars: Record<PromptVars[K], string | number>): string {
+  const template = PROMPTS[id] as string;
+  return template.replace(/\{\{(\w+)\}\}/g, (_, name: string) => {
+    const v = (vars as Record<string, string | number>)[name];
+    if (v === undefined) throw new Error(`prompt ${id}: missing {{${name}}}`);
+    return String(v);
+  });
+}
+
+/** Fill every item of a list prompt (rules) that has placeholders. */
+export function fillList<K extends keyof PromptVars>(id: K, vars: Record<PromptVars[K], string | number>): string[] {
+  return (PROMPTS[id] as readonly string[]).map((item) =>
+    item.replace(/\{\{(\w+)\}\}/g, (_, name: string) => {
+      const v = (vars as Record<string, string | number>)[name];
+      if (v === undefined) throw new Error(`prompt ${id}: missing {{${name}}}`);
+      return String(v);
+    }),
+  );
+}
+
+/** Ablatable spans (eval manifest segment ids). */
+export const PROMPT_SEGMENTS: Record<string, { prompt: PromptId; text?: string; pattern?: string }> = {
+  "guidelines.end-turn-after-bg": {"prompt":"guidelines.parent","text":"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."},
+  "guidelines.wake-handling": {"prompt":"guidelines.parent","text":"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. Do not wait for further user input when the next step is clear; do not merely acknowledge and stop."},
+  "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.monitor-end-turn": {"prompt":"guidelines.monitor-idle","text":"After starting or re-arming a monitor, or handling a monitor event, if no work remains, end your turn with a reply and no tool call; simply wait for the next notification. 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.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."},
+  "result.bash-bg-instruction": {"prompt":"tools.bash.result.backgrounded","text":"\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."},
+  "result.sleep-block-advice": {"prompt":"tools.bash.error.bare-sleep","text":" 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."},
+  "tooldesc.monitor-follow": {"prompt":"tools.monitor.description","text":"It must keep running and follow its source, e.g. `tail -n +1 -F file | grep --line-buffered PATTERN`; a command that reads once and exits (a plain grep or cat) only reports what is there now. Add `-m1` to grep to stop after the first match. "},
+  "tooldesc.monitor-silence": {"prompt":"tools.monitor.description","text":"Silence is not success: write the command so failures also produce lines (e.g. grep for both success and error patterns). "},
+  "tooldesc.monitor-wake": {"prompt":"tools.monitor.description","text":"Events arrive as system wakes (not new user messages). Handle each <pi-famulus-wake kind=\"monitor\"> before other work. Do not poll."},
+  "rules.monitor-use": {"prompt":"tools.monitor.rules","text":"Use the monitor tool to watch for conditions instead of running sleep/poll loops in bash."},
+  "rules.monitor-wake": {"prompt":"tools.monitor.rules","text":"When woken by a <pi-famulus-wake kind=\"monitor\">, handle the <event> before doing anything else — it is not a new user request and not user confirmation."},
+  "result.monitor-started-instruction": {"prompt":"tools.monitor.result.started","text":"You will get a <pi-famulus-wake kind=\"monitor\"> for each event, and a notice when it exits or times out. Do not poll it (task_list, task_output, or reading what it watches) or sleep."},
+  "tooldesc.subagent-wakes": {"prompt":"tools.subagent.description","text":"Each child that finishes while others are still running wakes you with <pi-famulus-wake kind=\"subagent-handover\"> (its prompt and result). The whole run wakes you with <pi-famulus-wake kind=\"subagent-done\">. Never poll or sleep to wait. "},
+  "tooldesc.subagent-overrun": {"prompt":"tools.subagent.description","text":"A subagent still running past its timeout_ms is not stopped; it wakes you with <pi-famulus-wake kind=\"subagent-overrun\"> so you can extend, steer, or interrupt it. "},
+  "rules.subagent-handover": {"prompt":"tools.subagent.rules","text":"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."},
+  "rules.subagent-no-poll": {"prompt":"tools.subagent.rules","text":"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."},
+  "rules.subagent-failed-child": {"prompt":"tools.subagent.rules","text":"A failed subagent does not fail the whole run; inspect per-subagent sections in the result."},
+  "rules.subagent-wakes-not-user": {"prompt":"tools.subagent.rules","text":"<pi-famulus-wake> is a system wake, not a user reply. kind=subagent-handover is one child; kind=subagent-done is the whole run."},
+  "tooldesc.subagent-timeout-overrun": {"prompt":"tools.subagent.param.timeout_ms","text":"Passing it does not stop the subagent: you get <pi-famulus-wake kind=\"subagent-overrun\"> and choose extend, steer, or interrupt. With resume: the resumed turn's budget. With extend: the new budget from now."},
+  "result.subagent-bg-instruction": {"prompt":"tools.subagent.result.backgrounded","text":"While others are still running, each finished subagent arrives as <pi-famulus-wake kind=\"subagent-handover\"> with that child's prompt and result. Read it and continue: 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 whole run. Do not poll. <pi-famulus-wake kind=\"subagent-done\"> arrives when every subagent in the run has finished. "},
+  "wake.lead-in": {"prompt":"wakes.lead-in","text":"System wake — not a new user message. Handle this <pi-famulus-wake> before other work."},
+};

package/src/shell-exec.ts

@@ -5,6 +5,7 @@
 import type { BashToolDetails } from "@earendil-works/pi-coding-agent";
 import { truncateTail } from "./format";
 import type { ManagerClient } from "./manager-client";
+import { fill } from "./prompts.generated";
 
 export const SHELL_MAX_LINES = 2000;
 export const SHELL_MAX_BYTES = 51200;
@@ -17,9 +18,12 @@ export const BARE_SLEEP_PATTERNS: RegExp[] = [
   /^\s*until\s+/,
 ];
 
-export function bareSleepError(command: string, guidance: string): string | null {
+export function bareSleepError(
+  command: string,
+  prompt: "tools.bash.error.bare-sleep" | "tools.child.bash.error.bare-sleep",
+): string | null {
   if (!BARE_SLEEP_PATTERNS.some((re) => re.test(command))) return null;
-  return `Refusing to run a bare sleep/idle-loop command: ${JSON.stringify(command)}. ${guidance}`;
+  return fill(prompt, { command: JSON.stringify(command) });
 }
 
 export function withAbort<T>(

package/src/subagent/admission.ts

@@ -0,0 +1,224 @@
+export interface LocalReservation {
+  admit(): void;
+  release(): void;
+}
+
+export interface AgentAdmissionManager {
+  isAvailable(): boolean;
+  protocolLevel(): number;
+  acquireAgent(
+    childId: string,
+    workKind?: string,
+    signal?: AbortSignal,
+  ): Promise<{ granted: boolean; rejection?: string }>;
+  releaseAgent(childId: string): Promise<void>;
+}
+
+export interface AdmissionTicket {
+  current(): boolean;
+  signal: AbortSignal;
+}
+
+export interface AgentAdmissionOptions {
+  childId: string;
+  workKind?: string;
+  reserveLocal(): Promise<LocalReservation>;
+  manager: AgentAdmissionManager | null;
+  /** Locally held or potentially-held daemon permits, keyed by their kind. */
+  leases: Map<string, string>;
+  /** Locally admitted children still waiting for a daemon permit. */
+  pendingLeases?: Set<string>;
+  /** Reconnect-time acquires to abort if the child settles while queued. */
+  pendingReregistrations?: Map<string, AbortController>;
+  ticket?: AdmissionTicket;
+  notice(reason: "manager unavailable" | "daemon too old"): void;
+  wait?: (signal?: AbortSignal) => Promise<void>;
+}
+
+const MAX_REREGISTER_ATTEMPTS = 40;
+
+const defaultWait = (signal?: AbortSignal) => new Promise<void>((resolve, reject) => {
+  const timer = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, 500);
+  const onAbort = () => {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+    reject(new Error("subagent admission cancelled"));
+  };
+  if (signal?.aborted) onAbort();
+  else signal?.addEventListener("abort", onAbort, { once: true });
+});
+
+function waitForRetry(wait: (signal?: AbortSignal) => Promise<void>, signal?: AbortSignal): Promise<void> {
+  if (!signal) return wait();
+  if (signal.aborted) return Promise.reject(new Error("subagent admission cancelled"));
+  return new Promise<void>((resolve, reject) => {
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      cleanup();
+      reject(new Error("subagent admission cancelled"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    wait(signal).then(
+      () => {
+        cleanup();
+        resolve();
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}
+
+/** Reserve the per-session slot first, then obtain a machine-wide work-kind permit. */
+export async function admitAgentChild(options: AgentAdmissionOptions): Promise<(terminal?: boolean) => void> {
+  const { childId, reserveLocal, manager, leases, pendingLeases, ticket, notice } = options;
+  const workKind = options.workKind ?? "other";
+  const wait = options.wait ?? defaultWait;
+  const cancelReregistration = () => options.pendingReregistrations?.get(childId)?.abort();
+  const finish = (reservation: LocalReservation) => (terminal = true) => {
+    reservation.release();
+    if (terminal) {
+      cancelReregistration();
+      pendingLeases?.delete(childId);
+      if (leases.delete(childId)) void manager?.releaseAgent(childId).catch(() => {});
+    }
+  };
+  const admitLocally = (reservation: LocalReservation) => {
+    try {
+      reservation.admit();
+    } catch (error) {
+      reservation.release();
+      throw error;
+    }
+    // Keep locally admitted fallback children in the reconciliation set too.
+    // A daemon reconnect can then acquire their permit before a later resume.
+    leases.set(childId, workKind);
+    pendingLeases?.add(childId);
+    return finish(reservation);
+  };
+
+  for (;;) {
+    const local = await reserveLocal();
+    if (!manager?.isAvailable()) {
+      notice("manager unavailable");
+      return admitLocally(local);
+    }
+    if (manager.protocolLevel() < 4) {
+      notice("daemon too old");
+      return admitLocally(local);
+    }
+    // A local fallback lease is not yet a daemon permit. Reacquire it, while a
+    // previously granted machine permit survives normal generation resumes.
+    if (leases.has(childId) && !pendingLeases?.has(childId)) {
+      try {
+        local.admit();
+      } catch (error) {
+        local.release();
+        throw error;
+      }
+      return finish(local);
+    }
+
+    let admission: { granted: boolean; rejection?: string };
+    try {
+      admission = await manager.acquireAgent(childId, workKind, ticket?.signal);
+    } catch (error) {
+      local.release();
+      if (ticket?.signal.aborted || (ticket && !ticket.current())) {
+        throw new Error("subagent admission cancelled");
+      }
+      if (manager.isAvailable()) throw error;
+      notice("manager unavailable");
+      // The request may have been granted before its response was lost.
+      // Remember it as pending so reconnect's idempotent acquire can reconcile
+      // that uncertain server-side result without consuming another slot.
+      let fallback: LocalReservation;
+      try {
+        fallback = await reserveLocal();
+      } catch (fallbackError) {
+        void manager.releaseAgent(childId).catch(() => {});
+        throw fallbackError;
+      }
+      try {
+        return admitLocally(fallback);
+      } catch (fallbackError) {
+        void manager.releaseAgent(childId).catch(() => {});
+        throw fallbackError;
+      }
+    }
+    if (admission.granted) {
+      try {
+        if (ticket && !ticket.current()) throw new Error("subagent admission cancelled");
+        local.admit();
+      } catch (error) {
+        local.release();
+        void manager.releaseAgent(childId).catch(() => {});
+        throw error;
+      }
+      leases.set(childId, workKind);
+      pendingLeases?.delete(childId);
+      return finish(local);
+    }
+
+    local.release();
+    if (ticket && !ticket.current()) throw new Error("subagent admission cancelled");
+    await waitForRetry(wait, ticket?.signal);
+  }
+}
+
+/** Re-register extension-held leases after hello/reconnect, preserving kind. */
+export async function reregisterAgentLeases(
+  manager: AgentAdmissionManager,
+  leases: Map<string, string>,
+  wait: (signal?: AbortSignal) => Promise<void> = defaultWait,
+  pendingLeases?: Set<string>,
+  pendingReregistrations?: Map<string, AbortController>,
+): Promise<void> {
+  if (manager.protocolLevel() < 4) return;
+  const childIds = new Set([...leases.keys(), ...(pendingLeases ?? [])]);
+  await Promise.all([...childIds].map(async (childId) => {
+    const stillHeld = () => leases.has(childId) || pendingLeases?.has(childId) === true;
+    for (let attempt = 0; attempt < MAX_REREGISTER_ATTEMPTS && stillHeld() && manager.isAvailable() && manager.protocolLevel() >= 4; attempt++) {
+      if (pendingReregistrations?.has(childId)) break;
+      const workKind = leases.get(childId) ?? "other";
+      const controller = new AbortController();
+      pendingReregistrations?.set(childId, controller);
+      let admission: { granted: boolean; rejection?: string };
+      try {
+        admission = await (pendingReregistrations
+          ? manager.acquireAgent(childId, workKind, controller.signal)
+          : manager.acquireAgent(childId, workKind));
+      } catch (error) {
+        if (!stillHeld() || controller.signal.aborted) break;
+        if (
+          error instanceof Error
+          && error.message.startsWith("pi-famulus request timed out: acquire_agent")
+          && manager.isAvailable()
+        ) {
+          if (attempt + 1 < MAX_REREGISTER_ATTEMPTS) await waitForRetry(wait, controller.signal);
+          continue;
+        }
+        throw error;
+      } finally {
+        if (pendingReregistrations?.get(childId) === controller) pendingReregistrations.delete(childId);
+      }
+      if (!stillHeld()) {
+        // The child may have settled after the grant was made but before the
+        // acquire response reached this continuation.
+        if (admission.granted) void manager.releaseAgent(childId).catch(() => {});
+        break;
+      }
+      if (admission.granted) {
+        leases.set(childId, workKind);
+        pendingLeases?.delete(childId);
+        break;
+      }
+      if (attempt + 1 < MAX_REREGISTER_ATTEMPTS) await waitForRetry(wait, controller.signal);
+    }
+  }));
+}

package/src/subagent/agent-records.ts

@@ -4,7 +4,8 @@
  *
  * Layout: <home>/sessions/<session_id>/agents/<child_id>.json
  */
-import { mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 export interface AgentChildRecord {
@@ -15,6 +16,10 @@ export interface AgentChildRecord {
   session_id: string;
   name: string;
   agent: string;
+  /** Explicit planned work class; old records default to `other`. */
+  work_kind?: string;
+  /** Time spent waiting for admission, when measured. */
+  queue_ms?: number;
   /** Resolved model id when known (param override or agent definition). */
   model?: string;
   status: "pending" | "running" | "completed" | "failed" | "interrupted";
@@ -33,6 +38,18 @@ export interface AgentChildRecord {
   result_tail?: string;
   /** Tool results seen in the transcript so far. */
   tool_calls?: number;
+  /** Cumulative provider usage.input and usage.output as reported. */
+  tokens_input?: number;
+  tokens_output?: number;
+  /** Separate cumulative provider cache counters; not folded into tokens_input. */
+  tokens_cache_read?: number;
+  tokens_cache_write?: number;
+  /** Observed assistant-message, tool-execution, and admission-queue wall time. */
+  llm_ms?: number;
+  tool_ms?: number;
+  /** Wall time that did not fit the observed phase boundaries. */
+  wall_other_ms?: number;
+  wall_approximate?: boolean;
   /** Absolute path of the live `<child_id>.jsonl` transcript. */
   transcript?: string;
 }
@@ -82,11 +99,57 @@ export function agentRecordPath(home: string, sessionId: string, childId: string
   return join(agentRecordsDir(home, sessionId), `${childId}.json`);
 }
 
-/** Write one child record (mkdir + overwrite). */
+/** Write one child record atomically (mkdir + same-directory temp file + rename). */
 export function writeAgentChildRecord(home: string, record: AgentChildRecord): void {
   const dir = agentRecordsDir(home, record.session_id);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(agentRecordPath(home, record.session_id, record.child_id), JSON.stringify(record));
+  const path = agentRecordPath(home, record.session_id, record.child_id);
+  const tempPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    writeFileSync(tempPath, JSON.stringify(record), { flag: "wx" });
+    renameSync(tempPath, path);
+  } finally {
+    try {
+      unlinkSync(tempPath);
+    } catch {
+      // rename consumed the temporary file, or a failed write left none.
+    }
+  }
+}
+
+export type AgentChildTelemetry = Partial<Pick<AgentChildRecord,
+  "tokens_input" | "tokens_output" | "tokens_cache_read" | "tokens_cache_write" | "llm_ms" | "tool_ms" | "queue_ms" | "wall_other_ms" | "wall_approximate"
+>>;
+
+/** Refresh live telemetry without waiting for a child state transition. */
+export function updateAgentChildMetrics(
+  home: string,
+  sessionId: string,
+  childId: string,
+  metrics: AgentChildTelemetry,
+): void {
+  const path = agentRecordPath(home, sessionId, childId);
+  try {
+    const record = JSON.parse(readFileSync(path, "utf8")) as Partial<AgentChildRecord>;
+    if (record.v !== 1 || record.kind !== "agent" || record.session_id !== sessionId || record.child_id !== childId) return;
+    writeAgentChildRecord(home, { ...(record as AgentChildRecord), ...metrics });
+  } catch {
+    // A metrics refresh must never interfere with the in-process child.
+  }
+}
+
+export function updateAgentChildTokens(
+  home: string,
+  sessionId: string,
+  childId: string,
+  tokens: { input: number; output: number; cacheRead: number; cacheWrite: number },
+): void {
+  updateAgentChildMetrics(home, sessionId, childId, {
+    tokens_input: tokens.input,
+    tokens_output: tokens.output,
+    tokens_cache_read: tokens.cacheRead,
+    tokens_cache_write: tokens.cacheWrite,
+  });
 }
 
 export function removeAgentChildRecord(home: string, sessionId: string, childId: string): void {