@catheadowl/ukp 0.2.6 → 0.3.0

package/src/server.ts

@@ -1,5 +1,6 @@
 import { dirname, join } from "node:path";
 import { readFileSync, writeFileSync, fstatSync, constants as fsConstants } from "node:fs";
+import { createHash, timingSafeEqual } from "node:crypto";
 import { createServer as netCreateServer, connect as netConnect, type Server as NetServer } from "node:net";
 import { ENDPOINT_NAME, loadManifest, type LoadedManifest } from "./config/manifest.ts";
 import { localPathOf, readRegistry } from "./registry.ts";
@@ -12,7 +13,8 @@ import {
   proposeEnvelope,
   proposeUpsert,
 } from "./capabilities/propose.ts";
-import { certSanOf, ensureSelfSignedTlsFiles, spkiPinOf } from "./capabilities/tls-identity.ts";
+import { certSanOf, ensureSelfSignedTlsFiles, migrateLegacyServiceTlsDir, spkiPinOf } from "./capabilities/tls-identity.ts";
+import { retireTlsIgnoreLine } from "./commands/init.ts";
 import {
   buildInlineReferences,
   projectSearchEnvelope,
@@ -40,6 +42,14 @@ import {
   type ParsedRg,
 } from "./capabilities/rg.ts";
 import { KitUsageError } from "./commands/kit.ts";
+import {
+  authenticateBearerKey,
+  loadTokenFile,
+  parseTokenFileText,
+  scopeAllows,
+  type ScopeAccess,
+  type TokenFileEntry,
+} from "./plumbing/token-file.ts";
 
 /** ukp-remote wire v1 server core (ADR-REM-001/002/003, ukp_remote W1/W7):
  * two serving shapes over one wire. Single-endpoint mode exposes ONE
@@ -57,7 +67,12 @@ import { KitUsageError } from "./commands/kit.ts";
  * modes, so client-side TOFU and name-assertion paths are shared. The
  * capability layer runs unchanged behind the routes (provider/transport
  * axes stay orthogonal): search via `runSearch` with a single-endpoint
- * scope, read via `runRead`, nav via `runNav`, rg via `runRg`. There is no
+ * scope, read via `runRead`, nav via `runNav`, rg via `runRg`. The bearer
+ * gate has two sources (W13 / RQ-16c): env tokens — the full-power
+ * shortcut, original RQ-16 semantics — or the labeled token file, read
+ * fresh per request so deleting a line revokes without a restart; a file
+ * key's scopes narrow the door's rosters exactly like `--select` does
+ * (ADR-REM-010 mechanism reuse, no 403 class). There is no
  * session, no streaming, and no server-side artifact: responses inline the
  * reference data (RQ-07) and generate a serve-scoped run id. */
 
@@ -96,9 +111,24 @@ export interface ServeConfig {
    * readable without it). In door mode the same gate covers all
    * `/e/<name>/v1/*` routes (door-level auth, O-2). */
   tokens?: readonly string[];
+  /** W13 / RQ-16c: the labeled token file (`~/.ukp/tokens`). When `tokens`
+   * is absent, the gate arms from this file instead: it is read FRESH on
+   * every request (revocation = deleting the line, no restart), a presented
+   * `ukp_<label>_<id>_<secret>` key is verified against the row's SHA-256,
+   * and the matched row's scopes decide which endpoints the key may touch
+   * (`name:ro|rw`, Docker-registry grammar, required per row). When
+   * `tokens` IS set, env wins outright and the file is not consulted —
+   * env is the full-power shortcut form of the same gate (AWS/gh/kubectl
+   * chain order). Scope enforcement reuses the ADR-REM-010 roster
+   * mechanism: an out-of-scope name shares the roster 404 with an unknown
+   * one, byte-identical, and the roster a scoped 404 carries is the key's
+   * own effective set — no new 403 class exists. */
+  tokenFilePath?: string;
   /** TLS transport (W5' / D-079): `self-signed` generates and persists an
-   * identity under the Service folder (`.ukp/tls/`) — in door mode under the
-   * registry's directory, since a door has no single Service folder;
+   * identity in the machine home beside the registry — `~/.ukp/tls/<name>/`
+   * in endpoint mode, the flat `~/.ukp/tls/` in door mode (a door has no
+   * single Service folder; endpoint mode converged on the same home
+   * 2026-11-01 because the identity is machine-scoped material);
    * `certificates` serves operator-provided PEM files (Let's Encrypt IP
    * certs, mkcert, private CA). `sanEntries` (the `--tls-san` flag, already
    * normalized `IP:x`/`DNS:y`) merges extra coverage into the self-signed
@@ -168,6 +198,11 @@ export interface ServeInfo {
   host: string;
   port: number;
   authRequired: boolean;
+  /** Present when the gate armed from the token file instead of env
+   * (W13 / RQ-16c) — feeds the banner's operator line. `keys` is a startup
+   * snapshot for visibility only; the live truth is the per-request fresh
+   * read (delete a line, next request 401s). */
+  tokenFile?: { keys: number };
   /** ripgrep availability probed once at startup IN THE DOOR'S OWN PROCESS
    * (2026-09-20, liku feedback): /v1/rg serves every endpoint and a missing
    * binary degrades per-endpoint on the wire by design — but that truth is
@@ -299,11 +334,18 @@ export function buildDiscoveryDocument(
  * the door's width admits — every one of them, or the `select` whitelist's
  * members (ADR-REM-010) — read fresh by the caller per request (new
  * endpoints appear without a restart). Remote bindings are not servable and
- * never make the roster. */
-function listDoorEndpoints(registryPath: string, select?: readonly string[]): Array<{ name: string; folder: string }> {
+ * never make the roster. W13 adds the per-key narrowing axis: `admit` is
+ * the matched file key's scope predicate for the route's access level, so
+ * the roster a scoped caller can ever see is scope ∩ select ∩ registry. */
+function listDoorEndpoints(
+  registryPath: string,
+  select?: readonly string[],
+  admit?: (name: string) => boolean,
+): Array<{ name: string; folder: string }> {
   return readRegistry(registryPath)
     .filter((binding) => binding.kind !== "remote")
     .filter((binding) => select === undefined || select.includes(binding.name))
+    .filter((binding) => admit === undefined || admit(binding.name))
     .map((binding) => ({ name: binding.name, folder: binding.path! }));
 }
 
@@ -713,8 +755,10 @@ function startServeListener(
 
 /** TLS material resolution (W5' / D-079), shared by both serve modes: a
  * self-signed identity is generated/re-signed/persisted under `identityDir`
- * (the Service folder's `.ukp/tls/` in endpoint mode, the registry directory
- * in door mode — a door has no single Service folder), explicit certificates
+ * (the machine home beside the registry: `~/.ukp/tls/<name>/` in endpoint
+ * mode, the home's flat root in door mode — a door has no single Service
+ * folder, and endpoint mode converged on the same home 2026-11-01 because
+ * the identity is machine-scoped material), explicit certificates
  * are read from the operator's paths. Bun.serve takes PEM contents
  * (path-string handling is platform-dependent). Every failure — unreadable
  * operator files, an unusable persisted identity, openssl unable to sign —
@@ -759,19 +803,95 @@ function resolveTlsMaterial(
   }
 }
 
+/** CHK-01 ruling (D-100 / ADR 0027): the bearer check hashes both sides
+ * with SHA-256 and compares the fixed 32-byte digests via
+ * `crypto.timingSafeEqual`. Hashing first makes the comparison
+ * length-uniform — operator-chosen tokens (`UKP_SERVE_TOKEN`, arbitrary
+ * length — not fixed-length hex) and attacker-chosen header values can
+ * never reach the raw API's equal-length requirement, and no early exit
+ * (length mismatch, first differing byte) shapes the failure timing.
+ * Every failure class — missing header, non-Bearer scheme, wrong value —
+ * runs this one path and then the single 401 below, so responses stay
+ * byte-identical across classes (CHK-02, CWE-204 family: the gate is
+ * not a credential oracle). */
+export function timingSafeBearerMatch(
+  authorization: string | null,
+  tokens: readonly string[],
+): boolean {
+  const presented = createHash("sha256").update(authorization ?? "").digest();
+  return tokens.some((token) =>
+    timingSafeEqual(createHash("sha256").update(`Bearer ${token}`).digest(), presented)
+  );
+}
+
+/** What the gate established about the caller (W13 / RQ-16c): an env token
+ * is the full-power shortcut form (its scope is the whole door, original
+ * RQ-16 semantics); a file key carries its row's scopes into authorization.
+ * `undefined` = no gate armed (loopback anonymous serving) — not a failure.
+ * The two never mix: env present means the file is not consulted at all. */
+type GateCredential =
+  | { kind: "env" }
+  | { kind: "file"; entry: TokenFileEntry };
+
+/** The single 401 every gate failure class emits (CHK-02 / CWE-204 family:
+ * the gate is not a credential oracle) — missing header, wrong scheme,
+ * unknown key, wrong secret, out-of-scope key on a single-endpoint gate. */
+function authFailureResponse(): Response {
+  return jsonResponse(
+    errorBody("auth-failure", "missing or invalid bearer token (Authorization: Bearer <token>)"),
+    401,
+  );
+}
+
+/** W13 / RQ-16c: whether ANY auth source is configured — env tokens or the
+ * token file. Drives `authRequired` (banner, discovery security.schemes)
+ * and the gate itself; with neither, serving is anonymous (the command
+ * layer's deny-by-default admission, RQ-18, is what prevents reaching here
+ * unarmed on non-loopback binds). */
+function gateArmed(config: ServeConfig): boolean {
+  return (config.tokens?.length ?? 0) > 0 || config.tokenFilePath !== undefined;
+}
+
+/** The door gate, both sources (W13): env tokens compare through the
+ * CHK-01 digest path unchanged; a token file is fresh-read per request
+ * (missing/unreadable/unparseable file ⇒ no key can pass — fail closed)
+ * and the presented key is verified against exactly its (label, keyId) row
+ * with a timing-safe digest compare inside the plumbing module. */
 function bearerGate(
   request: Request,
-  tokens: readonly string[] | undefined,
-): Response | undefined {
-  if ((tokens?.length ?? 0) === 0) return undefined;
-  const authorization = request.headers.get("authorization");
-  if (!tokens!.some((token) => authorization === `Bearer ${token}`)) {
-    return jsonResponse(
-      errorBody("auth-failure", "missing or invalid bearer token (Authorization: Bearer <token>)"),
-      401,
-    );
+  config: ServeConfig,
+): { credential: GateCredential | undefined } | { response: Response } {
+  if (!gateArmed(config)) return { credential: undefined };
+  if ((config.tokens?.length ?? 0) > 0) {
+    return timingSafeBearerMatch(request.headers.get("authorization"), config.tokens!)
+      ? { credential: { kind: "env" } }
+      : { response: authFailureResponse() };
   }
-  return undefined;
+  const loaded = loadTokenFile(config.tokenFilePath!);
+  if (!("text" in loaded)) return { response: authFailureResponse() };
+  const parsed = parseTokenFileText(loaded.text);
+  if ("error" in parsed) return { response: authFailureResponse() };
+  const authorization = request.headers.get("authorization");
+  // Scheme shape is part of the uniform failure path: a non-Bearer header
+  // fails exactly like a missing one (single 401, no early distinctions).
+  const match = /^Bearer (.+)$/.exec(authorization ?? "");
+  if (match === null) return { response: authFailureResponse() };
+  const entry = authenticateBearerKey(match[1]!, parsed.entries);
+  return entry !== undefined ? { credential: { kind: "file", entry } } : { response: authFailureResponse() };
+}
+
+/** Per-request roster admission from the matched key's scopes (rehearsal
+ * point E): read routes demand `ro`, the propose route demands `rw`. A
+ * `ro`-scoped endpoint is therefore absent from the write face's effective
+ * set the same way an unselected name is absent from a subset door — same
+ * roster-404 shape, no new refusal class. Env credentials and anonymous
+ * serving return undefined (the door's own width applies). */
+function scopeAdmit(
+  credential: GateCredential | undefined,
+  access: ScopeAccess,
+): ((name: string) => boolean) | undefined {
+  if (credential?.kind !== "file") return undefined;
+  return (name: string) => scopeAllows(credential.entry.scopes, name, access);
 }
 
 /** Per-request endpoint resolution for door routing (O-2): the registry is
@@ -781,11 +901,15 @@ function bearerGate(
  * single-mode discovery fetch does. A subset door (ADR-REM-010) routes an
  * excluded name into the SAME roster-404 branch as an unknown one — the
  * response is byte-identical either way, so the roster is the only name
- * list any response ever carries. */
+ * list any response ever carries. W13 scopes ride the same branch: an
+ * out-of-scope name for the matched key is indistinguishable from an
+ * unknown one, and the roster it sees is the key's own effective set
+ * (`admit` = scope ∩ select ∩ registry), never the wider door. */
 function resolveDoorRoute(
   registryPath: string,
   name: string,
   select?: readonly string[],
+  admit?: (name: string) => boolean,
 ): { folder: string } | { response: Response } {
   let binding;
   try {
@@ -794,8 +918,13 @@ function resolveDoorRoute(
     const reason = error instanceof Error ? error.message : String(error);
     return { response: jsonResponse(errorBody("provider-unavailable", `Host Registry is not readable: ${reason}`), 503) };
   }
-  if (binding === undefined || binding.kind === "remote" || (select !== undefined && !select.includes(name))) {
-    const roster = listDoorEndpoints(registryPath, select).map((endpoint) => endpoint.name).join(", ");
+  if (
+    binding === undefined
+    || binding.kind === "remote"
+    || (select !== undefined && !select.includes(name))
+    || (admit !== undefined && !admit(name))
+  ) {
+    const roster = listDoorEndpoints(registryPath, select, admit).map((endpoint) => endpoint.name).join(", ");
     return {
       response: jsonResponse(
         errorBody("not-found", `no such endpoint '${name}' on this host door (available: ${roster})`),
@@ -835,10 +964,16 @@ function resolveDoorRoute(
  * divide); every `/e/<name>/v1/*` route passes the door-level bearer gate.
  * The roster a 404 carries is the door's effective set — on a subset door
  * (ADR-REM-010) that is the select ∩ registry intersection, never the full
- * registry. */
-function doorNotFound(name: string | undefined, registryPath: string, select?: readonly string[]): Response {
+ * registry; on an authenticated scoped route (W13) it further intersects
+ * with the matched key's scopes via `admit`. */
+function doorNotFound(
+  name: string | undefined,
+  registryPath: string,
+  select?: readonly string[],
+  admit?: (name: string) => boolean,
+): Response {
   if (name !== undefined) {
-    const roster = listDoorEndpoints(registryPath, select).map((endpoint) => endpoint.name).join(", ");
+    const roster = listDoorEndpoints(registryPath, select, admit).map((endpoint) => endpoint.name).join(", ");
     return jsonResponse(
       errorBody("not-found", `no such endpoint '${name}' on this host door (available: ${roster})`),
       404,
@@ -867,7 +1002,9 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
         return jsonResponse(errorBody("method-not-allowed", `the discovery document is a GET resource`), 405);
       }
       try {
-        return jsonResponse(buildDoorDocument(listDoorEndpoints(config.registryPath, select), (config.tokens?.length ?? 0) > 0));
+        // Public door document (ADR-REM-003): no key presented, no scope
+        // narrowing — the door's own width is what the roster declares.
+        return jsonResponse(buildDoorDocument(listDoorEndpoints(config.registryPath, select), gateArmed(config)));
       } catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
         return jsonResponse(errorBody("provider-unavailable", `Host Registry is not readable: ${reason}`), 503);
@@ -892,7 +1029,7 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
         try {
           const loaded = loadManifest(resolved.folder);
           return jsonResponse(
-            buildDiscoveryDocument(loaded, readInstanceUid(resolved.folder), (config.tokens?.length ?? 0) > 0),
+            buildDiscoveryDocument(loaded, readInstanceUid(resolved.folder), gateArmed(config)),
           );
         } catch (error) {
           const reason = error instanceof Error ? error.message : String(error);
@@ -900,18 +1037,22 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
         }
       }
       if (rest.startsWith("/v1/propose/")) {
-        const denied = bearerGate(request, config.tokens);
-        if (denied !== undefined) return denied;
+        const gate = bearerGate(request, config);
+        if ("response" in gate) return gate.response;
+        // The write face demands the rw bit: a ro-scoped endpoint is not in
+        // this key's effective write roster (rehearsal point E).
+        const admit = scopeAdmit(gate.credential, "rw");
         const id = rest.slice("/v1/propose/".length);
-        if (id.includes("/")) return doorNotFound(undefined, config.registryPath, select);
-        const resolved = resolveDoorRoute(config.registryPath, name, select);
+        if (id.includes("/")) return doorNotFound(undefined, config.registryPath, select, admit);
+        const resolved = resolveDoorRoute(config.registryPath, name, select, admit);
         if ("response" in resolved) return resolved.response;
         return await handlePropose(request, config, name, resolved.folder, id);
       }
       if (rest === "/v1/search" || rest === "/v1/read" || rest === "/v1/nav" || rest === "/v1/rg") {
-        const denied = bearerGate(request, config.tokens);
-        if (denied !== undefined) return denied;
-        const resolved = resolveDoorRoute(config.registryPath, name, select);
+        const gate = bearerGate(request, config);
+        if ("response" in gate) return gate.response;
+        const admit = scopeAdmit(gate.credential, "ro");
+        const resolved = resolveDoorRoute(config.registryPath, name, select, admit);
         if ("response" in resolved) return resolved.response;
         if (rest === "/v1/search") {
           return await handleSearch(request, config, name, resolved.folder);
@@ -920,7 +1061,7 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
           return handleRead(url, request, config, name);
         }
         if (rest === "/v1/nav") {
-          return handleNav(url, request, config, name);
+          return await handleNav(url, request, config, name);
         }
         return handleRg(url, request, config, name);
       }
@@ -938,6 +1079,7 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
     ...(config.systemdSocket === true ? { systemdSocket: true } : {}),
   });
   const { server } = listener;
+  const tokenFile = tokenFileSnapshot(config);
 
   const info: ServeInfo = {
     mode: "door",
@@ -949,7 +1091,8 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
     url: listener.publicUrl,
     host,
     port: listener.port,
-    authRequired: (config.tokens?.length ?? 0) > 0,
+    authRequired: gateArmed(config),
+    ...(tokenFile !== undefined ? { tokenFile } : {}),
     rg: rgExecutableAvailable() ? "ok" : "missing",
     ...(tlsMaterial !== undefined
       ? { tls: { pin: tlsMaterial.pin, san: tlsMaterial.san, source: tlsMaterial.source } }
@@ -959,6 +1102,19 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
   return { server, info, stopAll: listener.stopAll };
 }
 
+/** Startup snapshot of the token file for the banner's operator line
+ * (W13): the live gate re-reads per request; this count is visibility, not
+ * truth. A parse failure here is cosmetic-zero — the command layer's
+ * admission already refused a malformed file, and the gate itself fails
+ * closed on any read/parse problem. */
+function tokenFileSnapshot(config: ServeConfig): { keys: number } | undefined {
+  if (config.tokenFilePath === undefined || (config.tokens?.length ?? 0) > 0) return undefined;
+  const loaded = loadTokenFile(config.tokenFilePath);
+  if (!("text" in loaded)) return { keys: 0 };
+  const parsed = parseTokenFileText(loaded.text);
+  return "error" in parsed ? { keys: 0 } : { keys: parsed.entries.length };
+}
+
 export function startUkpServer(config: ServeConfig): StartedServe {
   const host = config.host ?? "127.0.0.1";
 
@@ -988,7 +1144,21 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     );
   }
 
-  const tlsMaterial = resolveTlsMaterial(config, join(serviceFolder, ".ukp", "tls"));
+  // The self-signed identity is machine-scoped material (its SAN coverage
+  // names THIS host's interfaces) and lives in the machine home beside the
+  // registry — `~/.ukp/tls/<endpoint>/` here, the same home's flat root in
+  // door mode (adjudication 2026-11-01, inbox service-dir-layering item 2;
+  // endpoint mode converged on the home door mode already used). Keyed by
+  // the manifest's effective name: the registry namespace holds one
+  // endpoint per name, so a re-cloned folder re-attaches to its pinned
+  // identity instead of orphaning every client (INV-04). A pre-2026-11-01
+  // `.ukp/tls/` moves in once, keypair untouched; the retired `/tls/`
+  // ignore rule swaps out in the same gesture.
+  const identityDir = join(dirname(config.registryPath), "tls", startupManifest.effectiveName);
+  if (migrateLegacyServiceTlsDir(serviceFolder, identityDir) === "moved") {
+    retireTlsIgnoreLine(join(serviceFolder, ".ukp"));
+  }
+  const tlsMaterial = resolveTlsMaterial(config, identityDir);
 
   const handler = async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
@@ -1011,7 +1181,7 @@ export function startUkpServer(config: ServeConfig): StartedServe {
           );
         }
         return jsonResponse(
-          buildDiscoveryDocument(loaded, readInstanceUid(serviceFolder), (config.tokens?.length ?? 0) > 0),
+          buildDiscoveryDocument(loaded, readInstanceUid(serviceFolder), gateArmed(config)),
         );
       } catch (error) {
         return jsonResponse(
@@ -1022,8 +1192,15 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     }
 
     if (url.pathname.startsWith("/v1/propose/")) {
-      const denied = bearerGate(request, config.tokens);
-      if (denied !== undefined) return denied;
+      const gate = bearerGate(request, config);
+      if ("response" in gate) return gate.response;
+      // Single-endpoint gates have no roster to hide behind: a key that
+      // does not carry this endpoint at rw is simply not valid for this
+      // gate's write face — the same uniform 401, no new refusal class.
+      if (gate.credential?.kind === "file"
+        && !scopeAllows(gate.credential.entry.scopes, binding.name, "rw")) {
+        return authFailureResponse();
+      }
       const id = url.pathname.slice("/v1/propose/".length);
       if (id.includes("/")) {
         return jsonResponse(
@@ -1043,8 +1220,12 @@ export function startUkpServer(config: ServeConfig): StartedServe {
       || url.pathname === "/v1/nav"
       || url.pathname === "/v1/rg"
     ) {
-      const denied = bearerGate(request, config.tokens);
-      if (denied !== undefined) return denied;
+      const gate = bearerGate(request, config);
+      if ("response" in gate) return gate.response;
+      if (gate.credential?.kind === "file"
+        && !scopeAllows(gate.credential.entry.scopes, binding.name, "ro")) {
+        return authFailureResponse();
+      }
       if (url.pathname === "/v1/search") {
         return await handleSearch(request, config, binding.name, serviceFolder);
       }
@@ -1052,7 +1233,7 @@ export function startUkpServer(config: ServeConfig): StartedServe {
         return handleRead(url, request, config, binding.name);
       }
       if (url.pathname === "/v1/nav") {
-        return handleNav(url, request, config, binding.name);
+        return await handleNav(url, request, config, binding.name);
       }
       return handleRg(url, request, config, binding.name);
     }
@@ -1074,6 +1255,7 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     ...(config.systemdSocket === true ? { systemdSocket: true } : {}),
   });
   const { server } = listener;
+  const tokenFile = tokenFileSnapshot(config);
 
   const info: ServeInfo = {
     mode: "endpoint",
@@ -1083,7 +1265,8 @@ export function startUkpServer(config: ServeConfig): StartedServe {
     url: listener.publicUrl,
     host,
     port: listener.port,
-    authRequired: (config.tokens?.length ?? 0) > 0,
+    authRequired: gateArmed(config),
+    ...(tokenFile !== undefined ? { tokenFile } : {}),
     rg: rgExecutableAvailable() ? "ok" : "missing",
     ...(tlsMaterial !== undefined
       ? { tls: { pin: tlsMaterial.pin, san: tlsMaterial.san, source: tlsMaterial.source } }
@@ -1182,7 +1365,7 @@ function handleRead(url: URL, request: Request, config: ServeConfig, endpointNam
 /** GET /v1/nav?path=&depth= → the nav envelope IS the response (W6): the
  * client renders it through the same renderNavHuman/renderNavJson path as a
  * local run. Failures use the transport error shape with nav's classes. */
-function handleNav(url: URL, request: Request, config: ServeConfig, endpointName: string): Response {
+async function handleNav(url: URL, request: Request, config: ServeConfig, endpointName: string): Promise<Response> {
   if (request.method !== "GET") {
     return jsonResponse(errorBody("method-not-allowed", "/v1/nav is a GET route"), 405);
   }
@@ -1190,7 +1373,7 @@ function handleNav(url: URL, request: Request, config: ServeConfig, endpointName
   if ("error" in parsed) {
     return jsonResponse(errorBody("usage-error", parsed.error), 400);
   }
-  const outcome = runNav(parsed.request, {
+  const outcome = await runNav(parsed.request, {
     currentDirectory: config.currentDirectory,
     registryPath: config.registryPath,
   });

package/src/spawn-relay.ts

@@ -36,12 +36,30 @@ function psSingleQuoted(arg: string): string {
 
 /** The relay script. `notFoundGuard` adds a Get-Command pre-check that exits
  * TOOL_NOT_FOUND_EXIT when argv[0] does not resolve — for callers that must
- * distinguish a missing tool from a tool's own failure exit. */
+ * distinguish a missing tool from a tool's own failure exit.
+ *
+ * The leading $ProgressPreference suppression is load-bearing for the stderr
+ * contract (2026-10-09 finding, TODO rg-clixml-pattern-failure-windows): the
+ * guard's Get-Command is the script's first cmdlet, which makes the engine
+ * emit its one-time "Preparing modules for first use" progress record, and
+ * with a redirected stderr powershell.exe serializes that record as a
+ * `#< CLIXML` stream ahead of the tool's own stderr — the consumer then
+ * surfaces `status: failed: #< CLIXML` instead of the real tool error.
+ * Suppressing progress keeps the channel tool-stderr-only; native stderr
+ * itself passes through byte-clean, exit code included (verified live:
+ * rg's regex parse error arrives readable; UTF-8 match text unaffected). */
 export function toolRelayScript(argv: readonly string[], options: { notFoundGuard?: boolean } = {}): string {
+  // The guard resolves via -Name, never -LiteralName: PS 5.1's Get-Command
+  // has no -LiteralName parameter, and an unknown parameter on it is not a
+  // binding error — the argument is silently swallowed and the call returns
+  // EVERY command, so a -LiteralName guard is vacuous (a missing tool then
+  // falls through to `&` and its CommandNotFoundException exits 0 with a
+  // CLIXML leak; live-verified 2026-10-09 review). -Name globs, but tool
+  // names ("rg", "ssh") contain no glob characters.
   const guard = options.notFoundGuard === true
-    ? " if (-not (Get-Command -LiteralName $a[0] -ErrorAction SilentlyContinue)) { exit 127 };"
+    ? " if (-not (Get-Command -Name $a[0] -ErrorAction SilentlyContinue)) { exit 127 };"
     : "";
-  return `$a = @(${argv.map(psSingleQuoted).join(",")});${guard} & $a[0] $a[1..($a.Count-1)]; exit $LASTEXITCODE`;
+  return `$ProgressPreference = 'SilentlyContinue'; $a = @(${argv.map(psSingleQuoted).join(",")});${guard} & $a[0] $a[1..($a.Count-1)]; exit $LASTEXITCODE`;
 }
 
 /** The powershell carrier argv for a tool invocation: spawn THIS instead of