@agentprojectcontext/apx 1.77.3 → 1.79.0

package/src/host/daemon/api/telegram.js

@@ -6,7 +6,11 @@
 //   POST   /telegram/send_photo   { chat_id?, photo, caption?, parse_mode?, channel? }
 //   POST   /telegram/send_voice   { chat_id?, audio, caption?, duration?, channel? }
 //   POST   /telegram/send_audio   { chat_id?, audio, caption?, title?, performer?, channel? }
-//   POST   /telegram/notify       (alias of /telegram/send; daemon-initiated pushes)
+//   POST   /telegram/notify       { chat_id?, text, channel?, kind?, project_id?,
+//                                   severity?, unsolicited? }
+//                                 Daemon-initiated pushes. Goes through the
+//                                 interruption budget (core/nudge) and answers
+//                                 429 with a retry_after_ms when suppressed.
 //
 //   GET    /telegram/channels                         — list configured channels
 //   POST   /telegram/channels    { name, ... }        — create or replace one channel
@@ -31,7 +35,6 @@ import {
   removeTelegramChannel,
   unsetTelegramChannelFields,
   listContacts,
-  findContact,
   upsertContact,
   removeContact,
   listRoles,
@@ -40,14 +43,15 @@ import {
 } from "#core/config/index.js";
 
 import { redactChannel, isSecretMarker } from "#core/config/redact.js";
+import { canNudge, recordNudge, nudgeFeedbackKeyboard } from "#core/nudge/index.js";
 
-export function register(app, { telegram }) {
-  app.get("/telegram/status", (_req, res) => {
+export function register(api, { telegram }) {
+  api.get("/telegram/status", (_req, res) => {
     if (!telegram) return res.json({ enabled: false, channels: [] });
     res.json(telegram.status());
   });
 
-  app.post("/telegram/start", (_req, res) => {
+  api.post("/telegram/start", (_req, res) => {
     if (!telegram)
       return res.status(503).json({ error: "telegram plugin not loaded" });
     try {
@@ -58,7 +62,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.post("/telegram/stop", (_req, res) => {
+  api.post("/telegram/stop", (_req, res) => {
     if (!telegram)
       return res.status(503).json({ error: "telegram plugin not loaded" });
     try {
@@ -69,7 +73,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.post("/telegram/send", async (req, res) => {
+  api.post("/telegram/send", async (req, res) => {
     const { chat_id, text, channel } = req.body || {};
     if (!text) return res.status(400).json({ error: "text required" });
     if (!telegram)
@@ -82,7 +86,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.post("/telegram/send_photo", async (req, res) => {
+  api.post("/telegram/send_photo", async (req, res) => {
     const { chat_id, photo, caption, parse_mode, channel } = req.body || {};
     if (!photo)
       return res.status(400).json({ error: "photo required (path or url)" });
@@ -102,7 +106,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.post("/telegram/send_voice", async (req, res) => {
+  api.post("/telegram/send_voice", async (req, res) => {
     const { chat_id, audio, caption, duration, channel } = req.body || {};
     if (!audio) return res.status(400).json({ error: "audio required (path)" });
     if (!telegram)
@@ -121,7 +125,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.post("/telegram/send_audio", async (req, res) => {
+  api.post("/telegram/send_audio", async (req, res) => {
     const { chat_id, audio, caption, title, performer, channel } =
       req.body || {};
     if (!audio) return res.status(400).json({ error: "audio required (path)" });
@@ -145,7 +149,7 @@ export function register(app, { telegram }) {
   // ── Channel CRUD (config-only; caller must POST /admin/reload to apply) ──
   // We read fresh config from disk on each call so concurrent writes from the
   // CLI and the daemon don't clobber one another via stale closures.
-  app.get("/telegram/channels", (_req, res) => {
+  api.get("/telegram/channels", (_req, res) => {
     try {
       const cfg = readConfig();
       res.json({ channels: listTelegramChannels(cfg).map(redactChannel) });
@@ -154,7 +158,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.post("/telegram/channels", (req, res) => {
+  api.post("/telegram/channels", (req, res) => {
     const body = req.body || {};
     if (!body.name || typeof body.name !== "string") {
       return res.status(400).json({ error: "name required" });
@@ -173,7 +177,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.patch("/telegram/channels/:name", (req, res) => {
+  api.patch("/telegram/channels/:name", (req, res) => {
     const { name } = req.params;
     const body = req.body || {};
     try {
@@ -202,7 +206,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.delete("/telegram/channels/:name", (req, res) => {
+  api.delete("/telegram/channels/:name", (req, res) => {
     const { name } = req.params;
     try {
       const cfg = readConfig();
@@ -219,7 +223,7 @@ export function register(app, { telegram }) {
   // channel. These edit ~/.apx/config.json directly; the running poller picks
   // changes up on its next inbound message (it re-reads config per message), so
   // no /admin/reload is required for contact/role edits.
-  app.get("/telegram/contacts", (_req, res) => {
+  api.get("/telegram/contacts", (_req, res) => {
     try {
       const cfg = readConfig();
       res.json({
@@ -235,7 +239,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.patch("/telegram/contacts/:user_id", (req, res) => {
+  api.patch("/telegram/contacts/:user_id", (req, res) => {
     const { user_id } = req.params;
     const body = req.body || {};
     try {
@@ -254,7 +258,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.delete("/telegram/contacts/:user_id", (req, res) => {
+  api.delete("/telegram/contacts/:user_id", (req, res) => {
     const { user_id } = req.params;
     try {
       const cfg = readConfig();
@@ -267,7 +271,7 @@ export function register(app, { telegram }) {
   });
 
   // ── Roles (role → { tools }) ────────────────────────────────────────────
-  app.get("/telegram/roles", (_req, res) => {
+  api.get("/telegram/roles", (_req, res) => {
     try {
       res.json({ roles: listRoles(readConfig()) });
     } catch (e) {
@@ -275,7 +279,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.put("/telegram/roles/:name", (req, res) => {
+  api.put("/telegram/roles/:name", (req, res) => {
     const { name } = req.params;
     const body = req.body || {};
     try {
@@ -288,7 +292,7 @@ export function register(app, { telegram }) {
     }
   });
 
-  app.delete("/telegram/roles/:name", (req, res) => {
+  api.delete("/telegram/roles/:name", (req, res) => {
     const { name } = req.params;
     try {
       const { removed } = removeRole(readConfig(), name);
@@ -300,14 +304,47 @@ export function register(app, { telegram }) {
   });
 
   // Alias for proactive daemon-initiated pushes (routines, error handlers, …).
-  app.post("/telegram/notify", async (req, res) => {
-    const { chat_id, text, channel } = req.body || {};
+  //
+  // PUSH PATH 2 OF 4 — this endpoint exists FOR unrequested messages, so the
+  // interruption budget applies by default. A caller delivering something the
+  // user is waiting for says so with `unsolicited: false`, and that choice is
+  // then visible in its own diff rather than hidden in this handler.
+  api.post("/telegram/notify", async (req, res) => {
+    const { chat_id, text, channel, kind, project_id, severity, unsolicited } = req.body || {};
     if (!text) return res.status(400).json({ error: "text required" });
     if (!telegram)
       return res.status(503).json({ error: "telegram plugin not loaded" });
+
+    const gate = canNudge(
+      {
+        kind: kind || "notify",
+        project_id: project_id ?? null,
+        severity: severity || "normal",
+        unsolicited: unsolicited !== false,
+        channel: "telegram",
+      },
+      readConfig(),
+    );
+    if (!gate.allowed) {
+      // 429, not 500: nothing failed. The caller is being asked to wait, and
+      // told for how long, so a routine can decide to try again rather than
+      // treating a working guardrail as an outage.
+      return res.status(429).json({
+        ok: false,
+        suppressed: true,
+        reason: gate.reason,
+        retry_after_ms: gate.retry_after_ms,
+      });
+    }
+
     try {
-      const r = await telegram.send({ chat_id, text, channel });
-      res.status(202).json({ ok: true, message_id: r.message_id, via: "notify" });
+      const r = await telegram.send({
+        chat_id, text, channel,
+        reply_markup: gate.unsolicited ? nudgeFeedbackKeyboard(gate.nudge_id) : undefined,
+        meta: { nudge_id: gate.unsolicited ? gate.nudge_id : undefined, nudge_kind: gate.kind },
+      });
+      recordNudge(gate, { chat_id, preview: text });
+      res.status(202).json({ ok: true, message_id: r.message_id, via: "notify", nudge_id: gate.nudge_id });
     } catch (e) {
       res.status(502).json({ error: e.message });
     }

package/src/host/daemon/api/tools.js

@@ -11,11 +11,11 @@ import { buildRegistryRouter } from "#core/http-tools/registry.js";
 import { buildGlobRouter } from "#core/http-tools/glob.js";
 import { buildGrepRouter } from "#core/http-tools/grep.js";
 
-export function register(app, { express, projects, registries }) {
-  app.use("/tools/fetch", buildFetchRouter(express));
-  app.use("/tools/browser", buildBrowserRouter(express));
-  app.use("/tools/search", buildSearchRouter(express));
-  app.use("/tools/glob", buildGlobRouter(express));
-  app.use("/tools/grep", buildGrepRouter(express));
-  app.use("/tools", buildRegistryRouter(express, { projects, registries }));
+export function register(api, { express, projects, registries }) {
+  api.use("/tools/fetch", buildFetchRouter(express));
+  api.use("/tools/browser", buildBrowserRouter(express));
+  api.use("/tools/search", buildSearchRouter(express));
+  api.use("/tools/glob", buildGlobRouter(express));
+  api.use("/tools/grep", buildGrepRouter(express));
+  api.use("/tools", buildRegistryRouter(express, { projects, registries }));
 }

package/src/host/daemon/api/top-level.js

@@ -12,9 +12,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { resolveMemoryPath } from "./shared.js";
 
-export function register(app, { projects, registries, resolveTopProject }) {
+export function register(api, { projects, registries, resolveTopProject }) {
   // ---- /memory ----
-  app.get("/memory", (req, res) => {
+  api.get("/memory", (req, res) => {
     const p = resolveTopProject(req.query);
     if (!p) return res.status(404).json({ error: "no project registered" });
     const memPath = resolveMemoryPath(p);
@@ -22,7 +22,7 @@ export function register(app, { projects, registries, resolveTopProject }) {
     res.json({ project_id: p.id, path: memPath, body });
   });
 
-  app.post("/memory", (req, res) => {
+  api.post("/memory", (req, res) => {
     const p = resolveTopProject(req.query);
     if (!p) return res.status(404).json({ error: "no project registered" });
     const { body } = req.body || {};
@@ -42,7 +42,7 @@ export function register(app, { projects, registries, resolveTopProject }) {
   });
 
   // ---- /files ----
-  app.get("/files", (req, res) => {
+  api.get("/files", (req, res) => {
     const p = resolveTopProject(req.query);
     if (!p) return res.status(404).json({ error: "no project registered" });
     const rel = req.query.path;
@@ -90,7 +90,7 @@ export function register(app, { projects, registries, resolveTopProject }) {
     });
   });
 
-  app.post("/files", (req, res) => {
+  api.post("/files", (req, res) => {
     const p = resolveTopProject(req.query);
     if (!p) return res.status(404).json({ error: "no project registered" });
     const { path: rel, content } = req.body || {};
@@ -111,13 +111,13 @@ export function register(app, { projects, registries, resolveTopProject }) {
   });
 
   // ---- /mcp ----
-  app.get("/mcp", (req, res) => {
+  api.get("/mcp", (req, res) => {
     const p = resolveTopProject(req.query);
     if (!p) return res.status(404).json({ error: "no project registered" });
     res.json(registries.for(p).list());
   });
 
-  app.post("/mcp/run", async (req, res) => {
+  api.post("/mcp/run", async (req, res) => {
     const { project: projectRef, name, tool, params } = req.body || {};
     if (!name) return res.status(400).json({ error: "name required" });
     if (!tool) return res.status(400).json({ error: "tool required" });

package/src/host/daemon/api/transcribe.js

@@ -5,12 +5,12 @@
 //   X-Provider      auto | local | openai | custom   (overrides config)
 //
 // Shared by overlay, telegram voice messages, and any external caller.
-export function register(app) {
+export function register(api) {
   // GET /transcribe/providers — STT engine list + availability for the web
   // admin (mirror of /tts/providers). local = embedded faster-whisper;
   // openai = cloud Whisper; custom = any OpenAI-compatible server (mlx-audio
   // on Metal, a Radeon/NVIDIA box on the LAN, a remote endpoint).
-  app.get("/transcribe/providers", async (_req, res) => {
+  api.get("/transcribe/providers", async (_req, res) => {
     try {
       const { readConfig } = await import("#core/config/index.js");
       const { listSttProviders } = await import("#core/voice/transcription.js");
@@ -23,7 +23,7 @@ export function register(app) {
   // GET /transcribe/hardware — detected machine + the recommended local backend
   // (mlx on Apple Silicon, faster-whisper cuda on NVIDIA, else CPU). Drives the
   // "engine adapts itself" UX in the web admin.
-  app.get("/transcribe/hardware", async (_req, res) => {
+  api.get("/transcribe/hardware", async (_req, res) => {
     try {
       const { detectHardware, recommendStt } = await import("#core/voice/stt-hardware.js");
       const hw = detectHardware();
@@ -35,7 +35,7 @@ export function register(app) {
 
   // GET /transcribe/models?backend=faster|mlx — model catalog with on-disk
   // status (downloaded? size) for the model-manager UI.
-  app.get("/transcribe/models", async (req, res) => {
+  api.get("/transcribe/models", async (req, res) => {
     try {
       const backend = String(req.query.backend || "faster");
       const { listSttModels } = await import("#core/voice/stt-models.js");
@@ -48,7 +48,7 @@ export function register(app) {
   // GET /transcribe/warmup — load the local whisper model (if needed) and reset
   // its idle watchdog. Callers (e.g. the desktop window) ping this while open so
   // the first real utterance doesn't pay the cold-load cost.
-  app.get("/transcribe/warmup", async (_req, res) => {
+  api.get("/transcribe/warmup", async (_req, res) => {
     try {
       const { warmupWhisper } = await import("../whisper-server.js");
       res.json(await warmupWhisper());
@@ -57,7 +57,7 @@ export function register(app) {
     }
   });
 
-  app.post("/transcribe/chunk", async (req, res) => {
+  api.post("/transcribe/chunk", async (req, res) => {
     const chunks = [];
     req.on("data", (c) => chunks.push(c));
     req.on("end", async () => {

package/src/host/daemon/api/tts.js

@@ -11,8 +11,8 @@
 import { synthesize, listProviders } from "#core/voice/tts.js";
 import { readConfig } from "#core/config/index.js";
 
-export function register(app) {
-  app.post("/tts/say", async (req, res) => {
+export function register(api) {
+  api.post("/tts/say", async (req, res) => {
     try {
       const { text, voice, language, provider, format, style } = req.body || {};
       if (typeof text !== "string" || !text.trim()) {
@@ -33,7 +33,7 @@ export function register(app) {
     }
   });
 
-  app.get("/tts/providers", async (_req, res) => {
+  api.get("/tts/providers", async (_req, res) => {
     try {
       const info = await listProviders(readConfig());
       res.json(info);

package/src/host/daemon/api/vars.js

@@ -24,7 +24,10 @@ import {
   maskValue,
 } from "#core/vars/index.js";
 
-function normalizeScope(raw, { isBase }) {
+// Var scope vocabulary: project | global. The default depends on whether the
+// request targets the base store. See the note in api/mcps.js: these scope
+// helpers share a shape but not a vocabulary.
+function normalizeVarScope(raw, { isBase }) {
   if (!raw) return isBase ? "global" : "project";
   const s = String(raw).toLowerCase();
   if (s === "project" || s === "global") return s;
@@ -37,8 +40,8 @@ function maskAll(obj) {
   return out;
 }
 
-export function register(app, { project, registries }) {
-  app.get("/projects/:pid/vars", (req, res) => {
+export function register(api, { project, registries }) {
+  api.get("/projects/:pid/vars", (req, res) => {
     const p = project(req, res);
     if (!p) return;
     const reveal = req.query?.reveal === "1" || req.query?.reveal === "true";
@@ -54,7 +57,7 @@ export function register(app, { project, registries }) {
     });
   });
 
-  app.get("/projects/:pid/vars/:name", (req, res) => {
+  api.get("/projects/:pid/vars/:name", (req, res) => {
     const p = project(req, res);
     if (!p) return;
     const name = req.params.name;
@@ -80,7 +83,7 @@ export function register(app, { project, registries }) {
     });
   });
 
-  app.post("/projects/:pid/vars", (req, res) => {
+  api.post("/projects/:pid/vars", (req, res) => {
     const p = project(req, res);
     if (!p) return;
     const { name, value } = req.body || {};
@@ -91,7 +94,7 @@ export function register(app, { project, registries }) {
       return res.status(400).json({ error: "value required" });
     }
     const isBase = String(p.id) === "0";
-    const scope = normalizeScope(req.body?.scope, { isBase });
+    const scope = normalizeVarScope(req.body?.scope, { isBase });
     if (scope === null) {
       return res
         .status(400)
@@ -111,11 +114,11 @@ export function register(app, { project, registries }) {
     res.status(201).json({ ok: true, name, scope });
   });
 
-  app.delete("/projects/:pid/vars/:name", (req, res) => {
+  api.delete("/projects/:pid/vars/:name", (req, res) => {
     const p = project(req, res);
     if (!p) return;
     const isBase = String(p.id) === "0";
-    const scope = normalizeScope(req.query?.scope, { isBase });
+    const scope = normalizeVarScope(req.query?.scope, { isBase });
     if (scope === null) {
       return res
         .status(400)

package/src/host/daemon/api/voice.js

@@ -18,8 +18,10 @@
 //
 // Domain logic (channel context, suggestion parsing, audio decoding) lives in
 // core/. This file is just glue: parse request → call core → format response.
+import { stripReasoning } from "#core/util/thinking.js";
 import fs from "node:fs";
 import path from "node:path";
+import { TTS_TMP_DIR } from "#core/config/paths.js";
 import { readConfig } from "#core/config/index.js";
 import { synthesize } from "#core/voice/tts.js";
 import { stripEmotionTags } from "#core/voice/emotions.js";
@@ -31,18 +33,17 @@ import { extractSuggestions } from "#core/agent/suggestions.js";
 import { appendGlobalMessage } from "#core/stores/messages.js";
 import { appendErrorTrace, previewText } from "#core/logging.js";
 
-export function register(app, { projects, plugins, registries }) {
+export function register(api, { projects, plugins, registries }) {
   // GET /voice/tts?path=<abs>
   //
   // Streams a TTS audio file back to the caller. Sandboxed to the
   // ~/.apx/tmp/tts directory so a client can't request arbitrary
   // filesystem paths through a manifest-leaked reply_audio_path.
-  app.get("/voice/tts", async (req, res) => {
+  api.get("/voice/tts", async (req, res) => {
     const rawPath = String(req.query.path || "");
     if (!rawPath) return res.status(400).json({ error: "path required" });
     try {
-      const os = await import("node:os");
-      const ttsRoot = path.resolve(os.homedir(), ".apx", "tmp", "tts");
+      const ttsRoot = path.resolve(TTS_TMP_DIR);
       const resolved = path.resolve(rawPath);
       if (!resolved.startsWith(ttsRoot + path.sep)) {
         return res.status(403).json({ error: "path outside tts dir" });
@@ -65,7 +66,7 @@ export function register(app, { projects, plugins, registries }) {
     }
   });
 
-  app.post("/voice/turn", async (req, res) => {
+  api.post("/voice/turn", async (req, res) => {
     const body = req.body || {};
     const cfg = readConfig();
     let userText = (body.text || "").trim();
@@ -103,7 +104,7 @@ export function register(app, { projects, plugins, registries }) {
         : [];
       const channel = body.channel || "voice";
       let suggestions = [];
-      let toolsUsed = [];
+      const toolsUsed = [];
       // Attribution for the persisted turn (see the appendGlobalMessage below).
       let replyModel = null;
       let replyUsage = null;
@@ -128,7 +129,8 @@ export function register(app, { projects, plugins, registries }) {
             systemSuffix: channelCtx.systemSuffix,
             previousMessages,
           });
-          const raw = (result?.text || "").trim();
+          // Spoken back to the user — never narrate raw planning.
+          const raw = stripReasoning(result?.text || "").answer.trim();
           replyModel = result?.model || null;
           replyUsage = result?.usage || null;
           replyName = result?.name || null;

package/src/host/daemon/api/web.js

@@ -2,9 +2,10 @@
 //
 // The web bundle is built into src/interfaces/web/dist. When that folder
 // exists, this module mounts it at `/` so users can open
-// http://127.0.0.1:7430 and get the UI. SPA fallback: anything that isn't an
-// /api/* / /projects/* / etc. route falls through to index.html so React
-// Router can resolve client-side paths like /p/1/tasks.
+// http://127.0.0.1:7430 and get the UI. The root namespace belongs to the
+// panel alone — every data route lives under /api (see ./prefix.js) — so the
+// SPA fallback only has to step aside for that single prefix instead of a
+// hand-maintained list that drifts away from the route registry.
 //
 // During development the user runs `vite dev` on :7431 with proxy → :7430,
 // so this mount is a no-op (dist/ doesn't exist yet).
@@ -12,29 +13,17 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { isApiPath } from "./prefix.js";
+
+// Re-exported so the SPA/API seam keeps a single import site for callers that
+// reason about "which side of the seam is this path on?" (tests, auth).
+export { isApiPath };
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // host/daemon/api/web.js → ../../..  = src/   then interfaces/web/dist
 const WEB_DIST = path.resolve(__dirname, "..", "..", "..", "interfaces", "web", "dist");
 
-// Paths the panel is NOT allowed to swallow with its SPA fallback. These are
-// the real API surfaces; we keep the list flat so it doesn't drift away from
-// the actual route registry.
-const API_PREFIXES = [
-  "/health", "/admin", "/projects", "/telegram", "/engines", "/runtimes",
-  "/messages", "/sessions", "/tools", "/mcp", "/voice", "/tts", "/desktop", "/overlay",
-  "/transcribe", "/run", "/files", "/memory", "/env", "/pair", "/deck",
-  "/super-agent", "/identity", "/skills", "/profiles", "/inbox",
-  "/tasks", "/agents", "/plugins", "/previews", "/embeddings",
-];
-
-export function isApiPath(p) {
-  for (const prefix of API_PREFIXES) {
-    if (p === prefix || p.startsWith(prefix + "/")) return true;
-  }
-  return false;
-}
-
 // Client-side routes the SPA actually knows how to render. Must mirror the
 // <Routes> registry in src/interfaces/web/src/App.tsx. Anything else still
 // gets the SPA shell (so React Router shows the styled 404 page) but with an
@@ -51,15 +40,18 @@ export function isKnownSpaRoute(p) {
   return SPA_ROUTES.some((re) => re.test(p));
 }
 
-export function register(app, { express, token }) {
-  // /admin/web-token: localhost-only endpoint that returns the daemon token
-  // so the same-origin admin panel can authenticate every subsequent call.
-  // Refuses if the request didn't come from loopback. Also refuses if the
-  // request was tunneled in via Cloudflare/ngrok/etc. — those connect from
-  // a local agent so the socket IP IS loopback, but tunnel-specific headers
-  // give them away. When tunneled, the SPA must instead receive the token
-  // via URL fragment (#token=…) that the operator shares out-of-band.
-  app.get("/admin/web-token", (req, res) => {
+// /api/admin/web-token: localhost-only endpoint that returns the daemon token
+// so the same-origin admin panel can authenticate every subsequent call.
+// Refuses if the request didn't come from loopback. Also refuses if the
+// request was tunneled in via Cloudflare/ngrok/etc. — those connect from
+// a local agent so the socket IP IS loopback, but tunnel-specific headers
+// give them away. When tunneled, the SPA must instead receive the token
+// via URL fragment (#token=…) that the operator shares out-of-band.
+//
+// Registered on the API router (not the static mount below) so the panel's
+// bootstrap call is a normal /api/* request like every other.
+export function registerWebToken(api, { token }) {
+  api.get("/admin/web-token", (req, res) => {
     const ra = req.ip || req.socket?.remoteAddress || "";
     const isLocal =
       ra === "127.0.0.1" ||
@@ -86,7 +78,11 @@ export function register(app, { express, token }) {
     }
     res.json({ token });
   });
+}
 
+// Static admin panel at the root. Mounted after `app.use("/api", api)` in
+// api.js, so a stray /api/* request can never reach the SPA fallback.
+export function register(app, { express }) {
   if (!fs.existsSync(WEB_DIST)) {
     // No build present. Expose a hint endpoint so users hitting the daemon
     // root know what to do.
@@ -112,8 +108,8 @@ export function register(app, { express, token }) {
     return;
   }
 
-  // Serve static assets. NB: we mount AFTER the API routes are registered
-  // in api.js so /projects, /admin/*, etc. always win over the catch-all.
+  // Serve static assets. NB: we mount AFTER the /api router is mounted in
+  // api.js so data routes always win over this catch-all.
   app.use(
     express.static(WEB_DIST, {
       index: false,