@descryy/runtime-orchestrator 0.0.0

package/dist/respawn-and-supervise.js

@@ -0,0 +1,212 @@
+/**
+ * Respawn-and-supervise: a real, separate execution mode next to attach
+ * mode, not a change to attach mode itself.
+ *
+ * **The tradeoff this makes, stated up front, because it must never be
+ * applied silently.** Attach mode (`attach-to-running-process.ts` and its
+ * siblings) reaches a process that was already running, unconfined, before
+ * Descry touched it -- `sandbox.ts`'s own module doc (`@descryhq-wq/runtime-
+ * controller`) says plainly there is no honest way to retroactively contain
+ * that process. This module does not try. It kills the attached target and
+ * spawns a fresh, equivalent process through the EXISTING `spawnProcess()`
+ * (`@descryy/runtime-controller`), which already gets full sandboxing
+ * (`applySandbox`, `applyResourceLimits`) for anything it spawns -- the same
+ * mechanism `ExecutionController.run()` uses, not a parallel one. The price
+ * is real: in-memory state, open connections, anything the old process held
+ * that was never persisted is gone the moment it is killed. A caller must
+ * choose this explicitly; nothing in this repo switches a running attach
+ * into a respawn on its own.
+ *
+ * **How this module learns what to respawn -- the design question this
+ * lane was told not to guess past.** This repo has a standing, named
+ * precedent for exactly this shape of question: RT-032 ("declared, never
+ * inferred" -- `ServiceConfiguration.dependsOn`, `substitutePortPlaceholders`,
+ * `discoverRunner`'s refusal to sniff a test framework from `package.json`).
+ * The caller-declared path (`RespawnCommand` with `source: "caller-declared"`)
+ * is the one this module recommends and the only one its own convenience
+ * default reaches for. A `/proc/<pid>/cmdline` readback (Linux-only, and
+ * genuinely insufficient on its own -- it cannot recover env vars set
+ * programmatically before `exec`, file descriptors already open and handed
+ * off, or a cwd that changed after launch) is real, but explicitly a
+ * best-effort convenience, never the default: `inferRespawnCommandFromProc`
+ * exists, is opt-in, and labels its own output `source: "proc-cmdline-
+ * inferred"` so nothing downstream can mistake an inference for a
+ * declaration. The two are never blurred into one shape.
+ *
+ * **Killing the old process.** `respawnAndSupervise` does not assume it owns
+ * the target's process group -- an attached-to process was not spawned by
+ * this runtime and may not even be its own group leader, so this signals
+ * the individual pid only (SIGTERM, then SIGKILL after `gracePeriodMs` if
+ * still alive), mirroring `process-manager.ts`'s own two-stage `kill()`
+ * without reusing its group-kill (`signalGroup`), which is `spawnProcess`'s
+ * own escape hatch for a group *it* created.
+ */
+import { spawnProcess } from "@descryy/runtime-controller";
+import { readFileSync, readlinkSync } from "node:fs";
+import { isProcessAlive } from "./attach-to-running-process.js";
+const DEFAULT_GRACE_PERIOD_MS = 5000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Waits until `isProcessAlive(pid)` is false or `deadlineMs` elapses.
+ * Returns whether the process was confirmed dead.
+ */
+async function waitForDeath(pid, deadlineMs) {
+    const deadline = Date.now() + deadlineMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid))
+            return true;
+        await sleep(20);
+    }
+    return !isProcessAlive(pid);
+}
+/**
+ * Kills `pid` directly (not its process group -- see this module's own doc
+ * for why), escalating from SIGTERM to SIGKILL after `gracePeriodMs`.
+ * Resolves once the pid is confirmed dead, or throws if it survives even
+ * SIGKILL (a defunct-but-unreapable zombie owned by another process tree,
+ * or a permission boundary this caller's uid cannot cross) -- refusing to
+ * report success it did not actually observe, the same discipline
+ * `ManagedProcess.kill()` already holds for processes this runtime spawned
+ * itself.
+ */
+async function killTarget(pid, gracePeriodMs) {
+    if (!isProcessAlive(pid))
+        return { killedViaSigkill: false };
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        // Already gone between the isProcessAlive check and this signal -- a
+        // real, if narrow, race; fall through to the death check below rather
+        // than treating a caught error here as failure.
+    }
+    if (await waitForDeath(pid, gracePeriodMs))
+        return { killedViaSigkill: false };
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        // Same race, at the SIGKILL stage.
+    }
+    const dead = await waitForDeath(pid, Math.max(gracePeriodMs, 2000));
+    if (!dead) {
+        throw new Error(`respawnAndSupervise: pid ${String(pid)} did not exit even after SIGKILL -- refusing to report a kill that was not observed. ` +
+            "This can happen for a zombie this process cannot reap (owned by a different parent) or a permission boundary this caller's uid cannot cross.");
+    }
+    return { killedViaSigkill: true };
+}
+/**
+ * Kills the process at `options.targetPid` and spawns a fresh, supervised,
+ * (optionally) sandboxed replacement via `spawnProcess()`.
+ *
+ * **Not a silent behavior change to attach mode.** A caller reaches this
+ * function by name, explicitly, instead of one of the `attachToRunning*`
+ * functions -- there is no code path in this repo that upgrades an attach
+ * into a respawn on its own. `ATTACH_MODE_SCOPE_DISCLOSURE`
+ * (`@descryy/runtime-controller`) still governs attach mode itself,
+ * unconditionally, whether or not a caller ever reaches for this
+ * alternative.
+ *
+ * Throws (does not silently proceed) if `targetPid` is not alive at call
+ * time, matching `attachToRunningProcess`'s own "refuse rather than operate
+ * on a target that does not exist" contract.
+ */
+export async function respawnAndSupervise(options) {
+    if (!isProcessAlive(options.targetPid)) {
+        throw new Error(`respawnAndSupervise: pid ${String(options.targetPid)} for "${options.processId}" is not running -- ` +
+            "respawn-and-supervise requires a target that already exists, the same as attach mode does.");
+    }
+    const { killedViaSigkill } = await killTarget(options.targetPid, options.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS);
+    const managedProcess = spawnProcess({
+        processId: options.processId,
+        command: options.respawn.command,
+        args: options.respawn.args ?? [],
+        cwd: options.respawn.cwd,
+        ...(options.respawn.env === undefined ? {} : { env: options.respawn.env }),
+        ...(options.serviceName === undefined ? {} : { serviceName: options.serviceName }),
+        ...(options.port === undefined ? {} : { port: options.port }),
+        ...(options.resourceLimits === undefined ? {} : { resourceLimits: options.resourceLimits }),
+        ...(options.filesystemPolicy === undefined ? {} : { filesystemPolicy: options.filesystemPolicy }),
+        ...(options.networkPolicy === undefined ? {} : { networkPolicy: options.networkPolicy }),
+    });
+    return {
+        managedProcess,
+        killedPid: options.targetPid,
+        killedViaSigkill,
+        respawnSource: options.respawn.source,
+    };
+}
+/**
+ * The opt-in, disclosed, BEST-EFFORT convenience this module's own doc
+ * names -- never the default `respawnAndSupervise` reaches for on its own.
+ * Reads `/proc/<pid>/cmdline`, `/proc/<pid>/cwd` and `/proc/<pid>/environ`
+ * to reconstruct a `RespawnCommand`, labelling it `source:
+ * "proc-cmdline-inferred"` so it can never be mistaken for a caller
+ * declaration downstream.
+ *
+ * **Real, disclosed limitations, not hypothetical ones:** Linux-only (no
+ * `/proc` on macOS/Windows); env vars a process set on itself
+ * programmatically after `exec` (as opposed to what it was launched with)
+ * are invisible here, because `/proc/<pid>/environ` only ever reflects the
+ * environment at `execve()` time; already-open file descriptors handed to
+ * the original process (an inherited socket, a pipe from its own parent)
+ * have no representation in a command line at all and cannot be recovered
+ * by any means this function has. Returns `null` -- never throws, never
+ * guesses a partial answer -- when `/proc/<pid>/cmdline` cannot be read
+ * (platform mismatch, pid gone, permission denied) or is empty.
+ */
+export function inferRespawnCommandFromProc(pid, platform = process.platform) {
+    if (platform !== "linux")
+        return null;
+    let cmdlineRaw;
+    try {
+        cmdlineRaw = readFileSync(`/proc/${String(pid)}/cmdline`, "utf8");
+    }
+    catch {
+        return null;
+    }
+    // /proc/<pid>/cmdline is NUL-separated, with a trailing NUL -- split and
+    // drop the empty tail entry it always produces.
+    const parts = cmdlineRaw.split("\0").filter((part) => part !== "");
+    if (parts.length === 0)
+        return null;
+    const [command, ...args] = parts;
+    if (command === undefined)
+        return null;
+    let cwd;
+    try {
+        cwd = readlinkSync(`/proc/${String(pid)}/cwd`);
+    }
+    catch {
+        return null;
+    }
+    let env;
+    try {
+        const environRaw = readFileSync(`/proc/${String(pid)}/environ`, "utf8");
+        env = {};
+        for (const entry of environRaw.split("\0").filter((part) => part !== "")) {
+            const eq = entry.indexOf("=");
+            if (eq === -1)
+                continue;
+            env[entry.slice(0, eq)] = entry.slice(eq + 1);
+        }
+    }
+    catch {
+        // /proc/<pid>/environ is real but commonly permission-denied for a
+        // process owned by a different uid, even when cmdline/cwd were
+        // readable -- degrades to no env recovered rather than failing the
+        // whole inference, since command/args/cwd alone are still a real,
+        // usable (if incomplete) answer.
+        env = undefined;
+    }
+    return {
+        command,
+        args,
+        cwd,
+        ...(env === undefined ? {} : { env }),
+        source: "proc-cmdline-inferred",
+    };
+}
+//# sourceMappingURL=respawn-and-supervise.js.map

package/dist/respawn-and-supervise.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@descryy/runtime-orchestrator",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Assembles the runtime: controller-spawned services, live process output, collectors from a RuntimeAdapter, and a CollectorContext that can resolve script origins to source roots.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@descryy/runtime-contracts": "0.0.0",
+    "@descryy/runtime-backend-observation": "0.0.0",
+    "@descryy/runtime-controller": "0.0.0",
+    "@descryy/runtime-evidence-store": "0.0.0",
+    "@descryy/runtime-adapter-typescript": "0.0.0",
+    "@descryy/runtime-environment-profile": "0.0.0",
+    "@descryhq-wq/runtime-remote-log-ingestion": "0.0.0"
+  },
+  "devDependencies": {
+    "@descryhq-wq/runtime-adapter-csharp": "*",
+    "@descryhq-wq/runtime-adapter-go": "*",
+    "@descryhq-wq/runtime-adapter-jvm": "*",
+    "@descryhq-wq/runtime-adapter-php": "*",
+    "@descryhq-wq/runtime-adapter-python": "*",
+    "@descryhq-wq/runtime-adapter-ruby": "*",
+    "@descryhq-wq/runtime-adapter-rust": "*",
+    "@descryhq-wq/runtime-adapter-swift": "*"
+  }
+}