pi-famulus 0.1.2 → 0.1.4

package/src/tui/message-renderers.ts

@@ -98,6 +98,13 @@ 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)"}`
+        : "";
+      const additional = details.additional?.length ? ` · +${details.additional.length} more overdue` : "";
+      return `${theme.fg("warning", "!")} ${theme.fg("muted", "overrun")} ${details.name} ${formatDuration(details.elapsedMs)} / ${formatDuration(details.budgetMs)} budget · still running${additional}${shell}`;
+    }
     case "supervisor-request":
       return [
         `${theme.fg("warning", "?")} ${theme.fg("muted", `decision for ${details.name}`)} ${details.message.slice(0, 100)}`,
@@ -133,9 +140,52 @@ 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.`]
+          : []),
+        ...(details.additional?.length
+          ? [
+              `Also overdue (${details.additional.length}):`,
+              ...details.additional.map((child) => [
+                `${child.name} (${child.childId}) · run ${child.runId}`,
+                `Elapsed this turn: ${formatDuration(child.elapsedMs)} of ${formatDuration(child.budgetMs)}`,
+                `Last activity (${formatDuration(child.lastActivity.agoMs)} ago): ${child.lastActivity.text}`,
+                ...(child.shell ? [`Shell ${child.shell.taskId} · ${formatDuration(child.shell.elapsedMs)}\n$ ${child.shell.command}\nOutput: ${child.shell.outputPath}`] : []),
+                ...(child.hardCeilingMs !== undefined ? [`Hard ceiling stops it in ${formatDuration(child.hardCeilingMs)}.`] : []),
+                ...(child.hardCeilingMs === undefined || child.nextReminderMs < child.hardCeilingMs
+                  ? [`Next reminder in ${formatDuration(child.nextReminderMs)}.`]
+                  : []),
+              ].join("\n")),
+            ]
+          : []),
+      ].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

@@ -5,10 +5,13 @@
  * discriminator the renderer and the eval adapter both read.
  */
 
+// .ts suffix: eval/ loads this module with Node's own TypeScript support, which
+// needs explicit extensions (it imports wake.ts and behavior-guidelines.ts).
+import { fill, PROMPTS } from "./prompts.generated.ts";
+
 export const FAMULUS_WAKE_CUSTOM_TYPE = "pi-famulus-wake";
 
-export const FAMULUS_WAKE_LEAD_IN =
-  "System wake — not a new user message. Handle this <pi-famulus-wake> before other work.";
+export const FAMULUS_WAKE_LEAD_IN = PROMPTS["wakes.lead-in"];
 
 export interface WakeItem {
   id: string;
@@ -29,16 +32,71 @@ 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;
 }
 
-export type FamulusWake =
+/** 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;
+}
+
+/** Context retained for every secondary child in a batched overrun wake. */
+export interface SubagentOverrunChild {
+  runId: string;
+  childId: string;
+  name: string;
+  elapsedMs: number;
+  budgetMs: number;
+  reminder: number;
+  nextReminderMs: number;
+  /** Time left until the opt-in hard ceiling aborts this child. */
+  hardCeilingMs?: number;
+  lastActivity: { agoMs: number; text: string };
+  shell?: OverrunShell;
+}
+
+/**
+ * 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 +112,47 @@ 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;
+      additional?: SubagentOverrunChild[];
+    }
   | { kind: "supervisor-request"; from: string; name: string; message: string }
   | { kind: "supervisor-update"; from: string; name: string; message: string };
 
@@ -99,7 +183,80 @@ 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);
+  if (d.kind === "subagent-overrun") return [d.childId, ...((d as { additional?: { childId: string }[] }).additional ?? []).map((child) => child.childId)].filter((id): id is string => Boolean(id));
+  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 +266,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 +327,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 ? ` ${PROMPTS["wakes.handover.changed-active"]}` : ""),
+      )}</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 +356,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 ? ` ${PROMPTS["wakes.done.changed-active"]}` : ""),
+      )}</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,8 +383,88 @@ 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>`,
+  );
+  if (details.additional?.length) {
+    parts.push("  <also-overdue>");
+    for (const child of details.additional) {
+      const childAttrs = [
+        `run-id="${escapeXmlAttr(child.runId)}"`,
+        `child-id="${escapeXmlAttr(child.childId)}"`,
+        `name="${escapeXmlAttr(child.name)}"`,
+        `elapsed-ms="${Math.round(child.elapsedMs)}"`,
+        `budget-ms="${Math.round(child.budgetMs)}"`,
+        `reminder="${child.reminder}"`,
+        `next-reminder-ms="${Math.round(child.nextReminderMs)}"`,
+      ];
+      if (child.hardCeilingMs !== undefined) childAttrs.push(`hard-ceiling-ms="${Math.round(child.hardCeilingMs)}"`);
+      parts.push(`    <child ${childAttrs.join(" ")}>`);
+      parts.push(
+        `      <last-activity ago-ms="${Math.round(child.lastActivity.agoMs)}">${escapeXml(child.lastActivity.text)}</last-activity>`,
+      );
+      if (child.shell) parts.push(...renderOverrunShell(child.shell, "      "));
+      parts.push("    </child>");
+    }
+    parts.push("  </also-overdue>");
+  }
+  if (details.shell) parts.push(...renderOverrunShell(details.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 actions = fill("wakes.overrun.actions", { runId: details.runId, childId: details.childId });
+  const next = wakeDuration(details.nextReminderMs);
+  const hard = details.hardCeilingMs;
+  if (hard === undefined) return fill("wakes.overrun.options", { actions, next });
+  // Opt-in hard ceiling: never promise "keeps running" past it.
+  const ceiling = wakeDuration(hard);
+  const noAction =
+    details.nextReminderMs < hard
+      ? fill("wakes.overrun.ceiling-no-action-reminder", { next, ceiling })
+      : PROMPTS["wakes.overrun.ceiling-no-action"];
+  return fill("wakes.overrun.options-ceiling", { ceiling, actions, noAction });
+}
+
+function renderOverrunShell(shell: OverrunShell, indent: string): string[] {
+  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"}"`);
+  return [
+    `${indent}<shell ${shellAttrs.join(" ")}>`,
+    `${indent}  <command>${escapeXml(shell.command)}</command>`,
+    `${indent}  <output-file>${escapeXml(shell.outputPath)}</output-file>`,
+    `${indent}</shell>`,
+  ];
+}
+
 function renderRequest(details: Extract<FamulusWake, { kind: "supervisor-request" }>): string {
-  const recipe = `agent_message { action: "reply", to: "${details.from}", message: "<your decision>" }`;
+  const recipe = fill("wakes.request.reply-with", { from: details.from });
   return [
     `<pi-famulus-wake kind="supervisor-request" from="${escapeXmlAttr(details.from)}" name="${escapeXmlAttr(details.name)}">`,
     `  <message>${escapeXml(details.message)}</message>`,

package/src/work-index.ts

@@ -14,6 +14,10 @@ export const WORK_FINISHED_CAP = 50;
 export interface WorkItem {
   id: string;
   kind: WorkKind;
+  /** Daemon work-kind label for agents; shell commands are classified separately. */
+  workKind?: string;
+  /** Time queued for local/machine admission before the agent started. */
+  queueMs?: number;
   status: string;
   title: string;
   command?: string;