@descryy/runtime-controller 0.3.9 → 0.4.1

package/dist/process-manager.js

@@ -7,13 +7,21 @@
  * fixture-app slice (§34).
  */
 import { execFile, spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { closeSync, readSync, statSync } from "node:fs";
 import { createServer } from "node:net";
+import { resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
 import { promisify } from "node:util";
-import { applyResourceLimits } from "./execution-safety.js";
-import { applySandbox } from "./sandbox.js";
-import { applyContainerSandbox } from "./container-sandbox.js";
-import { computeAttachFence } from "./attach-fencing.js";
+import { applyResourceLimits, resourceLimitNotes } from "./execution-safety.js";
+import { applySandbox, NO_SANDBOX_DISCLOSURES } from "./sandbox.js";
+import { applyContainerSandbox, containerProcessEnv } from "./container-sandbox.js";
+import { computeAttachFence, getProcessStartTimeMs } from "./attach-fencing.js";
+import { openAttachLogFile, resolveAttachLogPath } from "./attach-log-file.js";
+import { buildChildEnvironment } from "./spawn-environment.js";
+import { assertTargetPid } from "./target-pid.js";
+import { liveDescendantPids } from "./process-identity.js";
+import { protectFromOrphaning } from "./orphan-reaper.js";
+import { BoundedOutput } from "./bounded-output.js";
 /**
  * Binds port 0, reads it, releases immediately. A real gap remains between "free
  * when checked" and "still free when the child binds it" (RT-024's gap, one layer
@@ -44,52 +52,38 @@ export function allocateEphemeralPort() {
     });
 }
 const DEFAULT_GRACE_PERIOD_MS = 5000;
-/**
- * RT-261: `outputBuffer += chunk` grew without bound for the process's whole
- * life -- a chatty service (or one stuck in a crash-log loop) grew Descry's
- * own memory, not the app's. Bounded to head + tail per service instead: the
- * first bytes usually carry the startup/config story, the last bytes carry
- * whatever just happened, and the (likely repetitive) middle is the part a
- * reader least needs verbatim. Starting values, not measurements.
- */
-const OUTPUT_HEAD_BYTES = 64 * 1024;
-const OUTPUT_TAIL_BYTES = 1024 * 1024;
-/** Marks the gap between head and tail; never confused with real process output because it names its own bound. */
-function truncationMarker(totalBytes, keptBytes) {
-    return `\n\n...[Descry truncated ${String(totalBytes - keptBytes)} of ${String(totalBytes)} bytes of output here -- head/tail kept, middle dropped]...\n\n`;
-}
+const GROUP_POLL_INTERVAL_MS = 25;
+const DOCKER_STOP_TIMEOUT_SLACK_MS = 10_000;
+const EXIT_DRAIN_TIMEOUT_MS = 2000;
 export function spawnProcess(options) {
     let startedAt = "";
     let exitedAt = null;
     let exitCode = null;
     let signal = null;
-    // Bounded head/tail buffer (RT-261) -- see OUTPUT_HEAD_BYTES/OUTPUT_TAIL_BYTES.
-    let headBuffer = "";
-    let tailBuffer = "";
-    let totalBytesSeen = 0;
-    let killStarted = false;
+    const output = new BoundedOutput();
+    let killInFlight = null;
+    let generation = 0;
     let child;
     let settled = false;
     // Set only for the container backend -- see kill() for why it needs a separate
     // stop mechanism from bwrap's group-kill.
     let containerName = null;
+    let sandboxDisclosures = NO_SANDBOX_DISCLOSURES;
+    let hostEnvironment = null;
+    let workloadInOwnPidNamespace = false;
+    let limitNotes = [];
     let resolveExit;
     let exitPromise;
-    // Everything a (re)spawn needs to reset, in one place -- construction and
-    // restart() must not drift into resetting different subsets of this state.
-    function spawnChild() {
-        startedAt = new Date().toISOString();
-        exitedAt = null;
-        exitCode = null;
-        signal = null;
-        headBuffer = "";
-        tailBuffer = "";
-        totalBytesSeen = 0;
-        killStarted = false;
-        settled = false;
-        exitPromise = new Promise((resolve) => {
-            resolveExit = resolve;
+    let releaseOrphanProtection = () => undefined;
+    function planLaunch() {
+        const cwd = options.cwd === undefined ? process.cwd() : resolve(options.cwd);
+        const childEnvironment = buildChildEnvironment({
+            declared: options.env ?? {},
+            ...(options.inheritHostEnvironment === undefined ? {} : { inheritHostEnvironment: options.inheritHostEnvironment }),
         });
+        if (options.filesystemPolicy !== undefined || options.networkPolicy !== undefined) {
+            assertSandboxPathsExist(cwd, options.filesystemPolicy);
+        }
         // "container" skips applyResourceLimits entirely (see SpawnProcessOptions.
         // sandboxBackend) -- "bwrap" (default) is unchanged.
         const wrapped = options.sandboxBackend === "container"
@@ -97,58 +91,118 @@ export function spawnProcess(options) {
                 interpreterCommand: options.command,
                 command: options.command,
                 args: options.args ?? [],
-                cwd: options.cwd ?? process.cwd(),
-                processEnv: { ...process.env, ...options.env },
+                cwd,
+                processEnv: containerProcessEnv(options.env),
+                ...(options.resourceLimits === undefined ? {} : { resourceLimits: options.resourceLimits }),
                 ...(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(),
+                cwd,
+                env: childEnvironment.env,
                 ...(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"],
+        return { wrapped, childEnvironment, cwd };
+    }
+    // Everything a (re)spawn needs to reset, in one place -- construction and
+    // restart() must not drift into resetting different subsets of this state.
+    function spawnChild() {
+        const { wrapped, childEnvironment, cwd } = planLaunch();
+        startedAt = new Date().toISOString();
+        exitedAt = null;
+        exitCode = null;
+        signal = null;
+        output.startNewEpoch();
+        killInFlight = null;
+        settled = false;
+        exitPromise = new Promise((resolveExitPromise) => {
+            resolveExit = resolveExitPromise;
         });
+        containerName = wrapped.containerName ?? null;
+        sandboxDisclosures = wrapped.sandboxDisclosures ?? NO_SANDBOX_DISCLOSURES;
+        hostEnvironment = childEnvironment.hostEnvironment;
+        workloadInOwnPidNamespace = wrapped.command === "bwrap";
+        limitNotes = options.sandboxBackend === "container" ? [] : resourceLimitNotes(options.resourceLimits);
+        try {
+            child = spawn(wrapped.command, [...wrapped.args], {
+                cwd,
+                env: { ...childEnvironment.env, ...wrapped.env },
+                detached: true,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            exitedAt = new Date().toISOString();
+            settled = true;
+            resolveExit({ exitCode: null, signal: null });
+            throw error;
+        }
+        releaseOrphanProtection = protectSpawned(child.pid, containerName);
         // Shared by both streams -- stdout/stderr are already interleaved into one
         // combined buffer (this module's existing contract), so head/tail bounding
         // applies to the combined stream, not per-fd.
-        function appendOutput(chunk) {
-            totalBytesSeen += chunk.length;
-            if (headBuffer.length < OUTPUT_HEAD_BYTES) {
-                headBuffer += chunk.toString("utf8");
-                if (headBuffer.length > OUTPUT_HEAD_BYTES) {
-                    headBuffer = headBuffer.slice(0, OUTPUT_HEAD_BYTES);
-                }
-            }
-            tailBuffer += chunk.toString("utf8");
-            if (tailBuffer.length > OUTPUT_TAIL_BYTES) {
-                tailBuffer = tailBuffer.slice(tailBuffer.length - OUTPUT_TAIL_BYTES);
-            }
+        function appendText(text) {
+            output.appendText(text);
+        }
+        const spawnedGeneration = ++generation;
+        function decodeInto(stream) {
+            if (stream === null)
+                return;
+            const decoder = new StringDecoder("utf8");
+            stream.on("data", (chunk) => {
+                if (spawnedGeneration !== generation)
+                    return;
+                output.countBytes(chunk.length);
+                appendText(decoder.write(chunk));
+            });
+            stream.on("end", () => {
+                if (spawnedGeneration !== generation)
+                    return;
+                appendText(decoder.end());
+            });
         }
-        child.stdout?.on("data", appendOutput);
-        child.stderr?.on("data", appendOutput);
+        decodeInto(child.stdout);
+        decodeInto(child.stderr);
         // A bad command (ENOENT) surfaces as an `'error'` event, not a thrown exception,
         // and per Node's docs `'exit'` may never fire after `'error'`. Both events settle
         // the same promise exactly once, so a failed spawn reads as an ordinary
         // never-became-ready process rather than crashing the caller or hanging cleanup.
-        function settle(info) {
-            if (settled)
+        let exitInfo = null;
+        let drainTimer;
+        function recordExit(info) {
+            if (exitInfo !== null)
                 return;
-            settled = true;
+            exitInfo = info;
             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 }));
+        function settle() {
+            if (settled || exitInfo === null)
+                return;
+            settled = true;
+            clearTimeout(drainTimer);
+            resolveExit(exitInfo);
+        }
+        const releaseThisSpawn = releaseOrphanProtection;
+        const spawnedPid = child.pid;
+        child.once("exit", (code, exitSignal) => {
+            recordExit({ exitCode: code, signal: exitSignal });
+            drainTimer = setTimeout(settle, EXIT_DRAIN_TIMEOUT_MS);
+            if (spawnedPid !== undefined && containerName === null && !isProcessGroupAlive(spawnedPid))
+                releaseThisSpawn();
+        });
+        child.once("close", (code, exitSignal) => {
+            recordExit({ exitCode: code, signal: exitSignal });
+            settle();
+        });
+        child.once("error", () => {
+            recordExit({ exitCode: null, signal: null });
+            settle();
+        });
     }
     spawnChild();
     function handle() {
@@ -164,16 +218,19 @@ export function spawnProcess(options) {
             port: options.port ?? null,
         };
     }
-    async function kill(gracePeriodMs = DEFAULT_GRACE_PERIOD_MS) {
-        if (killStarted || exitedAt !== null) {
-            await exitPromise;
-            return;
-        }
-        killStarted = true;
+    function kill(gracePeriodMs = DEFAULT_GRACE_PERIOD_MS) {
+        killInFlight ??= terminateGroup(gracePeriodMs);
+        return killInFlight;
+    }
+    async function terminateGroup(gracePeriodMs) {
         const pid = child.pid;
         if (pid === undefined) {
             return;
         }
+        if (exitedAt !== null && !isProcessGroupAlive(pid) && containerName === null) {
+            releaseOrphanProtection();
+            return;
+        }
         if (containerName !== null) {
             // Found via escape testing: the local `docker` CLI process is not the
             // container -- it runs under `dockerd`, a separate process tree.
@@ -181,17 +238,45 @@ export function spawnProcess(options) {
             // `docker stop` (by name) is the real stop mechanism here; `--rm` then
             // removes it. Still falls through to group-kill below as a CLI backstop.
             try {
-                await execFileAsync("docker", ["stop", "--time", String(Math.max(1, Math.round(gracePeriodMs / 1000))), containerName]);
+                await execFileAsync("docker", ["stop", "--time", String(Math.max(1, Math.round(gracePeriodMs / 1000))), containerName], {
+                    timeout: gracePeriodMs + DOCKER_STOP_TIMEOUT_SLACK_MS,
+                });
             }
             catch {
                 // Already stopped/removed -- not worth surfacing.
             }
         }
-        signalGroup(pid, "SIGTERM");
-        const exited = await Promise.race([exitPromise.then(() => true), sleep(gracePeriodMs).then(() => false)]);
-        if (!exited) {
+        requestGracefulStop(pid);
+        const groupGone = await waitForGroupToEmpty(pid, Date.now() + gracePeriodMs);
+        if (!groupGone) {
             signalGroup(pid, "SIGKILL");
-            await exitPromise;
+        }
+        await exitPromise;
+        releaseOrphanProtection();
+    }
+    function requestGracefulStop(pid) {
+        if (workloadInOwnPidNamespace) {
+            const descendants = liveDescendantPids(pid);
+            if (descendants.length > 0) {
+                for (const descendant of descendants)
+                    signalPid(descendant, "SIGTERM");
+                return;
+            }
+        }
+        signalGroup(pid, "SIGTERM");
+    }
+    async function waitForGroupToEmpty(pid, deadline) {
+        for (;;) {
+            if (exitedAt !== null && !isProcessGroupAlive(pid)) {
+                return true;
+            }
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) {
+                return false;
+            }
+            const tick = cancellableSleep(Math.min(GROUP_POLL_INTERVAL_MS, remainingMs));
+            await Promise.race([exitPromise, tick.done]);
+            tick.cancel();
         }
     }
     async function restart(gracePeriodMs = DEFAULT_GRACE_PERIOD_MS) {
@@ -202,27 +287,27 @@ export function spawnProcess(options) {
         spawnChild();
     }
     function readOutput() {
-        const droppedBytes = totalBytesSeen - headBuffer.length - tailBuffer.length;
-        if (droppedBytes <= 0) {
-            // No real gap yet -- tailBuffer alone already covers everything seen so
-            // far (headBuffer is a redundant prefix of it in this regime, since it
-            // hasn't been outgrown by the tail window sliding past it).
-            return tailBuffer;
-        }
-        return headBuffer + truncationMarker(totalBytesSeen, headBuffer.length + tailBuffer.length) + tailBuffer;
+        return output.read();
     }
     function outputInfo() {
-        return { totalBytesSeen, truncated: totalBytesSeen > headBuffer.length + tailBuffer.length };
+        return output.info();
+    }
+    function readOutputFrom(cursor) {
+        return output.readFrom(cursor);
     }
     return {
         handle,
         readOutput,
         outputInfo,
+        readOutputFrom,
         waitForExit: () => exitPromise,
         kill,
         restart,
         // A spawned process has no output that predates this runtime observing it.
         attachFence: () => null,
+        sandboxDisclosures: () => sandboxDisclosures,
+        hostEnvironment: () => hostEnvironment,
+        resourceLimitNotes: () => limitNotes,
     };
 }
 /**
@@ -234,6 +319,8 @@ export function spawnProcess(options) {
  * the reverse import would be circular. Tiny and pure enough to duplicate safely.
  */
 export function isProcessAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
     try {
         process.kill(pid, 0);
         return true;
@@ -243,10 +330,12 @@ export function isProcessAlive(pid) {
     }
 }
 const DEFAULT_ATTACH_POLL_INTERVAL_MS = 50;
+const ATTACH_READ_CHUNK_BYTES = 1024 * 1024;
+const ATTACH_START_TIME_TOLERANCE_MS = 2000;
 /**
- * `ManagedProcess` for a service attached to rather than spawned. Reads
- * `attach.logFilePath` fresh on every `readOutput()` -- same growing-whole-buffer
- * contract as a spawned process's in-memory pipe buffer.
+ * `ManagedProcess` for a service attached to rather than spawned. Tails
+ * `attach.logFilePath` from the last byte read into the same bounded head/tail
+ * buffer a spawned process uses, so a large log is read once, not on every poll.
  *
  * **`kill()` is a deliberate no-op, not a stub.** Descry did not spawn this process,
  * and `ATTACH_MODE_SCOPE_DISCLOSURE` is unconditional: attach mode never executes
@@ -268,23 +357,49 @@ const DEFAULT_ATTACH_POLL_INTERVAL_MS = 50;
  */
 export function attachManagedProcess(options) {
     const { pid, logFilePath } = options.attach;
+    assertTargetPid(pid, { allowOwnProcess: true });
     if (!isProcessAlive(pid)) {
         throw new Error(`attachManagedProcess: pid ${String(pid)} for "${options.processId}" is not running — attach requires ` +
             `a target that already exists.`);
     }
-    const fence = computeAttachFence(pid, logFilePath);
-    let maxObservedByteLength = fence.attachOffsetBytes;
+    if (logFilePath !== undefined) {
+        const resolution = resolveAttachLogPath(logFilePath);
+        if (!resolution.ok) {
+            throw new Error(`attachManagedProcess: log file refused for "${options.processId}": ${resolution.reason}`);
+        }
+    }
+    // H-attach-log-discovery: `logFilePath` is now optional -- absent means either
+    // a stream source was discovered instead (`options.attach.discoveredLogSource`,
+    // consumed by the orchestrator directly, never through this file-tail path) or
+    // nothing was found at all. Either way there is no file for RT-N3's fence to
+    // reason about, so `fence` is honestly `null` here, same as `spawnProcess`'s own
+    // "nothing predates observation" case -- `ManagedProcess.attachFence()` already
+    // admits `null` for exactly this.
+    const fence = logFilePath === undefined ? null : computeAttachFence(pid, logFilePath);
     const startedAt = new Date().toISOString();
+    const attachedStartTime = getProcessStartTimeMs(pid);
     let exitedAt = null;
     let exitPromise = null;
+    let observationEnded = false;
+    let pollTimer;
+    function targetStillRunning() {
+        if (!isProcessAlive(pid))
+            return false;
+        if (!attachedStartTime.ok)
+            return true;
+        const current = getProcessStartTimeMs(pid);
+        if (!current.ok)
+            return true;
+        return Math.abs(current.startTimeMs - attachedStartTime.startTimeMs) < ATTACH_START_TIME_TOLERANCE_MS;
+    }
     function handle() {
-        if (exitedAt === null && !isProcessAlive(pid)) {
+        if (exitedAt === null && !targetStillRunning()) {
             exitedAt = new Date().toISOString();
         }
         return {
             processId: options.processId,
             // No real command to report -- disclosed rather than guessed.
-            command: `<attached: pid ${String(pid)}, ${logFilePath}>`,
+            command: `<attached: pid ${String(pid)}${logFilePath === undefined ? "" : `, ${logFilePath}`}>`,
             pid,
             startedAt,
             exitedAt,
@@ -296,60 +411,115 @@ export function attachManagedProcess(options) {
             attached: true,
         };
     }
-    function readOutput() {
-        let content;
-        try {
-            content = readFileSync(logFilePath, "utf8");
+    const output = new BoundedOutput();
+    let fileOffset = fence?.backlogUnavailableReason === undefined ? 0 : fence.attachOffsetBytes;
+    let fileIdentity = null;
+    const decoder = new StringDecoder("utf8");
+    let chunk = null;
+    function pump() {
+        if (logFilePath === undefined)
+            return;
+        const opened = openAttachLogFile(logFilePath);
+        if (!opened.ok) {
+            throw new Error(`attachManagedProcess: could not read log file "${logFilePath}" for pid ${String(pid)}: ${opened.reason}`);
         }
-        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}`);
+        const { descriptor } = opened;
+        try {
+            const replaced = fileIdentity !== null && opened.inode !== fileIdentity;
+            if (opened.size < fileOffset || (replaced && fileOffset > 0)) {
+                throw new Error(`attachManagedProcess: log file "${logFilePath}" for pid ${String(pid)} shrank from ${String(fileOffset)} ` +
+                    `to ${String(opened.size)} bytes between reads -- this looks like log rotation or truncation, not new output. ` +
+                    "The file-tail contract can't reconstruct a rotated/truncated buffer without either duplicating or dropping " +
+                    `lines. Reported rather than guessed. (This run's own attach offset was ${String(fence?.attachOffsetBytes ?? 0)} bytes.)`);
+            }
+            fileIdentity = opened.inode;
+            chunk ??= Buffer.allocUnsafe(ATTACH_READ_CHUNK_BYTES);
+            while (fileOffset < opened.size) {
+                const read = readSync(descriptor, chunk, 0, Math.min(chunk.length, opened.size - fileOffset), fileOffset);
+                if (read === 0)
+                    break;
+                fileOffset += read;
+                output.countBytes(read);
+                output.appendText(decoder.write(chunk.subarray(0, read)));
+            }
         }
-        const byteLength = Buffer.byteLength(content, "utf8");
-        if (byteLength < maxObservedByteLength) {
-            throw new Error(`attachManagedProcess: log file "${logFilePath}" for pid ${String(pid)} shrank from ${String(maxObservedByteLength)} ` +
-                `to ${String(byteLength)} bytes between reads -- this looks like log rotation or truncation, not new output. ` +
-                "The file-tail contract can't reconstruct a rotated/truncated buffer without either duplicating or dropping " +
-                `lines. Reported rather than guessed. (This run's own attach offset was ${String(fence.attachOffsetBytes)} bytes.)`);
+        finally {
+            closeSync(descriptor);
         }
-        maxObservedByteLength = byteLength;
-        return content;
+    }
+    function readOutput() {
+        pump();
+        return output.read();
     }
     function waitForExit() {
-        exitPromise ??= new Promise((resolve) => {
+        exitPromise ??= new Promise((resolveExit) => {
             const poll = () => {
-                if (!isProcessAlive(pid)) {
+                pollTimer = undefined;
+                if (observationEnded)
+                    return;
+                if (!targetStillRunning()) {
                     exitedAt ??= new Date().toISOString();
-                    resolve({ exitCode: null, signal: null });
+                    resolveExit({ exitCode: null, signal: null });
                     return;
                 }
-                setTimeout(poll, DEFAULT_ATTACH_POLL_INTERVAL_MS);
+                pollTimer = setTimeout(poll, DEFAULT_ATTACH_POLL_INTERVAL_MS);
+                pollTimer.unref();
             };
             poll();
         });
         return exitPromise;
     }
     function kill() {
-        // Deliberate no-op -- see module doc above.
+        observationEnded = true;
+        if (pollTimer !== undefined) {
+            clearTimeout(pollTimer);
+            pollTimer = undefined;
+        }
         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.`));
     }
-    /**
-     * RT-261's head/tail bound is a spawnProcess concern -- this path re-reads
-     * `logFilePath` fresh on every call rather than accumulating a growing
-     * in-memory buffer, so there is nothing here for that bound to apply to.
-     * `truncated` stays honestly false; `totalBytesSeen` reports the real file
-     * size observed on the most recent read (0 before the first one).
-     */
     function outputInfo() {
-        return { totalBytesSeen: maxObservedByteLength, truncated: false };
+        return output.info();
     }
-    return { handle, readOutput, outputInfo, waitForExit, kill, restart, attachFence: () => fence };
+    function readOutputFrom(cursor) {
+        pump();
+        return output.readFrom(cursor);
+    }
+    return { handle, readOutput, outputInfo, readOutputFrom, waitForExit, kill, restart, attachFence: () => fence, sandboxDisclosures: () => NO_SANDBOX_DISCLOSURES };
 }
 const execFileAsync = promisify(execFile);
+function protectSpawned(pid, containerName) {
+    if (pid === undefined)
+        return () => undefined;
+    const releaseGroup = protectFromOrphaning({ kind: "group", pgid: pid });
+    if (containerName === null)
+        return releaseGroup;
+    const releaseContainer = protectFromOrphaning({ kind: "container", name: containerName });
+    return () => {
+        releaseGroup();
+        releaseContainer();
+    };
+}
+function assertSandboxPathsExist(cwd, filesystemPolicy) {
+    const required = [["working directory", cwd, true]];
+    for (const root of filesystemPolicy?.allowedRoots ?? [])
+        required.push(["allowed root", root, false]);
+    for (const [role, path, mustBeDirectory] of required) {
+        let isDirectory = false;
+        try {
+            isDirectory = statSync(path).isDirectory();
+        }
+        catch (error) {
+            const detail = error.code === "ENOENT" ? "does not exist" : `could not be inspected (${error instanceof Error ? error.message : String(error)})`;
+            throw new Error(`sandbox refused: ${role} ${path} ${detail}`);
+        }
+        if (mustBeDirectory && !isDirectory)
+            throw new Error(`sandbox refused: ${role} ${path} is not a directory`);
+    }
+}
 function signalGroup(pid, signal) {
     try {
         // Negative pid targets the whole process group (orphan-prevention mechanism).
@@ -359,7 +529,28 @@ function signalGroup(pid, signal) {
         // Group already gone -- not an error.
     }
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function signalPid(pid, signal) {
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        return;
+    }
+}
+function isProcessGroupAlive(pgid) {
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function cancellableSleep(ms) {
+    let timer;
+    const done = new Promise((resolve) => {
+        timer = setTimeout(resolve, ms);
+    });
+    return { done, cancel: () => clearTimeout(timer) };
 }
 //# sourceMappingURL=process-manager.js.map