pi-famulus 0.1.1 → 0.1.3

package/src/subagent/tool.ts

@@ -15,6 +15,7 @@
  */
 import { Type } from "typebox";
 import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { VALID_THINKING_LEVELS } from "../thinking-levels";
 import { formatSubagentHandover, formatSubagentNotification, truncateTail } from "../format";
 import { realClock, type Clock, type ClockTimer } from "../clock";
 
@@ -73,13 +74,18 @@ const subagentParameters = Type.Object({
     Type.String({
       description:
         'Model override for all subagents: fuzzy ("haiku"), qualified ("provider/id"), ' +
-        'optionally with ":<thinking>" suffix. Default: current model. ' +
+        `optionally with ":<thinking>" suffix (${VALID_THINKING_LEVELS.join(", ")}; ` +
+        '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.',
     }),
   ),
   timeout_ms: Type.Optional(
     Type.Number({
-      description: `Hard timeout per subagent in ms (default 1800000, max ${MAX_TIMEOUT_MS})`,
+      description:
+        `Time budget per subagent turn in ms (default 1800000, max ${MAX_TIMEOUT_MS}). ` +
+        '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.",
       maximum: MAX_TIMEOUT_MS,
     }),
   ),
@@ -92,13 +98,16 @@ const subagentParameters = Type.Object({
         Type.Literal("interrupt"),
         Type.Literal("resume"),
         Type.Literal("steer"),
+        Type.Literal("extend"),
         Type.Literal("models"),
       ],
       { description: "Manage an existing run (or list selectable models) instead of starting a new one" },
     ),
   ),
   run_id: Type.Optional(Type.String({ description: "Target run for action" })),
-  child_id: Type.Optional(Type.String({ description: "Target child (id or name) for steer/interrupt/resume" })),
+  child_id: Type.Optional(
+    Type.String({ description: "Target child (id or name) for steer/interrupt/resume/extend" }),
+  ),
   message: Type.Optional(Type.String({ description: "Message content for steer/resume" })),
 });
 
@@ -110,7 +119,7 @@ type SubagentParams = {
   fail_fast?: boolean;
   model?: string;
   timeout_ms?: number;
-  action?: "list" | "get" | "status" | "interrupt" | "resume" | "steer" | "models";
+  action?: "list" | "get" | "status" | "interrupt" | "resume" | "steer" | "extend" | "models";
   run_id?: string;
   child_id?: string;
   message?: string;
@@ -222,6 +231,7 @@ function toNotificationInfo(record: RunRecord, now: number) {
       status: c.status,
       text: c.result?.text ?? "",
       error: c.result?.error,
+      ...(c.result?.warning !== undefined ? { warning: c.result.warning } : {}),
       ...(c.prompt !== undefined ? { prompt: c.prompt } : {}),
     })),
   };
@@ -285,9 +295,23 @@ export function createSubagentTool(
     return registry;
   };
 
+  /** Last terminal state a subagent-done was sent for, per run. */
+  const runDoneSent = new Map<string, string>();
   const notifyRunCompleted = (registry: SubagentRegistry, runId: string): void => {
     const record = registry.get(runId);
-    if (!record) return;
+    if (!record) {
+      runDoneSent.delete(runId);
+      return;
+    }
+    // A resumed child can outlive the run's first-launch completion. The
+    // run is not done while it runs; its own settle sends this wake.
+    if (record.children.some((c) => c.status === "pending" || c.status === "running")) return;
+    // Several observers (first-launch completion, each resumed turn's settle)
+    // can see the same all-terminal state. One subagent-done per terminal
+    // state, identified by every child's turn number.
+    const terminalKey = record.children.map((c) => `${c.childId}:${c.turn ?? 1}`).join("|");
+    if (runDoneSent.get(runId) === terminalKey) return;
+    runDoneSent.set(runId, terminalKey);
     deps.getNotifyCenter()?.notify(formatSubagentNotification(toNotificationInfo(record, clock.now())));
   };
 
@@ -320,6 +344,7 @@ export function createSubagentTool(
         prompt: child.prompt ?? "",
         text: child.result?.text ?? "",
         ...(child.result?.error !== undefined ? { error: child.result.error } : {}),
+        ...(child.result?.warning !== undefined ? { warning: child.result.warning } : {}),
         stillRunning,
       }),
     );
@@ -590,12 +615,41 @@ export function createSubagentTool(
       };
     }
 
+    if (action === "extend") {
+      const handle = resolveSingleActiveChild(registry, record, params.child_id, "extend");
+      const child = record.children.find((c) => c.childId === handle.childId);
+      const ms = params.timeout_ms === undefined ? undefined : clampTimeout(params.timeout_ms, deps.defaultTimeoutMs);
+      const { deadlineAt, hardDeadlineAt } = handle.extend(ms);
+      const now = clock.now();
+      const hard =
+        hardDeadlineAt === null
+          ? ""
+          : ` The configured hard ceiling (hardTimeoutMs) is not moved: it stops this subagent in ${formatDurationMs(Math.max(0, hardDeadlineAt - now))}.`;
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `Extended subagent ${child?.name ?? handle.childId} (${handle.childId}) in run ${record.runId}: ` +
+              `the next <pi-famulus-wake kind="subagent-overrun"> comes in ${formatDurationMs(deadlineAt - now)} if it is still running. ` +
+              `Its result arrives as a wake when it finishes; do not poll.${hard}`,
+          },
+        ],
+        details: { run_id: record.runId, child_id: handle.childId, deadline_at: deadlineAt, hard_deadline_at: hardDeadlineAt },
+      };
+    }
+
     // resume
     if (!params.message) throw new Error("message is required for resume");
     const child = resolveSingleTerminalChild(record, params.child_id);
-    const handle = registry.handle(child.childId);
-    if (!handle) throw new Error(`subagent ${child.childId} has no live session to resume`);
-    await handle.resume(params.message);
+    // A resume is a new turn with its own soft budget: timeout_ms when given,
+    // else the child's spawn budget (the runner's default). Returns once the
+    // request is accepted; it never waits for an admission slot.
+    const { queuedBehind } = await registry.resumeChild(
+      child.childId,
+      params.message,
+      params.timeout_ms === undefined ? {} : { timeoutMs: clampTimeout(params.timeout_ms, deps.defaultTimeoutMs) },
+    );
     // Resume is asynchronous. If siblings are still running, hand this child
     // back as soon as it finishes; otherwise the run-complete wake covers it.
     const handedOver = new Set<string>();
@@ -610,11 +664,12 @@ export function createSubagentTool(
           type: "text",
           text:
             `Resumed subagent ${child.name} (${child.childId}) in run ${record.runId}. ` +
+            queuedText(queuedBehind) +
             "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.",
         },
       ],
-      details: { run_id: record.runId, child_id: child.childId },
+      details: { run_id: record.runId, child_id: child.childId, queued_behind: queuedBehind },
     };
   };
 
@@ -626,7 +681,10 @@ export function createSubagentTool(
       "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. Use action=list/get/status/interrupt/resume/steer to manage existing runs.",
+      "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.",
     promptSnippet: "Fan out subagents in parallel or sequence them in a chain",
     promptGuidelines: [
       '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.',
@@ -694,6 +752,13 @@ export function createSubagentTool(
   };
 }
 
+/** Resume result clause for a turn waiting for an admission slot ("" when it started at once). */
+function queuedText(queuedBehind: number | null): string {
+  if (queuedBehind === null) return "";
+  const ahead = queuedBehind === 0 ? "" : ` and ${queuedBehind} subagent(s) are waiting ahead of it`;
+  return `Every subagent slot is busy${ahead}, so it is queued and starts when a slot frees. `;
+}
+
 function resolveSingleActiveChild(
   registry: SubagentRegistry,
   record: RunRecord,
@@ -728,6 +793,14 @@ function resolveSingleTerminalChild(record: RunRecord, childIdOrName: string | u
       const known = record.children.map((c) => `${c.name} (${c.childId})`).join(", ");
       throw new Error(`no child "${childIdOrName}" in run ${record.runId} (children: ${known})`);
     }
+    if (child.status === "pending") {
+      // Queued for an admission slot (a launch or an earlier resume): steer
+      // would fail too, and a second resume adds nothing.
+      throw new Error(
+        `subagent ${child.name} (${child.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.",
+      );
+    }
     if (!matches(child)) {
       throw new Error(`subagent ${child.name} (${child.childId}) is still ${child.status}; use steer instead`);
     }

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/tui/tasks-command.ts

@@ -10,13 +10,12 @@ import type { ManagerClient, TaskRecord } from "../manager-client";
 import { taskOutputPath } from "../config";
 import { formatConversation } from "../subagent/conversation";
 import type { SubagentRegistry } from "../subagent/registry";
-import { formatAge, type WorkIndex, type WorkItem } from "../work-index";
+import { formatAge, nextAgeBoundary, type WorkIndex, type WorkItem } from "../work-index";
 import { notifyPlainFallback, showScrollDetail } from "./scroll-detail-view";
 import { readTaskFileTailCached, stderrPathFor } from "./task-output-paths";
 import { fitLines, loadPiTui, truncateToWidth } from "./pi-tui-load";
 import { statusGlyph } from "./tool-component";
 
-const AGE_TICK_MS = 1000;
 
 function isLive(item: WorkItem): boolean {
   return item.status === "pending" || item.status === "running";
@@ -261,9 +260,36 @@ async function showTaskList(
       let loadingAll = false;
       let confirmId: string | undefined;
       let hint = "";
-      const unsub = subscribe(() => tui.requestRender());
-      const ageTimer = clock.setInterval(() => tui.requestRender(), AGE_TICK_MS);
-      clock.unref?.(ageTimer);
+      // formatAge rounds (now - startedAt) to the nearest second, so each
+      // live row's visible age flips on half-second boundaries relative to
+      // its own startedAt. Schedule the earliest pending flip and
+      // re-evaluate after every tick and every index change.
+      let ageTimer: unknown = null;
+      const clearAgeTimer = () => {
+        if (ageTimer === null) return;
+        clock.clearTimeout(ageTimer);
+        ageTimer = null;
+      };
+      const scheduleAgeTick = () => {
+        clearAgeTimer();
+        const now = clock.now();
+        let next = Infinity;
+        for (const item of visibleItems()) {
+          if (!isLive(item)) continue;
+          next = Math.min(next, nextAgeBoundary(now, item.startedAt));
+        }
+        if (!Number.isFinite(next)) return;
+        ageTimer = clock.setTimeout(() => {
+          ageTimer = null;
+          tui.requestRender();
+          scheduleAgeTick();
+        }, next - now);
+        clock.unref?.(ageTimer);
+      };
+      const unsub = subscribe(() => {
+        tui.requestRender();
+        scheduleAgeTick();
+      });
       const border = new DynamicBorder((text) => theme.fg("border", text));
       const pageSize = () => Math.max(1, (tui.terminal?.rows ?? 24) - 8);
       const matches = (data: string, id: "tui.select.up" | "tui.select.down" | "tui.select.confirm" | "tui.select.cancel") => {
@@ -273,6 +299,7 @@ async function showTaskList(
         scope === "all" ? mergeItems(getItems(), allItems) : getItems(),
         filter,
       );
+      scheduleAgeTick();
       const choose = (id: string | undefined) => {
         selectedId = id;
         hint = "";
@@ -394,7 +421,10 @@ async function showTaskList(
             tui.requestRender();
           }
         },
-        dispose() { clock.clearInterval(ageTimer); unsub(); },
+        dispose() {
+          clearAgeTimer();
+          unsub();
+        },
       };
     },
     // Bottom sheet over the editor, where the user typed /tasks; the list is

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) } : {}),
+  });
+}