slidemind 0.3.20 → 0.4.0

package/src/workspace/lifecycle.mjs

@@ -0,0 +1,635 @@
+// Start / reuse / stop the workspace process.
+//
+// The descriptor (`<sessionConfigDir>/workspace/daemon.json`) is the ONLY
+// evidence of a running workspace, and it is trusted only after a live probe:
+// GET /health for the protocol (and whether it is draining), then the
+// bearer-authenticated status route, whose `nonce` must match the descriptor.
+// Port occupancy proves nothing — an unrelated service on 57103 (or on the
+// workspace's remembered port) is neither reused nor terminated.
+//
+// A workspace that accepts the connection and then says nothing (hung — a
+// refused one is simply gone) is asked once more, patiently; still silent, its
+// pid is signalled only when `ps` proves it is this install's daemon AND the
+// process that wrote the descriptor (POSIX). Anything less certain — a dead
+// pid, one the OS reused, Windows — is never signalled: a fresh workspace
+// starts beside it instead, and nothing here can block every start.
+//
+// Who serves: the newer code. A CLI newer than the running workspace (semver,
+// then the source mtime of a dev checkout) drains and replaces it; an older CLI
+// reuses the newer workspace, so two installs never take turns replacing each
+// other. A workspace on a newer protocol is `cli_update_required`.
+//
+// Concurrent starts serialize on an exclusive `start.lock` directory that names
+// its owner pid; a lock whose owner died is reclaimed at once, any other after
+// 30 s. The loser finds the winner's live descriptor.
+
+import { execFileSync, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compareCliVersions } from "../bridge/client/transport.mjs";
+import { readPackageJson, resolveDecksDir } from "../cli/common.mjs";
+import { updateCliInstruction } from "../install-channel.mjs";
+import { addDeck, coded, workspaceConfigDir } from "./registry.mjs";
+import { PROTOCOL_VERSION } from "./server.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DAEMON_ENTRY = path.join(__dirname, "daemon.mjs");
+
+export const START_DEADLINE_MS = 10_000;
+const START_LOCK_STALE_MS = 30_000;
+const PROBE_TIMEOUT_MS = 1_500;
+// a workspace that missed the first probe gets this long before it counts as hung
+const REPROBE_TIMEOUT_MS = 4_000;
+// how long a stopping workspace may take to leave (drain is capped at 5 s)
+const EXIT_WAIT_MS = 8_000;
+const TERM_GRACE_MS = 4_000;
+const LOG_CAP = 5 * 1024 * 1024;
+const LOG_KEEP = 2;
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * What code a daemon runs: the CLI version plus the newest mtime under `src/`.
+ * A daemon outlives the checkout it started from (an upgrade, a local edit);
+ * `ensureRunning` compares stamps to decide which side is newer.
+ */
+export function codeStamp() {
+  const src = path.join(__dirname, "..");
+  let newest = 0;
+  for (const f of fs.readdirSync(src, { recursive: true })) {
+    if (f.endsWith(".mjs") || f.endsWith(".js")) newest = Math.max(newest, fs.statSync(path.join(src, f)).mtimeMs);
+  }
+  return `${readPackageJson().version}+${Math.floor(newest)}`;
+}
+
+function parseStamp(code) {
+  const m = /^(.*)\+(\d+)$/.exec(String(code ?? ""));
+  return m ? { version: m[1], mtime: Number(m[2]) } : { version: String(code ?? "0"), mtime: 0 };
+}
+
+/** >0 when stamp `a` is newer code than `b`: the version first, the source mtime on a tie. */
+export function compareCode(a, b) {
+  const x = parseStamp(a);
+  const y = parseStamp(b);
+  return compareCliVersions(x.version, y.version) || Math.sign(x.mtime - y.mtime);
+}
+
+/** The code stamp a descriptor claims; a descriptor from before stamps counts as its version alone. */
+const descriptorCode = (d) => d?.code ?? `${d?.cliVersion ?? "0"}+0`;
+
+export function descriptorPath(dir = workspaceConfigDir()) {
+  return path.join(dir, "daemon.json");
+}
+
+export function logPath(dir = workspaceConfigDir()) {
+  return path.join(dir, "daemon.log");
+}
+
+/** Where a daemon remembers its port, so a restart keeps the page's origin (and its cookie). */
+export function lastPortPath(dir = workspaceConfigDir()) {
+  return path.join(dir, "last-port.json");
+}
+
+/** `daemon.log` over 5 MiB rolls to `.1`, `.1` to `.2`, `.2` is dropped. */
+export function rotateLogs(file = logPath()) {
+  let size = 0;
+  try {
+    size = fs.statSync(file).size;
+  } catch {
+    return;
+  }
+  if (size < LOG_CAP) return;
+  fs.rmSync(`${file}.${LOG_KEEP}`, { force: true });
+  for (let i = LOG_KEEP - 1; i >= 1; i--) {
+    try {
+      fs.renameSync(`${file}.${i}`, `${file}.${i + 1}`);
+    } catch {
+      // no such rotation yet
+    }
+  }
+  fs.renameSync(file, `${file}.1`);
+}
+
+/** The descriptor as on disk: null when absent, `{ malformed: true, file }` when unreadable. */
+export function readDescriptor(dir = workspaceConfigDir()) {
+  const file = descriptorPath(dir);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const d = JSON.parse(raw);
+    if (d && d.schemaVersion === 1 && typeof d.url === "string" && typeof d.cliBearer === "string") return d;
+  } catch {
+    // fall through
+  }
+  return { malformed: true, file };
+}
+
+/** Is `pid` a running process? EPERM means it exists under another user — alive, and not ours. */
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+
+/**
+ * May this pid be signalled as the hung workspace this descriptor names? Only
+ * when BOTH hold: the process is this install's detached daemon (argv is
+ * `<node> <DAEMON_ENTRY>`, the exact path — an editor, a `tail`, another
+ * install's daemon or a `--foreground` workspace never match), and it was
+ * already running when the descriptor was written (a pid the OS handed to a
+ * later process is not the one that wrote it). "unknown" when this system
+ * cannot tell (Windows, no `ps`) — never signalled either.
+ */
+function pidOwner(d) {
+  if (process.platform === "win32") return "unknown";
+  let out;
+  try {
+    out = execFileSync("ps", ["-ww", "-o", "etime=,command=", "-p", String(d.pid)], { encoding: "utf8", timeout: 2_000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "unknown";
+  }
+  // etime: [[dd-]hh:]mm:ss
+  const m = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)\s+(.+)$/.exec(out);
+  if (!m) return "unknown";
+  const elapsedS = ((Number(m[1] ?? 0) * 24 + Number(m[2] ?? 0)) * 60 + Number(m[3])) * 60 + Number(m[4]);
+  const cmd = m[5];
+  const tail = ` ${DAEMON_ENTRY}`;
+  if (!cmd.endsWith(tail) || !/^node[\d.]*(\.exe)?$/i.test(path.basename(cmd.slice(0, -tail.length)))) return "other";
+  const wrote = Date.parse(d.startedAt);
+  // started before it wrote its descriptor (etime has 1 s resolution)
+  return Number.isFinite(wrote) && Date.now() - elapsedS * 1000 <= wrote + 2_000 ? "ours" : "other";
+}
+
+/** A Codex sandbox: no background process survives it, and loopback may be cut. */
+export function sandboxed() {
+  return Boolean(process.env.CODEX_SANDBOX || process.env.CODEX_SANDBOX_NETWORK_DISABLED);
+}
+
+const SANDBOX_CODES = new Set(["EPERM", "EACCES", "EROFS"]);
+const sandboxError = (detail) => coded("workspace_sandboxed", `the workspace cannot start from this session (${detail}) — it looks sandboxed`);
+
+// A pooled keep-alive socket to a workspace that restarted on the same port is
+// dead on first use; one fresh attempt is not a retry of anything that landed.
+const STALE_SOCKET = new Set(["ECONNRESET", "EPIPE", "UND_ERR_SOCKET"]);
+
+async function fetchJson(url, { bearer = null, method = "GET", timeoutMs = PROBE_TIMEOUT_MS, body = null, headers = {} } = {}, attempt = 0) {
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: { ...(bearer ? { Authorization: `Bearer ${bearer}` } : {}), ...(body !== null ? { "Content-Type": "application/json" } : {}), ...headers },
+      body: body !== null ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    if (attempt === 0 && STALE_SOCKET.has(err?.cause?.code)) return fetchJson(url, { bearer, method, timeoutMs, body, headers }, 1);
+    throw err;
+  }
+  return { status: res.status, body: await res.json().catch(() => null) };
+}
+
+/**
+ * One CLI → workspace API call: `path` is relative to `/api/v1` ("/bootstrap",
+ * "/decks/<id>/tasks/…"), sent with the descriptor's CLI bearer and `body` as
+ * JSON. Resolves `{ status, body }` whatever the HTTP status (callers read the
+ * error envelope themselves); a dead pooled socket is retried once. Throws
+ * coded `workspace_down` when there is no usable descriptor, else the network
+ * error itself (`err.cause` kept, a timeout is a TimeoutError).
+ */
+export async function daemonRequest(path, { method = "GET", body = null, timeoutMs = 5000, headers = {} } = {}) {
+  const d = readDescriptor();
+  if (!d || d.malformed) throw coded("workspace_down", "the workspace is not running");
+  return fetchJson(`${d.url}/api/v1${path}`, { bearer: d.cliBearer, method, timeoutMs, body, headers });
+}
+
+const unreachableKind = (err) => (err?.name === "TimeoutError" || err?.cause?.name === "TimeoutError" ? "timeout" : "refused");
+
+/**
+ * Is this descriptor a live workspace of ours?
+ * `{ live, protocolVersion?, status?, draining?, unreachable?: "timeout"|"refused", foreign? }`.
+ * Only a health answer AND a status answer carrying the descriptor's nonce
+ * count; a draining workspace is never live for reuse.
+ */
+export async function probe(descriptor, { timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  if (!descriptor || descriptor.malformed) return { live: false };
+  let health;
+  try {
+    health = await fetchJson(`${descriptor.url}/health`, { timeoutMs });
+  } catch (err) {
+    return { live: false, unreachable: unreachableKind(err) };
+  }
+  if (health.status !== 200 || typeof health.body?.protocolVersion !== "number") return { live: false, foreign: true };
+  if (health.body.draining === true) return { live: false, draining: true, protocolVersion: health.body.protocolVersion };
+  let status;
+  try {
+    status = await fetchJson(`${descriptor.url}/api/v1/status`, { bearer: descriptor.cliBearer, timeoutMs });
+  } catch (err) {
+    return { live: false, unreachable: unreachableKind(err) };
+  }
+  if (status.status !== 200 || status.body?.nonce !== descriptor.nonce) return { live: false, foreign: true };
+  if (status.body.draining === true) return { live: false, draining: true, protocolVersion: health.body.protocolVersion };
+  return { live: true, protocolVersion: health.body.protocolVersion, status: status.body };
+}
+
+/** Does anything still answer on this url? (an in-process workspace has no pid of its own to watch) */
+async function answers(url) {
+  try {
+    await fetchJson(`${url}/health`, { timeoutMs: 500 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Wait until the descriptor's workspace has left: its pid exited (or, in-process, its listener closed). */
+async function awaitGone(d, ms = EXIT_WAIT_MS) {
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    if (d.pid !== process.pid ? !pidAlive(d.pid) : !(await answers(d.url))) return true;
+    await wait(100);
+  }
+  return false;
+}
+
+async function terminate(pid) {
+  try {
+    process.kill(pid, "SIGTERM");
+    // a stopped process holds SIGTERM until it runs again: let it drain
+    process.kill(pid, "SIGCONT");
+  } catch {
+    // already gone
+  }
+  if (await awaitGone({ pid }, TERM_GRACE_MS)) return;
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+    // already gone
+  }
+  await awaitGone({ pid }, 2_000);
+}
+
+/**
+ * The descriptor did not probe live. Draining → wait for it to leave. Hung —
+ * the connection is ACCEPTED and then nothing comes back, twice, the second
+ * time with a longer timeout — → terminate it, but only when `pidOwner` proves
+ * it is the daemon that wrote this descriptor. Everything else (refused, reset,
+ * someone else answering, a pid that cannot be verified) leaves the pid alone
+ * and a fresh workspace starts; it takes another port if the old one is still
+ * held, and an old one that wakes up later finds the descriptor is no longer
+ * its own and stops itself. Never throws: nothing here may block every start.
+ */
+async function recover(d, p) {
+  if (!d || d.malformed || !Number.isInteger(d.pid)) return p;
+  if (p.draining) {
+    await awaitGone(d); // a drain that overruns is left to finish beside the new one
+    return { live: false };
+  }
+  // in-process (foreground, tests): never signal ourselves
+  if (d.pid === process.pid) return p;
+  // refused or reset: nothing listens there any more, whatever holds the pid now
+  if (p.unreachable !== "timeout" || !pidAlive(d.pid)) return p;
+  // a busy moment: ask once more, patiently
+  const again = await probe(d, { timeoutMs: REPROBE_TIMEOUT_MS });
+  if (again.live) return again;
+  if (again.draining) {
+    await awaitGone(d);
+    return { live: false };
+  }
+  if (again.unreachable === "timeout" && pidOwner(d) === "ours") await terminate(d.pid);
+  return { live: false };
+}
+
+/** `{ running, url?, protocolVersion?, pid?, pendingJobs, pages, stale?, reason? }` for `workspace status`. */
+export async function workspaceStatus() {
+  const d = readDescriptor();
+  const idle = { running: false, pendingJobs: 0, pages: 0 };
+  if (!d) return { ...idle, reason: sandboxed() ? "sandboxed" : "not_started" };
+  if (d.malformed) return { ...idle, reason: "crashed", malformedDescriptor: d.file };
+  const p = await probe(d);
+  if (p.live) {
+    return {
+      running: true,
+      url: d.url,
+      protocolVersion: p.protocolVersion,
+      pid: d.pid,
+      pendingJobs: p.status.pendingJobs ?? 0,
+      pages: p.status.pages ?? 0,
+      // the next ensureRunning from this CLI replaces it
+      stale: p.protocolVersion < PROTOCOL_VERSION || compareCode(codeStamp(), descriptorCode(d)) > 0,
+    };
+  }
+  let reason;
+  if (p.draining) reason = "draining";
+  else if (sandboxed()) reason = "sandboxed";
+  else if (Number.isInteger(d.pid) && d.pid !== process.pid && !pidAlive(d.pid)) reason = "crashed";
+  else reason = p.unreachable === "timeout" ? "unresponsive" : "unreachable";
+  return { ...idle, reason };
+}
+
+/**
+ * Take the start lock or return null (someone else is starting). The lock is a
+ * directory naming its owner (pid + a token). A lock judged abandoned — its
+ * owner died, or it is older than 30 s — is reclaimed ATOMICALLY: renamed to a
+ * tombstone first, and removed only when the tombstone is the very lock that
+ * was judged (two starters judging the same stale lock: only one rename wins;
+ * a fresh lock created in between is put back, never removed). Release removes
+ * the lock only while it is still ours.
+ */
+async function withStartLock(dir, fn) {
+  const lock = path.join(dir, "start.lock");
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch (err) {
+    if (SANDBOX_CODES.has(err.code)) throw sandboxError(`${err.code} on ${dir}`);
+    throw err;
+  }
+  const token = randomBytes(8).toString("hex");
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      fs.mkdirSync(lock);
+    } catch (err) {
+      if (SANDBOX_CODES.has(err.code)) throw sandboxError(`${err.code} on ${dir}`);
+      if (err.code !== "EEXIST") throw err;
+      const judged = lockAbandoned(lock);
+      if (!judged) return null; // someone else is starting it
+      if (!reclaimLock(lock, judged)) return null;
+      continue;
+    }
+    let named = true;
+    try {
+      fs.writeFileSync(path.join(lock, "owner.json"), JSON.stringify({ pid: process.pid, token, at: new Date().toISOString() }));
+    } catch {
+      named = false; // the age fallback still covers it
+    }
+    try {
+      return await fn();
+    } finally {
+      const owner = lockOwner(lock);
+      if (named ? owner?.token === token : !owner) fs.rmSync(lock, { recursive: true, force: true });
+    }
+  }
+  return null;
+}
+
+function lockOwner(lock) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(lock, "owner.json"), "utf8"));
+  } catch {
+    return null; // just created, or from an older CLI
+  }
+}
+
+/** The lock as judged abandoned — `{ token, mtimeMs }` — or null while it is someone's live lock. */
+function lockAbandoned(lock) {
+  const owner = lockOwner(lock);
+  let mtimeMs;
+  try {
+    mtimeMs = fs.statSync(lock).mtimeMs;
+  } catch {
+    return { token: undefined, mtimeMs: null }; // released meanwhile: just try again
+  }
+  const snapshot = { token: owner?.token ?? null, mtimeMs };
+  if (Number.isInteger(owner?.pid) && owner.pid !== process.pid && !pidAlive(owner.pid)) return snapshot; // its holder was killed
+  return Date.now() - mtimeMs > START_LOCK_STALE_MS ? snapshot : null;
+}
+
+/** Remove the judged lock and nothing else. False when a live lock turned up in its place. */
+function reclaimLock(lock, judged) {
+  if (judged.mtimeMs === null) return true; // it was released: retry acquisition
+  const tomb = `${lock}.${process.pid}.${randomBytes(4).toString("hex")}.stale`;
+  try {
+    fs.renameSync(lock, tomb);
+  } catch (err) {
+    if (err.code === "ENOENT") return true; // someone else reclaimed or released it: retry acquisition
+    throw err;
+  }
+  let mtimeMs = null;
+  try {
+    mtimeMs = fs.statSync(tomb).mtimeMs;
+  } catch {
+    // vanished: nothing to put back
+  }
+  if ((lockOwner(tomb)?.token ?? null) === judged.token && mtimeMs === judged.mtimeMs) {
+    fs.rmSync(tomb, { recursive: true, force: true });
+    return true;
+  }
+  // a fresh lock was created between the judgement and the rename: hand it back
+  try {
+    fs.renameSync(tomb, lock);
+  } catch {
+    // another starter already holds start.lock; leave the tombstone to the age rule
+  }
+  return false;
+}
+
+/** Test seam: the start lock's judge and reclaimer, to drive their races deterministically. */
+export const startLockInternals = { lockAbandoned, reclaimLock, lockOwner };
+
+const startFailed = (detail, dir) => coded("workspace_start_failed", `the workspace could not start in the background (${detail}) — see ${logPath(dir)}`);
+
+// Poll until a live descriptor appears (optionally for a specific pid).
+async function awaitLive({ dir, pid = null, deadline, child = null }) {
+  while (Date.now() < deadline) {
+    if (child && child.exitCode !== null) throw startFailed(`it exited with code ${child.exitCode} before it was ready`, dir);
+    const d = readDescriptor(dir);
+    if (d && !d.malformed && (pid === null || d.pid === pid)) {
+      const p = await probe(d);
+      if (p.live) return { descriptor: d, probe: p };
+    }
+    await wait(100);
+  }
+  throw startFailed(`it did not become ready within ${START_DEADLINE_MS / 1000}s`, dir);
+}
+
+// The decks root of the command that starts the workspace, for the daemon's
+// auto-discovery — only when it exists; SLIDEMIND_DECKS already set wins.
+function decksDirEnv() {
+  if (process.env.SLIDEMIND_DECKS) return {};
+  const dir = resolveDecksDir();
+  return fs.existsSync(dir) ? { SLIDEMIND_DECKS: dir } : {};
+}
+
+/**
+ * Reuse or replace a live workspace: "reuse" | "replace". A newer protocol is
+ * this CLI's problem (`cli_update_required`); an older one, or older code, is
+ * replaced; newer code is reused with a note — never replaced by an older CLI.
+ */
+function judge(d, p, note) {
+  if (p.protocolVersion > PROTOCOL_VERSION) {
+    throw coded(
+      "cli_update_required",
+      `a newer slidemind workspace is running (protocol ${p.protocolVersion}); this CLI ${readPackageJson().version} speaks ${PROTOCOL_VERSION}. ${updateCliInstruction()}`,
+    );
+  }
+  if (p.protocolVersion < PROTOCOL_VERSION) return "replace";
+  const cmp = compareCode(codeStamp(), descriptorCode(d));
+  if (cmp > 0) return "replace";
+  if (cmp < 0 && d.cliVersion && compareCliVersions(d.cliVersion, readPackageJson().version) > 0) {
+    note(`slidemind: the workspace runs a newer slidemind (${d.cliVersion}) than this CLI (${readPackageJson().version}); using it.`);
+  }
+  return "reuse";
+}
+
+const reused = (d, p) => ({ url: d.url, started: false, protocolVersion: p.protocolVersion, pid: d.pid });
+
+/**
+ * Reuse the live workspace or start one. Resolves
+ * `{ url, started, protocolVersion, pid, daemon? }` — `daemon` only in
+ * foreground mode, where the workspace runs in THIS process and
+ * `daemon.stopped` resolves when it has drained. Throws coded
+ * `workspace_sandboxed`, `workspace_start_failed`, `cli_update_required` or
+ * (replacing an older workspace that will not stop) `workspace_unresponsive`;
+ * callers that have another way (the standalone gate) fall back on any of them.
+ */
+export async function ensureRunning({ foreground = false, note = (m) => process.stderr.write(`${m}\n`), _round = 0 } = {}) {
+  const dir = workspaceConfigDir();
+  const sandbox = sandboxed();
+  let d = readDescriptor(dir);
+  let p = await probe(d);
+  // a sandboxed session neither signals nor starts anything: it only reuses
+  if (!p.live && !sandbox) p = await recover(d, p);
+  if (p.live) {
+    const verdict = judge(d, p, note);
+    if (verdict === "reuse") return reused(d, p);
+    if (sandbox) {
+      if (p.protocolVersion !== PROTOCOL_VERSION) throw sandboxError("the running workspace is too old and cannot be replaced from here");
+      return reused(d, p);
+    }
+    await stopWorkspace();
+  }
+  if (sandbox) throw sandboxError(process.env.CODEX_SANDBOX_NETWORK_DISABLED ? "CODEX_SANDBOX_NETWORK_DISABLED" : "CODEX_SANDBOX");
+  const deadline = Date.now() + START_DEADLINE_MS;
+  const result = await withStartLock(dir, async () => {
+    // Re-check under the lock: the previous holder may have just finished.
+    const current = readDescriptor(dir);
+    const again = await probe(current);
+    if (again.live) {
+      // another CLI started one meanwhile: the same rule as above decides
+      if (judge(current, again, note) === "reuse") return reused(current, again);
+      await stopWorkspace();
+    } else if (again.draining) await awaitGone(current);
+    if (foreground) {
+      Object.assign(process.env, decksDirEnv());
+      const { runDaemon } = await import("./daemon.mjs");
+      const daemon = await runDaemon();
+      return { url: daemon.url, started: true, protocolVersion: PROTOCOL_VERSION, pid: process.pid, daemon };
+    }
+    try {
+      rotateLogs(logPath(dir));
+    } catch {
+      // an unrotated log is still a log
+    }
+    let fd;
+    try {
+      fd = fs.openSync(logPath(dir), "a");
+    } catch (err) {
+      if (SANDBOX_CODES.has(err.code)) throw sandboxError(`${err.code} on ${logPath(dir)}`);
+      throw startFailed(err.message, dir);
+    }
+    // The daemon is nobody's agent session: it never inherits a deck owner token.
+    const env = { ...process.env, ...decksDirEnv() };
+    delete env.SLIDEMIND_OWNER;
+    let child;
+    try {
+      child = spawn(process.execPath, [DAEMON_ENTRY], {
+        detached: true,
+        stdio: ["ignore", fd, fd],
+        env,
+        windowsHide: true,
+      });
+    } catch (err) {
+      throw startFailed(err.message, dir);
+    } finally {
+      fs.closeSync(fd);
+    }
+    child.unref();
+    const { descriptor, probe: live } = await awaitLive({ dir, pid: child.pid, deadline, child });
+    return { url: descriptor.url, started: true, protocolVersion: live.protocolVersion, pid: descriptor.pid };
+  });
+  if (result) return result;
+  // Another process holds the start lock: wait for its workspace, then judge
+  // it like any other — an older CLI starting at the same moment must not
+  // leave this newer one talking to its routes.
+  const { descriptor, probe: live } = await awaitLive({ dir, deadline });
+  if (judge(descriptor, live, note) === "reuse" || _round > 0) return reused(descriptor, live);
+  await stopWorkspace();
+  return ensureRunning({ foreground, note, _round: _round + 1 });
+}
+
+/**
+ * A browser entry URL for the live workspace: `<url>[/deck/<id>]#bootstrap=<key>`.
+ * The key is the workspace's link key, asked for with the CLI bearer and valid
+ * every time; the page exchanges it for its cookie and drops the fragment. Null
+ * when no workspace is live.
+ */
+export async function bootstrapUrl(deckId = null) {
+  const d = readDescriptor();
+  if (!d || d.malformed) return null;
+  let res;
+  try {
+    res = await fetchJson(`${d.url}/api/v1/bootstrap`, { method: "POST", bearer: d.cliBearer });
+  } catch (err) {
+    throw coded(unreachableKind(err) === "timeout" ? "workspace_unresponsive" : "workspace_start_failed", `the workspace did not answer a sign-in request (${unreachableKind(err)})`);
+  }
+  if (res.status !== 200 || !res.body?.token) throw coded("workspace_start_failed", `workspace refused a sign-in link (HTTP ${res.status})`);
+  return `${d.url}${deckId ? `/deck/${deckId}` : "/"}#bootstrap=${res.body.token}`;
+}
+
+/**
+ * The deck's library entry `{ id, path, … }`: written here, or — when this
+ * process may not write the library (an agent's sandbox answers EPERM on the
+ * registry lock) — by the live workspace, which owns that file and runs outside
+ * the sandbox. Without the second path a sandboxed agent's task carried no link
+ * and its deck never appeared in the workspace. Throws the local error when the
+ * workspace cannot register it either; `not_a_deck`/`missing_path` throw at once.
+ * `add` is the test seam for the local write.
+ */
+export async function registerDeck(p, { add = addDeck } = {}) {
+  const abs = path.resolve(p);
+  try {
+    return add(abs);
+  } catch (err) {
+    if (err?.code === "not_a_deck" || err?.code === "missing_path") throw err;
+    let answer;
+    try {
+      answer = await daemonRequest("/decks", { method: "POST", body: { path: abs } });
+    } catch {
+      throw err;
+    }
+    if (answer.status === 200 && answer.body?.deck?.id) return answer.body.deck;
+    throw err;
+  }
+}
+
+/**
+ * Drain and stop the live workspace; resolves once its process has left (or,
+ * in-process, its listener closed). `{ stopped, pendingJobs, exited }`; not
+ * running → `stopped:false`. A workspace already draining is waited out.
+ */
+export async function stopWorkspace() {
+  const d = readDescriptor();
+  const p = await probe(d);
+  if (!p.live) {
+    if (p.draining) return { stopped: true, pendingJobs: 0, exited: await awaitGone(d) };
+    return { stopped: false, running: false, pendingJobs: 0 };
+  }
+  let res;
+  try {
+    res = await fetchJson(`${d.url}/api/v1/stop`, { method: "POST", bearer: d.cliBearer, timeoutMs: 8_000 });
+  } catch (err) {
+    throw coded("workspace_unresponsive", `the workspace did not confirm the stop (${unreachableKind(err)}) — see ${logPath()}`);
+  }
+  if (res.status !== 200) throw coded("workspace_stop_failed", `workspace refused to stop (HTTP ${res.status})`);
+  return { stopped: true, pendingJobs: res.body?.pendingJobs ?? 0, exited: await awaitGone(d) };
+}