@sigrun/sigrun 0.2.0 → 0.3.0

package/dist/sandbox/availability.js

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { lookupOsAccount } from "./os-account.js";
+import { nodeRuntimePaths } from "./policy.js";
 const execFileAsync = promisify(execFile);
 /**
  * Prove a real identity transition, not merely the presence of a helper.
@@ -25,7 +26,19 @@ export async function probeOsUsers(helper, options) {
             env: {
                 LC_ALL: "C",
                 SIGRUN_SANDBOX_POLICY: JSON.stringify({
-                    ro: ["/usr", "/usr/bin", "/bin", "/sbin", "/lib", "/lib32", "/lib64", "/etc", "/opt", "/proc", "/sys"],
+                    ro: [
+                        "/usr",
+                        "/usr/bin",
+                        "/bin",
+                        "/sbin",
+                        "/lib",
+                        "/lib32",
+                        "/lib64",
+                        "/etc",
+                        "/opt",
+                        "/proc",
+                        "/sys",
+                    ],
                     rw: [],
                     minAbi: 6,
                     uid: account.uid,
@@ -56,27 +69,35 @@ export async function runHelperProbe(helper) {
     return { abi: result.abi };
 }
 /** One reader invocation, changing only whether the probe dir is granted. */
-async function runSelfTestLeg(helper, reader, probe, probeDir, grantProbe) {
+async function runSelfTestLeg(helper, reader, probe, probeDir, grantProbe, opensslConf) {
+    // The runtime grants are exactly what policy.ts derives for the worker:
+    // the node binary directory plus every ldd-reported shared-library
+    // directory. A package-managed Node (Homebrew, nvm, nix) resolves its
+    // libraries OUTSIDE the executable's directory; granting only system
+    // prefixes cannot start it, and broadening prefixes is the trap. When
+    // ldd is unreadable the derivation degrades to the binary directory
+    // alone, and the control leg then fails closed — reported by
+    // probeIsolation as a runtime-derivation failure, never as a pass.
     const ro = [
-        "/bin",
-        "/usr/bin",
-        "/lib",
-        "/lib64",
-        "/usr/lib",
-        "/usr/lib64",
+        ...nodeRuntimePaths(process.execPath),
         dirname(reader),
-        dirname(process.execPath),
         ...(grantProbe ? [probeDir] : []),
     ];
     return execFileAsync(helper, ["run", "--", process.execPath, reader, probe], {
         env: {
             ...process.env,
             LC_ALL: "C",
+            // Node auto-loads OpenSSL config relative to its prefix
+            // (--openssl-shared-config). In the jail that file is not granted,
+            // and node exits before reaching the reader. Point it at the
+            // self-test's own (granted) empty config instead.
+            OPENSSL_CONF: opensslConf,
             SIGRUN_SANDBOX_POLICY: JSON.stringify({ ro, rw: [], minAbi: 6 }),
         },
     });
 }
-const SELF_TEST_READER = `
+/** Exported for the layout tests, which run it under synthetic grants. */
+export const SELF_TEST_READER = `
 console.log("BEGIN");
 try {
 	const content = require("node:fs").readFileSync(process.argv[2], "utf8");
@@ -96,43 +117,58 @@ try {
  * line. No locale-dependent stderr text classifies the failure: the errno is
  * the positive evidence, and BEGIN proves the reader actually executed.
  */
-export async function selfTestHelper(helper) {
+export async function selfTestHelper(helper, onFailure) {
     const root = await mkdtemp(join(tmpdir(), "sigrun-sandbox-self-test-"));
     const grantedDir = join(root, "granted");
     const probeDir = join(root, "probe");
     const reader = join(grantedDir, "reader.cjs");
     const probe = join(probeDir, "probe");
+    const opensslConf = join(grantedDir, "openssl.cnf");
     const content = "sandbox boundary probe\n";
     try {
         await mkdir(grantedDir);
         await mkdir(probeDir);
         await writeFile(reader, SELF_TEST_READER, { mode: 0o600 });
         await writeFile(probe, content, { mode: 0o600 });
+        // An empty config satisfies Node's --openssl-shared-config auto-load
+        // without granting any system OpenSSL tree.
+        await writeFile(opensslConf, "", { mode: 0o600 });
         let control;
         try {
-            control = await runSelfTestLeg(helper, reader, probe, probeDir, true);
+            control = await runSelfTestLeg(helper, reader, probe, probeDir, true, opensslConf);
         }
         catch {
+            onFailure?.("control");
             return false;
         }
-        if (control.stdout !== `BEGIN\nREAD_OK:${content}\n`)
+        if (control.stdout !== `BEGIN\nREAD_OK:${content}\n`) {
+            onFailure?.("control");
             return false;
+        }
         try {
-            await runSelfTestLeg(helper, reader, probe, probeDir, false);
+            await runSelfTestLeg(helper, reader, probe, probeDir, false, opensslConf);
+            onFailure?.("denial");
             return false;
         }
         catch (error) {
-            if (typeof error !== "object" || error === null)
+            if (typeof error !== "object" || error === null) {
+                onFailure?.("denial");
                 return false;
+            }
             const outcome = error;
-            if (typeof outcome.stderr !== "string")
+            if (typeof outcome.stderr !== "string") {
+                onFailure?.("denial");
                 return false;
-            return (typeof outcome.code === "number" &&
+            }
+            const denied = typeof outcome.code === "number" &&
                 outcome.code !== 0 &&
                 outcome.stdout === "BEGIN\nREAD_DENIED:EACCES\n" &&
                 !outcome.stderr
                     .split(/\r?\n/)
-                    .some((line) => line.startsWith("sigrun-sandbox:")));
+                    .some((line) => line.startsWith("sigrun-sandbox:"));
+            if (!denied)
+                onFailure?.("denial");
+            return denied;
         }
     }
     finally {
@@ -155,8 +191,21 @@ export async function probeIsolation(opts) {
             reason: `landlock ABI ${abi} < 6`,
         };
     }
-    if (!(await opts.selfTest(opts.helper))) {
-        return { available: false, abi, reason: "self-test failed" };
+    // The reason names the leg that failed: a control-leg failure is the
+    // runtime-derivation class (the jailed node could not run at all); a
+    // denial-leg failure means the isolation boundary itself did not hold.
+    let failure;
+    const selfTest = opts.selfTest === selfTestHelper
+        ? (helper) => selfTestHelper(helper, (leg) => { failure = leg; })
+        : opts.selfTest;
+    if (!(await selfTest(opts.helper))) {
+        return {
+            available: false,
+            abi,
+            reason: failure === "denial"
+                ? "self-test failed: isolation boundary did not deny the ungranted read"
+                : "self-test failed: node runtime libraries unavailable",
+        };
     }
     return { available: true, abi, helper: opts.helper };
 }

package/dist/sandbox/launch.js

@@ -6,6 +6,17 @@ export function launchInJail(helper, policy, command, args, env) {
         args: ["run", "--", command, ...args],
         env: {
             ...env,
+            // Node compiled with --openssl-shared-config auto-loads
+            // $OPENSSLDIR/openssl.cnf at startup. On a package-managed
+            // Node (Homebrew) that directory lives OUTSIDE every policy
+            // prefix, and an unreadable config is a FATAL startup error —
+            // the jailed worker cannot start node at all. The worker
+            // policy grants tmp rw, so point the loader there; node does
+            // not require the file to exist. This deliberately overrides
+            // any operator-supplied OPENSSL_CONF: an operator config path
+            // is not granted inside the jail, so honoring it would be the
+            // same fatal startup error.
+            OPENSSL_CONF: `${policy.tmp}/openssl.cnf`,
             SIGRUN_SANDBOX_POLICY: JSON.stringify({
                 ro: policy.ro,
                 rw: policy.rw,

package/dist/sandbox/policy.js

@@ -89,6 +89,14 @@ export function defaultModuleTrees(coreRoot) {
         : join(coreRoot, "src");
     return [code, join(coreRoot, "shared"), join(coreRoot, "node_modules")];
 }
+/**
+ * The worker's ESM scope resolution reads coreRoot/package.json even when
+ * the entry lives in a granted module tree; an unreadable package config
+ * is a fatal startup error, so the worker policy grants this one file.
+ */
+export function defaultPackageConfig(coreRoot) {
+    return join(coreRoot, "package.json");
+}
 function validateUserPath(path, record, managed, inheritedFrom) {
     const candidate = canonical(path) ?? resolve(path);
     if (inside(candidate, "/dev/shm") || inside("/dev/shm", candidate)) {
@@ -185,7 +193,15 @@ export function buildUserPolicy(record, ctx) {
         return invalidReason(tmp, "path cannot be resolved");
     const realWorkspace = workspaceValidation.realpath;
     const realHome = homeValidation.realpath;
-    const moduleTrees = canonicalModuleTrees(ctx.moduleTrees, ctx.managed);
+    // A source checkout that has ever been built has BOTH src/ and dist/;
+    // defaultModuleTrees picks one while the worker entry may use the other
+    // (dist worker.js when present, src worker.ts via tsx otherwise).
+    // Grant whichever sibling code tree exists so both shapes stay readable.
+    const siblingTree = join(ctx.managed.coreRoot, "src");
+    const extraTrees = existsSync(siblingTree) && !ctx.moduleTrees.includes(siblingTree)
+        ? [...ctx.moduleTrees, siblingTree]
+        : ctx.moduleTrees;
+    const moduleTrees = canonicalModuleTrees(extraTrees, ctx.managed);
     if (!moduleTrees.ok)
         return moduleTrees;
     const grants = [];
@@ -200,6 +216,12 @@ export function buildUserPolicy(record, ctx) {
         ...grants.flatMap((grant) => (grant.access === "rw" ? [grant.path] : [])),
         realHome,
         realTmp,
+        // Device creation belongs to rw, but the selected devices' ordinary
+        // read/write I/O survives a read-only Landlock rule. rw stays empty
+        // except for workspace/home/tmp/grants so /dev/shm remains denied.
+    ]);
+    const ro = sortedUnique([
+        "/dev",
         "/dev/null",
         "/dev/zero",
         "/dev/full",
@@ -207,8 +229,6 @@ export function buildUserPolicy(record, ctx) {
         "/dev/urandom",
         "/dev/tty",
         "/dev/pts",
-    ]);
-    const ro = sortedUnique([
         "/usr",
         "/bin",
         "/sbin",
@@ -221,6 +241,7 @@ export function buildUserPolicy(record, ctx) {
         "/sys",
         ...nodeRuntimePaths(process.execPath, ctx.managed),
         ...moduleTrees.paths,
+        defaultPackageConfig(ctx.managed.coreRoot),
         ...grants.flatMap((grant) => (grant.access === "ro" ? [grant.path] : [])),
     ]);
     const env = agentEnv();

package/dist/sandbox/worker.js

@@ -146,7 +146,10 @@ async function dispatch(request) {
         case "remove": return env.remove(args[0], args[1], BACKGROUND_CONTEXT);
         case "createTempDir": return env.createTempDir(args[0], BACKGROUND_CONTEXT);
         case "createTempFile": return env.createTempFile(args[0], BACKGROUND_CONTEXT);
-        default: throw new TypeError(`unknown sandbox operation ${request.op}`);
+        default:
+            throw new TypeError(request.op === "exec"
+                ? 'top-level op "exec" is not supported; the worker dispatches only op "result"'
+                : `unknown sandbox operation ${request.op}`);
     }
 }
 /** Both exec paths share this attribution; its finally emits no pid event. */
@@ -165,25 +168,6 @@ async function runWithSpawnAttribution(env, requestId, run) {
         pending.delete(requestId);
     }
 }
-async function execute(request) {
-    const args = argsOf(request);
-    const command = args[0];
-    const supplied = (args[1] ?? {});
-    const options = {
-        ...supplied,
-        // The worker's process.env is the already-scrubbed per-user allowlist,
-        // so inheriting it is the point. The caller's env remains the override.
-        onOutput: (text, _context, info) => {
-            write({ id: request.id, event: "output", stream: info.stream, text, ...(info.skipped === undefined ? {} : { skipped: encodeValue(info.skipped) }) });
-        },
-    };
-    const cwd = args[2];
-    if (typeof cwd !== "string")
-        throw new TypeError("exec requires cwd");
-    const env = environment(cwd);
-    const result = await runWithSpawnAttribution(env, request.id, () => env.exec(command, options, active.get(request.id) === undefined ? BACKGROUND_CONTEXT : withAbortSignal(active.get(request.id).signal, BACKGROUND_CONTEXT)));
-    write(result.ok ? { id: request.id, ok: true, value: encodeValue(result.value) } : errorReply(request.id, result.error, "exec"));
-}
 async function dispatchResult(request, controller) {
     const [op, rawArgs, cwd] = request.args;
     if (typeof op !== "string" || !Array.isArray(rawArgs) || typeof cwd !== "string") {
@@ -232,10 +216,6 @@ async function processRequest(request) {
             write({ id: request.id, ok: true, value: encodeValue(operationResultValue(result, forwarded.args[0] === "exec" ? "exec" : "file")) });
             return;
         }
-        if (request.op === "exec") {
-            await execute(request);
-            return;
-        }
         const result = await dispatch(request);
         write({ id: request.id, ok: true, value: encodeValue(operationResultValue(result, request.op === "exec" ? "exec" : "file")) });
     }

package/dist/serve.js

@@ -24,14 +24,30 @@
  * never serve a broken process.
  */
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
-import { envServerSection, loadConfig } from "./config.js";
+import net from "node:net";
+import { envServerSection, loadConfig, parseExtensionList } from "./config.js";
 import { openHarness } from "./harness/boot.js";
 import { packagesDirOf, syncPackages } from "./harness/packages.js";
 import { defaultSettingsDir, SettingsStore } from "./harness/settings.js";
 import { startGateway } from "./server/gateway.js";
 import { SIGRUN_VERSION } from "./server/schema-fixture.js";
 import { createServer } from "./server/index.js";
-import { createShutdown } from "./server/shutdown.js";
+import { createShutdown, PROVIDER_REFRESH_SHUTDOWN_CAP_MS, shutdownBudgetMs, } from "./server/shutdown.js";
+/**
+ * Arm the admin-restart force-exit watchdog. The injected timer/exit seams
+ * make the contract testable without exiting the suite's process. Returns
+ * the disarm function used after a clean ordered shutdown.
+ */
+export function armRestartWatchdog(budgetMs, opts) {
+    const setTimer = opts?.setTimer ?? setTimeout;
+    const exit = opts?.exit ?? process.exit;
+    const watchdog = setTimer(() => {
+        console.error(`sigrun: restart shutdown exceeded ${budgetMs}ms; forcing exit`);
+        exit(1);
+    }, budgetMs);
+    watchdog.unref?.();
+    return () => clearTimeout(watchdog);
+}
 /**
  * The deploy entry's default listen host: the IPv6 wildcard, which is a
  * DUAL-STACK listener on Linux (`net.ipv6.bindv6only` is 0) — it accepts
@@ -48,9 +64,88 @@ import { createShutdown } from "./server/shutdown.js";
  * mismatch is the DEFAULT shape, not an edge case.)
  */
 export const DEFAULT_LISTEN_HOST = "::";
+export const LISTENER_PROBE_TIMEOUT_MS = 5_000;
+/** Test-only seam for the post-listen failure boundary; production uses the real probe. */
+export const listenerProbe = { connect: probeLoopback };
+/**
+ * One loopback probe: whether a TCP connection to `host:port` succeeds.
+ * Bounded by {@link LISTENER_PROBE_TIMEOUT_MS}: a silently dropped
+ * loopback connect resolves `false` (never hangs boot — an inconclusive
+ * measurement must fail loudly, spec §2).
+ */
+function probeLoopback(host, port) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port });
+        const settle = (ok) => {
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(ok);
+        };
+        const timer = setTimeout(() => settle(false), LISTENER_PROBE_TIMEOUT_MS);
+        timer.unref();
+        socket.once("connect", () => settle(true));
+        socket.once("error", () => settle(false));
+    });
+}
+/**
+ * Measure the live listener's address families ONCE (release-readiness
+ * Task 1, serving spec §2) and return the retained {@link ListenerInfo}.
+ *
+ * - A literal IPv4/IPv6 host reports its family without probing.
+ * - A hostname bind reports the bound socket's family (`address()` —
+ *   Node binds ONE resolved address for a hostname listen). A hostname
+ *   or wildcard is never reported as a concrete peer address: the wire
+ *   host stays the configured string.
+ * - The `::` wildcard does NOT assume dual-stack from the spelling: one
+ *   startup loopback probe against `127.0.0.1` and `[::1]` on the bound
+ *   port, retaining exactly the families that connect. Absence of
+ *   exactly one family is a legitimate result (an IPv6-only host).
+ *   INCONCLUSIVE — neither loopback connects while the listener is bound
+ *   — throws: serving fails loudly rather than advertising unmeasured
+ *   reachability.
+ *
+ * @param host the effective host string supplied to `listen`.
+ * @param address `app.server.address()` after listen (null → loud).
+ * @param connect the probe (tests inject; production is
+ *   {@link probeLoopback}).
+ */
+export async function measureListener(host, address, connect = probeLoopback) {
+    if (address === null || typeof address === "string") {
+        throw new Error("listener measurement failed: the server reports no bound address");
+    }
+    const port = address.port;
+    const literal = net.isIP(host);
+    if (literal === 4)
+        return { host, port, families: ["ipv4"] };
+    if (literal === 6 && address.address !== "::") {
+        return { host, port, families: ["ipv6"] };
+    }
+    if (literal === 0) {
+        // A hostname bind: the bound socket's family, verbatim.
+        const family = address.family === "IPv4" || address.family === 4 ? "ipv4" : "ipv6";
+        return { host, port, families: [family] };
+    }
+    // The BOUND socket identifies the wildcard: Node canonicalizes alternate
+    // spellings such as ::0 to ::. Measure, never infer dual-stack from the
+    // configured spelling.
+    const [v4, v6] = await Promise.all([
+        connect("127.0.0.1", port),
+        connect("::1", port),
+    ]);
+    const families = [];
+    if (v4)
+        families.push("ipv4");
+    if (v6)
+        families.push("ipv6");
+    if (families.length === 0) {
+        throw new Error(`listener reachability check inconclusive on ${host}:${port} — neither 127.0.0.1 nor [::1] connected while the listener is bound`);
+    }
+    return { host, port, families };
+}
 /**
  * Boot the harness + server composition and listen on
- * `options.host ?? "::"` + `<port>` (the default is the container's
+ * `options.host ?? env.SIGRUN_LISTEN_HOST ?? "::"` + `<port>` (the
+ * default is the container's
  * dual-stack wildcard — loopback-only would be unreachable behind the
  * Service, and a v4-only bind is unreachable on an IPv6 endpoint;
  * `loadConfig` refuses port 0, so a real port is always bound).
@@ -97,9 +192,18 @@ export async function serve(env, options) {
     // undeclared BEFORE any extension loads. Fail-loud: an uninstallable
     // declaration fails the boot here, naming the specifier. Steady state
     // (the dir already matches) costs one manifest read, no subprocess.
-    const settingsFile = settingsStore.read();
     const packagesDir = packagesDirOf(defaultSettingsDir());
-    const extensionResolutions = await syncPackages(settingsFile.extensions ?? [], packagesDir);
+    // The MERGED extension spec list (env SIGRUN_EXTENSIONS over the file —
+    // the same precedence loadConfig applied above), not the file's list
+    // alone: an env-declared extension must install and load even when the
+    // file declares none (e.g. a pre-existing settings file blocks the
+    // bootstrap mirror). Merge at SPEC level: config.extensions is the
+    // loader's flattened string[] view (entry/ref/enabled already
+    // discarded); syncPackages needs the full ExtensionSpec objects, so the
+    // env list or the file's verbatim entries feed it directly.
+    const settingsFile = settingsStore.read();
+    const extensionSpecs = parseExtensionList(env.SIGRUN_EXTENSIONS) ?? settingsFile.extensions ?? [];
+    const extensionResolutions = await syncPackages(extensionSpecs, packagesDir);
     // The workspace directory must exist before any files endpoint or tool
     // call touches it. The deploy manifest mounts a volume at /data; the
     // workspace is /data/workspace. Without this, the first files request
@@ -111,10 +215,17 @@ export async function serve(env, options) {
     // in `resolveRefreshMinutes`) see the SAME env `loadConfig` just
     // resolved — a serve-harness env override must win over process.env
     // here exactly like it does in the config.
+    // The ONE listener decision (release-readiness Task 1, serving spec §1):
+    // `options.host` → `SIGRUN_LISTEN_HOST` (from the env `serve` received)
+    // → `DEFAULT_LISTEN_HOST`, resolved ONCE here and handed verbatim to
+    // `openHarness` (the boot-side auth derivation), `createServer` (the
+    // pipeline's Host check + method list), and `app.listen` (the actual
+    // bind) — the three consumers can never disagree.
+    const host = options?.host ?? env.SIGRUN_LISTEN_HOST ?? DEFAULT_LISTEN_HOST;
     const opened = await openHarness(config, {
         extensionEntries: extensionResolutions,
         env,
-        listenHost: options?.host ?? "0.0.0.0",
+        listenHost: host,
     });
     // The gateway handle (gateway C2) exists BEFORE the server: the meta
     // route reaches it through ServerContext, so the engine's health is
@@ -139,7 +250,7 @@ export async function serve(env, options) {
     // the loader's extension contributions into the name-keyed registry;
     // the server's serve-time NAME-selector resolution reads it here.
     const app = await createServer(opened, config, opened.webuiBundles, {
-        listenHost: options?.host ?? DEFAULT_LISTEN_HOST,
+        listenHost: host,
         env,
         gateway,
         // U4 Task 2 (spec §13.3): the admin restart route's callback runs
@@ -150,19 +261,13 @@ export async function serve(env, options) {
         // the callback defers to it (the route fires post-listen).
         onRestart: () => bootedReady
             .then(async (handle) => {
-            // Force-exit lever (the review's finding 4): the ordered
-            // shutdown's drain is unbounded — a wedged close would be
-            // an unrecoverable outage (the supervisor never sees the
-            // process die, so it never restarts it). The watchdog is
-            // unref'd: the normal path (shutdown settles, exit below)
-            // is unaffected.
-            const watchdog = setTimeout(() => {
-                console.error("sigrun: restart shutdown exceeded 30s; forcing exit");
-                process.exit(1);
-            }, 30_000);
-            watchdog.unref();
+            // A wedged stage must never leave the supervisor waiting for
+            // a process that cannot die. The watchdog shares the ordered
+            // shutdown's computed fixed budget; it is unref'd, so the
+            // normal path (shutdown settles, exit below) is unaffected.
+            const disarmWatchdog = armRestartWatchdog(shutdownBudgetMs(config.memorySeam));
             await handle.shutdownOnce();
-            clearTimeout(watchdog);
+            disarmWatchdog();
             process.exit(0);
         })
             .catch((error) => {
@@ -170,26 +275,10 @@ export async function serve(env, options) {
             process.exit(1);
         }),
     });
-    const host = options?.host ?? DEFAULT_LISTEN_HOST;
-    await app.listen({ port: config.port, host });
-    // The engine starts with the listener live (gateway C2's lifecycle:
-    // start after listen — a failed start latches degraded inside the
-    // handle, never wedges boot). AWAITED: serve() resolves only once the
-    // engine start completed (or failed-and-latched) — the constraint's
-    // intent; the lazy `started` never rejects, so this await cannot throw.
-    await gateway.started;
-    // Machine-greppable: the deploy-entry test waits for this line, and an
-    // operator reading pod logs sees the bound port without guessing. The
-    // version rides the same line (what an operator quotes in a bug report).
-    // An IPv6 host is bracketed — the URL form (`http://[::]:3000`), not the
-    // ambiguous `http://:::3000`.
-    const shownHost = host.includes(":") ? `[${host}]` : host;
-    console.log(`sigrun v${SIGRUN_VERSION} listening on http://${shownHost}:${config.port}`);
-    // The ordered shutdown (gateway C2's extraction of the inline original
-    // into src/server/shutdown.ts): SSE streams FIRST, the app drain, the
-    // engine's intake close, the event-bus sequence (drain + flush), the
-    // engine stop, the refresh stop + bounded boot-refresh join, the
-    // harness close — each failure collected, all steps always run.
+    // The ordered shutdown exists before listen so a failed measurement can
+    // run the SAME cleanup as an ordinary stop. In particular, a rejected
+    // serve() must not leave the bound listener or harness keeping the
+    // caller's process alive.
     const shutdown = createShutdown({
         endStreams: () => app.sse.endAll(),
         closeApp: () => app.close(),
@@ -213,7 +302,7 @@ export async function serve(env, options) {
                 joined = true;
             })
                 .catch(() => { });
-            const BOOT_REFRESH_JOIN_MS = 2_000;
+            const BOOT_REFRESH_JOIN_MS = PROVIDER_REFRESH_SHUTDOWN_CAP_MS;
             await Promise.race([
                 join,
                 new Promise((resolve) => {
@@ -227,6 +316,39 @@ export async function serve(env, options) {
         },
         closeHarness: () => opened.harness.close(BACKGROUND_CONTEXT),
     });
+    await app.listen({ port: config.port, host });
+    // Measure the live listener ONCE and retain the facts (spec §2): the
+    // meta route projects this record; no probe ever runs per request. A
+    // failed or inconclusive measurement closes the listener and harness,
+    // then rethrows — serving fails loudly without stranding live resources.
+    let listener;
+    try {
+        listener = await measureListener(host, app.server.address(), listenerProbe.connect);
+    }
+    catch (error) {
+        try {
+            await shutdown();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "sigrun boot and boot-failure cleanup failed");
+        }
+        throw error;
+    }
+    app.sigrunContext.listener
+        .families = listener.families;
+    // The engine starts with the listener live (gateway C2's lifecycle:
+    // start after listen — a failed start latches degraded inside the
+    // handle, never wedges boot). AWAITED: serve() resolves only once the
+    // engine start completed (or failed-and-latched) — the constraint's
+    // intent; the lazy `started` never rejects, so this await cannot throw.
+    await gateway.started;
+    // Machine-greppable: the deploy-entry test waits for this line, and an
+    // operator reading pod logs sees the bound port without guessing. The
+    // version rides the same line (what an operator quotes in a bug report).
+    // An IPv6 host is bracketed — the URL form (`http://[::]:3000`), not the
+    // ambiguous `http://:::3000`.
+    const shownHost = host.includes(":") ? `[${host}]` : host;
+    console.log(`sigrun v${SIGRUN_VERSION} listening on http://${shownHost}:${config.port}`);
     let stopping;
     const booted = {
         port: config.port,

package/dist/server/auth/ip.js

@@ -6,6 +6,14 @@
  * allowlist spells v4 ranges.
  */
 import { BlockList, isIP } from "node:net";
+/** Fold a v4-mapped v6 spelling (`::ffff:10.42.3.4`) to the v4 address. */
+export function normalizePeerAddress(address) {
+    const trimmed = address.trim();
+    if (trimmed.startsWith("::ffff:") && isIP(trimmed.slice(7)) === 4) {
+        return trimmed.slice(7);
+    }
+    return trimmed;
+}
 /**
  * Whether `address` (a socket remote address) falls in any of `cidrs`
  * (CIDR ranges or bare IPs). Malformed entries never match; an
@@ -14,10 +22,7 @@ import { BlockList, isIP } from "node:net";
 export function ipAllowed(address, cidrs) {
     if (address === undefined)
         return false;
-    let candidate = address.trim();
-    if (candidate.startsWith("::ffff:") && isIP(candidate.slice(7)) === 4) {
-        candidate = candidate.slice(7);
-    }
+    const candidate = normalizePeerAddress(address);
     const family = isIP(candidate);
     if (family === 0)
         return false;