pi-famulus 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
   "type": "module",
   "license": "MIT",
@@ -9,36 +9,52 @@
     "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.1",
-    "pi-famulus-linux-arm64": "0.1.1",
-    "pi-famulus-darwin-x64": "0.1.1",
-    "pi-famulus-darwin-arm64": "0.1.1"
+    "pi-famulus-linux-x64": "0.1.3",
+    "pi-famulus-linux-arm64": "0.1.3",
+    "pi-famulus-darwin-x64": "0.1.3",
+    "pi-famulus-darwin-arm64": "0.1.3"
   },
   "pi": {
-    "extensions": ["./src/index.ts"]
+    "extensions": [
+      "./src/index.ts"
+    ]
   },
   "scripts": {
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": {
-    "typebox": "^1.3.7"
-  },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.1",
-    "@earendil-works/pi-tui": "^0.87.1",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "@types/node": "^24.0.0",
+    "typebox": "1.3.27",
     "typescript": "7.0.2",
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*",
     "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {

package/src/agents/definition.ts

@@ -15,6 +15,12 @@
  *   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;
@@ -24,7 +30,8 @@ export interface AgentDefinition {
   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";
@@ -35,8 +42,6 @@ export interface AgentDefinition {
 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;
 
@@ -178,12 +183,13 @@ 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 {

package/src/bash-override.ts

@@ -17,7 +17,7 @@ import { randomUUID } from "node:crypto";
 import { writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
 import type {
   AgentToolResult,
   BashToolDetails,
@@ -62,6 +62,46 @@ const bashParameters = Type.Object({
 
 type BashParams = { command: string; timeout?: number; run_in_background?: boolean };
 
+/**
+ * Mirrors the built-in bash outputSchema (pi ≥0.99) so codemode scripts calling
+ * `bash()` resolve to the same structured shape the built-in tool returns.
+ * pi does not export `bashOutputSchema`, so keep this in sync with BashToolOutput.
+ */
+const bashOutputSchema = Type.Object({
+  output: Type.String(),
+  truncated: Type.Boolean(),
+  full_output_path: Type.Optional(Type.String()),
+  exit_code: Type.Number(),
+  wall_time_seconds: Type.Number(),
+});
+type BashToolOutput = Static<typeof bashOutputSchema>;
+
+/** Same cap as the built-in structured output (1 MiB). */
+const STRUCTURED_OUTPUT_MAX_BYTES = 1024 * 1024;
+
+/** Full-output slice for structuredContent, keeping the tail like the built-in. */
+function structuredOutput(fullText: string): { output: string; truncated: boolean } {
+  if (Buffer.byteLength(fullText, "utf8") <= STRUCTURED_OUTPUT_MAX_BYTES) {
+    return { output: fullText, truncated: false };
+  }
+  // Keep the largest tail that fits the cap without materializing the whole
+  // output as a second buffer: search a UTF-16 index near the end (each code
+  // unit encodes to at least one byte, so the tail starts within `cap` units
+  // of the end) and only encode that slice.
+  let lo = Math.max(0, fullText.length - STRUCTURED_OUTPUT_MAX_BYTES);
+  let hi = fullText.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (Buffer.byteLength(fullText.slice(mid), "utf8") <= STRUCTURED_OUTPUT_MAX_BYTES) hi = mid;
+    else lo = mid + 1;
+  }
+  return { output: fullText.slice(lo), truncated: true };
+}
+
+function wallSeconds(startedAtMs: number, endedAtMs: number): number {
+  return Math.round((endedAtMs - startedAtMs) / 100) / 10;
+}
+
 /** Details shape returned by this override; superset of BashToolDetails. */
 export interface FamulusBashDetails extends BashToolDetails {
   backgrounded?: boolean;
@@ -130,6 +170,7 @@ async function executeLocal(
   clock: Clock,
 ): Promise<AgentToolResult<FamulusBashDetails | undefined>> {
   const timeoutMs = resolveTimeoutMs(params.timeout);
+  const startedAtMs = clock.now();
   const shell = process.env.SHELL && process.env.SHELL.length > 0 ? process.env.SHELL : "/bin/bash";
 
   const output = await new Promise<{ text: string; exitCode: number | null; signal: string | null; timedOut: boolean; aborted: boolean }>(
@@ -216,11 +257,26 @@ async function executeLocal(
   if (output.timedOut && params.timeout !== undefined) {
     throw new Error(appendStatus(text, timedOutStatus(params.timeout)));
   }
-  if (output.exitCode !== 0 && output.exitCode !== null) {
-    throw new Error(appendStatus(text, `Command exited with code ${output.exitCode}`));
-  }
   if (output.exitCode === null) throw new Error(appendStatus(text, killedBy(output.signal)));
-  return { content: [{ type: "text", text }], details };
+  const { output: structuredText, truncated: structuredTruncated } = structuredOutput(output.text);
+  const structuredContent: BashToolOutput = {
+    output: structuredText,
+    truncated: structuredTruncated,
+    ...(details?.fullOutputPath ? { full_output_path: details.fullOutputPath } : {}),
+    exit_code: output.exitCode,
+    wall_time_seconds: wallSeconds(startedAtMs, clock.now()),
+  };
+  if (output.exitCode !== 0) {
+    // Mirror the built-in bash tool: non-zero exits resolve to an isError
+    // result carrying structuredContent instead of rejecting.
+    return {
+      content: [{ type: "text", text: appendStatus(text, `Command exited with code ${output.exitCode}`) }],
+      details,
+      structuredContent,
+      isError: true,
+    };
+  }
+  return { content: [{ type: "text", text }], details, structuredContent };
 }
 
 // ---------------------------------------------------------------------------
@@ -245,6 +301,7 @@ export function createBashOverride(
       "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.",
     ],
     parameters: bashParameters,
+    outputSchema: bashOutputSchema,
     renderResult(result, { expanded }, theme, context) {
       const details = result.details as FamulusBashDetails | undefined;
       if (details?.backgrounded && details.task_id) {
@@ -291,6 +348,7 @@ export function createBashOverride(
       }
 
       const timeoutMs = resolveTimeoutMs(input.timeout);
+      const startedAtMs = (deps.clock ?? realClock).now();
       let start;
       try {
         start = await client.start({
@@ -358,15 +416,37 @@ export function createBashOverride(
       const collected = await collectOutput(client, start.task_id);
       const { text, details } = formatFinishedOutput(collected, outputPath);
       const exitCode = waitResult.exit_code ?? null;
-      if (exitCode !== 0 && exitCode !== null) {
-        throw new Error(appendStatus(text, `Command exited with code ${exitCode}`));
-      }
       // No exit code: killed (timeout, stop, crash), unless the manager
       // finished it as completed with its runner status unobservable.
       if (exitCode === null && collected.status !== "completed") {
         throw new Error(appendStatus(text, await killedStatus(client, start.task_id, input.timeout)));
       }
-      return { content: [{ type: "text", text }], details };
+      if (exitCode === null) {
+        // Completed but the exit code was unobservable: no honest
+        // structured shape (exit_code is required, and a sentinel like -1
+        // would misclassify success as failure), so omit structuredContent
+        // and let codemode scripts fall back to the text content.
+        return { content: [{ type: "text", text }], details };
+      }
+      const { output: structuredText, truncated: structuredTruncated } = structuredOutput(collected.text);
+      const structuredContent: BashToolOutput = {
+        output: structuredText,
+        truncated: structuredTruncated || collected.windowed,
+        full_output_path: outputPath,
+        exit_code: exitCode,
+        wall_time_seconds: wallSeconds(startedAtMs, (deps.clock ?? realClock).now()),
+      };
+      if (exitCode !== 0) {
+        // Mirror the built-in bash tool: non-zero exits resolve to an isError
+        // result carrying structuredContent instead of rejecting.
+        return {
+          content: [{ type: "text", text: appendStatus(text, `Command exited with code ${exitCode}`) }],
+          details,
+          structuredContent,
+          isError: true,
+        };
+      }
+      return { content: [{ type: "text", text }], details, structuredContent };
     },
   };
 }

package/src/behavior-guidelines.ts

@@ -22,6 +22,7 @@ export const BEHAVIOR_GUIDELINES = `## Background tasks and notifications (pi-fa
 - 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.
+- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind="subagent-overrun"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. Pick one: subagent({action:"extend", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:"interrupt", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.
 - 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 interface GuidelinePromptOptions {

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/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,14 @@
  * 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,
+  wakeDuration,
+  type FormattedWake,
+  type OverrunShell,
+  type WakeItem,
+} from "./wake";
 
 export { FAMULUS_WAKE_LEAD_IN } from "./wake";
 export type { FormattedWake, WakeItem } from "./wake";
@@ -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,55 @@ 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.
+ */
+export function formatSubagentOverrun(info: SubagentOverrunInfo): FormattedWake {
+  const shellBit = info.shell ? `; it is waiting on a shell command that has run ${wakeDuration(info.shell.elapsedMs)}` : "";
+  const summary =
+    `${info.name} has run ${wakeDuration(info.elapsedMs)} in this turn, past its ` +
+    `${wakeDuration(info.budgetMs)} budget, and is still running${shellBit}.`;
+  const oneLine = info.lastActivity.text.replace(/\s+/g, " ").trim();
+  const text =
+    oneLine.length > OVERRUN_ACTIVITY_CHARS ? `…${oneLine.slice(-OVERRUN_ACTIVITY_CHARS)}` : oneLine;
+  return formatFamulusWake({
+    kind: "subagent-overrun",
+    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 } : {}),
+    summary,
+    lastActivity: { agoMs: info.lastActivity.agoMs, text: text || "(no output yet)" },
+    ...(info.shell ? { shell: { ...info.shell, command: shellWakeTitle(info.shell.command) } } : {}),
   });
 }

package/src/index.ts

@@ -11,6 +11,7 @@ import { ExitNotifyGate } from "./exit-notify-gate";
 import { ExitWatchdog } from "./exit-watchdog";
 import { createExtensionEventLog } from "./events";
 import { readFileTail } from "./file-tail";
+import { statSync } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -27,7 +28,9 @@ import type { TaskExitInfo } from "./format";
 import { ManagerClient, type ManagerEvent, type TaskRecord } from "./manager-client";
 import { createMonitorTool, exitEventFromRecord, MonitorRegistry } from "./monitor";
 import { NotifyCenter } from "./notify";
+import { onWakeMessageEnd, registryStatusLookup } from "./wake-delivery";
 import { createChildBashTool } from "./subagent/child-bash";
+import { ChildShellTracker, createOverrunNotifier } from "./subagent/overrun";
 import {
   agentEndReason,
   headOf,
@@ -504,6 +507,8 @@ export default function (pi: ExtensionAPI): void {
         "warning",
       );
     }
+    // The foreground shell each child is blocked on, for its overrun wake.
+    const childShells = new ChildShellTracker();
     const createSession = createPiSessionFn({
       getModelRegistry: () => ctx?.modelRegistry ?? null,
       getModelRuntime: () => {
@@ -533,6 +538,7 @@ export default function (pi: ExtensionAPI): void {
               childId: req.childId,
               runId: req.runId,
               clock,
+              shells: childShells,
             }),
           );
         }
@@ -551,7 +557,9 @@ export default function (pi: ExtensionAPI): void {
       stallMs: subagentConfig.stallMs,
       stallRetries: subagentConfig.stallRetries,
       stallRetryDelayMs: subagentConfig.stallRetryDelayMs,
-      acquire: (req) => registry.admitChild(req.childId),
+      overrunRepeatMs: subagentConfig.overrunRepeatMs,
+      hardTimeoutMs: subagentConfig.hardTimeoutMs,
+      acquire: (req, ticket) => registry.admitChild(req.childId, ticket),
       onActivity: (childId) => {
         syncTranscript(childId);
       },
@@ -560,6 +568,22 @@ export default function (pi: ExtensionAPI): void {
         // retry budget (stallRetries) is already spent.
         logEvent("agent.stall", { child_id: childId, attempt });
       },
+      // Soft deadline: the child keeps running; the parent decides.
+      onOverrun: createOverrunNotifier({
+        now: () => clock.now(),
+        registry,
+        shells: childShells,
+        stat: (path) => {
+          try {
+            const st = statSync(path);
+            return { size: st.size, mtimeMs: st.mtimeMs };
+          } catch {
+            return null;
+          }
+        },
+        notify: (wake) => notifyCenter?.notify(wake),
+        logEvent,
+      }),
     });
     registry.setRunner(runner);
     subagentRegistry = registry;
@@ -581,6 +605,7 @@ export default function (pi: ExtensionAPI): void {
         }
         if (["completed", "failed", "interrupted"].includes(c.status) && previousStatus !== c.status) {
           const error = c.result?.error;
+          // Only the opt-in hard ceiling settles with error=timeout now.
           if (error === "timeout") logEvent("agent.timeout", { child_id: c.childId });
           logEvent("agent.settle", {
             child_id: c.childId,
@@ -694,6 +719,16 @@ export default function (pi: ExtensionAPI): void {
     notifyCenter?.settled();
   });
 
+  // A wake entering the model's context (steer / triggerTurn); see wake-delivery.ts.
+  pi.on("message_end", async (event) => {
+    const message = onWakeMessageEnd(event.message, {
+      now: () => clock.now(),
+      logEvent,
+      lookup: () => (subagentRegistry ? registryStatusLookup(subagentRegistry) : null),
+    });
+    return message ? { message } : undefined;
+  });
+
   pi.on("before_agent_start", async (event) => {
     applyBehaviorGuidelines(event.systemPromptOptions as { sections?: Record<string, string> });
   });

package/src/manager-client.ts

@@ -16,7 +16,7 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.1.1";
+const EXTENSION_VERSION = "0.1.3";
 // 3: speaks in-place upgrade (resends on reconnect, start keys).
 const PROTOCOL = 3;
 const HELLO_TIMEOUT_MS = 5000;

package/src/notify.ts

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