@bermudi/pi-delegate 0.1.13 → 0.1.15

package/runner.ts

@@ -5,7 +5,10 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   getGitChangedFiles,
+  extractAttributedFromActivities,
   extractTouchedFromActivities,
+  projectedAttributionPath,
+  snapshotPhysicalToolTarget,
 } from "./file-tracking.ts";
 import { extractTextFromPartialResult, extractOutput } from "./utils.ts";
 import { snapshotSessionUsage, usageDelta, emptyUsage } from "./usage.ts";
@@ -15,14 +18,27 @@ import { scheduleDeadline } from "./timer.ts";
 import {
   createQuiescenceBarrier,
   type CancellationSource,
+  type QuiescenceBarrier,
 } from "./quiescence.ts";
+import { markSessionQuarantined } from "./session-quarantine.ts";
 import type { Usage } from "@earendil-works/pi-ai";
 import type {
   AgentProgressUpdate,
+  FileAttribution,
   TaskFailureKind,
   ToolActivity,
 } from "./types.ts";
 
+let quiescenceTimingsForTesting:
+  Partial<import("./quiescence.ts").QuiescenceTimings> | undefined;
+
+/** @internal Test-only timings for forcing the bounded abandonment path. */
+export function _setRunnerQuiescenceTimingsForTesting(
+  timings: Partial<import("./quiescence.ts").QuiescenceTimings> | undefined,
+): void {
+  quiescenceTimingsForTesting = timings;
+}
+
 /** Human-facing error for an expired `deadlineMs` budget.
  *
  * This is exported so the lifecycle pre-check can return the same text as the
@@ -33,6 +49,43 @@ export function formatDeadlineExceededError(budgetMs: number): string {
   )} wall-clock budget and was cooperatively aborted (not a hard kill). Completed writes and commands remain.`;
 }
 
+function unionGitEvidence(
+  first: Set<string> | undefined,
+  second: Set<string> | undefined,
+): Set<string> | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  return new Set([...first, ...second]);
+}
+
+function cancellationFailureKind(
+  source: CancellationSource | undefined,
+): TaskFailureKind | undefined {
+  if (source === "parent-aborted") return "cancelled";
+  if (source === "deadline") return "deadline_exceeded";
+  if (source === "stalled") return "stalled";
+  return undefined;
+}
+
+/** Apply cancellation precedence without obscuring it in nested conditionals. */
+function resolveRunFailure(
+  source: CancellationSource | undefined,
+  fallbackError: string | undefined,
+  deadlineError: () => string,
+  stallError: () => string,
+): { error: string | undefined; failureKind: TaskFailureKind | undefined } {
+  if (source === "parent-aborted") {
+    return { error: "Aborted", failureKind: "cancelled" };
+  }
+  if (source === "deadline") {
+    return { error: deadlineError(), failureKind: "deadline_exceeded" };
+  }
+  if (source === "stalled") {
+    return { error: stallError(), failureKind: "stalled" };
+  }
+  return { error: fallbackError, failureKind: undefined };
+}
+
 /**
  * Run a single prompt against a live `AgentSession` and report progress.
  *
@@ -84,11 +137,16 @@ export async function runAgentSession(
   touchedFiles: string[];
   /** Files directly attributable to this run's edit/write tool calls. */
   attributedFiles: string[];
+  /** Provenance-bearing evidence behind attributedFiles. */
+  fileAttributions: FileAttribution[];
   failureKind?: TaskFailureKind;
   /** Whether `session.prompt()` was actually invoked. Distinguishes a pre-prompt
    *  deadline (session never used) from a mid-prompt deadline (session was
    *  prompted and may have partial state mutations). */
   prompted: boolean;
+  /** Quiescence was abandoned. All returned accounting and evidence are lower
+   * bounds captured before quarantined background work became safe. */
+  incomplete?: "quiescence_abandoned";
 }> {
   const startTime = start ?? Date.now();
   const stallTimeoutMs = getStallTimeoutMs(delegateConfig);
@@ -101,8 +159,58 @@ export async function runAgentSession(
   let deadlineExceeded = false;
   let clearDeadline: (() => void) | undefined;
   let prompted = false;
+  let cancellationDispatched = false;
+  let promptSettled = false;
+  let promptSettlement:
+    | Promise<
+        | { status: "not_started" | "fulfilled" }
+        | { status: "rejected"; error: unknown }
+      >
+    | undefined;
+  const currentCancellationSource = (): CancellationSource | undefined => {
+    if (signal?.aborted) return "parent-aborted";
+    if (deadlineExceeded) return "deadline";
+    if (stalled) return "stalled";
+    return undefined;
+  };
+  let recoveryBarrier: QuiescenceBarrier | undefined;
+  let abandonmentSafety: Promise<void> | undefined;
+  let unsubscribeFull: (() => void) | undefined;
+  let unsubscribeRecovery: (() => void) | undefined;
+  const safeLog = (message: string, error?: unknown): void => {
+    try {
+      console.error(message, error);
+    } catch {
+      // Recovery and listener cleanup must never create an unhandled failure.
+    }
+  };
+  const removeFullListener = (): void => {
+    const remove = unsubscribeFull;
+    unsubscribeFull = undefined;
+    try {
+      remove?.();
+    } catch (error) {
+      safeLog("[delegate] full AgentSession listener cleanup failed", error);
+    }
+  };
+  const removeRecoveryListener = (): void => {
+    const remove = unsubscribeRecovery;
+    unsubscribeRecovery = undefined;
+    try {
+      remove?.();
+    } catch (error) {
+      safeLog(
+        "[delegate] recovery AgentSession listener cleanup failed",
+        error,
+      );
+    }
+  };
   const activities: ToolActivity[] = [];
   const pendingById = new Map<string, ToolActivity>();
+  let notifyCancellationRequested!: () => void;
+  const cancellationRequested = new Promise<void>((resolve) => {
+    notifyCancellationRequested = resolve;
+  });
 
   // AgentSession.prompt() can return while an agent_settled extension callback
   // is still running fire-and-forget work through ctx.compact(). The barrier
@@ -110,21 +218,34 @@ export async function runAgentSession(
   // why it cannot be answered deterministically against today's host.
   const barrier = createQuiescenceBarrier({
     session,
-    cancellation: () =>
-      signal?.aborted
-        ? "parent-aborted"
-        : deadlineExceeded
-          ? "deadline"
-          : stalled
-            ? "stalled"
-            : undefined,
+    timings: quiescenceTimingsForTesting,
+    cancellation: currentCancellationSource,
     cancel: (source) => requestSessionCancellation(source),
   });
-  const waitForSessionQuiescence = () => barrier.wait();
+  // Once the bounded cancelled unwind gives up, do not start another full
+  // unwind budget later in the same runner. The session may still be active,
+  // but cancellation has an explicit terminal path instead of repeatedly
+  // waiting on work that the host cannot prove has stopped.
+  let sessionAbandoned = false;
+  let startAbandonedRecovery!: (source: CancellationSource) => Promise<void>;
+  const quarantineSession = (source: CancellationSource): void => {
+    if (sessionAbandoned) return;
+    sessionAbandoned = true;
+    abandonmentSafety ??= startAbandonedRecovery(source);
+  };
+  const waitForSessionQuiescence = async () => {
+    if (sessionAbandoned) return "abandoned" as const;
+    const outcome = await barrier.wait();
+    if (outcome === "abandoned") {
+      quarantineSession(currentCancellationSource() ?? "stalled");
+    }
+    return outcome;
+  };
 
   const requestSessionCancellation = (source: CancellationSource): void => {
+    cancellationDispatched = true;
     const logFailure = (operation: string, error: unknown) => {
-      console.error(`[delegate] ${source} subagent ${operation} failed`, error);
+      safeLog(`[delegate] ${source} subagent ${operation} failed`, error);
     };
     try {
       session.abortCompaction();
@@ -141,14 +262,103 @@ export async function runAgentSession(
     // 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) => {
+    try {
+      void session.abort().catch((error: unknown) => {
+        logFailure("agent cancellation", error);
+      });
+    } catch (error) {
+      // Some host fakes/versions can throw before returning the abort promise.
+      // Continue recording cancellation so the quarantine path still engages.
       logFailure("agent cancellation", error);
-    });
+    }
     // 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();
+    // Wake the prompt race only after every cooperative cancellation request
+    // has been dispatched and the barrier knows its cancellation generation.
+    notifyCancellationRequested();
+  };
+
+  startAbandonedRecovery = (source) => {
+    safeLog(
+      `[delegate] QUARANTINING ${source} AgentSession after quiescence abandonment; it will not be reused, disposed, or have its workspace cleaned until background termination confirms safety`,
+    );
+
+    try {
+      recoveryBarrier = createQuiescenceBarrier({
+        session,
+        cancellation: () => source,
+        // Recovery is deliberately unbounded. If the host never proves safety,
+        // the quarantine and its workspace live forever rather than racing work.
+        timings: { cancelledUnwindBudgetMs: Number.POSITIVE_INFINITY },
+        // A permanent quarantine is an intentional leak, not a reason to keep a
+        // headless Node process alive forever on its liveness probe.
+        unrefTimers: true,
+        cancel: (nextSource) => {
+          requestSessionCancellation(nextSource);
+          recoveryBarrier?.noteCancellationRequested();
+        },
+        onAbandon: () => {
+          // Infinity above makes this unreachable; keep fail-closed semantics if
+          // timing arithmetic ever changes.
+        },
+      });
+
+      // Freeze user-visible output/progress at the terminal result boundary.
+      // Recovery needs only event generation; retaining the full listener
+      // would mutate returned evidence and emit stale terminal progress.
+      unsubscribeRecovery = session.subscribe(() =>
+        recoveryBarrier?.noteEvent(),
+      );
+      removeFullListener();
+
+      requestSessionCancellation(source);
+      recoveryBarrier.noteCancellationRequested();
+    } catch (error) {
+      removeFullListener();
+      removeRecoveryListener();
+      safeLog(
+        `[delegate] quarantined ${source} AgentSession recovery setup failed; retaining session and workspace indefinitely`,
+        error,
+      );
+      return new Promise<void>(() => {});
+    }
+
+    const recovery = (async () => {
+      // Keep actively re-aborting while an ignored prompt/provider call winds
+      // down. A first quiet observation is not enough if prompt() itself is
+      // unresolved; after it settles, require a fresh quiet window.
+      await Promise.all([
+        promptSettlement ?? Promise.resolve({ status: "not_started" as const }),
+        recoveryBarrier!.wait(),
+      ]);
+      await recoveryBarrier!.wait();
+      safeLog(
+        `[delegate] quarantined ${source} AgentSession is now quiescent; deferred disposal and workspace cleanup may proceed`,
+      );
+      removeRecoveryListener();
+    })().catch((error) => {
+      safeLog(
+        `[delegate] quarantined ${source} AgentSession background termination failed; retaining session and workspace indefinitely`,
+        error,
+      );
+      // Never resolve safety after an observer failure: leaking is safer than
+      // allowing disposal or filesystem teardown to race unknown live work.
+      return new Promise<void>(() => {});
+    });
+    return recovery;
+  };
+
+  const finishResult = <T extends object>(
+    result: T,
+  ): T & { incomplete?: "quiescence_abandoned" } => {
+    if (!abandonmentSafety) return result;
+    return markSessionQuarantined(
+      { ...result, incomplete: "quiescence_abandoned" as const },
+      { safe: abandonmentSafety },
+    );
   };
 
   // Snapshot cumulative usage before the prompt so we can report only the
@@ -165,19 +375,14 @@ export async function runAgentSession(
     if (!onProgress) return;
     const delta = currentUsage().totalTokens;
     try {
+      const cancellationSource = currentCancellationSource();
       onProgress({
         tokens: delta,
         toolUses,
         durationMs: Date.now() - startTime,
         lastActivityAt,
         activities: [...activities],
-        failureKind: signal?.aborted
-          ? undefined
-          : deadlineExceeded
-            ? "deadline_exceeded"
-            : stalled
-              ? "stalled"
-              : undefined,
+        failureKind: cancellationFailureKind(cancellationSource),
       });
     } catch (error) {
       console.error("[delegate] progress callback threw; continuing", error);
@@ -420,8 +625,9 @@ export async function runAgentSession(
   // result, isError) — AgentSession forwards the underlying agent events
   // verbatim. Retry and compaction events are handled below; queue/bookkeeping
   // events and thinking changes are intentionally ignored.
-  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+  unsubscribeFull = session.subscribe((event: AgentSessionEvent) => {
     barrier.noteEvent();
+    recoveryBarrier?.noteEvent();
     switch (event.type) {
       case "tool_execution_start": {
         const now = Date.now();
@@ -431,6 +637,15 @@ export async function runAgentSession(
           args: event.args,
           startTime: now,
         };
+        if (event.toolName === "edit" || event.toolName === "write") {
+          // AgentSession emits this boundary synchronously before invoking the
+          // tool. Capture the physical target now: after execution a tool can
+          // delete or retarget the symlink it wrote through.
+          activity.fileAttribution = snapshotPhysicalToolTarget(
+            activity,
+            config.cwd,
+          );
+        }
         pendingById.set(event.toolCallId, activity);
         activities.push(activity);
         noteActivity(`executing tool '${event.toolName}'`);
@@ -578,14 +793,16 @@ export async function runAgentSession(
   // can still start a subagent that writes files and gets pooled.
   if (signal?.aborted) {
     abortHandler?.();
-    // The early return skips the try/finally below, so clean up the
-    // subscription and abort listener here — otherwise they leak on every
-    // already-aborted call, which is especially harmful for pooled sessions
-    // whose subscription would outlive the task.
+    // A pooled session can still have extension-started work even though this
+    // runner never prompts it. Use the same bounded cancelled unwind as every
+    // other cancellation path before returning ownership.
+    await waitForSessionQuiescence();
+    // The early return skips the try/finally below. The abandonment path has
+    // already replaced the full listener with its minimal recovery listener.
     if (signal && abortHandler)
       signal.removeEventListener("abort", abortHandler);
-    unsubscribe();
-    return {
+    removeFullListener();
+    return finishResult({
       output: "",
       error: "Aborted",
       durationMs: Date.now() - startTime,
@@ -593,8 +810,10 @@ export async function runAgentSession(
       usage: emptyUsage(),
       touchedFiles: [],
       attributedFiles: [],
+      fileAttributions: [],
+      failureKind: "cancelled" as const,
       prompted: false,
-    };
+    });
   }
 
   // If the deadline is already in the past, request cooperative cancellation
@@ -616,9 +835,9 @@ export async function runAgentSession(
     clearDeadlineWatchdog();
     if (signal && abortHandler)
       signal.removeEventListener("abort", abortHandler);
-    unsubscribe();
+    removeFullListener();
     if (signal?.aborted) {
-      return {
+      return finishResult({
         output: "",
         error: "Aborted",
         durationMs: Date.now() - startTime,
@@ -626,10 +845,12 @@ export async function runAgentSession(
         usage: emptyUsage(),
         touchedFiles: [],
         attributedFiles: [],
+        fileAttributions: [],
+        failureKind: "cancelled" as const,
         prompted: false,
-      };
+      });
     }
-    return {
+    return finishResult({
       output: "(no output)",
       error: deadlineError(),
       durationMs: Date.now() - startTime,
@@ -637,9 +858,10 @@ export async function runAgentSession(
       usage: emptyUsage(),
       touchedFiles: [],
       attributedFiles: [],
-      failureKind: "deadline_exceeded",
+      fileAttributions: [],
+      failureKind: "deadline_exceeded" as const,
       prompted: false,
-    };
+    });
   }
 
   try {
@@ -649,9 +871,48 @@ export async function runAgentSession(
     armDeadlineWatchdog();
     fireProgress();
 
-    prompted = true;
-    await session.prompt(prompt);
+    // AgentSession.abort() normally settles prompt(), but providers/tools can
+    // ignore cancellation and leave that promise pending forever. Race prompt
+    // settlement against cancellation, then use the barrier's bounded unwind.
+    // Prompt start is queued, so a cancellation dispatched in that window must be checked
+    // again inside the queued callback; otherwise the runner can return while
+    // that callback starts a newly cancelled prompt. Rejections are converted
+    // to data so a late rejection after abandonment cannot become an unhandled
+    // promise rejection.
+    promptSettlement = Promise.resolve()
+      .then(async () => {
+        if (cancellationDispatched) return { status: "not_started" as const };
+        prompted = true;
+        try {
+          await session.prompt(prompt);
+          return { status: "fulfilled" as const };
+        } catch (error) {
+          return { status: "rejected" as const, error };
+        }
+      })
+      .then((outcome) => {
+        promptSettled = true;
+        return outcome;
+      });
+    const promptOutcome = await Promise.race([
+      promptSettlement,
+      cancellationRequested.then(() => ({ status: "cancelled" as const })),
+    ]);
+    if (promptOutcome.status === "rejected") {
+      // A rejected prompt can still have fired agent_settled extension work.
+      // Keep ownership until that work is quiescent before routing the prompt
+      // error through the evidence-preserving catch path below. If cancellation
+      // arrived too, this remains the same bounded unwind/quarantine boundary.
+      await waitForSessionQuiescence();
+      throw promptOutcome.error;
+    }
     await waitForSessionQuiescence();
+    if (promptOutcome.status === "cancelled" && !promptSettled) {
+      // isIdle/quiescence can lie while a provider/tool keeps prompt() pending.
+      // Returning that object to lifecycle would permit reuse or disposal while
+      // ignored work still owns it, so force the existing quarantine recovery.
+      quarantineSession(currentCancellationSource() ?? "stalled");
+    }
 
     // The model is done; inactivity is no longer the right watchdog. Git
     // evidence collection can take several seconds (up to 5s per git call),
@@ -661,7 +922,7 @@ export async function runAgentSession(
     phase = "collecting git evidence";
     lastActivityAt = Date.now();
 
-    const gitAfter = await getGitChangedFiles(config.cwd);
+    let gitAfter = await getGitChangedFiles(config.cwd);
     if (deadlineAt && Date.now() >= deadlineAt && !deadlineExceeded) {
       abortForDeadline();
     }
@@ -671,7 +932,17 @@ export async function runAgentSession(
     // cancellation is still unwinding. Wait for the same quiescence barrier so
     // lifecycle does not dispose/reuse the session while compaction or an
     // extension callback is still active.
-    if (deadlineExceeded || signal?.aborted) await waitForSessionQuiescence();
+    if (currentCancellationSource()) {
+      await waitForSessionQuiescence();
+      // Cancellation unwind can mutate files after the first Git snapshot.
+      // Recollect only after the final bounded quiescence decision and union
+      // both observations: a later failure or reverted file must not erase
+      // evidence already observed before the unwind settled.
+      gitAfter = unionGitEvidence(
+        gitAfter,
+        await getGitChangedFiles(config.cwd),
+      );
+    }
 
     // Recompute evidence after the final quiescence wait. Output, usage,
     // activity-derived touched files, and the session error state can all be
@@ -680,37 +951,37 @@ export async function runAgentSession(
     const output = capturedOutput();
     const usage = currentUsage();
     const fromActivities = extractTouchedFromActivities(activities, config.cwd);
+    const fileAttributions = extractAttributedFromActivities(
+      activities,
+      config.cwd,
+    );
+    const attributedFiles = fileAttributions.map(projectedAttributionPath);
     const fromGit =
       gitBaseline && gitAfter
         ? [...gitAfter].filter((f) => !gitBaseline.has(f))
         : [];
-    const touchedFiles = [...new Set([...fromActivities, ...fromGit])];
-    const attributedFiles = fromActivities;
-    const errorMessage = signal?.aborted
-      ? "Aborted"
-      : deadlineExceeded
-        ? deadlineError()
-        : stalled
-          ? stallError()
-          : state.errorMessage;
-
-    return {
+    const touchedFiles = [
+      ...new Set([...fromActivities, ...attributedFiles, ...fromGit]),
+    ];
+    const failure = resolveRunFailure(
+      currentCancellationSource(),
+      state.errorMessage,
+      deadlineError,
+      stallError,
+    );
+
+    return finishResult({
       output: output || "(no output)",
-      error: errorMessage,
+      error: failure.error,
       durationMs: Date.now() - startTime,
       tokens: usage.totalTokens,
       usage,
       touchedFiles,
       attributedFiles,
-      failureKind: signal?.aborted
-        ? undefined
-        : deadlineExceeded
-          ? "deadline_exceeded"
-          : stalled
-            ? "stalled"
-            : undefined,
+      fileAttributions,
+      failureKind: failure.failureKind,
       prompted,
-    };
+    });
   } catch (err) {
     // Preserve partial-work evidence: whatever assistant output, token spend,
     // and touched files accumulated before the failure/abort. The touched-file
@@ -723,7 +994,7 @@ export async function runAgentSession(
     phase = "collecting git evidence";
     lastActivityAt = Date.now();
 
-    const gitAfter = await getGitChangedFiles(config.cwd);
+    let gitAfter = await getGitChangedFiles(config.cwd);
     if (deadlineAt && Date.now() >= deadlineAt && !deadlineExceeded) {
       abortForDeadline();
     }
@@ -733,7 +1004,16 @@ export async function runAgentSession(
     // cancellation is still unwinding. Wait for the same quiescence barrier so
     // lifecycle does not dispose/reuse the session while compaction or an
     // extension callback is still active.
-    if (deadlineExceeded || signal?.aborted) await waitForSessionQuiescence();
+    if (currentCancellationSource()) {
+      await waitForSessionQuiescence();
+      // As in the success path, the unwind itself can change Git-visible
+      // files. Preserve the first observation if recollection fails and union
+      // both successful observations so transient changes remain evidence.
+      gitAfter = unionGitEvidence(
+        gitAfter,
+        await getGitChangedFiles(config.cwd),
+      );
+    }
 
     // Recompute evidence after the final quiescence wait. Output, usage, and
     // activity-derived touched files can all be mutated by the unwinding work
@@ -741,44 +1021,43 @@ export async function runAgentSession(
     const partialOutput = capturedOutput();
     const usage = currentUsage();
     const fromActivities = extractTouchedFromActivities(activities, config.cwd);
+    const fileAttributions = extractAttributedFromActivities(
+      activities,
+      config.cwd,
+    );
+    const attributedFiles = fileAttributions.map(projectedAttributionPath);
     const fromGit =
       gitBaseline && gitAfter
         ? [...gitAfter].filter((f) => !gitBaseline.has(f))
         : [];
-    const touchedFiles = [...new Set([...fromActivities, ...fromGit])];
-    const attributedFiles = fromActivities;
-
-    const msg = signal?.aborted
-      ? "Aborted"
-      : deadlineExceeded
-        ? deadlineError()
-        : stalled
-          ? stallError()
-          : err instanceof Error
-            ? err.message
-            : String(err);
-    return {
+    const touchedFiles = [
+      ...new Set([...fromActivities, ...attributedFiles, ...fromGit]),
+    ];
+
+    const fallbackError = err instanceof Error ? err.message : String(err);
+    const failure = resolveRunFailure(
+      currentCancellationSource(),
+      fallbackError,
+      deadlineError,
+      stallError,
+    );
+    return finishResult({
       output: partialOutput || "(no output)",
-      error: msg,
+      error: failure.error,
       durationMs: Date.now() - startTime,
       tokens: usage.totalTokens,
       usage,
       touchedFiles,
       attributedFiles,
-      failureKind: signal?.aborted
-        ? undefined
-        : deadlineExceeded
-          ? "deadline_exceeded"
-          : stalled
-            ? "stalled"
-            : undefined,
+      fileAttributions,
+      failureKind: failure.failureKind,
       prompted,
-    };
+    });
   } finally {
     clearStallWatchdog();
     clearDeadlineWatchdog();
     if (signal && abortHandler)
       signal.removeEventListener("abort", abortHandler);
-    unsubscribe();
+    removeFullListener();
   }
 }