pi-async 0.2.0 → 0.3.0

package/src/core/spawn.ts

@@ -1,29 +1,64 @@
-import { createWriteStream, existsSync, mkdirSync, readdirSync, 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 }>; }
 
+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): { stdoutFile: string; stderrFile: string } {
+export function streamPaths(outputFile: string): { stdout: string; stderr: string } {
   if (outputFile.endsWith(".output")) {
     const base = outputFile.slice(0, -".output".length);
-    return { stdoutFile: `${base}.stdout`, stderrFile: `${base}.stderr` };
+    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}`);
   }
-  return { stdoutFile: `${outputFile}.stdout`, stderrFile: `${outputFile}.stderr` };
+  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: { outputFile: string; env?: Record<string, string> }): SpawnHandle {
+export function spawnDetached(command: string, opts: SpawnOptions): SpawnHandle {
+  assertUsableCwd(opts.cwd);
   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 { 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 });

package/src/core/task.ts

@@ -56,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 {
@@ -99,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/guard/settle-guard.ts

@@ -1,75 +1,184 @@
 import type { PiCtx } from "../core/notify.ts";
 import type { TaskRegistry } from "../core/registry.ts";
-import { envNumber } from "../core/env.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 ?? 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;
+    // 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 task${total === 1 ? "" : "s"}` } : 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();
+    }
   }
 }
-

package/src/tools/index.ts

@@ -1,6 +1,23 @@
 import type { PiCtx } from "../core/notify.ts";
 import type { TaskRegistry } from "../core/registry.ts";
-import { isTerminal, type WatchSpec } from "../core/task.ts";
+import { isTaskStatus, isTerminal, TASK_STATUSES, type TaskSnapshot, type TaskStatus, type WatchSpec } from "../core/task.ts";
+
+/**
+ * Structural view of pi's event-handler context (`ExtensionToolContext`).
+ *
+ * 0.3.0 deliberately does NOT import pi's `ExtensionToolContext` type: the
+ * package keeps its type baseline at pi 1.2.0, where the 5th `execute`
+ * argument existed but surface details moved between 1.2 and 1.5. Only `cwd`
+ * (session working directory) and `sessionManager` (data-dir resolution) are
+ * read, so a structural type is enough and stays compatible across hosts.
+ */
+export interface ToolContext {
+  cwd?: string;
+  sessionManager?: {
+    getSessionDir?: () => string;
+    getSessionId?: () => string;
+  };
+}
 
 /**
  * Wrap an extension-tool return value into pi's ToolResultMessage shape.
@@ -23,6 +40,26 @@ function toolResult(payload: unknown, isError = false): { content: Array<{ type:
 
 const promptGuidelines = "Check commands must not swallow errors with || true; map unknown states to failure; prefer structured output and jq -e; anchor output_matches regexes (compiled with multiline `m`: ^/$ are line boundaries) to avoid premature matches; prefer stdout_contains for simple cases and avoid nested quantifiers.";
 const MAX_LOG_BYTES = 50 * 1024;
+const DEFAULT_MAX_SYNC_TIMEOUT_MS = 600_000;
+const MAX_STATUS_LIMIT = 50;
+const DEFAULT_STATUS_LIMIT = 50;
+
+/** One-line snippet shown in the default system prompt's "Available tools" section (D-17). */
+const ASYNC_RUN_PROMPT_SNIPPET = "Run a shell command in the background, with optional watch conditions and completion notification.";
+
+/** Guidelines appended to the default system prompt while async_run is active (D-17). */
+const ASYNC_RUN_PROMPT_GUIDELINES = [
+  "Use async_run for long-running commands (servers, watchers, builds over a minute) instead of a blocking bash call; short commands belong in bash.",
+  "Collect background work with async_wait, inspect it with async_logs, and use async_status to see what is still active before ending a turn.",
+  "Pass name so later async_wait/async_logs/async_kill calls can address the task by name instead of its opaque taskId.",
+];
+
+/** `PI_ASYNC_MAX_SYNC_TIMEOUT_MS`, defaulting to 10 minutes when unset/invalid. */
+function resolveMaxSyncTimeoutMs(): number {
+  const parsed = Number(process.env.PI_ASYNC_MAX_SYNC_TIMEOUT_MS);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : DEFAULT_MAX_SYNC_TIMEOUT_MS;
+}
+
 const schema = (properties: Record<string, unknown>, required: string[] = [], allOf: unknown[] = []) => ({ type: "object", properties, required, additionalProperties: false, ...(allOf.length ? { allOf } : {}) });
 const stringField = { type: "string" };
 const timeoutField = { type: "number", minimum: 0 };
@@ -45,19 +82,78 @@ const watchSchema = {
   }, required: ["intervalMs", "timeoutMs", "success_when", "failure_when"], additionalProperties: false,
 };
 
-/** Register the frozen five-tool surface. */
-export function registerTools(pi: PiCtx, registry: TaskRegistry): void {
-  type ToolDef = { name: string; label: string; description: string; parameters: unknown; execute: (toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown> };
+/** Number of the clamped `async_status` limit: default 50, clamped to 1–50 (D-08). */
+function clampStatusLimit(value: unknown): number {
+  const raw = Number(value);
+  if (!Number.isFinite(raw)) return DEFAULT_STATUS_LIMIT;
+  return Math.min(MAX_STATUS_LIMIT, Math.max(1, Math.floor(raw)));
+}
+
+/**
+ * `async_status` redaction (PLAN §2.7): `metadata.delayedEnv` values become
+ * `"***"` while keys survive. Returns a shallow copy — the registry's live
+ * snapshot must never be mutated by a read-only tool.
+ */
+function redactSnapshot(task: TaskSnapshot): TaskSnapshot {
+  const metadata = { ...task.metadata };
+  const delayedEnv = metadata.delayedEnv;
+  if (delayedEnv && typeof delayedEnv === "object" && !Array.isArray(delayedEnv)) {
+    const redacted: Record<string, string> = {};
+    for (const key of Object.keys(delayedEnv as Record<string, unknown>)) redacted[key] = "***";
+    metadata.delayedEnv = redacted;
+  }
+  return { ...task, metadata };
+}
+
+/** Descending by `finishedAt ?? createdAt` (D-08 history ordering). */
+function byRecency(a: TaskSnapshot, b: TaskSnapshot): number {
+  return (b.finishedAt ?? b.createdAt) - (a.finishedAt ?? a.createdAt);
+}
+
+/**
+ * Register the frozen five-tool surface.
+ *
+ * `ensureConfigured` lets the extension wire a lazy, once-only
+ * `registry.configure({dataDir, cwd})` before the first tool call — tools may
+ * run before `session_start` (e.g. an immediate tool call), and the registry
+ * then still needs its session cwd/dataDir (PLAN §2.8). Tools stay usable
+ * without it (tests, direct embedding).
+ */
+export function registerTools(pi: PiCtx, registry: TaskRegistry, ensureConfigured?: (ctx?: ToolContext) => void): void {
+  type ToolDef = {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet?: string;
+    promptGuidelines?: string[];
+    parameters: unknown;
+    execute: (toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal, onUpdate?: unknown, ctx?: ToolContext) => Promise<unknown>;
+  };
   // SAFETY: ExtensionAPI exposes registerTool at runtime; this local structural view keeps schemas dependency-free.
   const api = pi as unknown as { registerTool?: (tool: ToolDef) => void };
   if (!api.registerTool) throw new Error("Pi host does not expose registerTool");
+  const maxSyncTimeoutMs = resolveMaxSyncTimeoutMs();
+  const configure = (ctx?: ToolContext): void => ensureConfigured?.(ctx);
+
   api.registerTool({
     name: "async_run", label: "Run async command",
     description: `Run a background, delayed, or synchronous shell command. mode=sync requires timeoutMs; mode=delayed requires delayMs. onTimeout (sync only): "promote" (default) hands the still-running task to background and returns; "abort" stops WAITING only — the command keeps running in the background and will still notify on completion (Esc semantics; does not kill). ${promptGuidelines}`,
+    promptSnippet: ASYNC_RUN_PROMPT_SNIPPET,
+    promptGuidelines: ASYNC_RUN_PROMPT_GUIDELINES,
     // Mode-conditional required fields + mode-scoped rejects enforced in execute (#45/#42),
     // not allOf/then (host validator emits opaque "must match then schema").
-    parameters: schema({ command: stringField, name: stringField, mode: { type: "string", enum: ["background", "sync", "delayed"], default: "background" }, timeoutMs: timeoutField, delayMs: timeoutField, taskTimeoutMs: timeoutField, onTimeout: { type: "string", enum: ["promote", "abort"], default: "promote" }, notifyOnCompletion: { type: "boolean" }, triggerOnCompletion: { type: "boolean" }, env: { type: "object", additionalProperties: { type: "string" } }, watch: watchSchema }, ["command"]),
-    execute: async (_id, params, signal) => {
+    parameters: schema({
+      command: stringField, name: stringField,
+      mode: { type: "string", enum: ["background", "sync", "delayed"], default: "background" },
+      timeoutMs: { type: "number", minimum: 0, maximum: maxSyncTimeoutMs, description: `Sync-mode wait budget in ms (max ${maxSyncTimeoutMs}, from PI_ASYNC_MAX_SYNC_TIMEOUT_MS).` },
+      delayMs: timeoutField, taskTimeoutMs: timeoutField,
+      onTimeout: { type: "string", enum: ["promote", "abort"], default: "promote" },
+      notifyOnCompletion: { type: "boolean" }, triggerOnCompletion: { type: "boolean" },
+      env: { type: "object", additionalProperties: { type: "string" } },
+      watch: watchSchema,
+    }, ["command"]),
+    execute: async (_id, params, signal, _onUpdate, ctx) => {
+      configure(ctx);
       const mode = String(params.mode ?? "background");
       if (mode !== "background" && mode !== "sync" && mode !== "delayed") throw new Error(`Unsupported async_run mode: ${mode}`);
       const command = String(params.command ?? "");
@@ -65,50 +161,103 @@ export function registerTools(pi: PiCtx, registry: TaskRegistry): void {
       if (mode === "delayed" && params.delayMs === undefined) throw new Error("delayMs is required for delayed mode");
       if (params.watch !== undefined && mode === "sync") throw new Error("watch is only supported for background and delayed modes");
       if (mode !== "sync" && params.timeoutMs !== undefined) throw new Error("timeoutMs is only valid for sync mode (use taskTimeoutMs to bound background/delayed tasks)");
+      if (mode !== "sync" && params.onTimeout !== undefined) throw new Error("onTimeout is only valid for sync mode");
       if (mode !== "delayed" && params.delayMs !== undefined) throw new Error("delayMs is only valid for delayed mode");
       const options = {
         command,
+        cwd: sessionCwd(ctx),
         ...(typeof params.name === "string" ? { name: params.name } : {}),
         ...(typeof params.taskTimeoutMs === "number" ? { taskTimeoutMs: params.taskTimeoutMs } : {}),
         ...(typeof params.notifyOnCompletion === "boolean" ? { notifyOnCompletion: params.notifyOnCompletion } : {}),
         ...(typeof params.triggerOnCompletion === "boolean" ? { triggerOnCompletion: params.triggerOnCompletion } : {}),
         ...(params.env && typeof params.env === "object" ? { env: params.env as Record<string, string> } : {}),
-        ...(params.watch && typeof params.watch === "object" ? { watch: params.watch as WatchSpec } : {}),
+        ...(mode !== "sync" && params.watch && typeof params.watch === "object" ? { watch: params.watch as WatchSpec } : {}),
       };
-      if (mode === "sync") { const r = await registry.runSync({ ...options, mode: "sync" }, Number(params.timeoutMs), params.onTimeout === "abort" ? "abort" : "promote", signal); return toolResult(r); }
+      if (mode === "sync") {
+        const timeoutMs = Number(params.timeoutMs);
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error("timeoutMs must be a non-negative finite number");
+        if (timeoutMs > maxSyncTimeoutMs) {
+          throw new Error(`timeoutMs must be at most ${maxSyncTimeoutMs} ms for sync mode (raise PI_ASYNC_MAX_SYNC_TIMEOUT_MS to allow longer waits; promote the task to background instead)`);
+        }
+        const result = await registry.runSync({ ...options, mode: "sync" }, timeoutMs, params.onTimeout === "abort" ? "abort" : "promote", signal);
+        // D-19 (narrowing D-18 to PLAN §2.7's exact wording): only a *finished* sync run with a
+        // non-zero exit is a tool error. promote/abort timeouts leave the task running
+        // (status "running") — that is not a non-zero exit and must not read as a failure;
+        // the payload still carries the full SyncResult (status/promoted/exitCode/outputTail).
+        const ended = result.status === "completed" || result.status === "failed" || result.status === "killed";
+        const isError = ended && (result.status !== "completed" || (result.exitCode !== undefined && result.exitCode !== 0));
+        return toolResult(result, isError);
+      }
       const task = mode === "delayed"
-        ? registry.scheduleDelayed({ ...options, mode: "delayed" }, Number(params.delayMs))
+        ? registry.scheduleDelayed(options, Number(params.delayMs))
         : registry.submit({ ...options, mode: "background" });
       return toolResult({ taskId: task.taskId, name: task.name, status: task.status, mode: task.mode, outputHint: `Use async_logs with taskId ${task.taskId} to inspect early output.` });
     },
   });
-  api.registerTool({ name: "async_wait", label: "Wait for async tasks", description: "Wait for tasks to finish or return notReady; waiting does not kill tasks.", parameters: schema({ taskIds: { type: "array", items: stringField }, timeoutMs: timeoutField }, ["taskIds", "timeoutMs"]), execute: async (_id, params, signal) => {
-    if (params.timeoutMs === undefined) throw new Error("timeoutMs is required");
-    return toolResult(await registry.wait(params.taskIds as string[], Number(params.timeoutMs), signal));
-  } });
-  api.registerTool({ name: "async_logs", label: "Read async output", description: "Read bounded, ANSI-stripped task output.", parameters: schema({ taskId: stringField, maxBytes: { type: "number", minimum: 0, maximum: MAX_LOG_BYTES }, tail: { type: "boolean" } }, ["taskId"]), execute: async (_id, params) => {
-    const maxBytes = params.maxBytes === undefined ? MAX_LOG_BYTES : Number(params.maxBytes);
-    if (maxBytes > MAX_LOG_BYTES) throw new Error("maxBytes must be at most 50 KiB");
-    return toolResult(registry.logs(String(params.taskId), { maxBytes, tail: params.tail !== false }));
-  } });
+  api.registerTool({
+    name: "async_wait", label: "Wait for async tasks",
+    description: "Wait for tasks (taskId or name) to finish or return notReady; waiting does not kill tasks.",
+    parameters: schema({ taskIds: { type: "array", items: stringField }, timeoutMs: timeoutField }, ["taskIds", "timeoutMs"]),
+    execute: async (_id, params, signal, _onUpdate, ctx) => {
+      configure(ctx);
+      if (params.timeoutMs === undefined) throw new Error("timeoutMs is required");
+      const taskIds = Array.isArray(params.taskIds) ? params.taskIds.map((id) => registry.resolveTaskId(String(id)).taskId) : [];
+      return toolResult(await registry.wait(taskIds, Number(params.timeoutMs), signal));
+    },
+  });
+  api.registerTool({
+    name: "async_logs", label: "Read async output",
+    description: "Read bounded, ANSI-stripped task output (taskId or name). stream selects merged/stdout/stderr.",
+    parameters: schema({
+      taskId: stringField,
+      maxBytes: { type: "number", minimum: 0, maximum: MAX_LOG_BYTES },
+      tail: { type: "boolean" },
+      stream: { type: "string", enum: ["merged", "stdout", "stderr"], default: "merged" },
+    }, ["taskId"]),
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      configure(ctx);
+      const maxBytes = params.maxBytes === undefined ? MAX_LOG_BYTES : Number(params.maxBytes);
+      if (maxBytes > MAX_LOG_BYTES) throw new Error("maxBytes must be at most 50 KiB");
+      const stream = params.stream === "stdout" || params.stream === "stderr" ? params.stream : "merged";
+      const { taskId } = registry.resolveTaskId(String(params.taskId));
+      return toolResult(registry.logs(taskId, { maxBytes, tail: params.tail !== false, stream }));
+    },
+  });
   api.registerTool({
     name: "async_status", label: "Async task status",
-    description: "List async tasks and current status. Defaults to active (running/pending) only; pass includeHistory:true for up to 50 recent tasks.",
-    parameters: schema({ includeHistory: { type: "boolean" } }),
-    execute: async (_id, params) => {
-      const MAX_HISTORY = 50;
-      if (params.includeHistory === true) {
-        const all = registry.list({ includeHistory: true });
-        return toolResult(all.slice(-MAX_HISTORY));
-      }
-      return toolResult(registry.list({ includeHistory: false }));
+    description: "List async tasks and current status. Defaults to active (running/pending) only; pass includeHistory:true (or an explicit status) for up to 50 recent tasks, newest first.",
+    parameters: schema({
+      includeHistory: { type: "boolean" },
+      status: { type: "string", enum: [...TASK_STATUSES, "active"] },
+      name: stringField,
+      limit: { type: "number", minimum: 1, maximum: MAX_STATUS_LIMIT },
+    }),
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      configure(ctx);
+      const includeHistory = params.includeHistory === true;
+      const status: TaskStatus | "active" | undefined = isTaskStatus(params.status) ? params.status : params.status === "active" ? "active" : undefined;
+      const name = typeof params.name === "string" && params.name.length > 0 ? params.name : undefined;
+      const limit = clampStatusLimit(params.limit);
+      const tasks = registry.list({
+        // An explicit status promises history visibility (a status filter is a history query).
+        includeHistory: includeHistory || status !== undefined,
+        ...(status === undefined ? {} : { status }),
+        ...(name === undefined ? {} : { name }),
+        limit,
+      });
+      // D-08: history views are newest-first; the default active view keeps insertion order.
+      const ordered = includeHistory || status !== undefined ? [...tasks].sort(byRecency) : tasks;
+      return toolResult(ordered.map(redactSnapshot));
     },
   });
   api.registerTool({
-    name: "async_kill", label: "Kill async task", description: "Terminate an async task and its process group.",
+    name: "async_kill", label: "Kill async task", description: "Terminate an async task (taskId or name) and its process group.",
     parameters: schema({ taskId: stringField }, ["taskId"]),
-    execute: async (_id, params) => {
-      const taskId = String(params.taskId);
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      configure(ctx);
+      // Unknown id/name throws here (registry message: "Unknown task or name: ...") → host isError result.
+      const resolved = registry.resolveTaskId(String(params.taskId));
+      const taskId = resolved.taskId;
       const before = registry.get(taskId);
       const alreadyTerminal = before !== undefined && isTerminal(before.status);
       let warning: string | undefined;
@@ -124,8 +273,14 @@ export function registerTools(pi: PiCtx, registry: TaskRegistry): void {
         status: after?.status,
         ...(after?.killKind ? { killKind: after.killKind } : {}),
         alreadyTerminal,
+        processAlive: registry.isProcessAlive(taskId),
         ...(warning ? { warning } : {}),
       }, Boolean(warning && after?.status !== "killed"));
     },
   });
 }
+
+/** Session cwd for tool-initiated runs: `ctx.cwd` when present, else the host process cwd (PLAN §2.7). */
+function sessionCwd(ctx?: ToolContext): string {
+  return typeof ctx?.cwd === "string" && ctx.cwd.length > 0 ? ctx.cwd : process.cwd();
+}