@sigrun/sigrun 0.1.6 → 0.2.1

package/dist/sandbox/worker.js

@@ -0,0 +1,261 @@
+/** Child entry: serve pi-durable's own environment over stdin/stdout. */
+import { BACKGROUND_CONTEXT, withAbortSignal } from "@earendil-works/chord/context";
+import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+import { createCommandObserver } from "./command-observer.js";
+import { decodeValue, encodeMessage, encodeValue, errorReply, wireError, } from "./protocol.js";
+const environments = new Map();
+/** Exec requests that have not reached pi-durable's synchronous spawn yet. */
+const pendingSpawns = new Map();
+/** One ownership observer per environment, shared by all its execs. */
+const commandObservers = new Map();
+const handles = new Map();
+const active = new Map();
+let nextHandle = 1;
+let buffer = "";
+function environment(cwd) {
+    let env = environments.get(cwd);
+    if (env === undefined) {
+        env = new NodeExecutionEnv({ cwd });
+        observeCommands(env);
+        environments.set(cwd, env);
+    }
+    return env;
+}
+/**
+ * Install ONE permanent observer per environment. This deliberately depends
+ * on pi-durable 1.3.0's PRIVATE, UNDOCUMENTED activeChildPids field because
+ * ExecutionEnv exposes no spawn notification. An upgrade that removes or
+ * changes that field must update this observer; fail loudly rather than
+ * silently losing crash cleanup.
+ */
+function observeCommands(env) {
+    // SAFETY: this is the intentional private-field dependency described above.
+    const registry = env.activeChildPids;
+    if (!(registry instanceof Set)) {
+        throw new Error("pi-durable activeChildPids is unavailable; sandbox command cleanup cannot be tracked");
+    }
+    commandObservers.set(env, createCommandObserver({
+        registry,
+        pending: () => pendingSpawns.get(env) ?? new Set(),
+        active: () => new Set(active.keys()),
+        emit: ({ id, pid, phase }) => write({ id, event: "command", pid, phase }),
+    }));
+}
+function write(message) {
+    // SAFETY: skipped is the exact ShellOutputSkip shape emitted by pi-durable;
+    // JsonValue is only the wider transport representation accepted by the encoder.
+    process.stdout.write(encodeMessage(message));
+}
+function argsOf(request) {
+    return request.args.map((arg) => decodeValue(arg));
+}
+function handleId(value) {
+    const id = typeof value === "object" && value !== null && "$handle" in value
+        ? value.$handle
+        : value;
+    if (typeof id !== "number" || !handles.has(id))
+        throw new Error("worker handle is closed");
+    return id;
+}
+function openHandle(handle) {
+    const id = nextHandle++;
+    handles.set(id, handle);
+    return { $handle: id };
+}
+async function handleCall(request, args) {
+    const id = handleId(args[0]);
+    const handle = handles.get(id);
+    const method = request.op.slice("handle.".length);
+    if (method === "close") {
+        handles.delete(id);
+        await handle.value.close(BACKGROUND_CONTEXT);
+        return null;
+    }
+    if (handle.kind === "text" && method === "readLine") {
+        return handle.value.readLine(BACKGROUND_CONTEXT);
+    }
+    if (handle.kind === "binary" && method === "info") {
+        return handle.value.info(BACKGROUND_CONTEXT);
+    }
+    if (handle.kind === "binary" && method === "read") {
+        return handle.value.read(args[1], args[2], BACKGROUND_CONTEXT);
+    }
+    if (handle.kind === "binary" && method === "scanLines") {
+        return handle.value.scanLines(args[1], BACKGROUND_CONTEXT);
+    }
+    if (handle.kind === "dir" && method === "next") {
+        return handle.value.next(args[1], BACKGROUND_CONTEXT);
+    }
+    throw new TypeError(`unsupported handle operation ${request.op}`);
+}
+async function dispatch(request) {
+    const args = argsOf(request);
+    if (request.op.startsWith("handle."))
+        return handleCall(request, args);
+    if (request.op === "hello") {
+        return { capabilities: { listFiles: "listFiles" in NodeExecutionEnv.prototype } };
+    }
+    if (request.op === "pid")
+        return process.pid;
+    const cwd = args.at(-1);
+    if (typeof cwd !== "string")
+        throw new TypeError(`${request.op} requires cwd`);
+    const env = environment(cwd);
+    switch (request.op) {
+        case "absolutePath": return env.absolutePath(args[0], BACKGROUND_CONTEXT);
+        case "joinPath": return env.joinPath(args[0], BACKGROUND_CONTEXT);
+        case "readTextFile": return env.readTextFile(args[0], BACKGROUND_CONTEXT);
+        case "openTextLineReader": {
+            const result = await env.openTextLineReader(args[0], BACKGROUND_CONTEXT);
+            return result.ok ? { ok: true, value: openHandle({ kind: "text", value: result.value }) } : result;
+        }
+        case "readTextLines": return env.readTextLines(args[0], args[1], BACKGROUND_CONTEXT);
+        case "readBinaryFile": return env.readBinaryFile(args[0], BACKGROUND_CONTEXT);
+        case "openBinaryReader": {
+            const result = await env.openBinaryReader(args[0], args[1], BACKGROUND_CONTEXT);
+            return result.ok ? { ok: true, value: openHandle({ kind: "binary", value: result.value }) } : result;
+        }
+        case "writeFile": return env.writeFile(args[0], args[1], BACKGROUND_CONTEXT);
+        case "appendFile": return env.appendFile(args[0], args[1], BACKGROUND_CONTEXT);
+        case "truncateFile": return env.truncateFile(args[0], args[1], BACKGROUND_CONTEXT);
+        case "flushFile": return env.flushFile(args[0], BACKGROUND_CONTEXT);
+        case "renameFile": return env.renameFile(args[0], args[1], BACKGROUND_CONTEXT);
+        case "fileInfo": return env.fileInfo(args[0], BACKGROUND_CONTEXT);
+        case "listDir": return env.listDir(args[0], BACKGROUND_CONTEXT);
+        case "listFiles": {
+            // NodeExecutionEnv gained this optional member after 1.3.0; the
+            // structural view keeps this worker compatible with both shapes.
+            const listing = env;
+            if (listing.listFiles === undefined)
+                throw new Error("listFiles is not supported");
+            return listing.listFiles(args[0], args[1], BACKGROUND_CONTEXT);
+        }
+        case "openDirReader": {
+            const result = await env.openDirReader(args[0], BACKGROUND_CONTEXT);
+            return result.ok ? { ok: true, value: openHandle({ kind: "dir", value: result.value }) } : result;
+        }
+        case "watch": {
+            const result = await env.watch(args[0], (change) => write({ id: request.id, event: "watch", change: encodeValue("error" in change ? { error: wireError(change.error) } : change) }), BACKGROUND_CONTEXT);
+            return result.ok
+                ? { ok: true, value: { handle: openHandle({ kind: "watch", value: result.value }), mode: result.value.mode } }
+                : result;
+        }
+        case "canonicalPath": return env.canonicalPath(args[0], BACKGROUND_CONTEXT);
+        case "exists": return env.exists(args[0], BACKGROUND_CONTEXT);
+        case "createDir": return env.createDir(args[0], args[1], BACKGROUND_CONTEXT);
+        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(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. */
+async function runWithSpawnAttribution(env, requestId, run) {
+    let pending = pendingSpawns.get(env);
+    if (pending === undefined) {
+        pending = new Set();
+        pendingSpawns.set(env, pending);
+    }
+    pending.add(requestId);
+    try {
+        return await run();
+    }
+    finally {
+        // processRequest's settlement sweep owns end events, not this finally.
+        pending.delete(requestId);
+    }
+}
+async function dispatchResult(request, controller) {
+    const [op, rawArgs, cwd] = request.args;
+    if (typeof op !== "string" || !Array.isArray(rawArgs) || typeof cwd !== "string") {
+        throw new TypeError("result requires op, args and cwd");
+    }
+    if (op === "exec") {
+        const args = rawArgs.map((arg) => decodeValue(arg));
+        const supplied = (args[1] ?? {});
+        const options = {
+            ...supplied,
+            onOutput: (text, _context, info) => {
+                write({ id: request.id, event: "output", stream: info.stream, text, ...(info.skipped === undefined ? {} : { skipped: encodeValue(info.skipped) }) });
+            },
+        };
+        const env = environment(cwd);
+        return runWithSpawnAttribution(env, request.id, () => env.exec(args[0], options, withAbortSignal(controller.signal, BACKGROUND_CONTEXT)));
+    }
+    return dispatch({ id: request.id, op, args: [...rawArgs, cwd] });
+}
+function operationResultValue(result, fallbackKind) {
+    if (typeof result === "object" && result !== null && "ok" in result && typeof result.ok === "boolean") {
+        if (result.ok)
+            return result;
+        if ("error" in result)
+            return { ok: false, error: wireError(result.error, fallbackKind) };
+    }
+    if (result === undefined)
+        return null;
+    if (typeof result === "string" || typeof result === "number" || typeof result === "boolean" || typeof result === "object")
+        return result;
+    throw new TypeError("unsupported operation result");
+}
+async function processRequest(request) {
+    if (request.id === 0 && request.op === "abort") {
+        const target = request.args[0];
+        if (typeof target === "number")
+            active.get(target)?.abort();
+        return;
+    }
+    const controller = new AbortController();
+    active.set(request.id, controller);
+    try {
+        if (request.op === "result") {
+            const forwarded = { id: request.id, op: "result.dispatch", args: request.args };
+            const result = await dispatchResult(forwarded, controller);
+            write({ id: request.id, ok: true, value: encodeValue(operationResultValue(result, forwarded.args[0] === "exec" ? "exec" : "file")) });
+            return;
+        }
+        const result = await dispatch(request);
+        write({ id: request.id, ok: true, value: encodeValue(operationResultValue(result, request.op === "exec" ? "exec" : "file")) });
+    }
+    catch (error) {
+        write(errorReply(request.id, error, request.op === "exec" ? "exec" : "file"));
+    }
+    finally {
+        active.delete(request.id);
+        // pi-durable removes a pid BEFORE the exec promise resolves. The
+        // registry hook therefore sees the request still active; this is the
+        // settlement boundary that forgets ordinary pids and emits their end.
+        for (const observer of commandObservers.values())
+            observer.settleRequest(request.id);
+    }
+}
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    for (;;) {
+        const newline = buffer.indexOf("\n");
+        if (newline < 0)
+            break;
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (line.trim() === "")
+            continue;
+        try {
+            void processRequest(JSON.parse(line));
+        }
+        catch (error) {
+            process.stderr.write(`sandbox worker request error: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
+});
+process.stdin.on("end", () => {
+    for (const controller of active.values())
+        controller.abort();
+    for (const env of environments.values())
+        void env.cleanup(BACKGROUND_CONTEXT);
+    for (const handle of handles.values())
+        void handle.value.close(BACKGROUND_CONTEXT);
+    process.exit(0);
+});

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";
@@ -32,10 +33,106 @@ 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";
+/**
+ * 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
+ * the pod's IPv4 connections AND its IPv6 ones.
+ *
+ * `0.0.0.0` is the WRONG default for a dual-stack cluster: it is a
+ * v4-only socket, so it refuses every IPv6 connection, while a Service
+ * whose `ipFamilies` is `["IPv6"]` advertises only the pod's IPv6
+ * address in its EndpointSlice. The gateway dials that address, gets
+ * connection-refused, and answers the browser with "upstream connect
+ * error or disconnect/reset before headers. reset reason: remote
+ * connection failure". (This cluster's ClusterIP range is
+ * `fd00:beef:cafe::/…`, so a chart-default Service is IPv6-only — the
+ * 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 ?? "0.0.0.0"` + `<port>` (the default is the container's
- * address — loopback-only would be unreachable behind the Service;
+ * `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).
  * The CLI's `run` additionally launches the TUI against the loopback URL
  * on {@link BootedServer.port}.
@@ -80,52 +177,108 @@ 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
     // 404s forever (the directory was never created).
     const { mkdir } = await import("node:fs/promises");
     await mkdir(config.workspace.path, { recursive: true });
-    const opened = await openHarness(config, { extensionEntries: extensionResolutions });
+    // The serve env threads into boot so boot-time env reads (store
+    // roots, the provider collector, the U4 scheduler cadence resolution
+    // 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: host,
+    });
     // The gateway handle (gateway C2) exists BEFORE the server: the meta
     // route reaches it through ServerContext, so the engine's health is
     // reportable from the first request. The ENGINE STARTS after listen
     // (below) — an engine supervising chat transports starts once the
     // server it delivers through is up.
     const gateway = startGateway(opened);
+    // The booted handle the restart callback defers to: `createServer`
+    // needs the callback BEFORE `serve` can build the BootedServer (the
+    // shutdown composition lives at the bottom of this function), so the
+    // handle is promised here and RESOLVED at return time; `onRestart`
+    // awaits the resolution. Between `app.listen` + `gateway.started` and
+    // the assignment below a supervised admin POST can already land (202
+    // answered, callback deferred) — awaiting the promise holds that
+    // window open instead of dropping the restart on the floor (a `?.`
+    // on an unassigned ref made 202-with-no-restart reachable).
+    let resolveBooted;
+    const bootedReady = new Promise((resolve) => {
+        resolveBooted = resolve;
+    });
     // The contributed-bundle registry (build-and-webui Task 6): boot folded
     // 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 ?? "0.0.0.0",
+        listenHost: host,
         env,
         gateway,
+        // U4 Task 2 (spec §13.3): the admin restart route's callback runs
+        // EXACTLY the SIGTERM path (the ordered shutdown), then exits 0 —
+        // the supervisor (chart/compose, `server.supervised`) brings the
+        // process back. `shutdownOnce` is the same re-entry guard the
+        // signal path uses; `stopping` is assigned by closure below, so
+        // 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();
+            await handle.shutdownOnce();
+            clearTimeout(watchdog);
+            process.exit(0);
+        })
+            .catch((error) => {
+            console.error("sigrun restart error:", error);
+            process.exit(1);
+        }),
     });
-    const host = options?.host ?? "0.0.0.0";
-    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).
-    console.log(`sigrun v${SIGRUN_VERSION} listening on http://${host}:${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(),
         gateway,
         eventBusShutdown: () => opened.eventBus.shutdownSequence(BACKGROUND_CONTEXT),
+        stopSandboxWorkers: async () => {
+            await opened.sandboxPool.stopAll();
+            await opened.userServices.stopAll();
+        },
         stopProviderRefresh: async () => {
             // The interval refresh scheduler (provider plugins Task 5) stops
             // BEFORE the harness closes. The T4 boot refresh promise is raced
@@ -154,8 +307,41 @@ 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;
-    return {
+    const booted = {
         port: config.port,
         shutdown,
         shutdownOnce: () => {
@@ -163,4 +349,6 @@ export async function serve(env, options) {
             return stopping;
         },
     };
+    resolveBooted(booted);
+    return booted;
 }

package/dist/server/auth/access-principal.js

@@ -0,0 +1,16 @@
+/** Project the authenticated caller into the shared access rule. */
+import { storedGroups } from "../../harness/identity/groups.js";
+import { isSuperuser } from "./principal.js";
+/**
+ * Read the CURRENT directory record on every access decision: stored group
+ * changes therefore apply immediately. Absent records (including anonymous
+ * callers) contribute no groups.
+ */
+export function accessPrincipalOf(principal, users) {
+    const record = principal.user === undefined ? undefined : users.get(principal.user);
+    return {
+        user: principal.user,
+        superuser: isSuperuser(principal),
+        ...(record === undefined ? {} : { groups: storedGroups(record) }),
+    };
+}