pi-famulus 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
   "type": "module",
   "license": "MIT",
@@ -9,19 +9,36 @@
     "url": "https://github.com/Leechael/pi-famulus",
     "directory": "extension"
   },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org" },
-  "os": ["linux", "darwin"],
-  "cpu": ["x64", "arm64"],
-  "files": ["src", "bin", "README.md"],
-  "bin": { "pi-famulus": "./bin/pi-famulus.js" },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "bin": {
+    "pi-famulus": "./bin/pi-famulus.js"
+  },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.1.2",
-    "pi-famulus-linux-arm64": "0.1.2",
-    "pi-famulus-darwin-x64": "0.1.2",
-    "pi-famulus-darwin-arm64": "0.1.2"
+    "pi-famulus-linux-x64": "0.1.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",

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/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.2";
+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,

package/src/subagent/child-bash.ts

@@ -25,6 +25,7 @@ import type {
 import { taskOutputPath } from "../config";
 import { realClock, type Clock } from "../clock";
 import type { ManagerClient } from "../manager-client";
+import type { ChildShellTracker } from "./overrun";
 import {
   appendStatus,
   bareSleepError,
@@ -66,6 +67,8 @@ export interface ChildBashDeps {
   childId?: string;
   runId?: string;
   clock?: Clock;
+  /** Records the shell this child is blocked on, for its overrun wake. */
+  shells?: Pick<ChildShellTracker, "start" | "end">;
 }
 
 const CHILD_SLEEP_GUIDANCE =
@@ -132,52 +135,66 @@ export function createChildBashTool(
       const outputPath = taskOutputPath(deps.home, deps.sessionId(), start.task_id);
 
       const clock = deps.clock ?? realClock;
-      const deadline = timeoutMs !== null ? clock.now() + timeoutMs : null;
-      let waitResult: { done: boolean; exit_code?: number | null } | null = null;
-      for (;;) {
-        const budget =
-          deadline === null
-            ? WAIT_SLICE_MS
-            : Math.min(WAIT_SLICE_MS, Math.max(1, deadline - clock.now()));
-        try {
-          waitResult = await withAbort(client.wait(start.task_id, budget), signal, () => {
-            client.stop(start.task_id, "tool").catch(() => {});
-          });
-        } catch (err) {
-          if ((err as Error).message === "aborted") {
-            throw new Error("Command aborted (task stopped)");
+      const childId = deps.childId;
+      if (childId) {
+        deps.shells?.start(childId, {
+          taskId: start.task_id,
+          command: input.command,
+          startedAt: clock.now(),
+          outputPath,
+        });
+      }
+      try {
+        const deadline = timeoutMs !== null ? clock.now() + timeoutMs : null;
+        let waitResult: { done: boolean; exit_code?: number | null } | null = null;
+        for (;;) {
+          const budget =
+            deadline === null
+              ? WAIT_SLICE_MS
+              : Math.min(WAIT_SLICE_MS, Math.max(1, deadline - clock.now()));
+          try {
+            waitResult = await withAbort(client.wait(start.task_id, budget), signal, () => {
+              client.stop(start.task_id, "tool").catch(() => {});
+            });
+          } catch (err) {
+            if ((err as Error).message === "aborted") {
+              throw new Error("Command aborted (task stopped)");
+            }
+            throw new Error(
+              `Lost contact with pi-famulus while waiting for task ${start.task_id}: ` +
+                `${(err as Error).message}. Output so far: ${outputPath}.`,
+            );
+          }
+          if (waitResult.done) break;
+          if (deadline !== null && clock.now() >= deadline) {
+            await client.stop(start.task_id, "timeout").catch(() => {});
+            const collected = await collectOutput(client, start.task_id).catch(() => null);
+            const text = collected ? formatFinishedOutput(collected, outputPath).text : "";
+            throw new Error(
+              appendStatus(text, timedOutStatus(input.timeout!)),
+            );
           }
-          throw new Error(
-            `Lost contact with pi-famulus while waiting for task ${start.task_id}: ` +
-              `${(err as Error).message}. Output so far: ${outputPath}.`,
-          );
-        }
-        if (waitResult.done) break;
-        if (deadline !== null && clock.now() >= deadline) {
-          await client.stop(start.task_id, "timeout").catch(() => {});
-          const collected = await collectOutput(client, start.task_id).catch(() => null);
-          const text = collected ? formatFinishedOutput(collected, outputPath).text : "";
-          throw new Error(
-            appendStatus(text, timedOutStatus(input.timeout!)),
-          );
         }
-      }
 
-      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)));
+        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)));
+        }
+        const finalDetails = details
+          ? { ...details, task_id: start.task_id }
+          : ({ task_id: start.task_id } as FamulusChildBashDetails);
+        return { content: [{ type: "text", text }], details: finalDetails };
+      } finally {
+        // The overrun wake must not name a shell that already returned.
+        if (childId) deps.shells?.end(childId, start.task_id);
       }
-      const finalDetails = details
-        ? { ...details, task_id: start.task_id }
-        : ({ task_id: start.task_id } as FamulusChildBashDetails);
-      return { content: [{ type: "text", text }], details: finalDetails };
     },
   };
 }