@descryy/runtime-orchestrator 0.4.9 → 0.4.10

package/dist/respawn-and-supervise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"respawn-and-supervise.d.ts","sourceRoot":"","sources":["../src/respawn-and-supervise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAgB,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAI1G,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,uBAAuB,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oGAAoG;IACpG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qHAAqH;IACrH,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,uIAAuI;IACvI,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAChE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IACpE,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,CAAC,eAAe,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,yBAAyB;IACxC,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6KAA6K;IAC7K,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;CAC9C;AAmDD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA6BjH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,cAAc,GAAG,IAAI,CA4C5H"}

package/dist/respawn-and-supervise.js

@@ -0,0 +1,171 @@
+/**
+ * Respawn-and-supervise: a separate execution mode next to attach mode, not a
+ * change to attach mode itself.
+ *
+ * **The tradeoff, stated up front — must never apply silently.** Attach mode
+ * reaches an already-running, unconfined process; there is no honest way to
+ * retroactively sandbox it (`sandbox.ts`). This module doesn't try — it kills the
+ * attached target and spawns a fresh equivalent via the existing `spawnProcess()`,
+ * which gets full sandboxing for anything it spawns. Price: in-memory state, open
+ * connections, anything unpersisted is gone the moment the old process is killed.
+ * A caller must choose this explicitly — nothing upgrades an attach into a respawn
+ * on its own.
+ *
+ * **How this learns what to respawn.** Follows RT-032's "declared, never inferred"
+ * precedent: caller-declared (`source: "caller-declared"`) is the recommended,
+ * default path. `/proc/<pid>/cmdline` readback is a real but best-effort,
+ * opt-in-only fallback (`inferRespawnCommandFromProc`), labelled `source:
+ * "proc-cmdline-inferred"` so it's never mistaken for a declaration.
+ *
+ * **Killing the old process.** Doesn't assume ownership of the target's process
+ * group — it may not even be its own group leader — so this signals the individual
+ * pid only (SIGTERM, then SIGKILL after `gracePeriodMs`), not `spawnProcess`'s
+ * group-kill escape hatch (`signalGroup`), which is only valid for a group it
+ * created itself.
+ */
+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 file header), escalating
+ * SIGTERM to SIGKILL after `gracePeriodMs`. Throws if it survives even SIGKILL
+ * (unreapable zombie, or a permission boundary) rather than reporting an unobserved
+ * success.
+ */
+async function killTarget(pid, gracePeriodMs) {
+    if (!isProcessAlive(pid))
+        return { killedViaSigkill: false };
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        // race: already gone between the isProcessAlive check and this signal
+    }
+    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 — reached only by explicit call,
+ * never an automatic upgrade path. `ATTACH_MODE_SCOPE_DISCLOSURE` still governs
+ * attach mode itself regardless.
+ *
+ * Throws if `targetPid` isn't alive at call time, matching `attachToRunningProcess`'s
+ * refuse-rather-than-operate-on-nonexistent-target 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,
+    };
+}
+/**
+ * Opt-in, best-effort convenience — never the default. Reads `/proc/<pid>/cmdline`,
+ * `/cwd` and `/environ` to reconstruct a `RespawnCommand`, labelled `source:
+ * "proc-cmdline-inferred"` so it's never mistaken for a caller declaration.
+ *
+ * Disclosed limitations: Linux-only; `/proc/<pid>/environ` reflects only the
+ * environment at `execve()` time, so env vars set programmatically after exec are
+ * invisible; already-open file descriptors (inherited sockets/pipes) have no
+ * command-line representation and can't be recovered. Returns `null` — never
+ * throws, never guesses partially — when cmdline can't be read 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;
+    }
+    // NUL-separated with a trailing NUL; drop the empty tail entry
+    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 {
+        // environ is commonly permission-denied across uids even when cmdline/cwd
+        // are readable; degrade to no env rather than failing the whole inference
+        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

@@ -1,6 +1,6 @@
 {
   "name": "@descryy/runtime-orchestrator",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "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",
@@ -28,7 +28,7 @@
   "dependencies": {
     "@descryy/runtime-contracts": "0.3.3",
     "@descryy/runtime-backend-observation": "0.3.6",
-    "@descryy/runtime-controller": "0.3.8",
+    "@descryy/runtime-controller": "0.3.9",
     "@descryy/runtime-evidence-store": "0.4.2",
     "@descryy/runtime-adapter-typescript": "0.3.7",
     "@descryy/runtime-environment-profile": "0.4.5",