pi-famulus 0.1.2 → 0.1.4

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,12 +39,15 @@
  * steer/followUp processing.
  */
 import { realClock, TimerScope, type Clock, type ClockTimer } from "../clock";
+import type { OverrunTick } from "./overrun";
 import type {
+  ChildHandle,
   ChildResult,
   ChildRunRequest,
   ChildRunner,
   ChildSessionAdapter,
   ChildStatus,
+  ChildWallUsage,
   CreateSessionFn,
   DisposableChildHandle,
 } from "./types";
@@ -48,6 +58,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 +69,14 @@ 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;
+  /** Aborted when this generation settles while its admission is queued. */
+  signal: AbortSignal;
+}
+
 export interface InProcessRunnerOptions {
   createSession: CreateSessionFn;
   /** Stall watchdog timeout (ms). Default 10 minutes. */
@@ -67,14 +87,24 @@ 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;
   /**
    * Per-generation admission hook. Awaited before each (re)start; the
-   * resolved releaser is called when the generation settles. Rejecting
-   * cancels the generation as {status:"interrupted", error}.
+   * releaser gets terminal=false for a resumable interruption so its local
+   * slot can be returned while the child-owned machine permit is retained.
+   * Rejecting cancels the generation as {status:"interrupted", error}.
    */
-  acquire?: (req: ChildRunRequest) => Promise<() => void>;
+  acquire?: (req: ChildRunRequest, ticket: AdmissionTicket) => Promise<(terminal?: boolean) => void>;
   /**
    * Called after the child's conversation may have changed (a message or
    * tool finished, or the generation settled). Used to persist transcripts.
@@ -93,8 +123,9 @@ export class InProcessRunner implements ChildRunner {
     this.opts = opts;
   }
 
-  async start(req: ChildRunRequest): Promise<DisposableChildHandle> {
+  async start(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<DisposableChildHandle> {
     const handle = new InProcessChildHandle(req, this.opts);
+    onHandle?.(handle);
     await handle.launch();
     return handle;
   }
@@ -107,25 +138,39 @@ 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<(terminal?: boolean) => void>;
   private readonly onActivity?: (childId: string) => void;
 
   private session: ChildSessionAdapter | null = null;
+  private sessionCreation: Promise<ChildSessionAdapter> | null = null;
   private resolvedModel_: string | undefined;
   private unsubscribe: (() => void) | null = null;
   private status_: ChildStatus = "pending";
   private lastEvent: number;
-  /** Generation start (reset per generation; durationMs is relative to runStartedAt). */
+  /** Session start, set once and preserved across user resumes. */
   private startedAt: number;
   /** User-turn start: reset on launch and user resume(), not on stall retries. */
   private runStartedAt: number;
+  /** Timestamp when this generation acquired admission; durationMs is measured from here. */
+  private admittedAt: number | null;
   /**
-   * 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 +185,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;
@@ -148,10 +194,29 @@ class InProcessChildHandle implements DisposableChildHandle {
   private stallAttempts = 0;
   /** Generation retired by a stall detection awaiting its retry. */
   private retiredGen: number | null = null;
-  private releaseSlot: (() => void) | null = null;
+  private releaseSlot: ((terminal?: boolean) => void) | null = null;
+  private admissionAbort: AbortController | null = null;
+  /** Whether the current generation's settled result is terminal for this child. */
+  private terminalSettle = false;
   private disposed = false;
-  /** Nested tool_execution_start/end. Stall stays paused while > 0. */
+  private disposalPromise: Promise<void> | undefined;
+  /** Nested current-generation tool calls. Stall stays paused while > 0. */
   private toolDepth = 0;
+  /** Start generation by Pi toolCallId so late end events cannot close a new interval. */
+  private readonly toolCallGenerations = new Map<string, number>();
+  /** FIFO fallback for adapters that omit Pi's toolCallId (marked approximate). */
+  private readonly anonymousToolGenerations: number[] = [];
+  private wall: ChildWallUsage = { llmMs: 0, toolMs: 0, queueMs: 0, otherMs: 0, approximate: false };
+  private generationAt: number | null = null;
+  private generationLlmMs = 0;
+  private generationToolMs = 0;
+  private generationQueueMs = 0;
+  private queueStartedAt: number | null = null;
+  private queueGeneration: number | null = null;
+  /** Pending-abort drain before resume is unclassified wall time. */
+  private otherStartedAt: number | null = null;
+  private llmStartedAt: number | null = null;
+  private toolStartedAt: number | null = null;
   /** contact_supervisor need_decision. Stall stays paused while true. */
   private decisionPaused = false;
 
@@ -168,11 +233,21 @@ 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;
     this.startedAt = this.clock.now();
     this.runStartedAt = this.startedAt;
+    this.admittedAt = null;
     this.turnBudgetStart = this.startedAt;
     this.lastEvent = this.startedAt;
     this.resultPromise = new Promise((resolve) => {
@@ -201,7 +276,14 @@ class InProcessChildHandle implements DisposableChildHandle {
     return this.resolvedModel_ ?? this.session?.resolvedModel;
   }
 
-  /** Pause the stall watchdog (need_decision). Nested with tool execution. */
+  effectiveThinkingLevel(): string | undefined {
+    return this.session?.effectiveThinkingLevel;
+  }
+
+  /**
+   * 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,12 +293,39 @@ 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() {
     return this.session?.getConversation() ?? [];
   }
 
+  tokenUsage() {
+    return this.session?.tokenUsage() ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  }
+
+  wallUsage(): ChildWallUsage {
+    const now = this.clock.now();
+    const queueMs = this.queueStartedAt === null ? 0 : Math.max(0, now - this.queueStartedAt);
+    const llmMs = this.llmStartedAt === null ? 0 : Math.max(0, now - this.llmStartedAt);
+    const toolMs = this.toolStartedAt === null ? 0 : Math.max(0, now - this.toolStartedAt);
+    const elapsed = this.generationAt === null ? 0 : Math.max(0, now - this.generationAt);
+    const accounted = this.generationQueueMs + queueMs + this.generationLlmMs + llmMs + this.generationToolMs + toolMs;
+    const otherMs =
+      this.wall.otherMs +
+      Math.max(0, elapsed - accounted) +
+      (this.otherStartedAt === null ? 0 : Math.max(0, now - this.otherStartedAt));
+    return {
+      llmMs: this.wall.llmMs + llmMs,
+      toolMs: this.wall.toolMs + toolMs,
+      queueMs: this.wall.queueMs + queueMs,
+      otherMs,
+      approximate: this.wall.approximate || otherMs > this.wall.otherMs,
+    };
+  }
+
   /** Launch generation 1. Resolves once the prompt is issued (not completed). */
   async launch(): Promise<void> {
     await this.beginGeneration(this.req.prompt, true);
@@ -230,7 +339,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 +351,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,
+    };
+  }
+
+  /**
+   * 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);
   }
 
-  async resume(message: string): Promise<void> {
+  /**
+   * 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 +413,62 @@ 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.
+    this.admittedAt = null;
+    // 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.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) {
+      this.otherStartedAt = this.now();
+      const idle = await this.awaitAbortBounded(pendingAbort);
+      this.closeOther(this.now());
+      if (!idle) {
+        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 {
@@ -293,7 +478,8 @@ class InProcessChildHandle implements DisposableChildHandle {
     }
   }
 
-  dispose(): void {
+  dispose(): void | Promise<void> {
+    if (this.disposed) return this.disposalPromise;
     this.disposed = true;
     this.clearTimers();
     if (this.unsubscribe) {
@@ -306,15 +492,18 @@ class InProcessChildHandle implements DisposableChildHandle {
     }
     const session = this.session;
     this.session = null;
-    if (session) {
-      try {
-        session.dispose();
-      } catch {
-        // ignore
-      }
+    try {
+      this.disposalPromise = session
+        ? session.dispose() || undefined
+        : this.sessionCreation?.then((created) => created.dispose(), () => {});
+      return this.disposalPromise;
+    } finally {
+      // Never leave result waiters hanging, even when cleanup throws or awaits.
+      this.settle(this.generation, { status: "interrupted", text: "", error: "disposed", durationMs: 0 });
+      // settle() can be a no-op if the child was already interrupted; disposal
+      // is terminal and must still return its retained machine permit.
+      this.release(true);
     }
-    // Never leave result waiters hanging.
-    this.settle(this.generation, { status: "interrupted", text: "", error: "disposed", durationMs: 0 });
   }
 
   // -------------------------------------------------------------------------
@@ -326,26 +515,62 @@ 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> {
+    if (this.disposed) return;
+    // Stall retries replace a generation without settling the user turn.
+    if (reuseSlot) this.pruneToolCalls(this.generation);
+    // A resumed turn allocated its generation when it was requested.
+    const gen = resumedGen ?? ++this.generation;
     this.retiredGen = null;
     this.clearRetryTimer();
     this.timerScope?.dispose();
     this.timerScope = new TimerScope(this.clock);
     this.settledFlag = false;
+    this.terminalSettle = false;
     this.status_ = "pending";
     this.startedAt = this.clock.now();
     this.lastEvent = this.startedAt;
+    if (!reuseSlot) {
+      this.generationAt = this.startedAt;
+      this.generationLlmMs = 0;
+      this.generationToolMs = 0;
+      this.generationQueueMs = 0;
+      this.queueStartedAt = this.acquire ? this.startedAt : null;
+      this.queueGeneration = this.queueStartedAt === null ? null : gen;
+      this.llmStartedAt = null;
+      this.toolStartedAt = null;
+    }
     // A tool_execution_end from the previous generation may have been dropped
     // after settle. Don't carry that depth (or a pending decision) into this one.
     this.toolDepth = 0;
     this.decisionPaused = false;
 
+    if (!reuseSlot) this.generationQueueMs = 0;
     if (this.acquire && !reuseSlot) {
+      const admissionAbort = new AbortController();
+      this.admissionAbort = admissionAbort;
       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.
+        const release = await this.acquire(this.req, {
+          current: () => !this.disposed && !this.isSettled(gen),
+          signal: admissionAbort.signal,
+        });
+        if (this.disposed || this.isSettled(gen)) {
+          // A queued interruption is resumable; only disposal is terminal.
+          release(this.disposed);
+          return;
+        }
+        this.releaseSlot = release;
       } catch (err) {
         // Admission denied (e.g. fail_fast cancellation while queued).
+        this.closeQueue(this.now(), gen);
         this.settle(gen, {
           status: "interrupted",
           text: "",
@@ -353,18 +578,30 @@ class InProcessChildHandle implements DisposableChildHandle {
           durationMs: this.now() - this.startedAt,
         });
         return;
+      } finally {
+        if (gen === this.generation) {
+          // closeQueue()/settle() accounts for this interval exactly once;
+          // the finally block only clears state owned by the current generation.
+          if (this.admissionAbort === admissionAbort) this.admissionAbort = null;
+        }
       }
+      this.closeQueue(this.now(), gen);
     }
     if (this.disposed || this.isSettled(gen)) {
-      this.release();
+      this.release(this.terminalSettle);
       return;
     }
+    if (!reuseSlot) this.admittedAt = this.now();
     this.status_ = "running";
 
     if (first) {
       try {
-        this.session = await this.createSession(this.req);
-        this.resolvedModel_ = this.session.resolvedModel;
+        this.sessionCreation = this.createSession(this.req);
+        const created = await this.sessionCreation;
+        // dispose() owns cleanup of an adapter that resolves after teardown.
+        if (this.disposed) return;
+        this.session = created;
+        this.resolvedModel_ = created.resolvedModel;
       } catch (err) {
         this.settle(gen, {
           status: "failed",
@@ -373,34 +610,14 @@ class InProcessChildHandle implements DisposableChildHandle {
           durationMs: this.now() - this.startedAt,
         });
         return;
+      } finally {
+        this.sessionCreation = null;
       }
       if (this.disposed || this.isSettled(gen)) {
         this.release();
         return;
       }
-      this.unsubscribe = this.session.subscribe((event) => {
-        if (event.type === "message_end" || event.type === "tool_execution_end" || event.type === "agent_end") {
-          this.notifyActivity();
-        }
-        // Track depth even after settle. A late tool_execution_end must not
-        // leak into the next resume, and must not rearm a stale generation.
-        if (event.type === "tool_execution_start") {
-          this.toolDepth++;
-          if (this.status_ === "running") this.clearStall();
-          return;
-        }
-        if (event.type === "tool_execution_end") {
-          this.toolDepth = Math.max(0, this.toolDepth - 1);
-          this.lastEvent = this.now();
-          if (this.status_ === "running" && this.toolDepth === 0 && !this.decisionPaused) {
-            this.armStall(this.generation);
-          }
-          return;
-        }
-        if (this.status_ !== "running") return;
-        this.lastEvent = this.now();
-        if (this.toolDepth === 0 && !this.decisionPaused) this.armStall(this.generation);
-      });
+      this.unsubscribe = this.session.subscribe((event) => this.handleSessionEvent(event));
     }
 
     const session = this.session;
@@ -414,13 +631,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 =
@@ -495,7 +718,19 @@ class InProcessChildHandle implements DisposableChildHandle {
 
   private settle(gen: number, result: ChildResult): void {
     if (gen !== this.generation || this.settledFlag) return;
+    const at = this.now();
+    this.pruneToolCalls(gen);
+    const queueMs = this.generationQueueMs + (
+      this.queueStartedAt !== null && this.queueGeneration === gen
+        ? Math.max(0, at - this.queueStartedAt)
+        : 0
+    );
+    if (result.queueMs === undefined && queueMs > 0) result.queueMs = queueMs;
+    this.closeOther(at);
+    this.finishWallGeneration(at, gen);
     this.settledFlag = true;
+    this.admissionAbort?.abort();
+    this.admissionAbort = null;
     this.clearTimers();
     // Generations run: 1 + resumes + stall retries. Forensics for the
     // incident class this exists for (a stalled child that needed retries).
@@ -503,9 +738,14 @@ class InProcessChildHandle implements DisposableChildHandle {
     if (result.attempts === undefined && this.generation > 1) {
       result.attempts = this.generation;
     }
-    // durationMs covers the whole user turn (launch/resume -> settle),
-    // including time lost to stalls and retry delays. dispose keeps its 0.
-    if (result.error !== "disposed") result.durationMs = this.now() - this.runStartedAt;
+    // durationMs covers admitted execution (including stalls and retry delays),
+    // but excludes time waiting for an admission slot. dispose keeps its 0.
+    if (result.error !== "disposed") {
+      result.durationMs = this.admittedAt === null ? 0 : Math.max(0, this.now() - this.admittedAt);
+    }
+    result.queueMs = this.admittedAt === null
+      ? Math.max(0, this.now() - this.runStartedAt)
+      : Math.max(0, this.admittedAt - this.runStartedAt);
     if (result.stalls === undefined && this.stallAttempts > 0) {
       result.stalls = this.stallAttempts;
     }
@@ -516,7 +756,8 @@ class InProcessChildHandle implements DisposableChildHandle {
       result.warning = this.session.warning;
     }
     this.status_ = result.status;
-    this.release();
+    this.terminalSettle = result.status !== "interrupted" || result.error === "disposed";
+    this.release(this.terminalSettle);
     this.notifyActivity();
     this.resolveResult(result);
   }
@@ -529,28 +770,245 @@ class InProcessChildHandle implements DisposableChildHandle {
     }
   }
 
-  private release(): void {
+  private pruneToolCalls(gen: number): void {
+    for (const [toolCallId, generation] of this.toolCallGenerations) {
+      if (generation === gen) this.toolCallGenerations.delete(toolCallId);
+    }
+    for (let i = this.anonymousToolGenerations.length - 1; i >= 0; i--) {
+      if (this.anonymousToolGenerations[i] === gen) this.anonymousToolGenerations.splice(i, 1);
+    }
+  }
+
+  private closeQueue(at: number, gen: number): void {
+    if (this.queueStartedAt === null || this.queueGeneration !== gen) return;
+    const elapsed = Math.max(0, at - this.queueStartedAt);
+    this.wall.queueMs += elapsed;
+    this.generationQueueMs += elapsed;
+    this.queueStartedAt = null;
+    this.queueGeneration = null;
+  }
+
+  private closeLlm(at: number): void {
+    if (this.llmStartedAt === null) return;
+    const elapsed = Math.max(0, at - this.llmStartedAt);
+    this.wall.llmMs += elapsed;
+    this.generationLlmMs += elapsed;
+    this.llmStartedAt = null;
+  }
+
+  private closeTool(at: number): void {
+    if (this.toolStartedAt === null) return;
+    const elapsed = Math.max(0, at - this.toolStartedAt);
+    this.wall.toolMs += elapsed;
+    this.generationToolMs += elapsed;
+    this.toolStartedAt = null;
+  }
+
+  private closeOther(at: number): void {
+    if (this.otherStartedAt === null) return;
+    const elapsed = Math.max(0, at - this.otherStartedAt);
+    this.wall.otherMs += elapsed;
+    if (elapsed > 0) this.wall.approximate = true;
+    this.otherStartedAt = null;
+  }
+
+  private accountWallEvent(event: { type: string; role?: string; usage?: { input: number; output: number } }, at: number): void {
+    const assistant = event.role === "assistant" || (event.role === undefined && event.usage !== undefined);
+    if (event.type === "message_start" && assistant) {
+      if (this.toolDepth === 0 && this.llmStartedAt === null) this.llmStartedAt = at;
+      else this.wall.approximate = true;
+    } else if (event.type === "message_end" && assistant) {
+      if (this.llmStartedAt === null) this.wall.approximate = true;
+      else this.closeLlm(at);
+    } else if (event.type === "tool_execution_start") {
+      if (this.toolDepth === 0) {
+        if (this.llmStartedAt !== null) {
+          this.closeLlm(at);
+          this.wall.approximate = true;
+        }
+        this.toolStartedAt = at;
+      }
+    } else if (event.type === "tool_execution_end") {
+      if (this.toolDepth === 0) this.wall.approximate = true;
+      else if (this.toolDepth === 1) this.closeTool(at);
+    }
+  }
+
+  private finishWallGeneration(at: number, gen: number): void {
+    this.closeQueue(at, gen);
+    if (this.llmStartedAt !== null) {
+      this.closeLlm(at);
+      this.wall.approximate = true;
+    }
+    if (this.toolStartedAt !== null) {
+      this.closeTool(at);
+      this.wall.approximate = true;
+    }
+    if (this.generationAt !== null) {
+      const elapsed = Math.max(0, at - this.generationAt);
+      const measured = this.generationQueueMs + this.generationLlmMs + this.generationToolMs;
+      const other = Math.max(0, elapsed - measured);
+      this.wall.otherMs += other;
+      if (other > 0) this.wall.approximate = true;
+    }
+    this.generationAt = null;
+    this.generationLlmMs = 0;
+    this.generationToolMs = 0;
+    this.generationQueueMs = 0;
+    this.queueStartedAt = null;
+    this.queueGeneration = null;
+    this.llmStartedAt = null;
+    this.toolStartedAt = null;
+  }
+
+  private handleSessionEvent(event: { type: string; role?: string; toolCallId?: string; usage?: { input: number; output: number } }): void {
+    const now = this.now();
+    const active = this.status_ === "running";
+    let currentToolEvent = false;
+    if (event.type === "tool_execution_start" && active) {
+      if (event.toolCallId) {
+        if (this.toolCallGenerations.has(event.toolCallId)) {
+          this.wall.approximate = true;
+        } else {
+          this.toolCallGenerations.set(event.toolCallId, this.generation);
+          currentToolEvent = true;
+        }
+      } else {
+        // Pi emits toolCallId; retain generation ownership for older adapters
+        // too, but mark their FIFO pairing as approximate.
+        this.anonymousToolGenerations.push(this.generation);
+        this.wall.approximate = true;
+        currentToolEvent = true;
+      }
+    } else if (event.type === "tool_execution_end") {
+      if (event.toolCallId) {
+        const generation = this.toolCallGenerations.get(event.toolCallId);
+        this.toolCallGenerations.delete(event.toolCallId);
+        currentToolEvent = active && generation === this.generation;
+        if (active && generation === undefined) this.wall.approximate = true;
+      } else {
+        const generation = this.anonymousToolGenerations.shift();
+        currentToolEvent = active && generation === this.generation;
+        if (active && !currentToolEvent) this.wall.approximate = true;
+      }
+    }
+    if (active && (!event.type.startsWith("tool_execution_") || currentToolEvent)) {
+      this.accountWallEvent(event, now);
+    }
+    if (
+      ["message_end", "tool_execution_end", "agent_end"].includes(event.type) ||
+      (active && ["message_start", "tool_execution_start"].includes(event.type))
+    ) {
+      this.notifyActivity();
+    }
+    if (event.type === "tool_execution_start") {
+      if (currentToolEvent) {
+        this.toolDepth++;
+        this.clearStall();
+      }
+      return;
+    }
+    if (event.type === "tool_execution_end") {
+      if (currentToolEvent) {
+        this.toolDepth = Math.max(0, this.toolDepth - 1);
+        this.lastEvent = now;
+        if (this.toolDepth === 0 && !this.decisionPaused) this.armStall(this.generation);
+      }
+      return;
+    }
+    if (!active) return;
+    this.lastEvent = now;
+    if (this.toolDepth === 0 && !this.decisionPaused) this.armStall(this.generation);
+  }
+
+  private release(terminal = true): void {
     const release = this.releaseSlot;
-    this.releaseSlot = null;
+    if (terminal) this.releaseSlot = null;
     if (release) {
       try {
-        release();
+        release(terminal);
       } catch {
         // ignore
       }
     }
   }
 
-  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;
+  }
+
+  collectDueOverrun(now: number): OverrunTick | undefined {
+    if (this.settledFlag || this.disposed || this.status_ !== "running" || this.decisionPaused || this.softDeadlineAt === null) return undefined;
+    if (this.softDeadlineAt > now || this.nextReminderAt === null || this.nextReminderAt > now) return undefined;
+    if (this.softTimer !== null) this.timerScope?.clearTimeout(this.softTimer);
+    this.softTimer = null;
+    this.reminders++;
+    this.nextReminderAt = now + this.overrunRepeatMs;
+    this.armSoftDeadline(this.generation);
+    return {
+      childId: this.req.childId,
+      elapsedMs: now - this.turnBudgetStart,
+      budgetMs: this.softDeadlineAt - this.turnBudgetStart,
+      reminder: this.reminders,
+      nextReminderMs: this.overrunRepeatMs,
+      lastEventAt: this.lastEvent,
+      hardRemainingMs: this.hardTimeoutMs > 0 ? Math.max(0, this.turnBudgetStart + this.hardTimeoutMs - now) : 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
+    }
+    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.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);
+    if (!(this.hardTimeoutMs > 0)) return;
+    const remaining = this.hardTimeoutMs - (this.now() - this.turnBudgetStart);
     if (remaining <= 0) {
       this.settle(gen, {
         status: "interrupted",
@@ -560,9 +1018,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;
@@ -599,6 +1057,10 @@ class InProcessChildHandle implements DisposableChildHandle {
    */
   private handleStall(gen: number): void {
     this.stallAttempts++;
+    if (this.llmStartedAt !== null) {
+      this.closeLlm(this.now());
+      this.wall.approximate = true;
+    }
     // Persist whatever the stalled generation produced before it went quiet.
     this.notifyActivity();
     try {
@@ -697,9 +1159,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();