pi-famulus 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,8 @@
 # pi-famulus
 
-Subagent orchestration, auto-backgrounding bash, monitoring, and agent-to-agent communication for pi.
+Subagent orchestration, auto-backgrounding bash, monitoring, and agent-to-agent communication for pi 1.0.0 or newer.
+
+Workers inherit user/global and trusted-project pi configuration and resources, including codemode and MCP, then receive famulus communication tools. An explicit agent `tools` list remains an allowlist; omitting it inherits the user’s default tools. Parent-only CLI resource overrides are not copied.
 
 After the first public release:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
   "type": "module",
   "license": "MIT",
@@ -9,21 +9,40 @@
     "url": "https://github.com/Leechael/pi-famulus",
     "directory": "extension"
   },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org" },
-  "os": ["linux", "darwin"],
-  "cpu": ["x64", "arm64"],
-  "files": ["src", "bin", "README.md"],
-  "bin": { "pi-famulus": "./bin/pi-famulus.js" },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "bin": {
+    "pi-famulus": "./bin/pi-famulus.js"
+  },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.1.2",
-    "pi-famulus-linux-arm64": "0.1.2",
-    "pi-famulus-darwin-x64": "0.1.2",
-    "pi-famulus-darwin-arm64": "0.1.2"
+    "pi-famulus-linux-x64": "0.1.4",
+    "pi-famulus-linux-arm64": "0.1.4",
+    "pi-famulus-darwin-x64": "0.1.4",
+    "pi-famulus-darwin-arm64": "0.1.4"
   },
   "pi": {
-    "extensions": ["./src/index.ts"]
+    "extensions": [
+      "./src/index.ts"
+    ]
   },
   "scripts": {
+    "deps": "nub install --frozen-lockfile --node-linker hoisted",
+    "prompts": "node scripts/build-prompts.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
@@ -36,7 +55,7 @@
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
     "typebox": "*",
     "@earendil-works/pi-tui": "*"
   },

package/src/agents/builtins.ts

@@ -4,38 +4,21 @@
  * These form the lowest precedence layer: user and project definitions with
  * the same name replace them wholesale.
  */
+import { PROMPTS } from "../prompts.generated";
 import type { AgentDefinition } from "./definition";
 
 export const BUILTIN_AGENTS: AgentDefinition[] = [
   {
     name: "explorer",
-    description:
-      "Fast read-only codebase exploration — finds files, symbols, and answers structure questions",
+    description: PROMPTS["agents.explorer.description"],
     tools: ["read", "grep", "find", "ls", "bash"],
-    systemPrompt: [
-      "You are an explorer agent. Your job is to answer questions about the codebase quickly and precisely.",
-      "",
-      "Rules:",
-      "- Return findings, never change code. You are strictly read-only: do not edit, write, or create files.",
-      "- Report concrete locations: cite specific file paths with line numbers (path:line) for every claim.",
-      "- Control your search scope: start narrow (targeted grep/find), widen only when needed, and stop once the question is answered.",
-      "- Prefer a short, factual summary over exhaustive dumps. List what you found and where.",
-    ].join("\n"),
+    systemPrompt: PROMPTS["agents.explorer.system-prompt"],
     source: "builtin",
   },
   {
     name: "worker",
-    description: "General-purpose executor — completes concrete coding tasks end to end",
-    tools: ["read", "bash", "edit", "write"],
-    systemPrompt: [
-      "You are a worker agent. Your job is to complete the concrete task you were given, end to end.",
-      "",
-      "Rules:",
-      "- Do the task, don't just describe it. Make the actual edits and run the actual commands.",
-      "- Self-verify before finishing: run the relevant tests, typecheck, or command that proves the task is done.",
-      "- Stay within the task's scope; do not refactor unrelated code.",
-      "- Report concisely: what you changed, how you verified it, and anything the supervisor should know.",
-    ].join("\n"),
+    description: PROMPTS["agents.worker.description"],
+    systemPrompt: PROMPTS["agents.worker.system-prompt"],
     source: "builtin",
   },
 ];

package/src/agents/definition.ts

@@ -15,16 +15,23 @@
  *   Body becomes the system prompt (trimmed; may be empty).
  */
 
+import {
+  isValidThinkingLevel,
+  VALID_THINKING_LEVELS,
+  type ThinkingLevel,
+} from "../thinking-levels";
+
 export interface AgentDefinition {
   /** Must match ^[a-z][a-z0-9-]*$ */
   name: string;
   /** Required, non-empty. */
   description: string;
-  /** Tool allowlist. Defaults to ["read","bash","edit","write"]. */
-  tools: string[];
+  /** Omitted: inherit user-configured tools. Explicit list: allowlist; []: disables user-configured tools, but injected Famulus tools remain. */
+  tools?: string[];
   /** "provider:id" or bare id. */
   model?: string;
-  thinking?: "minimal" | "low" | "medium" | "high" | "xhigh";
+  /** Thinking level (pi core parity; src/thinking-levels.ts). */
+  thinking?: ThinkingLevel;
   /** Frontmatter body, trimmed. Empty body → "". */
   systemPrompt: string;
   source: "builtin" | "user" | "project";
@@ -32,11 +39,7 @@ export interface AgentDefinition {
   path?: string;
 }
 
-export const DEFAULT_AGENT_TOOLS: readonly string[] = ["read", "bash", "edit", "write"];
-
 const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
-const THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh"] as const;
-type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 
 type Fail = (reason: string) => never;
 
@@ -163,7 +166,7 @@ export function parseAgentMarkdown(
   const description = parseScalar(fields.description, "description", fail);
   if (description === "") fail("field 'description' must be non-empty");
 
-  let tools = [...DEFAULT_AGENT_TOOLS];
+  let tools: string[] | undefined;
   if (fields.tools !== undefined) {
     tools = parseStringArray(fields.tools, "tools", fail);
   }
@@ -178,18 +181,19 @@ export function parseAgentMarkdown(
   let thinking: ThinkingLevel | undefined;
   if (fields.thinking !== undefined) {
     const value = parseScalar(fields.thinking, "thinking", fail);
-    if (!(THINKING_LEVELS as readonly string[]).includes(value)) {
+    if (isValidThinkingLevel(value)) {
+      thinking = value;
+    } else {
       fail(
-        `invalid thinking level "${value}" (expected one of: ${THINKING_LEVELS.join(", ")})`,
+        `invalid thinking level "${value}" (expected one of: ${VALID_THINKING_LEVELS.join(", ")})`,
       );
     }
-    thinking = value as ThinkingLevel;
   }
 
   return {
     name,
     description,
-    tools,
+    ...(tools !== undefined ? { tools } : {}),
     ...(model !== undefined ? { model } : {}),
     ...(thinking !== undefined ? { thinking } : {}),
     systemPrompt: body.trim(),

package/src/bash-override.ts

@@ -30,6 +30,7 @@ import { backgroundRowText, formatBackgroundNotice, truncateTail } from "./forma
 import { toolComponent } from "./tui/tool-component";
 import type { WorkIndex } from "./work-index";
 import type { ManagerClient } from "./manager-client";
+import { fill, PROMPTS } from "./prompts.generated";
 import {
   appendStatus,
   bareSleepError,
@@ -48,15 +49,12 @@ const MAX_LINES = SHELL_MAX_LINES;
 const MAX_BYTES = SHELL_MAX_BYTES;
 
 const bashParameters = Type.Object({
-  command: Type.String({ description: "The bash command to execute" }),
+  command: Type.String({ description: PROMPTS["tools.bash.param.command"] }),
   timeout: Type.Optional(
-    Type.Number({ description: "Hard kill timeout in seconds (optional, no default timeout)" }),
+    Type.Number({ description: PROMPTS["tools.bash.param.timeout"] }),
   ),
   run_in_background: Type.Optional(
-    Type.Boolean({
-      description:
-        "Start the command in the background and return immediately. You will be notified when it completes.",
-    }),
+    Type.Boolean({ description: PROMPTS["tools.bash.param.run_in_background"] }),
   ),
 });
 
@@ -135,11 +133,8 @@ function isActiveStatus(status: string | undefined): boolean {
   return status === undefined || status === "running" || status === "pending";
 }
 
-const BARE_SLEEP_GUIDANCE =
-  "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.";
-
 function rejectBareSleep(command: string): string | null {
-  return bareSleepError(command, BARE_SLEEP_GUIDANCE);
+  return bareSleepError(command, "tools.bash.error.bare-sleep");
 }
 
 function resolveTimeoutMs(timeoutSeconds: number | undefined): number | null {
@@ -289,17 +284,9 @@ export function createBashOverride(
   return {
     name: "bash",
     label: "Bash",
-    description:
-      "Execute a bash command in the current working directory. Returns stdout and stderr. " +
-      `Output is truncated to last ${MAX_LINES} lines or ${MAX_BYTES / 1024}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.",
-    promptSnippet: "Execute bash commands (ls, grep, find, etc.)",
-    promptGuidelines: [
-      "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.",
-    ],
+    description: fill("tools.bash.description", { maxLines: MAX_LINES, maxKb: MAX_BYTES / 1024 }),
+    promptSnippet: PROMPTS["tools.bash.snippet"],
+    promptGuidelines: [...PROMPTS["tools.bash.rules"]],
     parameters: bashParameters,
     outputSchema: bashOutputSchema,
     renderResult(result, { expanded }, theme, context) {

package/src/behavior-guidelines.ts

@@ -4,25 +4,22 @@
  * Returning `systemPrompt` from before_agent_start forces the whole prompt for
  * that user-prompt run only (and clobbers other extensions). Wake turns started
  * by sendMessage({ triggerTurn: true }) do not call before_agent_start again.
- * A named section is diffed into the transcript and stays visible on those turns.
+ * A named section is recorded on user turns. Pi can rebuild the base prompt
+ * after a wake's tool result and remove that run-local section, so the request
+ * projection restores only our section whenever it is missing or stale.
  */
-export const BEHAVIOR_GUIDELINES_SECTION = "pi-famulus";
+import type { ContextWithSystemEvent, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+// .ts suffix: eval/ loads this module with Node's own TypeScript support.
+import { fill, PROMPTS } from "./prompts.generated.ts";
 
-/** Child-only instructions injected through the contact_supervisor tool guideline. */
-export const CHILD_BEHAVIOR_GUIDELINES = `## Child agent behavior (pi-famulus)
+export const BEHAVIOR_GUIDELINES_SECTION = "pi-famulus";
 
-- Do not background work; bash runs to completion.
-- When blocked, use contact_supervisor with need_decision; use progress_update for status.
-- Use agent_message only to communicate with siblings in this same run.
-- Your final message is your result.`;
+export const MONITOR_IDLE_INSTRUCTION = PROMPTS["guidelines.monitor-idle"];
 
-export const BEHAVIOR_GUIDELINES = `## Background tasks and notifications (pi-famulus)
+/** Child-only instructions injected through the contact_supervisor tool guideline. */
+export const CHILD_BEHAVIOR_GUIDELINES = PROMPTS["guidelines.child"];
 
-- 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.
-- 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.
-- Never fabricate or assume a background task's result before its notification arrives.
-- 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.
-- 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.`;
+export const BEHAVIOR_GUIDELINES = fill("guidelines.parent", { monitorIdle: MONITOR_IDLE_INSTRUCTION });
 
 export interface GuidelinePromptOptions {
   sections?: Record<string, string>;
@@ -34,7 +31,35 @@ export function applyBehaviorGuidelines(options: GuidelinePromptOptions): void {
   options.sections[BEHAVIOR_GUIDELINES_SECTION] = BEHAVIOR_GUIDELINES;
 }
 
-/** What a later wake turn sees: persisted sections, no before_agent_start. */
+/** Register parent behavior without relying on command-only context methods. */
+export function registerBehaviorGuidelines(pi: Pick<ExtensionAPI, "on">): void {
+  pi.on("before_agent_start", (event) => {
+    applyBehaviorGuidelines(event.systemPromptOptions);
+  });
+  pi.on("context_with_system", (event) => restoreBehaviorGuidelines(event.messages));
+}
+
+/** Repair the model request, not the persisted transcript or other sections. */
+export function restoreBehaviorGuidelines(messages: ContextWithSystemEvent["messages"]) {
+  const expected = `<${BEHAVIOR_GUIDELINES_SECTION}>\n${BEHAVIOR_GUIDELINES}\n</${BEHAVIOR_GUIDELINES_SECTION}>`;
+  let current: string | null | undefined;
+  for (const message of messages) {
+    if (message.role === "system" && message.sections && BEHAVIOR_GUIDELINES_SECTION in message.sections) {
+      current = message.sections[BEHAVIOR_GUIDELINES_SECTION];
+    }
+  }
+  if (current === expected) return undefined;
+  return {
+    messages: [...messages, {
+      role: "system" as const,
+      content: "",
+      sections: { [BEHAVIOR_GUIDELINES_SECTION]: expected },
+      timestamp: Date.now(),
+    }],
+  };
+}
+
+/** Render named sections without replacing unrelated instructions. */
 export function wakePromptFromSections(sections: Record<string, string>): string {
   return Object.entries(sections)
     .map(([name, content]) => `<${name}>\n${content}\n</${name}>`)

package/src/clock.ts

@@ -43,6 +43,11 @@ export class ManualClock implements Clock {
     return this.currentTime;
   }
 
+  /** Timers still scheduled: lets tests assert that settle left nothing armed. */
+  get pendingTimers(): number {
+    return this.timers.size;
+  }
+
   setTimeout(callback: () => void, delayMs: number): ClockTimer {
     return this.schedule(callback, delayMs, null);
   }

package/src/comms/comms.ts

@@ -10,6 +10,7 @@ import {
   type MailboxOptions,
 } from "./mailbox";
 import type { Comms, CommsHost } from "./types";
+import { fill } from "../prompts.generated";
 import { formatFamulusWake, type FormattedWake } from "../wake";
 import type { Clock } from "../clock";
 
@@ -149,9 +150,12 @@ export function createComms(host: CommsHost, options: CommsOptions = {}): CommsW
         // Lifecycle (resume) belongs to the subagent tool. Resuming here never
         // wired a completion wake, so the parent hung.
         throw new Error(
-          `Child ${toChildId} (${child.name}) has finished (${child.status}). ` +
-            `agent_message does not resume children. ` +
-            `Use subagent({ action: "resume", run_id: "${child.runId}", child_id: "${toChildId}", message: "..." }).`,
+          fill("tools.agent_message.error.finished-child", {
+            childId: toChildId,
+            name: child.name,
+            status: child.status,
+            runId: child.runId,
+          }),
         );
       } else {
         throw new Error(

package/src/comms/tools.ts

@@ -13,6 +13,7 @@ import { realClock, type Clock } from "../clock";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { CommsWithOrigin } from "./comms";
 import { assertSiblingAllowed } from "./routing";
+import { PROMPTS } from "../prompts.generated";
 import type { ChildStatus, Comms, CommsHost, MailboxEntry } from "./types";
 
 export type AgentMessageSender =
@@ -25,11 +26,9 @@ export type AgentMessageSender =
 
 const contactSupervisorParameters = Type.Object({
   reason: Type.Union([Type.Literal("need_decision"), Type.Literal("progress_update")], {
-    description:
-      '"need_decision" blocks until the supervisor (parent agent) replies; ' +
-      '"progress_update" is fire-and-forget.',
+    description: PROMPTS["tools.child.contact_supervisor.param.reason"],
   }),
-  message: Type.String({ description: "Message for the supervisor." }),
+  message: Type.String({ description: PROMPTS["tools.child.contact_supervisor.param.message"] }),
 });
 
 export interface ContactSupervisorDetails {
@@ -45,13 +44,8 @@ export function createContactSupervisorTool(
   return {
     name: "contact_supervisor",
     label: "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.',
-    promptSnippet: "Ask the parent agent for a decision or report progress",
+    description: PROMPTS["tools.child.contact_supervisor.description"],
+    promptSnippet: PROMPTS["tools.child.contact_supervisor.snippet"],
     parameters: contactSupervisorParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       try {
@@ -79,24 +73,18 @@ const agentMessageParameters = Type.Object({
   action: Type.Union(
     [Type.Literal("send"), Type.Literal("reply"), Type.Literal("broadcast"), Type.Literal("list")],
     {
-      description:
-        '"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.',
+      description: PROMPTS["tools.agent_message.param.action"],
     },
   ),
   to: Type.Optional(
     Type.String({
-      description:
-        '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.",
+      description: PROMPTS["tools.agent_message.param.to"],
     }),
   ),
-  message: Type.Optional(Type.String({ description: "Message text." })),
+  message: Type.Optional(Type.String({ description: PROMPTS["tools.agent_message.param.message"] })),
   delivery: Type.Optional(
     Type.Union([Type.Literal("steer"), Type.Literal("queue")], {
-      description:
-        '"steer" (default) injects into a running child immediately; "queue" delivers after ' +
-        'its current turn. Sending to a finished child is an error — resume with subagent({action:"resume"}).',
+      description: PROMPTS["tools.agent_message.param.delivery"],
     }),
   ),
 });
@@ -209,21 +197,8 @@ export function createAgentMessageTool(
   return {
     name: "agent_message",
     label: "Agent Message",
-    description: isChild
-      ? "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."
-      : "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.",
-    promptSnippet: isChild
-      ? "Message sibling subagents in your run"
-      : "Send/reply/broadcast messages to subagents",
+    description: isChild ? PROMPTS["tools.child.agent_message.description"] : PROMPTS["tools.agent_message.description"],
+    promptSnippet: isChild ? PROMPTS["tools.child.agent_message.snippet"] : PROMPTS["tools.agent_message.snippet"],
     parameters: agentMessageParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const action = params.action;

package/src/config.ts

@@ -25,8 +25,15 @@ export interface FamulusConfig {
 export interface FamulusSubagentConfig {
   /** Sync-wait budget before a run is moved to background (ms). Overrides top-level subagentBudgetMs. */
   budgetMs?: number;
-  /** Default per-child hard timeout (ms). */
+  /**
+   * Default per-child soft budget per turn (ms). Reaching it wakes the parent
+   * (subagent-overrun); the child keeps running.
+   */
   timeoutMs?: number;
+  /** Repeat interval of the overrun wake while a child stays past its budget (ms). Default 10 min. */
+  overrunRepeatMs?: number;
+  /** Opt-in ceiling per turn that aborts the child (ms). 0 or absent = off (default). */
+  hardTimeoutMs?: number;
   /** Stall watchdog: abort a child with no events for this long (ms). Paused during tools and need_decision. */
   stallMs?: number;
   /** Auto-resume attempts after a stall before the run settles failed (stalled). Default 1. */
@@ -47,6 +54,9 @@ export interface FamulusSubagentConfig {
 export interface ResolvedSubagentConfig {
   budgetMs: number;
   timeoutMs: number;
+  overrunRepeatMs: number;
+  /** 0 = no hard ceiling. */
+  hardTimeoutMs: number;
   stallMs: number;
   stallRetries: number;
   stallRetryDelayMs: number;
@@ -69,6 +79,8 @@ function capTimerDelay(value: number): number {
 export const DEFAULT_SUBAGENT_CONFIG: ResolvedSubagentConfig = {
   budgetMs: 45000,
   timeoutMs: 1_800_000,
+  overrunRepeatMs: 600_000,
+  hardTimeoutMs: 0,
   stallMs: 300_000,
   stallRetries: 1,
   stallRetryDelayMs: 5_000,
@@ -85,6 +97,12 @@ export function resolveSubagentConfig(config: FamulusConfig): ResolvedSubagentCo
   resolved.budgetMs = config.subagentBudgetMs > 0 ? config.subagentBudgetMs : resolved.budgetMs;
   if (typeof section.budgetMs === "number" && section.budgetMs > 0) resolved.budgetMs = section.budgetMs;
   if (typeof section.timeoutMs === "number" && section.timeoutMs > 0) resolved.timeoutMs = section.timeoutMs;
+  if (typeof section.overrunRepeatMs === "number" && section.overrunRepeatMs > 0) {
+    resolved.overrunRepeatMs = capTimerDelay(section.overrunRepeatMs);
+  }
+  if (typeof section.hardTimeoutMs === "number" && section.hardTimeoutMs >= 0) {
+    resolved.hardTimeoutMs = capTimerDelay(section.hardTimeoutMs);
+  }
   if (typeof section.stallMs === "number" && section.stallMs > 0) {
     resolved.stallMs = capTimerDelay(section.stallMs);
   }
@@ -175,6 +193,12 @@ export function loadConfig(home: string = getFamulusHome()): FamulusConfig {
     const subagent: FamulusSubagentConfig = {};
     if (typeof section.budgetMs === "number" && section.budgetMs > 0) subagent.budgetMs = section.budgetMs;
     if (typeof section.timeoutMs === "number" && section.timeoutMs > 0) subagent.timeoutMs = section.timeoutMs;
+    if (typeof section.overrunRepeatMs === "number" && section.overrunRepeatMs > 0) {
+      subagent.overrunRepeatMs = capTimerDelay(section.overrunRepeatMs);
+    }
+    if (typeof section.hardTimeoutMs === "number" && section.hardTimeoutMs >= 0) {
+      subagent.hardTimeoutMs = capTimerDelay(section.hardTimeoutMs);
+    }
     if (typeof section.stallMs === "number" && section.stallMs > 0) {
       subagent.stallMs = capTimerDelay(section.stallMs);
     }

package/src/format.ts

@@ -4,7 +4,17 @@
  * These functions are the shared contract between implementation and tests.
  * Signatures must match Appendix A exactly.
  */
-import { formatFamulusWake, shellWakeTitle, type FormattedWake, type WakeItem } from "./wake";
+import {
+  formatFamulusWake,
+  shellWakeTitle,
+  type FamulusWake,
+  wakeDuration,
+  type FormattedWake,
+  type OverrunShell,
+  type SubagentOverrunChild,
+  type WakeItem,
+} from "./wake";
+import { fill } from "./prompts.generated";
 
 export { FAMULUS_WAKE_LEAD_IN } from "./wake";
 export type { FormattedWake, WakeItem } from "./wake";
@@ -142,10 +152,7 @@ export function formatBackgroundNotice(
   outputPath: string,
 ): string {
   // Model-facing. The transcript row is drawn by the bash tool's renderResult.
-  return [
-    `Command "${displayCommand(command)}" moved to background (task_id: ${taskId}). Output: ${outputPath}.`,
-    'You 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.',
-  ].join("\n");
+  return fill("tools.bash.result.backgrounded", { command: displayCommand(command), taskId, outputPath });
 }
 
 /** Transcript row for a backgrounded command (UI only; never sent to the model). */
@@ -195,6 +202,8 @@ export interface SubagentChildInfo {
   status: "pending" | "running" | "completed" | "failed" | "interrupted";
   text: string;
   error?: string;
+  /** Non-fatal caveat from the child run (e.g. an adapted model spec). */
+  warning?: string;
   /** Task prompt that was sent to this child. */
   prompt?: string;
 }
@@ -230,6 +239,7 @@ export interface SubagentHandoverInfo {
   prompt: string;
   text: string;
   error?: string;
+  warning?: string;
   /** Children that are still pending or running. Title is the agent name. */
   stillRunning: WakeItem[];
 }
@@ -251,6 +261,7 @@ export function formatSubagentNotification(info: SubagentNotificationInfo): Form
       prompt: capPrompt(child.prompt ?? ""),
       result: capTail(child.text),
       ...(child.error ? { error: child.error } : {}),
+      ...(child.warning ? { warning: child.warning } : {}),
     })),
   });
 }
@@ -272,5 +283,72 @@ export function formatSubagentHandover(info: SubagentHandoverInfo): FormattedWak
     prompt: capPrompt(info.prompt),
     result: capTail(info.text),
     ...(info.error ? { error: info.error } : {}),
+    ...(info.warning ? { warning: info.warning } : {}),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Soft deadline: a running child passed its budget (design doc §4.6 lifecycle)
+// ---------------------------------------------------------------------------
+
+export interface SubagentOverrunInfo {
+  runId: string;
+  childId: string;
+  name: string;
+  elapsedMs: number;
+  budgetMs: number;
+  reminder: number;
+  nextReminderMs: number;
+  /** Time left until the opt-in hard ceiling aborts the child. Absent when none is set. */
+  hardCeilingMs?: number;
+  lastActivity: { agoMs: number; text: string };
+  shell?: OverrunShell;
+}
+
+/** Last-activity text cap: enough to see what the child was doing. */
+const OVERRUN_ACTIVITY_CHARS = 300;
+
+/**
+ * A child is past its soft budget and still running. The parent decides:
+ * extend, steer, or interrupt; doing nothing leaves it running.
+ */
+function formatOverrunChild(info: SubagentOverrunInfo): SubagentOverrunChild {
+  const oneLine = info.lastActivity.text.replace(/\s+/g, " ").trim();
+  const text = oneLine.length > OVERRUN_ACTIVITY_CHARS ? `…${oneLine.slice(-OVERRUN_ACTIVITY_CHARS)}` : oneLine;
+  return {
+    runId: info.runId,
+    childId: info.childId,
+    name: info.name,
+    elapsedMs: info.elapsedMs,
+    budgetMs: info.budgetMs,
+    reminder: info.reminder,
+    nextReminderMs: info.nextReminderMs,
+    ...(info.hardCeilingMs !== undefined ? { hardCeilingMs: info.hardCeilingMs } : {}),
+    lastActivity: { agoMs: info.lastActivity.agoMs, text: text || "(no output yet)" },
+    ...(info.shell ? { shell: { ...info.shell, command: shellWakeTitle(info.shell.command) } } : {}),
+  };
+}
+
+function formatSubagentOverrunDetails(info: SubagentOverrunInfo): Extract<FamulusWake, { kind: "subagent-overrun" }> {
+  const child = formatOverrunChild(info);
+  const shell = child.shell ? fill("wakes.overrun.summary-shell", { elapsed: wakeDuration(child.shell.elapsedMs) }) : "";
+  const summary = fill("wakes.overrun.summary", {
+    name: child.name,
+    elapsed: wakeDuration(child.elapsedMs),
+    budget: wakeDuration(child.budgetMs),
+    shell,
+  });
+  return { kind: "subagent-overrun", ...child, summary };
+}
+
+export function formatSubagentOverrun(info: SubagentOverrunInfo): FormattedWake {
+  return formatFamulusWake(formatSubagentOverrunDetails(info));
+}
+
+export function formatSubagentOverrunBatch(infos: SubagentOverrunInfo[]): FormattedWake {
+  if (infos.length === 1) return formatSubagentOverrun(infos[0]);
+  return formatFamulusWake({
+    ...formatSubagentOverrunDetails(infos[0]),
+    additional: infos.slice(1).map(formatOverrunChild),
   });
 }