@rryando/arcs 3.11.0 → 4.1.0

package/dist/web-server/session-reconciler.js

@@ -0,0 +1,363 @@
+/**
+ * Session liveness reconciliation — the world's opinion on top of the store's.
+ *
+ * `deriveSessionPhase` (session-store) answers "what does this record claim" from
+ * persisted evidence alone. This module answers "is that still true", using the
+ * two liveness sources that exist outside the DAG:
+ *
+ *  - a run claim's pid, probed with signal 0. ARCS-driven runs are headless
+ *    `claude -p` children ARCS spawned itself, so their liveness is a local
+ *    process fact — and the persisted pid is what makes it readable from a
+ *    server process that did not spawn them.
+ *  - `claude agents --json`, which lists the live interactive/background
+ *    sessions a terminal is driving. That is the only way to tell a session ARCS
+ *    merely observes from one whose terminal has since been closed.
+ *
+ * Two shapes of work, deliberately separated:
+ *
+ *  - `settleOrphanedRuns` WRITES: a claim whose process is gone settles as
+ *    outcome `interrupted`, the claim is cleared and the session's run event
+ *    logs are pruned. Runs once at startup (see app.ts), because a claim
+ *    persisted by a previous process can never be live in this one unless its
+ *    child outlived the restart.
+ *  - `reconcileSessionPhases` READS: it returns demoted phases and never writes.
+ *    On-demand only — there is no timer here, and no poller.
+ *
+ * Everything that touches the outside world is tolerant by construction: the
+ * probe is a subprocess of a binary that may not exist, running a command whose
+ * output shape is claude's to change. A missing binary, a non-zero exit, an
+ * empty stdout or unparsable JSON all degrade to the store-derived phase and
+ * NEVER throw — a reconciler that can fail would take the sessions UI down with
+ * every claude release.
+ */
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+import { readRootMeta } from "../utils/dag.js";
+import { getDataDir } from "../utils/paths.js";
+import { deriveSessionPhase, listSessions, sessionRunClaim, settleSessionRun, } from "../utils/session-store.js";
+import { normalizeIdentifier } from "../utils/slug.js";
+import { pruneRunEventLogs } from "./run-event-log.js";
+const AGENTS_PROBE_TIMEOUT_MS = 5_000;
+const AGENTS_PROBE_MAX_BUFFER = 4 * 1024 * 1024;
+/** Keys an `agents --json` payload might wrap its array in. */
+const AGENT_LIST_KEYS = ["agents", "sessions", "data", "items"];
+function defaultAgentsProbe() {
+    return new Promise((resolveProbe) => {
+        try {
+            execFile("claude", ["agents", "--json"], {
+                timeout: AGENTS_PROBE_TIMEOUT_MS,
+                maxBuffer: AGENTS_PROBE_MAX_BUFFER,
+                encoding: "utf-8",
+            }, (error, stdout) => {
+                // ENOENT (no binary), a non-zero exit and the timeout kill all arrive
+                // here as an error — none of them is a usable answer, and none of
+                // them is fatal.
+                if (error)
+                    resolveProbe({ ok: false });
+                else
+                    resolveProbe({ ok: true, stdout: String(stdout) });
+            });
+        }
+        catch {
+            // Some spawn failures surface synchronously depending on platform.
+            resolveProbe({ ok: false });
+        }
+    });
+}
+function readString(node, ...keys) {
+    for (const key of keys) {
+        const value = node[key];
+        if (typeof value === "string" && value !== "")
+            return value;
+    }
+    return undefined;
+}
+function readPid(node) {
+    const value = node.pid;
+    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+        return value;
+    // Tolerated: some CLIs stringify pids.
+    if (typeof value === "string") {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isInteger(parsed) && parsed > 0)
+            return parsed;
+    }
+    return undefined;
+}
+/** The array of rows inside a payload, or `null` when there is no usable one. */
+function agentRows(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value !== "object" || value === null)
+        return null;
+    const node = value;
+    for (const key of AGENT_LIST_KEYS) {
+        if (Array.isArray(node[key]))
+            return node[key];
+    }
+    return null;
+}
+function toLiveAgent(row) {
+    if (typeof row !== "object" || row === null || Array.isArray(row))
+        return undefined;
+    const node = row;
+    const pid = readPid(node);
+    const sessionId = readString(node, "sessionId", "session_id");
+    // A row that identifies neither a process nor a session cannot answer a
+    // liveness question, so it is dropped rather than counted as an agent.
+    if (pid === undefined && sessionId === undefined)
+        return undefined;
+    const cwd = readString(node, "cwd", "directory");
+    const name = readString(node, "name");
+    const status = readString(node, "status", "state");
+    return {
+        ...(pid !== undefined && { pid }),
+        ...(cwd !== undefined && { cwd }),
+        ...(sessionId !== undefined && { sessionId }),
+        ...(name !== undefined && { name }),
+        ...(status !== undefined && { status }),
+    };
+}
+/**
+ * Parses `claude agents --json` stdout into live agents.
+ *
+ * `null` means "the probe answered nothing usable" (empty output, non-JSON, a
+ * JSON shape carrying no array) and is NOT the same as `[]`, which means "the
+ * probe worked and no agent is live". Only the second may demote a session:
+ * conflating them would mark every observed session idle the day claude changes
+ * its output.
+ */
+export function parseLiveAgents(stdout) {
+    const text = stdout.trim();
+    if (text === "")
+        return null;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const rows = agentRows(value);
+    if (rows === null)
+        return null;
+    const agents = [];
+    for (const row of rows) {
+        const agent = toLiveAgent(row);
+        if (agent !== undefined)
+            agents.push(agent);
+    }
+    return agents;
+}
+/**
+ * Runs the probe and parses it. `null` on every degraded path — missing binary,
+ * non-zero exit, timeout, unparsable output, or a probe that threw.
+ */
+export async function listLiveClaudeAgents(options = {}) {
+    const probe = options.probe ?? defaultAgentsProbe;
+    let result;
+    try {
+        result = await probe();
+    }
+    catch {
+        return null;
+    }
+    if (!result.ok)
+        return null;
+    return parseLiveAgents(result.stdout);
+}
+// ---------------------------------------------------------------------------
+// Process liveness
+// ---------------------------------------------------------------------------
+/**
+ * Whether a pid is a live process, via signal 0 (no signal delivered).
+ *
+ * SHORTCUT: pids are reused, so a recycled pid reads alive and keeps an orphan
+ * claim standing; upgrade to a start-time check (`/proc/<pid>/stat` field 22 or
+ * `ps -o lstart`) when a stuck claim is ever actually observed.
+ */
+export function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the process exists but belongs to another user — alive.
+        return err?.code === "EPERM";
+    }
+}
+/** Does this agent report the session behind this record? */
+function agentMatchesSession(session, agent) {
+    const reported = agent.sessionId;
+    if (reported === undefined)
+        return false;
+    if (reported === session.runtimeSessionId)
+        return true;
+    if (normalizeIdentifier(reported) === session.normalizedId)
+        return true;
+    // An ARCS thread runs under its own claude-facing uuid, which is what the
+    // agent list reports — the ARCS thread id never reaches claude.
+    const claudeSessionId = session.metadata?.claudeSessionId;
+    return typeof claudeSessionId === "string" && reported === claudeSessionId;
+}
+/**
+ * The store-derived phase, demoted when the world disagrees.
+ *
+ * Demotion is one-way: this can turn `running` into `idle`, never the reverse.
+ * Nothing outside the record may promote a session — the DAG stays the source
+ * of truth and the probe is only ever allowed to take evidence away.
+ *
+ * Which evidence applies depends on what the record claims, not on its origin:
+ *  - a run claim is checked against its pid. `claude agents` never lists a
+ *    headless `claude -p` child, so asking it about an ARCS run would demote
+ *    every healthy run.
+ *  - everything else is checked against the agent list. `agents === null` (the
+ *    probe degraded) leaves the `lastCheckpointAt`-derived phase untouched.
+ */
+export function reconcilePhase(session, agents, options = {}) {
+    const derived = deriveSessionPhase(session, { now: options.now });
+    if (derived !== "running")
+        return derived;
+    if (sessionRunClaim(session) !== undefined) {
+        const pid = session.currentRunPid;
+        // No pid to probe (the spawn produced none) — the heartbeat stands alone.
+        if (typeof pid !== "number")
+            return derived;
+        return (options.isAlive ?? isProcessAlive)(pid) ? "running" : "idle";
+    }
+    if (agents === null)
+        return derived;
+    return agents.some((agent) => agentMatchesSession(session, agent)) ? "running" : "idle";
+}
+/**
+ * Whether this record's phase can depend on the agent list at all.
+ *
+ * Exactly the one branch of `reconcilePhase` that reads `agents`: a derived
+ * `running` with no run claim. Everything else — terminal, idle, or claimed —
+ * answers from the record alone and never looks at the list.
+ */
+function needsAgentList(session, now) {
+    return (deriveSessionPhase(session, { now }) === "running" && sessionRunClaim(session) === undefined);
+}
+/**
+ * Reconciled phase for every session in a project. Read-only: no writes, no
+ * timer, and at most ONE `claude agents --json` for the whole index — never one
+ * per session.
+ *
+ * The probe is LAZY: `claude agents --json` costs ~0.35s of wall clock and a
+ * whole subprocess, and its answer is read at a single branch of
+ * `reconcilePhase`. Every terminal record, every idle one and every ARCS run
+ * holding a claim decides without it, so a probe fired before the phases are
+ * derived is a subprocess whose result is thrown away — on EVERY sessions
+ * request, list and detail alike, at whatever rate the watcher invalidates the
+ * query. So the derivation runs first and the probe only follows when some
+ * record actually reaches that branch.
+ *
+ * Skipping it passes `null` — the same value a degraded probe yields, and the
+ * value no session left in this pass can read: reaching the `agents` branch is
+ * precisely the condition that would have run the probe.
+ */
+export async function reconcileSessionPhases(projectDir, options = {}) {
+    const sessions = await listSessions(projectDir);
+    // One clock for both passes, so the derivation that decides whether to probe
+    // is the same one reconcilePhase answers from.
+    const now = options.now ?? Date.now();
+    const scoped = { ...options, now };
+    const agents = sessions.some((session) => needsAgentList(session, now))
+        ? await listLiveClaudeAgents({ probe: options.probe })
+        : null;
+    return sessions.map((session) => ({
+        sessionId: session.normalizedId,
+        phase: reconcilePhase(session, agents, scoped),
+    }));
+}
+function orphanError(pid) {
+    return pid === undefined
+        ? "run was interrupted: no pid was recorded for it, so nothing could report how it ended"
+        : `run was interrupted: its process (pid ${pid}) is gone and never reported an outcome`;
+}
+/**
+ * Settles every run claim in a project whose process is gone.
+ *
+ * A claim only survives when its pid is still alive — a run spawned by a
+ * previous server process either outlived the restart (leave it be; it still
+ * holds the write-target) or died with it, and a dead claim that is never
+ * cleared is a session stuck on `running` for good. The settled run keeps
+ * whatever `metadata.run` already held and gains `outcome: "interrupted"`,
+ * which no live run can ever produce.
+ *
+ * A settle here also prunes the session's run event logs, exactly as the route's
+ * own write-back does — this is the ONLY settle an interrupted run ever gets, so
+ * it is the only place that can bound the logs of a session whose runs never
+ * settle normally.
+ *
+ * Never throws: a project whose index cannot be read is skipped, and a record
+ * deleted mid-sweep is simply not settled.
+ */
+export async function settleOrphanedRuns(projectDir, options = {}) {
+    const alive = options.isAlive ?? isProcessAlive;
+    let sessions;
+    try {
+        sessions = await listSessions(projectDir);
+    }
+    catch {
+        return [];
+    }
+    const settled = [];
+    for (const session of sessions) {
+        const runId = sessionRunClaim(session);
+        if (runId === undefined)
+            continue;
+        const pid = typeof session.currentRunPid === "number" ? session.currentRunPid : undefined;
+        if (pid !== undefined && alive(pid))
+            continue;
+        try {
+            await settleSessionRun(projectDir, session.normalizedId, {
+                runId,
+                outcome: "interrupted",
+                error: orphanError(pid),
+                endedAt: options.now,
+            });
+            settled.push({ sessionId: session.normalizedId, runId, ...(pid !== undefined && { pid }) });
+            // Retention belongs to every settle, and this is the one settle path that
+            // is not a run's own write-back. A server that dies mid-run never reaches
+            // `writeBackRun`'s prune, so a session whose runs are always interrupted
+            // would otherwise accumulate one RUN_EVENT_LOG_MAX_BYTES log per run
+            // forever — this sweep is the only thing that ever visits those runs
+            // again. Never throws and its failure is not the sweep's business: the
+            // claim is already released above whatever retention manages to delete.
+            await pruneRunEventLogs(projectDir, session.normalizedId);
+        }
+        catch {
+            // Record vanished between the read and the settle — nothing to settle.
+        }
+    }
+    return settled;
+}
+/**
+ * Startup sweep across every registered project.
+ *
+ * Composition-time work (app.ts calls it once, fire-and-forget) but the logic
+ * lives here. One pass, no timer: liveness questions after startup are answered
+ * on demand by `reconcileSessionPhases`.
+ *
+ * Never throws — a data dir without a readable meta.json settles nothing and
+ * reports it, rather than taking the server down at boot.
+ */
+export async function settleOrphanedRunsOnStartup(dataDir = getDataDir(), options = {}) {
+    let slugs;
+    try {
+        slugs = (await readRootMeta(dataDir)).projects.map((project) => project.id);
+    }
+    catch {
+        return [];
+    }
+    const settled = [];
+    for (const slug of slugs) {
+        settled.push(...(await settleOrphanedRuns(resolve(dataDir, "projects", slug), options)));
+    }
+    return settled;
+}
+//# sourceMappingURL=session-reconciler.js.map

package/dist/web-server/session-reconciler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reconciler.js","sourceRoot":"","sources":["../../src/web-server/session-reconciler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EACL,kBAAkB,EAClB,YAAY,EAGZ,eAAe,EACf,gBAAgB,GACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAyBvD,MAAM,uBAAuB,GAAG,KAAK,CAAC;AACtC,MAAM,uBAAuB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhD,+DAA+D;AAC/D,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhE,SAAS,kBAAkB;IACzB,OAAO,IAAI,OAAO,CAAoB,CAAC,YAAY,EAAE,EAAE;QACrD,IAAI,CAAC;YACH,QAAQ,CACN,QAAQ,EACR,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACpB;gBACE,OAAO,EAAE,uBAAuB;gBAChC,SAAS,EAAE,uBAAuB;gBAClC,QAAQ,EAAE,OAAO;aAClB,EACD,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;gBAChB,sEAAsE;gBACtE,kEAAkE;gBAClE,iBAAiB;gBACjB,IAAI,KAAK;oBAAE,YAAY,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;;oBAClC,YAAY,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC1D,CAAC,CACF,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;YACnE,YAAY,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CAAC,IAA6B,EAAE,GAAG,IAAc;IAClE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;IAC9D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,OAAO,CAAC,IAA6B;IAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC;IACvB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACpF,uCAAuC;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC;IAC5D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,iFAAiF;AACjF,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,IAAI,GAAG,KAAgC,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAc,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,GAAY;IAC/B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACpF,MAAM,IAAI,GAAG,GAA8B,CAAC;IAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAC9D,wEAAwE;IACxE,uEAAuE;IACvE,IAAI,GAAG,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACnE,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO;QACL,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;QACjC,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;QACjC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;QACnC,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7B,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,UAAmC,EAAE;IAErC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,kBAAkB,CAAC;IAClD,IAAI,MAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,KAAK,EAAE,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sEAAsE;QACtE,OAAQ,GAAoC,EAAE,IAAI,KAAK,OAAO,CAAC;IACjE,CAAC;AACH,CAAC;AAoBD,6DAA6D;AAC7D,SAAS,mBAAmB,CAAC,OAAoB,EAAE,KAAgB;IACjE,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC;IACjC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,QAAQ,KAAK,OAAO,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,mBAAmB,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IACxE,0EAA0E;IAC1E,gEAAgE;IAChE,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,EAAE,eAAe,CAAC;IAC1D,OAAO,OAAO,eAAe,KAAK,QAAQ,IAAI,QAAQ,KAAK,eAAe,CAAC;AAC7E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAoB,EACpB,MAA0B,EAC1B,UAA4B,EAAE;IAE9B,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAClE,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAE1C,IAAI,eAAe,CAAC,OAAO,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC;QAClC,0EAA0E;QAC1E,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,OAAO,CAAC;QAC5C,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;IACvE,CAAC;IAED,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;AAC1F,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,OAAoB,EAAE,GAAuB;IACnE,OAAO,CACL,kBAAkB,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,SAAS,IAAI,eAAe,CAAC,OAAO,CAAC,KAAK,SAAS,CAC7F,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,UAAkB,EAClB,UAA4B,EAAE;IAE9B,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,CAAC;IAChD,6EAA6E;IAC7E,+CAA+C;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACtC,MAAM,MAAM,GAAqB,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,CAAC;IACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACrE,CAAC,CAAC,MAAM,oBAAoB,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACtD,CAAC,CAAC,IAAI,CAAC;IACT,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAChC,SAAS,EAAE,OAAO,CAAC,YAAY;QAC/B,KAAK,EAAE,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC;KAC/C,CAAC,CAAC,CAAC;AACN,CAAC;AAYD,SAAS,WAAW,CAAC,GAAuB;IAC1C,OAAO,GAAG,KAAK,SAAS;QACtB,CAAC,CAAC,uFAAuF;QACzF,CAAC,CAAC,yCAAyC,GAAG,yCAAyC,CAAC;AAC5F,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAAkB,EAClB,UAA4B,EAAE;IAE9B,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC;IAChD,IAAI,QAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1F,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,CAAC;YAAE,SAAS;QAE9C,IAAI,CAAC;YACH,MAAM,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,EAAE;gBACvD,KAAK;gBACL,OAAO,EAAE,aAAa;gBACtB,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC;gBACvB,OAAO,EAAE,OAAO,CAAC,GAAG;aACrB,CAAC,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC5F,0EAA0E;YAC1E,0EAA0E;YAC1E,yEAAyE;YACzE,qEAAqE;YACrE,qEAAqE;YACrE,uEAAuE;YACvE,wEAAwE;YACxE,MAAM,iBAAiB,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;QACzE,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,UAAkB,UAAU,EAAE,EAC9B,UAA4B,EAAE;IAE9B,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,kBAAkB,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/web-server/static.d.ts

@@ -4,6 +4,13 @@
  * The Vite build output lives at dist/web-client (resolved by the caller).
  * If the bundle is missing, the server runs API-only and explains how to
  * build the client.
+ *
+ * index.html is never streamed verbatim: it is read and transformed so the SPA
+ * boots holding this server's mutation token (see web-token.ts) without a
+ * second fetch. There are TWO paths that answer with index.html — the direct
+ * request for `/` and the SPA fallback that backs every deep link — and both go
+ * through the same transform, because a shell served without the token is a
+ * client that cannot write.
  */
 import type { Hono } from "hono";
 export declare function registerStaticServing(app: Hono, root: string): void;

package/dist/web-server/static.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../../src/web-server/static.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAMjC,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAuBnE"}
+{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../../src/web-server/static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AA0C1C,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA0BnE"}

package/dist/web-server/static.js

@@ -4,12 +4,51 @@
  * The Vite build output lives at dist/web-client (resolved by the caller).
  * If the bundle is missing, the server runs API-only and explains how to
  * build the client.
+ *
+ * index.html is never streamed verbatim: it is read and transformed so the SPA
+ * boots holding this server's mutation token (see web-token.ts) without a
+ * second fetch. There are TWO paths that answer with index.html — the direct
+ * request for `/` and the SPA fallback that backs every deep link — and both go
+ * through the same transform, because a shell served without the token is a
+ * client that cannot write.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { fail } from "./respond.js";
+import { currentWebToken } from "./web-token.js";
 const NOT_BUILT_HINT = "ARCS web client is not built. Run `npm run build:web` in the arcs repo (or reinstall @rryando/arcs).";
+/**
+ * Client contract: the SPA reads its token from
+ * `<meta name="arcs-web-token" content="…">` in the document head and sends it
+ * back as the `X-ARCS-Token` header on every mutating request.
+ */
+const TOKEN_META_NAME = "arcs-web-token";
+/** Request paths that resolve to the SPA shell rather than a bundled asset. */
+const INDEX_PATHS = new Set(["/", "/index.html"]);
+/**
+ * Reads the built shell and injects this server's token as a head meta tag.
+ *
+ * The token is hex, so it needs no HTML escaping, and the source is always the
+ * untouched Vite output — the server only ever reads index.html, never writes
+ * it back, so the injection cannot accumulate across restarts. `no-store` keeps
+ * a rotated token from being served from a stale cache after a restart.
+ */
+function serveIndexHtml(c, root) {
+    let shell;
+    try {
+        shell = readFileSync(join(root, "index.html"), "utf-8");
+    }
+    catch {
+        // The bundle vanished after startup — same answer as never having built it.
+        return c.text(NOT_BUILT_HINT, 404);
+    }
+    const meta = `<meta name="${TOKEN_META_NAME}" content="${currentWebToken() ?? ""}" />`;
+    const injected = shell.includes("</head>")
+        ? shell.replace("</head>", `  ${meta}\n  </head>`)
+        : `${meta}\n${shell}`;
+    return c.html(injected, 200, { "cache-control": "no-store" });
+}
 export function registerStaticServing(app, root) {
     if (!existsSync(join(root, "index.html"))) {
         app.notFound((c) => {
@@ -23,14 +62,18 @@ export function registerStaticServing(app, root) {
     app.use("*", async (c, next) => {
         if (c.req.path.startsWith("/api/"))
             return next();
+        // Transform point 1 — the direct shell request.
+        if (INDEX_PATHS.has(c.req.path))
+            return serveIndexHtml(c, root);
         return serveStatic({ root })(c, next);
     });
     app.notFound((c) => {
         if (c.req.path.startsWith("/api/")) {
             return c.json(fail("not_found", `No route: ${c.req.method} ${c.req.path}`), 404);
         }
-        // SPA fallback — client-side routing takes over.
-        return serveStatic({ path: join(root, "index.html") })(c, async () => { });
+        // Transform point 2 — SPA fallback, where client-side routing takes over.
+        // Deep links land here and need the token just as much as `/` does.
+        return serveIndexHtml(c, root);
     });
 }
 //# sourceMappingURL=static.js.map

package/dist/web-server/static.js.map

@@ -1 +1 @@
-{"version":3,"file":"static.js","sourceRoot":"","sources":["../../src/web-server/static.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAE7D,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEpC,MAAM,cAAc,GAClB,sGAAsG,CAAC;AAEzG,MAAM,UAAU,qBAAqB,CAAC,GAAS,EAAE,IAAY;IAC3D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE;YACjB,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACnC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;YACnF,CAAC;YACD,OAAO,CAAC,CAAC,IAAI,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QAC7B,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,EAAE,CAAC;QAClD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE;QACjB,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QACnF,CAAC;QACD,iDAAiD;QACjD,OAAO,WAAW,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC,CAAsB,CAAC;IACjG,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"static.js","sourceRoot":"","sources":["../../src/web-server/static.ts"],"names":[],"mappings":"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"}

package/dist/web-server/web-auth.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `X-ARCS-Token` gate for mutating API routes.
+ *
+ * Layered on top of (never instead of) the global loopback-only
+ * `secureLocalRequest`: loopback proves the caller is on this machine, the
+ * token proves it is a page this server itself served (see web-token.ts).
+ *
+ * Deny-by-default across `/api/*` rather than an allowlist of known paths: a
+ * mutating route added later is gated the moment it is registered, with exactly
+ * one exemption — `/api/hook/*`, whose caller is a Claude Code hook subprocess
+ * and not the browser, and which carries its own independent bearer token
+ * (hook-auth.ts). Reads are untouched: every GET/HEAD/OPTIONS passes straight
+ * through, so `/api/events` and the whole read surface behave exactly as before.
+ */
+import type { MiddlewareHandler } from "hono";
+export declare const requireWebToken: MiddlewareHandler;
+//# sourceMappingURL=web-auth.d.ts.map

package/dist/web-server/web-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-auth.d.ts","sourceRoot":"","sources":["../../src/web-server/web-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAc9C,eAAO,MAAM,eAAe,EAAE,iBAW7B,CAAC"}

package/dist/web-server/web-auth.js

@@ -0,0 +1,33 @@
+/**
+ * `X-ARCS-Token` gate for mutating API routes.
+ *
+ * Layered on top of (never instead of) the global loopback-only
+ * `secureLocalRequest`: loopback proves the caller is on this machine, the
+ * token proves it is a page this server itself served (see web-token.ts).
+ *
+ * Deny-by-default across `/api/*` rather than an allowlist of known paths: a
+ * mutating route added later is gated the moment it is registered, with exactly
+ * one exemption — `/api/hook/*`, whose caller is a Claude Code hook subprocess
+ * and not the browser, and which carries its own independent bearer token
+ * (hook-auth.ts). Reads are untouched: every GET/HEAD/OPTIONS passes straight
+ * through, so `/api/events` and the whole read surface behave exactly as before.
+ */
+import { fail } from "./respond.js";
+import { verifyWebToken } from "./web-token.js";
+/** Mirrors the mutation set in security.ts. */
+const MUTATION_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** The one prefix that authenticates with its own bearer token instead. */
+const HOOK_PREFIX = "/api/hook/";
+function needsWebToken(method, path) {
+    return MUTATION_METHODS.has(method.toUpperCase()) && !path.startsWith(HOOK_PREFIX);
+}
+export const requireWebToken = async (c, next) => {
+    if (needsWebToken(c.req.method, c.req.path) &&
+        !verifyWebToken(c.req.header("x-arcs-token") ?? "")) {
+        // A clean typed refusal, not a throw: respond.ts only maps DagError, and a
+        // missing token is an auth answer rather than a DAG failure.
+        return c.json(fail("web_unauthorized", "Missing or invalid ARCS web token"), 401);
+    }
+    await next();
+};
+//# sourceMappingURL=web-auth.js.map

package/dist/web-server/web-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-auth.js","sourceRoot":"","sources":["../../src/web-server/web-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,+CAA+C;AAC/C,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAErE,2EAA2E;AAC3E,MAAM,WAAW,GAAG,YAAY,CAAC;AAEjC,SAAS,aAAa,CAAC,MAAc,EAAE,IAAY;IACjD,OAAO,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAsB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;IAClE,IACE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;QACvC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,EACnD,CAAC;QACD,2EAA2E;QAC3E,6DAA6D;QAC7D,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,mCAAmC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC"}

package/dist/web-server/web-token.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Per-server auth token for the browser-facing mutating API.
+ *
+ * The loopback + Origin checks in security.ts stop remote and cross-site
+ * callers, but they authenticate a NETWORK LOCATION, not a process: every other
+ * program on this machine shares localhost, and the mutating routes now spawn
+ * `claude` subprocesses. This token proves the caller is a page THIS server
+ * served — it is minted fresh at every server start and injected into the
+ * served index.html (see static.ts), so the SPA holds it from first paint and
+ * no other local process can guess it.
+ *
+ * Deliberately per-SERVER, not per-project (unlike hook-token-store, which
+ * authenticates a per-project hook install): it authenticates the browser tab,
+ * and one tab drives every project. Verification always reads the in-memory
+ * value, never the file, so a second server started against the same data dir
+ * cannot authorize requests to this one — it only replaces the on-disk copy.
+ * Exactly one token is live per PROCESS: a second createApp in the same process
+ * rotates it and every app then verifies against the newest value. ARCS runs
+ * one server per process, so that is a test-only nuance.
+ *
+ * The file exists for out-of-band consumers (scripts, tests) and is written
+ * 0o600: the token is never passed on an argv or in an env var a `ps` can read.
+ */
+export declare function webTokenPath(): string;
+/**
+ * Mints this server's token, replacing any previous one, and persists it 0o600.
+ * Called once from createApp, before any route can be served: the middleware
+ * and the index.html transform both read the value it installs.
+ */
+export declare function mintWebToken(): string;
+/** This server's live token, or undefined before mintWebToken() has run. */
+export declare function currentWebToken(): string | undefined;
+/**
+ * Constant-time token comparison. Returns false when no token has been minted
+ * yet, so a request that arrives before startup finished cannot be authorized
+ * by an empty header.
+ */
+export declare function verifyWebToken(candidate: string): boolean;
+//# sourceMappingURL=web-token.d.ts.map

package/dist/web-server/web-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-token.d.ts","sourceRoot":"","sources":["../../src/web-server/web-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAkBH,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAerC;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAOzD"}