@bermudi/pi-delegate 0.1.9 → 0.1.11

package/quiescence.ts

@@ -0,0 +1,262 @@
+/**
+ * The post-prompt quiescence barrier.
+ *
+ * ## Why this exists
+ *
+ * `AgentSession.prompt()` can resolve while work it started is still running.
+ * Pi awaits `agent_settled` extension handlers, but an extension's handler is
+ * free to call `ctx.compact()` and return immediately — and in pi 0.84
+ * `ctx.compact()` is `void (async () => { … })()`. The session tracks that
+ * compaction in `isCompacting`, but it holds no promise for it, and the
+ * `onComplete` callback that fires afterwards may start a *continuation*
+ * prompt. So `await prompt()` is not "the session is done with my task".
+ *
+ * If the runner returned ownership at that point, lifecycle would dispose or
+ * re-pool a session that is still mutating files, spending tokens, and reading
+ * a context that disposal has already invalidated. See
+ * `docs/pi-codex-compaction-stale-context-defect.md`.
+ *
+ * ## Why it is a heuristic
+ *
+ * Pi exposes no primitive for "pending extension work" — no counter, no
+ * promise registry, no `hasPendingExtensionWork()`. `waitForIdle()` is not a
+ * substitute: `isIdle` is false only while a run is *active*, so a detached
+ * continuation that has not started yet is indistinguishable from one that
+ * will never start. All this barrier can observe is `isIdle`, `isCompacting`,
+ * and the session event stream.
+ *
+ * It therefore waits for **stability** rather than completion: the session must
+ * be idle, non-compacting, and event-quiet across N consecutive event-loop
+ * turns. Two turns matter because `compaction_end` is emitted *before*
+ * `ctx.compact`'s `onComplete` runs, and that callback may start a continuation
+ * in the very next turn.
+ *
+ * This is a **mitigation, not a proof**. A deterministic fix belongs upstream
+ * (make `ctx.compact()` awaitable, or expose pending extension work); until
+ * then, detached work that pauses longer than the grace period can still
+ * outlast the barrier.
+ *
+ * ## Bounded unwind
+ *
+ * While the task is healthy the barrier waits indefinitely — a legitimate
+ * remote compaction can take minutes, and cutting it short re-opens the
+ * disposal race. Unbounded waiting is safe there because the runner's stall
+ * watchdog is armed: a wedged session gets cancelled, which moves the barrier
+ * into its bounded mode.
+ *
+ * Once cancellation has been requested the session is supposed to be tearing
+ * down, so the wait is bounded by `cancelledUnwindBudgetMs`. Without a bound,
+ * an extension that keeps launching continuations keeps resetting progress and
+ * the barrier never returns — hanging the delegate task forever, which is
+ * strictly worse than reporting a cancelled task whose session may still be
+ * active. On expiry the barrier logs and returns `"abandoned"`.
+ */
+
+/** Why the runner asked the session to stop. */
+export type CancellationSource = "parent-aborted" | "stalled" | "deadline";
+
+/** The only session state the barrier observes. */
+export type QuiescenceObservable = {
+  readonly isIdle: boolean;
+  readonly isCompacting: boolean;
+};
+
+export type QuiescenceTimings = {
+  /** Consecutive unchanged event-loop turns required to declare quiescence. */
+  requiredQuietTurns: number;
+  /**
+   * One-shot wait, after cancellation, before quiet turns may accumulate. Two
+   * event-loop turns pass in microseconds — far faster than a continuation
+   * delayed by async auth — so without this the barrier would return before a
+   * delayed continuation ever became observable.
+   */
+  cancelledGraceMs: number;
+  /**
+   * Liveness fallback for host versions that clear an internal busy flag
+   * without emitting a corresponding public event. Normal transitions arrive
+   * as events, so this only bounds the pathological case.
+   */
+  eventProbeMs: number;
+  /** Ceiling on a cancelled unwind before the barrier gives up. */
+  cancelledUnwindBudgetMs: number;
+};
+
+export const DEFAULT_QUIESCENCE_TIMINGS: QuiescenceTimings = {
+  requiredQuietTurns: 2,
+  cancelledGraceMs: 50,
+  eventProbeMs: 250,
+  cancelledUnwindBudgetMs: 30_000,
+};
+
+/**
+ * `"quiescent"` — the session went idle and stayed quiet; ownership may be
+ * returned to the caller. `"abandoned"` — the cancelled-unwind budget expired
+ * while work was still starting; the caller regains ownership of a session
+ * that may still be active.
+ */
+export type QuiescenceOutcome = "quiescent" | "abandoned";
+
+export type QuiescenceBarrierOptions = {
+  session: QuiescenceObservable;
+  /** The active cancellation source, or `undefined` while the task is healthy. */
+  cancellation: () => CancellationSource | undefined;
+  /** Re-request cooperative cancellation of work that started post-cancellation. */
+  cancel: (source: CancellationSource) => void;
+  timings?: Partial<QuiescenceTimings>;
+  now?: () => number;
+  /** Overridable for tests; defaults to a `console.error` trace. */
+  onAbandon?: (info: {
+    source: CancellationSource;
+    waitedMs: number;
+    reAborts: number;
+  }) => void;
+};
+
+export type QuiescenceBarrier = {
+  /**
+   * Record any observed session event. Every event counts, including ones the
+   * runner ignores for progress: an event is evidence that something is alive.
+   */
+  noteEvent(): void;
+  /**
+   * Record that cooperative cancellation was just dispatched. Must be called
+   * *after* `session.abort()` is invoked, so events the abort itself emits
+   * synchronously are attributed to the abort rather than mistaken for new
+   * work.
+   */
+  noteCancellationRequested(): void;
+  /** Wait for stability. Safe to call more than once per task. */
+  wait(): Promise<QuiescenceOutcome>;
+};
+
+export function createQuiescenceBarrier(
+  options: QuiescenceBarrierOptions,
+): QuiescenceBarrier {
+  const { session, cancellation, cancel } = options;
+  const timings = { ...DEFAULT_QUIESCENCE_TIMINGS, ...options.timings };
+  const now = options.now ?? Date.now;
+  const onAbandon =
+    options.onAbandon ??
+    (({ source, waitedMs, reAborts }) => {
+      console.error(
+        `[delegate] quiescence barrier gave up after ${waitedMs}ms and ${reAborts} re-abort(s) unwinding a ${source} subagent; the session may still be running detached extension work`,
+      );
+    });
+
+  // Monotonic counter over observed session events. Comparing a sampled
+  // generation to the current one closes the race between "check session
+  // state" and "install the next waiter": an event that lands in between
+  // changes the generation, so it can never be missed.
+  let generation = 0;
+  let wake: (() => void) | undefined;
+  // Generation at the moment cancellation was last dispatched. Any later
+  // event means new work started despite the abort. -1 = never cancelled.
+  let cancelledAtGeneration = -1;
+
+  const noteEvent = () => {
+    generation++;
+    const pending = wake;
+    wake = undefined;
+    pending?.();
+  };
+
+  const sleep = (ms: number) =>
+    new Promise<void>((resolve) => setTimeout(resolve, ms));
+  const nextEventLoopTurn = () =>
+    new Promise<void>((resolve) => setImmediate(resolve));
+
+  /** Resolve on the next session event, or after the liveness probe. */
+  const waitForEventAfter = (sampled: number, probeMs: number) => {
+    if (generation !== sampled) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(probe);
+        if (wake === finish) wake = undefined;
+        resolve();
+      };
+      const probe = setTimeout(finish, probeMs);
+      if (generation !== sampled) {
+        finish();
+        return;
+      }
+      wake = finish;
+    });
+  };
+
+  const wait = async (): Promise<QuiescenceOutcome> => {
+    let quietTurns = 0;
+    let graceWaited = false;
+    let reAborts = 0;
+    let unwindStartedAt: number | undefined;
+    // Remaining cancelled-unwind budget, or Infinity while healthy. Timed
+    // waits are clamped to it so expiry is not overshot by a full probe.
+    let budgetLeft = Number.POSITIVE_INFINITY;
+
+    while (quietTurns < timings.requiredQuietTurns) {
+      const sampled = generation;
+      await nextEventLoopTurn();
+
+      const source = cancellation();
+      if (source) {
+        unwindStartedAt ??= now();
+        const waitedMs = now() - unwindStartedAt;
+        budgetLeft = timings.cancelledUnwindBudgetMs - waitedMs;
+        if (budgetLeft <= 0) {
+          onAbandon({ source, waitedMs, reAborts });
+          return "abandoned";
+        }
+
+        // Re-abort work that started after the last cancellation request —
+        // typically a continuation from an extension's onComplete callback,
+        // possibly delayed by async auth. Checked *before* the idle check so a
+        // fast continuation that already finished between samples is still
+        // caught: the generation moved even though the session is idle again.
+        // Re-aborting resets progress so any further continuation is seen too.
+        if (
+          cancelledAtGeneration >= 0 &&
+          generation !== cancelledAtGeneration
+        ) {
+          cancel(source);
+          reAborts++;
+          quietTurns = 0;
+          graceWaited = false;
+          continue;
+        }
+      }
+
+      const idle = session.isIdle && !session.isCompacting;
+      if (idle && generation === sampled) {
+        if (source && !graceWaited) {
+          // A single timed wait, not a busy-spin: the event loop stays free to
+          // process a delayed continuation's events while we sleep.
+          graceWaited = true;
+          await sleep(Math.min(timings.cancelledGraceMs, budgetLeft));
+          continue;
+        }
+        quietTurns++;
+        continue;
+      }
+
+      quietTurns = 0;
+      graceWaited = false;
+      if (!idle) {
+        await waitForEventAfter(
+          generation,
+          Math.min(timings.eventProbeMs, budgetLeft),
+        );
+      }
+    }
+    return "quiescent";
+  };
+
+  return {
+    noteEvent,
+    noteCancellationRequested: () => {
+      cancelledAtGeneration = generation;
+    },
+    wait,
+  };
+}

package/runner.ts

@@ -12,6 +12,10 @@ import { snapshotSessionUsage, usageDelta, emptyUsage } from "./usage.ts";
 import { getStallTimeoutMs } from "./config.ts";
 import { fmtDuration } from "./format.ts";
 import { scheduleDeadline } from "./timer.ts";
+import {
+  createQuiescenceBarrier,
+  type CancellationSource,
+} from "./quiescence.ts";
 import type { Usage } from "@earendil-works/pi-ai";
 import type {
   AgentProgressUpdate,
@@ -40,7 +44,7 @@ export function formatDeadlineExceededError(budgetMs: number): string {
  *      `AgentProgressUpdate` / `ToolActivity` shapes,
  *   2. wires the parent abort signal to `session.abort()`,
  *   3. waits for extension-started post-run compaction/continuations to become
- *      quiescent before returning ownership to lifecycle,
+ *      quiescent before returning ownership to lifecycle (`quiescence.ts`),
  *   4. snapshots usage before/after the prompt for token delta accounting, and
  *   5. computes touched files from activity + git diff.
  *
@@ -97,51 +101,26 @@ export async function runAgentSession(
   let prompted = false;
   const activities: ToolActivity[] = [];
   const pendingById = new Map<string, ToolActivity>();
-  let sessionEventGeneration = 0;
-  let wakeSessionEvent: (() => void) | undefined;
 
   // AgentSession.prompt() can return while an agent_settled extension callback
-  // is still running fire-and-forget work through ctx.compact(). Keep a small
-  // internal event seam so the runner can wait without polling throughout a
-  // potentially long remote compaction. The generation closes the race between
-  // checking session state and installing the next waiter.
-  let abortRequestedGeneration = -1;
-  const noteSessionEvent = () => {
-    sessionEventGeneration++;
-    const wake = wakeSessionEvent;
-    wakeSessionEvent = undefined;
-    wake?.();
-  };
-  const waitForSessionEventAfter = async (
-    generation: number,
-  ): Promise<void> => {
-    if (sessionEventGeneration !== generation) return;
-    await new Promise<void>((resolve) => {
-      let settled = false;
-      const probe = setTimeout(() => finish(), 250);
-      const finish = () => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(probe);
-        if (wakeSessionEvent === finish) wakeSessionEvent = undefined;
-        resolve();
-      };
-      if (sessionEventGeneration !== generation) {
-        finish();
-        return;
-      }
-      // AgentSession normally emits every transition we care about. The slow
-      // probe is a liveness fallback for host versions that clear an internal
-      // busy flag without a corresponding public event.
-      wakeSessionEvent = finish;
-    });
-  };
-  const nextEventLoopTurn = () =>
-    new Promise<void>((resolve) => setImmediate(resolve));
+  // is still running fire-and-forget work through ctx.compact(). The barrier
+  // owns the "is the session really done?" reasoning; see quiescence.ts for
+  // why it cannot be answered deterministically against today's host.
+  const barrier = createQuiescenceBarrier({
+    session,
+    cancellation: () =>
+      signal?.aborted
+        ? "parent-aborted"
+        : deadlineExceeded
+          ? "deadline"
+          : stalled
+            ? "stalled"
+            : undefined,
+    cancel: (source) => requestSessionCancellation(source),
+  });
+  const waitForSessionQuiescence = () => barrier.wait();
 
-  const requestSessionCancellation = (
-    source: "parent-aborted" | "stalled" | "deadline",
-  ): void => {
+  const requestSessionCancellation = (source: CancellationSource): void => {
     const logFailure = (operation: string, error: unknown) => {
       console.error(`[delegate] ${source} subagent ${operation} failed`, error);
     };
@@ -155,106 +134,19 @@ export async function runAgentSession(
     } catch (error) {
       logFailure("branch-summary cancellation", error);
     }
-    noteSessionEvent();
-    // Fire the abort before recording the generation. session.abort() may
-    // synchronously emit events (e.g. a final message_update as the stream
-    // unwinds) that increment the generation. Recording after the call
-    // ensures those abort-caused events are accounted for, so the quiescence
+    barrier.noteEvent();
+    // Fire the abort before recording the cancellation point. session.abort()
+    // may synchronously emit events (e.g. a final message_update as the stream
+    // unwinds); recording after the call attributes those to the abort, so the
     // barrier's re-abort check doesn't loop on the abort's own events.
     void session.abort().catch((error: unknown) => {
       logFailure("agent cancellation", error);
     });
-    // Record the generation after abort is dispatched. If new session events
-    // fire after this point (e.g. a continuation prompt started by an
-    // extension's onComplete callback delayed by async auth), the quiescence
-    // barrier re-aborts to cancel that continuation rather than letting it run
-    // — and potentially mutate files — after the task is considered cancelled.
-    abortRequestedGeneration = sessionEventGeneration;
-  };
-
-  /**
-   * Wait until the session is idle and non-compacting for two unchanged event
-   * loop turns. The quiet turns are significant: AgentSession emits
-   * compaction_end before ctx.compact's onComplete/onError callback runs, and a
-   * successful callback may immediately start a continuation prompt.
-   *
-   * Cancellation re-abort: if the task has been cancelled (parent abort or
-   * stall), any session event after the last cancellation request means new
-   * work started — typically a continuation from an extension's onComplete
-   * callback, possibly delayed by async auth. The barrier re-aborts to cancel
-   * it. This check runs *before* the idle check so a fast continuation that
-   * already completed between samples is still caught: the generation changed
-   * even though the session is idle again, and re-abort resets the tracker to
-   * catch any further continuations.
-   *
-   * Cancelled grace period: when cancelled and idle, a single 50 ms wait is
-   * required before quiet turns can accumulate. Without it, a continuation
-   * delayed by async auth or another extension handler can start after the
-   * runner returns — the two event-loop turns pass in microseconds, far faster
-   * than any realistic async-auth gap. This is a **mitigation, not a
-   * deterministic fix**: a deterministic solution would require the host to
-   * expose pending extension work (e.g. `AgentSession.hasPendingExtensionWork()`)
-   * so the barrier could wait on it explicitly. The grace period adds at most
-   * one 50 ms wait per cancellation/re-abort cycle — re-aborts reset the
-   * `graceWaited` flag, so a sequence of delayed continuations can cause
-   * multiple grace waits.
-   */
-  const waitForSessionQuiescence = async (): Promise<void> => {
-    const cancelledGraceMs = 50;
-    const cancellationRequested = () =>
-      signal?.aborted || stalled || deadlineExceeded;
-    const cancellationSource = (): "parent-aborted" | "stalled" | "deadline" =>
-      signal?.aborted
-        ? "parent-aborted"
-        : deadlineExceeded
-          ? "deadline"
-          : "stalled";
-    let quietTurns = 0;
-    let graceWaited = false;
-    while (quietTurns < 2) {
-      const generation = sessionEventGeneration;
-      await nextEventLoopTurn();
-
-      // Re-abort if new activity started after the last cancellation request.
-      // This runs before the idle check so a fast continuation that completed
-      // between samples (generation changed, session idle again) is still
-      // caught. After re-aborting, restart the loop to recompute isIdle/
-      // isCompacting rather than falling through to the 250 ms event probe.
-      if (
-        cancellationRequested() &&
-        abortRequestedGeneration >= 0 &&
-        sessionEventGeneration !== abortRequestedGeneration
-      ) {
-        requestSessionCancellation(cancellationSource());
-        quietTurns = 0;
-        graceWaited = false;
-        continue;
-      }
-
-      const idle = session.isIdle && !session.isCompacting;
-      if (idle && sessionEventGeneration === generation) {
-        if (cancellationRequested() && !graceWaited) {
-          // Wait once for a grace period before accepting quiet turns. A
-          // continuation delayed by async auth can start after the immediate
-          // microtask batch settles. This is a single setTimeout, not a
-          // busy-spin — the event loop is free to process the continuation's
-          // events during the wait.
-          graceWaited = true;
-          await new Promise<void>((resolve) =>
-            setTimeout(resolve, cancelledGraceMs),
-          );
-          continue;
-        }
-        quietTurns++;
-        continue;
-      }
-
-      quietTurns = 0;
-      graceWaited = false;
-      if (!idle) {
-        await waitForSessionEventAfter(sessionEventGeneration);
-      }
-    }
+    // Any session event after this point means new work started despite the
+    // abort (e.g. a continuation prompt from an extension's onComplete
+    // callback delayed by async auth). The barrier re-aborts it rather than
+    // letting it mutate files after the task is considered cancelled.
+    barrier.noteCancellationRequested();
   };
 
   // Snapshot cumulative usage before the prompt so we can report only the
@@ -527,7 +419,7 @@ export async function runAgentSession(
   // verbatim. Retry and compaction events are handled below; queue/bookkeeping
   // events and thinking changes are intentionally ignored.
   const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-    noteSessionEvent();
+    barrier.noteEvent();
     switch (event.type) {
       case "tool_execution_start": {
         const now = Date.now();