@bivy/bivy 0.0.0 → 0.1.0-staging.10

package/dist/runtime/codex-auth.js

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Codex credential materialization.
+//
+// A ChatGPT/Codex subscription a user connects *inside Bivy* lands in the shared
+// node vault as an `openai-codex` OAuth record. The Codex CLI can't
+// read that vault — it authenticates from `OPENAI_API_KEY` or its own
+// `$CODEX_HOME/auth.json` (the file `codex login` writes). This module bridges the
+// gap: it mints the file Codex expects from the vault record, so a subscription
+// connected in Bivy "just works" for Codex with no separate `codex login`.
+//
+// Why it's sound: Pi's `openai-codex` OAuth app IS the Codex CLI's own OAuth app
+// (identical client_id, token endpoint, and scopes — verified against the codex
+// binary), so tokens minted through Bivy are accepted by Codex's backend. The
+// vault stores {access, refresh, expires, accountId} but NOT the `id_token`
+// Codex's auth.json requires; we recover it with a `refresh_token` grant. The
+// original grant used `scope=openid`, so the refresh response carries a fresh
+// `id_token` — the same call Codex itself makes to refresh.
+//
+// Rotation note: OpenAI rotates the refresh token on every grant, so we persist
+// the rotated token back to the vault. We mint only when no auth.json exists yet
+// (Codex then owns and self-refreshes it), which keeps churn to a single grant.
+// The residual edge case — Codex self-refreshing later invalidates the vault's
+// copy for *other* `openai-codex` consumers — is documented; for the common case
+// (the subscription was connected for Codex) there are no other consumers.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createCredentialVault } from "./credential-store.js";
+// Codex's own OAuth app — verified identical to the app Pi's `openai-codex` login
+// uses, so a refresh grant minted here is honored by Codex's backend.
+const CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token";
+/** Resolve Codex's home dir exactly as the CLI (and our rollout reader) does. */
+export function resolveCodexHome() {
+    return process.env.CODEX_HOME?.trim() || path.join(os.homedir(), ".codex");
+}
+/**
+ * Pre-trust a workspace in Codex's `config.toml` so a `bivy run codex` launched
+ * there doesn't stall on the first-run "Do you trust the contents of this
+ * directory?" gate — which, unanswered, blocks Codex before it writes a rollout
+ * (and so blocks "continue as chat" takeover, which resumes by that rollout id).
+ *
+ * We only ADD a missing `[projects."<path>"]` trust entry; we never rewrite or
+ * downgrade an existing one (a user may have deliberately set a different level).
+ * Best-effort and idempotent: any failure just leaves the interactive prompt in
+ * place, exactly as before. Mirrors what choosing "Yes, continue" would persist.
+ */
+export function ensureCodexTrusted(workspace) {
+    const dir = workspace?.trim();
+    if (!dir)
+        return;
+    try {
+        const codexHome = resolveCodexHome();
+        const configFile = path.join(codexHome, "config.toml");
+        let existing = "";
+        try {
+            existing = fs.readFileSync(configFile, "utf8");
+        }
+        catch { /* no config yet — we'll create one */ }
+        // TOML basic-string key: escape backslashes and double quotes.
+        const escaped = dir.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        const header = `[projects."${escaped}"]`;
+        // Already has a table header for this exact path → leave its trust_level be.
+        if (existing.split(/\r?\n/).some((line) => line.trim() === header))
+            return;
+        const prefix = existing.length && !existing.endsWith("\n") ? "\n" : "";
+        const block = `${prefix}\n${header}\ntrust_level = "trusted"\n`;
+        fs.mkdirSync(codexHome, { recursive: true, mode: 0o700 });
+        fs.appendFileSync(configFile, block);
+    }
+    catch { /* best effort — an untrusted prompt is a soft failure, not a hard one */ }
+}
+/** Exchange a refresh token for a fresh token set (incl. the `id_token`). */
+async function refreshCodexTokens(refreshToken) {
+    let res;
+    try {
+        res = await fetch(CODEX_TOKEN_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+                client_id: CODEX_OAUTH_CLIENT_ID,
+            }),
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (!res.ok)
+        return undefined;
+    const j = (await res.json().catch(() => ({})));
+    const idToken = typeof j.id_token === "string" ? j.id_token : "";
+    const accessToken = typeof j.access_token === "string" ? j.access_token : "";
+    const refreshTok = typeof j.refresh_token === "string" ? j.refresh_token : "";
+    const expiresIn = typeof j.expires_in === "number" ? j.expires_in : 0;
+    if (!idToken || !accessToken || !refreshTok)
+        return undefined;
+    return { idToken, accessToken, refreshToken: refreshTok, expiresIn };
+}
+/**
+ * Ensure the Codex CLI has a usable credential file, minting one from Bivy's
+ * vault when needed. Returns the resolved `CODEX_HOME` (so the caller can pin it
+ * on the subprocess env) or `undefined` when there's nothing to do / no vault
+ * credential — in which case the caller's preflight surfaces the actionable
+ * "no credential" error unchanged.
+ *
+ * Idempotent and low-churn: if an `auth.json` already exists (a native
+ * `codex login` or a prior materialization) it is left untouched — Codex owns and
+ * self-refreshes it — so we mint at most once. We write to the *default* Codex
+ * home (never a throwaway dir) so Codex's rollouts stay where the session reader
+ * looks.
+ */
+export async function ensureCodexAuth(credsDir) {
+    const codexHome = resolveCodexHome();
+    const authFile = path.join(codexHome, "auth.json");
+    // Never clobber an existing login (native or previously materialized); Codex
+    // owns and refreshes it. An OPENAI_API_KEY, if present, is handled by preflight.
+    if (fs.existsSync(authFile))
+        return codexHome;
+    if (process.env.OPENAI_API_KEY?.trim())
+        return undefined;
+    const store = createCredentialVault(credsDir);
+    const cred = await store.read("openai-codex").catch(() => undefined);
+    if (!cred || cred.type !== "oauth" || typeof cred.refresh !== "string" || !cred.refresh)
+        return undefined;
+    const refreshed = await refreshCodexTokens(cred.refresh);
+    if (!refreshed)
+        return undefined;
+    // Persist the rotated refresh token back to the vault FIRST — OpenAI rotates it
+    // on every grant, so the previous one is now dead. If we can't persist it, bail
+    // rather than strand the vault on a token we've just invalidated.
+    try {
+        await store.modify("openai-codex", async (current) => ({
+            ...(current ?? cred),
+            type: "oauth",
+            access: refreshed.accessToken,
+            refresh: refreshed.refreshToken,
+            expires: Date.now() + refreshed.expiresIn * 1000,
+        }));
+    }
+    catch {
+        return undefined;
+    }
+    const accountId = typeof cred.accountId === "string" ? cred.accountId : undefined;
+    const authJson = {
+        auth_mode: "chatgpt",
+        OPENAI_API_KEY: null,
+        tokens: {
+            id_token: refreshed.idToken,
+            access_token: refreshed.accessToken,
+            refresh_token: refreshed.refreshToken,
+            account_id: accountId,
+        },
+        last_refresh: new Date().toISOString(),
+    };
+    try {
+        fs.mkdirSync(codexHome, { recursive: true, mode: 0o700 });
+        const tmp = `${authFile}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(authJson, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, authFile);
+    }
+    catch {
+        return undefined;
+    }
+    return codexHome;
+}

package/dist/runtime/codex-preflight.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Codex credential preflight.
+//
+// The Codex CLI authenticates one of two ways: an OpenAI API key read from the
+// `OPENAI_API_KEY` environment variable, or tokens in `CODEX_HOME/auth.json`
+// (default `~/.codex/auth.json`). Bivy's shared credential vault forwards *API
+// keys* to every agent (see credentials.ts), and `codex-auth.ts` mints the
+// auth.json from a connected ChatGPT/Codex *subscription* — so both sign-in kinds
+// now reach Codex.
+//
+// This preflight is the backstop: if neither an API key nor an auth.json is
+// present after that handoff (e.g. no OpenAI sign-in at all, or a saved
+// subscription that could not be refreshed), `codex exec` would fail with the
+// opaque upstream error `unexpected status 401 Unauthorized: Missing bearer or
+// basic authentication in header`. We detect that up front and return a clear,
+// actionable message instead of letting the subprocess spawn and die on a 401.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Path to the Codex CLI's own auth file (`CODEX_HOME/auth.json`, default `~/.codex`). */
+export function codexAuthFile(deps = {}) {
+    const codexHome = (deps.codexHome ?? process.env.CODEX_HOME)?.trim();
+    const base = codexHome ? codexHome : path.join(deps.home ?? os.homedir(), ".codex");
+    return path.join(base, "auth.json");
+}
+/** The user-facing message shown when Codex has no OpenAI credential. */
+export const CODEX_NO_CREDENTIAL_MESSAGE = [
+    "Codex has no OpenAI credential on this node, so it can't start a turn — it would fail with `401 Unauthorized: Missing bearer or basic authentication in header`.",
+    "",
+    "Fix it any of these ways:",
+    "• Connect ChatGPT Plus/Pro (Codex) under Keys & OAuth — Bivy mints Codex's auth file from it automatically, or",
+    "• Add an OpenAI API key under Keys & OAuth — Bivy passes it to Codex as OPENAI_API_KEY, or",
+    "• Run `codex login` on this node to sign in directly.",
+    "",
+    "If you already connected the ChatGPT/Codex subscription in Bivy and still see this, the saved login could not be refreshed — reconnect it under Keys & OAuth.",
+].join("\n");
+/**
+ * Returns a human-readable error when the Codex CLI has no usable OpenAI
+ * credential (no `OPENAI_API_KEY` in the resolved environment and no
+ * `codex login` auth file), or undefined when a credential is present so the
+ * turn should proceed. `env` is the environment the Codex subprocess will run
+ * with (ambient process env + Bivy's vault handoff), so this catches both an
+ * OpenAI API key stored in Bivy and one already present on the node.
+ */
+export function codexCredentialPreflight(env, deps = {}) {
+    if (env.OPENAI_API_KEY?.trim())
+        return undefined;
+    const exists = deps.fileExists ?? ((p) => {
+        try {
+            return fs.existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (exists(codexAuthFile(deps)))
+        return undefined;
+    return CODEX_NO_CREDENTIAL_MESSAGE;
+}

package/dist/runtime/codex-sessions.js

@@ -0,0 +1,279 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Codex on-disk session ("rollout") reader — the read side of adopting a Codex
+// session that was started outside Bivy (e.g. a bare `codex` in a terminal).
+//
+// The Codex CLI ("@openai/codex") persists each session as a JSONL rollout under
+//   $CODEX_HOME/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl
+// (CODEX_HOME defaults to ~/.codex). The first line carries session metadata
+// (id, cwd, timestamp); subsequent lines are response/event items.
+//
+// IMPORTANT — best-effort, and NOT yet verified against a live Codex here:
+// Codex's rollout record shape has changed across versions, so every read is
+// defensive (unknown/malformed lines are skipped, never thrown), and both a
+// wrapped (`{type,payload}`) and a flat record layout are tolerated. This module
+// only *reconstructs history* and *locates* sessions; a governed live resume of a
+// Codex session additionally needs the Codex runtime to gain resume +
+// toolInterception (today it is a non-governing process runtime — see
+// docs/agent-runtimes.md and src/runtime/index.ts `cliAgentInfo`). Unlike Claude,
+// Codex has no stable launch-time session-id flag to pin, so adoption relies on
+// locating the rollout a run produced (see discoverCodexSessionForCwd).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { hasLiveProcessForCwd } from "./native-process-scan.js";
+/** Binary names a live Codex process could be running under (see
+ *  native-process-scan.ts's best-effort cwd match). */
+const CODEX_BIN_NAMES = ["codex"];
+export function codexHome() {
+    return process.env.CODEX_HOME?.trim() || path.join(os.homedir(), ".codex");
+}
+export function codexSessionsDir() {
+    return path.join(codexHome(), "sessions");
+}
+/** Unwrap a `{ type, payload }` envelope, else return the record as-is. */
+function inner(rec) {
+    const r = (rec ?? {});
+    return r.payload && typeof r.payload === "object" ? r.payload : r;
+}
+function toEpoch(value) {
+    if (value == null)
+        return undefined;
+    const ms = new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : undefined;
+}
+/** Recursively collect `rollout-*.jsonl` files under a Codex sessions dir. */
+function findRolloutFiles(root) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // missing/unreadable — best-effort
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile() && /^rollout-.*\.jsonl$/.test(entry.name))
+                out.push(full);
+        }
+    };
+    walk(root);
+    return out;
+}
+/** Session metadata from a rollout's first line (id / cwd / start time). */
+function metaFromFirstLine(line) {
+    try {
+        const rec = JSON.parse(line);
+        const p = inner(rec);
+        const id = typeof p.id === "string" ? p.id : typeof p.session_id === "string" ? p.session_id : undefined;
+        const cwd = typeof p.cwd === "string" ? p.cwd : undefined;
+        const createdAt = toEpoch(p.timestamp ?? rec.timestamp);
+        return { id, cwd, createdAt };
+    }
+    catch {
+        return {};
+    }
+}
+/** Extract plain text from a Codex content field (string or content-block array). */
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((block) => {
+        const b = (block ?? {});
+        if (typeof b.text === "string")
+            return b.text;
+        return "";
+    })
+        .join("")
+        .trim();
+}
+/**
+ * Reconstruct a session's conversation from its rollout file as normalized
+ * RuntimeMessages (role + content + timestamp) — the same shape loadClaudeTranscript
+ * produces, so a reopened Codex session paints prior history the same way. Skips
+ * meta/system/tooling records; keeps user and assistant turns. Best-effort.
+ */
+export function loadCodexTranscriptFile(file) {
+    const messages = [];
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return messages;
+    }
+    for (const line of raw.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const p = inner(rec);
+        // A message item: either {role, content} directly or an item with type "message".
+        const role = p.role ?? (p.type === "message" ? p.role : undefined);
+        if (role !== "user" && role !== "assistant")
+            continue;
+        const content = p.content ?? p.text;
+        const text = textOf(content);
+        if (!text)
+            continue;
+        messages.push({ role, content: text, timestamp: toEpoch(p.timestamp ?? rec.timestamp) ?? Date.now() });
+    }
+    return messages;
+}
+/**
+ * Materialise a **cross-runtime** fork's portable history as a fresh Codex
+ * rollout so `codex ... resume <id>` (the app-server's `thread/resume`) opens on
+ * a copy of the whole conversation — the write-side counterpart to
+ * `loadCodexTranscript`, and Codex's `importHistoryForFork` (fidelity
+ * "replayed"). The rollout is written in the current wrapped layout — a
+ * `session_meta` line then one `response_item` per turn — under the id-addressed
+ * date path Codex uses (`$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl`), the
+ * same shape `loadCodexTranscriptFile` reads back and `discoverCodexSessionForCwd`
+ * locates. Message turns carry a Responses-API `message` item (`input_text` for
+ * the user, `output_text` for the assistant), which reads back through `textOf`.
+ *
+ * IMPORTANT — best-effort, and NOT verified against a live Codex resume here (see
+ * this module's header): Codex's rollout schema is version-variable, so whether a
+ * *synthesised* rollout is fully honored by `thread/resume` depends on the
+ * installed Codex. The fork engine calls this only as its "replayed" tier and
+ * falls back to a seeded continuation prompt if it throws; a node can force that
+ * fallback outright with `BIVY_CODEX_NO_FORK_REPLAY=1` when its Codex build
+ * doesn't accept synthesised rollouts.
+ */
+export function writeCodexRollout(history, cwd) {
+    if (process.env.BIVY_CODEX_NO_FORK_REPLAY === "1") {
+        throw new Error("Codex fork replay disabled (BIVY_CODEX_NO_FORK_REPLAY=1)");
+    }
+    const id = randomUUID();
+    const now = new Date();
+    const iso = now.toISOString();
+    const yyyy = String(now.getUTCFullYear());
+    const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(now.getUTCDate()).padStart(2, "0");
+    const dir = path.join(codexSessionsDir(), yyyy, mm, dd);
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = iso.replace(/[:.]/g, "-").replace(/Z$/, "");
+    const file = path.join(dir, `rollout-${stamp}-${id}.jsonl`);
+    const records = [
+        { type: "session_meta", timestamp: iso, payload: { id, timestamp: iso, cwd, cli_version: "bivy-fork" } },
+        ...history.map((message) => ({
+            type: "response_item",
+            timestamp: iso,
+            payload: {
+                type: "message",
+                role: message.role,
+                content: [{ type: message.role === "user" ? "input_text" : "output_text", text: message.text }],
+            },
+        })),
+    ];
+    fs.writeFileSync(file, records.map((r) => JSON.stringify(r)).join("\n") + "\n");
+    return { sessionFile: id, id };
+}
+/** Enumerate Codex sessions on disk, newest first. Best-effort. */
+export function listCodexSessions() {
+    const sessions = [];
+    for (const file of findRolloutFiles(codexSessionsDir())) {
+        let firstLine = "";
+        let mtime;
+        try {
+            mtime = fs.statSync(file).mtimeMs;
+            const fd = fs.readFileSync(file, "utf8");
+            firstLine = fd.split(/\r?\n/, 1)[0] ?? "";
+        }
+        catch {
+            continue;
+        }
+        const meta = metaFromFirstLine(firstLine);
+        const transcript = loadCodexTranscriptFile(file);
+        // Codex prepends synthetic context turns as the first "user" messages —
+        // `<environment_context>`, `<recommended_plugins>`, `<user_instructions>`,
+        // etc. — which make useless list labels. Prefer the first turn that isn't one
+        // of these XML-ish blocks (i.e. the user's real prompt), falling back to the
+        // first turn only if that's genuinely all there is.
+        const userTurns = transcript.filter((m) => m.role === "user");
+        const contentOf = (m) => String(m?.content ?? "");
+        const isInjectedBlock = (text) => /^<[a-z][\w-]*>/i.test(text.trimStart());
+        const firstUser = userTurns.find((m) => !isInjectedBlock(contentOf(m))) ?? userTurns[0];
+        const firstMessage = firstUser ? contentOf(firstUser).slice(0, 200) : undefined;
+        sessions.push({
+            id: meta.id,
+            file,
+            cwd: meta.cwd,
+            createdAt: meta.createdAt ?? mtime,
+            firstMessage,
+        });
+    }
+    return sessions.sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0));
+}
+/** Load a Codex session's transcript by its session id (searches the store). */
+export function loadCodexTranscript(sessionId) {
+    const match = listCodexSessions().find((s) => s.id === sessionId);
+    return match ? loadCodexTranscriptFile(match.file) : [];
+}
+/**
+ * Delete a Codex session's rollout file by id so a user-initiated delete in the
+ * app actually removes it from Codex's store (`$CODEX_HOME/sessions/**`) — the
+ * read-side counterpart to loadCodexTranscript. Returns true if a rollout was
+ * unlinked. Best-effort: a missing store / already-gone file is not an error.
+ */
+export function deleteCodexSession(sessionId) {
+    const match = listCodexSessions().find((s) => s.id === sessionId);
+    if (!match)
+        return false;
+    try {
+        fs.unlinkSync(match.file);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/**
+ * Locate the Codex session a run produced, for adoption when there is no pinned
+ * id: the newest rollout whose recorded cwd matches `cwd` and that started at/after
+ * `since` (the run-terminal's creation time, minus a small skew). Returns the
+ * session summary or undefined. Best-effort — Codex assigns the id itself, so this
+ * is how a `bivy run codex` session is mapped back to its on-disk rollout.
+ */
+export function discoverCodexSessionForCwd(cwd, since = 0) {
+    const target = path.resolve(cwd);
+    const skewMs = 5_000;
+    return listCodexSessions().find((s) => s.cwd != null && path.resolve(s.cwd) === target && (s.createdAt ?? 0) >= since - skewMs);
+}
+/**
+ * Enumerate Codex's on-disk sessions as bounded discovery metadata (issue
+ * #156's runtime-agnostic discovery/adoption flow — see
+ * native-session-discovery.ts). Every Codex session Codex itself assigned an
+ * id to is resumable via `codex exec resume <id>`, so `resumable` is true
+ * whenever an id was recorded; `active` is a best-effort live-process check
+ * scoped to this session's own cwd, never its transcript content.
+ */
+export function discoverNativeCodexSessions(hasLiveProcess = (cwd) => hasLiveProcessForCwd(cwd, CODEX_BIN_NAMES)) {
+    return listCodexSessions()
+        .filter((s) => Boolean(s.id))
+        .map((s) => ({
+        runtimeId: "codex-approvals",
+        ref: s.id,
+        file: s.file,
+        cwd: s.cwd,
+        updatedAt: s.createdAt,
+        title: s.firstMessage,
+        active: Boolean(s.cwd) && hasLiveProcess(s.cwd),
+        resumable: true,
+    }));
+}

package/dist/runtime/control-plane-location.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+export class ControlPlaneSessionLocationRegistry {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Map a durable row to a routable location, or undefined if not adoptable. */
+    toLocation(row) {
+        if (!row.sessionId || !row.agentServiceAddress)
+            return undefined;
+        const runtimeId = this.options.resolveRuntimeId(row.sessionId);
+        if (!runtimeId)
+            return undefined; // can't route an attach without the runtime id
+        return { sessionId: row.sessionId, agentServiceAddress: row.agentServiceAddress, runtimeId, nodeId: this.options.nodeId };
+    }
+    async lookup(sessionId) {
+        if (!sessionId)
+            return undefined;
+        const rows = await this.options.fetchNodeSessions().catch(() => []);
+        const row = rows.find((r) => r.sessionId === sessionId);
+        return row ? this.toLocation(row) : undefined;
+    }
+    /**
+     * Every adoptable session this node currently owns in the control plane (has a
+     * host address AND a resolvable runtime id). Startup adoption iterates this and
+     * re-attaches to each. Never throws — a fetch failure yields `[]`.
+     */
+    async listNode() {
+        const rows = await this.options.fetchNodeSessions().catch(() => []);
+        const out = [];
+        for (const row of rows) {
+            const location = this.toLocation(row);
+            if (location)
+                out.push(location);
+        }
+        return out;
+    }
+    // Writes are owned by advertiseSessions (the replace-all POST to /node/sessions
+    // is the single writer of session_index); this is a read-through view.
+    async record(_location) {
+        /* no-op: advertise owns control-plane writes */
+    }
+    async forget(_sessionId) {
+        /* no-op: advertise owns control-plane writes */
+    }
+}
+/**
+ * Layers two registries so a lookup prefers the fast, authoritative in-memory
+ * entry (this daemon's own live sessions) and falls through to a shared,
+ * durable one (the control plane) only on a miss — exactly the "in-memory first,
+ * then control-plane" ordering Stage 3 needs so nothing regresses when the
+ * process already knows a session. Writes (`record`/`forget`) go to the primary
+ * (in-memory) layer; the control-plane layer's writes are no-ops by design.
+ */
+export class LayeredSessionLocationRegistry {
+    primary;
+    fallback;
+    constructor(primary, fallback) {
+        this.primary = primary;
+        this.fallback = fallback;
+    }
+    async record(location) {
+        await this.primary.record(location);
+        await this.fallback.record(location);
+    }
+    async lookup(sessionId) {
+        return (await this.primary.lookup(sessionId)) ?? (await this.fallback.lookup(sessionId));
+    }
+    async forget(sessionId) {
+        await this.primary.forget(sessionId);
+        await this.fallback.forget(sessionId);
+    }
+}