pi-famulus 0.1.2 → 0.1.3

package/src/subagent/types.ts

@@ -16,7 +16,9 @@ export interface AgentDefinition {
   description: string; // required, non-empty
   tools: string[]; // default ["read","bash","edit","write"]
   model?: string; // "provider:id" | bare id
-  thinking?: "minimal" | "low" | "medium" | "high" | "xhigh";
+  // Mirror of src/agents/definition.ts — keep in sync with
+  // src/thinking-levels.ts (VALID_THINKING_LEVELS), the single source.
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
   systemPrompt: string; // frontmatter body, trimmed
   source: "builtin" | "user" | "project";
   path?: string; // builtins have no path
@@ -58,6 +60,7 @@ export interface ChildRunRequest {
   taskPrompt?: string;
   agent: AgentDefinition; // already resolved
   model?: string; // subagent() parameter-level override
+  /** Soft budget per turn: reaching it wakes the parent; it does not abort. */
   timeoutMs: number;
   depth: number; // main session = 0, child = 1
 }
@@ -70,7 +73,13 @@ export interface ChildHandle {
   // current generation's promise).
   steer(message: string): Promise<void>; // while running; terminal -> throw
   followUp(message: string): Promise<void>; // same, queued delivery
-  resume(message: string): Promise<void>; // terminal -> continue running
+  /** terminal -> continue running; opts.timeoutMs is the new turn's soft budget (default: spawn budget). */
+  resume(message: string, opts?: { timeoutMs?: number }): Promise<void>;
+  /**
+   * running -> soft deadline = now + timeoutMs (default: spawn budget);
+   * otherwise throws. Returns the new deadline and the unmoved hard ceiling.
+   */
+  extend(timeoutMs?: number): { deadlineAt: number; hardDeadlineAt: number | null };
   interrupt(): Promise<void>; // abort; result resolves as interrupted
   status(): ChildStatus;
   lastEventAt(): number; // for the stall watchdog / status display

package/src/thinking-levels.ts

@@ -0,0 +1,26 @@
+/**
+ * Thinking levels pi core accepts — the single source of truth for the
+ * extension. The pi SDK does not export its list (pi's internal
+ * VALID_THINKING_LEVELS), so this is a maintained copy; parity tests pin
+ * every level (impl-model-spec.test.ts, impl-agents.test.ts).
+ *
+ * Pure module: zero pi dependencies, zero npm dependencies. Both src/agents/
+ * and src/subagent/ consume this — neither layer imports the other (see
+ * design doc Appendix B).
+ */
+
+export const VALID_THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+
+export type ThinkingLevel = (typeof VALID_THINKING_LEVELS)[number];
+
+export function isValidThinkingLevel(level: string): level is ThinkingLevel {
+  return (VALID_THINKING_LEVELS as readonly string[]).includes(level);
+}

package/src/tui/message-renderers.ts

@@ -98,6 +98,12 @@ function collapsedText(details: FamulusWake, theme: Theme): string {
       const { color, glyph } = statusGlyph(bad ? "failed" : details.status);
       return `${theme.fg(color, glyph)} ${theme.fg("muted", "subagent")} ${countStatuses(details.children.map((child) => child.status))}`;
     }
+    case "subagent-overrun": {
+      const shell = details.shell
+        ? ` · shell ${formatDuration(details.shell.elapsedMs)}${details.shell.growing === null ? "" : details.shell.growing ? " (output growing)" : " (output idle)"}`
+        : "";
+      return `${theme.fg("warning", "!")} ${theme.fg("muted", "overrun")} ${details.name} ${formatDuration(details.elapsedMs)} / ${formatDuration(details.budgetMs)} budget · still running${shell}`;
+    }
     case "supervisor-request":
       return [
         `${theme.fg("warning", "?")} ${theme.fg("muted", `decision for ${details.name}`)} ${details.message.slice(0, 100)}`,
@@ -133,9 +139,37 @@ export function expandedWakeText(details: FamulusWake | undefined, content: stri
     case "monitor":
       return [`Monitor: ${details.description}`, `Task: ${details.id}`, ...(details.status ? [`Status: ${details.status}`] : []), `Event: ${details.event}`, ...(details.eventCount ? [`Events: ${details.eventCount}`] : []), ...(details.droppedLines ? [`Dropped lines: ${details.droppedLines}`] : [])].join("\n");
     case "subagent-handover":
-      return [`Subagent handover: ${details.name} (${details.status})`, `Run: ${details.runId}`, `Child: ${details.childId}`, `Task prompt: ${details.prompt}`, `Result: ${details.result}`, ...(details.error ? [`Error: ${details.error}`] : []), ...(details.stillRunning.length ? [`Still running: ${details.stillRunning.map((item) => `${item.id} ${item.title}`).join(", ")}`] : [])].join("\n\n");
+      return [`Subagent handover: ${details.name} (${details.status})`, `Run: ${details.runId}`, `Child: ${details.childId}`, `Task prompt: ${details.prompt}`, `Result: ${details.result}`, ...(details.error ? [`Error: ${details.error}`] : []), ...(details.warning ? [`Warning: ${details.warning}`] : []), ...(details.stillRunning.length ? [`Still running: ${details.stillRunning.map((item) => `${item.id} ${item.title}`).join(", ")}`] : [])].join("\n\n");
     case "subagent-done":
-      return [`Subagent run: ${details.runId} (${details.status})`, `Duration: ${formatDuration(details.durationMs)}`, ...details.children.map((child) => [`${child.name} (${child.childId}) · ${child.status}`, `Task prompt: ${child.prompt}`, `Result: ${child.result}`, ...(child.error ? [`Error: ${child.error}`] : [])].join("\n"))].join("\n\n");
+      return [`Subagent run: ${details.runId} (${details.status})`, `Duration: ${formatDuration(details.durationMs)}`, ...details.children.map((child) => [`${child.name} (${child.childId}) · ${child.status}`, `Task prompt: ${child.prompt}`, `Result: ${child.result}`, ...(child.error ? [`Error: ${child.error}`] : []), ...(child.warning ? [`Warning: ${child.warning}`] : [])].join("\n"))].join("\n\n");
+    case "subagent-overrun": {
+      const shell = details.shell;
+      return [
+        `Subagent past its budget: ${details.name} (still running, reminder ${details.reminder})`,
+        `Run: ${details.runId}`,
+        `Child: ${details.childId}`,
+        `Elapsed this turn: ${formatDuration(details.elapsedMs)} of ${formatDuration(details.budgetMs)}`,
+        `Last activity (${formatDuration(details.lastActivity.agoMs)} ago): ${details.lastActivity.text}`,
+        ...(shell
+          ? [
+              [
+                `Shell ${shell.taskId} · ${formatDuration(shell.elapsedMs)}`,
+                `$ ${shell.command}`,
+                `Output: ${shell.outputPath}${shell.outputBytes !== null ? ` (${shell.outputBytes} bytes)` : ""}`,
+                ...(shell.outputIdleMs !== null ? [`Last output: ${formatDuration(shell.outputIdleMs)} ago`] : []),
+              ].join("\n"),
+            ]
+          : []),
+        ...(details.hardCeilingMs !== undefined
+          ? [`Hard ceiling stops it in ${formatDuration(details.hardCeilingMs)} (extend does not move it).`]
+          : []),
+        // Same condition as overrunOptions in wake.ts: do not promise a
+        // reminder that the hard ceiling will stop the child before.
+        ...(details.hardCeilingMs === undefined || details.nextReminderMs < details.hardCeilingMs
+          ? [`Next reminder in ${formatDuration(details.nextReminderMs)} unless you extend, steer, or interrupt it.`]
+          : []),
+      ].join("\n\n");
+    }
     case "supervisor-request":
       return [`Decision requested by ${details.name} (${details.from})`, `Request: ${details.message}`, `Reply with /reply ${details.from} <decision>`].join("\n");
     case "supervisor-update":

package/src/wake-delivery.ts

@@ -0,0 +1,137 @@
+/**
+ * The moment a wake enters the model's context (design.md §4.5).
+ *
+ * NotifyCenter hands a wake to pi.sendMessage; pi may hold it for minutes
+ * (a steer waits for the current tool calls and turn to end). pi emits the
+ * extension `message_end` event for a custom message right before it is
+ * pushed into the agent's context: in agent-core's loop for steered
+ * messages, and in the prompt for a triggerTurn message. That is where the
+ * real delivery is logged (`wake.inject`).
+ *
+ * Passive wakes (`triggerTurn: false`) never reach extension `message_end`:
+ * pi appends them through a path that only notifies its own listeners. The
+ * NotifyCenter sends them only when the agent is idle, so they are appended
+ * at send time and `wake.deliver mode=passive` is the proxy for them.
+ *
+ * Zero pi dependency: the handler takes the message object pi passes.
+ */
+import {
+  FAMULUS_WAKE_CUSTOM_TYPE,
+  renderWakeXml,
+  wakeIds,
+  wakeRootIndex,
+  type FamulusWake,
+  type WakeChildStatus,
+} from "./wake";
+import type { RunRegistry } from "./subagent/registry";
+
+export interface WakeDeliveryDeps {
+  now: () => number;
+  logEvent?: (type: string, fields?: Record<string, unknown>) => void;
+  /** Current subagent statuses; null/absent when no registry is live. */
+  lookup?: () => WakeStatusLookup | null;
+}
+
+interface CustomMessageLike {
+  role?: string;
+  customType?: string;
+  content?: unknown;
+  details?: unknown;
+}
+
+/** The wake's details when `message` is a pi-famulus-wake custom message. */
+export function famulusWakeDetails(message: unknown): FamulusWake | undefined {
+  const m = message as CustomMessageLike | null | undefined;
+  if (!m || m.role !== "custom" || m.customType !== FAMULUS_WAKE_CUSTOM_TYPE) return undefined;
+  const details = m.details as FamulusWake | undefined;
+  return details && typeof details === "object" && typeof details.kind === "string" ? details : undefined;
+}
+
+/** Current statuses, read from the subagent registry at injection. */
+export interface WakeStatusLookup {
+  childStatus: (runId: string, childId: string) => WakeChildStatus | undefined;
+  runStatus: (runId: string) => string | undefined;
+}
+
+/** Lookup over the run records of a subagent registry. */
+export function registryStatusLookup(registry: Pick<RunRegistry, "get">): WakeStatusLookup {
+  return {
+    childStatus: (runId, childId) => registry.get(runId)?.children.find((c) => c.childId === childId)?.status,
+    runStatus: (runId) => registry.get(runId)?.status,
+  };
+}
+
+/**
+ * Subagent wakes are snapshots. Re-check each child's status against the
+ * registry: a changed child shows its current status, with the snapshot's
+ * status kept as statusAsOf (rendered status-as-of, plus a
+ * <changed-since-as-of> line). Policy: mark, never drop: the snapshot's
+ * results stay useful (design.md §4.5).
+ */
+function recheckStatuses(details: FamulusWake, lookup: WakeStatusLookup): FamulusWake {
+  if (details.kind === "subagent-handover") {
+    const now = lookup.childStatus(details.runId, details.childId);
+    if (now === undefined || now === details.status) return details;
+    return { ...details, status: now, statusAsOf: details.status };
+  }
+  if (details.kind === "subagent-done") {
+    let changed = false;
+    const children = details.children.map((child) => {
+      const now = lookup.childStatus(details.runId, child.childId);
+      if (now === undefined || now === child.status) return child;
+      changed = true;
+      return { ...child, status: now, statusAsOf: child.status };
+    });
+    if (!changed) return details;
+    const runNow = lookup.runStatus(details.runId);
+    return { ...details, children, ...(runNow && runNow !== details.status ? { runStatusNow: runNow } : {}) };
+  }
+  return details;
+}
+
+/**
+ * The wake as the model should see it on entering the context: the root
+ * gains age-ms (how old its snapshot is now), and subagent statuses are
+ * re-checked when a lookup is given. Returns undefined when nothing
+ * changes: not a wake, not stamped, or content that is not the canonical
+ * rendering of its details (never rewrite text this module did not make).
+ */
+export function wakeAtInjection<M extends CustomMessageLike>(
+  message: M,
+  now: number,
+  lookup?: WakeStatusLookup,
+): M | undefined {
+  const details = famulusWakeDetails(message);
+  if (!details || details.asOf === undefined || typeof message.content !== "string") return undefined;
+  const root = wakeRootIndex(message.content);
+  if (root < 0 || message.content.slice(root) !== renderWakeXml(details)) return undefined;
+  let next: FamulusWake = { ...details, ageMs: Math.max(0, now - details.asOf) };
+  if (lookup) next = recheckStatuses(next, lookup);
+  return { ...message, content: message.content.slice(0, root) + renderWakeXml(next), details: next };
+}
+
+/**
+ * pi `message_end` handler body: log the injection and return the
+ * replacement message (same role), if any.
+ */
+export function onWakeMessageEnd<M extends CustomMessageLike>(message: M, deps: WakeDeliveryDeps): M | undefined {
+  try {
+    logWakeInjected(message, deps);
+    return wakeAtInjection(message, deps.now(), deps.lookup?.() ?? undefined);
+  } catch {
+    // Never break pi's message handling over a wake annotation.
+    return undefined;
+  }
+}
+
+/** Log `wake.inject` for a wake entering the context. Non-wake messages are ignored. */
+export function logWakeInjected(message: unknown, deps: WakeDeliveryDeps): void {
+  const details = famulusWakeDetails(message);
+  if (!details) return;
+  const now = deps.now();
+  deps.logEvent?.("wake.inject", {
+    kind: details.kind,
+    ids: wakeIds(details),
+    ...(details.asOf !== undefined ? { as_of: details.asOf, lag_ms: Math.max(0, now - details.asOf) } : {}),
+  });
+}

package/src/wake.ts

@@ -29,16 +29,56 @@ export interface TaskWake {
   signal?: string;
 }
 
+export type WakeChildStatus = "pending" | "running" | "completed" | "failed" | "interrupted";
+
 export interface SubagentDoneChild {
   childId: string;
   name: string;
-  status: "pending" | "running" | "completed" | "failed" | "interrupted";
+  /** Status when the model sees the wake (re-checked at injection). */
+  status: WakeChildStatus;
+  /** Set when the status changed after as-of: the status in the snapshot. */
+  statusAsOf?: WakeChildStatus;
   prompt: string;
   result: string;
   error?: string;
+  /** Non-fatal caveat from the child run (e.g. an adapted model spec). */
+  warning?: string;
+}
+
+/** The foreground shell a child is blocked on when its overrun wake is built. */
+export interface OverrunShell {
+  taskId: string;
+  /** One line, capped (shellWakeTitle). */
+  command: string;
+  elapsedMs: number;
+  outputPath: string;
+  /** Output file size; null when the file could not be read. */
+  outputBytes: number | null;
+  /** Time since the output file last changed; null when unknown. */
+  outputIdleMs: number | null;
+  /** Output grew since the previous reminder, or changed in the last minute; null when unknown. */
+  growing: boolean | null;
 }
 
-export type FamulusWake =
+/**
+ * When the wake's content was generated (design.md §4.5): stamped by the
+ * NotifyCenter when it receives or builds the wake. A steered wake can wait
+ * minutes before the model sees it; the model needs to know how old the
+ * snapshot is.
+ */
+export interface WakeTiming {
+  /** Epoch ms. Rendered as the root attribute as-of (UTC, seconds). */
+  asOf?: number;
+  /**
+   * How old the wake was when it entered the model's context (ms). Set at
+   * injection (wake-delivery.ts), rendered as the root attribute age-ms.
+   */
+  ageMs?: number;
+}
+
+export type FamulusWake = FamulusWakeBody & WakeTiming;
+
+type FamulusWakeBody =
   | { kind: "task"; stillRunning: WakeItem[]; tasks: TaskWake[] }
   | {
       kind: "monitor";
@@ -54,21 +94,46 @@ export type FamulusWake =
       runId: string;
       childId: string;
       name: string;
-      status: "completed" | "failed" | "interrupted";
+      /** The settle this wake reports; pending/running only when re-checked at injection. */
+      status: WakeChildStatus;
+      /** Set when the status changed after as-of: the status in the snapshot. */
+      statusAsOf?: WakeChildStatus;
       stillRunning: WakeItem[];
       summary: string;
       prompt: string;
       result: string;
       error?: string;
+      warning?: string;
     }
   | {
       kind: "subagent-done";
       runId: string;
       status: "completed" | "partial" | "failed" | "interrupted";
+      /** Set at injection when a child is pending or running again: the run's status then. */
+      runStatusNow?: string;
       durationMs: number;
       summary: string;
       children: SubagentDoneChild[];
     }
+  | {
+      kind: "subagent-overrun";
+      runId: string;
+      childId: string;
+      name: string;
+      /** Time in this user turn (since admission of the launch or resume). */
+      elapsedMs: number;
+      /** The turn's soft budget (timeout_ms), extensions included. */
+      budgetMs: number;
+      /** 1 for the first wake of this turn, then 2, 3, … */
+      reminder: number;
+      /** When the next reminder is due if the parent does nothing. */
+      nextReminderMs: number;
+      /** Time left until the opt-in hard ceiling aborts the child; absent when none is set. */
+      hardCeilingMs?: number;
+      summary: string;
+      lastActivity: { agoMs: number; text: string };
+      shell?: OverrunShell;
+    }
   | { kind: "supervisor-request"; from: string; name: string; message: string }
   | { kind: "supervisor-update"; from: string; name: string; message: string };
 
@@ -99,7 +164,79 @@ export function formatFamulusWake(details: FamulusWake, leadIn: string = FAMULUS
   return { customType: FAMULUS_WAKE_CUSTOM_TYPE, content, details };
 }
 
+/** Task/child/monitor ids a wake is about (event log `ids`). */
+export function wakeIds(details: { kind?: string }): string[] {
+  const d = details as {
+    kind?: string;
+    id?: string;
+    taskId?: string;
+    tasks?: { id: string }[];
+    children?: { childId: string }[];
+    childId?: string;
+    from?: string;
+  };
+  if (d.kind === "task") return (d.tasks ?? []).map((task) => task.id);
+  if (d.kind === "subagent-done") return (d.children ?? []).map((child) => child.childId);
+  return [d.id ?? d.taskId ?? d.childId ?? d.from].filter((id): id is string => Boolean(id));
+}
+
+/** UTC, second precision: the model needs how old a snapshot is, not milliseconds. */
+export function wakeTimestamp(ms: number): string {
+  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/** Append attributes to the root <pi-famulus-wake …> tag of rendered content. */
+function addRootAttrs(content: string, attrs: string[]): string {
+  if (attrs.length === 0) return content;
+  // `\s`: the lead-in mentions a bare <pi-famulus-wake>; the root tag has attributes.
+  const root = /<pi-famulus-wake\s[^>]*>/.exec(content);
+  if (!root) return content;
+  const end = root.index + root[0].length - 1;
+  return `${content.slice(0, end)} ${attrs.join(" ")}${content.slice(end)}`;
+}
+
+function timingAttrs(details: WakeTiming): string[] {
+  const attrs: string[] = [];
+  if (details.asOf !== undefined) attrs.push(`as-of="${wakeTimestamp(details.asOf)}"`);
+  if (details.ageMs !== undefined) attrs.push(`age-ms="${Math.round(details.ageMs)}"`);
+  return attrs;
+}
+
+/** The <pi-famulus-wake> element for `details` (no lead-in). */
+export function renderWakeXml(details: FamulusWake): string {
+  return renderWake(details);
+}
+
+/** Index of the root <pi-famulus-wake …> tag in content, or -1. */
+export function wakeRootIndex(content: string): number {
+  return content.search(/<pi-famulus-wake\s/);
+}
+
+/**
+ * Stamp a wake with the time it was generated. Leaves non-wake messages and
+ * already-stamped wakes alone, so a wake held for later delivery keeps the
+ * time it was built.
+ */
+export function stampWakeAsOf<M extends { customType: string; content: string; details?: unknown }>(
+  message: M,
+  asOf: number,
+): M {
+  if (message.customType !== FAMULUS_WAKE_CUSTOM_TYPE) return message;
+  const details = message.details as (WakeTiming & { kind?: string }) | undefined;
+  if (!details || typeof details !== "object" || !details.kind || details.asOf !== undefined) return message;
+  const stamped = { ...details, asOf };
+  const content = addRootAttrs(message.content, timingAttrs(stamped));
+  // addRootAttrs is a no-op when the root tag is missing; keep details in
+  // sync with content so wakeAtInjection does not reject a phantom stamp.
+  if (content === message.content) return message;
+  return { ...message, content, details: stamped };
+}
+
 function renderWake(details: FamulusWake): string {
+  return addRootAttrs(renderWakeBody(details), timingAttrs(details));
+}
+
+function renderWakeBody(details: FamulusWake): string {
   switch (details.kind) {
     case "task":
       return renderTask(details);
@@ -109,6 +246,8 @@ function renderWake(details: FamulusWake): string {
       return renderHandover(details);
     case "subagent-done":
       return renderDone(details);
+    case "subagent-overrun":
+      return renderOverrun(details);
     case "supervisor-request":
       return renderRequest(details);
     case "supervisor-update":
@@ -168,12 +307,23 @@ function renderHandover(details: Extract<FamulusWake, { kind: "subagent-handover
     `name="${escapeXmlAttr(details.name)}"`,
     `status="${escapeXmlAttr(details.status)}"`,
   ];
+  if (details.statusAsOf) attrs.push(`status-as-of="${escapeXmlAttr(details.statusAsOf)}"`);
   const parts = [`<pi-famulus-wake ${attrs.join(" ")}>`];
   const still = stillRunningXml(details.stillRunning);
   if (still) parts.push(still);
   parts.push(`  <summary>${escapeXml(details.summary)}</summary>`);
+  if (details.statusAsOf) {
+    const active = details.status === "pending" || details.status === "running";
+    parts.push(
+      `  <changed-since-as-of>${escapeXml(
+        `${details.name} (${details.childId}): ${details.statusAsOf} → ${details.status}.` +
+          (active ? " Its result arrives as a new wake when it finishes." : ""),
+      )}</changed-since-as-of>`,
+    );
+  }
   parts.push(`  <prompt>${escapeXml(details.prompt)}</prompt>`);
   if (details.error) parts.push(`  <error>${escapeXml(details.error)}</error>`);
+  if (details.warning) parts.push(`  <warning>${escapeXml(details.warning)}</warning>`);
   parts.push(`  <result>${escapeXml(details.result)}</result>`);
   parts.push("</pi-famulus-wake>");
   return parts.join("\n");
@@ -186,13 +336,26 @@ function renderDone(details: Extract<FamulusWake, { kind: "subagent-done" }>): s
     `status="${escapeXmlAttr(details.status)}"`,
     `duration-ms="${Math.round(details.durationMs)}"`,
   ];
+  if (details.runStatusNow) attrs.push(`status-now="${escapeXmlAttr(details.runStatusNow)}"`);
   const parts = [`<pi-famulus-wake ${attrs.join(" ")}>`, `  <summary>${escapeXml(details.summary)}</summary>`];
+  const changed = details.children.filter((child) => child.statusAsOf !== undefined);
+  if (changed.length > 0) {
+    const list = changed.map((c) => `${c.name} (${c.childId}): ${c.statusAsOf} → ${c.status}`).join("; ");
+    const active = details.children.some((c) => c.status === "pending" || c.status === "running");
+    parts.push(
+      `  <changed-since-as-of>${escapeXml(
+        `${list}.` + (active ? " The run is active again; another subagent-done arrives when it finishes." : ""),
+      )}</changed-since-as-of>`,
+    );
+  }
   for (const child of details.children) {
+    const asOf = child.statusAsOf ? ` status-as-of="${escapeXmlAttr(child.statusAsOf)}"` : "";
     parts.push(
-      `  <child id="${escapeXmlAttr(child.childId)}" name="${escapeXmlAttr(child.name)}" status="${escapeXmlAttr(child.status)}">`,
+      `  <child id="${escapeXmlAttr(child.childId)}" name="${escapeXmlAttr(child.name)}" status="${escapeXmlAttr(child.status)}"${asOf}>`,
     );
     parts.push(`    <prompt>${escapeXml(child.prompt)}</prompt>`);
     if (child.error) parts.push(`    <error>${escapeXml(child.error)}</error>`);
+    if (child.warning) parts.push(`    <warning>${escapeXml(child.warning)}</warning>`);
     parts.push(`    <result>${escapeXml(child.result)}</result>`);
     parts.push("  </child>");
   }
@@ -200,6 +363,77 @@ function renderDone(details: Extract<FamulusWake, { kind: "subagent-done" }>): s
   return parts.join("\n");
 }
 
+/** Coarse human duration for model-facing text: "45s", "12m", "1h05m". */
+export function wakeDuration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m`;
+  return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+}
+
+function renderOverrun(details: Extract<FamulusWake, { kind: "subagent-overrun" }>): string {
+  const attrs = [
+    'kind="subagent-overrun"',
+    `run-id="${escapeXmlAttr(details.runId)}"`,
+    `child-id="${escapeXmlAttr(details.childId)}"`,
+    `name="${escapeXmlAttr(details.name)}"`,
+    `elapsed-ms="${Math.round(details.elapsedMs)}"`,
+    `budget-ms="${Math.round(details.budgetMs)}"`,
+    `reminder="${details.reminder}"`,
+  ];
+  if (details.hardCeilingMs !== undefined) attrs.push(`hard-ceiling-ms="${Math.round(details.hardCeilingMs)}"`);
+  const parts = [`<pi-famulus-wake ${attrs.join(" ")}>`, `  <summary>${escapeXml(details.summary)}</summary>`];
+  parts.push(
+    `  <last-activity ago-ms="${Math.round(details.lastActivity.agoMs)}">${escapeXml(details.lastActivity.text)}</last-activity>`,
+  );
+  const shell = details.shell;
+  if (shell) {
+    const shellAttrs = [`task-id="${escapeXmlAttr(shell.taskId)}"`, `elapsed-ms="${Math.round(shell.elapsedMs)}"`];
+    if (shell.outputBytes !== null) shellAttrs.push(`output-bytes="${shell.outputBytes}"`);
+    if (shell.outputIdleMs !== null) shellAttrs.push(`output-idle-ms="${Math.round(shell.outputIdleMs)}"`);
+    if (shell.growing !== null) shellAttrs.push(`growing="${shell.growing ? "yes" : "no"}"`);
+    parts.push(`  <shell ${shellAttrs.join(" ")}>`);
+    parts.push(`    <command>${escapeXml(shell.command)}</command>`);
+    parts.push(`    <output-file>${escapeXml(shell.outputPath)}</output-file>`);
+    parts.push("  </shell>");
+  }
+  parts.push(`  <options>${escapeXml(overrunOptions(details))}</options>`);
+  parts.push("</pi-famulus-wake>");
+  return parts.join("\n");
+}
+
+/** The parent's three actions and what happens if it takes none. */
+function overrunOptions(details: Extract<FamulusWake, { kind: "subagent-overrun" }>): string {
+  const ids = `run_id: "${details.runId}", child_id: "${details.childId}"`;
+  const actions =
+    `give it more time with subagent({ action: "extend", ${ids}, timeout_ms: <ms from now> }); ` +
+    `redirect it with agent_message({ action: "send", to: "${details.childId}", message: "<instruction>" }); ` +
+    `or stop it with subagent({ action: "interrupt", ${ids} }). `;
+  const hard = details.hardCeilingMs;
+  if (hard === undefined) {
+    return (
+      "It has not been stopped. Choose one: " +
+      actions +
+      `If you do none of these, it keeps running and the next reminder is scheduled in ${wakeDuration(details.nextReminderMs)}; ` +
+      "its result arrives as usual when it finishes."
+    );
+  }
+  // Opt-in hard ceiling: never promise "keeps running" past it.
+  const ceiling = wakeDuration(hard);
+  const noAction =
+    details.nextReminderMs < hard
+      ? `If you do none of these, it keeps running and the next reminder is scheduled in ${wakeDuration(details.nextReminderMs)}, until the hard ceiling stops it in ${ceiling}.`
+      : "If you do none of these, it keeps running until the hard ceiling stops it.";
+  return (
+    `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."
+  );
+}
+
 function renderRequest(details: Extract<FamulusWake, { kind: "supervisor-request" }>): string {
   const recipe = `agent_message { action: "reply", to: "${details.from}", message: "<your decision>" }`;
   return [