@devfn/processes 0.1.0 → 0.1.1

package/README.md

@@ -1,3 +1,27 @@
 # @devfn/processes
 
 Native process groups, durable logs, HTTP/TCP/command/log readiness, PID-birth ownership checks, and graceful termination. It is deliberately browser- and artifact-model-neutral so ProbeFn can adopt it later without depending on DevFn orchestration.
+
+## Gated launches
+
+- `runGatedCommand` runs a command that creates outside resources only after its launcher identity has been recorded. The process wrapper never runs its command without the launch gate channel.
+- On POSIX, `gatedLauncherStatus`/`stopGatedLauncher` resolve such a launch only once the launcher and its process group are gone. On Windows they judge and stop only the launcher and its current process tree, so they cannot confirm that a descendant which left that tree is gone.
+- `runGatedCommand` redacts the values of `redactKeys` from the command's output and keeps at most `maxBuffer` bytes of each output stream, stopping the launcher's group as soon as either passes it.
+- Once the command exits, it waits at most a bounded drain for output that a process it left behind still holds open, then stops that process's group, waiting a bounded time for it to exit and forcing it if needed. A finished command therefore never waits indefinitely on a leftover process. A failed stop is reported together with the command's own outcome, never instead of it.
+- `ProcessSupervisor.run` runs a finite command to completion through the same gate, with its output in a private log, a per-run timeout and an abort signal, both of which stop its whole group. The same bounded drain applies, so a command that exits 0 while a descendant holds its output open succeeds and that descendant is stopped with its group. `discardOutput` keeps none of the command's output, for output that may carry values `redactKeys` cannot name.
+
+## Process groups
+
+- Every recorded process and launcher leads its own process group (POSIX), and `processGroupStatus` judges the whole group: a leader that exited while processes remain in its group is `unverified`, not gone, and a reused leader PID (a readable different start identity) proves the group gone, because a PID is not reused while its group exists.
+- `stop` signals only a verified leader, waits until its whole group is gone (forcing members that ignore termination), and never signals a live PID whose start identity cannot be read or a leaderless group (`DEVFN_PROCESS_IDENTITY_UNVERIFIED`).
+- The group is judged again immediately before each signal. POSIX offers no way to signal a group atomically with that check, but a group ID is not reused while any member remains, so the only exposure is a group that empties and whose ID a new group leader takes in the instant between the check and the signal.
+- On Windows, which has no process groups, only the leader is judged and stopped with its process tree.
+
+## Start identities
+
+- Start identities do not depend on the caller's environment: on macOS the `ps` start time is read with `TZ=UTC0` and `LC_ALL=C`.
+- A signature recorded by an earlier release in the caller's time zone and locale is never compared as text. It is decided by the record's own UTC time (a receipt process's `startedAt`, a lock's or trust ticket's `createdAt`, a Caddy owner's `startedAt`, a port lease owner's `recordedAt`), which DevFn writes only after reading a live owner's identity:
+  - a process whose pinned UTC start is later than that time by more than two seconds is another process reusing the PID;
+  - one that started no later than that time is the recorded process;
+  - a record without a time, or a start later than it by at most two seconds (the allowance for wall-clock adjustment), is `unverified`.
+- An earlier release's active port lease has no `recordedAt`, but its `updatedAt` was written at activation, just after its owner's identity was read, and stays unchanged while the lease is active, so the registry copies it to the owner's `recordedAt` before any transition; a lease whose PID was reused is then `stale` or `externally-occupied` as in earlier releases. Only a lease that already left `active` under an earlier release has no record time, and its owner stays `unverified`.

package/dist/adapters.d.ts

@@ -1,3 +1,3 @@
-import type { ProcessSpec } from "@devfn/config";
+import { type ProcessSpec } from "@devfn/config";
 export declare function resolveAdapterCommand(spec: ProcessSpec): string[];
 export declare function createProcessEnvironment(spec: ProcessSpec, generated?: Record<string, string>, source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/adapters.js

@@ -1,3 +1,4 @@
+import { assertEnvironmentKeyCasing } from "@devfn/config";
 export function resolveAdapterCommand(spec) {
     const extra = spec.command ?? [];
     switch (spec.adapter) {
@@ -16,6 +17,7 @@ export function resolveAdapterCommand(spec) {
 }
 const BASE_ENV = ["PATH", "SHELL", "HOME", "USER", "LOGNAME", "TMPDIR", "TMP", "TEMP", "SystemRoot", "ComSpec", "PATHEXT"];
 export function createProcessEnvironment(spec, generated = {}, source = process.env) {
+    assertEnvironmentKeyCasing(BASE_ENV, spec.envAllowlist ?? [], Object.keys(spec.env ?? {}), Object.keys(generated), spec.exposure === "public" ? [] : ["HOST", "DEVFN_HOST"], spec.adapter === "pnpm" ? ["COREPACK_ENABLE_NETWORK"] : []);
     const result = {};
     for (const key of [...BASE_ENV, ...(spec.envAllowlist ?? [])])
         if (source[key] !== undefined)
@@ -27,5 +29,9 @@ export function createProcessEnvironment(spec, generated = {}, source = process.
     }
     if (spec.adapter === "pnpm")
         result.COREPACK_ENABLE_NETWORK = "0";
+    // Only DevFn's own launcher may ask the process wrapper to discard output.
+    for (const key of Object.keys(result))
+        if (key.toUpperCase() === "DEVFN_DISCARD_OUTPUT")
+            delete result[key];
     return result;
 }

package/dist/gated.d.ts

@@ -0,0 +1,34 @@
+import { type ProcessOwnerIdentity } from "./types.js";
+export interface GatedCommandOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+    maxBuffer?: number;
+    /** Environment keys whose values are redacted from the command's output. */
+    redactKeys?: readonly string[];
+    /** Record the launcher identity; the command runs only after this resolves. */
+    onLaunched: (launcher: ProcessOwnerIdentity) => Promise<void>;
+}
+export type GatedCommandRunner = (file: string, args: string[], options: GatedCommandOptions) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Whether anything a gated launcher ran may still run, by the process group
+ * rule: the launcher leads its own group on POSIX, so a member left after it
+ * died is something it started, while a reused launcher PID proves its group
+ * gone. "gone" is the only conclusive answer.
+ */
+export declare function gatedLauncherStatus(launcher: ProcessOwnerIdentity): Promise<"running" | "unverified" | "gone">;
+/**
+ * Stop a gated launcher and everything in its process group, signalling only
+ * a verified launcher identity. Resolves only once nothing it ran remains.
+ */
+export declare function stopGatedLauncher(launcher: ProcessOwnerIdentity, timeoutMs?: number): Promise<void>;
+/**
+ * Run a command that may create resources outside DevFn through a launcher
+ * whose identity is recorded before the command can start. If the recording
+ * fails or DevFn dies first, the launcher's gate closes and the command never
+ * runs, so an unrecorded launcher proves the command never ran.
+ */
+export declare const runGatedCommand: GatedCommandRunner;

package/dist/gated.js

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { stopProcessGroup } from "./group.js";
+import { processBirthSignature, processGroupStatus } from "./identity.js";
+import { ProcessError } from "./types.js";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// A process the command left behind may hold its output open after it exits;
+// these bound the wait for that output so the leftover can still be stopped.
+const WRAPPER_DRAIN_MS = 1_000;
+const OUTPUT_DRAIN_MS = 2_000;
+/**
+ * Whether anything a gated launcher ran may still run, by the process group
+ * rule: the launcher leads its own group on POSIX, so a member left after it
+ * died is something it started, while a reused launcher PID proves its group
+ * gone. "gone" is the only conclusive answer.
+ */
+export async function gatedLauncherStatus(launcher) {
+    const status = await processGroupStatus(launcher.pid, launcher.birthSignature);
+    return status === "exited" || status === "identity-mismatch" ? "gone" : status;
+}
+/**
+ * Stop a gated launcher and everything in its process group, signalling only
+ * a verified launcher identity. Resolves only once nothing it ran remains.
+ */
+export async function stopGatedLauncher(launcher, timeoutMs = 10_000) {
+    await stopProcessGroup(launcher, "The launcher", timeoutMs);
+}
+/**
+ * Run a command that may create resources outside DevFn through a launcher
+ * whose identity is recorded before the command can start. If the recording
+ * fails or DevFn dies first, the launcher's gate closes and the command never
+ * runs, so an unrecorded launcher proves the command never ran.
+ */
+export const runGatedCommand = async (file, args, options) => {
+    const wrapperPath = fileURLToPath(new URL("./wrapper.js", import.meta.url));
+    // Its output is always kept, whatever the inherited environment asks of the
+    // wrapper (in any key casing, as Windows reads it).
+    const environment = { ...(options.env ?? process.env) };
+    for (const key of Object.keys(environment))
+        if (key.toUpperCase() === "DEVFN_DISCARD_OUTPUT")
+            delete environment[key];
+    const child = spawn(process.execPath, [wrapperPath], {
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        env: { ...environment, DEVFN_WRAPPED_COMMAND: JSON.stringify([file, ...args]),
+            DEVFN_REDACT_KEYS: JSON.stringify(options.redactKeys ?? []), DEVFN_WRAPPER_DRAIN_MS: String(WRAPPER_DRAIN_MS) },
+        detached: process.platform !== "win32",
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+    const maxBuffer = options.maxBuffer ?? 1024 * 1024;
+    // Output is kept only up to the limit; passing it stops the launcher.
+    let overflowed;
+    const overflow = new Promise((resolve) => { overflowed = () => resolve("overflow"); });
+    let exceeded = false;
+    const capture = (stream) => {
+        const chunks = [];
+        let size = 0;
+        stream.on("data", (chunk) => {
+            if (exceeded)
+                return;
+            if (size + chunk.length > maxBuffer) {
+                chunks.push(chunk.subarray(0, maxBuffer - size));
+                size = maxBuffer;
+                exceeded = true;
+                overflowed();
+                return;
+            }
+            chunks.push(chunk);
+            size += chunk.length;
+        });
+        return () => Buffer.concat(chunks).toString("utf8");
+    };
+    const stdout = capture(child.stdout);
+    const stderr = capture(child.stderr);
+    // "close" never follows a disconnected IPC channel, so wait for the exit
+    // and the end of the output instead.
+    const ended = (stream) => new Promise((resolve) => { stream.once("close", resolve); stream.once("error", () => resolve()); });
+    const output = Promise.all([ended(child.stdout), ended(child.stderr)]);
+    const closed = new Promise((resolve) => child.once("exit", (code, signal) => resolve({ code, signal })))
+        .then(async (result) => { await Promise.race([output, delay(OUTPUT_DRAIN_MS)]); return result; });
+    await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("spawn", resolve);
+    }).catch((error) => { throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Unable to launch ${file}.`, { cause: error instanceof Error ? error.message : String(error) }); });
+    const pid = child.pid;
+    let birthSignature;
+    for (let attempt = 0; attempt < 10 && !birthSignature; attempt += 1) {
+        birthSignature = await processBirthSignature(pid);
+        if (!birthSignature)
+            await delay(20);
+    }
+    const launcher = { pid, ...(birthSignature ? { birthSignature } : {}) };
+    // This launcher is this process's child: its PID is not reused before it is
+    // reaped, and afterwards its group ID is not reused while a member remains,
+    // so what is left in that group is its own and may be stopped.
+    const stopOwnLauncher = async () => await stopProcessGroup(launcher, `The launcher for ${file}`, 10_000, { ownGroup: { leaderUnreaped: () => child.exitCode === null && child.signalCode === null } });
+    try {
+        if (!birthSignature)
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Could not establish a launcher identity for ${file}; refusing to run it unrecorded.`);
+        await options.onLaunched(launcher);
+    }
+    catch (error) {
+        // Closing the channel before the gate opens makes the launcher exit
+        // without running the command.
+        if (child.connected)
+            child.disconnect();
+        await closed;
+        throw error;
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new ProcessError("DEVFN_PROCESS_START_FAILED", `Launcher for ${file} did not acknowledge its launch gate.`)), 10_000);
+        child.once("disconnect", () => { clearTimeout(timer); resolve(); });
+        child.send("start", (error) => {
+            if (!error)
+                return;
+            clearTimeout(timer);
+            reject(new ProcessError("DEVFN_PROCESS_START_FAILED", `Unable to open the launch gate for ${file}.`, { cause: error.message }));
+        });
+    }).catch(async (error) => {
+        await stopOwnLauncher().catch(() => undefined);
+        throw error;
+    });
+    let timer;
+    const timedOut = options.timeout ? new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), options.timeout); }) : undefined;
+    const outcome = await Promise.race([closed, overflow, ...(timedOut ? [timedOut] : [])]);
+    clearTimeout(timer);
+    // An exited launcher may have left a member that could still act for it.
+    // A failed stop never hides the command's own outcome; it is reported with it.
+    let stopError;
+    try {
+        await stopOwnLauncher();
+    }
+    catch (error) {
+        stopError = error;
+    }
+    const failed = (message, details) => Object.assign(new Error(stopError === undefined ? message
+        : `${message} ${stopError instanceof Error ? stopError.message : String(stopError)}`), { stdout: stdout(), stderr: stderr(), ...details,
+        ...(stopError === undefined ? {} : { cleanupError: stopError }) });
+    if (outcome === "timeout")
+        throw failed(`Command ${file} ${args.join(" ")} timed out after ${options.timeout}ms.`, { killed: true });
+    if (exceeded || outcome === "overflow")
+        throw failed(`Command ${file} output exceeded ${maxBuffer} bytes.`, { killed: true });
+    if (outcome.code !== 0) {
+        const output = stderr() ? `\n${stderr()}` : "";
+        throw failed(`Command failed: ${file} ${args.join(" ")}${output}`, { code: outcome.code, signal: outcome.signal });
+    }
+    if (stopError !== undefined)
+        throw stopError;
+    return { stdout: stdout(), stderr: stderr() };
+};

package/dist/group.d.ts

@@ -0,0 +1,20 @@
+import { type ProcessOwnerIdentity } from "./types.js";
+/** Only an exited leader with an empty group, or a reused leader PID, proves nothing of a group remains. */
+export declare function processGroupGone(owner: ProcessOwnerIdentity): Promise<boolean>;
+/** Signal a group leader and its group (its process tree on Windows). */
+export declare function signalProcessGroup(pid: number, force: boolean): Promise<void>;
+export declare function waitForProcessGroupExit(owner: ProcessOwnerIdentity, timeoutMs: number): Promise<boolean>;
+/**
+ * Stop a recorded group leader and everything in its group, resolving only
+ * once nothing of it remains. Only a verified leader is signalled. Once it
+ * was, its group ID cannot be reused while a member remains, so members that
+ * outlive it are forced too; elsewhere only the verified leader is. A caller
+ * that spawned the leader during its own run (ownGroup) knows its unreaped
+ * child is that leader, and that the members of a leaderless group are what
+ * it started.
+ */
+export declare function stopProcessGroup(owner: ProcessOwnerIdentity, label: string, timeoutMs: number, options?: {
+    ownGroup?: {
+        leaderUnreaped: () => boolean;
+    };
+}): Promise<void>;

package/dist/group.js

@@ -0,0 +1,87 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { processExists, processGroupStatus, processIdentityStatus } from "./identity.js";
+import { ProcessError } from "./types.js";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Only an exited leader with an empty group, or a reused leader PID, proves nothing of a group remains. */
+export async function processGroupGone(owner) {
+    const status = await processGroupStatus(owner.pid, owner.birthSignature, owner.startedAt);
+    return status === "exited" || status === "identity-mismatch";
+}
+/** Signal a group leader and its group (its process tree on Windows). */
+export async function signalProcessGroup(pid, force) {
+    if (process.platform !== "win32") {
+        try {
+            process.kill(-pid, force ? "SIGKILL" : "SIGTERM");
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                throw error;
+        }
+        return;
+    }
+    // The system copy, never one found through PATH.
+    const systemRoot = process.env.SystemRoot;
+    const taskkill = path.win32.join(systemRoot && path.win32.isAbsolute(systemRoot) ? systemRoot : "C:\\Windows", "System32", "taskkill.exe");
+    await new Promise((resolve, reject) => {
+        const child = spawn(taskkill, ["/pid", String(pid), "/T", ...(force ? ["/F"] : [])], { stdio: "ignore", windowsHide: true });
+        child.once("error", reject);
+        child.once("exit", (code) => code === 0 || !processExists(pid) ? resolve() : reject(new Error(`taskkill exited with ${code}`)));
+    });
+}
+export async function waitForProcessGroupExit(owner, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await processGroupGone(owner))
+            return true;
+        await delay(50);
+    }
+    return await processGroupGone(owner);
+}
+/**
+ * Stop a recorded group leader and everything in its group, resolving only
+ * once nothing of it remains. Only a verified leader is signalled. Once it
+ * was, its group ID cannot be reused while a member remains, so members that
+ * outlive it are forced too; elsewhere only the verified leader is. A caller
+ * that spawned the leader during its own run (ownGroup) knows its unreaped
+ * child is that leader, and that the members of a leaderless group are what
+ * it started.
+ */
+export async function stopProcessGroup(owner, label, timeoutMs, options = {}) {
+    const status = await processGroupStatus(owner.pid, owner.birthSignature, owner.startedAt);
+    if (status === "exited" || status === "identity-mismatch")
+        return;
+    const leaderExited = await processIdentityStatus(owner.pid, owner.birthSignature, owner.startedAt) === "exited";
+    if (status === "unverified" && !(options.ownGroup && (leaderExited || options.ownGroup.leaderUnreaped()))) {
+        throw new ProcessError("DEVFN_PROCESS_IDENTITY_UNVERIFIED", leaderExited
+            ? `${label} (PID ${owner.pid}) exited, but processes remain in its process group ${owner.pid}; DevFn cannot verify they are its own and will not signal them.`
+            : `PID ${owner.pid} may still be ${label}, but its identity cannot be verified; DevFn will not signal it.`, { pid: owner.pid });
+    }
+    try {
+        // A graceful request can be refused (Windows console processes accept
+        // only a forced taskkill); the wait and forced stop below decide.
+        try {
+            await signalProcessGroup(owner.pid, false);
+        }
+        catch (error) {
+            if (process.platform !== "win32")
+                throw error;
+        }
+        if (await waitForProcessGroupExit(owner, timeoutMs))
+            return;
+        // Judge the group again right before forcing it. POSIX cannot signal a
+        // group atomically with that check; a group ID is not reused while any
+        // member remains, so only a group that empties in between is exposed.
+        const remaining = await processGroupStatus(owner.pid, owner.birthSignature, owner.startedAt);
+        if (remaining === "exited" || remaining === "identity-mismatch")
+            return;
+        if (process.platform !== "win32" || await processIdentityStatus(owner.pid, owner.birthSignature, owner.startedAt) === "running" || options.ownGroup?.leaderUnreaped())
+            await signalProcessGroup(owner.pid, true);
+    }
+    catch (error) {
+        throw new ProcessError("DEVFN_PROCESS_STOP_FAILED", `Unable to stop ${label} (PID ${owner.pid}).`, { pid: owner.pid, cause: error instanceof Error ? error.message : String(error) });
+    }
+    if (!await waitForProcessGroupExit(owner, 5_000)) {
+        throw new ProcessError("DEVFN_PROCESS_STOP_FAILED", `${label} (PID ${owner.pid}) or a process in its group did not exit after forced termination.`, { pid: owner.pid });
+    }
+}

package/dist/identity.d.ts

@@ -1 +1 @@
-export { matchesProcessIdentity, processBirthSignature, processExists } from "@devfn/config";
+export { classifyProcessIdentity, matchesProcessIdentity, processBirthSignature, processExists, processGroupStatus, processIdentityStatus, startedProcessBirthSignature, type ProcessGroupStatus, type ProcessIdentityStatus } from "@devfn/config";

package/dist/identity.js

@@ -1 +1 @@
-export { matchesProcessIdentity, processBirthSignature, processExists } from "@devfn/config";
+export { classifyProcessIdentity, matchesProcessIdentity, processBirthSignature, processExists, processGroupStatus, processIdentityStatus, startedProcessBirthSignature } from "@devfn/config";

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { createProcessEnvironment, resolveAdapterCommand } from "./adapters.js";
-export { matchesProcessIdentity, processBirthSignature, processExists } from "./identity.js";
-export { checkReadinessNow, waitForReadiness, type ReadinessInput } from "./readiness.js";
+export { classifyProcessIdentity, matchesProcessIdentity, processBirthSignature, processExists, processGroupStatus, processIdentityStatus, startedProcessBirthSignature, type ProcessGroupStatus, type ProcessIdentityStatus } from "./identity.js";
+export { stopProcessGroup } from "./group.js";
+export { checkReadinessNow, resolveHttpReadinessUrl, waitForReadiness, type ReadinessInput } from "./readiness.js";
+export { gatedLauncherStatus, runGatedCommand, stopGatedLauncher, type GatedCommandOptions, type GatedCommandRunner } from "./gated.js";
 export { createStreamingRedactor, type StreamingRedactor } from "./redaction.js";
 export { ProcessSupervisor } from "./supervisor.js";
 export * from "./types.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 export { createProcessEnvironment, resolveAdapterCommand } from "./adapters.js";
-export { matchesProcessIdentity, processBirthSignature, processExists } from "./identity.js";
-export { checkReadinessNow, waitForReadiness } from "./readiness.js";
+export { classifyProcessIdentity, matchesProcessIdentity, processBirthSignature, processExists, processGroupStatus, processIdentityStatus, startedProcessBirthSignature } from "./identity.js";
+export { stopProcessGroup } from "./group.js";
+export { checkReadinessNow, resolveHttpReadinessUrl, waitForReadiness } from "./readiness.js";
+export { gatedLauncherStatus, runGatedCommand, stopGatedLauncher } from "./gated.js";
 export { createStreamingRedactor } from "./redaction.js";
 export { ProcessSupervisor } from "./supervisor.js";
 export * from "./types.js";

package/dist/readiness.d.ts

@@ -10,5 +10,9 @@ export type ReadinessInput = {
     readLog?: () => Promise<string>;
     previouslyReady?: boolean;
 };
+/** Resolve the endpoint used by startup and later readiness probes. */
+export declare function resolveHttpReadinessUrl(health: Extract<HealthCheck, {
+    type: "http";
+}>, ports: Readonly<Record<string, number>>): string;
 export declare function checkReadinessNow(input: ReadinessInput): Promise<boolean>;
 export declare function waitForReadiness(input: ReadinessInput): Promise<void>;

package/dist/readiness.js

@@ -64,32 +64,52 @@ async function readLogWindow(logPath) {
         await handle.close();
     }
 }
-function resolveHttpUrl(health, input) {
-    const port = health.port ? input.ports[health.port] : undefined;
-    let url = health.url ?? `http://127.0.0.1:${port}${health.path ?? "/"}`;
-    if (health.url && health.path) {
-        const parsed = new URL(health.url);
-        const baseSearch = parsed.search;
-        const baseHash = parsed.hash;
-        parsed.search = "";
-        parsed.hash = "";
-        parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/`;
-        const appended = new URL(health.path.replace(/^\/+/, ""), parsed);
-        if (appended.origin !== parsed.origin)
-            throw new Error("HTTP readiness path must stay on the configured URL origin.");
-        if (!appended.search)
-            appended.search = baseSearch;
-        if (!appended.hash)
-            appended.hash = baseHash;
-        url = appended.toString();
-    }
+function appendHttpHealthPath(url, healthPath) {
+    const parsed = new URL(url);
+    const baseSearch = parsed.search;
+    const baseHash = parsed.hash;
+    parsed.search = "";
+    parsed.hash = "";
+    parsed.pathname = `${parsed.pathname.replace(/\/$/, "")}/`;
+    const appended = new URL(healthPath.replace(/^\/+/, ""), parsed);
+    if (appended.origin !== parsed.origin)
+        throw new Error("HTTP readiness path must stay on the configured URL origin.");
+    if (appended.username || appended.password)
+        throw new Error("HTTP readiness URL credentials must use the secret channel.");
+    if (!appended.search)
+        appended.search = baseSearch;
+    if (!appended.hash)
+        appended.hash = baseHash;
+    return appended.toString();
+}
+function leasedHttpHealthUrl(url, healthPath, port) {
+    const source = url ? new URL(url) : undefined;
+    const protocol = source?.protocol ?? "http:";
+    const suffix = source ? `${source.pathname}${source.search}${source.hash}` : healthPath ?? "/";
+    return `${protocol}//127.0.0.1:${port}${suffix}`;
+}
+/** Resolve the endpoint used by startup and later readiness probes. */
+export function resolveHttpReadinessUrl(health, ports) {
+    const port = health.port ? ports[health.port] : undefined;
+    const configured = health.url ? new URL(health.url) : undefined;
+    if (configured && configured.protocol !== "http:" && configured.protocol !== "https:")
+        throw new Error("HTTP readiness URL must use http or https.");
+    if (configured && (configured.username || configured.password))
+        throw new Error("HTTP readiness URL credentials must use the secret channel.");
+    let url = health.url ?? "";
+    if (health.url && health.path)
+        url = appendHttpHealthPath(url, health.path);
+    // Validate an absolute path against the configured origin first. The direct
+    // lease replaces the origin only after that relationship is established.
+    if (port !== undefined)
+        url = leasedHttpHealthUrl(url, health.path, port);
     const parsed = new URL(url);
     if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
         throw new Error("HTTP readiness URL must use http or https.");
     return parsed.toString();
 }
 async function httpReady(health, input, timeoutMs) {
-    const url = resolveHttpUrl(health, input);
+    const url = resolveHttpReadinessUrl(health, input.ports);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
@@ -169,7 +189,7 @@ export async function waitForReadiness(input) {
     }
     if (input.health.type === "http") {
         try {
-            resolveHttpUrl(input.health, input);
+            resolveHttpReadinessUrl(input.health, input.ports);
         }
         catch (error) {
             throw new ProcessError("DEVFN_PROCESS_NOT_READY", "Invalid HTTP readiness configuration.", { cause: error instanceof Error ? error.message : String(error) });

package/dist/supervisor.d.ts

@@ -1,10 +1,39 @@
-import { type ManagedProcess, type StartProcessInput } from "./types.js";
+import { type ManagedProcess, type ProcessRunResult, type RunProcessInput, type StartProcessInput } from "./types.js";
 export declare function prepareProcessLog(logPath: string, resetSensitiveHistory: boolean): Promise<{
     logFd: number;
     logOffset: number;
 }>;
 export declare class ProcessSupervisor {
     start(input: StartProcessInput): Promise<ManagedProcess>;
+    /**
+     * Run a finite command to completion through the same gated wrapper: it
+     * starts only after onStarted recorded its identity (a failed recording
+     * means it never ran), and a timeout or abort stops its whole process
+     * group. Whatever it left in its group is stopped once it exits. Only exit
+     * code 0 succeeds; nothing the command changed is undone. Both limits bound
+     * the recording too: a run that throws never ran its command.
+     */
+    run(input: RunProcessInput): Promise<ProcessRunResult>;
+    /**
+     * Await onStarted until it settles or a run limit is reached. Returns why
+     * the recording failed; the caller checks the limits as it opens the gate,
+     * so a recording that settles after the run gave up never opens it.
+     */
+    private recordIdentity;
+    /** Spawn the gated wrapper for a command, its identity read and its output going to a private log. */
+    private launch;
+    /**
+     * Stop a process and everything its wrapper's group still runs. A reused
+     * PID is reported as a mismatch; an unreadable identity, or a wrapper that
+     * exited while its group lives on, is never signalled and never reported
+     * gone.
+     */
     stop(managed: ManagedProcess, timeoutMs?: number): Promise<void>;
-    status(managed: ManagedProcess): Promise<"running" | "stopped" | "identity-mismatch">;
+    /**
+     * "stopped" and "identity-mismatch" prove nothing the process ran remains;
+     * "unverified" is a live PID whose identity cannot be read, or a wrapper
+     * that exited while processes remain in its group, either of which may
+     * still be it and must never be treated as stopped.
+     */
+    status(managed: ManagedProcess): Promise<"running" | "stopped" | "identity-mismatch" | "unverified">;
 }

package/dist/supervisor.js

@@ -5,27 +5,25 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveContainedPath } from "@devfn/config";
 import { createProcessEnvironment, resolveAdapterCommand } from "./adapters.js";
-import { matchesProcessIdentity, processBirthSignature, processExists } from "./identity.js";
+import { stopProcessGroup } from "./group.js";
+import { processExists, processGroupStatus, startedProcessBirthSignature } from "./identity.js";
 import { waitForReadiness } from "./readiness.js";
 import { ProcessError } from "./types.js";
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function terminateProcess(pid, force = false) {
-    if (process.platform !== "win32") {
-        process.kill(-pid, force ? "SIGKILL" : "SIGTERM");
-        return;
-    }
+/** Let the wrapper run its command and wait until it detached from the channel. */
+async function openLaunchGate(child) {
+    if (!child.connected)
+        throw new ProcessError("DEVFN_PROCESS_START_FAILED", "Process wrapper exited before its launch gate opened.");
     await new Promise((resolve, reject) => {
-        const child = spawn("taskkill", ["/pid", String(pid), "/T", ...(force ? ["/F"] : [])], { stdio: "ignore", windowsHide: true });
-        child.once("error", reject);
-        child.once("exit", (code) => code === 0 || !processExists(pid) ? resolve() : reject(new Error(`taskkill exited with ${code}`)));
+        const timer = setTimeout(() => reject(new ProcessError("DEVFN_PROCESS_START_FAILED", "Process wrapper did not acknowledge its launch gate.")), 10_000);
+        child.once("disconnect", () => { clearTimeout(timer); resolve(); });
+        child.send("start", (error) => {
+            if (!error)
+                return;
+            clearTimeout(timer);
+            reject(new ProcessError("DEVFN_PROCESS_START_FAILED", "Unable to open the process launch gate.", { cause: error.message }));
+        });
     });
 }
-async function waitForProcessExit(pid, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline && processExists(pid))
-        await delay(50);
-    return !processExists(pid);
-}
 export async function prepareProcessLog(logPath, resetSensitiveHistory) {
     const existing = await lstat(logPath).catch((error) => {
         if (error.code === "ENOENT")
@@ -50,13 +48,160 @@ export async function prepareProcessLog(logPath, resetSensitiveHistory) {
         throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Unable to open process log ${logPath} safely.`, { cause: error instanceof Error ? error.message : String(error) });
     }
 }
+// A process a finite command left behind can hold its output open after the
+// command exits; the wrapper stops waiting for that output after this long,
+// so the run ends with the command and the leftover is stopped with its group.
+const RUN_DRAIN_MS = 1_000;
+const MAX_TIMER_MS = 2_147_483_647;
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+/** The first of a run's timeout and its abort signal, once either is reached. */
+function runLimit(timeoutMs, signal) {
+    let current;
+    let timer;
+    let onAbort;
+    const reached = new Promise((resolve) => {
+        const reach = (limit) => { current ??= limit; resolve(current); };
+        timer = setTimeout(() => reach("timed-out"), timeoutMs);
+        onAbort = () => reach("cancelled");
+        if (signal?.aborted)
+            onAbort();
+        else
+            signal?.addEventListener("abort", onAbort, { once: true });
+    });
+    return { reached, current: () => current, dispose: () => { clearTimeout(timer); if (onAbort)
+            signal?.removeEventListener("abort", onAbort); } };
+}
+/** Why a run must never start its command once a limit was reached. */
+function notStarted(input, reached) {
+    if (reached === undefined)
+        return undefined;
+    const why = reached === "timed-out" ? `timed out after ${input.timeoutMs} ms` : "was cancelled";
+    return { reason: new ProcessError("DEVFN_PROCESS_START_FAILED", `Task ${input.name} ${why} before it started.`) };
+}
+function runResult(managed, ended, stopError, error) {
+    let outcome;
+    if (typeof ended === "string")
+        outcome = ended;
+    else
+        outcome = ended.code === 0 ? "succeeded" : "failed";
+    const status = typeof ended === "string" ? { code: null, signal: null } : ended;
+    return { outcome, exitCode: status.code, signal: status.signal, process: managed, ...(error ? { error } : {}), ...(stopError ? { stopError } : {}) };
+}
 export class ProcessSupervisor {
     async start(input) {
         const command = resolveAdapterCommand(input.spec);
+        const { child, managed, logOffset, cwd, environment, exited } = await this.launch({ name: input.name, command, root: input.root, cwd: input.spec.cwd,
+            runtimeDir: input.runtimeDir, environment: createProcessEnvironment(input.spec, input.environment), redactKeys: input.spec.secretEnv ?? [],
+            ...(input.spec.shutdownTimeoutMs === undefined ? {} : { shutdownTimeoutMs: input.spec.shutdownTimeoutMs }) });
+        try {
+            try {
+                await input.onStarted?.(managed);
+                await openLaunchGate(child);
+            }
+            finally {
+                if (child.connected)
+                    child.disconnect();
+            }
+            await waitForReadiness({ health: input.spec.health, ports: input.ports ?? {}, logPath: managed.logPath, logOffset, cwd, environment, isAlive: () => !exited() && processExists(managed.pid) });
+            managed.readyAt = new Date().toISOString();
+            return managed;
+        }
+        catch (error) {
+            await stopProcessGroup(managed, managed.name, input.spec.shutdownTimeoutMs ?? 10_000, { ownGroup: { leaderUnreaped: () => !exited() } }).catch(() => undefined);
+            throw error;
+        }
+    }
+    /**
+     * Run a finite command to completion through the same gated wrapper: it
+     * starts only after onStarted recorded its identity (a failed recording
+     * means it never ran), and a timeout or abort stops its whole process
+     * group. Whatever it left in its group is stopped once it exits. Only exit
+     * code 0 succeeds; nothing the command changed is undone. Both limits bound
+     * the recording too: a run that throws never ran its command.
+     */
+    async run(input) {
+        // A timer clamps anything else to 1 ms, which would end every run at once.
+        if (!Number.isInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > MAX_TIMER_MS) {
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Task ${input.name} has an invalid timeout of ${input.timeoutMs} ms.`);
+        }
+        const { child, managed, exited } = await this.launch({ ...input,
+            wrapperEnvironment: { DEVFN_WRAPPER_DRAIN_MS: String(RUN_DRAIN_MS), ...(input.discardOutput ? { DEVFN_DISCARD_OUTPUT: "1" } : {}) } });
+        let settle;
+        const exit = new Promise((resolve) => { settle = resolve; });
+        if (exited())
+            settle({ code: child.exitCode, signal: child.signalCode });
+        else
+            child.once("exit", (code, signal) => settle({ code, signal }));
+        // Once stopped, or past stopping, the wrapper no longer holds the caller's event loop open.
+        // A stop failure never hides the command's own outcome; the caller reports both.
+        const stop = async () => {
+            try {
+                await stopProcessGroup(managed, managed.name, input.shutdownTimeoutMs ?? 10_000, { ownGroup: { leaderUnreaped: () => !exited() } });
+                return undefined;
+            }
+            catch (error) {
+                return errorMessage(error);
+            }
+            finally {
+                child.unref();
+            }
+        };
+        child.ref();
+        // The timeout and abort bound the whole run: the identity recording and the gate too.
+        const limit = runLimit(input.timeoutMs, input.signal);
+        try {
+            // Decided in the turn that sends start, so a limit reached any time before the send keeps the gate closed.
+            const unstarted = await this.recordIdentity(input, managed, limit) ?? notStarted(input, limit.current());
+            if (unstarted) {
+                // Closing the channel before the gate opens makes the wrapper exit without running the command.
+                if (child.connected)
+                    child.disconnect();
+                const stopError = await stop();
+                throw stopError ? new ProcessError("DEVFN_PROCESS_START_FAILED", errorMessage(unstarted.reason), { stopError }) : unstarted.reason;
+            }
+            const gate = openLaunchGate(child);
+            gate.catch(() => undefined);
+            let ended;
+            let error;
+            try {
+                ended = await Promise.race([gate.then(() => exit), limit.reached]);
+            }
+            catch (error_) {
+                // The wrapper may have received the gate and started the command, so it ends as a failed run.
+                ended = { code: null, signal: null };
+                error = errorMessage(error_);
+            }
+            if (child.connected)
+                child.disconnect();
+            return runResult(managed, ended, await stop(), error);
+        }
+        finally {
+            limit.dispose();
+        }
+    }
+    /**
+     * Await onStarted until it settles or a run limit is reached. Returns why
+     * the recording failed; the caller checks the limits as it opens the gate,
+     * so a recording that settles after the run gave up never opens it.
+     */
+    async recordIdentity(input, managed, limit) {
+        const recorded = Promise.resolve().then(async () => { await input.onStarted?.(managed); });
+        recorded.catch(() => undefined);
+        try {
+            await Promise.race([recorded, limit.reached]);
+            return undefined;
+        }
+        catch (error) {
+            return { reason: error };
+        }
+    }
+    /** Spawn the gated wrapper for a command, its identity read and its output going to a private log. */
+    async launch(input) {
+        const { command } = input;
         if (command.length === 0)
             throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Process ${input.name} has no command.`);
-        const cwd = await resolveContainedPath(input.root, input.spec.cwd ?? ".", `processes.${input.name}.cwd`).catch((error) => {
-            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Process cwd escapes repository: ${input.spec.cwd ?? "."}`, { cause: error instanceof Error ? error.message : String(error) });
+        const cwd = await resolveContainedPath(input.root, input.cwd ?? ".", `processes.${input.name}.cwd`).catch((error) => {
+            throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Process cwd escapes repository: ${input.cwd ?? "."}`, { cause: error instanceof Error ? error.message : String(error) });
         });
         const logsDir = path.join(input.runtimeDir, "logs");
         await mkdir(logsDir, { recursive: true, mode: 0o700 });
@@ -64,15 +209,21 @@ export class ProcessSupervisor {
             throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Invalid process name ${input.name}.`);
         const logPath = path.join(logsDir, `${input.name}.log`);
         mkdirSync(path.dirname(logPath), { recursive: true });
-        const { logFd, logOffset } = await prepareProcessLog(logPath, Boolean(input.spec.secretEnv?.length));
-        const environment = createProcessEnvironment(input.spec, input.environment);
+        // Only discardOutput may ask the wrapper to discard output, never the
+        // given environment (in any key casing, as Windows reads it).
+        const environment = { ...input.environment };
+        for (const key of Object.keys(environment))
+            if (key.toUpperCase() === "DEVFN_DISCARD_OUTPUT")
+                delete environment[key];
+        const { logFd, logOffset } = await prepareProcessLog(logPath, Boolean(input.redactKeys?.length) || input.discardOutput === true);
         const wrapperPath = fileURLToPath(new URL("./wrapper.js", import.meta.url));
         const child = spawn(process.execPath, [wrapperPath], {
             cwd,
-            env: { ...environment, DEVFN_WRAPPED_COMMAND: JSON.stringify(command), DEVFN_REDACT_KEYS: JSON.stringify(input.spec.secretEnv ?? []) },
+            env: { ...environment, DEVFN_WRAPPED_COMMAND: JSON.stringify(command), DEVFN_REDACT_KEYS: JSON.stringify(input.redactKeys ?? []), ...input.wrapperEnvironment },
             detached: process.platform !== "win32",
             windowsHide: true,
-            stdio: ["ignore", logFd, logFd],
+            // The IPC channel gates the command until its identity is recorded.
+            stdio: ["ignore", logFd, logFd, "ipc"],
         });
         let exited = false;
         child.once("exit", () => { exited = true; });
@@ -85,13 +236,10 @@ export class ProcessSupervisor {
         if (!child.pid)
             throw new ProcessError("DEVFN_PROCESS_START_FAILED", `Process ${input.name} did not receive a PID.`);
         child.unref();
-        let birthSignature;
-        for (let attempt = 0; attempt < 10 && !birthSignature; attempt += 1) {
-            birthSignature = await processBirthSignature(child.pid);
-            if (!birthSignature)
-                await delay(20);
-        }
+        const birthSignature = await startedProcessBirthSignature(child.pid);
         if (!birthSignature) {
+            if (child.connected)
+                child.disconnect();
             try {
                 if (process.platform !== "win32")
                     process.kill(-child.pid, "SIGTERM");
@@ -109,41 +257,30 @@ export class ProcessSupervisor {
             cwd,
             logPath,
             startedAt: new Date().toISOString(),
-            ...(input.spec.shutdownTimeoutMs === undefined ? {} : { shutdownTimeoutMs: input.spec.shutdownTimeoutMs }),
+            ...(input.shutdownTimeoutMs === undefined ? {} : { shutdownTimeoutMs: input.shutdownTimeoutMs }),
         };
-        try {
-            await input.onStarted?.(managed);
-            await waitForReadiness({ health: input.spec.health, ports: input.ports ?? {}, logPath, logOffset, cwd, environment, isAlive: () => !exited && processExists(managed.pid) });
-            managed.readyAt = new Date().toISOString();
-            return managed;
-        }
-        catch (error) {
-            await this.stop(managed, input.spec.shutdownTimeoutMs).catch(() => undefined);
-            throw error;
-        }
+        return { child, managed, logOffset, cwd, environment, exited: () => exited };
     }
+    /**
+     * Stop a process and everything its wrapper's group still runs. A reused
+     * PID is reported as a mismatch; an unreadable identity, or a wrapper that
+     * exited while its group lives on, is never signalled and never reported
+     * gone.
+     */
     async stop(managed, timeoutMs = managed.shutdownTimeoutMs ?? 10_000) {
-        if (!processExists(managed.pid))
-            return;
-        if (!await matchesProcessIdentity(managed.pid, managed.birthSignature)) {
+        if (await processGroupStatus(managed.pid, managed.birthSignature, managed.startedAt) === "identity-mismatch") {
             throw new ProcessError("DEVFN_PROCESS_OWNERSHIP_MISMATCH", `PID ${managed.pid} no longer matches the DevFn process identity.`, { name: managed.name, pid: managed.pid });
         }
-        try {
-            await terminateProcess(managed.pid);
-            if (!await waitForProcessExit(managed.pid, timeoutMs)) {
-                await terminateProcess(managed.pid, true);
-                if (!await waitForProcessExit(managed.pid, 5_000))
-                    throw new ProcessError("DEVFN_PROCESS_STOP_FAILED", `Process ${managed.name} did not exit after forced termination.`);
-            }
-        }
-        catch (error) {
-            if (error.code !== "ESRCH")
-                throw new ProcessError("DEVFN_PROCESS_STOP_FAILED", `Unable to stop ${managed.name}.`, { cause: error instanceof Error ? error.message : String(error) });
-        }
+        await stopProcessGroup(managed, managed.name, timeoutMs);
     }
+    /**
+     * "stopped" and "identity-mismatch" prove nothing the process ran remains;
+     * "unverified" is a live PID whose identity cannot be read, or a wrapper
+     * that exited while processes remain in its group, either of which may
+     * still be it and must never be treated as stopped.
+     */
     async status(managed) {
-        if (!processExists(managed.pid))
-            return "stopped";
-        return await matchesProcessIdentity(managed.pid, managed.birthSignature) ? "running" : "identity-mismatch";
+        const status = await processGroupStatus(managed.pid, managed.birthSignature, managed.startedAt);
+        return status === "exited" ? "stopped" : status;
     }
 }

package/dist/types.d.ts

@@ -10,6 +10,13 @@ export interface ManagedProcess {
     readyAt?: string;
     shutdownTimeoutMs?: number;
 }
+/** A recorded process identity; the birth signature tells a reused PID apart. */
+export interface ProcessOwnerIdentity {
+    pid: number;
+    birthSignature?: string;
+    /** When DevFn recorded this identity, after reading it from the live process. */
+    startedAt?: string;
+}
 export interface StartProcessInput {
     name: string;
     spec: ProcessSpec;
@@ -19,8 +26,37 @@ export interface StartProcessInput {
     ports?: Record<string, number>;
     onStarted?: (process: ManagedProcess) => Promise<void>;
 }
+export interface RunProcessInput {
+    name: string;
+    /** The complete command and environment; nothing is added to them. */
+    command: string[];
+    environment: NodeJS.ProcessEnv;
+    root: string;
+    /** Repository-relative working directory. */
+    cwd?: string;
+    runtimeDir: string;
+    /** Environment keys whose values are redacted from the log. */
+    redactKeys?: readonly string[];
+    /** Keep none of the command's output, for output that may carry values redaction cannot know. */
+    discardOutput?: boolean;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    shutdownTimeoutMs?: number;
+    /** Record the identity; the command runs only after this resolves. */
+    onStarted?: (process: ManagedProcess) => Promise<void>;
+}
+export interface ProcessRunResult {
+    outcome: "succeeded" | "failed" | "timed-out" | "cancelled";
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    process: ManagedProcess;
+    /** Why a run that may have started has no exit status. */
+    error?: string;
+    /** Something the command left behind could not be stopped. */
+    stopError?: string;
+}
 export declare class ProcessError extends Error {
-    readonly code: "DEVFN_PROCESS_START_FAILED" | "DEVFN_PROCESS_NOT_READY" | "DEVFN_PROCESS_OWNERSHIP_MISMATCH" | "DEVFN_PROCESS_STOP_FAILED";
+    readonly code: "DEVFN_PROCESS_START_FAILED" | "DEVFN_PROCESS_NOT_READY" | "DEVFN_PROCESS_OWNERSHIP_MISMATCH" | "DEVFN_PROCESS_IDENTITY_UNVERIFIED" | "DEVFN_PROCESS_STOP_FAILED";
     readonly details?: Record<string, unknown> | undefined;
-    constructor(code: "DEVFN_PROCESS_START_FAILED" | "DEVFN_PROCESS_NOT_READY" | "DEVFN_PROCESS_OWNERSHIP_MISMATCH" | "DEVFN_PROCESS_STOP_FAILED", message: string, details?: Record<string, unknown> | undefined);
+    constructor(code: "DEVFN_PROCESS_START_FAILED" | "DEVFN_PROCESS_NOT_READY" | "DEVFN_PROCESS_OWNERSHIP_MISMATCH" | "DEVFN_PROCESS_IDENTITY_UNVERIFIED" | "DEVFN_PROCESS_STOP_FAILED", message: string, details?: Record<string, unknown> | undefined);
 }

package/dist/wrapper.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { constants } from "node:os";
 import { createStreamingRedactor } from "./redaction.js";
 function requiredJson(name) {
     const raw = process.env[name];
@@ -12,27 +13,81 @@ if (!Array.isArray(command) || command.length === 0 || !command.every((item) =>
     throw new Error("Invalid wrapped command.");
 if (!Array.isArray(keys) || !keys.every((item) => typeof item === "string"))
     throw new Error("Invalid redaction keys.");
+// The supervisor opens this gate only after it recorded this process's
+// identity. If it dies first, the channel closes and the command never runs,
+// so a launch without a recorded identity proves nothing of it started.
+// Without the channel there is no gate, so the command never runs.
+if (!process.send) {
+    process.stderr.write("The DevFn process wrapper requires its launch gate channel.\n");
+    process.exit(1);
+}
+const opened = await new Promise((resolve) => {
+    process.once("message", (message) => resolve(message === "start"));
+    process.once("disconnect", () => resolve(false));
+});
+process.removeAllListeners("message");
+process.removeAllListeners("disconnect");
+if (!opened)
+    process.exit(1);
+process.disconnect();
+const drainMs = Number(process.env.DEVFN_WRAPPER_DRAIN_MS ?? Number.NaN);
+const discard = process.env.DEVFN_DISCARD_OUTPUT === "1";
 const environment = { ...process.env };
 delete environment.DEVFN_WRAPPED_COMMAND;
 delete environment.DEVFN_REDACT_KEYS;
+delete environment.DEVFN_WRAPPER_DRAIN_MS;
+delete environment.DEVFN_DISCARD_OUTPUT;
 const secrets = [...new Set(keys.map((key) => environment[key]).filter((value) => typeof value === "string" && value.length > 0))].sort((a, b) => b.length - a.length);
-const child = spawn(command[0], command.slice(1), { cwd: process.cwd(), env: environment, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+if (discard)
+    process.stdout.write("[DevFn] Output of this command is not kept: it may carry secret values DevFn cannot redact.\n");
+const child = spawn(command[0], command.slice(1), { cwd: process.cwd(), env: environment, stdio: ["ignore", discard ? "ignore" : "pipe", discard ? "ignore" : "pipe"], windowsHide: true });
+/** Forward output, redacted; the returned function flushes what is held back. */
 function pipeRedacted(stream, destination) {
     if (secrets.length === 0) {
         stream.pipe(destination, { end: false });
-        return;
+        return () => undefined;
     }
     const redactor = createStreamingRedactor(secrets, (value) => destination.write(value));
+    let ended = false;
+    const end = () => { if (!ended) {
+        ended = true;
+        redactor.end();
+    } };
     stream.setEncoding("utf8");
     stream.on("data", (chunk) => redactor.push(chunk));
-    stream.on("end", () => redactor.end());
+    stream.on("end", end);
+    return end;
 }
-pipeRedacted(child.stdout, process.stdout);
-pipeRedacted(child.stderr, process.stderr);
-child.once("error", (error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
-child.once("close", (code, signal) => {
-    if (signal)
-        process.kill(process.pid, signal);
-    else
+const flushes = discard ? [] : [pipeRedacted(child.stdout, process.stdout), pipeRedacted(child.stderr, process.stderr)];
+// Node ignores SIGPIPE and SIGXFSZ and opens its inspector on SIGUSR1, so
+// the wrapper never sends itself those. Whatever becomes of a signal it does
+// send itself, its exit code reports a command a signal ended as failed.
+const unmirrored = new Set(["SIGPIPE", "SIGXFSZ", "SIGUSR1"]);
+const finish = (code, signal) => {
+    if (!signal) {
         process.exitCode = code ?? 1;
-});
+        return;
+    }
+    process.exitCode = 128 + (constants.signals[signal] ?? 0);
+    if (!unmirrored.has(signal))
+        process.kill(process.pid, signal);
+};
+let closed = false;
+child.once("error", (error) => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
+child.once("close", (code, signal) => { closed = true; finish(code, signal); });
+// A process the command left behind can hold its output open after the
+// command exits. With a drain limit the wrapper then stops waiting for that
+// output and exits, so its caller can stop what remains of its group.
+if (Number.isInteger(drainMs) && drainMs >= 0) {
+    child.once("exit", (code, signal) => {
+        setTimeout(() => {
+            if (closed)
+                return;
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            for (const flush of flushes)
+                flush();
+            finish(code, signal);
+        }, drainMs).unref();
+    });
+}

package/package.json

@@ -1,15 +1,43 @@
 {
   "name": "@devfn/processes",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Browser-neutral native process supervision and readiness for DevFn and ProbeFn consumers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/superfunctions.git",
+    "directory": "devfn/processes"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist", "README.md"],
-  "scripts": { "build": "tsc -p tsconfig.json", "typecheck": "tsc --noEmit -p tsconfig.json", "test": "vitest run", "lint": "echo 'lint not configured'", "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"" },
-  "dependencies": { "@devfn/config": "0.1.0" },
-  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0", "vitest": "^3.2.4" },
-  "engines": { "node": ">=22" },
-  "license": "MIT"
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "echo 'lint not configured'",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "@devfn/config": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "gitHead": "699d9d09932199d660333c57fe7bc646492ea3bf"
 }