@checkstack/backend-api 0.20.0 → 0.21.0

package/src/script-sandbox/policy.ts

@@ -0,0 +1,220 @@
+import {
+  sandboxPolicySchema,
+  type SandboxPolicy,
+  type SandboxPolicyInput,
+} from "@checkstack/common";
+
+/**
+ * OS-level sandbox policy for the shared user-script runners.
+ *
+ * The policy SHAPE (the zod `sandboxPolicySchema` and its sub-schemas) is the
+ * single source of truth in `@checkstack/common` so it can be shared by the
+ * RPC contract (admin read/write endpoints) and the satellite WS protocol
+ * (policy relay) without a backward dependency on this backend package. This
+ * module re-exports that schema and layers the runtime-only
+ * helpers on top: the shipped default profile, the env-seeded low-priv UID/GID
+ * resolution, and `mergeSandboxPolicy`.
+ *
+ * The two runners (`shell-script-runner.ts`, `esm-script-runner.ts`) parse a
+ * `SandboxPolicyInput` against {@link sandboxPolicySchema}, reconcile it against
+ * detected host capabilities, and build the extra `Bun.spawn` options from the
+ * result.
+ */
+
+export {
+  onUnavailableSchema,
+  resourceLimitsSchema,
+  filesystemPolicySchema,
+  networkPolicySchema,
+  privilegePolicySchema,
+  sandboxPolicySchema,
+  type OnUnavailable,
+  type ResourceLimits,
+  type FilesystemPolicy,
+  type NetworkPolicy,
+  type PrivilegePolicy,
+  type SandboxPolicy,
+  type SandboxPolicyInput,
+} from "@checkstack/common";
+
+/**
+ * The shipped global default profile (DP) - plan §6.1.
+ *
+ * This is the runner's base default, so every script run is hardened out of the
+ * box. It is SECURE-by-default: egress is denied until an operator adds
+ * allowlist entries (network `allowlist` with an empty `allow` list), temp-file
+ * writes are confined to the per-run scratch dir, the reconciled managed-package
+ * tree is bound read-only, and fork-bombs / OOM / disk-fill plus reads of
+ * arbitrary host paths (on a wrapper host) are blocked. Ordinary outbound
+ * `fetch` does NOT work by default - the operator must allowlist the
+ * destinations a script may reach.
+ *
+ * FAIL-CLOSED by default (`onUnavailable: "fail"`): if any requested layer
+ * cannot be enforced on the host, the run is REFUSED
+ * ({@link SandboxUnavailableError} -> clean `exitCode: -1`, NO unsandboxed
+ * spawn) rather than silently degrading to a weaker subset. This makes the
+ * shipped global default fail safe: a malicious script never slips through on a
+ * host that is missing a sandbox primitive. The official container images are
+ * built to support every layer (bubblewrap + unprivileged user namespaces +
+ * slirp4netns rootless egress + util-linux rlimits + a dedicated non-root UID),
+ * so the secure default WORKS out of the box there - see the container
+ * verification in `docs/.../script-sandboxing` and the in-container probe. An
+ * operator running on a host that genuinely cannot enforce a layer can switch
+ * the global policy to `degrade` (drop to the portable subset and surface it)
+ * via the admin settings page; that is an explicit, audited opt-out, never a
+ * silent one. Each run's actual enforcement is reported via the
+ * {@link EffectiveSandbox} report.
+ *
+ * The `privilege.uid`/`gid` are left UNSET here; the dedicated low-priv target
+ * is resolved at runtime by {@link resolveDefaultSandboxProfile} (from
+ * `CHECKSTACK_SANDBOX_UID` / `CHECKSTACK_SANDBOX_GID`), so the constant stays a
+ * pure value and the env read happens once per process where it is used.
+ */
+export const DEFAULT_SANDBOX_PROFILE: SandboxPolicy = sandboxPolicySchema.parse({
+  enabled: true,
+  // Fail-closed: refuse the run if a layer can't be enforced, rather than
+  // silently dropping to a weaker subset. The shipped containers support every
+  // layer so this is a working default there; weak hosts can opt into
+  // "degrade" explicitly via the admin settings page.
+  onUnavailable: "fail",
+  resources: {
+    cpuSeconds: 60,
+    memoryBytes: 512 * 1024 * 1024,
+    maxOpenFiles: 1024,
+    maxProcesses: 256,
+    maxOutputBytes: 5 * 1024 * 1024,
+    maxFileSizeBytes: 256 * 1024 * 1024,
+  },
+  filesystem: {
+    mode: "scratch-plus-ro",
+  },
+  network: {
+    // Secure-by-default: allowlist with an EMPTY allow list = deny egress until
+    // an operator adds entries. Link-local / cloud-metadata IPs stay blocked.
+    mode: "allowlist",
+    allow: [],
+    denyLinkLocalAndMetadata: true,
+  },
+  privilege: {
+    mode: "drop-to-uid",
+  },
+});
+
+/** Env var naming the dedicated low-privilege UID to drop script runs to. */
+export const SANDBOX_UID_ENV = "CHECKSTACK_SANDBOX_UID";
+/** Env var naming the dedicated low-privilege GID to drop script runs to. */
+export const SANDBOX_GID_ENV = "CHECKSTACK_SANDBOX_GID";
+
+/**
+ * Parse a non-negative integer from an env value, or `undefined` when unset /
+ * malformed. A malformed value is treated as "not configured" (the privilege
+ * drop then degrades to `inherit` and surfaces it) rather than throwing - a
+ * typo in an operator env var must not crash every script run.
+ */
+function readNonNegativeIntEnv(name: string): number | undefined {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") {
+    return undefined;
+  }
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return undefined;
+  }
+  return parsed;
+}
+
+/**
+ * Resolve the shipped {@link DEFAULT_SANDBOX_PROFILE} with the dedicated
+ * low-privilege UID/GID seeded from the environment
+ * (`CHECKSTACK_SANDBOX_UID` / `CHECKSTACK_SANDBOX_GID`).
+ *
+ * This is the value the runner uses as its base default. When no UID is
+ * configured (the common dev / macOS case) the privilege layer keeps
+ * `drop-to-uid` but, with no target, the wrapper degrades it to `inherit` and
+ * surfaces it - never a hard failure. A configured GID without a UID is
+ * ignored (a GID drop without a UID drop is not meaningful here).
+ *
+ * Pure read of `process.env`; safe to call per run (no spawning, no I/O).
+ */
+export function resolveDefaultSandboxProfile(): SandboxPolicy {
+  const uid = readNonNegativeIntEnv(SANDBOX_UID_ENV);
+  if (uid === undefined) {
+    return DEFAULT_SANDBOX_PROFILE;
+  }
+  const gid = readNonNegativeIntEnv(SANDBOX_GID_ENV);
+  return {
+    ...DEFAULT_SANDBOX_PROFILE,
+    privilege: {
+      ...DEFAULT_SANDBOX_PROFILE.privilege,
+      uid,
+      ...(gid === undefined ? {} : { gid }),
+    },
+  };
+}
+
+/**
+ * Deep-merge a partial per-item override on top of a base policy. The base is
+ * the fully-resolved global default (e.g. {@link DEFAULT_SANDBOX_PROFILE}, or
+ * the durable global default read from settings); the override is a partial
+ * `SandboxPolicyInput` parsed from a per-check /
+ * per-action `sandbox` config field. Per-item values win per-field, and only
+ * the fields the override actually sets are touched - an override that only
+ * sets `{ network: { mode: "deny" } }` must not re-widen the other layers
+ * back to the bare zod field defaults.
+ *
+ * Returns a validated {@link SandboxPolicy}.
+ */
+export function mergeSandboxPolicy({
+  base,
+  override,
+}: {
+  base: SandboxPolicy;
+  override?: SandboxPolicyInput;
+}): SandboxPolicy {
+  if (override === undefined) {
+    return base;
+  }
+  // Validate the override against the schema FIRST so its values and bounds
+  // are enforced, then overlay only the keys the caller actually provided
+  // (defined keys only) so an unset layer keeps the base value rather than
+  // being re-widened to the bare zod field default.
+  sandboxPolicySchema.parse(override);
+
+  const merged: SandboxPolicy = {
+    enabled: pick(override.enabled, base.enabled),
+    onUnavailable: pick(override.onUnavailable, base.onUnavailable),
+    resources: overlayDefined(base.resources, override.resources),
+    filesystem: overlayDefined(base.filesystem, override.filesystem),
+    network: overlayDefined(base.network, override.network),
+    privilege: overlayDefined(base.privilege, override.privilege),
+  };
+
+  // Re-validate the merged shape (cheap; keeps bounds + strict enforcement).
+  return sandboxPolicySchema.parse(merged);
+}
+
+/** Return `value` when defined, otherwise `fallback`. */
+function pick<T>(value: T | undefined, fallback: T): T {
+  return value === undefined ? fallback : value;
+}
+
+/**
+ * Overlay only the *defined* keys of `over` onto `base`. An explicit
+ * `undefined` in `over` does not clobber the base value.
+ */
+function overlayDefined<T extends Record<string, unknown>>(
+  base: T,
+  over: Partial<T> | undefined,
+): T {
+  if (over === undefined) {
+    return base;
+  }
+  const result: T = { ...base };
+  for (const key of Object.keys(over) as Array<keyof T>) {
+    const value = over[key];
+    if (value !== undefined) {
+      result[key] = value as T[keyof T];
+    }
+  }
+  return result;
+}

package/src/script-sandbox/provider.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+  FAIL_CLOSED_SANDBOX_PROFILE,
+  registerSandboxPolicyProvider,
+  resetSandboxPolicyProvider,
+  resolveActiveSandboxPolicy,
+} from "./provider";
+import { resolveDefaultSandboxProfile, type SandboxPolicy } from "./policy";
+
+describe("script-sandbox policy provider", () => {
+  afterEach(() => {
+    resetSandboxPolicyProvider();
+  });
+
+  it("fails closed (deny egress, scratch-only) when no provider is registered", async () => {
+    resetSandboxPolicyProvider();
+    const { policy, failedClosed } = await resolveActiveSandboxPolicy();
+    expect(failedClosed).toBe(true);
+    expect(policy).toEqual(FAIL_CLOSED_SANDBOX_PROFILE);
+    expect(policy.network.mode).toBe("deny");
+    expect(policy.filesystem.mode).toBe("scratch-plus-ro");
+    expect(policy.privilege.mode).toBe("drop-to-uid");
+    expect(policy.enabled).toBe(true);
+  });
+
+  it("returns the registered provider's policy", async () => {
+    const provided: SandboxPolicy = resolveDefaultSandboxProfile();
+    registerSandboxPolicyProvider(async () => provided);
+    const { policy, failedClosed } = await resolveActiveSandboxPolicy();
+    expect(failedClosed).toBe(false);
+    expect(policy).toEqual(provided);
+  });
+
+  it("fails closed when the provider throws (does not widen the sandbox)", async () => {
+    registerSandboxPolicyProvider(async () => {
+      throw new Error("transient db error");
+    });
+    const { policy, failedClosed } = await resolveActiveSandboxPolicy();
+    expect(failedClosed).toBe(true);
+    expect(policy).toEqual(FAIL_CLOSED_SANDBOX_PROFILE);
+  });
+
+  it("fail-closed network is never unrestricted", async () => {
+    expect(FAIL_CLOSED_SANDBOX_PROFILE.network.mode).not.toBe("unrestricted");
+    expect(FAIL_CLOSED_SANDBOX_PROFILE.network.allow).toEqual([]);
+    expect(FAIL_CLOSED_SANDBOX_PROFILE.network.denyLinkLocalAndMetadata).toBe(
+      true,
+    );
+  });
+
+  it("last registered provider wins (single cluster-wide value)", async () => {
+    registerSandboxPolicyProvider(async () => resolveDefaultSandboxProfile());
+    const second: SandboxPolicy = {
+      ...resolveDefaultSandboxProfile(),
+      network: { mode: "deny", allow: [], denyLinkLocalAndMetadata: true },
+    };
+    registerSandboxPolicyProvider(async () => second);
+    const { policy } = await resolveActiveSandboxPolicy();
+    expect(policy.network.mode).toBe("deny");
+  });
+});

package/src/script-sandbox/provider.ts

@@ -0,0 +1,134 @@
+import { sandboxPolicySchema, type SandboxPolicy } from "./policy";
+
+/**
+ * Process-wide active sandbox policy provider.
+ *
+ * The script runners (`shell-script-runner.ts`, `esm-script-runner.ts`) no
+ * longer accept a per-run `sandbox` argument: policy is GLOBAL-only. Each run
+ * resolves the active policy through {@link resolveActiveSandboxPolicy}, which
+ * awaits the provider registered once at platform startup
+ * (see the script plugins' `init` and the satellite runtime).
+ *
+ * Why a provider (not a constant): the durable global default lives in the
+ * shared Postgres `plugin_configs` table, reachable only where a
+ * `ConfigService` is wired (the core pod). The runner module itself has no DB
+ * handle, so startup hands it a closure that reads the durable value. This keeps
+ * the global policy a single cluster-wide value (state-and-scale rule 2: the
+ * same answer on every pod that has wired the same `ConfigService`-backed
+ * provider), while the runner stays dependency-free.
+ *
+ * Fail-closed (security core): if NO provider is registered, or the registered
+ * provider throws, {@link resolveActiveSandboxPolicy} returns the
+ * {@link FAIL_CLOSED_SANDBOX_PROFILE} — the most restrictive safe policy (no
+ * egress, scratch filesystem + read-only managed packages, privilege drop) —
+ * NOT the permissive shipped
+ * default. A misconfigured or un-wired runtime therefore denies, it does not
+ * silently run unsandboxed.
+ */
+
+/** Reason string attached to the synthetic downgrade when failing closed. */
+export const FAIL_CLOSED_DOWNGRADE_REASON =
+  "no global sandbox policy provider was registered (or it failed); fell back " +
+  "to the most restrictive fail-closed policy (deny egress, scratch filesystem " +
+  "with read-only managed packages, privilege drop) instead of running " +
+  "unsandboxed";
+
+/**
+ * The fail-closed policy. Derived from the shipped safe default's resource caps
+ * and privilege drop, but with the network locked to `deny` (no egress at all)
+ * and the filesystem locked to `scratch-plus-ro` — the per-run scratch dir is
+ * writable and the reconciled managed-package tree
+ * (`resolutionRoot/node_modules`) is bound READ-ONLY so a script can still
+ * `import` its allowlisted packages, while the rest of the host FS stays
+ * hidden. `onUnavailable` stays `degrade` so an unenforceable layer on a weak
+ * host still RUNS the most restrictive subset it can (and surfaces the gap)
+ * rather than refusing every run on a host that lacks the strong primitives —
+ * refusing all runs would be a worse, silent-everything-breaks failure mode
+ * than enforcing the portable subset.
+ */
+export const FAIL_CLOSED_SANDBOX_PROFILE: SandboxPolicy = sandboxPolicySchema.parse({
+  enabled: true,
+  onUnavailable: "degrade",
+  resources: {
+    cpuSeconds: 60,
+    memoryBytes: 512 * 1024 * 1024,
+    maxOpenFiles: 1024,
+    maxProcesses: 256,
+    maxOutputBytes: 5 * 1024 * 1024,
+    maxFileSizeBytes: 256 * 1024 * 1024,
+  },
+  filesystem: {
+    mode: "scratch-plus-ro",
+  },
+  network: {
+    mode: "deny",
+    allow: [],
+    denyLinkLocalAndMetadata: true,
+  },
+  privilege: {
+    mode: "drop-to-uid",
+  },
+});
+
+/** A registered provider for the active global sandbox policy. */
+export type SandboxPolicyProvider = () => Promise<SandboxPolicy>;
+
+/**
+ * The result of resolving the active policy: the policy plus whether the
+ * resolution fell back to {@link FAIL_CLOSED_SANDBOX_PROFILE}. The runners use
+ * `failedClosed` to inject a synthetic downgrade into the run's
+ * EffectiveSandbox report so the fallback is never silent.
+ */
+export interface ResolvedActiveSandboxPolicy {
+  policy: SandboxPolicy;
+  /** True when no provider was registered or the provider threw. */
+  failedClosed: boolean;
+}
+
+// Module-level singleton. The active global policy is a single cluster-wide
+// value, NOT per-run state — every run on this process wants the same answer —
+// so a module-level provider closure is scale-correct. (Per-run state would be
+// a bug; there is none here.)
+let activeProvider: SandboxPolicyProvider | undefined;
+
+/**
+ * Register the process-wide active sandbox policy provider. Called ONCE at
+ * platform startup where a `ConfigService` is available (the core pod) or with
+ * the relayed cluster policy (the satellite runtime). Re-registering replaces
+ * the previous provider (idempotent for the same closure; last writer wins),
+ * which is harmless because the value is a single cluster-wide global.
+ */
+export function registerSandboxPolicyProvider(
+  provider: SandboxPolicyProvider,
+): void {
+  activeProvider = provider;
+}
+
+/**
+ * Clear the registered provider. Test-only helper so a test can assert the
+ * fail-closed path and reset between cases. Not part of the production flow.
+ */
+export function resetSandboxPolicyProvider(): void {
+  activeProvider = undefined;
+}
+
+/**
+ * Resolve the active global sandbox policy for a run.
+ *
+ * - Provider registered and succeeds -> its policy, `failedClosed: false`.
+ * - No provider, or the provider throws -> {@link FAIL_CLOSED_SANDBOX_PROFILE},
+ *   `failedClosed: true`. NEVER the permissive shipped default.
+ */
+export async function resolveActiveSandboxPolicy(): Promise<ResolvedActiveSandboxPolicy> {
+  if (activeProvider === undefined) {
+    return { policy: FAIL_CLOSED_SANDBOX_PROFILE, failedClosed: true };
+  }
+  try {
+    const policy = await activeProvider();
+    return { policy, failedClosed: false };
+  } catch {
+    // A provider that throws (e.g. a transient DB error reading the durable
+    // default) must NOT widen the sandbox: fail closed, not open.
+    return { policy: FAIL_CLOSED_SANDBOX_PROFILE, failedClosed: true };
+  }
+}

package/src/script-sandbox/readiness.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "bun:test";
+import {
+  assessSandboxHostReadiness,
+  formatSandboxReadinessBanner,
+} from "./readiness";
+import type { SandboxCapabilities } from "./capabilities";
+
+/** A fully-capable Linux host (every OS layer enforceable). */
+const LINUX_READY: SandboxCapabilities = {
+  platform: "linux",
+  euidIsRoot: false,
+  hasPrlimit: true,
+  rlimitNative: true,
+  wrapper: "bwrap",
+  userNamespaces: true,
+  netNamespaces: true,
+  userNsCreatable: true,
+  netEgressIface: null,
+  netEgressAddressing: null,
+  netEgressRootless: true,
+};
+
+describe("assessSandboxHostReadiness", () => {
+  it("reports enforceable with no guidance on a fully-capable Linux host", () => {
+    const r = assessSandboxHostReadiness({ caps: LINUX_READY });
+    expect(r.enforceable).toBe(true);
+    expect(r.reasons).toEqual([]);
+    expect(r.guidance).toBe("");
+  });
+
+  it("is NOT enforceable on darwin and guides to Docker + degrade", () => {
+    const r = assessSandboxHostReadiness({
+      caps: { ...LINUX_READY, platform: "darwin" },
+    });
+    expect(r.enforceable).toBe(false);
+    expect(r.platform).toBe("darwin");
+    expect(r.reasons.join(" ")).toContain("requires Linux");
+    // Both supported dev paths must be surfaced.
+    expect(r.guidance).toContain("Docker");
+    expect(r.guidance).toContain('"degrade"');
+    // It must NOT claim to relax enforcement on its own.
+    expect(r.guidance).toContain("REFUSED");
+  });
+
+  it("is NOT enforceable on a Linux host where the live userns probe fails", () => {
+    const r = assessSandboxHostReadiness({
+      caps: { ...LINUX_READY, userNsCreatable: false, netNamespaces: false },
+    });
+    expect(r.enforceable).toBe(false);
+    expect(r.reasons.join(" ")).toContain("user + net namespaces");
+    expect(r.guidance).toContain("degrade");
+  });
+
+  it("flags a missing wrapper and missing prlimit on Linux", () => {
+    const r = assessSandboxHostReadiness({
+      caps: { ...LINUX_READY, wrapper: null, rlimitNative: false },
+    });
+    expect(r.enforceable).toBe(false);
+    expect(r.reasons.join(" ")).toContain("namespace-capable wrapper");
+    expect(r.reasons.join(" ")).toContain("prlimit");
+  });
+});
+
+describe("formatSandboxReadinessBanner", () => {
+  it("returns an empty string when the host is enforceable", () => {
+    const readiness = assessSandboxHostReadiness({ caps: LINUX_READY });
+    expect(formatSandboxReadinessBanner({ readiness })).toBe("");
+  });
+
+  it("frames the guidance with rules + a header when not enforceable", () => {
+    const readiness = assessSandboxHostReadiness({
+      caps: { ...LINUX_READY, platform: "darwin" },
+    });
+    const banner = formatSandboxReadinessBanner({ readiness });
+    expect(banner).toContain("SCRIPT SANDBOX: OS-LEVEL ISOLATION UNAVAILABLE");
+    expect(banner).toContain("=".repeat(78));
+    // The full guidance is still embedded in the banner.
+    expect(banner).toContain(readiness.guidance);
+  });
+});

package/src/script-sandbox/readiness.ts

@@ -0,0 +1,117 @@
+import {
+  detectSandboxCapabilities,
+  type SandboxCapabilities,
+} from "./capabilities";
+
+/**
+ * Whether THIS host can actually enforce the OS-level sandbox layers, plus
+ * developer-facing guidance when it cannot.
+ *
+ * The OS-level isolation (filesystem / network / privilege / resources) is
+ * built on LINUX kernel primitives - unprivileged user + net namespaces via
+ * `bubblewrap`, `prlimit` rlimits, `nftables` / `slirp4netns` egress. On
+ * macOS / Windows (and on a Linux host missing the primitives or with
+ * unprivileged user namespaces blocked) none of that is available, so under
+ * the secure fail-closed default policy (`onUnavailable: "fail"`) the runners
+ * correctly REFUSE every run rather than execute it unsandboxed.
+ *
+ * This assessment lets a process surface that situation ONCE at startup with
+ * actionable guidance, instead of every script run failing with an opaque
+ * "sandbox unavailable" error. It does NOT change the policy or relax
+ * enforcement - the durable global policy remains the single source of truth.
+ */
+export interface SandboxHostReadiness {
+  /**
+   * True when the host can enforce the OS-level sandbox layers (Linux with a
+   * namespace-capable wrapper, creatable user+net namespaces, and `prlimit`).
+   */
+  enforceable: boolean;
+  /** The detected host platform. */
+  platform: SandboxCapabilities["platform"];
+  /**
+   * Human-readable reasons the OS layer cannot be enforced. Empty when
+   * {@link enforceable} is true.
+   */
+  reasons: string[];
+  /**
+   * Multi-line developer/operator guidance: why runs are refused under the
+   * fail-closed default, and the two supported local-development paths
+   * (Docker prod-parity, or an explicit `degrade` policy). Empty string when
+   * {@link enforceable} is true.
+   */
+  guidance: string;
+}
+
+/**
+ * Assess whether the host can enforce the OS-level sandbox, and build the
+ * developer guidance shown when it cannot. Pure over the detected (cached)
+ * capabilities; pass `caps` to test specific hosts.
+ */
+export function assessSandboxHostReadiness({
+  caps = detectSandboxCapabilities(),
+}: { caps?: SandboxCapabilities } = {}): SandboxHostReadiness {
+  const reasons: string[] = [];
+
+  if (caps.platform === "linux") {
+    if (caps.wrapper === null) {
+      reasons.push(
+        "no namespace-capable wrapper found on PATH (install bubblewrap, or nsjail)",
+      );
+    }
+    if (!caps.userNsCreatable) {
+      reasons.push(
+        "unprivileged user + net namespaces cannot be created on this host (kernel toggle off, or blocked by the container seccomp profile - see the bundled seccomp profile + /proc unmask requirement)",
+      );
+    }
+    if (!caps.rlimitNative) {
+      reasons.push("prlimit (util-linux) is not available for resource limits");
+    }
+  } else {
+    reasons.push(
+      `OS-level isolation requires Linux kernel primitives (bubblewrap namespaces, prlimit, nftables); this host is ${caps.platform}`,
+    );
+  }
+
+  const enforceable = reasons.length === 0;
+  if (enforceable) {
+    return { enforceable, platform: caps.platform, reasons, guidance: "" };
+  }
+
+  const guidance = [
+    "Script sandbox: OS-level isolation is UNAVAILABLE on this host:",
+    ...reasons.map((reason) => `  - ${reason}`),
+    'Under the secure fail-closed default policy (onUnavailable: "fail") script runs are REFUSED rather than run unsandboxed. For local development you have two supported options:',
+    "  1. Prod-parity enforcement: run the runtime inside the Linux sandbox container (docker-compose.yml ships the required seccomp profile + /proc unmask). On macOS / Windows this uses Docker Desktop's Linux VM and enforces exactly as production does.",
+    '  2. Fast native dev: set the global Script Sandbox policy to "degrade" in Admin -> Settings -> Script Sandbox. Scripts then run with the PORTABLE SUBSET (wall-clock timeout + output truncation, NO OS isolation) - acceptable for your own dev scripts, never a security boundary.',
+    "Production MUST run on Linux. See docs: developer-guide/security/script-sandbox (Local development).",
+  ].join("\n");
+
+  return { enforceable, platform: caps.platform, reasons, guidance };
+}
+
+/**
+ * Frame the readiness guidance in a high-visibility banner so it stands out in
+ * terminal scrollback even when a multi-process dev runner (e.g. Bun's
+ * `--filter` view, which elides per-task output) interleaves or collapses logs.
+ * Returns the empty string when the host can enforce the sandbox (nothing to
+ * surface).
+ */
+export function formatSandboxReadinessBanner({
+  readiness,
+}: {
+  readiness: SandboxHostReadiness;
+}): string {
+  if (readiness.enforceable) return "";
+  const rule = "=".repeat(78);
+  // The headline is the FIRST line so it carries the logger's level prefix
+  // (e.g. winston `warn:`) and therefore surfaces as a real entry in a log
+  // viewer's alerts/warnings, instead of an empty leading line. The rules +
+  // detailed guidance follow as continuation lines.
+  return [
+    "SCRIPT SANDBOX: OS-LEVEL ISOLATION UNAVAILABLE ON THIS HOST",
+    rule,
+    readiness.guidance,
+    rule,
+    "",
+  ].join("\n");
+}