pi-async 0.1.0 → 0.3.0

package/extensions/index.ts

@@ -1,45 +1,164 @@
+import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearTaskActivity, raiseTaskActivity, reportActivity } from "../src/core/bus.ts";
 import { sendCompletionNotification } from "../src/core/notify.ts";
 import { TaskRegistry } from "../src/core/registry.ts";
+import { isTerminal, type TaskSnapshot } from "../src/core/task.ts";
 import { SettleGuard } from "../src/guard/settle-guard.ts";
-import { registerTools } from "../src/tools/index.ts";
+import { registerTools, type ToolContext } from "../src/tools/index.ts";
 import { registerRail } from "../src/tui/rail.ts";
-import { disposeStatus, initStatus } from "../src/tui/status.ts";
+import { initStatus } from "../src/tui/status.ts";
 import { registerPanelCommands } from "../src/tui/panel.ts";
 import { bindTuiHost } from "../src/tui/host.ts";
-import { isTerminal } from "../src/core/task.ts";
 
 export type PiCtx = ExtensionAPI;
 
+/** Structural view of pi's session manager: 0.3.0 only reads dir + id (validated at runtime). */
+type SessionManagerLike = {
+  getSessionDir?: () => string | undefined;
+  getSessionId?: () => string | undefined;
+};
+
 type RuntimeContext = PiCtx & {
   cwd?: string;
-  pid?: number;
-  sessionId?: string;
-  getSessionId?: () => string | undefined;
-  sessionManager?: { getSessionId?: () => string | undefined };
-  mode?: string;
+  sessionManager?: SessionManagerLike;
   on?: (event: string, handler: (...args: unknown[]) => unknown) => unknown;
   registerTool?: (...args: unknown[]) => unknown;
+  registerMessageRenderer?: (...args: unknown[]) => unknown;
 };
 
-function registryDataDir(pi: PiCtx): string {
-  const context = pi as RuntimeContext;
-  const pid = Number.isInteger(context.pid) && (context.pid ?? 0) > 0 ? context.pid ?? process.pid : process.pid;
-  const sessionId = context.sessionManager?.getSessionId?.() ?? context.getSessionId?.() ?? context.sessionId;
-  const safeSessionId = (sessionId || String(process.pid)).replace(/[^\w.-]/g, "_");
-  const cwd = typeof context.cwd === "string" && context.cwd.length > 0 ? context.cwd : process.cwd();
-  return join(cwd, ".pi", "async", `${safeSessionId}-${pid}`);
+/**
+ * Session-scoped data directory (D-16 / PLAN §2.8):
+ * `<sessionDir>/pi-async/<sessionId>`, or undefined when the host exposes no
+ * session directory (degraded hosts, factory-time calls) so the caller can
+ * fall back to the library default. Nothing is created here — the registry
+ * creates directories lazily on first persist/configure (D-04).
+ */
+function sessionDataDir(ctx?: { sessionManager?: SessionManagerLike }): string | undefined {
+  const dir = ctx?.sessionManager?.getSessionDir?.();
+  const sessionId = ctx?.sessionManager?.getSessionId?.();
+  if (typeof dir !== "string" || dir.length === 0) return undefined;
+  if (typeof sessionId !== "string" || sessionId.length === 0) return undefined;
+  return join(dir, "pi-async", sessionId);
+}
+
+/** Library fallback when no session directory is available: per-process `~/.pi/async/<pid>`. */
+function fallbackDataDir(): string {
+  return join(homedir(), ".pi", "async", String(process.pid));
+}
+
+/**
+ * Previous init generation. Retired (guard disposed, registry suspended — never
+ * killed) at the start of the next init: `/reload` must be able to adopt the
+ * running tasks, and a timer that outlives the invalidated ctx would crash the
+ * whole process (#44 / crash 2026-10-21). Killing is reserved for
+ * `session_shutdown` with quit/new/fork.
+ */
+let activeRegistry: TaskRegistry | undefined;
+
+/** Previous generation's settle guard; disposed up front instead of trusting a teardown event. */
+let activeGuard: SettleGuard | undefined;
+
+/** One-line card for completion notifications (PLAN §2.8), rendered from message.details. */
+function formatDuration(ms: number): string {
+  return `${(Math.max(0, ms) / 1000).toFixed(1)}s`;
+}
+
+function firstContentLine(content: unknown): string {
+  if (typeof content === "string") {
+    return content.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim() ?? "";
+  }
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (!block || typeof block !== "object") continue;
+      const text = (block as { text?: unknown }).text;
+      if (typeof text !== "string") continue;
+      const line = text.split(/\r?\n/).find((candidate) => candidate.trim().length > 0);
+      if (line) return line.trim();
+    }
+  }
+  return "";
+}
+
+/**
+ * `✓ name (completed, 1.2s) · exit 0` / `✗ name (failed, 1.2s) · exit 7 · kill timeout`.
+ * Duration comes from the live snapshot (details does not carry timings); without
+ * a snapshot the duration is omitted. Falls back to the message content's first
+ * line when the custom message carries no details.
+ */
+function notificationCard(message: unknown, registry: TaskRegistry): string {
+  const details = (message as { details?: unknown })?.details;
+  if (!details || typeof details !== "object") {
+    return firstContentLine((message as { content?: unknown })?.content) || "async task notification";
+  }
+  const d = details as { taskId?: unknown; name?: unknown; status?: unknown; exitCode?: unknown; killKind?: unknown; failureKind?: unknown };
+  const taskId = typeof d.taskId === "string" ? d.taskId : undefined;
+  const snapshot: TaskSnapshot | undefined = taskId ? registry.get(taskId) : undefined;
+  const status = typeof d.status === "string" ? d.status : snapshot?.status ?? "unknown";
+  const name = typeof d.name === "string" ? d.name : snapshot?.name ?? "async task";
+  const finishedAt = snapshot?.finishedAt;
+  const duration = finishedAt === undefined ? "" : `, ${formatDuration(finishedAt - (snapshot?.startedAt ?? snapshot?.createdAt ?? finishedAt))}`;
+  const parts = [`${status === "completed" ? "✓" : "✗"} ${name} (${status}${duration})`];
+  const exitCode = typeof d.exitCode === "number" ? d.exitCode : snapshot?.exitCode;
+  if (exitCode !== undefined) parts.push(`exit ${exitCode}`);
+  const killKind = typeof d.killKind === "string" ? d.killKind : undefined;
+  const failureKind = typeof d.failureKind === "string" ? d.failureKind : undefined;
+  if (killKind) parts.push(`kill ${killKind}`);
+  else if (failureKind) parts.push(`failure ${failureKind}`);
+  return parts.join(" · ");
 }
 
 /** Wire the task runtime to the host API, degrading optional Pi features gracefully. */
 export async function init(pi: PiCtx): Promise<void> {
-  const registry = new TaskRegistry({ dataDir: registryDataDir(pi) });
-  // NOTE: pi's factory-time ExtensionAPI exposes no `mode`/`ui` — those live on
-  // event-handler contexts (pi.on("session_start", (event, ctx) => ...)). TUI
-  // registration must therefore bind lazily from the first event context.
+  // Retire the previous generation first: dispose its guard and SUSPEND its registry
+  // (timers/watches stopped, processes left running) so a /reload can adopt the work
+  // from disk. Never kill here — killing is quit/new/fork's job (PLAN §2.8).
+  const previousGuard = activeGuard;
+  const previousRegistry = activeRegistry;
+  activeGuard = undefined;
+  activeRegistry = undefined;
+  if (previousGuard) {
+    try {
+      previousGuard.dispose();
+    } catch (error) {
+      console.error("pi-async: previous settle guard disposal during reload failed", error);
+    }
+  }
+  if (previousRegistry) {
+    try {
+      await previousRegistry.suspend();
+    } catch (error) {
+      console.error("pi-async: previous registry suspension during reload failed", error);
+    }
+  }
+
+  const context = pi as RuntimeContext;
+  // The factory creates the registry only — no mkdir, no reloadFromDisk, no timers.
+  // Data dir and cwd land in `configure()` on the first session/tool context (D-04).
+  // Real pi exposes no sessionManager at factory time, so this is usually the library
+  // fallback until the first session ctx arrives (PLAN §2.8: "no sessionManager → fallback").
+  const factoryDataDir = sessionDataDir(context) ?? fallbackDataDir();
+  const registry = new TaskRegistry({ dataDir: factoryDataDir });
+  activeRegistry = registry;
+  // NOTE: pi's factory-time ExtensionAPI exposes no `mode`/`ui`/`sessionManager` — those live on
+  // event-handler contexts (pi.on("session_start", (event, ctx) => ...)), so data dir, cwd and TUI
+  // binding are resolved lazily from the first ctx.
+  let configured = false;
   let tui = false;
+
+  /** One-time `configure({dataDir, cwd})` from whatever ctx is available (session event or tool call). */
+  const ensureConfigured = (ctx?: { cwd?: string; sessionManager?: SessionManagerLike }): void => {
+    if (configured) return;
+    configured = true;
+    try {
+      registry.configure({ dataDir: sessionDataDir(ctx) ?? factoryDataDir, cwd: typeof ctx?.cwd === "string" && ctx.cwd.length > 0 ? ctx.cwd : undefined });
+    } catch (error) {
+      // configure() is contractually non-throwing (D-05); never let a wiring hiccup break a tool call.
+      console.error("pi-async: registry configure failed", error);
+    }
+  };
+
   const bindTui = (ctx: unknown): void => {
     if (!bindTuiHost(ctx)) return;
     tui = true;
@@ -48,16 +167,53 @@ export async function init(pi: PiCtx): Promise<void> {
     registerPanelCommands(pi, registry);
   };
 
+  // First session_start / message_start: configure → resend missed notifications, and bind
+  // the TUI synchronously on the first TUI-capable ctx (pi exposes ui only on event ctxs).
+  // Idempotent: repeated events neither re-configure nor re-send.
+  let startup: Promise<void> | undefined;
+  const onLifecycle = (ctx: unknown): Promise<void> => {
+    if (!startup) {
+      ensureConfigured(ctx as RuntimeContext);
+      startup = (async () => {
+        try {
+          await registry.resendUnnotified();
+        } catch (error) {
+          console.error("pi-async: re-sending missed notifications failed", error);
+        }
+      })();
+    }
+    bindTui(ctx);
+    return startup;
+  };
+
   registry.setEvents({
     onFinalize: (snapshot) => {
       clearTaskActivity(pi, snapshot.taskId);
       reportActivity(pi, registry.activeCount());
       if (tui) initStatus(pi, registry);
       if (snapshot.metadata.notifyOnCompletion === false) return;
+      let outputTail = "";
+      let truncated = false;
+      try {
+        const logSlice = registry.logs(snapshot.taskId, { maxBytes: 8192, tail: true });
+        outputTail = logSlice.text;
+        truncated = logSlice.truncated;
+      } catch (error) {
+        // Out-of-dataDir outputFile (D-11) must not crash finalization or the notification path.
+        console.error(`pi-async: could not read output for ${snapshot.taskId}`, error);
+      }
       const outputFile = String(snapshot.metadata.outputFile ?? "");
-      const outputTail = registry.logs(snapshot.taskId, { maxBytes: 8192, tail: true }).text;
-      const guidance = snapshot.status === "failed" ? `Inspect task output with async_logs (taskId: ${snapshot.taskId}).` : undefined;
-      void sendCompletionNotification(pi, registry, {
+      // `lost` = adopted after /reload but the exit status was never observed; saying only "failed"
+      // would misreport a normal reload ending. `startError` (W1a) explains a failed spawn/delayed start.
+      const startError = typeof snapshot.metadata.startError === "string" && snapshot.metadata.startError.length > 0
+        ? snapshot.metadata.startError
+        : undefined;
+      const failureNotes: string[] = [];
+      if (snapshot.failureKind === "lost") failureNotes.push("Exit status unknown after session reload; output may be incomplete.");
+      if (startError !== undefined) failureNotes.push(`Start error: ${startError}`);
+      if (snapshot.status === "failed") failureNotes.push(`Inspect task output with async_logs (taskId: ${snapshot.taskId}).`);
+      const guidance = failureNotes.length > 0 ? failureNotes.join(" ") : undefined;
+      const payload = {
         taskId: snapshot.taskId,
         name: snapshot.name,
         status: snapshot.status,
@@ -65,7 +221,18 @@ export async function init(pi: PiCtx): Promise<void> {
         outputFile,
         ...(outputTail ? { summary: outputTail } : {}),
         ...(guidance ? { guidance } : {}),
-      }, { triggerTurn: snapshot.metadata.triggerOnCompletion !== false })
+        ...(snapshot.killKind ? { killKind: snapshot.killKind } : {}),
+        ...(snapshot.failureKind ? { failureKind: snapshot.failureKind } : {}),
+        ...(truncated || snapshot.metadata.capped === true ? { summaryTruncated: true } : {}),
+      };
+      // Honest notification (PLAN §2.4/§2.8): no fake retries here. A failed send keeps
+      // notified=false / notifyAttempts>0 in the registry and is re-sent at the next session_start.
+      void sendCompletionNotification(pi, registry, payload, { triggerTurn: snapshot.metadata.triggerOnCompletion !== false })
+        .then((outcome) => {
+          if (outcome === "failed") {
+            console.error(`pi-async: completion notification failed for ${snapshot.taskId}; it will be re-sent on the next session_start`);
+          }
+        })
         .catch((error: unknown) => console.error(`pi-async: completion notification failed for ${snapshot.taskId}`, error));
     },
     onStateChange: (snapshot) => {
@@ -77,28 +244,44 @@ export async function init(pi: PiCtx): Promise<void> {
     },
   });
 
-  try {
-    await registry.reloadFromDisk();
-  } catch (error) {
-    console.error("pi-async: failed to reload task state; continuing with an empty registry", error);
+  if (typeof context.registerTool === "function") registerTools(pi, registry, ensureConfigured);
+
+  // Completion notification card (PLAN §2.8). Local component implementation: the TUI lane owns
+  // src/tui/*, so this renderer must not import from there.
+  if (typeof context.registerMessageRenderer === "function") {
+    context.registerMessageRenderer("async-task-notification", (message: unknown) => ({
+      render: () => [notificationCard(message, registry)],
+      invalidate: () => undefined,
+    }));
   }
 
-  const context = pi as RuntimeContext;
-  if (typeof context.registerTool === "function") registerTools(pi, registry);
-  // Bind TUI surfaces from the first event context (factory API has no mode/ui).
   if (typeof context.on === "function") {
-    context.on("session_start", (_event: unknown, ctx: unknown) => bindTui(ctx));
-    context.on("message_start", (_event: unknown, ctx: unknown) => bindTui(ctx));
+    context.on("session_start", (_event: unknown, ctx: unknown) => onLifecycle(ctx));
+    context.on("message_start", (_event: unknown, ctx: unknown) => onLifecycle(ctx));
+
+    // agent_settled / agent_before_settle are registered by SettleGuard itself.
+    activeGuard = new SettleGuard(pi, registry);
+    activeGuard.register();
   }
-  if (typeof context.on === "function") new SettleGuard(pi, registry).register();
 
   let shutdownPromise: Promise<void> | undefined;
   if (typeof context.on === "function") {
-    context.on("session_shutdown", async () => {
-      if (!shutdownPromise) shutdownPromise = (async () => {
-        if (tui) disposeStatus();
-        await registry.shutdown();
-      })();
+    context.on("session_shutdown", async (event: unknown) => {
+      if (!shutdownPromise) {
+        shutdownPromise = (async () => {
+          // D-16 / PLAN §2.8: reload + resume suspend (next generation adopts from disk);
+          // quit/new/fork (and an unknown/undefined reason) shut down and kill.
+          const reason = (event as { reason?: string } | undefined)?.reason;
+          const suspendOnly = reason === "reload" || reason === "resume";
+          if (activeRegistry === registry) activeRegistry = undefined;
+          try {
+            if (suspendOnly) await registry.suspend();
+            else await registry.shutdown();
+          } catch (error) {
+            console.error(`pi-async: session shutdown (${String(reason ?? "unknown")}) failed`, error);
+          }
+        })();
+      }
       await shutdownPromise;
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-async",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Pi extension for async shell tasks: background/delayed/sync modes, output-matching watches, event-driven waiting, settle guard for legion children, and a TUI task rail — completion notifications wake your session.",
   "type": "module",
   "license": "MIT",
@@ -39,11 +39,14 @@
     "src/",
     "README.md",
     "LICENSE",
-    "docs/CONTRACT.md"
+    "docs/CONTRACT.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --experimental-strip-types --test tests/*.test.ts"
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "verify": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run verify"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^1.2.0",

package/src/core/bus.ts

@@ -1,12 +1,20 @@
 import type { PiCtx } from "./notify.ts";
 
+/** Aggregate activity source id (frozen §7). */
+const AGGREGATE_ACTIVITY_ID = "pi-async";
+
+/** Per-task activity id — legion #156 / osc-busy-plugin: `plugin/<name>/…`. */
+export function taskActivityId(taskId: string): string {
+  return `plugin/pi-async/${taskId}`;
+}
+
 /** Report aggregate async work through Pi's activity API when the host exposes it. */
 export function reportActivity(pi: PiCtx, active: { running: number; pending: number }): void {
   // SAFETY: PiCtx is the installed extension API; ui.setActivity is feature-detected for versions without it.
   const ui = (pi as unknown as { ui?: { setActivity?: (id: string, activity: { message: string } | undefined) => void } }).ui;
   if (typeof ui?.setActivity !== "function") return;
   const count = active.running + active.pending;
-  ui.setActivity("pi-async", count === 0 ? undefined : { message: `${count} async tasks` });
+  ui.setActivity(AGGREGATE_ACTIVITY_ID, count === 0 ? undefined : { message: `${count} async tasks` });
   // Activity uses the host API; never emit terminal OSC/printf escapes. In particular,
   // leave PI_PROGRAM_STATUS untouched for hosts which own that status channel.
 }
@@ -16,7 +24,7 @@ export function raiseTaskActivity(pi: PiCtx, taskId: string, message = "Async ta
   // SAFETY: PiCtx is the installed extension API; ui.setActivity is feature-detected for versions without it.
   const ui = (pi as unknown as { ui?: { setActivity?: (id: string, activity: { message: string } | undefined) => void } }).ui;
   if (typeof ui?.setActivity !== "function") return;
-  ui.setActivity(`pi-async/${taskId}`, { message });
+  ui.setActivity(taskActivityId(taskId), { message });
 }
 
 /** Clear task-scoped activity when the host supports Pi's optional activity API. */
@@ -24,5 +32,5 @@ export function clearTaskActivity(pi: PiCtx, taskId: string): void {
   // SAFETY: PiCtx is the installed extension API; ui.setActivity is feature-detected for versions without it.
   const ui = (pi as unknown as { ui?: { setActivity?: (id: string, activity: { message: string } | undefined) => void } }).ui;
   if (typeof ui?.setActivity !== "function") return;
-  ui.setActivity(`pi-async/${taskId}`, undefined);
+  ui.setActivity(taskActivityId(taskId), undefined);
 }

package/src/core/duration.ts

@@ -0,0 +1,20 @@
+import type { TaskSnapshot } from "./task.ts";
+
+/**
+ * Format a task's elapsed duration for TUI surfaces.
+ * - pending → em dash (not started)
+ * - end base = finishedAt ?? now (terminal states freeze; live tasks tick)
+ * - three tiers: Ns / Mm Ss / Hh Mm
+ */
+export function formatElapsedMs(ms: number): string {
+  const seconds = Math.floor(Math.max(0, ms) / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  return minutes < 60 ? `${minutes}m ${seconds % 60}s` : `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+
+export function formatDuration(task: TaskSnapshot, now: number): string {
+  if (task.status === "pending") return "—";
+  const end = task.finishedAt ?? now;
+  return formatElapsedMs(end - (task.startedAt ?? task.createdAt));
+}

package/src/core/env.ts

@@ -0,0 +1,134 @@
+export interface EnvNumberOpts {
+  min?: number;
+  max?: number;
+  /** When true, non-integers fall back (avoids Number("")===0 and 2.7→3 surprises). */
+  integer?: boolean;
+}
+
+/**
+ * Parse a numeric env var with empty-string → fallback (not Number("")===0).
+ * Non-finite / out-of-range / non-integer (when requested) also fall back.
+ */
+export function envNumber(name: string, fallback: number, opts?: EnvNumberOpts): number {
+  const raw = process.env[name];
+  if (raw === undefined) return fallback;
+  const trimmed = raw.trim();
+  if (trimmed === "") return fallback;
+  const parsed = Number(trimmed);
+  if (!Number.isFinite(parsed)) return fallback;
+  if (opts?.integer && !Number.isInteger(parsed)) return fallback;
+  if (opts?.min !== undefined && parsed < opts.min) return fallback;
+  if (opts?.max !== undefined && parsed > opts.max) return fallback;
+  return parsed;
+}
+
+/** Child environment inheritance policy (REV-16). `safe` is the default. */
+export type EnvPolicy = "safe" | "all" | "none";
+
+/** Keys whose inheritance would silently change how the child resolves code (REV-16). */
+const DANGEROUS_KEYS: ReadonlySet<string> = new Set([
+  "PATH",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "NODE_OPTIONS",
+  "BASH_ENV",
+  "ENV",
+  "SHELLOPTS",
+  "PYTHONPATH",
+  "GIT_SSH_COMMAND",
+]);
+
+/** Suffix families treated as credentials under `safe` inheritance. */
+const SENSITIVE_SUFFIX = /_(API_KEY|TOKEN|SECRET|PASSWORD)$/i;
+const SENSITIVE_SUBSTRING = /CREDENTIAL/i;
+const SENSITIVE_EXPLICIT: ReadonlySet<string> = new Set([
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SESSION_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "NPM_TOKEN",
+]);
+
+/** `none` keeps only what a POSIX shell needs to start at all. */
+const NONE_ALLOWED: ReadonlySet<string> = new Set(["PATH", "HOME", "SHELL", "TERM", "LANG", "TMPDIR", "USER"]);
+
+/** Host-only tuning knob: never leaks into a child, under any policy. */
+export const INTERNAL_MAX_OUTPUT_ENV = "PI_ASYNC_INTERNAL_MAX_OUTPUT_BYTES";
+
+function isSensitiveKey(key: string): boolean {
+  if (SENSITIVE_EXPLICIT.has(key) || SENSITIVE_SUFFIX.test(key) || SENSITIVE_SUBSTRING.test(key)) return true;
+  // npm reads credentials from lower-case `npm_config_*` keys (e.g. npm_config__authToken).
+  return key.toLowerCase().startsWith("npm_config_") && /(auth|token|password)/i.test(key);
+}
+
+function noneAllows(key: string): boolean {
+  return NONE_ALLOWED.has(key) || key.startsWith("LC_");
+}
+
+function assignDefined(target: Record<string, string>, source: NodeJS.ProcessEnv | Record<string, string>): void {
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    target[key] = String(value);
+  }
+}
+
+/**
+ * Reject explicit overrides of process-resolution keys (`PATH`, `NODE_OPTIONS`, …).
+ *
+ * Exported so task-submission paths (e.g. delayed tasks, which spawn later) can fail fast
+ * instead of surfacing the error only when the process is finally started. Applied by every
+ * inheritance policy.
+ */
+export function assertSafeEnvKeys(extra: Record<string, string> | undefined, policyName?: EnvPolicy): void {
+  if (!extra) return;
+  const policyContext = policyName ? ` under env policy "${policyName}"` : "";
+  for (const key of Object.keys(extra)) {
+    if (!DANGEROUS_KEYS.has(key)) continue;
+    throw new Error(
+      `Refusing to set dangerous environment variable ${key} for an async task: ` +
+        `explicit overrides of process-resolution keys are rejected${policyContext}. ` +
+        `The inherited ${key} is used instead.`,
+    );
+  }
+}
+
+/**
+ * Build the child environment for a task (pure: never mutates `base` or `extra`).
+ *
+ * - `safe`  (default): inherit `base` minus credential-ish keys; extra ordinary keys override.
+ * - `all`   : legacy `{...base, ...extra}`.
+ * - `none`  : only PATH/HOME/SHELL/TERM/LANG/LC_-prefixed/TMPDIR/USER from `base`, plus extra ordinary keys.
+ *
+ * In every policy an explicit dangerous key (`PATH`, `NODE_OPTIONS`, …) in `extra` throws,
+ * and the internal output-cap knob is always stripped.
+ */
+export function buildChildEnv(
+  base: NodeJS.ProcessEnv,
+  extra: Record<string, string> | undefined,
+  policy: EnvPolicy,
+): Record<string, string> {
+  assertSafeEnvKeys(extra, policy);
+  const env: Record<string, string> = {};
+  switch (policy) {
+    case "all":
+      assignDefined(env, base);
+      break;
+    case "none":
+      for (const [key, value] of Object.entries(base)) {
+        if (value === undefined || !noneAllows(key)) continue;
+        env[key] = String(value);
+      }
+      break;
+    case "safe":
+    default:
+      for (const [key, value] of Object.entries(base)) {
+        if (value === undefined || isSensitiveKey(key)) continue;
+        env[key] = String(value);
+      }
+      break;
+  }
+  assignDefined(env, extra ?? {});
+  delete env[INTERNAL_MAX_OUTPUT_ENV];
+  return env;
+}