@descryy/runtime-controller 0.0.0

package/dist/process-manager.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Process manager (plan §5): command execution, working directory,
+ * environment variables, process-group tracking, stdout/stderr capture,
+ * exit-code capture, cleanup with a shutdown grace period, and orphan-
+ * process prevention.
+ *
+ * Orphan prevention and group-kill use POSIX process groups
+ * (`detached: true` + `process.kill(-pid, signal)`), matching this
+ * project's Linux development and CI targets. Not portable to Windows as
+ * written — out of scope for the V1 fixture-app slice (plan §34).
+ */
+import type { FilesystemPolicy, NetworkPolicy, ProcessHandle, ResourceLimits, ServiceAttachConfiguration } from "@descryy/runtime-contracts";
+/**
+ * Binds port 0 (OS picks a free one), reads it, releases it immediately.
+ * A real gap remains between "free when checked" and "still free when the
+ * real service binds it" (RT-024's own class of gap, one layer down) --
+ * unavoidable without binding the real service directly to the probe
+ * socket, which `spawnProcess`'s child-process model doesn't support, and
+ * which no ordinary application would cooperate with anyway.
+ *
+ * **Examined for a fix and deliberately not "fixed".** Holding the probe
+ * socket open for longer does not narrow the window, it widens it: the
+ * child cannot bind while we hold the port, and the dominant term is the
+ * child's own startup, not our release. Retrying on the child's bind error
+ * would mean parsing that error out of process output, which is
+ * per-language text and has no place in a language-neutral controller.
+ * What was done instead is to make the one symptom legible: `awaitReadiness`
+ * now names the endpoint it probed, so a collision reads as "nothing
+ * answered on this port" rather than as an unexplained application failure.
+ * In practice the window is a handful of milliseconds and readiness always
+ * runs afterwards, so a genuine collision fails loudly -- it is just no
+ * longer misattributed.
+ */
+export declare function allocateEphemeralPort(): Promise<number>;
+export interface SpawnProcessOptions {
+    readonly processId: string;
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Joins the resulting ProcessHandle back to ExecutionConfiguration.services (RT-023). Omit for a process with no corresponding named service. */
+    readonly serviceName?: string;
+    /** The real port this process is bound to, when the caller already knows it (e.g. an ephemeral port it allocated before spawning). Recorded on the handle, not otherwise used by this function. */
+    readonly port?: number;
+    /** §21's execution boundary (RT-070). Applied via `applyResourceLimits` -- see its own comment for the refuse-rather-than-silently-unconstrained contract. Re-applied on every (re)spawn, including `restart()`. */
+    readonly resourceLimits?: ResourceLimits;
+    /** §21's execution boundary, filesystem half. Applied via `applySandbox` -- see its own comment. Re-applied on every (re)spawn, including `restart()`. */
+    readonly filesystemPolicy?: FilesystemPolicy;
+    /** §21's execution boundary, network half. Applied via `applySandbox` -- see its own comment. Re-applied on every (re)spawn, including `restart()`. */
+    readonly networkPolicy?: NetworkPolicy;
+    /**
+     * Selects which real mechanism enforces `filesystemPolicy`/`networkPolicy`.
+     * Absent means `"bwrap"` -- exactly today's behavior, unchanged.
+     * `"container"` routes through `applyContainerSandbox` (`./container-sandbox.ts`)
+     * instead. See `ExecutionConfiguration.sandboxBackend`'s own comment.
+     *
+     * **Does not compose with `resourceLimits` in this pass**: the container
+     * backend applies directly to `command`/`args`, skipping
+     * `applyResourceLimits`'s `prlimit` wrap entirely (a minimal container
+     * image is not guaranteed to carry `prlimit`, and Docker's own
+     * `--memory`/`--cpus`/`--pids-limit` equivalent is not wired up here) --
+     * disclosed in `container-sandbox.ts`'s own module doc, not silently
+     * dropped.
+     */
+    readonly sandboxBackend?: "bwrap" | "container";
+}
+export interface ProcessExitInfo {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+}
+export interface ManagedProcess {
+    handle(): ProcessHandle;
+    /** Combined stdout+stderr captured so far, in arrival order — the backing store for log-pattern readiness checks. */
+    readOutput(): string;
+    waitForExit(): Promise<ProcessExitInfo>;
+    /** SIGTERM the process group, wait up to `gracePeriodMs`, then SIGKILL if still alive. Idempotent. */
+    kill(gracePeriodMs?: number): Promise<void>;
+    /**
+     * Kills the current process (if still alive — a no-op wait if it already
+     * exited on its own) and spawns a fresh one with the SAME `command`/
+     * `args`/`cwd`/`env`. `handle()`, `readOutput()` and `waitForExit()` all
+     * observe the new process afterward — this is the same `ManagedProcess`
+     * object, not a new one, so a caller holding the original reference does
+     * not need to re-fetch anything. Readiness is the caller's job, same as
+     * after the original `spawnProcess` — this resolves once the new process
+     * EXISTS, not once it is ready.
+     */
+    restart(gracePeriodMs?: number): Promise<void>;
+}
+export declare function spawnProcess(options: SpawnProcessOptions): ManagedProcess;
+/**
+ * `process.kill(pid, 0)` sends no signal — it only asks the kernel whether
+ * delivery would be possible. `ESRCH` means no such pid; `EPERM` means a
+ * pid we don't own but that unambiguously exists, still alive for this
+ * purpose. Any other error is treated as "exists" rather than guessed away.
+ *
+ * A second, deliberate copy of `packages/orchestrator/src/attach-to-running-process.ts`'s
+ * function of the same name, not an import of it: `orchestrator` depends on
+ * `controller` (see `orchestrator/package.json`), so the reverse import
+ * would be circular. Tiny and pure, the same "duplicated because both
+ * copies are easy to notice drift" precedent `attach-to-running-jvm-process.ts`'s
+ * own `reconstructJvmSourcePath` already sets for exactly this reason.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+export interface AttachProcessOptions {
+    readonly processId: string;
+    readonly attach: ServiceAttachConfiguration;
+    readonly serviceName?: string;
+    readonly port?: number;
+}
+/**
+ * `ManagedProcess` for a service `ExecutionController.run()` attaches to
+ * instead of spawning (`ServiceConfiguration.attach`). Reads
+ * `attach.logFilePath` fresh on every `readOutput()` call — the same
+ * growing-whole-buffer contract a spawned process's in-memory pipe buffer
+ * already has (`spawnProcess`'s own `outputBuffer`), so `createPollingProcessOutputSource`
+ * (`@descryy/runtime-orchestrator`) needs no attach-specific branch to
+ * consume either one.
+ *
+ * **`kill()` is a deliberate no-op, not a stub.** Descry did not spawn this
+ * process and `ATTACH_MODE_SCOPE_DISCLOSURE` (`@descryy/runtime-contracts`)
+ * is unconditional: attach mode "never executes code in it or applies
+ * changes to it." `ExecutionController`'s cleanup path kills every managed
+ * process on failure/timeout/stop — for an attached service that would mean
+ * terminating a process this runtime does not own, silently, the exact
+ * thing the disclosure promises never happens. Ending observation (no
+ * further polling) is the honest equivalent of "stop" here; the target
+ * keeps running, as it was before Descry ever attached. `restart()` throws
+ * for the same reason: there is no command this runtime could relaunch it
+ * with.
+ */
+export declare function attachManagedProcess(options: AttachProcessOptions): ManagedProcess;
+//# sourceMappingURL=process-manager.d.ts.map

package/dist/process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../src/process-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAK7I;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAevD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,kJAAkJ;IAClJ,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mMAAmM;IACnM,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oNAAoN;IACpN,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,0JAA0J;IAC1J,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,uJAAuJ;IACvJ,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;CACjD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,IAAI,aAAa,CAAC;IACxB,qHAAqH;IACrH,UAAU,IAAI,MAAM,CAAC;IACrB,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,sGAAsG;IACtG,IAAI,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAID,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CAiKzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CA4ElF"}

package/dist/process-manager.js

@@ -0,0 +1,333 @@
+/**
+ * Process manager (plan §5): command execution, working directory,
+ * environment variables, process-group tracking, stdout/stderr capture,
+ * exit-code capture, cleanup with a shutdown grace period, and orphan-
+ * process prevention.
+ *
+ * Orphan prevention and group-kill use POSIX process groups
+ * (`detached: true` + `process.kill(-pid, signal)`), matching this
+ * project's Linux development and CI targets. Not portable to Windows as
+ * written — out of scope for the V1 fixture-app slice (plan §34).
+ */
+import { execFile, spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { promisify } from "node:util";
+import { applyResourceLimits } from "./execution-safety.js";
+import { applySandbox } from "./sandbox.js";
+import { applyContainerSandbox } from "./container-sandbox.js";
+/**
+ * Binds port 0 (OS picks a free one), reads it, releases it immediately.
+ * A real gap remains between "free when checked" and "still free when the
+ * real service binds it" (RT-024's own class of gap, one layer down) --
+ * unavoidable without binding the real service directly to the probe
+ * socket, which `spawnProcess`'s child-process model doesn't support, and
+ * which no ordinary application would cooperate with anyway.
+ *
+ * **Examined for a fix and deliberately not "fixed".** Holding the probe
+ * socket open for longer does not narrow the window, it widens it: the
+ * child cannot bind while we hold the port, and the dominant term is the
+ * child's own startup, not our release. Retrying on the child's bind error
+ * would mean parsing that error out of process output, which is
+ * per-language text and has no place in a language-neutral controller.
+ * What was done instead is to make the one symptom legible: `awaitReadiness`
+ * now names the endpoint it probed, so a collision reads as "nothing
+ * answered on this port" rather than as an unexplained application failure.
+ * In practice the window is a handful of milliseconds and readiness always
+ * runs afterwards, so a genuine collision fails loudly -- it is just no
+ * longer misattributed.
+ */
+export function allocateEphemeralPort() {
+    return new Promise((resolve, reject) => {
+        const probe = createServer();
+        probe.once("error", reject);
+        probe.listen(0, () => {
+            const address = probe.address();
+            if (address === null || typeof address === "string") {
+                probe.close();
+                reject(new Error("could not determine an ephemeral port"));
+                return;
+            }
+            const { port } = address;
+            probe.close(() => resolve(port));
+        });
+    });
+}
+const DEFAULT_GRACE_PERIOD_MS = 5000;
+export function spawnProcess(options) {
+    let startedAt = "";
+    let exitedAt = null;
+    let exitCode = null;
+    let signal = null;
+    let outputBuffer = "";
+    let killStarted = false;
+    let child;
+    let settled = false;
+    // Set only for the container backend (applyContainerSandbox's own
+    // returned name) -- see kill()'s own comment for why the container
+    // needs a real, separate stop mechanism from the bwrap path's group-kill.
+    let containerName = null;
+    let resolveExit;
+    let exitPromise;
+    // Everything a (re)spawn needs to reset, in one place -- `restart()` calls
+    // this again after the previous child has fully exited, and the two call
+    // sites (initial construction, restart) must not drift into resetting
+    // different subsets of this state.
+    function spawnChild() {
+        startedAt = new Date().toISOString();
+        exitedAt = null;
+        exitCode = null;
+        signal = null;
+        outputBuffer = "";
+        killStarted = false;
+        settled = false;
+        exitPromise = new Promise((resolve) => {
+            resolveExit = resolve;
+        });
+        // "container" skips applyResourceLimits entirely (see SpawnProcessOptions.
+        // sandboxBackend's own comment on why prlimit composition isn't attempted
+        // for this backend yet) -- every other case (the default, "bwrap")
+        // behaves exactly as before this field existed.
+        const wrapped = options.sandboxBackend === "container"
+            ? applyContainerSandbox({
+                interpreterCommand: options.command,
+                command: options.command,
+                args: options.args ?? [],
+                cwd: options.cwd ?? process.cwd(),
+                processEnv: { ...process.env, ...options.env },
+                ...(options.filesystemPolicy === undefined ? {} : { filesystemPolicy: options.filesystemPolicy }),
+                ...(options.networkPolicy === undefined ? {} : { networkPolicy: options.networkPolicy }),
+            })
+            : applySandbox({
+                interpreterCommand: options.command,
+                ...applyResourceLimits(options.command, options.args ?? [], options.resourceLimits),
+                cwd: options.cwd ?? process.cwd(),
+                ...(options.filesystemPolicy === undefined ? {} : { filesystemPolicy: options.filesystemPolicy }),
+                ...(options.networkPolicy === undefined ? {} : { networkPolicy: options.networkPolicy }),
+            });
+        containerName = wrapped.containerName ?? null;
+        child = spawn(wrapped.command, wrapped.args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            detached: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout?.on("data", (chunk) => {
+            outputBuffer += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            outputBuffer += chunk.toString("utf8");
+        });
+        // Node does not call `spawn()`'s error path synchronously -- a bad
+        // command (ENOENT) surfaces later as an `'error'` event, never a thrown
+        // exception here, and per Node's own docs `'exit'` may never fire after
+        // an `'error'`. An EventEmitter's unhandled `'error'` event crashes the
+        // process, and with no `'exit'` guaranteed either, `exitPromise` would
+        // otherwise hang forever -- both `'exit'` and `'error'` settle the same
+        // promise exactly once, so a failed-to-spawn process reads as an
+        // ordinary never-became-ready process (no pid, no output, no readiness
+        // success) rather than crashing the caller or hanging its cleanup.
+        function settle(info) {
+            if (settled)
+                return;
+            settled = true;
+            exitedAt = new Date().toISOString();
+            exitCode = info.exitCode;
+            signal = info.signal;
+            resolveExit(info);
+        }
+        child.once("exit", (code, exitSignal) => settle({ exitCode: code, signal: exitSignal }));
+        child.once("error", () => settle({ exitCode: null, signal: null }));
+    }
+    spawnChild();
+    function handle() {
+        return {
+            processId: options.processId,
+            command: options.command,
+            pid: child.pid ?? null,
+            startedAt,
+            exitedAt,
+            exitCode,
+            signal,
+            serviceName: options.serviceName ?? null,
+            port: options.port ?? null,
+        };
+    }
+    async function kill(gracePeriodMs = DEFAULT_GRACE_PERIOD_MS) {
+        if (killStarted || exitedAt !== null) {
+            await exitPromise;
+            return;
+        }
+        killStarted = true;
+        const pid = child.pid;
+        if (pid === undefined) {
+            return;
+        }
+        if (containerName !== null) {
+            // Real finding from this backend's own escape tests, not assumed up
+            // front: the local `docker` CLI process is not the container -- it
+            // runs under `dockerd`, a separate process tree entirely. Signaling
+            // the CLI's process group (the mechanism below, correct for bwrap,
+            // which execs the sandboxed process directly) left a real orphaned
+            // container running in testing. `docker stop` targets the actual
+            // container by name and is the real stop mechanism for this backend;
+            // `--rm` (set by applyContainerSandbox) then removes it once stopped.
+            // Still falls through to the group-kill below afterward, as a
+            // backstop for the local CLI process itself.
+            try {
+                await execFileAsync("docker", ["stop", "--time", String(Math.max(1, Math.round(gracePeriodMs / 1000))), containerName]);
+            }
+            catch {
+                // Already stopped/removed (e.g. the process exited on its own
+                // first) -- not an error worth surfacing to the caller.
+            }
+        }
+        signalGroup(pid, "SIGTERM");
+        const exited = await Promise.race([exitPromise.then(() => true), sleep(gracePeriodMs).then(() => false)]);
+        if (!exited) {
+            signalGroup(pid, "SIGKILL");
+            await exitPromise;
+        }
+    }
+    async function restart(gracePeriodMs = DEFAULT_GRACE_PERIOD_MS) {
+        // Safe whether the process is still alive, already exited on its own,
+        // or already mid-kill -- `kill()` is idempotent in all three cases and
+        // this always waits for the OLD child to be fully gone before
+        // `spawnChild()` reassigns `child`/`exitPromise`/etc., so no event from
+        // the outgoing process can land on the incoming one's state.
+        await kill(gracePeriodMs);
+        spawnChild();
+    }
+    return {
+        handle,
+        readOutput: () => outputBuffer,
+        waitForExit: () => exitPromise,
+        kill,
+        restart,
+    };
+}
+/**
+ * `process.kill(pid, 0)` sends no signal — it only asks the kernel whether
+ * delivery would be possible. `ESRCH` means no such pid; `EPERM` means a
+ * pid we don't own but that unambiguously exists, still alive for this
+ * purpose. Any other error is treated as "exists" rather than guessed away.
+ *
+ * A second, deliberate copy of `packages/orchestrator/src/attach-to-running-process.ts`'s
+ * function of the same name, not an import of it: `orchestrator` depends on
+ * `controller` (see `orchestrator/package.json`), so the reverse import
+ * would be circular. Tiny and pure, the same "duplicated because both
+ * copies are easy to notice drift" precedent `attach-to-running-jvm-process.ts`'s
+ * own `reconstructJvmSourcePath` already sets for exactly this reason.
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+const DEFAULT_ATTACH_POLL_INTERVAL_MS = 50;
+/**
+ * `ManagedProcess` for a service `ExecutionController.run()` attaches to
+ * instead of spawning (`ServiceConfiguration.attach`). Reads
+ * `attach.logFilePath` fresh on every `readOutput()` call — the same
+ * growing-whole-buffer contract a spawned process's in-memory pipe buffer
+ * already has (`spawnProcess`'s own `outputBuffer`), so `createPollingProcessOutputSource`
+ * (`@descryy/runtime-orchestrator`) needs no attach-specific branch to
+ * consume either one.
+ *
+ * **`kill()` is a deliberate no-op, not a stub.** Descry did not spawn this
+ * process and `ATTACH_MODE_SCOPE_DISCLOSURE` (`@descryy/runtime-contracts`)
+ * is unconditional: attach mode "never executes code in it or applies
+ * changes to it." `ExecutionController`'s cleanup path kills every managed
+ * process on failure/timeout/stop — for an attached service that would mean
+ * terminating a process this runtime does not own, silently, the exact
+ * thing the disclosure promises never happens. Ending observation (no
+ * further polling) is the honest equivalent of "stop" here; the target
+ * keeps running, as it was before Descry ever attached. `restart()` throws
+ * for the same reason: there is no command this runtime could relaunch it
+ * with.
+ */
+export function attachManagedProcess(options) {
+    const { pid, logFilePath } = options.attach;
+    if (!isProcessAlive(pid)) {
+        throw new Error(`attachManagedProcess: pid ${String(pid)} for "${options.processId}" is not running — attach requires ` +
+            `a target that already exists.`);
+    }
+    const startedAt = new Date().toISOString();
+    let exitedAt = null;
+    let exitPromise = null;
+    function handle() {
+        if (exitedAt === null && !isProcessAlive(pid)) {
+            exitedAt = new Date().toISOString();
+        }
+        return {
+            processId: options.processId,
+            // No command to report — this runtime never launched this process,
+            // so there is nothing here that isn't a guess. Disclosed rather than
+            // fabricated.
+            command: `<attached: pid ${String(pid)}, ${logFilePath}>`,
+            pid,
+            startedAt,
+            exitedAt,
+            // Neither is observable for a process we did not spawn and do not
+            // reap — see this function's own module doc on why `kill()` never
+            // signals it, which is exactly what would let us learn either.
+            exitCode: null,
+            signal: null,
+            serviceName: options.serviceName ?? null,
+            port: options.port ?? null,
+            attached: true,
+        };
+    }
+    function readOutput() {
+        try {
+            return readFileSync(logFilePath, "utf8");
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`attachManagedProcess: could not read log file "${logFilePath}" for pid ${String(pid)}: ${detail}`);
+        }
+    }
+    function waitForExit() {
+        exitPromise ??= new Promise((resolve) => {
+            const poll = () => {
+                if (!isProcessAlive(pid)) {
+                    exitedAt ??= new Date().toISOString();
+                    resolve({ exitCode: null, signal: null });
+                    return;
+                }
+                setTimeout(poll, DEFAULT_ATTACH_POLL_INTERVAL_MS);
+            };
+            poll();
+        });
+        return exitPromise;
+    }
+    function kill() {
+        // Deliberate no-op — see this function's own module doc.
+        return Promise.resolve();
+    }
+    function restart() {
+        return Promise.reject(new Error(`attachManagedProcess: cannot restart an attached process (pid ${String(pid)}) — Descry did not spawn ` +
+            `it and has no command to relaunch it with.`));
+    }
+    return { handle, readOutput, waitForExit, kill, restart };
+}
+const execFileAsync = promisify(execFile);
+function signalGroup(pid, signal) {
+    try {
+        // Negative pid targets the whole process group (the child is its
+        // leader, per `detached: true`), not just the immediate process --
+        // this is the orphan-prevention mechanism.
+        process.kill(-pid, signal);
+    }
+    catch {
+        // Group already gone -- nothing to signal, not an error.
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=process-manager.js.map

package/dist/process-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.js","sourceRoot":"","sources":["../src/process-manager.ts"],"names":[],"mappings":"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"}

package/dist/readiness.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Readiness (plan §6): "Readiness must not equal 'process exists.'" —
+ * supported strategies are HTTP health check, TCP/port check, a known log
+ * pattern, a real subprocess command, or a caller-supplied hook (which
+ * covers the plan's "framework readiness hook" and "user-defined readiness"
+ * — two names for the same shape, a caller-provided async predicate,
+ * consolidated into one mechanism rather than two near-identical ones).
+ *
+ * **`command` is not `custom-hook` (RT-193).** An earlier version of this
+ * comment folded the plan's "command check" into `custom-hook` too, on the
+ * reasoning that both are "a caller-provided check." That collapsed a real
+ * distinction: `custom-hook` runs a caller's own in-process predicate,
+ * while `command` runs an actual subprocess and reads its actual exit
+ * code — the same "declared, not inferred" shape `ServiceConfiguration`'s
+ * own `command` field already uses, one layer over. A caller with a real
+ * CLI health check (`pg_isready`, a framework's own readiness script) had
+ * no way to express that without either wrapping it in a hand-written
+ * `custom-hook` predicate that shells out itself, or reimplementing the
+ * subprocess plumbing per caller — `command` is that plumbing, built once.
+ *
+ * The plan requires recording which mechanism succeeded — `ReadinessResult`
+ * makes that a field, not something inferred after the fact.
+ *
+ * **What `ready: true` does and does not claim (RT-024).** All four
+ * mechanisms answer one question — is something listening / responding
+ * where expected — and none answer whether it is the process *this*
+ * `spawnProcess` call produced. A stale listener from an unrelated, already-
+ * dead run satisfies `http`/`tcp-port` identically to a correct one; nothing
+ * here can tell them apart. `log-pattern` only carries the stronger,
+ * this-run-specific guarantee when its `read` is wired to *this* execution's
+ * own `ManagedProcess.readOutput()` — the type does not enforce that wiring,
+ * it is a caller discipline. `custom-hook` inherits whatever the caller's
+ * predicate actually checks.
+ *
+ * Callers that bind a fixed, guessable host:port are exposed to this gap;
+ * an ephemeral port closes it by construction (nothing else can already be
+ * bound there) rather than by detection, and is the default recommendation
+ * over a startup-nonce scheme, which only earns its extra machinery when a
+ * fixed port is genuinely unavoidable (a contract with an external tool).
+ * See `descry-runtime`'s `DECISIONS.md` RT-024 for how this was found —
+ * a real 30-second collector timeout that looked like a Playwright/DOM bug
+ * and was actually a correct wait against an orphaned process from a
+ * different, already-dead session.
+ *
+ * **A single probe attempt cannot outlive `timeoutMs` (RT-030).** `http`
+ * and `tcp-port` each bind their I/O to the *remaining* time until
+ * `deadline`, not a fresh per-attempt budget — a target that accepts a
+ * connection and never responds no longer lets one probe attempt run past
+ * the caller's own deadline. Measured, not theoretical: an unbound `fetch`
+ * here let `awaitReadiness` run past its own `timeoutMs` (>8s observed
+ * against a 3s budget). `command` honors the same discipline, the same
+ * way: `execFile`'s own `timeout` option is set to the remaining time until
+ * `deadline`, so a command that hangs instead of exiting is killed rather
+ * than left to run past the caller's own budget — it owns a real OS
+ * resource (a child process) exactly like the http/tcp-port sockets do, so
+ * it gets the same treatment. `custom-hook` is not wrapped the same way — a
+ * caller-supplied predicate owns its own timeout behavior, same as every
+ * other `Collector`-shaped callback contract in this repo (`collector.ts`'s
+ * own docs put "must resolve, not hang" on the implementer); imposing a
+ * surprise external cancellation on arbitrary caller code would be a
+ * different, larger decision than fixing the mechanisms that own a real OS
+ * resource this module can actually clean up.
+ */
+export declare const READINESS_MECHANISMS: readonly ["http", "tcp-port", "log-pattern", "command", "custom-hook"];
+export type ReadinessMechanism = (typeof READINESS_MECHANISMS)[number];
+export interface HttpReadinessCheck {
+    readonly kind: "http";
+    readonly url: string;
+    readonly expectedStatus?: number;
+}
+export interface TcpPortReadinessCheck {
+    readonly kind: "tcp-port";
+    readonly host: string;
+    readonly port: number;
+}
+export interface LogPatternReadinessCheck {
+    readonly kind: "log-pattern";
+    /**
+     * Tested against `read()`'s full return value on every poll (RT-032's
+     * `awaitReadiness` loop). `read` is documented to wire to
+     * `ManagedProcess.readOutput()`, which returns the entire accumulated
+     * stdout+stderr buffer with **no size cap** — a caller-supplied pattern
+     * with an unbounded quantifier immediately before a literal that can be
+     * absent (the exact shape RT-069 found and fixed in
+     * `evidence-store/redaction.ts`'s `EMAIL_PATTERN`, and RT-070 also found
+     * and fixed in this package's own `PORT_PLACEHOLDER`) would run that
+     * catastrophic-backtracking cost against a growing buffer on every single
+     * poll. Nothing in this repo currently supplies such a pattern here, so
+     * this is a disclosed risk at the call site rather than a fixed one — the
+     * regex is the caller's, not this module's, to bound.
+     */
+    readonly pattern: RegExp;
+    /** Pulls currently-buffered output — wire this to a ManagedProcess's `readOutput`. */
+    readonly read: () => string;
+}
+export interface CommandReadinessCheck {
+    readonly kind: "command";
+    readonly command: string;
+    readonly args?: readonly string[];
+    /** Defaults to this process's own `cwd` (`execFile`'s own default) when omitted. */
+    readonly cwd?: string;
+}
+export interface CustomHookReadinessCheck {
+    readonly kind: "custom-hook";
+    readonly check: () => Promise<boolean>;
+}
+export type ReadinessCheck = HttpReadinessCheck | TcpPortReadinessCheck | LogPatternReadinessCheck | CommandReadinessCheck | CustomHookReadinessCheck;
+export interface ReadinessResult {
+    readonly ready: boolean;
+    /** Which mechanism succeeded — null when none did within the timeout. */
+    readonly mechanism: ReadinessMechanism | null;
+    readonly elapsedMs: number;
+    readonly reason: string | null;
+}
+export interface AwaitReadinessOptions {
+    readonly timeoutMs: number;
+    readonly pollIntervalMs?: number;
+}
+export declare function awaitReadiness(checks: readonly ReadinessCheck[], options: AwaitReadinessOptions): Promise<ReadinessResult>;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../src/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAKH,eAAO,MAAM,oBAAoB,wEAAyE,CAAC;AAC3G,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,qBAAqB,GACrB,wBAAwB,GACxB,qBAAqB,GACrB,wBAAwB,CAAC;AAE7B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAID,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAwC1B"}