pi-async 0.1.0 → 0.3.0

package/src/core/spawn.ts

@@ -1,28 +1,78 @@
-import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { setTimeout as delay } from "node:timers/promises";
+import { buildChildEnv, INTERNAL_MAX_OUTPUT_ENV, type EnvPolicy } from "./env.ts";
 import type { TaskSnapshot } from "./task.ts";
 
+export type { EnvPolicy };
+
 export interface SpawnHandle { pid: number; exit: Promise<{ code: number }>; }
 
-/** Start a shell command in its own POSIX process group and capture merged output. */
-export function spawnDetached(command: string, opts: { outputFile: string; env?: Record<string, string> }): SpawnHandle {
+export interface SpawnOptions {
+  outputFile: string;
+  env?: Record<string, string>;
+  cwd?: string;
+  envPolicy?: EnvPolicy;
+}
+
+/** Derive per-stream sidecar paths next to the merged `.output` file. */
+export function streamPaths(outputFile: string): { stdout: string; stderr: string } {
+  if (outputFile.endsWith(".output")) {
+    const base = outputFile.slice(0, -".output".length);
+    return { stdout: `${base}.stdout`, stderr: `${base}.stderr` };
+  }
+  return { stdout: `${outputFile}.stdout`, stderr: `${outputFile}.stderr` };
+}
+
+/** Resolve the inheritance policy; an unknown `PI_ASYNC_ENV_INHERIT` falls back to `safe` (D-10). */
+export function resolveEnvPolicy(explicit?: EnvPolicy): EnvPolicy {
+  if (explicit) return explicit;
+  const inherited = process.env.PI_ASYNC_ENV_INHERIT;
+  if (inherited === "all") return "all";
+  if (inherited === "none") return "none";
+  return "safe";
+}
+
+/** Fail loudly before forking when the requested cwd cannot be used. */
+function assertUsableCwd(cwd: string | undefined): void {
+  if (cwd === undefined) return;
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(cwd);
+  } catch {
+    throw new Error(`Working directory does not exist: ${cwd}`);
+  }
+  if (!stats.isDirectory()) throw new Error(`Working directory is not a directory: ${cwd}`);
+}
+
+/** Start a shell command in its own POSIX process group; capture merged + separate streams. */
+export function spawnDetached(command: string, opts: SpawnOptions): SpawnHandle {
+  assertUsableCwd(opts.cwd);
   mkdirSync(dirname(opts.outputFile), { recursive: true });
-  const capBytes = finiteNumber(opts.env?.PI_ASYNC_INTERNAL_MAX_OUTPUT_BYTES ?? process.env.PI_ASYNC_MAX_OUTPUT_BYTES, 20 * 1024 * 1024);
-  const env = { ...process.env, ...opts.env };
-  delete env.PI_ASYNC_INTERNAL_MAX_OUTPUT_BYTES;
-  const child = spawn("/bin/sh", ["-c", command], { detached: true, stdio: ["ignore", "pipe", "pipe"], env });
-  if (!child.pid) throw new Error("Failed to start detached task process");
-  const output = createWriteStream(opts.outputFile, { flags: "w", mode: 0o600 });
+  const { stdout: stdoutFile, stderr: stderrFile } = streamPaths(opts.outputFile);
+  const capBytes = finiteNumber(opts.env?.[INTERNAL_MAX_OUTPUT_ENV] ?? process.env.PI_ASYNC_MAX_OUTPUT_BYTES, 20 * 1024 * 1024);
+  const env = buildChildEnv(process.env, opts.env, resolveEnvPolicy(opts.envPolicy));
+  // Always pass cwd explicitly: the host process cwd is not the session cwd (REV-13).
+  const child = spawn("/bin/sh", ["-c", command], { detached: true, stdio: ["ignore", "pipe", "pipe"], env, cwd: opts.cwd });
+  // Attach a no-op error listener before any throw so a failed spawn can never surface as an
+  // unhandled 'error' event (which would crash the host); the exit promise re-observes it.
+  child.on("error", () => undefined);
+  if (!child.pid) throw new Error(`Failed to start detached task process${opts.cwd ? ` in ${opts.cwd}` : ""}`);
+  const merged = createWriteStream(opts.outputFile, { flags: "w", mode: 0o600 });
+  const stdoutOut = createWriteStream(stdoutFile, { flags: "w", mode: 0o600 });
+  const stderrOut = createWriteStream(stderrFile, { flags: "w", mode: 0o600 });
+  // Cleanup may unlink the data dir while pipes still flush; ignore late write errors.
+  for (const stream of [merged, stdoutOut, stderrOut]) stream.on("error", () => undefined);
   let totalBytes = 0;
   let capReached = false;
-  const copy = (chunk: Buffer): void => {
+  const copy = (chunk: Buffer, stream: "stdout" | "stderr"): void => {
     if (capReached) return;
     const remaining = Math.max(0, capBytes - totalBytes);
     const accepted = chunk.subarray(0, remaining);
     if (accepted.length) {
-      output.write(accepted);
+      merged.write(accepted);
+      (stream === "stdout" ? stdoutOut : stderrOut).write(accepted);
       totalBytes += accepted.length;
     }
     if (accepted.length < chunk.length) {
@@ -35,12 +85,19 @@ export function spawnDetached(command: string, opts: { outputFile: string; env?:
       });
     }
   };
-  child.stdout?.on("data", (chunk: Buffer) => copy(Buffer.from(chunk)));
-  child.stderr?.on("data", (chunk: Buffer) => copy(Buffer.from(chunk)));
+  child.stdout?.on("data", (chunk: Buffer) => copy(Buffer.from(chunk), "stdout"));
+  child.stderr?.on("data", (chunk: Buffer) => copy(Buffer.from(chunk), "stderr"));
   const exit = new Promise<{ code: number }>((resolve, reject) => {
     child.once("error", reject);
     child.once("close", (code) => {
-      output.end(() => resolve({ code: code ?? 1 }));
+      let pending = 3;
+      const done = (): void => {
+        pending--;
+        if (pending === 0) resolve({ code: code ?? 1 });
+      };
+      merged.end(done);
+      stdoutOut.end(done);
+      stderrOut.end(done);
     });
   });
   return { pid: child.pid, exit };
@@ -51,7 +108,6 @@ function finiteNumber(value: string | undefined, fallback: number): number {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
-/** Merge the cap marker into the task snapshot with the same atomic-rename strategy as the registry. */
 function persistOutputCap(outputFile: string): void {
   const metadataFile = outputFile.endsWith(".output") ? `${outputFile.slice(0, -7)}.json` : `${outputFile}.json`;
   try {
@@ -75,17 +131,37 @@ function groupExists(pid: number): boolean {
   }
 }
 
+/** True only if the process group has a non-zombie member (#6). */
+function groupHasLiveMember(pgid: number): boolean {
+  try {
+    for (const entry of readdirSync("/proc")) {
+      if (!/^\d+$/.test(entry)) continue;
+      try {
+        const stat = readFileSync(`/proc/${entry}/stat`, "utf8");
+        const closeParen = stat.lastIndexOf(") ");
+        if (closeParen < 0) continue;
+        const rest = stat.slice(closeParen + 2).split(" ");
+        const state = rest[0];
+        const pgrp = Number(rest[2]);
+        if (pgrp === pgid && state !== "Z") return true;
+      } catch { /* raced */ }
+    }
+    return false;
+  } catch {
+    return groupExists(pgid);
+  }
+}
+
 async function waitForGroupExit(pid: number, timeoutMs: number): Promise<boolean> {
   const deadline = Date.now() + timeoutMs;
-  while (groupExists(pid) && Date.now() < deadline) await delay(Math.min(100, Math.max(1, deadline - Date.now())));
-  return !groupExists(pid);
+  while (groupHasLiveMember(pid) && Date.now() < deadline) await delay(Math.min(100, Math.max(1, deadline - Date.now())));
+  return !groupHasLiveMember(pid);
 }
 
-/** Terminate the detached process group, escalating from TERM to KILL. */
 export async function killTree(pid: number, opts?: { graceMs?: number }): Promise<{ confirmed: boolean }> {
   const graceMs = opts?.graceMs ?? 3000;
   if (!Number.isInteger(pid) || pid <= 1) throw new RangeError("pid must identify a child process");
-  if (!groupExists(pid)) return { confirmed: true };
+  if (!groupHasLiveMember(pid)) return { confirmed: true };
   try { process.kill(-pid, "SIGTERM"); } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
   }
@@ -93,6 +169,5 @@ export async function killTree(pid: number, opts?: { graceMs?: number }): Promis
   try { process.kill(-pid, "SIGKILL"); } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
   }
-  // Bounded probe: do not hang shutdown forever if the kernel cannot prove death.
   return { confirmed: await waitForGroupExit(pid, 1500) };
 }

package/src/core/task.ts

@@ -1,19 +1,32 @@
-export type TaskStatus = "pending" | "running" | "completed" | "failed" | "killed";
+export const TASK_STATUSES = ["pending", "running", "completed", "failed", "killed"] as const;
+export type TaskStatus = (typeof TASK_STATUSES)[number];
 export type TaskMode = "background" | "sync" | "delayed";
 export type KillKind = "user" | "timeout" | "output_cap" | "shutdown" | "watch_failure";
+export type FailureKind = "lost" | "blind_exhausted" | "watch_timeout";
 
 export const TERMINAL_STATUSES = ["completed", "failed", "killed"] as const satisfies readonly TaskStatus[];
 
+export function isTaskStatus(value: unknown): value is TaskStatus {
+  return typeof value === "string" && (TASK_STATUSES as readonly string[]).includes(value);
+}
+
 export function isTerminal(status: TaskStatus): boolean {
   return TERMINAL_STATUSES.includes(status as (typeof TERMINAL_STATUSES)[number]);
 }
 
-/** Derive a concise, single-line display name from a shell command. */
+/** Cap a task name at `limit` Unicode code points without splitting surrogate pairs (#28). */
+export function capName(name: string, limit = 48): string {
+  const characters = Array.from(name);
+  return characters.length <= limit ? name : characters.slice(0, limit - 1).join("") + "…";
+}
+
+/** Derive a concise, single-line display name from a shell command.
+ *  Uses the first non-blank line so a leading newline does not collapse to the fallback (#23). */
 export function deriveName(command: string): string {
-  const normalized = command.split(/\r?\n/, 1)[0]?.trim().replace(/\s+/g, " ") ?? "";
+  const firstContentLine = command.split(/\r?\n/).find((line) => line.trim().length > 0);
+  const normalized = firstContentLine?.trim().replace(/\s+/g, " ") ?? "";
   if (normalized.length === 0) return "async task";
-  const characters = Array.from(normalized);
-  return characters.length <= 48 ? normalized : characters.slice(0, 47).join("") + "…";
+  return capName(normalized);
 }
 
 export type Condition =
@@ -43,6 +56,8 @@ export interface RunOptions {
   triggerOnCompletion?: boolean;
   env?: Record<string, string>;
   watch?: WatchSpec;
+  /** 0.3.0: directory the task runs in; defaults to the registry/session cwd, then process.cwd(). */
+  cwd?: string;
 }
 
 export interface RunReceipt {
@@ -59,9 +74,13 @@ export interface SyncResult extends RunReceipt {
   promoted: boolean;
 }
 
+export type WaitResultItem = { taskId: string; status: TaskStatus; exitCode?: number; outputTail: string; killKind?: KillKind; failureKind?: FailureKind };
+export type WaitNotReadyItem = { taskId: string; status: "running" | "pending"; elapsedMs: number };
+/** All-terminal → { results }; timeout-only → { notReady }; mixed timeout → { results, notReady } (REV-7 / #43 + #37 kinds). */
 export type WaitOutcome =
-  | { results: Array<{ taskId: string; status: TaskStatus; exitCode?: number; outputTail: string }> }
-  | { notReady: Array<{ taskId: string; status: "running" | "pending"; elapsedMs: number }> };
+  | { results: WaitResultItem[] }
+  | { notReady: WaitNotReadyItem[] }
+  | { results: WaitResultItem[]; notReady: WaitNotReadyItem[] };
 
 export interface TaskSnapshot {
   taskId: string;
@@ -72,7 +91,7 @@ export interface TaskSnapshot {
   pid?: number;
   exitCode?: number;
   killKind?: KillKind;
-  failureKind?: "lost";
+  failureKind?: FailureKind;
   createdAt: number;
   startedAt?: number;
   finishedAt?: number;
@@ -82,4 +101,15 @@ export interface TaskSnapshot {
   outputConsumed: boolean;
   watch?: WatchSpec;
   metadata: Record<string, unknown>;
+  // 0.3.0 additions (all optional so pre-0.3.0 snapshots stay readable).
+  /** Working directory the task executes in (REV-13). */
+  cwd?: string;
+  /** Absolute deadline for `taskTimeoutMs` (reload re-arms the remaining time). */
+  timeoutAt?: number;
+  /** Absolute deadline for the watch window (reload restores the remaining budget). */
+  watchDeadline?: number;
+  /** Number of completion-notification attempts so far (honesty accounting, no retries). */
+  notifyAttempts?: number;
+  /** Process liveness seen when the snapshot was produced (false once finalized). */
+  processAlive?: boolean;
 }

package/src/core/watch.ts

@@ -2,6 +2,35 @@ import type { Condition, WatchSpec } from "./task.ts";
 
 const compiledRegexes = new WeakMap<Condition, RegExp>();
 
+/** Captured streams for watch evaluation: stdout/stderr are distinct; output is merged. */
+export interface WatchOutput {
+  output: string;
+  stdout: string;
+  stderr: string;
+}
+
+/** Cap regex subject size so catastrophic patterns cannot grow without bound (#24). */
+export const MAX_OUTPUT_MATCH_BYTES = 64 * 1024;
+
+/**
+ * Classic exponential-backtracking shape: a group that itself ends with a
+ * quantifier, then another quantifier — e.g. (a+)+ / (a*)* / (a|b+)+.
+ * Conservative; does not catch every polynomial case.
+ */
+const NESTED_QUANTIFIER = /\((?:[^()\\]|\\.)*[+*]\)\s*[+*]/;
+
+function rejectDangerousRegex(regex: string): string | undefined {
+  if (NESTED_QUANTIFIER.test(regex)) {
+    return "regex has nested quantifiers (ReDoS risk); simplify or use stdout_contains";
+  }
+  return undefined;
+}
+
+function matchSubject(output: string): string {
+  if (output.length <= MAX_OUTPUT_MATCH_BYTES) return output;
+  return output.slice(-MAX_OUTPUT_MATCH_BYTES);
+}
+
 export function validateWatchSpec(spec: WatchSpec): { ok: true } | { ok: false; error: string } {
   const invalid = (error: string) => ({ ok: false as const, error });
   if (!spec || typeof spec !== "object") return invalid("watch must be an object");
@@ -38,13 +67,18 @@ export function validateWatchSpec(spec: WatchSpec): { ok: true } | { ok: false;
           break;
         case "json_path_exists":
           if (typeof condition.path !== "string" || parseJsonPath(condition.path) === undefined) {
-            return invalid(`${location}: invalid JSON path`);
+            const shown = typeof condition.path === "string" ? JSON.stringify(condition.path) : String(condition.path);
+            return invalid(`${location}: invalid JSON path ${shown}: paths must start with "$" (e.g. $.ready or $.items[0].state)`);
           }
           break;
         case "output_matches":
           if (typeof condition.regex !== "string") return invalid(`${location}: regex must be a string`);
+          {
+            const danger = rejectDangerousRegex(condition.regex);
+            if (danger) return invalid(`${location}: ${danger}`);
+          }
           try {
-            compiledRegexes.set(condition, new RegExp(condition.regex));
+            compiledRegexes.set(condition, new RegExp(condition.regex, "m"));
           } catch {
             return invalid(`${location}: invalid regex`);
           }
@@ -57,7 +91,9 @@ export function validateWatchSpec(spec: WatchSpec): { ok: true } | { ok: false;
   return { ok: true };
 }
 
-export function evalConditions(conds: Condition[], ctx: { output: string; exitCode?: number }): boolean {
+export type WatchEvalContext = WatchOutput & { exitCode?: number };
+
+export function evalConditions(conds: Condition[], ctx: WatchEvalContext): boolean {
   const result = evaluateConditionsDetailed(conds, ctx);
   return result.status === "matched" && result.matched;
 }
@@ -65,7 +101,7 @@ export function evalConditions(conds: Condition[], ctx: { output: string; exitCo
 export interface WatchLoopDeps {
   taskId: string;
   spec: WatchSpec;
-  readOutput: () => string;
+  readOutput: () => WatchOutput;
   getExitCode: () => number | undefined;
   onSuccess: (detail: string) => void;
   onFailure: () => void;
@@ -111,17 +147,17 @@ export class WatchLoop {
     const conditions = [...this.deps.spec.failure_when, ...this.deps.spec.success_when];
     const needsOutput = conditions.some((condition) => condition.type !== "exit_code");
     const needsExitCode = conditions.some((condition) => condition.type === "exit_code");
-    let output = "";
+    let streams: WatchOutput = { output: "", stdout: "", stderr: "" };
     let exitCode: number | undefined;
     try {
-      if (needsOutput) output = this.deps.readOutput();
+      if (needsOutput) streams = this.deps.readOutput();
       if (needsExitCode) exitCode = this.deps.getExitCode();
     } catch {
       this.countBlindCheck();
       return;
     }
 
-    const ctx = { output, exitCode };
+    const ctx: WatchEvalContext = { ...streams, exitCode };
     const failure = evaluateConditionsDetailed(this.deps.spec.failure_when, ctx);
     if (failure.status === "matched" && failure.matched) {
       this.finish(this.deps.onFailure);
@@ -178,7 +214,7 @@ type ConditionEvaluation =
   | { status: "pending" }
   | { status: "error" };
 
-function evaluateConditionsDetailed(conditions: Condition[], ctx: { output: string; exitCode?: number }): ConditionEvaluation {
+function evaluateConditionsDetailed(conditions: Condition[], ctx: WatchEvalContext): ConditionEvaluation {
   let pending = false;
   let error = false;
   for (const condition of conditions) {
@@ -192,21 +228,21 @@ function evaluateConditionsDetailed(conditions: Condition[], ctx: { output: stri
   return { status: "matched", matched: false };
 }
 
-function evaluateCondition(condition: Condition, ctx: { output: string; exitCode?: number }): ConditionEvaluation {
+function evaluateCondition(condition: Condition, ctx: WatchEvalContext): ConditionEvaluation {
   switch (condition.type) {
     case "exit_code":
       return ctx.exitCode === undefined
         ? { status: "pending" }
         : { status: "matched", matched: ctx.exitCode === condition.equals };
     case "stdout_contains":
+      return { status: "matched", matched: ctx.stdout.includes(condition.value) };
     case "stderr_contains":
-      // The frozen WatchLoop context exposes the captured merged output stream.
-      return { status: "matched", matched: ctx.output.includes(condition.value) };
+      return { status: "matched", matched: ctx.stderr.includes(condition.value) };
     case "output_matches": {
       let regex = compiledRegexes.get(condition);
       if (!regex) {
         try {
-          regex = new RegExp(condition.regex);
+          regex = new RegExp(condition.regex, "m");
           compiledRegexes.set(condition, regex);
         } catch {
           return { status: "error" };
@@ -214,7 +250,7 @@ function evaluateCondition(condition: Condition, ctx: { output: string; exitCode
       }
       // Global/sticky expressions otherwise retain lastIndex between watch polls.
       regex.lastIndex = 0;
-      return { status: "matched", matched: regex.test(ctx.output) };
+      return { status: "matched", matched: regex.test(matchSubject(ctx.output)) };
     }
     case "json_path_exists": {
       let root: unknown;

package/src/guard/settle-guard.ts

@@ -1,78 +1,184 @@
 import type { PiCtx } from "../core/notify.ts";
 import type { TaskRegistry } from "../core/registry.ts";
+import type { TaskSnapshot } from "../core/task.ts";
 
+/** `custom_message` draft pi accepts from `agent_before_settle` (PLAN §2.6). */
+interface CustomMessageDraft {
+  type: "custom_message";
+  customType: string;
+  content: string;
+  display: false;
+}
+
+/** The slice of pi's `AgentBeforeSettleEvent` this guard reads; `entries` may be absent. */
+interface BeforeSettleEvent {
+  entries?: unknown[];
+}
+
+/** The slice of pi's `AgentSettledEvent` this guard reads. */
+interface SettledEvent {
+  aborted?: boolean;
+}
+
+/** `agent_before_settle` result: appended drafts plus an optional extra provider request. */
+interface BeforeSettleResult {
+  entries: unknown[];
+  continue?: boolean;
+}
+
+type HostHooks = {
+  on?: (event: string, handler: (...args: unknown[]) => unknown) => unknown;
+  off?: (event: string, handler: (...args: unknown[]) => unknown) => void;
+};
+
+type MessageHost = {
+  sendMessage?: (message: unknown, options: unknown) => unknown;
+};
+
+const idsOf = (active: TaskSnapshot[]): string => active.map((task) => task.taskId).join(", ");
+
+/**
+ * Keeps a legion child from reporting a verdict while async tasks are still in flight.
+ *
+ * 0.3.0 (D-12) removed the old `setInterval` heartbeat: it only ever wrote
+ * `async-task-heartbeat` entries nobody read, and because timer callbacks run outside pi's
+ * event-loop `try/catch` a stale ctx there escaped as an `uncaughtException` (crash
+ * 2026-10-21, `Timeout._onTimeout` at settle-guard heartbeat). Reminders are now produced
+ * inside the `agent_before_settle` boundary, where pi tolerates (and contains) extension
+ * errors, and `agent_settled` (`aborted` runs) sends at most one follow-up per generation.
+ */
 export class SettleGuard {
   private readonly maxReminders: number;
-  private readonly heartbeatMs: number;
   private reminders = 0;
-  private heartbeat?: ReturnType<typeof setInterval>;
+  private settledSent = false;
   private removeHooks: Array<() => void> = [];
+  private disposed = false;
   private readonly pi: PiCtx;
   private readonly registry: TaskRegistry;
 
-  constructor(pi: PiCtx, registry: TaskRegistry, opts?: { maxReminders?: number; heartbeatMs?: number }) {
+  constructor(pi: PiCtx, registry: TaskRegistry, opts?: { maxReminders?: number }) {
     this.pi = pi;
     this.registry = registry;
     this.maxReminders = opts?.maxReminders ?? 3;
-    this.heartbeatMs = opts?.heartbeatMs ?? finiteEnvNumber("PI_ASYNC_HEARTBEAT_MS", 60_000);
   }
 
   register(): void {
-    // SAFETY: PiCtx hooks vary by runtime; these optional operations are only invoked after presence checks.
-    const hooks = this.pi as unknown as {
-      on?: (event: string, handler: (...args: unknown[]) => unknown) => void;
-      off?: (event: string, handler: (...args: unknown[]) => unknown) => void;
-      appendEntry?: (customType: string, data: unknown) => void;
+    // D-12: one env switch disarms the guard entirely — it registers nothing at all.
+    if (process.env.PI_ASYNC_SETTLE_GUARD === "0") return;
+    if (this.disposed) return;
+    // SAFETY: PiCtx hooks vary by runtime; `on` returns the unsubscribe function (the real
+    // host has no `pi.off`), so both shapes are feature-detected before use.
+    const hooks = this.pi as unknown as HostHooks;
+    const unsubscribers: Array<() => void> = [];
+    const listen = (event: string, handler: (...args: unknown[]) => unknown): void => {
+      const result = hooks.on?.(event, handler);
+      // SAFETY: pi.on() returns an unsubscribe function; older/mocked hosts may return void, in
+      // which case there is nothing to release and the guard relies on `off`/`disposed` alone.
+      if (typeof result === "function") unsubscribers.push(result as () => void);
+      else unsubscribers.push(() => hooks.off?.(event, handler));
     };
-    const beforeSettle = () => {
+
+    const beforeSettle = (event?: unknown): BeforeSettleResult | undefined => {
+      if (this.disposed) return undefined;
       const active = this.registry.list({ includeHistory: false });
-      if (active.length === 0) { this.reminders = 0; this.reportActivity(); return; }
       this.reportActivity();
+      // A stale ctx made reportActivity tear us down; the generation is gone, so stay silent.
+      if (this.disposed) return undefined;
+      if (active.length === 0) {
+        this.reminders = 0;
+        return undefined;
+      }
+      // Any drafts pi already queued for this boundary are preserved in front of ours.
+      const entries = [...((event as BeforeSettleEvent | undefined)?.entries ?? [])];
+      const ids = idsOf(active);
       if (this.reminders >= this.maxReminders) {
-        hooks.appendEntry?.("async-task-unresolved", { message: `${active.length} async task(s) remain unresolved: ${active.map((task) => task.taskId).join(", ")}` });
-        return;
+        // Budget spent: record the unresolved list for the transcript, then let the run settle
+        // (`continue` omitted so pi does not force another provider request).
+        const unresolved: CustomMessageDraft = {
+          type: "custom_message",
+          customType: "async-task-unresolved",
+          content: `${active.length} async task(s) left unresolved: ${ids}. Collect them with async_wait or async_status before finishing.`,
+          display: false,
+        };
+        return { entries: [...entries, unresolved] };
       }
       this.reminders++;
-      hooks.appendEntry?.("async-task-settle-reminder", { message: `${active.length} async task(s) not collected (${active.map((task) => task.taskId).join(", ")}); use async_wait/async_status before reporting verdict.` });
-      return { continue: true };
+      const reminder: CustomMessageDraft = {
+        type: "custom_message",
+        customType: "async-task-settle-reminder",
+        content: `${active.length} async task(s) not collected yet: ${ids}. Call async_wait or async_status before reporting a verdict.`,
+        display: false,
+      };
+      return { entries: [...entries, reminder], continue: true };
     };
-    const beforeRun = () => { this.reminders = 0; };
+
+    const agentStart = (): void => {
+      this.reminders = 0;
+      this.settledSent = false;
+    };
+
+    const agentSettled = (event?: unknown): void => {
+      if (this.disposed || this.settledSent) return;
+      if ((event as SettledEvent | undefined)?.aborted !== true) return;
+      if (!this.registry.hasActiveWork()) return;
+      // D-13: at most one follow-up per generation; latch before the host call so a throw
+      // cannot turn into a retry storm.
+      this.settledSent = true;
+      let ids = "";
+      try {
+        ids = idsOf(this.registry.list({ includeHistory: false }));
+      } catch { /* best effort: the snapshot is decoration for the message body */ }
+      const content = `This run was aborted with async task(s) still running${ids ? `: ${ids}` : ""}. Use async_wait or async_status to collect them.`;
+      try {
+        // SAFETY: sendMessage is part of ExtensionAPI; feature-detected because mocks and older
+        // hosts may omit it, and a stale ctx getter throws on access.
+        const host = this.pi as unknown as MessageHost;
+        const send = host.sendMessage;
+        if (typeof send !== "function") return;
+        const result = send.call(host, { customType: "async-task-unresolved", content }, { deliverAs: "followUp" });
+        // SAFETY: hosts return void; a mock/future host may return a promise, which must never
+        // surface as an unhandled rejection.
+        if (result && typeof (result as PromiseLike<unknown>).then === "function") {
+          void Promise.resolve(result as PromiseLike<unknown>).catch(() => undefined);
+        }
+      } catch { /* best effort: sending is advisory, never fatal to settle */ }
+    };
+
     // SAFETY: PI_LEGION_NODE_ID is the documented legion-child marker; presence opts into settle reminders.
     const legionChild = process.env.PI_LEGION_NODE_ID !== undefined;
-    if (legionChild) hooks.on?.("agent_before_settle", beforeSettle);
-    hooks.on?.("agent_start", beforeRun);
-    const cleanup = () => {
-      if (this.heartbeat) clearInterval(this.heartbeat);
-      if (legionChild) hooks.off?.("agent_before_settle", beforeSettle);
-      hooks.off?.("agent_start", beforeRun);
-      this.removeHooks = [];
-    };
-    hooks.on?.("session_shutdown", () => { void cleanup(); });
-    this.removeHooks.push(cleanup);
-    this.startHeartbeat(hooks);
+    if (legionChild) listen("agent_before_settle", beforeSettle);
+    listen("agent_start", agentStart);
+    // Thread 2 of the guard: registered for every session (not only legion children).
+    listen("agent_settled", agentSettled);
+    listen("session_shutdown", () => { this.dispose(); });
+    this.removeHooks.push(() => {
+      for (const unsubscribe of unsubscribers.splice(0)) {
+        try { unsubscribe(); } catch { /* best effort: the host ctx may already be stale */ }
+      }
+    });
     this.reportActivity();
   }
 
-  private reportActivity(): void {
-    // SAFETY: setActivity is feature-detected because older Pi hosts do not implement the optional API.
-    const ui = (this.pi as unknown as { ui?: { setActivity?: (id: string, value: { message: string } | undefined) => void } }).ui;
-    if (typeof ui?.setActivity !== "function") return;
-    const count = this.registry.activeCount();
-    const total = count.running + count.pending;
-    ui.setActivity("pi-async", total ? { message: `${total} async tasks` } : undefined);
+  /** Idempotent teardown; a second call is a no-op. */
+  dispose(): void {
+    this.disposed = true;
+    for (const remove of this.removeHooks.splice(0)) {
+      try { remove(); } catch { /* best effort: the host ctx may already be stale */ }
+    }
   }
 
-  private startHeartbeat(hooks: { appendEntry?: (customType: string, data: unknown) => void }): void {
-    if (this.heartbeat || this.heartbeatMs <= 0) return;
-    this.heartbeat = setInterval(() => {
-      if (!this.registry.hasActiveWork()) return;
-      hooks.appendEntry?.("async-task-heartbeat", { timestamp: Date.now(), active: this.registry.activeCount() });
-    }, this.heartbeatMs);
-    this.heartbeat.unref?.();
+  private reportActivity(): void {
+    if (this.disposed) return;
+    try {
+      // SAFETY: `pi.ui` itself throws on a stale ctx, so the read is guarded with the call.
+      const ui = (this.pi as unknown as { ui?: { setActivity?: (id: string, value: { message: string } | undefined) => void } }).ui;
+      if (typeof ui?.setActivity !== "function") return;
+      const count = this.registry.activeCount();
+      const total = count.running + count.pending;
+      ui.setActivity("pi-async", total ? { message: `${total} async task${total === 1 ? "" : "s"}` } : undefined);
+    } catch {
+      // The host abandoned this generation; detach instead of retrying into a dead API.
+      this.dispose();
+    }
   }
 }
-
-function finiteEnvNumber(name: string, fallback: number): number {
-  const parsed = Number(process.env[name] ?? fallback);
-  return Number.isFinite(parsed) ? parsed : fallback;
-}