pi-async 0.0.0-stage → 0.2.0

package/src/core/spawn.ts

@@ -0,0 +1,138 @@
+import { createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import type { TaskSnapshot } from "./task.ts";
+
+export interface SpawnHandle { pid: number; exit: Promise<{ code: number }>; }
+
+/** Derive per-stream sidecar paths next to the merged `.output` file. */
+export function streamPaths(outputFile: string): { stdoutFile: string; stderrFile: string } {
+  if (outputFile.endsWith(".output")) {
+    const base = outputFile.slice(0, -".output".length);
+    return { stdoutFile: `${base}.stdout`, stderrFile: `${base}.stderr` };
+  }
+  return { stdoutFile: `${outputFile}.stdout`, stderrFile: `${outputFile}.stderr` };
+}
+
+/** Start a shell command in its own POSIX process group; capture merged + separate streams. */
+export function spawnDetached(command: string, opts: { outputFile: string; env?: Record<string, string> }): SpawnHandle {
+  mkdirSync(dirname(opts.outputFile), { recursive: true });
+  const { stdoutFile, stderrFile } = streamPaths(opts.outputFile);
+  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 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, stream: "stdout" | "stderr"): void => {
+    if (capReached) return;
+    const remaining = Math.max(0, capBytes - totalBytes);
+    const accepted = chunk.subarray(0, remaining);
+    if (accepted.length) {
+      merged.write(accepted);
+      (stream === "stdout" ? stdoutOut : stderrOut).write(accepted);
+      totalBytes += accepted.length;
+    }
+    if (accepted.length < chunk.length) {
+      capReached = true;
+      persistOutputCap(opts.outputFile);
+      void killTree(child.pid ?? 0, { graceMs: 3000 }).then(({ confirmed }) => {
+        if (!confirmed) console.error(`pi-async: output cap could not confirm process group ${child.pid} exited`);
+      }).catch((error: unknown) => {
+        console.error(`pi-async: failed to kill process group ${child.pid} after output cap`, error);
+      });
+    }
+  };
+  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) => {
+      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 };
+}
+
+function finiteNumber(value: string | undefined, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function persistOutputCap(outputFile: string): void {
+  const metadataFile = outputFile.endsWith(".output") ? `${outputFile.slice(0, -7)}.json` : `${outputFile}.json`;
+  try {
+    if (!existsSync(metadataFile)) throw new Error(`Task metadata is not available at ${metadataFile}`);
+    const snapshot = JSON.parse(readFileSync(metadataFile, "utf8")) as TaskSnapshot;
+    snapshot.metadata = { ...snapshot.metadata, capped: true };
+    const temp = `${metadataFile}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(snapshot), { mode: 0o600 });
+    renameSync(temp, metadataFile);
+  } catch (error) {
+    console.error(`pi-async: failed to persist output cap metadata for ${outputFile}`, error);
+  }
+}
+
+function groupExists(pid: number): boolean {
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** 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 (groupHasLiveMember(pid) && Date.now() < deadline) await delay(Math.min(100, Math.max(1, deadline - Date.now())));
+  return !groupHasLiveMember(pid);
+}
+
+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 (!groupHasLiveMember(pid)) return { confirmed: true };
+  try { process.kill(-pid, "SIGTERM"); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+  }
+  if (await waitForGroupExit(pid, graceMs)) return { confirmed: true };
+  try { process.kill(-pid, "SIGKILL"); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+  }
+  return { confirmed: await waitForGroupExit(pid, 1500) };
+}

package/src/core/task.ts

@@ -0,0 +1,102 @@
+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]);
+}
+
+/** 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 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";
+  return capName(normalized);
+}
+
+export type Condition =
+  | { type: "exit_code"; equals: number }
+  | { type: "stdout_contains"; value: string }
+  | { type: "stderr_contains"; value: string }
+  | { type: "json_path_exists"; path: string }
+  | { type: "output_matches"; regex: string };
+
+export interface WatchSpec {
+  intervalMs: number;
+  timeoutMs: number;
+  success_when: Condition[];
+  failure_when: Condition[];
+  blind_checks?: number;
+}
+
+export interface RunOptions {
+  command: string;
+  name?: string;
+  mode?: TaskMode;
+  delayMs?: number;
+  timeoutMs?: number;
+  onTimeout?: "promote" | "abort";
+  taskTimeoutMs?: number;
+  notifyOnCompletion?: boolean;
+  triggerOnCompletion?: boolean;
+  env?: Record<string, string>;
+  watch?: WatchSpec;
+}
+
+export interface RunReceipt {
+  taskId: string;
+  name: string;
+  status: TaskStatus;
+  mode: TaskMode;
+  outputHint: string;
+}
+
+export interface SyncResult extends RunReceipt {
+  exitCode?: number;
+  outputTail: string;
+  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: WaitResultItem[] }
+  | { notReady: WaitNotReadyItem[] }
+  | { results: WaitResultItem[]; notReady: WaitNotReadyItem[] };
+
+export interface TaskSnapshot {
+  taskId: string;
+  name: string;
+  command: string;
+  mode: TaskMode;
+  status: TaskStatus;
+  pid?: number;
+  exitCode?: number;
+  killKind?: KillKind;
+  failureKind?: FailureKind;
+  createdAt: number;
+  startedAt?: number;
+  finishedAt?: number;
+  dueAt?: number;
+  taskTimeoutMs?: number;
+  notified: boolean;
+  outputConsumed: boolean;
+  watch?: WatchSpec;
+  metadata: Record<string, unknown>;
+}

package/src/core/watch.ts

@@ -0,0 +1,308 @@
+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");
+  if (!Number.isFinite(spec.intervalMs) || !Number.isInteger(spec.intervalMs) || spec.intervalMs < 1_000) {
+    return invalid("intervalMs must be an integer greater than or equal to 1000");
+  }
+  if (!Number.isFinite(spec.timeoutMs) || !Number.isInteger(spec.timeoutMs) || spec.timeoutMs <= 0) {
+    return invalid("timeoutMs must be a positive finite integer");
+  }
+  if (spec.blind_checks !== undefined &&
+      (!Number.isFinite(spec.blind_checks) || !Number.isInteger(spec.blind_checks) || spec.blind_checks < 1)) {
+    return invalid("blind_checks must be a positive integer");
+  }
+  if (!Array.isArray(spec.success_when) || !Array.isArray(spec.failure_when)) {
+    return invalid("success_when and failure_when must be arrays");
+  }
+
+  for (const [group, conditions] of [
+    ["success_when", spec.success_when],
+    ["failure_when", spec.failure_when],
+  ] as const) {
+    for (const [index, condition] of conditions.entries()) {
+      const location = `${group}[${index}]`;
+      if (!condition || typeof condition !== "object" || !("type" in condition)) {
+        return invalid(`${location} is invalid`);
+      }
+      switch (condition.type) {
+        case "exit_code":
+          if (!Number.isFinite(condition.equals)) return invalid(`${location}: equals must be finite`);
+          break;
+        case "stdout_contains":
+        case "stderr_contains":
+          if (typeof condition.value !== "string") return invalid(`${location}: value must be a string`);
+          break;
+        case "json_path_exists":
+          if (typeof condition.path !== "string" || parseJsonPath(condition.path) === undefined) {
+            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, "m"));
+          } catch {
+            return invalid(`${location}: invalid regex`);
+          }
+          break;
+        default:
+          return invalid(`${location}: unknown condition type`);
+      }
+    }
+  }
+  return { ok: true };
+}
+
+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;
+}
+
+export interface WatchLoopDeps {
+  taskId: string;
+  spec: WatchSpec;
+  readOutput: () => WatchOutput;
+  getExitCode: () => number | undefined;
+  onSuccess: (detail: string) => void;
+  onFailure: () => void;
+  onBlindExhausted: () => void;
+  onWatchTimeout: () => void;
+}
+
+export class WatchLoop {
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private stopped = true;
+  private finished = false;
+  private deadline = 0;
+  private blindCount = 0;
+  private readonly deps: WatchLoopDeps;
+
+  constructor(deps: WatchLoopDeps) {
+    this.deps = deps;
+  }
+
+  start(): void {
+    if (!this.stopped || this.finished) return;
+    this.stopped = false;
+    this.blindCount = 0;
+    this.deadline = Date.now() + this.deps.spec.timeoutMs;
+    this.check();
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  private check(): void {
+    if (this.stopped) return;
+    if (Date.now() >= this.deadline) {
+      this.finish(this.deps.onWatchTimeout);
+      return;
+    }
+
+    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 streams: WatchOutput = { output: "", stdout: "", stderr: "" };
+    let exitCode: number | undefined;
+    try {
+      if (needsOutput) streams = this.deps.readOutput();
+      if (needsExitCode) exitCode = this.deps.getExitCode();
+    } catch {
+      this.countBlindCheck();
+      return;
+    }
+
+    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);
+      return;
+    }
+    const success = evaluateConditionsDetailed(this.deps.spec.success_when, ctx);
+    if (success.status === "matched" && success.matched) {
+      const matched = success.condition;
+      this.finish(() => this.deps.onSuccess(`success_when matched: ${JSON.stringify(matched)}`));
+      return;
+    }
+
+    // Pending observations (e.g. a process still running or incomplete JSON output)
+    // are not infrastructure failures and must not consume the blind-check budget.
+    if (failure.status === "error" || success.status === "error") {
+      this.countBlindCheck();
+    } else {
+      this.blindCount = 0;
+      this.scheduleNext();
+    }
+  }
+
+  private countBlindCheck(): void {
+    this.blindCount++;
+    if (this.blindCount >= (this.deps.spec.blind_checks ?? 3)) {
+      this.finish(this.deps.onBlindExhausted);
+      return;
+    }
+    this.scheduleNext();
+  }
+
+  private scheduleNext(): void {
+    if (this.stopped) return;
+    const remaining = this.deadline - Date.now();
+    if (remaining <= 0) {
+      this.finish(this.deps.onWatchTimeout);
+      return;
+    }
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      this.check();
+    }, Math.min(this.deps.spec.intervalMs, remaining));
+  }
+
+  private finish(callback: () => void): void {
+    this.finished = true;
+    this.stop();
+    callback();
+  }
+}
+
+type ConditionEvaluation =
+  | { status: "matched"; matched: boolean; condition?: Condition }
+  | { status: "pending" }
+  | { status: "error" };
+
+function evaluateConditionsDetailed(conditions: Condition[], ctx: WatchEvalContext): ConditionEvaluation {
+  let pending = false;
+  let error = false;
+  for (const condition of conditions) {
+    const result = evaluateCondition(condition, ctx);
+    if (result.status === "matched" && result.matched) return { status: "matched", matched: true, condition };
+    if (result.status === "pending") pending = true;
+    if (result.status === "error") error = true;
+  }
+  if (error) return { status: "error" };
+  if (pending) return { status: "pending" };
+  return { status: "matched", matched: false };
+}
+
+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":
+      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, "m");
+          compiledRegexes.set(condition, regex);
+        } catch {
+          return { status: "error" };
+        }
+      }
+      // Global/sticky expressions otherwise retain lastIndex between watch polls.
+      regex.lastIndex = 0;
+      return { status: "matched", matched: regex.test(matchSubject(ctx.output)) };
+    }
+    case "json_path_exists": {
+      let root: unknown;
+      try {
+        root = JSON.parse(ctx.output);
+      } catch {
+        return { status: "pending" };
+      }
+      const tokens = parseJsonPath(condition.path);
+      if (tokens === undefined) return { status: "error" };
+      let current = root;
+      for (const token of tokens) {
+        if (typeof token === "number") {
+          if (!Array.isArray(current) || token >= current.length) return { status: "matched", matched: false };
+          current = current[token];
+        } else {
+          if (current === null || typeof current !== "object" || !Object.hasOwn(current, token)) {
+            return { status: "matched", matched: false };
+          }
+          current = (current as Record<string, unknown>)[token];
+        }
+      }
+      return { status: "matched", matched: true };
+    }
+  }
+}
+
+function parseJsonPath(path: string): Array<string | number> | undefined {
+  if (!path.startsWith("$") || path.length === 0) return undefined;
+  const tokens: Array<string | number> = [];
+  let index = 1;
+  while (index < path.length) {
+    if (path[index] === ".") {
+      const start = ++index;
+      if (index >= path.length || !/[A-Za-z_$]/.test(path[index]!)) return undefined;
+      index++;
+      while (index < path.length && /[A-Za-z0-9_$-]/.test(path[index]!)) index++;
+      tokens.push(path.slice(start, index));
+      continue;
+    }
+    if (path[index] === "[") {
+      const end = path.indexOf("]", index + 1);
+      if (end < 0) return undefined;
+      const raw = path.slice(index + 1, end);
+      if (!/^\d+$/.test(raw)) return undefined;
+      const arrayIndex = Number(raw);
+      if (!Number.isSafeInteger(arrayIndex)) return undefined;
+      tokens.push(arrayIndex);
+      index = end + 1;
+      continue;
+    }
+    return undefined;
+  }
+  return tokens;
+}

package/src/guard/settle-guard.ts

@@ -0,0 +1,75 @@
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+import { envNumber } from "../core/env.ts";
+
+export class SettleGuard {
+  private readonly maxReminders: number;
+  private readonly heartbeatMs: number;
+  private reminders = 0;
+  private heartbeat?: ReturnType<typeof setInterval>;
+  private removeHooks: Array<() => void> = [];
+  private readonly pi: PiCtx;
+  private readonly registry: TaskRegistry;
+
+  constructor(pi: PiCtx, registry: TaskRegistry, opts?: { maxReminders?: number; heartbeatMs?: number }) {
+    this.pi = pi;
+    this.registry = registry;
+    this.maxReminders = opts?.maxReminders ?? 3;
+    this.heartbeatMs = opts?.heartbeatMs ?? envNumber("PI_ASYNC_HEARTBEAT_MS", 60_000, { integer: true, min: 0 });
+  }
+
+  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;
+    };
+    const beforeSettle = () => {
+      const active = this.registry.list({ includeHistory: false });
+      if (active.length === 0) { this.reminders = 0; this.reportActivity(); return; }
+      this.reportActivity();
+      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;
+      }
+      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 beforeRun = () => { this.reminders = 0; };
+    // 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);
+    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 task${total === 1 ? "" : "s"}` } : undefined);
+  }
+
+  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?.();
+  }
+}
+