@sigrun/sigrun 0.2.0 → 0.2.1

package/dist/harness/boot.js

@@ -169,6 +169,12 @@ export async function openHarness(config, options = {}) {
     // I/O here (each file materializes on its first write), so this is
     // pure construction over paths boot already owns.
     const identity = options.identity ?? openIdentityStores(roots);
+    // The caller-supplied host wins (serving spec §1: `serve()` resolves
+    // the ONE effective host — options.host → SIGRUN_LISTEN_HOST →
+    // DEFAULT_LISTEN_HOST — and passes it here). The env read below is
+    // NOT a second source on the serve path (the option is always set
+    // there); it remains for direct `openHarness` callers that never
+    // bind a listener (tests) and must derive the same auth posture.
     const listenHost = options.listenHost ?? env.SIGRUN_LISTEN_HOST ?? "0.0.0.0";
     const methods = effectiveMethods(config.auth, listenHost);
     const isolationState = new IsolationState({

package/dist/harness/builtins.js

@@ -38,7 +38,7 @@ import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parsePackageSpecifier, readPackageName } from "./packages.js";
 /**
- * The four built-ins, in load order (codemode before tool-search: both
+ * The five built-ins, in load order (codemode before tool-search: both
  * wrap pi-durable's own extensions and neither depends on the other, but
  * the order pins the tool-collision story should names ever overlap).
  * Specifiers are the published package names (Task 3) — npm keys a file:

package/dist/harness/seam-host.js

@@ -171,6 +171,18 @@ export function createSeamHost(identity, kinds, bind, sharedStores, perUserTools
                 return true;
             }, context);
         },
+        async peekInteraction(conversationId, callId, context) {
+            // The non-consuming inspection read (release-readiness-2 §1):
+            // the SAME stored projection as snapshotInteraction, with NO
+            // path to takeSecretDelivery — an inspector (the gateway
+            // notifier, outcome edits, answer correlation) can never eat
+            // the owning extension's one-shot raw-secret delivery.
+            const h = await harness(context);
+            const stored = await h.snapshot(InteractionDoc, conversationId, callId, context);
+            if (stored === undefined)
+                return undefined;
+            return asInteractionRecord(stored);
+        },
         async snapshotInteraction(conversationId, callId, context) {
             const h = await harness(context);
             const stored = await h.snapshot(InteractionDoc, conversationId, callId, context);

package/dist/harness/sections/context-files.js

@@ -53,7 +53,7 @@ export const IDENTITY_TEXT = "You are sigrun, an AI assistant running as a persi
  * The persona sigrun ships when no `SOUL.md` exists. A present `SOUL.md`
  * replaces it wholesale; the default is never merged in.
  */
-export const DEFAULT_PERSONA = `You are Sigrun. You choose, and you say why — a valkyrie doesn't dither over the field. You have opinions and you give them straight: if a plan is bad, say it's bad and say what would make it good. Hedging is a way of lying politely.
+export const DEFAULT_PERSONA = `You are Sigrun. You choose, and you say why — choosing is the job, and dithering over the field isn't. You have opinions and you give them straight: if a plan is bad, say it's bad and say what would make it good. Hedging is a way of lying politely.
 
 Match your reply to the weight of the ask. No filler openers, no restating the request, no narrating what the user can already see. When you don't know, say so and name what would settle it.
 

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,7 +24,8 @@
  * 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";
@@ -48,9 +49,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 +177,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 +200,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 +235,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
@@ -170,26 +266,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(),
@@ -227,6 +307,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,