sealkeep 0.9.0 → 0.11.1

package/dist/src/ui-server.js

@@ -1,7 +1,9 @@
-import { spawn } from "node:child_process";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { execFile, spawn } from "node:child_process";
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { createLocalApiServer, localApiToken } from "./local-api.js";
+import { promisify } from "node:util";
+import { createLocalApiServer, LOCAL_UI_PROOF_VERSION, localApiToken, localUiBootstrapProof, localUiProof, localUiProofKey, localUiProofKeyPath, } from "./local-api.js";
 /**
  * The GUI, reachable without typing a command.
  *
@@ -11,12 +13,39 @@ import { createLocalApiServer, localApiToken } from "./local-api.js";
  * pointed at it, authenticated, without a person copying a token by hand.
  *
  * This module is the plumbing for that and nothing else. It starts (or finds)
- * the loopback server, builds the URL that carries the token, and launches a
- * browser. Every line printed to a terminal lives in cli.ts, so this stays
+ * the loopback server, mints a short-lived one-use browser ticket, and launches
+ * a browser. Every line printed to a terminal lives in cli.ts, so this stays
  * usable by any surface that is not a terminal — the native shell in §5 v2
  * being the obvious one.
  */
 const LOOPBACK_HOST = "127.0.0.1";
+const execFileAsync = promisify(execFile);
+/**
+ * Process-generation helpers are part of listener ownership, so they must be
+ * both exact and bounded. On a heavily loaded Mac, `ps` can inherit the
+ * service's scheduling class and otherwise wait indefinitely before emitting
+ * one line. A timeout is uncertainty, never evidence that an owner is dead.
+ */
+const PROCESS_IDENTITY_COMMAND_TIMEOUT_MS = 750;
+const PROCESS_IDENTITY_LOOKUP_TIMEOUT_MS = 1_000;
+const processIdentityCommandOptions = {
+    windowsHide: true,
+    timeout: PROCESS_IDENTITY_COMMAND_TIMEOUT_MS,
+    killSignal: "SIGKILL",
+    maxBuffer: 4 * 1024,
+};
+/**
+ * `taskpolicy -B` is PID-only on macOS. Its supported command form is `-a`,
+ * which gives the child application scheduling/resource policy instead of
+ * inheriting an old service definition's background policy. Keep both paths
+ * argument-vector based: no shell parses a PID or command.
+ */
+export function uiPsIdentityCommand(pid, targetPlatform = process.platform) {
+    const args = ["-p", String(pid), "-o", "lstart="];
+    return targetPlatform === "darwin"
+        ? { file: "/usr/sbin/taskpolicy", args: ["-a", "/bin/ps", ...args] }
+        : { file: "ps", args };
+}
 /**
  * The name to show a person, as opposed to the address to bind.
  *
@@ -43,8 +72,6 @@ export const DISPLAY_HOST = "localhost";
  * window on an odd port beats a correct error.
  */
 export const DEFAULT_UI_PORT = 7477;
-/** The hostnames this service answers to, mirrored by ALLOWED_HOSTS in local-api.ts. */
-export const UI_HOSTNAMES = ["localhost", "127.0.0.1", "vault.line", "vault.localhost"];
 /** Loopback round trips are sub-millisecond; anything slower is a listener that has stopped answering. */
 const PROBE_TIMEOUT_MS = 1_500;
 /** How long to wait for an opener to fail before assuming the window is on its way. See openInBrowser. */
@@ -65,40 +92,253 @@ export async function readUiRecord(dataDir) {
         const port = Number(saved?.port);
         if (!Number.isInteger(port) || port < 1 || port > 65_535)
             return null;
-        return { port, pid: Number(saved?.pid) || 0, startedAt: String(saved?.startedAt ?? "") };
+        const owner = saved?.owner === "autopilot" || saved?.owner === "interactive" ? saved.owner : undefined;
+        const requestedPort = Number(saved?.requestedPort);
+        const instanceId = typeof saved?.instanceId === "string" && /^[A-Za-z0-9_-]{16,128}$/.test(saved.instanceId)
+            ? saved.instanceId
+            : undefined;
+        const processIdentity = typeof saved?.processIdentity === "string" && saved.processIdentity.length > 0 && saved.processIdentity.length <= 512
+            ? saved.processIdentity
+            : undefined;
+        return {
+            port,
+            pid: Number(saved?.pid) || 0,
+            startedAt: String(saved?.startedAt ?? ""),
+            ...(owner ? { owner } : {}),
+            ...(Number.isInteger(requestedPort) && requestedPort >= 0 && requestedPort <= 65_535 ? { requestedPort } : {}),
+            ...(instanceId ? { instanceId } : {}),
+            ...(processIdentity ? { processIdentity } : {}),
+        };
     }
     catch {
         return null;
     }
 }
 /**
- * Written in place rather than through a temp file and a rename: a half-written
- * record fails to parse, and failing to parse already means "start a fresh
- * server", which is the safe answer. Atomicity would buy nothing.
+ * Atomically published: a reader sees either the preceding complete owner or
+ * the next complete owner, never a truncated file that could start a second
+ * mutating API server.
  */
 export async function writeUiRecord(dataDir, record) {
     await mkdir(dataDir, { recursive: true, mode: 0o700 });
-    await writeFile(uiRecordPath(dataDir), JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
+    const path = uiRecordPath(dataDir);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
 }
 /**
- * Removes the record only when it still names this server's port. Two servers
- * can exist at once (a second one starts whenever the first is unreachable),
- * and the first to shut down must not delete the survivor's announcement.
+ * Removes the record only when it still names this exact listener generation.
+ * A closing old process must not delete a replacement's announcement.
  */
-export async function clearUiRecord(dataDir, port) {
-    if (port !== undefined) {
+export async function clearUiRecord(dataDir, port, instanceId) {
+    if (port !== undefined || instanceId !== undefined) {
         const recorded = await readUiRecord(dataDir);
-        if (recorded && recorded.port !== port)
+        if (!recorded || (port !== undefined && recorded.port !== port) || (instanceId !== undefined && recorded.instanceId !== instanceId))
             return;
     }
     await rm(uiRecordPath(dataDir), { force: true });
 }
+const uiLeaseDir = (dataDir, lane) => join(dataDir, `ui-${lane}-leases`);
+const pause = (milliseconds) => new Promise((resolve) => {
+    setTimeout(resolve, milliseconds);
+});
+async function readLeaseCandidate(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (typeof value.instanceId !== "string" || !Number.isInteger(value.pid) || !Number.isFinite(value.createdAtMs)
+            || typeof value.processIdentity !== "string" || value.processIdentity.length < 1 || value.processIdentity.length > 512)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Kernel-backed process generation, not merely a reusable PID.
+ *
+ * Listener leases survive SIGKILL by design. A later, unrelated process can be
+ * assigned the same PID, so `kill(pid, 0)` alone turns the dead lease back into
+ * a convincing owner forever. Linux exposes an exact boot id + start tick;
+ * macOS/BSD expose the process start instant through ps; Windows exposes the
+ * same creation instant through PowerShell. Failure is explicit: starting a
+ * second stateful API is less safe than refusing when ownership cannot be
+ * proved.
+ */
+function processLiveness(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return "dead";
+    try {
+        process.kill(pid, 0);
+        return "alive";
+    }
+    catch (error) {
+        return error.code === "ESRCH" ? "dead" : "unknown";
+    }
+}
+export const uiProcessIdentity = async (pid) => {
+    const before = processLiveness(pid);
+    if (before === "dead")
+        return { state: "dead" };
+    if (before === "unknown")
+        return { state: "unknown" };
+    try {
+        if (process.platform === "linux") {
+            const [raw, bootId] = await Promise.all([
+                readFile(`/proc/${pid}/stat`, "utf8"),
+                readFile("/proc/sys/kernel/random/boot_id", "utf8"),
+            ]);
+            const afterName = raw.slice(raw.lastIndexOf(")") + 2).trim().split(/\s+/);
+            const startTicks = afterName[19]; // proc(5) field 22; this slice starts at field 3.
+            if (startTicks && /^\d+$/.test(startTicks) && bootId.trim()) {
+                return { state: "identified", identity: `linux:${bootId.trim()}:${startTicks}` };
+            }
+        }
+        else if (process.platform === "win32") {
+            const command = `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`;
+            const { stdout } = await execFileAsync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], processIdentityCommandOptions);
+            const started = stdout.trim();
+            if (/^\d+$/.test(started))
+                return { state: "identified", identity: `windows:${started}` };
+        }
+        else {
+            const command = uiPsIdentityCommand(pid);
+            const { stdout } = await execFileAsync(command.file, command.args, processIdentityCommandOptions);
+            const started = stdout.trim();
+            if (started)
+                return { state: "identified", identity: `ps:${started}` };
+        }
+    }
+    catch { }
+    // The process can exit between the liveness and identity queries. Only that
+    // confirmed ESRCH makes the lease stale; permission errors and transient
+    // kernel/tool failures remain unknown and therefore fail closed.
+    return processLiveness(pid) === "dead" ? { state: "dead" } : { state: "unknown" };
+};
+/**
+ * Test seams are bounded too: production must remain safe if an OS helper,
+ * filesystem lookup, or injected platform adapter never settles. Unknown is
+ * deliberately fail-closed; only an explicit dead result permits reclaiming
+ * another generation's lease.
+ */
+async function boundedProcessIdentity(lookup, pid) {
+    let timeout;
+    const deadline = new Promise((resolve) => {
+        timeout = setTimeout(() => resolve({ state: "unknown" }), PROCESS_IDENTITY_LOOKUP_TIMEOUT_MS);
+    });
+    try {
+        const result = await Promise.race([
+            Promise.resolve().then(() => lookup(pid)),
+            deadline,
+        ]);
+        if (result.state === "dead" || result.state === "unknown")
+            return result;
+        if (result.state === "identified" && typeof result.identity === "string"
+            && result.identity.length > 0 && result.identity.length <= 512)
+            return result;
+        return { state: "unknown" };
+    }
+    catch {
+        return processLiveness(pid) === "dead" ? { state: "dead" } : { state: "unknown" };
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+async function candidateState(value, lookup = uiProcessIdentity) {
+    const current = await boundedProcessIdentity(lookup, value.pid);
+    if (current.state === "dead")
+        return "stale";
+    if (current.state === "unknown")
+        return "unknown";
+    return current.identity === value.processIdentity ? "current" : "stale";
+}
+async function ownsLease(dataDir, lane, expected, lookup = uiProcessIdentity) {
+    const value = await readLeaseCandidate(join(uiLeaseDir(dataDir, lane), `${expected.instanceId}.json`));
+    return Boolean(value && value.pid === expected.pid && value.processIdentity === expected.processIdentity
+        && value.instanceId === expected.instanceId && await candidateState(value, lookup) === "current");
+}
+/**
+ * Cross-process election for the one stateful local API allowed per vault.
+ *
+ * Each contender owns a uniquely named file, so cleanup never unlinks another
+ * generation. A short contention window lets simultaneous service/UI starts
+ * see the same candidate set; the earliest creation wins and remains present
+ * for the listener lifetime. Later contenders can only borrow its listener.
+ */
+async function acquireUiLease(dataDir, lane, lookup = uiProcessIdentity) {
+    const directory = uiLeaseDir(dataDir, lane);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const instanceId = randomBytes(24).toString("base64url");
+    const path = join(directory, `${instanceId}.json`);
+    // One election may inspect several lease files belonging to the same
+    // process (including its own freshly published candidate). Resolve each PID
+    // generation once so one `ps` delay cannot be multiplied by the file count.
+    const generations = new Map();
+    const lookupOnce = (pid) => {
+        let pending = generations.get(pid);
+        if (!pending) {
+            pending = boundedProcessIdentity(lookup, pid);
+            generations.set(pid, pending);
+        }
+        return pending;
+    };
+    const current = await lookupOnce(process.pid);
+    if (current.state !== "identified")
+        throw new Error("Sealkeep could not verify this process generation, so it refused to start a second stateful local API");
+    const identity = current.identity;
+    const candidate = { instanceId, pid: process.pid, processIdentity: identity, createdAtMs: Date.now() };
+    await writeFile(path, JSON.stringify(candidate) + "\n", { flag: "wx", mode: 0o600 });
+    const release = () => rm(path, { force: true });
+    await pause(80);
+    const entries = await readdir(directory).catch(() => []);
+    const active = [];
+    let uncertain = false;
+    for (const name of entries) {
+        if (!name.endsWith(".json"))
+            continue;
+        const candidatePath = join(directory, name);
+        const value = await readLeaseCandidate(candidatePath);
+        if (!value) {
+            await rm(candidatePath, { force: true }).catch(() => undefined);
+            continue;
+        }
+        const state = await candidateState(value, lookupOnce);
+        if (state === "stale") {
+            await rm(candidatePath, { force: true }).catch(() => undefined);
+            continue;
+        }
+        if (state === "unknown") {
+            uncertain = true;
+            continue;
+        }
+        active.push(value);
+    }
+    if (uncertain) {
+        await release();
+        return null;
+    }
+    active.sort((left, right) => left.createdAtMs - right.createdAtMs || left.instanceId.localeCompare(right.instanceId));
+    if (active[0]?.instanceId !== instanceId) {
+        await release();
+        return null;
+    }
+    return { instanceId, processIdentity: identity, path, release };
+}
 /** Where a person goes. Bound on loopback, named so it can be read and typed. */
 export const uiOrigin = (port, host = DISPLAY_HOST) => `http://${host}:${port}`;
 /** Where this process talks to itself. Always the address, never a name that has to resolve. */
 export const uiProbeOrigin = (port) => `http://${LOOPBACK_HOST}:${port}`;
 /**
- * How the browser gets authenticated: the token rides in the URL fragment.
+ * How the browser gets authenticated: a short-lived one-use ticket rides in
+ * the URL fragment; the permanent bearer never enters opener argv.
  *
  * A fragment is the only part of a URL a browser never transmits. It is not in
  * the request line, so it cannot reach an access log, a proxy, or a Referer
@@ -111,14 +351,10 @@ export const uiProbeOrigin = (port) => `http://${LOOPBACK_HOST}:${port}`;
  * is the terminal step this whole command exists to remove, and it puts the
  * secret in scrollback, in `script` logs, and in any pasted transcript.
  *
- * What this does cost: the URL is an argv of the opener process, so it is
- * visible to `ps` for the few milliseconds that process lives. That is
- * accepted rather than overlooked — the token grants nothing that a local
- * process running as this user does not already have, since it can read
- * <data-dir>/local-api-token directly. Scrollback is the leak that outlives
- * the session; argv is not.
+ * The ticket is visible briefly in opener argv, but it expires after seconds,
+ * is redeemable once, and can only be minted through the owner-only proof key.
  */
-export const uiUrl = (port, token) => `${uiOrigin(port)}/#token=${encodeURIComponent(token)}`;
+export const uiUrl = (port, ticket) => `${uiOrigin(port)}/#ticket=${encodeURIComponent(ticket)}`;
 /**
  * Which command opens a URL here.
  *
@@ -191,35 +427,65 @@ export async function openInBrowser(url, options = {}) {
         child.unref();
     });
 }
-/**
- * Is a Sealkeep local API still listening on `port`, and is it *this* vault's?
- *
- * Two questions, because a recorded port answers neither. A port is reused by
- * whatever process grabs it next, so `/health` first establishes that the
- * listener is one of ours at all. Then a `/v1/status` call carrying this
- * vault's token establishes that it reads the same token file — that is, that
- * it serves this data dir and not a second vault's. 401 is the only answer
- * that means "not this vault": every other status got past the token check,
- * including the 404 a data dir with no vault yet would return.
- */
-export async function servesThisVault(port, token, fetchImpl = fetch) {
+function exactJson(response) {
+    return response.status === 200 && /^application\/json(?:;|$)/i.test(response.headers.get("content-type") ?? "");
+}
+function secretEqual(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export async function servesThisVault(port, credentials, fetchImpl = fetch) {
     try {
-        const health = await fetchImpl(`${uiProbeOrigin(port)}/health`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
-        if (!health.ok)
+        const nonce = randomBytes(32).toString("base64url");
+        const health = await fetchImpl(`${uiProbeOrigin(port)}/health?nonce=${encodeURIComponent(nonce)}`, {
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        if (!exactJson(health))
             return false;
         const body = await health.json().catch(() => null);
-        if (body?.mode !== "local-api")
+        if (!body || Object.keys(body).sort().join(",") !== "instanceId,mode,nonce,ok,port,proof,proofVersion,version")
             return false;
-        const authorized = await fetchImpl(`${uiProbeOrigin(port)}/v1/status`, {
-            headers: { authorization: `Bearer ${token}` },
-            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
-        });
-        return authorized.status !== 401;
+        if (body.ok !== true || body.mode !== "local-api" || body.version !== 1 || body.proofVersion !== LOCAL_UI_PROOF_VERSION
+            || body.nonce !== nonce || body.port !== port || body.instanceId !== credentials.instanceId || typeof body.proof !== "string")
+            return false;
+        return secretEqual(body.proof, localUiProof(credentials.proofKey, nonce, port, credentials.instanceId));
+    }
+    catch {
+        return false;
+    }
+}
+/** Compatibility-only proof that a pre-ticket listener is actually present. */
+async function servesLegacyLocalApi(port, fetchImpl = fetch) {
+    try {
+        const response = await fetchImpl(`${uiProbeOrigin(port)}/health`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        if (!exactJson(response))
+            return false;
+        const body = await response.json().catch(() => null);
+        return Boolean(body && body.ok === true && body.mode === "local-api" && body.version === 1);
     }
     catch {
         return false;
     }
 }
+async function issueBootstrapTicket(port, credentials, fetchImpl = fetch) {
+    const nonce = randomBytes(32).toString("base64url");
+    const proof = localUiBootstrapProof(credentials.proofKey, nonce, port, credentials.instanceId);
+    const response = await fetchImpl(`${uiProbeOrigin(port)}/v1/auth/bootstrap-ticket`, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({ nonce, instanceId: credentials.instanceId, proof }),
+        signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    if (!exactJson(response))
+        throw new Error("The authenticated local UI bootstrap request was refused");
+    const body = await response.json().catch(() => null);
+    if (!body || body.instanceId !== credentials.instanceId || typeof body.ticket !== "string"
+        || !/^[A-Za-z0-9_-]{43}$/.test(body.ticket) || typeof body.expiresAt !== "string") {
+        throw new Error("The local UI returned an invalid bootstrap ticket");
+    }
+    return body.ticket;
+}
 /**
  * Starts the local UI, or points at the one already running for this vault.
  *
@@ -230,7 +496,7 @@ export async function servesThisVault(port, token, fetchImpl = fetch) {
  * what someone typing the command twice actually meant.
  */
 export async function startUi(dataDir, options = {}) {
-    const token = await localApiToken(dataDir);
+    const [token, proofKey] = await Promise.all([localApiToken(dataDir), localUiProofKey(dataDir)]);
     const open = options.open ?? ((url) => openInBrowser(url));
     const wantsBrowser = options.openBrowser ?? true;
     const noBrowser = { opened: false, command: null, declined: true };
@@ -250,44 +516,418 @@ export async function startUi(dataDir, options = {}) {
             return { opened: false, command: null, problem: error instanceof Error ? error.message : "could not open a browser" };
         }
     };
-    const recorded = (options.reuse ?? true) ? await readUiRecord(dataDir) : null;
-    if (recorded && await servesThisVault(recorded.port, token, options.fetchImpl ?? fetch)) {
-        const url = uiUrl(recorded.port, token);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const adopt = async () => {
+        const recorded = await readUiRecord(dataDir);
+        if (!recorded?.instanceId || !await servesThisVault(recorded.port, { proofKey, instanceId: recorded.instanceId }, fetchImpl))
+            return null;
+        const ticket = await issueBootstrapTicket(recorded.port, { proofKey, instanceId: recorded.instanceId }, fetchImpl);
+        const url = uiUrl(recorded.port, ticket);
         return {
-            port: recorded.port, origin: uiOrigin(recorded.port), address: LOOPBACK_HOST, url, reused: true, running: recorded,
+            port: recorded.port,
+            origin: uiOrigin(recorded.port),
+            address: LOOPBACK_HOST,
+            url,
+            reused: true,
+            running: recorded,
+            instanceId: recorded.instanceId,
+            isListening: () => false,
             browser: await launch(url),
-            // Another process owns that server; stopping it from here would close a
-            // window somebody else's terminal claims to be holding open.
-            close: async () => { }
+            close: async () => { },
         };
+    };
+    // `reuse:false` used to create a second stateful API process. That is never
+    // safe: upload/reclaim journals and in-memory transfer ownership are per
+    // vault. Keep accepting the option for source compatibility, but ownership
+    // is now unconditionally singleton.
+    const already = await adopt();
+    if (already)
+        return already;
+    // A pre-ticket release may still own the vault after an in-place upgrade.
+    // It cannot prove its generation, so adopting it would be unsafe; starting a
+    // second stateful API would be worse. Make the owner restart explicit and
+    // leave its record untouched instead of racing the same transfer journal.
+    const legacy = await readUiRecord(dataDir);
+    if (legacy && !legacy.instanceId && await servesLegacyLocalApi(legacy.port, fetchImpl)) {
+        throw new Error("An older Sealkeep local UI still owns this vault; stop or restart it before opening the upgraded UI");
+    }
+    let lease = null;
+    for (let attempt = 0; attempt < 3 && !lease; attempt += 1) {
+        lease = await acquireUiLease(dataDir, "listener", options.processIdentityLookup);
+        if (lease)
+            break;
+        const deadline = Date.now() + PROBE_TIMEOUT_MS * 2;
+        while (Date.now() < deadline) {
+            const borrowed = await adopt();
+            if (borrowed)
+                return borrowed;
+            await pause(25);
+        }
     }
-    const server = createLocalApiServer(dataDir, token);
+    if (!lease)
+        throw new Error("Another Sealkeep process owns this vault's local API but has not become ready yet");
+    const instanceId = lease.instanceId;
+    const server = createLocalApiServer(dataDir, token, {
+        listenerInstanceId: instanceId,
+        onRecoveryPhraseAvailable: options.onRecoveryPhraseAvailable,
+    });
     // The stable port is a preference, not a requirement. Something else holding
     // 7477 is not this user's problem to solve before they can see their vault,
     // so a busy port falls back to whatever is free rather than failing.
     const wanted = options.port ?? DEFAULT_UI_PORT;
-    await new Promise((ready, broken) => {
-        const settle = () => { server.off("error", retry); ready(); };
-        const retry = (error) => {
-            if (wanted === 0 || (error.code !== "EADDRINUSE" && error.code !== "EACCES")) {
-                broken(error);
-                return;
-            }
-            server.once("error", broken);
-            server.listen(0, LOOPBACK_HOST, settle);
-        };
-        server.once("error", retry);
-        server.listen(wanted, LOOPBACK_HOST, settle);
-    });
+    try {
+        await new Promise((ready, broken) => {
+            const settle = () => { server.off("error", retry); ready(); };
+            const retry = (error) => {
+                if (wanted === 0 || (error.code !== "EADDRINUSE" && error.code !== "EACCES")) {
+                    broken(error);
+                    return;
+                }
+                server.once("error", broken);
+                server.listen(0, LOOPBACK_HOST, settle);
+            };
+            server.once("error", retry);
+            server.listen(wanted, LOOPBACK_HOST, settle);
+        });
+    }
+    catch (error) {
+        await lease.release().catch(() => undefined);
+        throw error;
+    }
     const { port } = server.address();
-    await writeUiRecord(dataDir, { port, pid: process.pid, startedAt: new Date().toISOString() });
-    const url = uiUrl(port, token);
+    try {
+        await writeUiRecord(dataDir, {
+            port,
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+            owner: options.owner ?? "interactive",
+            requestedPort: wanted,
+            instanceId,
+            processIdentity: lease.processIdentity,
+        });
+    }
+    catch (error) {
+        await new Promise((done) => server.close(() => done()));
+        await lease.release().catch(() => undefined);
+        throw error;
+    }
+    let ticket;
+    try {
+        ticket = await issueBootstrapTicket(port, { proofKey, instanceId }, fetchImpl);
+    }
+    catch (error) {
+        await new Promise((done) => server.close(() => done()));
+        await clearUiRecord(dataDir, port, instanceId);
+        await lease.release().catch(() => undefined);
+        throw error;
+    }
+    const url = uiUrl(port, ticket);
     return {
-        port, origin: uiOrigin(port), address: server.address().address, url, reused: false, running: null,
+        port, origin: uiOrigin(port), address: server.address().address, url, reused: false, running: null, instanceId,
+        isListening: () => server.listening,
         browser: await launch(url),
         close: async () => {
-            await clearUiRecord(dataDir, port);
             await new Promise((done) => server.close(() => done()));
+            // The lease remains held while the exact generation record is removed,
+            // so no replacement can be published between compare and unlink.
+            await clearUiRecord(dataDir, port, instanceId);
+            await lease.release();
+        }
+    };
+}
+/**
+ * Runtime evidence for the background service's UI lane.
+ *
+ * This is deliberately state, not preference: `daemon --serve-ui` in the
+ * native service definition is the preference. This owner-only record merely
+ * says which process is supervising the listener now, where it actually
+ * landed after a port collision, and why it is retrying if it could not bind.
+ */
+export const uiSupervisorPath = (dataDir) => join(dataDir, "ui-supervisor.json");
+// Same-process close/start overlap is common in tests and service kickstarts.
+// Track the exact generation, never the data directory, so an old close cannot
+// hide a replacement and entries are removed as soon as that close publishes.
+const closingSupervisorInstances = new Set();
+async function readUiSupervisorRecord(dataDir) {
+    try {
+        const value = JSON.parse(await readFile(uiSupervisorPath(dataDir), "utf8"));
+        if (value.version !== 1 || !Number.isInteger(value.pid) || value.pid <= 0)
+            return null;
+        if (typeof value.instanceId !== "string" || !/^[A-Za-z0-9_-]{16,128}$/.test(value.instanceId))
+            return null;
+        if (typeof value.processIdentity !== "string" || value.processIdentity.length < 1 || value.processIdentity.length > 512)
+            return null;
+        if (value.state !== "starting" && value.state !== "running" && value.state !== "retrying" && value.state !== "off")
+            return null;
+        const requestedPort = Number(value.requestedPort);
+        if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65_535)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeUiSupervisorRecord(dataDir, value) {
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    const path = uiSupervisorPath(dataDir);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/** Live truth for CLI/setup status; stale pid/record files never count as available. */
+export async function uiRuntimeStatus(dataDir, options = {}) {
+    const [supervisor, listener, proofKey] = await Promise.all([
+        readUiSupervisorRecord(dataDir),
+        readUiRecord(dataDir),
+        readFile(localUiProofKeyPath(dataDir), "utf8").then((raw) => raw.trim()).catch(() => ""),
+    ]);
+    const listenerAvailable = Boolean(listener?.instanceId && proofKey
+        && await servesThisVault(listener.port, { proofKey, instanceId: listener.instanceId }, options.fetchImpl ?? fetch));
+    const supervisorLeaseIsCurrent = supervisor ? await ownsLease(dataDir, "supervisor", {
+        instanceId: supervisor.instanceId,
+        pid: supervisor.pid,
+        processIdentity: supervisor.processIdentity,
+        createdAtMs: 0,
+    }, options.processIdentityLookup) : false;
+    const supervisorOwnsCurrent = Boolean(supervisor && supervisor.state !== "off"
+        && !closingSupervisorInstances.has(supervisor.instanceId) && supervisorLeaseIsCurrent
+        && (supervisor.state !== "running" || (listenerAvailable && listener && supervisor.port === listener.port
+            && supervisor.listenerPid === listener.pid && supervisor.listenerInstanceId === listener.instanceId)));
+    const supervised = supervisorOwnsCurrent;
+    const available = listenerAvailable;
+    const requestedPort = (supervised ? supervisor?.requestedPort : undefined) ?? listener?.requestedPort ?? DEFAULT_UI_PORT;
+    return {
+        supervised,
+        available,
+        state: available ? "running" : supervised ? "retrying" : "off",
+        requestedPort,
+        port: available ? listener.port : null,
+        origin: available ? uiProbeOrigin(listener.port) : null,
+        address: available ? LOOPBACK_HOST : null,
+        fallback: Boolean(available && requestedPort !== 0 && listener.port !== requestedPort),
+        supervisorPid: supervised ? supervisor.pid : null,
+        listenerPid: available ? listener.pid : null,
+        listenerOwner: available ? listener.owner ?? "interactive" : null,
+        checkedAt: supervised ? supervisor.checkedAt : null,
+        nextRetryAt: supervised && !available ? supervisor.nextRetryAt : null,
+        lastError: supervised && !available ? supervisor.lastError : null,
+    };
+}
+/**
+ * Keeps one authenticated loopback UI available beside Autopilot.
+ *
+ * It opens no window. A live UI already serving this vault is reused and
+ * watched; if that owner later exits, the next bounded check replaces it. An
+ * unrelated process on 7477 is never adopted: startUi falls back to a free
+ * loopback port and the exact port is written to both runtime records.
+ */
+export async function startUiSupervisor(dataDir, options = {}) {
+    const requestedPort = options.port ?? DEFAULT_UI_PORT;
+    if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65_535) {
+        throw new RangeError("UI port must be an integer from 0 to 65535");
+    }
+    const retryMs = Math.max(50, options.retryMs ?? 5_000);
+    const start = options.start ?? startUi;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    let supervisorLease = null;
+    for (let attempt = 0; attempt < 4 && !supervisorLease; attempt += 1) {
+        supervisorLease = await acquireUiLease(dataDir, "supervisor", options.processIdentityLookup);
+        if (supervisorLease)
+            break;
+        const current = await uiRuntimeStatus(dataDir, {
+            fetchImpl: options.fetchImpl,
+            processIdentityLookup: options.processIdentityLookup,
+        });
+        if (current.supervised)
+            break;
+        await pause(50);
+    }
+    if (!supervisorLease) {
+        // A concurrent service owner won the per-vault election. This handle is a
+        // borrower: it can report that owner's truth but may never stop it.
+        const deadline = Date.now() + PROBE_TIMEOUT_MS * 2;
+        while (Date.now() < deadline) {
+            const status = await uiRuntimeStatus(dataDir, {
+                fetchImpl: options.fetchImpl,
+                processIdentityLookup: options.processIdentityLookup,
+            });
+            if (status.supervised)
+                break;
+            await pause(25);
+        }
+        return {
+            owned: false,
+            refresh: () => uiRuntimeStatus(dataDir, {
+                fetchImpl: options.fetchImpl,
+                processIdentityLookup: options.processIdentityLookup,
+            }),
+            status: () => uiRuntimeStatus(dataDir, {
+                fetchImpl: options.fetchImpl,
+                processIdentityLookup: options.processIdentityLookup,
+            }),
+            close: async () => { },
+        };
+    }
+    const supervisorInstanceId = supervisorLease.instanceId;
+    const startedAt = new Date().toISOString();
+    let handle = null;
+    let closed = false;
+    let timer = null;
+    let inFlight = null;
+    const publish = async (patch) => {
+        if (closed)
+            return;
+        const prior = await readUiSupervisorRecord(dataDir);
+        const now = new Date().toISOString();
+        await writeUiSupervisorRecord(dataDir, {
+            version: 1,
+            instanceId: supervisorInstanceId,
+            pid: process.pid,
+            processIdentity: supervisorLease.processIdentity,
+            state: "starting",
+            requestedPort,
+            port: null,
+            listenerPid: null,
+            listenerOwner: null,
+            listenerInstanceId: null,
+            ownsListener: false,
+            startedAt: prior?.instanceId === supervisorInstanceId ? prior.startedAt : startedAt,
+            checkedAt: now,
+            nextRetryAt: null,
+            lastError: null,
+            ...patch,
+        });
+    };
+    const ensure = async () => {
+        if (closed)
+            return;
+        if (handle) {
+            // A listener created by this supervisor has a stronger, synchronous
+            // source of truth than an HTTP round trip through its own event loop.
+            // On a large vault a dashboard request may occupy that loop for longer
+            // than PROBE_TIMEOUT_MS even though the socket and server are healthy.
+            // Closing on that timeout used to interrupt the browser's one-use ticket
+            // redemption, producing a visible connected/disconnected loop. Only a
+            // borrowed listener needs the authenticated cross-process probe.
+            const listenerResponding = !handle.reused && handle.isListening()
+                ? true
+                : await readFile(localUiProofKeyPath(dataDir), "utf8")
+                    .then((raw) => raw.trim())
+                    .then((proofKey) => Boolean(proofKey) && servesThisVault(handle.port, { proofKey, instanceId: handle.instanceId }, fetchImpl))
+                    .catch(() => false);
+            if (listenerResponding) {
+                await publish({
+                    state: "running",
+                    port: handle.port,
+                    listenerPid: handle.reused ? handle.running?.pid ?? null : process.pid,
+                    listenerOwner: handle.reused ? handle.running?.owner ?? "interactive" : "autopilot",
+                    listenerInstanceId: handle.instanceId,
+                    ownsListener: !handle.reused,
+                });
+                return;
+            }
+            if (!handle.reused)
+                await handle.close().catch(() => undefined);
+            handle = null;
+        }
+        await publish({ state: "starting" });
+        try {
+            const next = await start(dataDir, {
+                port: requestedPort,
+                openBrowser: false,
+                reuse: true,
+                owner: "autopilot",
+                fetchImpl,
+                onRecoveryPhraseAvailable: options.onRecoveryPhraseAvailable,
+                processIdentityLookup: options.processIdentityLookup,
+            });
+            if (closed) {
+                if (!next.reused)
+                    await next.close().catch(() => undefined);
+                return;
+            }
+            handle = next;
+            await publish({
+                state: "running",
+                port: next.port,
+                listenerPid: next.reused ? next.running?.pid ?? null : process.pid,
+                listenerOwner: next.reused ? next.running?.owner ?? "interactive" : "autopilot",
+                listenerInstanceId: next.instanceId,
+                ownsListener: !next.reused,
+            });
+        }
+        catch (error) {
+            const nextRetryAt = new Date(Date.now() + retryMs).toISOString();
+            await publish({
+                state: "retrying",
+                nextRetryAt,
+                lastError: error instanceof Error ? error.message.split("\n")[0] : "local UI could not start",
+            }).catch(() => undefined);
         }
     };
+    const refresh = async () => {
+        if (!inFlight) {
+            const current = ensure();
+            inFlight = current;
+            // Observe both outcomes on this housekeeping branch. `finally()` would
+            // create a second rejecting promise and turn a handled write error into
+            // an unhandled rejection in the long-running service.
+            void current.then(() => { if (inFlight === current)
+                inFlight = null; }, () => { if (inFlight === current)
+                inFlight = null; });
+        }
+        const current = inFlight;
+        if (current)
+            await current;
+        return uiRuntimeStatus(dataDir, { fetchImpl, processIdentityLookup: options.processIdentityLookup });
+    };
+    await refresh();
+    timer = setInterval(() => { void refresh().catch(() => undefined); }, retryMs);
+    timer.unref?.();
+    let closeInFlight = null;
+    return {
+        owned: true,
+        refresh,
+        status: () => uiRuntimeStatus(dataDir, { fetchImpl, processIdentityLookup: options.processIdentityLookup }),
+        close: () => {
+            if (closeInFlight)
+                return closeInFlight;
+            closeInFlight = (async () => {
+                closed = true;
+                closingSupervisorInstances.add(supervisorInstanceId);
+                if (timer)
+                    clearInterval(timer);
+                timer = null;
+                await inFlight?.catch(() => undefined);
+                const owned = handle && !handle.reused ? handle : null;
+                handle = null;
+                await owned?.close().catch(() => undefined);
+                const current = await readUiSupervisorRecord(dataDir);
+                if (current?.instanceId === supervisorInstanceId) {
+                    await writeUiSupervisorRecord(dataDir, {
+                        ...current,
+                        state: "off",
+                        port: null,
+                        listenerPid: null,
+                        listenerOwner: null,
+                        listenerInstanceId: null,
+                        ownsListener: false,
+                        checkedAt: new Date().toISOString(),
+                        nextRetryAt: null,
+                        lastError: null,
+                    }).catch(() => undefined);
+                }
+                await supervisorLease.release().catch(() => undefined);
+                closingSupervisorInstances.delete(supervisorInstanceId);
+            })();
+            return closeInFlight;
+        },
+    };
 }