pi-async 0.1.0 → 0.2.0

package/src/core/registry.ts

@@ -1,19 +1,22 @@
 import { randomUUID } from "node:crypto";
-import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, existsSync } from "node:fs";
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { killTree, spawnDetached } from "./spawn.ts";
-import { stripAnsi } from "./output.ts";
-import { deriveName, isTerminal, type KillKind, type RunOptions, type SyncResult, type TaskMode, type TaskSnapshot, type WatchSpec, type WaitOutcome } from "./task.ts";
-import { evalConditions, validateWatchSpec, WatchLoop } from "./watch.ts";
+import { killTree, spawnDetached, streamPaths } from "./spawn.ts";
+import { stripLogControls, truncateUtf8Bytes } from "./output.ts";
+import { envNumber } from "./env.ts";
+import { capName, deriveName, isTaskStatus, isTerminal, type FailureKind, type KillKind, type RunOptions, type SyncResult, type TaskMode, type TaskSnapshot, type WatchSpec, type WaitOutcome } from "./task.ts";
+import { evalConditions, validateWatchSpec, WatchLoop, type WatchOutput } from "./watch.ts";
 
 export interface RegistryEvents {
   onFinalize(snapshot: TaskSnapshot): void;
   onStateChange(snapshot: TaskSnapshot): void;
 }
-export interface RegistryConfig { dataDir: string; maxTasks?: number; maxOutputBytes?: number; }
+export interface RegistryConfig { dataDir: string; maxTasks?: number; maxOutputBytes?: number; retentionMs?: number; retentionCount?: number; }
 interface LiveTask { outputFile: string; exit?: Promise<{ code: number }>; timer?: ReturnType<typeof setTimeout>; delayTimer?: ReturnType<typeof setTimeout>; watcher?: ReturnType<typeof setInterval>; killKind?: KillKind; processExited?: boolean; }
 interface Waiter { ids: Set<string>; resolve: () => void; }
 const DEFAULT_MAX_OUTPUT = 20 * 1024 * 1024;
+const DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_RETENTION_COUNT = 100;
 
 export class TaskRegistry {
   private readonly tasks = new Map<string, TaskSnapshot>();
@@ -24,14 +27,19 @@ export class TaskRegistry {
   private events: RegistryEvents = { onFinalize: () => undefined, onStateChange: () => undefined };
   private readonly maxTasks: number;
   private readonly maxOutputBytes: number;
+  private readonly retentionMs: number;
+  private readonly retentionCount: number;
   private closed = false;
+  private reloading = false;
   private shutdownPromise?: Promise<void>;
 
   private readonly config: RegistryConfig;
   constructor(config: RegistryConfig) {
     this.config = config;
-    this.maxTasks = config.maxTasks ?? finiteEnvNumber("PI_ASYNC_MAX_TASKS", 32);
-    this.maxOutputBytes = config.maxOutputBytes ?? finiteEnvNumber("PI_ASYNC_MAX_OUTPUT_BYTES", DEFAULT_MAX_OUTPUT);
+    this.maxTasks = config.maxTasks ?? envNumber("PI_ASYNC_MAX_TASKS", 32, { integer: true, min: 1 });
+    this.maxOutputBytes = config.maxOutputBytes ?? envNumber("PI_ASYNC_MAX_OUTPUT_BYTES", DEFAULT_MAX_OUTPUT, { integer: true, min: 0 });
+    this.retentionMs = config.retentionMs ?? envNumber("PI_ASYNC_RETENTION_MS", DEFAULT_RETENTION_MS, { integer: true, min: 0 });
+    this.retentionCount = config.retentionCount ?? envNumber("PI_ASYNC_RETENTION_COUNT", DEFAULT_RETENTION_COUNT, { integer: true, min: 0 });
     mkdirSync(config.dataDir, { recursive: true });
   }
 
@@ -50,7 +58,7 @@ export class TaskRegistry {
     const taskId = randomUUID();
     const outputFile = join(this.config.dataDir, `${taskId}.output`);
     const task: TaskSnapshot = {
-      taskId, name: opts.name?.slice(0, 48) ?? deriveName(opts.command), command: opts.command, mode: "delayed", status: "pending",
+      taskId, name: opts.name ? capName(opts.name) : deriveName(opts.command), command: opts.command, mode: "delayed", status: "pending",
       createdAt, dueAt: createdAt + delayMs, taskTimeoutMs: opts.taskTimeoutMs, notified: false, outputConsumed: false,
       ...(opts.watch ? { watch: opts.watch } : {}),
       metadata: { notifyOnCompletion: opts.notifyOnCompletion ?? true, triggerOnCompletion: opts.triggerOnCompletion ?? true, outputFile, ...(opts.env ? { delayedEnv: opts.env } : {}) },
@@ -72,13 +80,19 @@ export class TaskRegistry {
     let promoted = false;
     try {
       const outcome = await this.wait([task.taskId], timeoutMs, signal);
-      if ("notReady" in outcome && onTimeout === "promote" && !isTerminal(task.status)) {
+      // Timeout / Esc: stop waiting. promote → background + promoted flag; abort → Esc semantics
+      // (keep process, bookkeeping mode becomes background so the receipt is not "sync+running").
+      if ("notReady" in outcome && !isTerminal(task.status)) {
         task.mode = "background";
-        promoted = true;
+        if (onTimeout === "promote") promoted = true;
         this.emitState(task);
       }
     } catch (error) {
       if (!signal?.aborted) throw error;
+      if (!isTerminal(task.status) && task.mode === "sync") {
+        task.mode = "background";
+        this.emitState(task);
+      }
     }
     return this.syncResult(task, promoted);
   }
@@ -100,14 +114,16 @@ export class TaskRegistry {
       onBlindExhausted: () => {
         const current = this.tasks.get(taskId);
         if (current && !isTerminal(current.status)) {
-          this.finalize(current, "failed");
+          current.failureKind = "blind_exhausted";
+          this.finalize(current, "failed", undefined, "watch_failure");
           void this.kill(taskId, "watch_failure").catch((error: unknown) => console.error(`pi-async: blind-check kill failed for task ${taskId}`, error));
         }
       },
       onWatchTimeout: () => {
         const current = this.tasks.get(taskId);
         if (current && !isTerminal(current.status)) {
-          this.finalize(current, "failed");
+          current.failureKind = "watch_timeout";
+          this.finalize(current, "failed", undefined, "watch_failure");
           void this.kill(taskId, "watch_failure").catch((error: unknown) => console.error(`pi-async: watch-timeout kill failed for task ${taskId}`, error));
         }
       },
@@ -135,7 +151,7 @@ export class TaskRegistry {
     const taskId = randomUUID();
     const outputFile = join(this.config.dataDir, `${taskId}.output`);
     const task: TaskSnapshot = {
-      taskId, name: opts.name?.slice(0, 48) ?? deriveName(opts.command), command: opts.command, mode, status: "running",
+      taskId, name: opts.name ? capName(opts.name) : deriveName(opts.command), command: opts.command, mode, status: "running",
       createdAt: Date.now(), startedAt: Date.now(), taskTimeoutMs: opts.taskTimeoutMs, notified: false, outputConsumed: false,
       ...(opts.watch ? { watch: opts.watch } : {}),
       metadata: { notifyOnCompletion: opts.notifyOnCompletion ?? true, triggerOnCompletion: opts.triggerOnCompletion ?? true, outputFile },
@@ -168,9 +184,9 @@ export class TaskRegistry {
       if (task.metadata.capped || task.metadata.watchSuccess !== undefined) this.persist(task);
       if (!isTerminal(task.status) && task.watch) {
         try {
-          const output = this.readWatchOutput(task.taskId);
-          if (evalConditions(task.watch.failure_when, { output, exitCode: code })) this.finalize(task, "killed", undefined, "watch_failure");
-          else if (evalConditions(task.watch.success_when, { output, exitCode: code })) {
+          const streams = this.readWatchOutput(task.taskId);
+          if (evalConditions(task.watch.failure_when, { ...streams, exitCode: code })) this.finalize(task, "killed", undefined, "watch_failure");
+          else if (evalConditions(task.watch.success_when, { ...streams, exitCode: code })) {
             task.metadata.watchSuccess = `success_when matched after process exit: ${JSON.stringify(task.watch.success_when)}`;
             this.finalize(task, "completed", code);
           }
@@ -219,11 +235,16 @@ export class TaskRegistry {
     }, delayMs);
   }
 
-  private readWatchOutput(taskId: string): string {
+  private readWatchOutput(taskId: string): WatchOutput {
     const task = this.tasks.get(taskId);
     if (!task) throw new Error(`Unknown task id: ${taskId}`);
     const outputFile = String(task.metadata.outputFile ?? this.live.get(taskId)?.outputFile ?? join(this.config.dataDir, `${taskId}.output`));
-    return stripAnsi(readFileSync(outputFile, "utf8"));
+    // Missing primary output must throw so WatchLoop blind_checks can fire (#37/#68 + CONTRACT).
+    // stripLogControls: ANSI + bare C0 for model/watch paths (#18); streams stay distinct (#4).
+    const output = stripLogControls(readFileSync(outputFile, "utf8"));
+    const { stdoutFile, stderrFile } = streamPaths(outputFile);
+    const readSide = (file: string): string => existsSync(file) ? stripLogControls(readFileSync(file, "utf8")) : "";
+    return { output, stdout: readSide(stdoutFile), stderr: readSide(stderrFile) };
   }
 
   private syncResult(task: TaskSnapshot, promoted: boolean): SyncResult {
@@ -231,7 +252,7 @@ export class TaskRegistry {
     const lines = outputTail.split("\n");
     if (lines.length > 200) outputTail = lines.slice(-200).join("\n");
     const bytes = Buffer.from(outputTail, "utf8");
-    if (bytes.byteLength > 8192) outputTail = bytes.subarray(bytes.byteLength - 8192).toString("utf8");
+    if (bytes.byteLength > 8192) outputTail = truncateUtf8Bytes(bytes, 8192, true);
     return {
       taskId: task.taskId, name: task.name, status: task.status, mode: task.mode,
       outputHint: `Use async_logs with taskId ${task.taskId} to inspect early output.`,
@@ -243,8 +264,13 @@ export class TaskRegistry {
   get(taskId: string): TaskSnapshot | undefined { return this.tasks.get(taskId); }
   list(opts?: { includeHistory?: boolean }): TaskSnapshot[] { const all = [...this.tasks.values()]; return opts?.includeHistory === false ? all.filter((task) => !isTerminal(task.status)) : all; }
 
-  wait(taskIds: string[], timeoutMs: number, signal?: AbortSignal): Promise<WaitOutcome> {
-    const uniqueIds = [...new Set(taskIds)];
+  wait(taskIds: string[] | string, timeoutMs: number, signal?: AbortSignal): Promise<WaitOutcome> {
+    // A bare string is one id; String is iterable so `[...new Set("uuid")]` would split into characters (#40).
+    const idList = typeof taskIds === "string" ? [taskIds] : taskIds;
+    if (!Array.isArray(idList) || idList.some((id) => typeof id !== "string")) {
+      return Promise.reject(new TypeError(`taskIds must be an array of strings (got ${typeof taskIds})`));
+    }
+    const uniqueIds = [...new Set(idList)];
     const unknown = uniqueIds.filter((id) => !this.tasks.has(id));
     if (unknown.length) return Promise.reject(new Error(`Unknown task id(s): ${unknown.join(", ")}`));
     if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("Wait aborted"));
@@ -260,7 +286,12 @@ export class TaskRegistry {
       const timeout = setTimeout(() => {
         if (settled) return;
         settled = true; cleanup();
-        resolve({ notReady: pending().map((task) => ({ taskId: task.taskId, status: task.status as "running" | "pending", elapsedMs: Date.now() - task.createdAt })) });
+        const still = pending();
+        const finishedIds = uniqueIds.filter((id) => !still.some((task) => task.taskId === id));
+        const notReady = still.map((task) => ({ taskId: task.taskId, status: task.status as "running" | "pending", elapsedMs: Date.now() - task.createdAt }));
+        // REV-7: no finished → pure { notReady }; mixed → { results, notReady }.
+        if (finishedIds.length === 0) resolve({ notReady });
+        else resolve({ results: finishedIds.map((id) => this.waitResult(this.tasks.get(id)!)), notReady });
       }, Math.max(0, timeoutMs));
       const abort = () => { if (settled) return; settled = true; cleanup(); reject(signal?.reason ?? new Error("Wait aborted")); };
       const cleanup = () => { clearTimeout(timeout); signal?.removeEventListener("abort", abort); this.waiters.delete(waiter); };
@@ -276,8 +307,9 @@ export class TaskRegistry {
     if (!existsSync(fullPath)) return { text: "", truncated: false, fullPath };
     const data = readFileSync(fullPath);
     const maxBytes = Math.min(50 * 1024, Math.max(0, opts.maxBytes ?? 50 * 1024));
-    const selected = opts.tail === false ? data.subarray(0, maxBytes) : data.subarray(Math.max(0, data.length - maxBytes));
-    return { text: stripAnsi(selected.toString("utf8")), truncated: data.length > selected.length, fullPath };
+    const truncated = data.length > maxBytes;
+    const text = stripLogControls(truncateUtf8Bytes(data, maxBytes, opts.tail !== false));
+    return { text, truncated, fullPath };
   }
 
   async kill(taskId: string, kind: KillKind): Promise<void> {
@@ -294,12 +326,22 @@ export class TaskRegistry {
     }
     if (isTerminal(task.status) && live.processExited) return;
     live.killKind = kind;
+    let confirmed = true;
     if (task.pid && !live.processExited) {
       const result = await killTree(task.pid);
-      if (!result.confirmed) throw new Error("Descendant processes may have leaked");
+      confirmed = result.confirmed;
     }
+    // Finalize first so async_kill can always return { taskId, status } even when the
+    // confirmation probe cannot prove the group is gone (#6).
     if (!isTerminal(task.status)) this.finalize(task, "killed", undefined, kind);
-    else if (live.timer) { clearTimeout(live.timer); live.timer = undefined; }
+    else {
+      // D4 / leftover process: record kill without flipping the settled observation status (#33).
+      task.killKind = kind;
+      try { this.persist(task); } catch { /* dataDir may already be gone during teardown */ }
+      if (live.timer) { clearTimeout(live.timer); live.timer = undefined; }
+    }
+    // Finalize-first (#6): still surface confirmation failure after status is settled.
+    if (!confirmed) throw new Error("Descendant processes may have leaked");
   }
   cancel(taskId: string): boolean {
     const task = this.tasks.get(taskId);
@@ -320,7 +362,18 @@ export class TaskRegistry {
     if (this.shutdownPromise) return this.shutdownPromise;
     this.closed = true;
     this.shutdownPromise = (async () => {
+      // Pending delayed tasks hold no OS resources. Clear their timers but leave snapshots
+      // as pending so same-process /reload can restore them (CONTRACT reload / #20).
+      for (const task of this.tasks.values()) {
+        if (task.status !== "pending") continue;
+        const live = this.live.get(task.taskId);
+        if (live?.delayTimer) { clearTimeout(live.delayTimer); live.delayTimer = undefined; }
+        const watch = this.watchLoops.get(task.taskId);
+        watch?.stop();
+        this.watchLoops.delete(task.taskId);
+      }
       const ids = [...this.tasks.values()].filter((task) => {
+        if (task.status === "pending") return false;
         const live = this.live.get(task.taskId);
         return !isTerminal(task.status) || (task.pid !== undefined && (live ? !live.processExited : this.pidAlive(task.pid)));
       }).map((task) => task.taskId);
@@ -338,48 +391,103 @@ export class TaskRegistry {
     return this.shutdownPromise;
   }
   async reloadFromDisk(): Promise<void> {
-    for (const file of readdirSync(this.config.dataDir).filter((name) => name.endsWith(".json"))) {
-      try {
-        const snapshot = JSON.parse(readFileSync(join(this.config.dataDir, file), "utf8")) as TaskSnapshot;
-        if (!snapshot.taskId || this.tasks.has(snapshot.taskId)) continue;
-        this.tasks.set(snapshot.taskId, snapshot);
-        if (snapshot.status === "pending" && snapshot.mode === "delayed") {
-          const outputFile = String(snapshot.metadata.outputFile ?? join(this.config.dataDir, `${snapshot.taskId}.output`));
-          this.live.set(snapshot.taskId, { outputFile });
-          if (snapshot.watch) this.attachWatch(snapshot.taskId, snapshot.watch);
-          const dueAt = snapshot.dueAt ?? Date.now();
-          this.scheduleDelayedStart(snapshot, Math.max(0, dueAt - Date.now()));
-          continue;
-        }
-        if ((snapshot.status === "running" || snapshot.metadata.watchSuccess !== undefined) && snapshot.pid && this.pidAlive(snapshot.pid)) {
-          const outputFile = String(snapshot.metadata.outputFile ?? join(this.config.dataDir, `${snapshot.taskId}.output`));
-          const live: LiveTask = { outputFile };
-          this.live.set(snapshot.taskId, live);
-          live.watcher = setInterval(() => {
-            if (snapshot.pid && !this.pidAlive(snapshot.pid)) {
-              if (live.watcher) clearInterval(live.watcher);
-              live.processExited = true;
-              if (live.timer) { clearTimeout(live.timer); live.timer = undefined; }
-              snapshot.metadata.capped = this.isOutputCapped(snapshot);
-              if (!isTerminal(snapshot.status)) {
-                if (live.killKind) this.finalize(snapshot, "killed", undefined, live.killKind);
-                else if (snapshot.metadata.capped) this.finalize(snapshot, "failed", undefined, "output_cap");
-                else { snapshot.failureKind = "lost"; this.finalize(snapshot, "failed"); }
+    this.reloading = true;
+    try {
+      for (const file of readdirSync(this.config.dataDir).filter((name) => name.endsWith(".json"))) {
+        try {
+          const snapshot = JSON.parse(readFileSync(join(this.config.dataDir, file), "utf8")) as TaskSnapshot;
+          // #34: skip unknown status values from disk.
+          if (!snapshot.taskId || !isTaskStatus(snapshot.status) || this.tasks.has(snapshot.taskId)) continue;
+          this.tasks.set(snapshot.taskId, snapshot);
+          if (snapshot.status === "pending" && snapshot.mode === "delayed") {
+            const outputFile = String(snapshot.metadata.outputFile ?? join(this.config.dataDir, `${snapshot.taskId}.output`));
+            this.live.set(snapshot.taskId, { outputFile });
+            if (snapshot.watch) this.attachWatch(snapshot.taskId, snapshot.watch);
+            const dueAt = snapshot.dueAt ?? Date.now();
+            this.scheduleDelayedStart(snapshot, Math.max(0, dueAt - Date.now()));
+            continue;
+          }
+          if ((snapshot.status === "running" || snapshot.metadata.watchSuccess !== undefined) && snapshot.pid && this.pidAlive(snapshot.pid)) {
+            const outputFile = String(snapshot.metadata.outputFile ?? join(this.config.dataDir, `${snapshot.taskId}.output`));
+            const live: LiveTask = { outputFile };
+            this.live.set(snapshot.taskId, live);
+            live.watcher = setInterval(() => {
+              if (snapshot.pid && !this.pidAlive(snapshot.pid)) {
+                if (live.watcher) clearInterval(live.watcher);
+                live.processExited = true;
+                if (live.timer) { clearTimeout(live.timer); live.timer = undefined; }
+                snapshot.metadata.capped = this.isOutputCapped(snapshot);
+                if (!isTerminal(snapshot.status)) {
+                  if (live.killKind) this.finalize(snapshot, "killed", undefined, live.killKind);
+                  else if (snapshot.metadata.capped) this.finalize(snapshot, "failed", undefined, "output_cap");
+                  else { snapshot.failureKind = "lost"; this.finalize(snapshot, "failed"); }
+                }
               }
-            }
-          }, 100);
-          live.watcher.unref?.();
-          if (snapshot.status === "running" && snapshot.watch) this.attachWatch(snapshot.taskId, snapshot.watch);
-        } else if (snapshot.status === "running") {
-          snapshot.status = "failed"; snapshot.failureKind = "lost"; snapshot.finishedAt = Date.now(); this.persist(snapshot); this.events.onFinalize(snapshot);
-        }
-      } catch { /* Ignore incomplete/corrupt metadata files; atomic writer leaves prior version intact. */ }
+            }, 100);
+            live.watcher.unref?.();
+            if (snapshot.status === "running" && snapshot.watch) this.attachWatch(snapshot.taskId, snapshot.watch);
+          } else if (snapshot.status === "running") {
+            snapshot.status = "failed"; snapshot.failureKind = "lost"; snapshot.finishedAt = Date.now(); this.persist(snapshot); this.events.onFinalize(snapshot);
+          }
+        } catch { /* Ignore incomplete/corrupt metadata files; atomic writer leaves prior version intact. */ }
+      }
+    } finally {
+      this.reloading = false;
+      this.prune();
     }
   }
 
-  private waitResult(task: TaskSnapshot): { taskId: string; status: TaskSnapshot["status"]; exitCode?: number; outputTail: string } {
+  /**
+   * Drop terminal-task artifacts that fall outside the retention window.
+   *
+   * Policy (per dataDir): keep the union of (1) the newest `retentionCount`
+   * terminal tasks by finishedAt/createdAt and (2) any terminal task still
+   * younger than `retentionMs`. Everything else terminal is deleted
+   * (.json + .output via metadata.outputFile) and removed from memory.
+   * Non-terminal tasks are never touched. Missing files are ignored.
+   */
+  prune(now = Date.now()): { pruned: number } {
+    const terminal = this.list({ includeHistory: true })
+      .filter((task) => isTerminal(task.status))
+      .sort((a, b) => (b.finishedAt ?? b.createdAt) - (a.finishedAt ?? a.createdAt));
+    let pruned = 0;
+    for (let i = 0; i < terminal.length; i++) {
+      const task = terminal[i]!;
+      const ageAnchor = task.finishedAt ?? task.createdAt;
+      const withinCount = i < this.retentionCount;
+      const withinAge = now - ageAnchor < this.retentionMs;
+      if (withinCount || withinAge) continue;
+      this.removeArtifacts(task);
+      pruned++;
+    }
+    return { pruned };
+  }
+
+  private removeArtifacts(task: TaskSnapshot): void {
+    const outputFile = String(task.metadata.outputFile ?? join(this.config.dataDir, `${task.taskId}.output`));
+    try { rmSync(outputFile, { force: true }); } catch { /* force already ignores ENOENT; swallow other rare races */ }
+    try { rmSync(join(this.config.dataDir, `${task.taskId}.json`), { force: true }); } catch { /* same */ }
+    const live = this.live.get(task.taskId);
+    if (live?.timer) clearTimeout(live.timer);
+    if (live?.delayTimer) clearTimeout(live.delayTimer);
+    if (live?.watcher) clearInterval(live.watcher);
+    this.live.delete(task.taskId);
+    this.watchLoops.get(task.taskId)?.stop();
+    this.watchLoops.delete(task.taskId);
+    this.tasks.delete(task.taskId);
+    this.notifyClaims.delete(task.taskId);
+  }
+
+  private waitResult(task: TaskSnapshot): { taskId: string; status: TaskSnapshot["status"]; exitCode?: number; outputTail: string; killKind?: KillKind; failureKind?: FailureKind } {
     this.consume(task.taskId);
-    return { taskId: task.taskId, status: task.status, ...(task.exitCode === undefined ? {} : { exitCode: task.exitCode }), outputTail: this.logs(task.taskId, { maxBytes: 8192, tail: true }).text };
+    return {
+      taskId: task.taskId,
+      status: task.status,
+      ...(task.exitCode === undefined ? {} : { exitCode: task.exitCode }),
+      outputTail: this.logs(task.taskId, { maxBytes: 8192, tail: true }).text,
+      ...(task.killKind ? { killKind: task.killKind } : {}),
+      ...(task.failureKind ? { failureKind: task.failureKind } : {}),
+    };
   }
   private finalize(task: TaskSnapshot, status: TaskSnapshot["status"], code?: number, killKind?: KillKind): void {
     if (isTerminal(task.status)) return;
@@ -390,8 +498,14 @@ export class TaskRegistry {
     if (live?.watcher) clearInterval(live.watcher);
     // D4: watch success settles the observed task but leaves the process under its task timeout.
     if (live?.timer && !(task.metadata.watchSuccess !== undefined && !live.processExited)) { clearTimeout(live.timer); live.timer = undefined; }
+    // #15: a waiter already owns this result — set the suppression latch before onFinalize
+    // can claimNotification / sendCompletionNotification.
+    if ([...this.waiters].some((waiter) => waiter.ids.has(task.taskId))) {
+      task.outputConsumed = true;
+    }
     this.persist(task); this.emitState(task); this.events.onFinalize(task);
     for (const waiter of [...this.waiters]) if (waiter.ids.has(task.taskId)) waiter.resolve();
+    if (!this.reloading) this.prune();
   }
   private emitState(task: TaskSnapshot): void { this.persist(task); this.events.onStateChange(task); }
   private persist(task: TaskSnapshot): void {
@@ -405,12 +519,25 @@ export class TaskRegistry {
     } catch { return task.metadata.capped === true; }
   }
   private pidAlive(pid: number): boolean {
-    try { process.kill(-pid, 0); return true; }
-    catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; }
+    // Prefer /proc so a zombie-only group is not treated as alive (#6 / reload lost detection).
+    try {
+      for (const entry of readdirSync("/proc")) {
+        if (!/^\d+$/.test(entry)) continue;
+        try {
+          const stat = readFileSync(join("/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 === pid && state !== "Z") return true;
+        } catch { /* raced with exit */ }
+      }
+      return false;
+    } catch {
+      try { process.kill(-pid, 0); return true; }
+      catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; }
+    }
   }
 }
 
-function finiteEnvNumber(name: string, fallback: number): number {
-  const parsed = Number(process.env[name] ?? fallback);
-  return Number.isFinite(parsed) ? parsed : fallback;
-}

package/src/core/spawn.ts

@@ -1,4 +1,4 @@
-import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+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";
@@ -6,23 +6,38 @@ import type { TaskSnapshot } from "./task.ts";
 
 export interface SpawnHandle { pid: number; exit: Promise<{ code: number }>; }
 
-/** Start a shell command in its own POSIX process group and capture merged output. */
+/** 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 output = createWriteStream(opts.outputFile, { flags: "w", mode: 0o600 });
+  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 +50,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 +73,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 +96,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 +134,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 =
@@ -59,9 +72,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 +89,7 @@ export interface TaskSnapshot {
   pid?: number;
   exitCode?: number;
   killKind?: KillKind;
-  failureKind?: "lost";
+  failureKind?: FailureKind;
   createdAt: number;
   startedAt?: number;
   finishedAt?: number;