@descryy/runtime-controller 0.3.8 → 0.4.0

package/dist/execution-safety.js

@@ -0,0 +1,140 @@
+/**
+ * §21/RT-070's execution boundary: resource limits and privilege reporting for a
+ * runtime declared trusted-local -- every spawned process runs with the invoking
+ * user's own OS privileges, no filesystem/network restriction. Names the boundary
+ * rather than leaving it absent (§38); real isolation (containers/namespaces) is a
+ * separate decision this module does not invent (§29).
+ *
+ * Enforces for real, via the OS: CPU time, virtual memory, process count, through
+ * `prlimit` -- an exec wrapper, never a shell (a shell would undo RT-036's
+ * `tokenizeCommand` refusal of shell metacharacters). `prlimit` is util-linux, absent
+ * on macOS, so it's reported as a capability, never assumed.
+ */
+import { execFileSync } from "node:child_process";
+import { networkIsolationCapability } from "./sandbox.js";
+/** Whether `prlimit` is reachable on PATH. `env` is a parameter (default `process.env`) so the "unavailable" branch is testable without mutating the real environment. */
+export function resourceLimitCapability(env = process.env) {
+    try {
+        execFileSync("prlimit", ["--version"], { env, stdio: "ignore" });
+        return { availability: "available", reason: null };
+    }
+    catch {
+        return {
+            availability: "unavailable",
+            reason: "prlimit (util-linux) is not on PATH -- CPU/memory/process limits cannot be enforced on this platform without reintroducing a shell, which this runtime refuses to do (RT-036)",
+        };
+    }
+}
+/**
+ * RT-193 originally made this always `unavailable`. Now delegates to
+ * `networkIsolationCapability()` (`./sandbox.ts`), real on Linux via a bwrap network
+ * namespace -- kept as the stable name every caller already imports (the seam
+ * RT-193 anticipated). Still unconditionally `unavailable` on macOS/Windows.
+ */
+export function networkPolicyCapability(env = process.env) {
+    return networkIsolationCapability(env);
+}
+/**
+ * Wraps `command`/`args` so the OS enforces `limits`, via `prlimit`. `undefined` or
+ * empty `limits` returns them unchanged -- opt-in only.
+ *
+ * **Throws rather than silently spawning unconstrained** when a limit was requested
+ * and `prlimit` is unavailable (refuse-not-guess, per RT-036) -- the alternative is a
+ * caller asking for a memory cap and silently getting an unbounded process, the
+ * "sandbox that doesn't sandbox" shape §38 bans.
+ */
+export function applyResourceLimits(command, args, limits, env = process.env) {
+    if (limits === undefined)
+        return { command, args };
+    const flags = [];
+    if (limits.maxMemoryBytes !== undefined)
+        flags.push(`--as=${limits.maxMemoryBytes}`);
+    if (limits.maxCpuSeconds !== undefined)
+        flags.push(`--cpu=${limits.maxCpuSeconds}`);
+    if (limits.maxProcesses !== undefined)
+        flags.push(`--nproc=${limits.maxProcesses}`);
+    if (flags.length === 0)
+        return { command, args };
+    const capability = resourceLimitCapability(env);
+    if (capability.availability !== "available") {
+        throw new Error(`resource limits were requested but cannot be enforced on this platform: ${capability.reason}`);
+    }
+    return { command: "prlimit", args: [...flags, "--", command, ...args] };
+}
+/**
+ * DEC-272: the sandbox boundary (RT-070) must be stated to the user directly, not
+ * left as a silent doc gap. Fixed, not derived from `runningAsRoot` -- the boundary
+ * is the same regardless of privilege level found.
+ *
+ * **Scope: this is the unconditional-unisolated text, not a universal one.** Accurate
+ * for every execution before `sandbox.ts` existed; no longer true once spawn-mode got
+ * real bwrap-backed isolation (`applySandbox`) -- using this unconditionally for an
+ * isolated process would understate its boundary, which is not the safe direction to
+ * be wrong in. `sandboxBoundaryDisclosureFor()` below is the mode-aware replacement;
+ * this constant remains its no-policy-applied return value and attach-mode's own
+ * disclosure (attach-mode never has anything more accurate to say).
+ */
+export const SANDBOX_BOUNDARY_DISCLOSURE = "This app runs with your own user permissions, the same as if you started it yourself. " +
+    "The filesystem and network are not isolated -- anything your own account could read, write, " +
+    "or reach, this run can too.";
+const NO_POLICIES_APPLIED = { filesystemPolicyApplied: false, networkPolicyApplied: false };
+/**
+ * Mode-aware replacement for reading `SANDBOX_BOUNDARY_DISCLOSURE` unconditionally.
+ * Defaults to no-policy-applied, so a no-arg call matches the old constant exactly.
+ *
+ * **Only ever true for spawn-mode.** Attach-mode has no path to produce
+ * `filesystemPolicyApplied`/`networkPolicyApplied: true` for a process it didn't
+ * spawn (structural, see `sandbox.ts`) -- attach-mode callers should never pass
+ * anything but the default.
+ */
+export function sandboxBoundaryDisclosureFor(policies = NO_POLICIES_APPLIED) {
+    const { filesystemPolicyApplied, networkPolicyApplied } = policies;
+    if (!filesystemPolicyApplied && !networkPolicyApplied)
+        return SANDBOX_BOUNDARY_DISCLOSURE;
+    if (filesystemPolicyApplied && networkPolicyApplied) {
+        return ("This process was spawned inside a real OS-level sandbox (bubblewrap): filesystem access is restricted " +
+            "to its declared allowedRoots (plus its own working directory) -- nothing else on this machine is visible " +
+            "to it, not merely unwritable -- and network access is fully denied, including this machine's own loopback. " +
+            "This is real isolation, not a name-only boundary.");
+    }
+    if (filesystemPolicyApplied) {
+        return ("This process was spawned inside a real OS-level sandbox (bubblewrap): filesystem access is restricted " +
+            "to its declared allowedRoots (plus its own working directory) -- nothing else on this machine is visible " +
+            "to it, not merely unwritable. Network access was NOT restricted for this run -- it can reach anything " +
+            "your own account's network could reach.");
+    }
+    return ("This process was spawned inside a real OS-level sandbox (bubblewrap): network access is fully denied " +
+        "for this run, including this machine's own loopback. Filesystem access was NOT restricted for this run -- " +
+        "it can read, write, or reach anything your own account's filesystem could.");
+}
+/**
+ * Attach mode's contractual scope guarantee -- distinct from the sandbox-boundary
+ * disclosure above: this is what an attach-mode `Collector` is permitted to *do*, not
+ * what OS boundary wraps it. Mirrors `Collector` in `@descryy/runtime-contracts`.
+ * Stated once so every attach-mode caller surfaces the identical sentence.
+ */
+export const ATTACH_MODE_SCOPE_DISCLOSURE = "Attach mode observes an already-running process; it never executes code in it or applies changes to it. " +
+    "This is a permanent, documented architectural limitation, not a temporary gap -- there is no honest way to " +
+    "retroactively sandbox a process that was already running, unconfined, before this tool touched it. " +
+    "Respawn-and-supervise and the cgroup resource-limit move are real alternatives next to attach mode, not " +
+    "fixes to it; see their own documentation for what each actually gets you.";
+/**
+ * Reports, never enforces. §21's policy for trusted-local (RT-070) is not "refuse to
+ * run as root" -- CI containers commonly do, and a hard refusal would turn a
+ * documented boundary into an undocumented outage. The privilege level just becomes
+ * observable instead of invisible.
+ *
+ * A required parameter, not defaulted: `undefined` is the real value a no-uid-concept
+ * platform produces, and a default can't distinguish "explicitly undefined" from
+ * "omitted." `currentPrivilegeReport()` below is the convenience wrapper; this makes
+ * both branches testable without actually running as root or on Windows.
+ */
+export function privilegeReportFor(getuid) {
+    if (getuid === undefined)
+        return { runningAsRoot: null, disclosure: SANDBOX_BOUNDARY_DISCLOSURE };
+    return { runningAsRoot: getuid() === 0, disclosure: SANDBOX_BOUNDARY_DISCLOSURE };
+}
+export function currentPrivilegeReport() {
+    return privilegeReportFor(process.getuid?.bind(process));
+}
+//# sourceMappingURL=execution-safety.js.map

package/dist/execution-safety.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+export { withDefaultProcessEnv } from "./env.ts";
+export type { SpawnProcessOptions, ProcessExitInfo, ManagedProcess, AttachProcessOptions, ProcessOutputInfo } from "./process-manager.ts";
+export { spawnProcess, attachManagedProcess, isProcessAlive } from "./process-manager.ts";
+export type { AttachFence, ProcessStartTimeResult, OtherLogWriterCheck } from "./attach-fencing.ts";
+export { computeAttachFence, getProcessStartTimeMs, detectOtherLogWriters } from "./attach-fencing.ts";
+export type { ReadinessMechanism, ReadinessIdentity, HttpReadinessCheck, TcpPortReadinessCheck, LogPatternReadinessCheck, CommandReadinessCheck, CustomHookReadinessCheck, ReadinessCheck, ReadinessResult, AwaitReadinessOptions, ProcessOutputReader, } from "./readiness.ts";
+export { READINESS_MECHANISMS, READINESS_IDENTITY_LEVELS, awaitReadiness, createProcessOutputReader } from "./readiness.ts";
+export type { IdentityVerification } from "./process-identity.ts";
+export { verifyListeningSocketOwner } from "./process-identity.ts";
+export type { ProcReader, PortOwnerLookup, LogSourceDescriptor } from "./attach-discovery.ts";
+export { REAL_PROC_READER, findPortOwner, resolveLogSourceForPid } from "./attach-discovery.ts";
+export type { CreateExecutionInput, RunOptions, ProcessLifecycleEvent } from "./controller.ts";
+export { ExecutionController } from "./controller.ts";
+export type { ProcessCollector } from "./process-collector.ts";
+export { createProcessCollector } from "./process-collector.ts";
+export type { RegisteredCollectorCapabilities, CollectorCapabilityKey } from "./capability-registry.ts";
+export { buildExecutionCapabilities, bestCapabilityStatus } from "./capability-registry.ts";
+export type { PrivilegeReport, AppliedIsolationPolicies } from "./execution-safety.ts";
+export { resourceLimitCapability, applyResourceLimits, networkPolicyCapability, privilegeReportFor, currentPrivilegeReport, SANDBOX_BOUNDARY_DISCLOSURE, sandboxBoundaryDisclosureFor, ATTACH_MODE_SCOPE_DISCLOSURE, } from "./execution-safety.ts";
+export type { SandboxOptions } from "./sandbox.ts";
+export { filesystemIsolationCapability, networkIsolationCapability, unsupportedNetworkPolicyReason, resolveExecutableDirectory, applySandbox, } from "./sandbox.ts";
+export type { ContainerSandboxOptions } from "./container-sandbox.ts";
+export { containerRuntimeCapability, containerFilesystemIsolationCapability, containerNetworkIsolationCapability, unsupportedContainerNetworkPolicyReason, resolveContainerImage, applyContainerSandbox, } from "./container-sandbox.ts";
+export { captureEnvironmentMetadata } from "./environment-metadata.ts";
+export type { DependencyVersionMismatch, DependencyVersionCheckResult } from "./dependency-version-check.ts";
+export { checkDependencyVersions } from "./dependency-version-check.ts";
+export type { DeclaredVersionSource, EnvironmentVersionCheckResult } from "./environment-version-check.ts";
+export { DECLARED_VERSION_SOURCES, checkEnvironmentVersion, satisfiesDeclaredNodeVersion } from "./environment-version-check.ts";
+export type { CommandTokenization, ServicesValidation } from "./orchestration.ts";
+export { tokenizeCommand, validateServicesConfiguration, substitutePortPlaceholders } from "./orchestration.ts";
+export type { PreflightCheckKind, PreflightStatus, PreflightProbeOutcome, PreflightCheckSpec, PreflightCheckResult, PreflightResult, } from "./preflight.ts";
+export { PREFLIGHT_CHECK_KINDS, PREFLIGHT_STATUSES, PREFLIGHT_CHECK_TIMEOUT_MS, runPreflight, portFreeCheck, portAnswersCheck, readinessTargetCheck, databaseReachableCheck, customCheck, } from "./preflight.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":"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"}

package/dist/index.js

@@ -0,0 +1,18 @@
+export { withDefaultProcessEnv } from "./env.js";
+export { spawnProcess, attachManagedProcess, isProcessAlive } from "./process-manager.js";
+export { computeAttachFence, getProcessStartTimeMs, detectOtherLogWriters } from "./attach-fencing.js";
+export { READINESS_MECHANISMS, READINESS_IDENTITY_LEVELS, awaitReadiness, createProcessOutputReader } from "./readiness.js";
+export { verifyListeningSocketOwner } from "./process-identity.js";
+export { REAL_PROC_READER, findPortOwner, resolveLogSourceForPid } from "./attach-discovery.js";
+export { ExecutionController } from "./controller.js";
+export { createProcessCollector } from "./process-collector.js";
+export { buildExecutionCapabilities, bestCapabilityStatus } from "./capability-registry.js";
+export { resourceLimitCapability, applyResourceLimits, networkPolicyCapability, privilegeReportFor, currentPrivilegeReport, SANDBOX_BOUNDARY_DISCLOSURE, sandboxBoundaryDisclosureFor, ATTACH_MODE_SCOPE_DISCLOSURE, } from "./execution-safety.js";
+export { filesystemIsolationCapability, networkIsolationCapability, unsupportedNetworkPolicyReason, resolveExecutableDirectory, applySandbox, } from "./sandbox.js";
+export { containerRuntimeCapability, containerFilesystemIsolationCapability, containerNetworkIsolationCapability, unsupportedContainerNetworkPolicyReason, resolveContainerImage, applyContainerSandbox, } from "./container-sandbox.js";
+export { captureEnvironmentMetadata } from "./environment-metadata.js";
+export { checkDependencyVersions } from "./dependency-version-check.js";
+export { DECLARED_VERSION_SOURCES, checkEnvironmentVersion, satisfiesDeclaredNodeVersion } from "./environment-version-check.js";
+export { tokenizeCommand, validateServicesConfiguration, substitutePortPlaceholders } from "./orchestration.js";
+export { PREFLIGHT_CHECK_KINDS, PREFLIGHT_STATUSES, PREFLIGHT_CHECK_TIMEOUT_MS, runPreflight, portFreeCheck, portAnswersCheck, readinessTargetCheck, databaseReachableCheck, customCheck, } from "./preflight.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":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG1F,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAevG,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAG5H,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAGnE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAGhG,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAG5F,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,8BAA8B,EAC9B,0BAA0B,EAC1B,YAAY,GACb,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACtC,mCAAmC,EACnC,uCAAuC,EACvC,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAMjI,OAAO,EAAE,eAAe,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAYhH,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,0BAA0B,EAC1B,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,GACZ,MAAM,gBAAgB,CAAC"}

package/dist/orchestration.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Turns a declarative `services` map (§6, RT-028) into a concrete spawn order for
+ * `ExecutionController.run()` (RT-032). Pure and side-effect-free -- validated and
+ * ordered before anything is spawned, so a bad reference is refused atomically
+ * rather than discovered mid-sequence.
+ *
+ * Start order and port injection are declared, never inferred (RT-023's "ask, don't
+ * guess"): a `${name.port}` reference alone doesn't create an ordering guarantee --
+ * `name` must also appear in the referencing service's `dependsOn`, or validation refuses.
+ */
+import type { ServiceConfiguration } from "@descryy/runtime-contracts";
+export type ServicesValidation = {
+    readonly valid: true;
+    readonly order: readonly string[];
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/**
+ * Validates a `services` map and returns a topological spawn order. Checks, all
+ * before anything is spawned: every `dependsOn` names a real key; the `dependsOn`
+ * graph has no cycle; every `${name}.port` placeholder in a service's `env` has
+ * `name` in that service's own `dependsOn`.
+ */
+export declare function validateServicesConfiguration(services: Readonly<Record<string, ServiceConfiguration>>): ServicesValidation;
+/**
+ * Replaces every `${name}.port` in `env`'s values with the resolved port for `name`.
+ * Assumes `validateServicesConfiguration` already confirmed the reference. An
+ * unresolvable reference is left untouched, not dropped -- a caller that skipped
+ * validation sees an obviously-wrong literal instead of a silent empty substitution.
+ */
+export declare function substitutePortPlaceholders(env: Readonly<Record<string, string>> | undefined, resolvedPorts: ReadonlyMap<string, number>): Record<string, string>;
+export type CommandTokenization = {
+    readonly ok: true;
+    readonly command: string;
+    readonly args: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * POSIX-style tokenizer for `ServiceConfiguration.command`: single quotes (literal),
+ * double quotes (`\` escapes `"` and `\`), backslash escapes outside quotes. Needed
+ * because config carries one string (§6) but `spawnProcess` wants `command`/`args`
+ * separately, and plain whitespace-split breaks paths with spaces.
+ *
+ * Refuses rather than guesses on an unterminated quote, trailing backslash, or
+ * unquoted shell operator -- a plausible-but-wrong tokenization would disguise a
+ * config error as an application failure.
+ *
+ * Globs and `~` pass through literally, unrefused -- exactly what happens with no
+ * shell, and frequently intended literally.
+ */
+export declare function tokenizeCommand(raw: string): CommandTokenization;
+//# sourceMappingURL=orchestration.d.ts.map

package/dist/orchestration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration.d.ts","sourceRoot":"","sources":["../src/orchestration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAUvE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,GACvD,kBAAkB,CAyDpB;AAkCD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACjD,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAWpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CA6EhE"}

package/dist/orchestration.js

@@ -0,0 +1,219 @@
+/**
+ * Turns a declarative `services` map (§6, RT-028) into a concrete spawn order for
+ * `ExecutionController.run()` (RT-032). Pure and side-effect-free -- validated and
+ * ordered before anything is spawned, so a bad reference is refused atomically
+ * rather than discovered mid-sequence.
+ *
+ * Start order and port injection are declared, never inferred (RT-023's "ask, don't
+ * guess"): a `${name.port}` reference alone doesn't create an ordering guarantee --
+ * `name` must also appear in the referencing service's `dependsOn`, or validation refuses.
+ */
+// Bounded at {1,256}, not `+`: RT-070's regex audit (after RT-069's ReDoS finding in
+// evidence-store/redaction.ts) flagged this exact shape -- unbounded class followed by
+// a literal (`.port}`) that can be absent -- as O(n^2) backtracking on a long
+// unterminated string. Low-risk since `service.env` is developer-authored, not
+// adversarial, but the shape matches a real same-day DoS elsewhere. 256 is far more
+// than any real name needs.
+const PORT_PLACEHOLDER = /\$\{([^}]{1,256})\.port\}/g;
+/**
+ * Validates a `services` map and returns a topological spawn order. Checks, all
+ * before anything is spawned: every `dependsOn` names a real key; the `dependsOn`
+ * graph has no cycle; every `${name}.port` placeholder in a service's `env` has
+ * `name` in that service's own `dependsOn`.
+ */
+export function validateServicesConfiguration(services) {
+    const names = Object.keys(services);
+    for (const name of names) {
+        for (const dep of services[name]?.dependsOn ?? []) {
+            if (!(dep in services)) {
+                return { valid: false, reason: `service "${name}" depends on "${dep}", which is not in services` };
+            }
+        }
+    }
+    const orderResult = topologicalOrder(services, names);
+    if (!orderResult.valid) {
+        return orderResult;
+    }
+    for (const name of names) {
+        const declared = new Set(services[name]?.dependsOn ?? []);
+        for (const value of Object.values(services[name]?.env ?? {})) {
+            for (const match of value.matchAll(PORT_PLACEHOLDER)) {
+                const referenced = match[1];
+                if (referenced !== undefined && !declared.has(referenced)) {
+                    return {
+                        valid: false,
+                        reason: `service "${name}" references "\${${referenced}.port}" in env but does not declare "${referenced}" in dependsOn`,
+                    };
+                }
+            }
+        }
+    }
+    // Exactly one of `command`/`attach` per service, checked before spawning.
+    // Neither: nothing tells run() how to start it. Both: ambiguous, don't guess.
+    for (const name of names) {
+        const service = services[name];
+        const hasCommand = service?.command !== undefined;
+        const hasAttach = service?.attach !== undefined;
+        if (hasCommand === hasAttach) {
+            return {
+                valid: false,
+                reason: `service "${name}" must declare exactly one of "command" (spawn) or "attach" (attach to an already-running process), not ${hasCommand ? "both" : "neither"}`,
+            };
+        }
+    }
+    // A command that can't be tokenized is a config error -- check before spawning
+    // rather than discovering it mid-sequence with earlier services already running.
+    for (const name of names) {
+        const command = services[name]?.command;
+        if (command === undefined)
+            continue;
+        const tokenized = tokenizeCommand(command);
+        if (!tokenized.ok) {
+            return { valid: false, reason: `service "${name}": ${tokenized.reason}` };
+        }
+    }
+    return orderResult;
+}
+function topologicalOrder(services, names) {
+    const order = [];
+    const visited = new Set();
+    const visiting = new Set();
+    function visit(name) {
+        if (visited.has(name))
+            return null;
+        if (visiting.has(name))
+            return `cycle detected in dependsOn involving "${name}"`;
+        visiting.add(name);
+        for (const dep of services[name]?.dependsOn ?? []) {
+            const err = visit(dep);
+            if (err !== null)
+                return err;
+        }
+        visiting.delete(name);
+        visited.add(name);
+        order.push(name);
+        return null;
+    }
+    for (const name of names) {
+        const err = visit(name);
+        if (err !== null) {
+            return { valid: false, reason: err };
+        }
+    }
+    return { valid: true, order };
+}
+/**
+ * Replaces every `${name}.port` in `env`'s values with the resolved port for `name`.
+ * Assumes `validateServicesConfiguration` already confirmed the reference. An
+ * unresolvable reference is left untouched, not dropped -- a caller that skipped
+ * validation sees an obviously-wrong literal instead of a silent empty substitution.
+ */
+export function substitutePortPlaceholders(env, resolvedPorts) {
+    const result = {};
+    for (const [key, value] of Object.entries(env ?? {})) {
+        result[key] = value.replace(PORT_PLACEHOLDER, (literal, name) => {
+            const port = resolvedPorts.get(name);
+            return port === undefined ? literal : String(port);
+        });
+    }
+    return result;
+}
+/**
+ * Shell operators that only mean anything to a shell. `spawnProcess` uses
+ * `child_process.spawn` without one -- no implicit shell, no injection surface. A
+ * command containing these was never going to behave as written; refusing beats the
+ * old whitespace-split behavior of silently passing `> out.log` as literal args to
+ * `node`. `sh -c "..."` still works for anyone who wants a real shell.
+ */
+const SHELL_OPERATORS = new Set(["|", "&", ";", "<", ">", "`", "$"]);
+/**
+ * POSIX-style tokenizer for `ServiceConfiguration.command`: single quotes (literal),
+ * double quotes (`\` escapes `"` and `\`), backslash escapes outside quotes. Needed
+ * because config carries one string (§6) but `spawnProcess` wants `command`/`args`
+ * separately, and plain whitespace-split breaks paths with spaces.
+ *
+ * Refuses rather than guesses on an unterminated quote, trailing backslash, or
+ * unquoted shell operator -- a plausible-but-wrong tokenization would disguise a
+ * config error as an application failure.
+ *
+ * Globs and `~` pass through literally, unrefused -- exactly what happens with no
+ * shell, and frequently intended literally.
+ */
+export function tokenizeCommand(raw) {
+    const tokens = [];
+    let current = "";
+    let started = false; // distinguishes an empty quoted token ('') from no token
+    let quote = null;
+    for (let i = 0; i < raw.length; i++) {
+        const char = raw[i];
+        if (quote === "'") {
+            if (char === "'")
+                quote = null;
+            else
+                current += char;
+            continue;
+        }
+        if (quote === '"') {
+            if (char === "\\") {
+                const next = raw[i + 1];
+                if (next === undefined)
+                    return { ok: false, reason: 'command ends with a trailing backslash inside a double-quoted string, which escapes nothing' };
+                // Only `"` and `\` are escapable in double quotes; else keep the backslash.
+                if (next === '"' || next === "\\") {
+                    current += next;
+                    i++;
+                }
+                else {
+                    current += char;
+                }
+                continue;
+            }
+            if (char === '"')
+                quote = null;
+            else
+                current += char;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (char === "\\") {
+            const next = raw[i + 1];
+            if (next === undefined)
+                return { ok: false, reason: "command ends with a trailing backslash, which escapes nothing" };
+            current += next;
+            started = true;
+            i++;
+            continue;
+        }
+        if (SHELL_OPERATORS.has(char)) {
+            return {
+                ok: false,
+                reason: `command contains the shell operator "${char}" outside quotes, but processes are spawned without a shell — ` +
+                    `it would be passed to the program as a literal argument rather than interpreted. ` +
+                    `Use an explicit shell (sh -c "...") if that is what you meant.`,
+            };
+        }
+        if (/\s/.test(char)) {
+            if (started) {
+                tokens.push(current);
+                current = "";
+                started = false;
+            }
+            continue;
+        }
+        current += char;
+        started = true;
+    }
+    if (quote !== null)
+        return { ok: false, reason: `command has an unterminated ${quote === '"' ? "double" : "single"} quote` };
+    if (started)
+        tokens.push(current);
+    const [head, ...rest] = tokens;
+    if (head === undefined || head === "")
+        return { ok: false, reason: "command is empty" };
+    return { ok: true, command: head, args: rest };
+}
+//# sourceMappingURL=orchestration.js.map

package/dist/orchestration.js.map

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

package/dist/preflight.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Ready check before a run (RT-263). A broken setup used to be discovered only after a
+ * full readiness wait (up to `RunOptions.readiness[*].timeoutMs`, often ~30s-2min) had
+ * already failed. This runs a short, read-only pass first — the same declared checks a
+ * run is about to depend on, single-shot rather than polled to a full timeout — and
+ * reports a plain-words problem and fix before the caller starts anything.
+ *
+ * Deliberately generic: this module owns the engine (status, timing, disclosure), never
+ * a specific check's mechanism it would have to import a language, a browser, a graph
+ * store or a database driver to perform. `customCheck` is the seam every one of those
+ * uses — `chromiumCanLaunch`, `graphExists`, and any future "database reachable" check
+ * are built by the caller that already depends on the thing being checked, and handed in
+ * as a probe. Nothing here decides what a broken setup is, only how many of the caller's
+ * own answers it takes to call one "ready", "partial" or "broken".
+ *
+ * **Read-only, always.** Every probe built here (`portFreeCheck`, `portAnswersCheck`,
+ * `readinessTargetCheck`) only ever connects or asks; none binds a port, starts a
+ * process or writes anything. A `customCheck` probe is the caller's own code and this
+ * module cannot enforce that discipline on it, but every caller in this codebase that
+ * builds one must hold to it too (Build A step 4).
+ */
+import { type ReadinessCheck } from "./readiness.ts";
+export declare const PREFLIGHT_CHECK_KINDS: readonly ["port", "readiness", "chromium", "graph", "database", "custom"];
+export type PreflightCheckKind = (typeof PREFLIGHT_CHECK_KINDS)[number];
+export declare const PREFLIGHT_STATUSES: readonly ["ready", "partial", "broken"];
+export type PreflightStatus = (typeof PREFLIGHT_STATUSES)[number];
+/**
+ * Bounds one check's own probe — not the whole preflight. Every check in a call runs
+ * concurrently (`Promise.all`), so a caller with several checks still finishes near this
+ * bound rather than their sum. Starting value, not a measurement: it is what lets a
+ * `broken` setup report within the lane's 5s target while still giving a slow-but-honest
+ * TCP probe (a loaded machine, a container cold-starting) more than an instant to answer.
+ */
+export declare const PREFLIGHT_CHECK_TIMEOUT_MS = 4000;
+export interface PreflightProbeOutcome {
+    readonly ok: boolean;
+    /**
+     * Plain words, always — this is what the user sees. When `!ok`, names the exact
+     * problem AND the fix ("Nothing is listening on localhost:3000. Is your app
+     * running?"), never a bare boolean or a stack trace. Ignored (by convention "ok")
+     * when `ok` is true.
+     */
+    readonly message: string;
+}
+export interface PreflightCheckSpec {
+    readonly kind: PreflightCheckKind;
+    /** Named for the report — "port 3000 is free", "chromium can launch". */
+    readonly label: string;
+    /**
+     * A failing required check makes the whole preflight `broken` — this run cannot
+     * proceed without it. A failing non-required check makes it `partial` instead: the
+     * run continues, and the failure becomes a disclosed gap (what won't be observed),
+     * never silently dropped (rule 7).
+     */
+    readonly required: boolean;
+    readonly probe: () => Promise<PreflightProbeOutcome>;
+}
+export interface PreflightCheckResult {
+    readonly kind: PreflightCheckKind;
+    readonly label: string;
+    readonly required: boolean;
+    readonly ok: boolean;
+    readonly message: string;
+}
+export interface PreflightResult {
+    readonly status: PreflightStatus;
+    readonly elapsedMs: number;
+    readonly checks: readonly PreflightCheckResult[];
+    /**
+     * Plain-word problems from every failed non-required check — what this run will
+     * proceed without observing. Empty exactly when `status === "ready"`. A `broken`
+     * result's problems are read off `checks` instead (every failed required check),
+     * because those stop the run rather than being disclosed alongside it.
+     */
+    readonly disclosures: readonly string[];
+}
+/**
+ * Runs every check concurrently and folds the results into one status. Never throws —
+ * a probe that rejects or hangs past its own bound is recorded as a failed check
+ * (`runOne` below), not a crash of the preflight itself, because "the check broke" and
+ * "the setup is broken" are different facts the caller still needs told apart... except
+ * they aren't told apart here: a check that cannot even answer is exactly as blocking as
+ * one that answered "no", which is why it is folded in as `!ok` rather than a third
+ * outcome. What is preserved is the message, which always names which check and why.
+ */
+export declare function runPreflight(checks: readonly PreflightCheckSpec[]): Promise<PreflightResult>;
+/**
+ * Boot precondition: nothing may already be listening at `host:port` before this run
+ * spawns its own process there — a stale listener from a dead session would otherwise
+ * be mistaken for this run's own (the same RT-024 hazard `readiness.ts` names). `ready`
+ * is `!answered` — the inverse polarity of `portAnswersCheck` below, for the attach case.
+ */
+export declare function portFreeCheck(host: string, port: number, label?: string): PreflightCheckSpec;
+/**
+ * Attach precondition: the caller is attaching to an app it expects to already be
+ * running, so something must already answer at `host:port`. `ready` is `answered` —
+ * the inverse polarity of `portFreeCheck` above, for the boot case.
+ */
+export declare function portAnswersCheck(host: string, port: number, label?: string): PreflightCheckSpec;
+/**
+ * Wraps a run's own declared `ReadinessCheck`s as a single-shot preflight probe — one
+ * pass at `PREFLIGHT_CHECK_TIMEOUT_MS`, never the full poll loop `awaitReadiness` runs
+ * once the run actually starts. Reuses `awaitReadiness` itself rather than a second
+ * probing mechanism that could drift from what the real readiness wait checks.
+ *
+ * Required by default: a target this run declared and cannot reach is this run being
+ * broken, not a gap it can disclose and continue past. A caller may mark a secondary
+ * target `required: false` when the run can genuinely proceed without it.
+ */
+export declare function readinessTargetCheck(label: string, checks: readonly ReadinessCheck[], options?: {
+    readonly required?: boolean;
+}): PreflightCheckSpec;
+export declare function databaseReachableCheck(host: string, port: number, label?: string): PreflightCheckSpec;
+/**
+ * The seam for anything this package must not name (rule 1's dependency-direction
+ * cousin: `@descryy/runtime-controller` has no browser, graph or database dependency,
+ * and must not gain one just to phrase a preflight check). A caller that already
+ * depends on the thing being checked — `@descryy/runtime-browser` for Chromium,
+ * `@descryy/mcp` for the graph — builds the probe and hands it in with this.
+ */
+export declare function customCheck(kind: PreflightCheckKind, label: string, required: boolean, probe: () => Promise<PreflightProbeOutcome>): PreflightCheckSpec;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErE,eAAO,MAAM,qBAAqB,2EAA4E,CAAC;AAC/G,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,eAAO,MAAM,kBAAkB,yCAA0C,CAAC;AAC1E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAUlG;AA+CD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAgB5F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAW/F;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5C,kBAAkB,CAUpB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAarG;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,kBAAkB,EACxB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,EACjB,KAAK,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,GAC1C,kBAAkB,CAEpB"}