@descryy/runtime-orchestrator 0.0.0

package/dist/cdp-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-client.js","sourceRoot":"","sources":["../src/cdp-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAgBH;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,YAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,aAAa,EAAE,EAAE;QACnD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,YAAY,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;QAChD,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0D,CAAC;QACpF,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,SAAS,cAAc,CAAC,KAAY;YAClC,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,OAAO,CAAC,MAAM,EAAE;gBAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;QAED,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE;YACnC,OAAO,GAAG,IAAI,CAAC;YACf,cAAc,CAAC;gBACb,IAAI,CAAI,MAAc,EAAE,SAAkC,EAAE;oBAC1D,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;oBACpB,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;wBACxC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAmC,EAAE,MAAM,EAAE,CAAC,CAAC;wBAC1E,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;oBACtD,CAAC,CAAC,CAAC;gBACL,CAAC;gBACD,EAAE,CAAC,MAAc,EAAE,OAAkD;oBACnE,IAAI,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBAChC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;wBACtB,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;wBAChB,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;oBAC7B,CAAC;oBACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;oBACjB,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACnC,CAAC;gBACD,KAAK;oBACH,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,CAAC;aACF,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAmB,EAAE,EAAE;YACzD,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC7E,IAAI,GAAsH,CAAC;YAC3H,IAAI,CAAC;gBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;gBACjE,kEAAkE;gBAClE,wDAAwD;gBACxD,2DAA2D;gBAC3D,OAAO;YACT,CAAC;YAED,IAAI,GAAG,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACpC,IAAI,OAAO,KAAK,SAAS;oBAAE,OAAO;gBAClC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACvB,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;oBAC5B,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;gBAC7F,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC9B,CAAC;gBACD,OAAO;YACT,CAAC;YAED,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACtC,IAAI,GAAG,KAAK,SAAS;oBAAE,OAAO;gBAC9B,KAAK,MAAM,OAAO,IAAI,GAAG;oBAAE,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;YACvD,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;YACpC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,qCAAqC,YAAY,EAAE,CAAC,CAAC;YAC7E,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC;gBACf,aAAa,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC;YACD,cAAc,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;YACpC,cAAc,CAAC,IAAI,KAAK,CAAC,oBAAoB,YAAY,SAAS,CAAC,CAAC,CAAC;QACvE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cgroup-partial-restriction.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Partial going-forward resource restriction for an already-running,
+ * attached-to process, via cgroups v2 -- the second, narrower alternative
+ * next to respawn-and-supervise (`respawn-and-supervise.ts`).
+ *
+ * **What this genuinely gets you, stated exactly, because the honest
+ * boundary here is not the same shape as spawn-mode's.** Moving a live
+ * pid's cgroup membership (writing it into a delegated cgroup's own
+ * `cgroup.procs`, per the kernel's cgroups v2 unified hierarchy) applies
+ * real, kernel-enforced resource limits -- `memory.max`, `cpu.max`,
+ * `pids.max` -- to a process this runtime never spawned, without killing
+ * or restarting it. That is real and this module proves it for real (see
+ * the test suite). **It does NOT, and structurally cannot, give the moved
+ * process any filesystem or network isolation.** Changing which mount or
+ * network namespace an already-running process belongs to needs `setns()`
+ * against a live pid -- a fundamentally different, far more invasive
+ * operation than a cgroup move, not attempted here and out of scope for
+ * this pass. Every value this module returns, and every place this
+ * capability is described, says so: `CGROUP_PARTIAL_RESTRICTION_SCOPE`
+ * below is the literal, load-bearing string every result carries, precisely
+ * so nothing downstream can round it up to "sandboxed" or "isolated" --
+ * words that would misrepresent this as equivalent to `sandbox.ts`'s real
+ * spawn-time bwrap isolation.
+ *
+ * **How the delegated cgroup is found -- measured on this host, not
+ * assumed from cgroups v2 documentation.** A non-root user cannot write
+ * anywhere under `/sys/fs/cgroup` by default; what makes any of this
+ * possible at all is a systemd user session's own delegation
+ * (`user@<uid>.service`, `Delegate=yes`), which typically extends through
+ * `app.slice`/`session.slice`/`background.slice` beneath it. But
+ * delegation is not uniform all the way down: cgroups v2's "no internal
+ * processes" rule means a *leaf* cgroup that already directly holds a
+ * process (a systemd `.scope`, including the very one this Node process
+ * itself runs in) generally cannot have its `subtree_control` extended
+ * further -- writing to it fails with `EBUSY`, measured directly against
+ * this repo's own dev host while building this module. `findDelegatedCgroupAncestor`
+ * therefore does not trust `cgroup.subtree_control` text or permission
+ * bits alone; it walks up from this process's own `/proc/self/cgroup` path
+ * and, at each ancestor, creates a real, temporary probe child directory
+ * and checks whether the kernel actually gave it a `memory.max` file --
+ * the only way to honestly know a given ancestor's delegation reaches that
+ * far, empirically, the same "prove it against the real mechanism" standard
+ * `sandbox.ts`'s own escape tests hold spawn-mode isolation to.
+ */
+import type { CapabilityStatus } from "@descryy/runtime-contracts";
+/**
+ * The literal, load-bearing scope string. Every `CgroupMoveResult` carries
+ * this exact value under `scope` -- never restated by hand elsewhere, so a
+ * caller (or a future capability-report string, or a decisions-inbox entry)
+ * that quotes `.scope` can never accidentally drift from this wording.
+ */
+export declare const CGROUP_PARTIAL_RESTRICTION_SCOPE: "partial -- resource limits only, no filesystem or network isolation";
+/**
+ * Walks up from this process's own cgroup toward `/sys/fs/cgroup`, returning
+ * the deepest (most specific) ancestor directory whose children genuinely
+ * get a real `memory.max` -- i.e. the actual delegation boundary, not
+ * merely a directory this uid happens to own. `null` when cgroups v2 is not
+ * mounted, this process's own cgroup path cannot be determined, or no
+ * ancestor all the way to the root passes the probe (no delegation at all).
+ */
+export declare function findDelegatedCgroupAncestor(): string | null;
+export declare function cgroupV2Capability(): CapabilityStatus;
+export interface CgroupResourceLimits {
+    /**
+     * Maps to cgroups v2 `memory.max`, in bytes. **Also writes `memory.swap.max=0`
+     * for the same cgroup, deliberately, when this is set** -- measured directly
+     * while building this module: with swap available on the host (the common
+     * case), `memory.max` alone does not kill anything, it just makes the
+     * kernel push the cgroup's pages to swap under pressure, so a caller
+     * declaring a memory cap would silently get "slows down and swaps"
+     * instead of the real, hard boundary the field name promises. Disabling
+     * swap for the created cgroup is what makes `memory.max` an actual
+     * enforced limit (the kernel's own cgroup-aware OOM killer terminates a
+     * process here, SIGKILL, once reclaim genuinely cannot bring usage under
+     * the cap) rather than a soft one. Not independently toggleable in this
+     * pass -- if a future caller genuinely wants "cap it but let it swap,"
+     * that is a real, separate field to add later, not silently assumed here.
+     */
+    readonly memoryMaxBytes?: number;
+    /** Maps to cgroups v2 `pids.max` -- caps the number of tasks (processes/threads) this cgroup may hold at once. */
+    readonly maxProcesses?: number;
+    /**
+     * Raw cgroups v2 `cpu.max` value (`"$MAX $PERIOD"`, e.g. `"50000 100000"`
+     * for 50% of one CPU). Declaring this when the delegated ancestor does
+     * not actually expose a writable `cpu.max` to its children is a refusal
+     * (throws), not a silently-dropped limit -- matching `applySandbox`'s own
+     * "declared, refused rather than silently ignored if unenforceable"
+     * precedent. Measured on this repo's own dev host: `cpu` was NOT
+     * delegated at the same level `memory`/`pids` were, so this is a real,
+     * not hypothetical, gap a caller can hit.
+     */
+    readonly cpuMax?: string;
+}
+export interface CgroupMoveResult {
+    readonly applied: true;
+    readonly cgroupPath: string;
+    /** Always the literal `CGROUP_PARTIAL_RESTRICTION_SCOPE` string -- see its own doc for why this is never restated by hand. */
+    readonly scope: typeof CGROUP_PARTIAL_RESTRICTION_SCOPE;
+    readonly appliedLimits: CgroupResourceLimits;
+    /**
+     * Best-effort removal of the cgroup this call created. Succeeds only once
+     * `cgroup.procs` is empty -- the pid exited, or was itself moved
+     * elsewhere -- because cgroups v2 refuses to remove a non-empty cgroup,
+     * the same "no internal processes hiding a live one" rule
+     * `findDelegatedCgroupAncestor`'s own probe relies on. Returns whether
+     * removal actually happened; never throws.
+     */
+    readonly release: () => boolean;
+}
+/**
+ * Moves `options.pid` -- an already-running process this runtime did not
+ * spawn -- into a newly created, resource-limited cgroup. Throws (does not
+ * silently proceed) when the target is not alive, when `cgroupV2Capability()`
+ * reports unavailable, or when a declared limit's controller file does not
+ * actually exist under the delegated ancestor found for it.
+ *
+ * Limits are written to the new cgroup BEFORE the pid is moved into it, so
+ * a process is never observed inside a cgroup with a half-applied limit
+ * set; if any write fails, the created (still-empty) cgroup is removed and
+ * the error is rethrown rather than left as an orphaned, unlimited group.
+ */
+export declare function moveProcessIntoRestrictedCgroup(options: {
+    readonly pid: number;
+    readonly limits: CgroupResourceLimits;
+    readonly nameHint?: string;
+}): CgroupMoveResult;
+//# sourceMappingURL=cgroup-partial-restriction.d.ts.map

package/dist/cgroup-partial-restriction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cgroup-partial-restriction.d.ts","sourceRoot":"","sources":["../src/cgroup-partial-restriction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAKnE;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,EAAG,qEAA8E,CAAC;AAkD/H;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,IAAI,CAiB3D;AAED,wBAAgB,kBAAkB,IAAI,gBAAgB,CAkBrD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,kHAAkH;IAClH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8HAA8H;IAC9H,QAAQ,CAAC,KAAK,EAAE,OAAO,gCAAgC,CAAC;IACxD,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,gBAAgB,CA2EnB"}

package/dist/cgroup-partial-restriction.js

@@ -0,0 +1,236 @@
+/**
+ * Partial going-forward resource restriction for an already-running,
+ * attached-to process, via cgroups v2 -- the second, narrower alternative
+ * next to respawn-and-supervise (`respawn-and-supervise.ts`).
+ *
+ * **What this genuinely gets you, stated exactly, because the honest
+ * boundary here is not the same shape as spawn-mode's.** Moving a live
+ * pid's cgroup membership (writing it into a delegated cgroup's own
+ * `cgroup.procs`, per the kernel's cgroups v2 unified hierarchy) applies
+ * real, kernel-enforced resource limits -- `memory.max`, `cpu.max`,
+ * `pids.max` -- to a process this runtime never spawned, without killing
+ * or restarting it. That is real and this module proves it for real (see
+ * the test suite). **It does NOT, and structurally cannot, give the moved
+ * process any filesystem or network isolation.** Changing which mount or
+ * network namespace an already-running process belongs to needs `setns()`
+ * against a live pid -- a fundamentally different, far more invasive
+ * operation than a cgroup move, not attempted here and out of scope for
+ * this pass. Every value this module returns, and every place this
+ * capability is described, says so: `CGROUP_PARTIAL_RESTRICTION_SCOPE`
+ * below is the literal, load-bearing string every result carries, precisely
+ * so nothing downstream can round it up to "sandboxed" or "isolated" --
+ * words that would misrepresent this as equivalent to `sandbox.ts`'s real
+ * spawn-time bwrap isolation.
+ *
+ * **How the delegated cgroup is found -- measured on this host, not
+ * assumed from cgroups v2 documentation.** A non-root user cannot write
+ * anywhere under `/sys/fs/cgroup` by default; what makes any of this
+ * possible at all is a systemd user session's own delegation
+ * (`user@<uid>.service`, `Delegate=yes`), which typically extends through
+ * `app.slice`/`session.slice`/`background.slice` beneath it. But
+ * delegation is not uniform all the way down: cgroups v2's "no internal
+ * processes" rule means a *leaf* cgroup that already directly holds a
+ * process (a systemd `.scope`, including the very one this Node process
+ * itself runs in) generally cannot have its `subtree_control` extended
+ * further -- writing to it fails with `EBUSY`, measured directly against
+ * this repo's own dev host while building this module. `findDelegatedCgroupAncestor`
+ * therefore does not trust `cgroup.subtree_control` text or permission
+ * bits alone; it walks up from this process's own `/proc/self/cgroup` path
+ * and, at each ancestor, creates a real, temporary probe child directory
+ * and checks whether the kernel actually gave it a `memory.max` file --
+ * the only way to honestly know a given ancestor's delegation reaches that
+ * far, empirically, the same "prove it against the real mechanism" standard
+ * `sandbox.ts`'s own escape tests hold spawn-mode isolation to.
+ */
+import { existsSync, mkdirSync, readFileSync, rmdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isProcessAlive } from "./attach-to-running-process.js";
+const CGROUP_ROOT = "/sys/fs/cgroup";
+/**
+ * The literal, load-bearing scope string. Every `CgroupMoveResult` carries
+ * this exact value under `scope` -- never restated by hand elsewhere, so a
+ * caller (or a future capability-report string, or a decisions-inbox entry)
+ * that quotes `.scope` can never accidentally drift from this wording.
+ */
+export const CGROUP_PARTIAL_RESTRICTION_SCOPE = "partial -- resource limits only, no filesystem or network isolation";
+function ownUnifiedCgroupPath() {
+    let content;
+    try {
+        content = readFileSync("/proc/self/cgroup", "utf8");
+    }
+    catch {
+        return null;
+    }
+    for (const line of content.trim().split("\n")) {
+        // cgroups v2 unified-hierarchy lines read "0::<path>" -- hierarchy id 0,
+        // no named controllers (that's a v1 concept), then the path. A host
+        // still running v1 controllers alongside v2 has other numbered lines
+        // here too; only the "0::" one is this module's concern.
+        const firstColon = line.indexOf(":");
+        const secondColon = line.indexOf(":", firstColon + 1);
+        if (firstColon === -1 || secondColon === -1)
+            continue;
+        if (line.slice(0, firstColon) === "0" && firstColon + 1 === secondColon) {
+            return line.slice(secondColon + 1);
+        }
+    }
+    return null;
+}
+/**
+ * Real, empirical probe -- not a permission-bit read. See this module's own
+ * doc for why: a directory can be `mkdir`-able yet still produce a child
+ * with no `memory.max` at all, when the controller was never actually
+ * enabled in that parent's own `cgroup.subtree_control` (this process's own
+ * leaf scope is exactly this shape, measured directly). The only honest
+ * test is creating a real probe child and checking what the kernel actually
+ * gave it.
+ */
+function probeControllableChild(candidateDir) {
+    const probe = join(candidateDir, `.descry-cgroup-probe-${String(process.pid)}-${String(Date.now())}-${String(Math.random()).slice(2, 8)}`);
+    try {
+        mkdirSync(probe);
+    }
+    catch {
+        return false;
+    }
+    const controllable = existsSync(join(probe, "memory.max"));
+    try {
+        rmdirSync(probe);
+    }
+    catch {
+        // Best-effort cleanup of our own just-created probe directory -- not
+        // this module's problem if something else raced to touch it first.
+    }
+    return controllable;
+}
+/**
+ * Walks up from this process's own cgroup toward `/sys/fs/cgroup`, returning
+ * the deepest (most specific) ancestor directory whose children genuinely
+ * get a real `memory.max` -- i.e. the actual delegation boundary, not
+ * merely a directory this uid happens to own. `null` when cgroups v2 is not
+ * mounted, this process's own cgroup path cannot be determined, or no
+ * ancestor all the way to the root passes the probe (no delegation at all).
+ */
+export function findDelegatedCgroupAncestor() {
+    if (process.platform !== "linux")
+        return null;
+    if (!existsSync(join(CGROUP_ROOT, "cgroup.controllers")))
+        return null;
+    const ownPath = ownUnifiedCgroupPath();
+    if (ownPath === null)
+        return null;
+    let dir = join(CGROUP_ROOT, ownPath.replace(/^\/+/, ""));
+    // Walk strictly upward, never testing CGROUP_ROOT itself -- writing
+    // limits at the true root would apply host-wide and is root-only on
+    // every real system anyway, so it is deliberately excluded rather than
+    // reached as a fallback.
+    while (dir !== CGROUP_ROOT && dirname(dir) !== dir) {
+        if (existsSync(dir) && probeControllableChild(dir))
+            return dir;
+        dir = dirname(dir);
+    }
+    return null;
+}
+export function cgroupV2Capability() {
+    if (process.platform !== "linux") {
+        return { availability: "unavailable", reason: `cgroups v2 resource-limit move is Linux-only; not available on "${process.platform}"` };
+    }
+    if (!existsSync(join(CGROUP_ROOT, "cgroup.controllers"))) {
+        return { availability: "unavailable", reason: `${CGROUP_ROOT} has no cgroup.controllers file -- this host is not using the cgroups v2 unified hierarchy` };
+    }
+    const ancestor = findDelegatedCgroupAncestor();
+    if (ancestor === null) {
+        return {
+            availability: "unavailable",
+            reason: "cgroups v2 is mounted, but no writable, controller-delegated cgroup ancestor was found for this process -- commonly means this " +
+                "process is not running under a systemd user session with delegation (Delegate=yes on user@<uid>.service), or is running as a " +
+                "user with no cgroup delegation anywhere in its own ancestry. Refusing rather than silently doing nothing.",
+        };
+    }
+    return { availability: "available", reason: null };
+}
+/**
+ * Moves `options.pid` -- an already-running process this runtime did not
+ * spawn -- into a newly created, resource-limited cgroup. Throws (does not
+ * silently proceed) when the target is not alive, when `cgroupV2Capability()`
+ * reports unavailable, or when a declared limit's controller file does not
+ * actually exist under the delegated ancestor found for it.
+ *
+ * Limits are written to the new cgroup BEFORE the pid is moved into it, so
+ * a process is never observed inside a cgroup with a half-applied limit
+ * set; if any write fails, the created (still-empty) cgroup is removed and
+ * the error is rethrown rather than left as an orphaned, unlimited group.
+ */
+export function moveProcessIntoRestrictedCgroup(options) {
+    if (!isProcessAlive(options.pid)) {
+        throw new Error(`moveProcessIntoRestrictedCgroup: pid ${String(options.pid)} is not running -- cannot move a target that does not exist.`);
+    }
+    const capability = cgroupV2Capability();
+    if (capability.availability !== "available") {
+        throw new Error(`moveProcessIntoRestrictedCgroup: cannot apply -- ${capability.reason}`);
+    }
+    const ancestor = findDelegatedCgroupAncestor();
+    if (ancestor === null) {
+        // Unreachable given capability.availability === "available" above, but
+        // narrows the type honestly rather than a non-null assertion.
+        throw new Error("moveProcessIntoRestrictedCgroup: no delegated cgroup ancestor found despite capability reporting available -- internal inconsistency.");
+    }
+    const cgroupPath = join(ancestor, `descry-restrict-${options.nameHint ?? String(options.pid)}-${String(Date.now())}`);
+    mkdirSync(cgroupPath);
+    try {
+        if (options.limits.cpuMax !== undefined && !existsSync(join(cgroupPath, "cpu.max"))) {
+            throw new Error(`cpuMax was requested but the delegated cgroup ancestor (${ancestor}) does not expose a writable cpu.max to its children on this host -- ` +
+                "refusing rather than silently ignoring the limit.");
+        }
+        if (options.limits.memoryMaxBytes !== undefined) {
+            writeFileSync(join(cgroupPath, "memory.max"), String(options.limits.memoryMaxBytes));
+            // See CgroupResourceLimits.memoryMaxBytes's own comment: without this,
+            // a host with swap available reclaims into swap instead of killing,
+            // and memory.max stops being a real limit. Best-effort -- a host with
+            // no memory.swap.max file at all (swap accounting compiled out, or no
+            // swap controller delegated) still gets a real memory.max, just
+            // without this hardening; not a reason to refuse the whole call.
+            try {
+                writeFileSync(join(cgroupPath, "memory.swap.max"), "0");
+            }
+            catch {
+                // Disclosed above, not silently pretended to have succeeded.
+            }
+        }
+        if (options.limits.maxProcesses !== undefined) {
+            writeFileSync(join(cgroupPath, "pids.max"), String(options.limits.maxProcesses));
+        }
+        if (options.limits.cpuMax !== undefined) {
+            writeFileSync(join(cgroupPath, "cpu.max"), options.limits.cpuMax);
+        }
+        // Moved last, only once every requested limit is confirmed written.
+        writeFileSync(join(cgroupPath, "cgroup.procs"), String(options.pid));
+    }
+    catch (error) {
+        try {
+            rmdirSync(cgroupPath);
+        }
+        catch {
+            // Best-effort -- if the pid was already moved in before the failure,
+            // the directory is non-empty and cannot be removed; nothing more this
+            // catch can honestly do about that.
+        }
+        throw new Error(`moveProcessIntoRestrictedCgroup: failed to apply limits or move pid ${String(options.pid)} into ${cgroupPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return {
+        applied: true,
+        cgroupPath,
+        scope: CGROUP_PARTIAL_RESTRICTION_SCOPE,
+        appliedLimits: options.limits,
+        release: () => {
+            try {
+                rmdirSync(cgroupPath);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=cgroup-partial-restriction.js.map

package/dist/cgroup-partial-restriction.js.map

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

package/dist/collector-version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `Evidence.collectorVersion`'s source for evidence the orchestrator itself
+ * emits directly (e.g. `COLLECTOR_ERROR` for a collector that never got
+ * past `start()`, so no collector-owned code ever ran to attribute the row
+ * to): this package's own `package.json` "version", read from the artifact
+ * itself rather than hand-duplicated into a second string that can drift
+ * from what actually shipped. Same idea as `nodeVersion` elsewhere in this
+ * repo (`process.version`, always known, never probed) applied to a
+ * package instead of the Node runtime.
+ */
+export declare const COLLECTOR_VERSION: string;
+//# sourceMappingURL=collector-version.d.ts.map

package/dist/collector-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-version.d.ts","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,eAAO,MAAM,iBAAiB,EAAE,MAA6E,CAAC"}

package/dist/collector-version.js

@@ -0,0 +1,14 @@
+/**
+ * `Evidence.collectorVersion`'s source for evidence the orchestrator itself
+ * emits directly (e.g. `COLLECTOR_ERROR` for a collector that never got
+ * past `start()`, so no collector-owned code ever ran to attribute the row
+ * to): this package's own `package.json` "version", read from the artifact
+ * itself rather than hand-duplicated into a second string that can drift
+ * from what actually shipped. Same idea as `nodeVersion` elsewhere in this
+ * repo (`process.version`, always known, never probed) applied to a
+ * package instead of the Node runtime.
+ */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export const COLLECTOR_VERSION = require("../package.json").version;
+//# sourceMappingURL=collector-version.js.map

package/dist/collector-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-version.js","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,CAAC,iBAAiB,CAAkC,CAAC,OAAO,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export type { PollingProcessOutputSourceOptions } from "./polling-output-source.ts";
+export { createPollingProcessOutputSource } from "./polling-output-source.ts";
+export type { AttachToRunningProcessOptions } from "./attach-to-running-process.ts";
+export { attachToRunningProcess, isProcessAlive } from "./attach-to-running-process.ts";
+export type { AttachToRunningNodeProcessOptions } from "./attach-to-running-node-process.ts";
+export { attachToRunningNodeProcess, discoverNodeInspectorUrl } from "./attach-to-running-node-process.ts";
+export type { CdpSession } from "./cdp-client.ts";
+export { connectCdp } from "./cdp-client.ts";
+export type { AttachToRunningJvmProcessOptions } from "./attach-to-running-jvm-process.ts";
+export { attachToRunningJvmProcess } from "./attach-to-running-jvm-process.ts";
+export type { RespawnCommand, RespawnCommandSource, RespawnAndSuperviseOptions, RespawnAndSuperviseResult, } from "./respawn-and-supervise.ts";
+export { respawnAndSupervise, inferRespawnCommandFromProc } from "./respawn-and-supervise.ts";
+export type { CgroupResourceLimits, CgroupMoveResult, } from "./cgroup-partial-restriction.ts";
+export { CGROUP_PARTIAL_RESTRICTION_SCOPE, cgroupV2Capability, findDelegatedCgroupAncestor, moveProcessIntoRestrictedCgroup, } from "./cgroup-partial-restriction.ts";
+export type { InstrumentedExecutionInput, InstrumentedExecutionResult } from "./instrumented-execution.ts";
+export { runInstrumentedExecution, createSourceRootResolver } from "./instrumented-execution.ts";
+export type { BackendObservationMechanism, RunRemoteLogObservationInput, RunRemoteLogObservationResult, } from "./profile-backend-observation.ts";
+export { backendObservationMechanismFor, runRemoteLogObservation } from "./profile-backend-observation.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iCAAiC,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAC9E,YAAY,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACxF,YAAY,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AAC7F,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC3G,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC;AAC3F,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAC9F,YAAY,EACV,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC3G,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACjG,YAAY,EACV,2BAA2B,EAC3B,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createPollingProcessOutputSource } from "./polling-output-source.js";
+export { attachToRunningProcess, isProcessAlive } from "./attach-to-running-process.js";
+export { attachToRunningNodeProcess, discoverNodeInspectorUrl } from "./attach-to-running-node-process.js";
+export { connectCdp } from "./cdp-client.js";
+export { attachToRunningJvmProcess } from "./attach-to-running-jvm-process.js";
+export { respawnAndSupervise, inferRespawnCommandFromProc } from "./respawn-and-supervise.js";
+export { CGROUP_PARTIAL_RESTRICTION_SCOPE, cgroupV2Capability, findDelegatedCgroupAncestor, moveProcessIntoRestrictedCgroup, } from "./cgroup-partial-restriction.js";
+export { runInstrumentedExecution, createSourceRootResolver } from "./instrumented-execution.js";
+export { backendObservationMechanismFor, runRemoteLogObservation } from "./profile-backend-observation.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAE9E,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAExF,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAE3G,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAO/E,OAAO,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAK9F,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAMjG,OAAO,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/instrumented-execution.d.ts

@@ -0,0 +1,111 @@
+/**
+ * **The assembly nothing else performed.**
+ *
+ * Every piece of the runtime existed and none of them were wired together
+ * in production code: the controller spawned services, `RuntimeAdapter`
+ * could build collectors, `resolveServiceRootForOrigin` could map an origin
+ * to a source root, and `EvidenceStore` could persist. Only tests ever
+ * connected them, each in its own way, which meant the thing the product
+ * actually does had no single implementation to be right or wrong.
+ *
+ * This module is that implementation. It:
+ *
+ * 1. runs an `ExecutionController` over a `services` configuration;
+ * 2. wraps each spawned process in a **live** `ProcessOutputSource` that
+ *    polls the accumulated buffer and yields each line exactly once;
+ * 3. builds a `CollectorContext` carrying a real `resolveSourceRoot`,
+ *    closed over the execution's own processes — the channel RT-033 added
+ *    and RT-029 built the lookup for, which until now nothing populated;
+ * 4. starts the adapter's collectors, drains them, stops them;
+ * 5. writes every emitted item through `EvidenceStore`, so redaction runs
+ *    rather than being assumed (plan §28).
+ *
+ * **What it deliberately does not do.** It does not decide whether a
+ * finding exists, does not correlate to graph nodes, and does not drive a
+ * browser. Those are separate stages with separate contracts, and folding
+ * them in here would make the one place that assembles the runtime also the
+ * place that judges it.
+ */
+import type { Evidence, Execution, ExecutionConfiguration, ProcessHandle, ServiceRootLookup } from "@descryy/runtime-contracts";
+import type { RuntimeAdapter } from "@descryy/runtime-backend-observation";
+import { type CreateExecutionInput, type RunOptions } from "@descryy/runtime-controller";
+import { EvidenceStore } from "@descryy/runtime-evidence-store";
+export interface InstrumentedExecutionInput {
+    /** Carries the `ExecutionConfiguration` itself — the controller's own input shape, not a parallel copy that could drift from it. */
+    readonly execution: CreateExecutionInput;
+    readonly runOptions: RunOptions;
+    /** Supplies the collectors. One adapter per execution: a run observes one backend runtime. */
+    readonly adapter: RuntimeAdapter;
+    /** Where evidence is written. Provided rather than constructed so a caller owns the database's lifetime and its redaction policy. */
+    readonly store: EvidenceStore;
+    /**
+     * How long to keep draining collector output after the services are up.
+     * There is no "the application is done" signal at this layer — a server
+     * runs until stopped — so the caller states how long the observation
+     * window is rather than this module guessing.
+     */
+    readonly observeForMs: number;
+    /**
+     * **Opt-in, per service name** (a key into `execution.configuration.services`):
+     * front that service with `InboundProxy` (RT-192, DEC-271) once — and
+     * only once — its OWN readiness has already succeeded. This module never
+     * re-asks the question; it reads the answer `controller.run()` already
+     * produced (`ExecutionController.serviceStartResults`), the same
+     * "readiness confirmed on the app's real port FIRST, proxy started AFTER"
+     * sequencing `cross-service-trace.test.ts` performs by hand.
+     *
+     * Absent, or a service not named here, is today's behaviour, unchanged:
+     * no proxy, traffic observed only through whatever collectors `adapter`
+     * itself supplies.
+     *
+     * **This does not close any per-language "HTTP observation" checklist
+     * row.** Every one of those rows uses a self-initiated fixture — the app
+     * calls itself via the exact `PORT` it bound — which has no separate
+     * public port for a proxy to sit in front of. This flag makes
+     * `InboundProxy` available for a *future externally-driven* scenario
+     * (the shape RT-196/`cross-service-trace.test.ts` already proved by
+     * hand); it does not retroactively make any current fixture
+     * externally-driven.
+     */
+    readonly frontWithInboundProxy?: Readonly<Record<string, boolean>>;
+    /**
+     * Fires once every collector for this run — including any `InboundProxy`
+     * `frontWithInboundProxy` started — has started, and before the
+     * observation window's sleep begins. Exists so a caller (chiefly a test)
+     * can drive real traffic through a just-started proxy while it and the
+     * service it fronts are still alive; `InstrumentedExecutionResult` itself
+     * is only returned after the whole run has already stopped every
+     * process, which is too late for that. A throwing callback is not caught
+     * here, matching `RunOptions.onProcessLifecycleEvent`'s own "must not
+     * hang, may not silently swallow its own failure" rule.
+     */
+    readonly onReady?: (info: {
+        readonly execution: Execution;
+        /** Service name → the proxy's own bound port, for every service that was both flagged AND successfully fronted. */
+        readonly proxyPorts: Readonly<Record<string, number>>;
+    }) => void | Promise<void>;
+}
+export interface InstrumentedExecutionResult {
+    readonly execution: Execution;
+    readonly evidence: readonly Evidence[];
+    /** Every collector's own report of what it could do, after the run — not what it claimed at construction. */
+    readonly collectorCapabilities: readonly {
+        readonly collectorId: string;
+        readonly capabilities: ReturnType<import("@descryy/runtime-contracts").Collector["capabilities"]>;
+    }[];
+    /** Set when `run()` refused before spawning anything. Evidence is empty and that is a refusal, not an absence of failures. */
+    readonly validationError: string | null;
+}
+/**
+ * Builds the origin → source-root lookup a collector reads through
+ * `CollectorContext.resolveSourceRoot`.
+ *
+ * This is the piece that had been missing at both ends: RT-029 wrote the
+ * lookup and nothing called it; RT-033 added the channel and nothing filled
+ * it. It closes over the execution's *own* processes, which is what makes
+ * the port→service join possible at all — under ephemeral ports the
+ * configuration cannot know the port, so only the running process can say.
+ */
+export declare function createSourceRootResolver(processes: readonly ProcessHandle[], configuration: ExecutionConfiguration): (origin: string) => ServiceRootLookup;
+export declare function runInstrumentedExecution(input: InstrumentedExecutionInput): Promise<InstrumentedExecutionResult>;
+//# sourceMappingURL=instrumented-execution.d.ts.map

package/dist/instrumented-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumented-execution.d.ts","sourceRoot":"","sources":["../src/instrumented-execution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAEV,QAAQ,EACR,SAAS,EACT,sBAAsB,EACtB,aAAa,EACb,iBAAiB,EAClB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,sCAAsC,CAAC;AAEhG,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,UAAU,EAGhB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAKhE,MAAM,WAAW,0BAA0B;IACzC,oIAAoI;IACpI,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,qIAAqI;IACrI,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;QAC9B,mHAAmH;QACnH,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACvD,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAC;IACvC,6GAA6G;IAC7G,QAAQ,CAAC,qBAAqB,EAAE,SAAS;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,OAAO,4BAA4B,EAAE,SAAS,CAAC,cAAc,CAAC,CAAC,CAAA;KAAE,EAAE,CAAC;IAC/K,8HAA8H;IAC9H,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,aAAa,EAAE,EACnC,aAAa,EAAE,sBAAsB,GACpC,CAAC,MAAM,EAAE,MAAM,KAAK,iBAAiB,CAEvC;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAqVtH"}