pi-famulus 0.1.2 → 0.1.3

package/src/subagent/runner.ts

@@ -9,7 +9,13 @@
  * starts a new generation on the same session):
  * - a per-generation admission slot is acquired via the optional `acquire`
  *   hook (the registry uses it for the global concurrency cap);
- * - `timeoutMs` is a hard timeout: abort -> result {status:"interrupted", error:"timeout"};
+ * - `timeoutMs` is a SOFT deadline per user turn: reaching it calls
+ *   `onOverrun` (the parent gets a subagent-overrun wake) and repeats every
+ *   `overrunRepeatMs`; the child is not aborted and its shell keeps running.
+ *   `extend()` re-arms the deadline; steer/followUp after a reminder postpone
+ *   the next one. See design.md §4.6 "Child lifecycle".
+ * - `hardTimeoutMs` (opt-in, default off) is the abort ceiling per turn:
+ *   abort -> result {status:"interrupted", error:"timeout"};
  * - a stall watchdog aborts the child after `stallMs` (default 10min) without
  *   any session event. A stall is treated as transient (a silently dropped
  *   provider stream): the child is aborted and auto-resumed on the SAME
@@ -21,9 +27,10 @@
  *   rejects prompt() while a run is still active ("Agent is already
  *   processing"). The wait is bounded by `stallMs` — an abort that never
  *   completes means the stream ignored it and the session is dead.
- * - `timeoutMs` is a budget for the whole user turn: stall retries arm only
- *   the remaining time, and a timeout landing during a retry delay still
- *   fires (it is not masked by the retired generation).
+ * - deadlines belong to the whole user turn: stall retries re-arm the soft
+ *   deadline / reminder schedule and the hard ceiling from turn-level fields,
+ *   never from the retry. A reminder landing during a retry delay is sent and
+ *   the retry still runs; a hard ceiling landing there still settles.
  * - session/prompt exceptions -> {status:"failed", error}.
  *
  * Note on pi semantics: AgentSession.prompt() resolves only after the whole
@@ -32,6 +39,7 @@
  * steer/followUp processing.
  */
 import { realClock, TimerScope, type Clock, type ClockTimer } from "../clock";
+import type { OverrunTick } from "./overrun";
 import type {
   ChildResult,
   ChildRunRequest,
@@ -48,6 +56,8 @@ export const DEFAULT_STALL_MS = 5 * 60 * 1000;
 export const DEFAULT_STALL_RETRIES = 1;
 /** Pause between the stall abort and the retry prompt (ms). */
 export const DEFAULT_STALL_RETRY_DELAY_MS = 5_000;
+/** Overrun reminder interval while a child stays past its soft budget (ms). */
+export const DEFAULT_OVERRUN_REPEAT_MS = 10 * 60 * 1000;
 
 /** Continuation prompt for a stall retry: the transcript holds the context. */
 export function stallRetryPrompt(stallMs: number): string {
@@ -57,6 +67,12 @@ export function stallRetryPrompt(stallMs: number): string {
   );
 }
 
+/** Identity of one generation's slot request (see InProcessRunnerOptions.acquire). */
+export interface AdmissionTicket {
+  /** False once the requesting generation settled or was superseded. */
+  current: () => boolean;
+}
+
 export interface InProcessRunnerOptions {
   createSession: CreateSessionFn;
   /** Stall watchdog timeout (ms). Default 10 minutes. */
@@ -67,6 +83,15 @@ export interface InProcessRunnerOptions {
   stallRetryDelayMs?: number;
   /** Called on every stall detection (before any retry), with the 1-based attempt. */
   onStall?: (childId: string, attempt: number) => void;
+  /** Overrun reminder interval (ms). Default 10 minutes. */
+  overrunRepeatMs?: number;
+  /** Abort ceiling per user turn (ms). 0/absent = off: the soft deadline never aborts. */
+  hardTimeoutMs?: number;
+  /**
+   * The child passed its soft deadline (first reminder) or is still past it
+   * (later reminders). The child keeps running; the parent decides.
+   */
+  onOverrun?: (tick: OverrunTick) => void;
   /** Shared time source and scheduler. */
   clock?: Clock;
   /**
@@ -74,7 +99,7 @@ export interface InProcessRunnerOptions {
    * resolved releaser is called when the generation settles. Rejecting
    * cancels the generation as {status:"interrupted", error}.
    */
-  acquire?: (req: ChildRunRequest) => Promise<() => void>;
+  acquire?: (req: ChildRunRequest, ticket: AdmissionTicket) => Promise<() => void>;
   /**
    * Called after the child's conversation may have changed (a message or
    * tool finished, or the generation settled). Used to persist transcripts.
@@ -107,8 +132,11 @@ class InProcessChildHandle implements DisposableChildHandle {
   private readonly stallRetries: number;
   private readonly stallRetryDelayMs: number;
   private readonly onStall?: (childId: string, attempt: number) => void;
+  private readonly overrunRepeatMs: number;
+  private readonly hardTimeoutMs: number;
+  private readonly onOverrun?: (tick: OverrunTick) => void;
   private readonly clock: Clock;
-  private readonly acquire?: (req: ChildRunRequest) => Promise<() => void>;
+  private readonly acquire?: (req: ChildRunRequest, ticket: AdmissionTicket) => Promise<() => void>;
   private readonly onActivity?: (childId: string) => void;
 
   private session: ChildSessionAdapter | null = null;
@@ -121,11 +149,19 @@ class InProcessChildHandle implements DisposableChildHandle {
   /** User-turn start: reset on launch and user resume(), not on stall retries. */
   private runStartedAt: number;
   /**
-   * When the timeout budget starts counting. Set after admission and session
+   * When the turn's deadlines start counting. Set after admission and session
    * creation (queue wait must not eat the budget), and NOT reset by stall
    * retries — a stall already consumes budget time by definition.
    */
   private turnBudgetStart: number;
+  /** This turn's soft budget: spawn timeoutMs, or resume()'s timeoutMs. */
+  private turnBudgetMs: number;
+  /** Soft deadline (absolute). Moved by extend(). Null = no soft deadline. */
+  private softDeadlineAt: number | null = null;
+  /** When the soft timer fires next: softDeadlineAt, then each reminder. */
+  private nextReminderAt: number | null = null;
+  /** Overrun reminders sent this turn. */
+  private reminders = 0;
   /** Abort kicked off by the latest stall detection; awaited (bounded) by the retry. */
   private abortPromise: Promise<void> | null = null;
   private generation = 0;
@@ -140,7 +176,8 @@ class InProcessChildHandle implements DisposableChildHandle {
    * the previous turn's settle by definition).
    */
   private settleWaiters: Array<() => void> = [];
-  private timeoutTimer: ClockTimer | null = null;
+  private softTimer: ClockTimer | null = null;
+  private hardTimer: ClockTimer | null = null;
   private stallTimer: ClockTimer | null = null;
   private retryTimer: { scope: TimerScope; id: ClockTimer } | null = null;
   private timerScope: TimerScope | null = null;
@@ -168,6 +205,15 @@ class InProcessChildHandle implements DisposableChildHandle {
       ? Math.max(0, Math.floor(rawDelay))
       : DEFAULT_STALL_RETRY_DELAY_MS;
     this.onStall = opts.onStall;
+    const rawRepeat = opts.overrunRepeatMs ?? DEFAULT_OVERRUN_REPEAT_MS;
+    this.overrunRepeatMs =
+      Number.isFinite(rawRepeat) && rawRepeat > 0
+        ? Math.max(1, Math.floor(rawRepeat))
+        : DEFAULT_OVERRUN_REPEAT_MS;
+    const rawHard = opts.hardTimeoutMs ?? 0;
+    this.hardTimeoutMs = Number.isFinite(rawHard) && rawHard > 0 ? Math.floor(rawHard) : 0;
+    this.onOverrun = opts.onOverrun;
+    this.turnBudgetMs = req.timeoutMs;
     this.clock = opts.clock ?? realClock;
     this.acquire = opts.acquire;
     this.onActivity = opts.onActivity;
@@ -201,7 +247,10 @@ class InProcessChildHandle implements DisposableChildHandle {
     return this.resolvedModel_ ?? this.session?.resolvedModel;
   }
 
-  /** Pause the stall watchdog (need_decision). Nested with tool execution. */
+  /**
+   * need_decision pending: pause the stall watchdog (nested with tool
+   * execution) and hold overrun reminders. The soft budget keeps counting.
+   */
   pauseStall(): void {
     this.decisionPaused = true;
     this.clearStall();
@@ -211,6 +260,9 @@ class InProcessChildHandle implements DisposableChildHandle {
     this.decisionPaused = false;
     this.lastEvent = this.clock.now();
     if (this.status_ === "running" && this.toolDepth === 0) this.armStall(this.generation);
+    // Deliver a reminder held during the decision (due now, so it fires at
+    // once); otherwise this re-arms the unchanged schedule.
+    if (this.status_ === "running" && !this.settledFlag) this.armSoftDeadline(this.generation);
   }
 
   conversation() {
@@ -230,7 +282,9 @@ class InProcessChildHandle implements DisposableChildHandle {
       // The previous generation was aborted; delivery would be undefined.
       throw new Error(`subagent ${this.req.childId} is restarting after a stall; retry shortly`);
     }
+    const gen = this.generation;
     await this.session.steer(message);
+    this.parentActed(gen);
   }
 
   async followUp(message: string): Promise<void> {
@@ -240,10 +294,57 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (this.retiredGen !== null) {
       throw new Error(`subagent ${this.req.childId} is restarting after a stall; retry shortly`);
     }
+    const gen = this.generation;
     await this.session.followUp(message);
+    this.parentActed(gen);
+  }
+
+  /**
+   * Parent action on an overrun: move the soft deadline to now + timeoutMs
+   * (default: the spawn budget). The reminder count continues; the hard
+   * ceiling (if any) does not move.
+   */
+  extend(timeoutMs?: number): { deadlineAt: number; hardDeadlineAt: number | null } {
+    if (this.status_ !== "running") {
+      throw new Error(`subagent ${this.req.childId} is not running (status: ${this.status_})`);
+    }
+    const ms = timeoutMs ?? this.req.timeoutMs;
+    if (!(ms > 0)) throw new Error("extend needs a positive timeout_ms");
+    this.softDeadlineAt = this.now() + ms;
+    this.nextReminderAt = this.softDeadlineAt;
+    this.armSoftDeadline(this.generation);
+    return {
+      deadlineAt: this.softDeadlineAt,
+      hardDeadlineAt: this.hardTimeoutMs > 0 ? this.turnBudgetStart + this.hardTimeoutMs : null,
+    };
   }
 
-  async resume(message: string): Promise<void> {
+  /**
+   * steer/followUp after a reminder: the parent is handling the overrun, so
+   * the next reminder waits a full interval. Before the first reminder the
+   * deadline is untouched, and so is a deadline that extend() moved into the
+   * future: the child is inside its budget again, and the next wake belongs
+   * at that deadline, not one repeat from now.
+   */
+  private parentActed(gen: number): void {
+    // The delivery was awaited: if its turn settled (and maybe a resume
+    // started a new one) meanwhile, it must not move the new schedule.
+    if (gen !== this.generation || this.settledFlag) return;
+    if (this.reminders === 0 || this.status_ !== "running") return;
+    const now = this.now();
+    if (this.softDeadlineAt !== null && now < this.softDeadlineAt) return;
+    this.nextReminderAt = now + this.overrunRepeatMs;
+    this.armSoftDeadline(this.generation);
+  }
+
+  /**
+   * Start a new user turn. Resolves once the request is accepted, not when
+   * the turn starts: draining a still-unwinding abort and waiting for an
+   * admission slot run in the background, so the parent's tool call never
+   * waits for a slot. Until admission the child is "pending" (queued).
+   * Failures after acceptance settle the new turn instead of rejecting.
+   */
+  async resume(message: string, opts: { timeoutMs?: number } = {}): Promise<void> {
     if (this.status_ === "running" || this.status_ === "pending") {
       throw new Error(
         `subagent ${this.req.childId} is still ${this.status_}; use steer for a running subagent`,
@@ -255,35 +356,57 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (!this.session) {
       throw new Error(`subagent ${this.req.childId} has no session to resume`);
     }
-    // Drain a stall/timeout abort that is still unwinding (real pi rejects
-    // prompt() while the aborted run is active). Bounded: a hung abort means
-    // the session is dead and cannot be resumed.
-    const pendingAbort = this.abortPromise;
-    this.abortPromise = null;
-    if (pendingAbort && !(await this.awaitAbortBounded(pendingAbort))) {
-      throw new Error(
-        `subagent ${this.req.childId} session did not go idle after the abort; cannot resume`,
-      );
-    }
-    if (this.disposed) {
-      throw new Error(`subagent ${this.req.childId} has been disposed`);
-    }
-    // A new user turn gets a fresh stall budget and a fresh timeout budget.
+    // A new user turn gets a fresh stall budget and a fresh soft budget:
+    // the one passed with resume, else the spawn budget.
     this.stallAttempts = 0;
+    this.turnBudgetMs =
+      opts.timeoutMs !== undefined && opts.timeoutMs > 0 ? opts.timeoutMs : this.req.timeoutMs;
+    this.reminders = 0;
     this.runStartedAt = this.clock.now();
-    // Swap in the new generation's result promise synchronously so that
-    // registry.getResult() observes it before/while admission runs.
+    // The turn's generation exists from here: interrupt()/dispose() while it
+    // is queued settle it, and its result promise is observable through
+    // registry.getResult() before admission.
+    const gen = ++this.generation;
+    this.settledFlag = false;
+    this.retiredGen = null;
+    this.status_ = "pending";
+    this.startedAt = this.runStartedAt;
+    this.lastEvent = this.runStartedAt;
     this.resultPromise = new Promise((resolve) => {
       this.resolveResult = resolve;
     });
-    await this.beginGeneration(message, false);
+    const pendingAbort = this.abortPromise;
+    this.abortPromise = null;
+    void this.startResumedTurn(gen, message, pendingAbort);
+  }
+
+  /**
+   * Background half of resume(): drain a stall/timeout abort that is still
+   * unwinding (real pi rejects prompt() while the aborted run is active),
+   * then admission and prompt. Bounded: a hung abort means the session is
+   * dead, and the turn settles failed.
+   */
+  private async startResumedTurn(gen: number, message: string, pendingAbort: Promise<void> | null): Promise<void> {
+    if (pendingAbort && !(await this.awaitAbortBounded(pendingAbort))) {
+      this.settle(gen, {
+        status: "failed",
+        text: "",
+        error: `subagent ${this.req.childId} session did not go idle after the abort; cannot resume`,
+        durationMs: this.now() - this.runStartedAt,
+      });
+      return;
+    }
+    if (this.disposed || this.isSettled(gen)) return;
+    await this.beginGeneration(message, false, false, gen);
   }
 
   async interrupt(): Promise<void> {
     if (this.status_ !== "running" && this.status_ !== "pending") return;
     this.settle(this.generation, {
       status: "interrupted",
-      text: this.partialText(),
+      // A pending turn has produced nothing yet; the last assistant text
+      // belongs to the previous turn.
+      text: this.status_ === "pending" ? "" : this.partialText(),
       durationMs: this.now() - this.startedAt,
     });
     try {
@@ -326,8 +449,14 @@ class InProcessChildHandle implements DisposableChildHandle {
    * slot acquired by the stalled generation is still held (no settle happened),
    * so admission is not re-run and the slot is not double-counted.
    */
-  private async beginGeneration(prompt: string, first: boolean, reuseSlot = false): Promise<void> {
-    const gen = ++this.generation;
+  private async beginGeneration(
+    prompt: string,
+    first: boolean,
+    reuseSlot = false,
+    resumedGen?: number,
+  ): Promise<void> {
+    // A resumed turn allocated its generation when it was requested.
+    const gen = resumedGen ?? ++this.generation;
     this.retiredGen = null;
     this.clearRetryTimer();
     this.timerScope?.dispose();
@@ -343,7 +472,12 @@ class InProcessChildHandle implements DisposableChildHandle {
 
     if (this.acquire && !reuseSlot) {
       try {
-        this.releaseSlot = await this.acquire(this.req);
+        // The ticket ties the slot request to THIS generation: a request
+        // whose generation settled while queued (interrupt, then a new
+        // resume) must not admit the child's next generation.
+        this.releaseSlot = await this.acquire(this.req, {
+          current: () => !this.disposed && !this.isSettled(gen),
+        });
       } catch (err) {
         // Admission denied (e.g. fail_fast cancellation while queued).
         this.settle(gen, {
@@ -414,13 +548,19 @@ class InProcessChildHandle implements DisposableChildHandle {
       return;
     }
 
-    // The timeout budget starts only after admission and session creation:
+    // The turn's deadlines start only after admission and session creation:
     // time spent queued for an admission slot is not the child's budget.
-    if (!reuseSlot) this.turnBudgetStart = this.now();
-    this.armTimeout(gen);
-    // A stall can spend the whole timeout budget before this generation
-    // starts; armTimeout settles in that case and prompting must not proceed.
+    // Stall retries (reuseSlot) keep the turn's deadlines and schedule.
+    if (!reuseSlot) {
+      this.turnBudgetStart = this.now();
+      this.softDeadlineAt = this.turnBudgetMs > 0 ? this.turnBudgetStart + this.turnBudgetMs : null;
+      this.nextReminderAt = this.softDeadlineAt;
+    }
+    this.armHardCeiling(gen);
+    // A stall can spend the whole hard budget before this generation starts;
+    // armHardCeiling settles in that case and prompting must not proceed.
     if (this.isSettled(gen)) return;
+    this.armSoftDeadline(gen);
     this.armStall(gen);
     // Tell the child which model it is — otherwise only the parent/fleet knows.
     const prompted =
@@ -541,16 +681,63 @@ class InProcessChildHandle implements DisposableChildHandle {
     }
   }
 
-  private armTimeout(gen: number): void {
-    if (this.timeoutTimer !== null) {
-      this.timerScope?.clearTimeout(this.timeoutTimer);
-      this.timeoutTimer = null;
+  /**
+   * Soft deadline / reminder timer for the current generation scope, due at
+   * nextReminderAt (turn-level, so a stall retry re-arms the same schedule).
+   */
+  private armSoftDeadline(gen: number): void {
+    if (this.softTimer !== null) {
+      this.timerScope?.clearTimeout(this.softTimer);
+      this.softTimer = null;
+    }
+    if (this.nextReminderAt === null) return;
+    const delay = Math.max(0, this.nextReminderAt - this.now());
+    this.softTimer = this.timerScope?.setTimeout(() => {
+      this.softTimer = null;
+      // Deliberately NOT isCurrent(): during a stall's retry delay the child
+      // is still running from the parent's view, so the reminder is due.
+      if (this.settledFlag || this.disposed || gen !== this.generation) return;
+      // A pending need_decision already put a supervisor-request wake in
+      // front of the parent: hold the reminder (nextReminderAt stays due)
+      // until resumeStall() re-arms it when the decision resolves.
+      if (this.decisionPaused) return;
+      this.fireOverrun(gen);
+    }, delay) ?? null;
+  }
+
+  private fireOverrun(gen: number): void {
+    const now = this.now();
+    this.reminders++;
+    this.nextReminderAt = now + this.overrunRepeatMs;
+    try {
+      this.onOverrun?.({
+        childId: this.req.childId,
+        elapsedMs: now - this.turnBudgetStart,
+        budgetMs: (this.softDeadlineAt ?? now) - this.turnBudgetStart,
+        reminder: this.reminders,
+        nextReminderMs: this.overrunRepeatMs,
+        lastEventAt: this.lastEvent,
+        hardRemainingMs:
+          this.hardTimeoutMs > 0 ? Math.max(0, this.turnBudgetStart + this.hardTimeoutMs - now) : null,
+      });
+    } catch {
+      // overrun observers must not break the schedule
     }
-    if (!(this.req.timeoutMs > 0)) return;
-    // The timeout is a budget for the whole user turn: a stall retry arms
-    // only what the stalled generation did not already consume. The budget
-    // clock starts after admission (turnBudgetStart), not at launch.
-    const remaining = this.req.timeoutMs - (this.now() - this.turnBudgetStart);
+    this.armSoftDeadline(gen);
+  }
+
+  /**
+   * Opt-in abort ceiling (hardTimeoutMs). The ceiling is per user turn: a
+   * stall retry arms only what the stalled generation did not already
+   * consume, and the budget clock starts after admission (turnBudgetStart).
+   */
+  private armHardCeiling(gen: number): void {
+    if (this.hardTimer !== null) {
+      this.timerScope?.clearTimeout(this.hardTimer);
+      this.hardTimer = null;
+    }
+    if (!(this.hardTimeoutMs > 0)) return;
+    const remaining = this.hardTimeoutMs - (this.now() - this.turnBudgetStart);
     if (remaining <= 0) {
       this.settle(gen, {
         status: "interrupted",
@@ -560,9 +747,9 @@ class InProcessChildHandle implements DisposableChildHandle {
       });
       return;
     }
-    this.timeoutTimer = this.timerScope?.setTimeout(() => {
-      this.timeoutTimer = null;
-      // Deliberately NOT isCurrent(): a timeout landing during a stall's
+    this.hardTimer = this.timerScope?.setTimeout(() => {
+      this.hardTimer = null;
+      // Deliberately NOT isCurrent(): a ceiling landing during a stall's
       // retry delay must still fire — the retry has not started a new
       // generation, and the budget is spent.
       if (this.settledFlag || this.disposed || gen !== this.generation) return;
@@ -697,9 +884,13 @@ class InProcessChildHandle implements DisposableChildHandle {
   }
 
   private clearTimers(): void {
-    if (this.timeoutTimer !== null) {
-      this.timerScope?.clearTimeout(this.timeoutTimer);
-      this.timeoutTimer = null;
+    if (this.softTimer !== null) {
+      this.timerScope?.clearTimeout(this.softTimer);
+      this.softTimer = null;
+    }
+    if (this.hardTimer !== null) {
+      this.timerScope?.clearTimeout(this.hardTimer);
+      this.hardTimer = null;
     }
     this.clearStall();
     this.clearRetryTimer();

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`);
     }