@code-partner/codepipe-hub 0.14.1-dev.422.gf90f06c4 → 0.14.1-dev.424.ge3c8cc77

package/hub/dist/index.js

@@ -13,7 +13,7 @@ var PLATFORM_VERSION;
 var init_version_generated = __esm({
   "../packages/shared/dist/version.generated.js"() {
     "use strict";
-    PLATFORM_VERSION = "0.14.1-dev.422.gf90f06c4";
+    PLATFORM_VERSION = "0.14.1-dev.424.ge3c8cc77";
   }
 });
 
@@ -31,8 +31,8 @@ var init_version = __esm({
   "../packages/shared/dist/version.js"() {
     "use strict";
     init_version_generated();
-    PROTOCOL_VERSION = 4;
-    MIN_SUPPORTED_PROTOCOL = 4;
+    PROTOCOL_VERSION = 5;
+    MIN_SUPPORTED_PROTOCOL = 5;
   }
 });
 
@@ -2960,21 +2960,14 @@ var init_duration = __esm({
 });
 
 // ../packages/shared/dist/node-handshake.js
-function readNodeSocketSecrets(headers, query) {
-  const found = [];
+function readNodeSocketSecret(headers) {
   const raw = headers["authorization"];
   const header = Array.isArray(raw) ? raw[0] : raw;
-  if (typeof header === "string") {
-    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
-    const token = match?.[1]?.trim();
-    if (token !== void 0 && token !== "")
-      found.push({ token, source: "header" });
-  }
-  const fromQuery = query?.token;
-  if (typeof fromQuery === "string" && fromQuery !== "") {
-    found.push({ token: fromQuery, source: "query" });
-  }
-  return found;
+  if (typeof header !== "string")
+    return null;
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  const token = match?.[1]?.trim();
+  return token !== void 0 && token !== "" ? token : null;
 }
 function decideNodeHandshake(frame, hub, recognizedCapabilities, authenticatedAs) {
   const handshake = parseNodeHandshake(frame);
@@ -8682,7 +8675,10 @@ var init_route_definition = __esm({
       node: ["/node/v1"],
       local: ["/local"],
       mcp: ["/mcp"],
-      bootstrap: ["/auth", "/bootstrap"],
+      // `/cli` is the CLI's own bootstrap: the connection request it opens, the
+      // page and the email link a person confirms it on (DEV-927 settled it here
+      // rather than moving a path the CLI and a sent email already hold).
+      bootstrap: ["/auth", "/bootstrap", "/cli"],
       operational: ["/healthz", "/readyz"],
       // Static serves the browser bundle from the root and the install script from
       // its documented path (ADR-0060 §5), so it has no single prefix to check.
@@ -8704,7 +8700,8 @@ var init_route_definition = __esm({
       "/api/tasks",
       "/api/projects",
       "/api/admin",
-      "/api/notifications"
+      "/api/notifications",
+      "/bug-report"
     ];
     PUBLIC_MUTATION_ALLOWLIST = [
       "auth.login",
@@ -8712,18 +8709,20 @@ var init_route_definition = __esm({
       "auth.loginPassword",
       "auth.logout",
       "auth.register",
-      "auth.setPassword",
       "bootstrap.request",
-      "bootstrap.confirm",
       "bootstrap.authorizeEmail",
-      "bootstrap.authorizeConfirm"
+      // DEV-927: a node registers with a registration token in the body — the
+      // token IS the credential, and there is no node identity yet to bear it.
+      "node.sandbox.register",
+      "node.farm.register",
+      "node.runner.register"
     ];
   }
 });
 
 // src/http/route-registry.ts
-function installRouteGuard(app, mode, log) {
-  const registry = new RouteRegistry(mode, log);
+function installRouteGuard(app, mode, log, legacy = []) {
+  const registry = new RouteRegistry(mode, log, legacy);
   app.addHook("onRoute", (route) => registry.inspect(route));
   return registry;
 }
@@ -8744,15 +8743,18 @@ var init_route_registry = __esm({
     init_route_definition();
     META_KEY = "codepipeRoute";
     RouteRegistry = class {
-      constructor(mode, log = { warn: (message) => console.warn(message) }) {
+      constructor(mode, log = { warn: (message) => console.warn(message) }, legacy = []) {
         this.mode = mode;
         this.log = log;
+        this.legacyAllowed = new Set(legacy);
       }
       routes = /* @__PURE__ */ new Map();
       paths = /* @__PURE__ */ new Set();
       operationIds = /* @__PURE__ */ new Set();
       unclassified = 0;
       invalid = 0;
+      legacyAllowed;
+      legacySeen = /* @__PURE__ */ new Set();
       /** Every route registered with metadata, in registration order. */
       list() {
         return [...this.routes.values()];
@@ -8770,6 +8772,12 @@ var init_route_registry = __esm({
       unclassifiedCount() {
         return this.unclassified;
       }
+      /** The same registrations by name (`METHOD /path`), so a test can hold the
+       *  legacy list to exactly what the process still serves: an entry nobody
+       *  registers any more is a stale allowance, and it fails there. */
+      unclassifiedRoutes() {
+        return [...this.legacySeen];
+      }
       /** Registrations that had metadata and broke a rule. Counted separately from
        *  the unclassified ones: "not migrated yet" and "migrated wrongly" are
        *  different problems, and a violation that lands in neither count is a
@@ -8789,12 +8797,14 @@ var init_route_registry = __esm({
         if (methods.length === 0) return;
         this.paths.add(route.url);
         if (!meta) {
-          this.unclassified += 1;
-          if (this.mode === "enforce") {
+          const tolerated = methods.every((method) => this.legacyAllowed.has(`${method} ${route.url}`));
+          if (this.mode === "enforce" && !tolerated) {
             throw new Error(
-              `route registry: ${methods.join("/")} ${route.url} registered without metadata \u2014 every route declares its surface, operationId and policy (ADR-0060 \xA73)`
+              `route registry: ${methods.join("/")} ${route.url} registered without metadata \u2014 every route declares its surface, operationId and policy (ADR-0060 \xA73); the old roots are closed since the cutover (DEV-927)`
             );
           }
+          this.unclassified += 1;
+          for (const method of methods) this.legacySeen.add(`${method} ${route.url}`);
           return;
         }
         const violations = methods.flatMap(
@@ -12239,6 +12249,8 @@ function createCommandOperations(deps) {
         throw errors.unprocessable({ details: { reason: outcome.reason } });
       case "not_found":
         throw errors.notFound();
+      case "rate_limited":
+        throw errors.rateLimited();
     }
   }
   function accountActorOf(actor) {
@@ -12828,6 +12840,14 @@ function createCommandOperations(deps) {
         return { value: run.result, replayed: run.replayed };
       });
     },
+    async issueWorkerRegistrationToken(actor) {
+      const subjectId = actor.principal.subjectId;
+      return await audited(actor, { operationId: "worker.issueRegistrationToken", aggregateType: "account", aggregateId: subjectId, projectId: null }, async (policy) => {
+        await require2(actor, "account.manage", { type: "account" }, policy);
+        const issued = unwrap(await write2.issueWorkerRegistrationToken({ owner: accountActorOf(actor) }));
+        return { value: { secret: issued.secret, expiresAt: toTimestamp(issued.expiresAt) }, replayed: false };
+      });
+    },
     async reportInitStatus(actor, command) {
       const { projectId, phase } = command;
       return await audited(actor, { operationId: "project.reportInitStatus", aggregateType: "project", aggregateId: projectId, projectId, data: { phase, failed: command.error !== void 0 } }, async (policy) => {
@@ -13125,8 +13145,8 @@ var init_cutover_preflight = __esm({
     SECRET_CONSUMERS = [
       { consumer: "agent credential in the job bundle (Claude / Codex)", purpose: "agent_execution", implemented: true, note: "issued per job from the project's auth mode" },
       { consumer: "repository clone tokens in the job bundle (GitHub / GitLab / Bitbucket)", purpose: "repository_read", implemented: true, note: "one grant for each host the job clones" },
-      { consumer: "Context Repo push of the delivery from the SANDBOX (contextWrite)", purpose: "context_write", implemented: false, note: "open: the delivery has to reach the holder of the materializer role without a write credential on the SANDBOX \u2014 the transport is an owner's decision" },
-      { consumer: "mirror clone token in the job bundle (mirrorWrite, read use)", purpose: "repository_read", implemented: false, note: "open: a read grant under the mirror's host, issued with the delivery transport" },
+      { consumer: "Context Repo push of the delivery from the SANDBOX (contextWrite)", purpose: "context_write", implemented: true, note: "the SANDBOX publishes the delivery over the host-local relay and the holder of the materializer role pushes it; no write credential on the SANDBOX" },
+      { consumer: "mirror clone token in the job bundle (mirrorWrite, read use)", purpose: "repository_read", implemented: true, note: "a read grant under the mirror's host, issued by the holder of the role with the other repository grants" },
       { consumer: "tracker writes (YouTrack) \u2014 CLI-side, never on the SANDBOX", purpose: "tracker_write", implemented: true, note: "nothing to move: the holder of the role already writes" },
       { consumer: "named project secrets in custom-action runs \u2014 CLI-side", purpose: "custom_action", implemented: true, note: "nothing to move until a tool-run executes on the SANDBOX" }
     ];
@@ -25805,10 +25825,16 @@ async function deleteSandboxRegistration(db, sandboxId) {
 async function sandboxRoutes(app, deps) {
   const { db, config } = deps;
   const registerByIp = createAbuseThrottle({ windowMs: 15 * 6e4, max: 30 });
-  const regTokenMintByEmail = createAbuseThrottle({ windowMs: 60 * 6e4, max: 30 });
   app.post(
-    "/sandbox/register",
+    "/node/v1/sandbox/register",
     {
+      ...routeMeta({
+        surface: "node",
+        operationId: "node.sandbox.register",
+        authPolicy: "public",
+        stability: "preview",
+        summary: "Register a SANDBOX with a registration token"
+      }),
       schema: {
         body: {
           type: "object",
@@ -25849,14 +25875,29 @@ async function sandboxRoutes(app, deps) {
       return { sandboxId: id, token };
     }
   );
-  app.get("/sandbox/me", async (req, reply) => {
+  app.get("/node/v1/sandbox/me", routeMeta({
+    surface: "node",
+    operationId: "node.sandbox.me",
+    authPolicy: "node_actor",
+    resourcePolicy: "node.connect",
+    stability: "preview",
+    summary: "Is this SANDBOX registration still known"
+  }), async (req, reply) => {
     const sandbox = await authenticateSandboxByBearer(db, req.headers.authorization);
     if (!sandbox) return reply.status(401).send({ error: "unauthorized" });
     return { sandboxId: sandbox.id, name: sandbox.name };
   });
   app.post(
-    "/sandbox/agent-auth",
+    "/node/v1/sandbox/agent-auth",
     {
+      ...routeMeta({
+        surface: "node",
+        operationId: "node.sandbox.agentAuth",
+        authPolicy: "node_actor",
+        resourcePolicy: "node.connect",
+        stability: "preview",
+        summary: "Report the host's agent login and ask whether to probe it"
+      }),
       schema: {
         body: {
           type: "object",
@@ -25892,8 +25933,16 @@ async function sandboxRoutes(app, deps) {
     }
   );
   app.post(
-    "/sandbox/agent-auth/result",
+    "/node/v1/sandbox/agent-auth/result",
     {
+      ...routeMeta({
+        surface: "node",
+        operationId: "node.sandbox.agentAuthResult",
+        authPolicy: "node_actor",
+        resourcePolicy: "node.connect",
+        stability: "preview",
+        summary: "Report the verdict of an agent login probe"
+      }),
       schema: {
         body: {
           type: "object",
@@ -25943,19 +25992,6 @@ async function sandboxRoutes(app, deps) {
     app.log.info({ email: session.email, revoked }, "sandbox reg token revoked");
     return { revoked };
   });
-  app.post("/sandbox/reg-token/cli", async (req, reply) => {
-    const auth = await resolveCliAuth(db, config, req.headers.authorization);
-    if (!auth) {
-      return reply.status(401).send({ error: "bad_cli_token" });
-    }
-    if (!regTokenMintByEmail.take(`email:${auth.email}`)) {
-      app.log.warn({ email: auth.email }, "ephemeral sandbox reg token mint throttled");
-      return reply.status(429).send({ error: "too_many_requests" });
-    }
-    const { secret, expiresAt } = await issueEphemeralSandboxRegToken(db, auth.email);
-    app.log.info({ email: auth.email }, "ephemeral sandbox reg token issued for CLI");
-    return { secret, expiresAt };
-  });
   app.delete(
     "/sandbox/:sandboxId",
     async (req, reply) => {
@@ -25992,11 +26028,11 @@ var init_sandbox2 = __esm({
     init_sealedbox();
     init_abuse_throttle();
     init_auth();
-    init_cli_auth();
     init_sandbox_reg_tokens();
     init_users();
     init_agent_auth_probe();
     init_ws();
+    init_route_registry();
   }
 });
 
@@ -26060,8 +26096,15 @@ async function farmRoutes(app, deps) {
   const { db, config } = deps;
   const registerByIp = createAbuseThrottle({ windowMs: 15 * 6e4, max: 10 });
   app.post(
-    "/farm/register",
+    "/node/v1/farm/register",
     {
+      ...routeMeta({
+        surface: "node",
+        operationId: "node.farm.register",
+        authPolicy: "public",
+        stability: "preview",
+        summary: "Register a FARM with the operator's registration token"
+      }),
       schema: {
         body: {
           type: "object",
@@ -26140,6 +26183,7 @@ var init_farm2 = __esm({
     init_sealedbox();
     init_abuse_throttle();
     init_ws();
+    init_route_registry();
   }
 });
 
@@ -26241,8 +26285,15 @@ async function runnerRoutes(app, deps) {
   const { db, config } = deps;
   const registerByIp = createAbuseThrottle({ windowMs: 15 * 6e4, max: 10 });
   app.post(
-    "/runner/register",
+    "/node/v1/runner/register",
     {
+      ...routeMeta({
+        surface: "node",
+        operationId: "node.runner.register",
+        authPolicy: "public",
+        stability: "preview",
+        summary: "Register a RUNNER host with a personal registration token"
+      }),
       schema: {
         body: {
           type: "object",
@@ -26345,6 +26396,7 @@ var init_runner2 = __esm({
     init_users();
     init_runner_reg_tokens();
     init_ws();
+    init_route_registry();
   }
 });
 
@@ -27524,23 +27576,11 @@ function installSocketKeepalive(socket, periodMs) {
 }
 async function wsRoutes(app, deps) {
   const { db, config } = deps;
-  async function authenticateSocket(req, component, resolve4) {
-    for (const secret of readNodeSocketSecrets(req.headers, req.query)) {
-      const resolved = await resolve4(secret.token);
-      if (resolved === null || resolved === void 0) continue;
-      if (secret.source === "query") warnAboutQueryCredential(component, req.ip ?? null);
-      return resolved;
-    }
-    return null;
-  }
-  const warnedComponents = /* @__PURE__ */ new Set();
-  function warnAboutQueryCredential(component, remote) {
-    if (warnedComponents.has(component)) return;
-    warnedComponents.add(component);
-    app.log.warn(
-      { component, remote },
-      "node socket authenticated from the query string \u2014 the credential lands in proxy logs; update the component to send it in the Authorization header (this is logged once)"
-    );
+  async function authenticateSocket(req, resolve4) {
+    const token = readNodeSocketSecret(req.headers);
+    if (token === null) return null;
+    const resolved = await resolve4(token);
+    return resolved === null || resolved === void 0 ? null : resolved;
   }
   const cliSocket = async (socket, req) => {
     let boundProjectId = null;
@@ -27877,7 +27917,7 @@ async function wsRoutes(app, deps) {
         app.log.info({ remote: req.ip }, "CLI socket closed (never registered)");
       }
     });
-    auth = await authenticateSocket(req, "cli", (token) => authFromSecret(db, config, token));
+    auth = await authenticateSocket(req, (token) => authFromSecret(db, config, token));
     if (!auth) {
       socket.close(1008, "unauthorized");
       return;
@@ -27895,7 +27935,7 @@ async function wsRoutes(app, deps) {
     void pump();
   };
   const sandboxSocket = async (socket, req) => {
-    const sandbox = await authenticateSocket(req, "sandbox", (token) => findSandboxByToken(db, token));
+    const sandbox = await authenticateSocket(req, (token) => findSandboxByToken(db, token));
     if (!sandbox) {
       socket.close(1008, "unauthorized");
       return;
@@ -28013,7 +28053,7 @@ async function wsRoutes(app, deps) {
     });
   };
   const farmSocket = async (socket, req) => {
-    const farm = await authenticateSocket(req, "farm", (token) => findFarmByToken(db, token));
+    const farm = await authenticateSocket(req, (token) => findFarmByToken(db, token));
     if (!farm) {
       socket.close(1008, "unauthorized");
       return;
@@ -28105,7 +28145,7 @@ async function wsRoutes(app, deps) {
     });
   };
   const runnerSocket = async (socket, req) => {
-    const runner = await authenticateSocket(req, "runner", (token) => findRunnerByToken(db, token));
+    const runner = await authenticateSocket(req, (token) => findRunnerByToken(db, token));
     if (!runner) {
       socket.close(1008, "unauthorized");
       return;
@@ -28237,10 +28277,12 @@ async function wsRoutes(app, deps) {
         }
         const auth = parseNodeAuth(parsed);
         if (auth !== null) {
-          if (auth.component !== component || !await authenticate({ ...req, headers: { authorization: `Bearer ${auth.token}` } })) {
+          const withFrameCredential = { ...req, headers: { ...req.headers, authorization: `Bearer ${auth.token}` } };
+          if (auth.component !== component || !await authenticate(withFrameCredential)) {
             refuse("unauthenticated");
             return;
           }
+          effectiveReq = withFrameCredential;
           authenticated = true;
           return;
         }
@@ -28277,7 +28319,7 @@ async function wsRoutes(app, deps) {
         socket.off("message", listener);
         socket.pause();
         try {
-          await inner(socket, req);
+          await inner(socket, effectiveReq);
         } catch (err) {
           app.log.error({ err, component }, "node socket handler failed after handshake");
           socket.close(1011, "handler_failed");
@@ -28288,6 +28330,7 @@ async function wsRoutes(app, deps) {
         socket.resume();
       };
       let authenticated = false;
+      let effectiveReq = req;
       const ready = authenticate(req).then((ok2) => {
         authenticated = ok2;
       });
@@ -28321,7 +28364,6 @@ async function wsRoutes(app, deps) {
       });
     }
   }
-  app.get("/cli/connect", { websocket: true }, cliSocket);
   app.get(
     "/node/v1/cli/connect",
     {
@@ -28335,9 +28377,8 @@ async function wsRoutes(app, deps) {
         summary: "Control socket of a CLI instance"
       })
     },
-    withNodeHandshake("cli", async (r) => await authenticateSocket(r, "cli", (token) => authFromSecret(db, config, token)) !== null, cliSocket)
+    withNodeHandshake("cli", async (r) => await authenticateSocket(r, (token) => authFromSecret(db, config, token)) !== null, cliSocket)
   );
-  app.get("/sandbox/connect", { websocket: true }, sandboxSocket);
   app.get(
     "/node/v1/sandbox/connect",
     {
@@ -28351,9 +28392,8 @@ async function wsRoutes(app, deps) {
         summary: "Control socket of a SANDBOX instance"
       })
     },
-    withNodeHandshake("sandbox", async (r) => await authenticateSocket(r, "sandbox", (token) => findSandboxByToken(db, token)) !== null, sandboxSocket)
+    withNodeHandshake("sandbox", async (r) => await authenticateSocket(r, (token) => findSandboxByToken(db, token)) !== null, sandboxSocket)
   );
-  app.get("/farm/connect", { websocket: true }, farmSocket);
   app.get(
     "/node/v1/farm/connect",
     {
@@ -28367,9 +28407,8 @@ async function wsRoutes(app, deps) {
         summary: "Control socket of a FARM instance"
       })
     },
-    withNodeHandshake("farm", async (r) => await authenticateSocket(r, "farm", (token) => findFarmByToken(db, token)) !== null, farmSocket)
+    withNodeHandshake("farm", async (r) => await authenticateSocket(r, (token) => findFarmByToken(db, token)) !== null, farmSocket)
   );
-  app.get("/runner/connect", { websocket: true }, runnerSocket);
   app.get(
     "/node/v1/runner/connect",
     {
@@ -28383,7 +28422,7 @@ async function wsRoutes(app, deps) {
         summary: "Control socket of a RUNNER instance"
       })
     },
-    withNodeHandshake("runner", async (r) => await authenticateSocket(r, "runner", (token) => findRunnerByToken(db, token)) !== null, runnerSocket)
+    withNodeHandshake("runner", async (r) => await authenticateSocket(r, (token) => findRunnerByToken(db, token)) !== null, runnerSocket)
   );
 }
 var agentLoginProviders, deliveryFollowers, projectCliConnections, projectLastSeenAt, projectLastDuplicateRegisterAt, sandboxConnections, farmConnections, runnerConnections, cliMessageHandlers, cliRegisterHandlers, cliDisconnectHandlers, farmMessageHandlers, runnerMessageHandlers, providerMessageHandlers, RECOGNIZED_NODE_CAPABILITIES, NODE_HANDSHAKE_BACKLOG, NODE_HANDSHAKE_TIMEOUT_MS;
@@ -28879,9 +28918,7 @@ var DASHBOARD_ROUTES = [
 var CONSOLE_ROUTES = [/^\/$/];
 var DECLARED_RESERVED_ROOTS = [
   ...Object.values(SURFACE_PREFIXES).flat(),
-  ...RETIRED_ROOTS,
-  "/cli",
-  "/ws"
+  ...RETIRED_ROOTS
 ];
 function isBrowserRoute(app, path) {
   const clean = path.split("?")[0].split("#")[0];
@@ -28978,9 +29015,22 @@ var RETIRED_SOCKET_PATHS = [
   "/farm/connect",
   "/runner/connect"
 ];
+var RETIRED_NODE_PATHS = [
+  "/jobs/claim",
+  "/jobs/heartbeat",
+  "/jobs/release",
+  "/jobs/result",
+  "/sandbox/register",
+  "/sandbox/me",
+  "/sandbox/agent-auth",
+  "/sandbox/agent-auth/result",
+  "/sandbox/reg-token/cli",
+  "/farm/register",
+  "/runner/register"
+];
 function isRetiredClientPath(url, registeredPaths = []) {
   const path = url.split("?")[0].split("#")[0];
-  if (RETIRED_SOCKET_PATHS.includes(path)) return !registeredPaths.includes(path);
+  if (RETIRED_SOCKET_PATHS.includes(path) || RETIRED_NODE_PATHS.includes(path)) return !registeredPaths.includes(path);
   const retired = RETIRED_ROOTS.find((root) => path === root || path.startsWith(`${root}/`));
   if (retired === void 0) return false;
   return !registeredPaths.some((p) => p === retired || p.startsWith(`${retired}/`));
@@ -29032,6 +29082,121 @@ async function registerSpaHosts(app, opts) {
 // src/server.ts
 init_route_registry();
 
+// src/http/legacy-routes.ts
+var STATIC_PLUGIN_ROUTES = ["GET /*"];
+var LEGACY_ROUTES = [
+  "DELETE /api/admin/farms/:farmId",
+  "DELETE /api/admin/runners/:runnerId",
+  "DELETE /api/admin/sandboxes/:sandboxId",
+  "DELETE /projects/:projectId/secrets/:name",
+  "DELETE /runner/:runnerId",
+  "DELETE /runner/reg-token",
+  "DELETE /sandbox/:sandboxId",
+  "DELETE /sandbox/reg-token",
+  "GET /admin/pause",
+  "GET /api/admin/farms",
+  "GET /api/admin/logs",
+  "GET /api/admin/presence",
+  "GET /api/admin/projects",
+  "GET /api/admin/registrations",
+  "GET /api/admin/runners",
+  "GET /api/admin/server",
+  "GET /api/admin/settings",
+  "GET /api/admin/stats",
+  "GET /api/admin/users",
+  "GET /api/notifications/settings",
+  "GET /api/projects/:projectId/tasks/:taskKey/plan-review",
+  "GET /bug-report",
+  "GET /projects/:projectId/actions",
+  "GET /projects/:projectId/adr-backfill",
+  "GET /projects/:projectId/clusters/:anchorKey/journal",
+  "GET /projects/:projectId/config-proposals/:proposalId/agent-activity/stream",
+  "GET /projects/:projectId/context-file",
+  "GET /projects/:projectId/drafts/:draftId/agent-activity/stream",
+  "GET /projects/:projectId/model/drift",
+  "GET /projects/:projectId/model/search",
+  "GET /projects/:projectId/pause",
+  "GET /projects/:projectId/prompts",
+  "GET /projects/:projectId/prompts/:role",
+  "GET /projects/:projectId/review-metrics",
+  "GET /projects/:projectId/runs",
+  "GET /projects/:projectId/runs/:runId/stream",
+  "GET /projects/:projectId/tasks/:taskKey/actions",
+  "GET /projects/:projectId/tasks/:taskKey/agent-activity/stream",
+  "GET /projects/:projectId/tasks/:taskKey/external-review/draft",
+  "GET /projects/:projectId/tasks/:taskKey/review-rounds",
+  "GET /projects/:projectId/tracker-status",
+  "GET /projects/:projectId/tracker/fields",
+  "GET /runner/reg-token",
+  "GET /runners",
+  "GET /sandbox/reg-token",
+  "POST /admin/pause",
+  "POST /api/admin/farms/:farmId/assign",
+  "POST /api/admin/farms/:farmId/unassign",
+  "POST /api/admin/registrations/:id/approve",
+  "POST /api/admin/registrations/:id/reject",
+  "POST /api/admin/runners/:runnerId/owner",
+  "POST /api/admin/users",
+  "POST /api/admin/users/:email/activate",
+  "POST /api/admin/users/:email/block",
+  "POST /api/projects/:projectId/tasks/:taskKey/develop",
+  "POST /api/projects/:projectId/tasks/:taskKey/observer-answer",
+  "POST /api/projects/:projectId/tasks/:taskKey/plan-review",
+  "POST /api/projects/:projectId/tasks/:taskKey/stage",
+  "POST /api/projects/:projectId/tasks/:taskKey/workflow-route",
+  "POST /bug-report",
+  "POST /projects/:projectId/actions/:actionId/run",
+  "POST /projects/:projectId/adr-backfill/discard",
+  "POST /projects/:projectId/adr-backfill/promote",
+  "POST /projects/:projectId/check-readiness",
+  "POST /projects/:projectId/clusters/:anchorKey/reject",
+  "POST /projects/:projectId/creds",
+  "POST /projects/:projectId/detach-from-farm",
+  "POST /projects/:projectId/gh-runner/connect",
+  "POST /projects/:projectId/gh-runner/disconnect",
+  "POST /projects/:projectId/model-bootstrap",
+  "POST /projects/:projectId/move-to-farm",
+  "POST /projects/:projectId/pause",
+  "POST /projects/:projectId/refresh-context-status",
+  "POST /projects/:projectId/retry-init",
+  "POST /projects/:projectId/secrets",
+  "POST /projects/:projectId/sync-config",
+  "POST /projects/:projectId/sync-context",
+  "POST /projects/:projectId/tasks/:taskKey/actions/:actionId/run",
+  "POST /projects/:projectId/tasks/:taskKey/approve",
+  "POST /projects/:projectId/tasks/:taskKey/build-flag",
+  "POST /projects/:projectId/tasks/:taskKey/cancel",
+  "POST /projects/:projectId/tasks/:taskKey/comment",
+  "POST /projects/:projectId/tasks/:taskKey/external-review/close",
+  "POST /projects/:projectId/tasks/:taskKey/external-review/dismiss",
+  "POST /projects/:projectId/tasks/:taskKey/external-review/publish",
+  "POST /projects/:projectId/tasks/:taskKey/external-review/rerun",
+  "POST /projects/:projectId/tasks/:taskKey/external-review/start",
+  "POST /projects/:projectId/tasks/:taskKey/force-done",
+  "POST /projects/:projectId/tasks/:taskKey/open-pr",
+  "POST /projects/:projectId/tasks/:taskKey/pause",
+  "POST /projects/:projectId/tasks/:taskKey/publish-branch",
+  "POST /projects/:projectId/tasks/:taskKey/reject",
+  "POST /projects/:projectId/tasks/:taskKey/restart",
+  "POST /projects/:projectId/tasks/:taskKey/retry",
+  "POST /projects/:projectId/tasks/:taskKey/to-backlog",
+  "POST /projects/:projectId/tasks/:taskKey/tracker-status",
+  "POST /projects/:projectId/tasks/:taskKey/unarchive",
+  "POST /projects/:projectId/tracker-sync",
+  "POST /runner/reg-token",
+  "POST /sandbox/reg-token",
+  "PUT /api/admin/farms/:farmId/quota",
+  "PUT /api/admin/settings",
+  "PUT /api/notifications/settings",
+  "PUT /projects/:projectId/adr/:file",
+  "PUT /projects/:projectId/prompts/:role",
+  "PUT /projects/:projectId/tasks/:taskKey/branch-name",
+  "PUT /projects/:projectId/tasks/:taskKey/cluster-base",
+  "PUT /projects/:projectId/tasks/:taskKey/commit-summary",
+  "PUT /projects/:projectId/tasks/:taskKey/description",
+  "PUT /projects/:projectId/tasks/:taskKey/solution"
+];
+
 // src/http/browser-security.ts
 init_auth();
 import { createHash as createHash9, randomBytes as randomBytes3 } from "node:crypto";
@@ -31024,6 +31189,28 @@ async function apiV1MutationRoutes(app, deps) {
       }
     }
   );
+  app.post(
+    "/workers/registration-token",
+    routeMeta({
+      surface: "application",
+      operationId: "worker.issueRegistrationToken",
+      authPolicy: "application_actor",
+      resourcePolicy: "account.manage",
+      stability: "preview",
+      summary: "Mint a single-use registration token for a worker of this account"
+    }),
+    async (req, reply) => {
+      const requestId = requestIdOf(req);
+      try {
+        const actor = await actorOr401({ db, config }, req, reply, requestId);
+        if (!actor) return reply;
+        const issued = await commands.issueWorkerRegistrationToken(actor);
+        return reply.status(201).send(issued);
+      } catch (err) {
+        return sendError(reply, err, requestId);
+      }
+    }
+  );
   app.post(
     "/projects/:projectId/init-status",
     routeMeta({
@@ -34145,6 +34332,8 @@ function requestGhRunnersDelete(runnerId, projectId, sealedBundle, timeoutMs) {
 init_farm2();
 init_runner2();
 init_init_status();
+init_sandbox_reg_tokens();
+init_abuse_throttle();
 
 // src/projects/forget.ts
 init_legacy_cred_bundles();
@@ -34426,6 +34615,7 @@ function nodeUnavailable(capability, err) {
 function taskState(row) {
   return { ...row, revision: String(row.updatedAt) };
 }
+var WORKER_REG_TOKEN_MINTS = createAbuseThrottle({ windowMs: 60 * 6e4, max: 30 });
 function createWriteModel(db, log, hooks = {}) {
   async function readTaskRow(projectId, key) {
     const row = await db.get(
@@ -35108,6 +35298,16 @@ function createWriteModel(db, log, hooks = {}) {
       log.info({ projectId, jobId, kind }, kind === "backfill" ? "backfill job enqueued" : "index job enqueued");
       return ok({ jobId });
     },
+    async issueWorkerRegistrationToken({ owner }) {
+      if (owner.email === null) return { ok: false, refusal: "unprocessable", reason: "account_has_no_email" };
+      if (!WORKER_REG_TOKEN_MINTS.take(`email:${owner.email}`)) {
+        log.warn({ email: owner.email }, "ephemeral sandbox reg token mint throttled");
+        return { ok: false, refusal: "rate_limited" };
+      }
+      const issued = await issueEphemeralSandboxRegToken(db, owner.email);
+      log.info({ email: owner.email }, "ephemeral sandbox reg token issued for a client");
+      return ok(issued);
+    },
     async reportInitStatus({ projectId, phase, error }) {
       const recorded = await advanceInitPhase(db, projectId, phase);
       if (error !== null) {
@@ -37925,6 +38125,7 @@ function clearPasswordAttempts(key) {
 
 // src/routes/auth.ts
 init_users();
+init_route_registry();
 async function authRoutes(app, deps) {
   const { db, config, mailer } = deps;
   const loginByIp = createAbuseThrottle({ windowMs: 15 * 6e4, max: 30 });
@@ -37965,18 +38166,21 @@ async function authRoutes(app, deps) {
   function registerAccountRoutes() {
     app.post(
       "/auth/login",
-      {
-        schema: {
-          body: {
-            type: "object",
-            required: ["email"],
-            properties: {
-              email: { type: "string", minLength: 3, maxLength: 254 },
-              pwa_nonce: { type: "string", minLength: 1, maxLength: 64 }
-            }
+      routeMeta({
+        surface: "bootstrap",
+        operationId: "auth.login",
+        authPolicy: "public",
+        stability: "preview",
+        summary: "Sign in: send a magic link",
+        requestSchema: {
+          type: "object",
+          required: ["email"],
+          properties: {
+            email: { type: "string", minLength: 3, maxLength: 254 },
+            pwa_nonce: { type: "string", minLength: 1, maxLength: 64 }
           }
         }
-      },
+      }),
       async (req, reply) => {
         const email = (req.body.email ?? "").trim().toLowerCase();
         if (loginThrottled(email, req.ip)) {
@@ -37994,18 +38198,21 @@ async function authRoutes(app, deps) {
     );
     app.post(
       "/auth/login-start",
-      {
-        schema: {
-          body: {
-            type: "object",
-            required: ["email"],
-            properties: {
-              email: { type: "string", minLength: 3, maxLength: 254 },
-              pwa_nonce: { type: "string", minLength: 1, maxLength: 64 }
-            }
+      routeMeta({
+        surface: "bootstrap",
+        operationId: "auth.loginStart",
+        authPolicy: "public",
+        stability: "preview",
+        summary: "Start a sign-in, without saying whether the account exists",
+        requestSchema: {
+          type: "object",
+          required: ["email"],
+          properties: {
+            email: { type: "string", minLength: 3, maxLength: 254 },
+            pwa_nonce: { type: "string", minLength: 1, maxLength: 64 }
           }
         }
-      },
+      }),
       async (req, reply) => {
         const email = (req.body.email ?? "").trim().toLowerCase();
         if (loginThrottled(email, req.ip)) {
@@ -38027,18 +38234,21 @@ async function authRoutes(app, deps) {
     );
     app.post(
       "/auth/login-password",
-      {
-        schema: {
-          body: {
-            type: "object",
-            required: ["email", "password"],
-            properties: {
-              email: { type: "string", minLength: 3, maxLength: 254 },
-              password: { type: "string", minLength: 1, maxLength: MAX_PASSWORD_LENGTH }
-            }
+      routeMeta({
+        surface: "bootstrap",
+        operationId: "auth.loginPassword",
+        authPolicy: "public",
+        stability: "preview",
+        summary: "Sign in with a password",
+        requestSchema: {
+          type: "object",
+          required: ["email", "password"],
+          properties: {
+            email: { type: "string", minLength: 3, maxLength: 254 },
+            password: { type: "string", minLength: 1, maxLength: MAX_PASSWORD_LENGTH }
           }
         }
-      },
+      }),
       async (req, reply) => {
         const email = (req.body.email ?? "").trim().toLowerCase();
         const password = req.body.password ?? "";
@@ -38062,15 +38272,18 @@ async function authRoutes(app, deps) {
     );
     app.post(
       "/auth/set-password",
-      {
-        schema: {
-          body: {
-            type: "object",
-            required: ["password"],
-            properties: { password: { type: "string", minLength: 1, maxLength: 512 } }
-          }
+      routeMeta({
+        surface: "bootstrap",
+        operationId: "auth.setPassword",
+        authPolicy: "session",
+        stability: "preview",
+        summary: "Set the signed-in account's password",
+        requestSchema: {
+          type: "object",
+          required: ["password"],
+          properties: { password: { type: "string", minLength: 1, maxLength: 512 } }
         }
-      },
+      }),
       async (req, reply) => {
         const session = await requireSession(db, req, reply);
         if (!session) return reply;
@@ -38089,7 +38302,14 @@ async function authRoutes(app, deps) {
         return reply.send({ status: "ok" });
       }
     );
-    app.get("/auth/verify", async (req, reply) => {
+    app.get("/auth/verify", routeMeta({
+      surface: "bootstrap",
+      operationId: "auth.verify",
+      authPolicy: "public",
+      // A redirect from an email link, not a JSON operation to generate a client for.
+      stability: "internal",
+      summary: "Redeem a magic link"
+    }), async (req, reply) => {
       const wantsHtml = (req.headers.accept ?? "").toLowerCase().includes("text/html");
       const token = (req.query.token ?? "").trim();
       if (!token) {
@@ -38111,7 +38331,14 @@ async function authRoutes(app, deps) {
     });
   }
   function registerSessionRoutes() {
-    app.get("/auth/me", async (req, reply) => {
+    app.get("/auth/me", routeMeta({
+      surface: "bootstrap",
+      operationId: "auth.me",
+      // A cookie, or the single-owner's credential on the local profile.
+      authPolicy: "application_actor",
+      stability: "preview",
+      summary: "Who is signed in"
+    }), async (req, reply) => {
       const session = await readSession(db, req);
       if (!session) return reply.status(401).send({ error: "no_session" });
       const user = await findUser(db, session.email);
@@ -38123,7 +38350,13 @@ async function authRoutes(app, deps) {
         singleOwner
       };
     });
-    app.post("/auth/logout", async (req, reply) => {
+    app.post("/auth/logout", routeMeta({
+      surface: "bootstrap",
+      operationId: "auth.logout",
+      authPolicy: "public",
+      stability: "preview",
+      summary: "Sign out"
+    }), async (req, reply) => {
       const cookie2 = req.cookies[SESSION_COOKIE_NAME];
       if (cookie2) {
         const unsigned = req.unsignCookie(cookie2);
@@ -38134,7 +38367,13 @@ async function authRoutes(app, deps) {
       reply.clearCookie(SESSION_COOKIE_NAME, { path: "/" });
       return { status: "ok" };
     });
-    app.get("/auth/pwa-ready", async (req, reply) => {
+    app.get("/auth/pwa-ready", routeMeta({
+      surface: "bootstrap",
+      operationId: "auth.pwaReady",
+      authPolicy: "public",
+      stability: "preview",
+      summary: "Whether an installed app's sign-in has completed"
+    }), async (req, reply) => {
       const nonce = (req.query.nonce ?? "").trim();
       if (!nonce) return reply.status(400).send({ error: "missing_nonce" });
       const result = await consumePwaNonce(db, nonce);
@@ -38159,6 +38398,7 @@ import { nanoid as nanoid41 } from "nanoid";
 init_settings();
 init_users();
 init_cli_tokens();
+init_route_registry();
 var REQUEST_TTL_MS = 15 * 6e4;
 var APPROVAL_TTL_MS = 24 * 60 * 6e4;
 async function cliBootstrapRoutes(app, deps) {
@@ -38192,15 +38432,18 @@ async function cliBootstrapRoutes(app, deps) {
   }
   app.post(
     "/cli/bootstrap-request",
-    {
-      schema: {
-        body: {
-          type: "object",
-          required: ["email"],
-          properties: { email: { type: "string", minLength: 3, maxLength: 254 } }
-        }
+    routeMeta({
+      surface: "bootstrap",
+      operationId: "bootstrap.request",
+      authPolicy: "public",
+      stability: "preview",
+      summary: "A CLI asks to be connected to an account",
+      requestSchema: {
+        type: "object",
+        required: ["email"],
+        properties: { email: { type: "string", minLength: 3, maxLength: 254 } }
       }
-    },
+    }),
     async (req, reply) => {
       const email = (req.body.email ?? "").trim().toLowerCase();
       if (!isValidEmail(email)) {
@@ -38248,6 +38491,14 @@ async function cliBootstrapRoutes(app, deps) {
   );
   app.get(
     "/cli/authorize",
+    routeMeta({
+      surface: "bootstrap",
+      operationId: "bootstrap.authorizePage",
+      authPolicy: "public",
+      // An HTML page, not a JSON operation to generate a client for.
+      stability: "internal",
+      summary: "The page where a person confirms a CLI connection"
+    }),
     async (req, reply) => {
       const requestId = (req.query.request ?? "").trim();
       const row = requestId ? await loadRequest(requestId) : void 0;
@@ -38296,15 +38547,19 @@ async function cliBootstrapRoutes(app, deps) {
   );
   app.post(
     "/cli/authorize/confirm",
-    {
-      schema: {
-        body: {
-          type: "object",
-          required: ["request"],
-          properties: { request: { type: "string", minLength: 1, maxLength: 64 } }
-        }
+    routeMeta({
+      surface: "bootstrap",
+      operationId: "bootstrap.authorizeConfirm",
+      // A cookie, or the single-owner's credential on the local profile.
+      authPolicy: "application_actor",
+      stability: "preview",
+      summary: "Confirm a CLI connection as the signed-in person",
+      requestSchema: {
+        type: "object",
+        required: ["request"],
+        properties: { request: { type: "string", minLength: 1, maxLength: 64 } }
       }
-    },
+    }),
     async (req, reply) => {
       const session = await readSession(db, req);
       if (!session || !await isAllowedLogin(db, config, session.email)) {
@@ -38322,15 +38577,18 @@ async function cliBootstrapRoutes(app, deps) {
   );
   app.post(
     "/cli/authorize/email",
-    {
-      schema: {
-        body: {
-          type: "object",
-          required: ["request"],
-          properties: { request: { type: "string", minLength: 1, maxLength: 64 } }
-        }
+    routeMeta({
+      surface: "bootstrap",
+      operationId: "bootstrap.authorizeEmail",
+      authPolicy: "public",
+      stability: "preview",
+      summary: "Confirm a CLI connection by email instead",
+      requestSchema: {
+        type: "object",
+        required: ["request"],
+        properties: { request: { type: "string", minLength: 1, maxLength: 64 } }
       }
-    },
+    }),
     async (req, reply) => {
       const requestId = (req.body.request ?? "").trim();
       const row = await loadRequest(requestId);
@@ -38348,6 +38606,13 @@ async function cliBootstrapRoutes(app, deps) {
   );
   app.get(
     "/cli/bootstrap-confirm",
+    routeMeta({
+      surface: "bootstrap",
+      operationId: "bootstrap.confirm",
+      authPolicy: "public",
+      stability: "internal",
+      summary: "Redeem the CLI connection link from the email"
+    }),
     async (req, reply) => {
       const token = (req.query.token ?? "").trim();
       reply.type("text/html");
@@ -38398,6 +38663,13 @@ async function cliBootstrapRoutes(app, deps) {
   );
   app.get(
     "/cli/bootstrap-poll",
+    routeMeta({
+      surface: "bootstrap",
+      operationId: "bootstrap.poll",
+      authPolicy: "public",
+      stability: "preview",
+      summary: "A CLI polls whether its connection was confirmed"
+    }),
     async (req, reply) => {
       const requestId = (req.query.request ?? "").trim();
       if (!requestId) return reply.status(400).send({ error: "missing_request" });
@@ -38437,13 +38709,20 @@ import { nanoid as nanoid42 } from "nanoid";
 init_auth();
 init_settings();
 init_users();
+init_route_registry();
 var CHALLENGE_TTL_MS = 10 * 6e4;
 var MIN_FILL_MS = 2e3;
 async function registrationRoutes(app, deps) {
   const { db, config, mailer } = deps;
   const submitByIp = createAbuseThrottle({ windowMs: 60 * 6e4, max: 10 });
   const challengeByIp = createAbuseThrottle({ windowMs: 60 * 6e4, max: 60 });
-  app.get("/auth/register-challenge", async (req, reply) => {
+  app.get("/auth/register-challenge", routeMeta({
+    surface: "bootstrap",
+    operationId: "auth.registerChallenge",
+    authPolicy: "public",
+    stability: "preview",
+    summary: "The challenge a registration form answers"
+  }), async (req, reply) => {
     if (!challengeByIp.take(`ip:${req.ip}`)) {
       return reply.status(429).send({ error: "too_many_requests" });
     }
@@ -38457,21 +38736,24 @@ async function registrationRoutes(app, deps) {
   });
   app.post(
     "/auth/register",
-    {
-      schema: {
-        body: {
-          type: "object",
-          required: ["email", "challengeId"],
-          properties: {
-            email: { type: "string", minLength: 3, maxLength: 254 },
-            name: { type: "string", maxLength: 200 },
-            note: { type: "string", maxLength: 1e3 },
-            challengeId: { type: "string", minLength: 1, maxLength: 64 },
-            website: { type: "string", maxLength: 200 }
-          }
+    routeMeta({
+      surface: "bootstrap",
+      operationId: "auth.register",
+      authPolicy: "public",
+      stability: "preview",
+      summary: "Ask for an account",
+      requestSchema: {
+        type: "object",
+        required: ["email", "challengeId"],
+        properties: {
+          email: { type: "string", minLength: 3, maxLength: 254 },
+          name: { type: "string", maxLength: 200 },
+          note: { type: "string", maxLength: 1e3 },
+          challengeId: { type: "string", minLength: 1, maxLength: 64 },
+          website: { type: "string", maxLength: 200 }
         }
       }
-    },
+    }),
     async (req, reply) => {
       const email = (req.body.email ?? "").trim().toLowerCase();
       const name = (req.body.name ?? "").trim() || null;
@@ -38519,7 +38801,13 @@ async function registrationRoutes(app, deps) {
       return reply.status(202).send({ status: "pending" });
     }
   );
-  app.get("/auth/register-approve", async (req, reply) => {
+  app.get("/auth/register-approve", routeMeta({
+    surface: "bootstrap",
+    operationId: "auth.registerApprove",
+    authPolicy: "public",
+    stability: "internal",
+    summary: "Approve a registration request from its link"
+  }), async (req, reply) => {
     const token = (req.query.token ?? "").trim();
     const row = token ? await db.get(`SELECT id, email, name, note, status, approve_token as approveToken,
                     reject_token as rejectToken, created_at as createdAt,
@@ -38539,7 +38827,13 @@ async function registrationRoutes(app, deps) {
       )
     );
   });
-  app.get("/auth/register-reject", async (req, reply) => {
+  app.get("/auth/register-reject", routeMeta({
+    surface: "bootstrap",
+    operationId: "auth.registerReject",
+    authPolicy: "public",
+    stability: "internal",
+    summary: "Reject a registration request from its link"
+  }), async (req, reply) => {
     const token = (req.query.token ?? "").trim();
     const row = token ? await db.get(`SELECT id, email, name, status FROM registration_requests WHERE reject_token = ?`, token) : void 0;
     if (!row) {
@@ -38741,6 +39035,7 @@ function safeNext(next) {
 }
 
 // src/routes/install.ts
+init_route_registry();
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { dirname as dirname3, resolve as resolve2 } from "node:path";
 import { existsSync as existsSync6 } from "node:fs";
@@ -38751,7 +39046,14 @@ var SCRIPT_PATH = [
   resolve2(MODULE_DIR2, "../../../deploy/install-sandbox.sh")
 ].find((p) => existsSync6(p)) ?? resolve2(MODULE_DIR2, "../../../deploy/install-sandbox.sh");
 async function installRoutes(app) {
-  app.get("/install-sandbox.sh", async (_req, reply) => {
+  app.get("/install-sandbox.sh", routeMeta({
+    surface: "static",
+    operationId: "ops.installSandboxScript",
+    authPolicy: "public",
+    // A shell script, not a JSON operation.
+    stability: "internal",
+    summary: "The SANDBOX install script"
+  }), async (_req, reply) => {
     try {
       const body = await readFile(SCRIPT_PATH, "utf8");
       return reply.type("text/x-shellscript; charset=utf-8").send(body);
@@ -39522,10 +39824,18 @@ async function negotiateJobCredentials(db, spec, workerId, log, issuer) {
 // src/routes/jobs.ts
 init_sandbox2();
 init_ws();
+init_route_registry();
 async function jobsRoutes(app, deps) {
   const { db, config } = deps;
   const notifyDeps = deps.notify;
-  app.post("/jobs/claim", async (req, reply) => {
+  app.post("/node/v1/jobs/claim", routeMeta({
+    surface: "node",
+    operationId: "node.jobs.claim",
+    authPolicy: "node_actor",
+    resourcePolicy: "node.connect",
+    stability: "preview",
+    summary: "Claim the next job for this SANDBOX (long poll)"
+  }), async (req, reply) => {
     const sandbox = await authenticateSandboxByBearer(db, req.headers.authorization);
     if (!sandbox) {
       return reply.status(401).send({ error: "unauthorized" });
@@ -39579,8 +39889,16 @@ async function jobsRoutes(app, deps) {
     }
   });
   app.post(
-    "/jobs/heartbeat",
+    "/node/v1/jobs/heartbeat",
     {
+      ...routeMeta({
+        surface: "node",
+        operationId: "node.jobs.heartbeat",
+        authPolicy: "node_actor",
+        resourcePolicy: "node.connect",
+        stability: "preview",
+        summary: "Keep a claimed job's lease alive"
+      }),
       schema: {
         body: {
           type: "object",
@@ -39642,8 +39960,16 @@ async function jobsRoutes(app, deps) {
     }
   );
   app.post(
-    "/jobs/release",
+    "/node/v1/jobs/release",
     {
+      ...routeMeta({
+        surface: "node",
+        operationId: "node.jobs.release",
+        authPolicy: "node_actor",
+        resourcePolicy: "node.connect",
+        stability: "preview",
+        summary: "Hand a claimed job back to the queue"
+      }),
       schema: {
         body: {
           type: "object",
@@ -39679,8 +40005,16 @@ async function jobsRoutes(app, deps) {
     }
   );
   app.post(
-    "/jobs/result",
+    "/node/v1/jobs/result",
     {
+      ...routeMeta({
+        surface: "node",
+        operationId: "node.jobs.result",
+        authPolicy: "node_actor",
+        resourcePolicy: "node.connect",
+        stability: "preview",
+        summary: "Report a finished job"
+      }),
       schema: {
         body: {
           type: "object",
@@ -41454,9 +41788,11 @@ async function buildServer(config, db) {
       }
     });
   }
-  const routeRegistry = installRouteGuard(app, "observe", {
-    warn: (message) => app.log.warn(message)
-  });
+  const routeRegistry = installRouteGuard(app, "enforce", { warn: (message) => app.log.warn(message) }, [
+    ...LEGACY_ROUTES,
+    ...STATIC_PLUGIN_ROUTES
+  ]);
+  app.decorate("routeRegistry", routeRegistry);
   const mailer = buildMailer(loadMailerConfig(), app.log);
   app.log.info({ mailer: mailer.mode }, "mailer mode");
   const notifyDeps = {
@@ -41678,10 +42014,9 @@ async function buildServer(config, db) {
     app.log.info(
       {
         classified: routeRegistry.list().length,
-        unclassified: routeRegistry.unclassifiedCount(),
-        invalid: routeRegistry.invalidCount()
+        legacy: routeRegistry.unclassifiedRoutes().filter((r) => !STATIC_PLUGIN_ROUTES.includes(r)).length
       },
-      "route registry: routes still to declare their metadata"
+      "route registry: legacy routes still served for the browser"
     );
   });
   await registerSpaHosts(app, {