@catheadowl/ukp 0.2.3 → 0.2.5

package/src/commands/serve-task.ts

@@ -48,15 +48,15 @@ export function printTaskPreflightError(input: {
   allowAnonymous: boolean;
 }): string | undefined {
   if (input.platform !== "win32") {
-    return "--print-task is Windows-only; on Linux prefer systemd socket activation (ukp serve --systemd-socket) — the deployment handbook carries that recipe";
+    return "--print-task is Windows-only; on Linux prefer systemd socket activation (ukp serve --systemd-socket) - the deployment handbook carries that recipe";
   }
   const loopback =
     input.host === "127.0.0.1" || input.host === "localhost" || input.host === "::1" || input.host === "[::1]";
   if (!loopback && !input.hasTls) {
-    return "refusing to print an off-loopback door without TLS: clients refuse to register plain-http urls — pass --tls (self-signed, pinned at registration) or --tls-cert/--tls-key, or bind loopback behind a TLS-terminating proxy";
+    return "refusing to print an off-loopback door without TLS: clients refuse to register plain-http urls - pass --tls (self-signed, pinned at registration) or --tls-cert/--tls-key, or bind loopback behind a TLS-terminating proxy";
   }
   if (input.allowAnonymous && !loopback) {
-    return "refusing to print this shape: --allow-anonymous is loopback-only and serve would refuse it at task start — set the token in the generated script instead";
+    return "refusing to print this shape: --allow-anonymous is loopback-only and serve would refuse it at task start - set the token in the generated script instead";
   }
   return undefined;
 }
@@ -86,10 +86,10 @@ function parentDirOf(path: string): string | undefined {
 export function renderServeTaskArtifacts(input: ServeTaskInput): string {
   const serveLine = serveCommandLine(input);
   const out: string[] = [
-    "ukp serve --print-task — Windows resident-door artifacts",
+    "ukp serve --print-task - Windows resident-door artifacts",
     "",
     "Print-only: review these, then apply them yourself. UKP installs nothing,",
-    "starts nothing, and supervises nothing — the door's lifecycle belongs to",
+    "starts nothing, and supervises nothing - the door's lifecycle belongs to",
     "you and your process manager.",
     "",
   ];
@@ -97,7 +97,7 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
   if (input.tls?.mode === "certificates") {
     const certDir = parentDirOf(input.tls.certPath);
     out.push(
-      "0) Certificate — generate ONCE (Git for Windows' openssl works; this",
+      "0) Certificate - generate ONCE (Git for Windows' openssl works; this",
       "   avoids any runtime openssl dependency of --tls):",
       "",
       "   openssl req -x509 -newkey rsa:2048 -nodes -days 825 -keyout",
@@ -115,7 +115,7 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
   }
 
   out.push(
-    "1) Start script — save as %USERPROFILE%\\.ukp\\start-door.cmd",
+    "1) Start script - save as %USERPROFILE%\\.ukp\\start-door.cmd",
     "   (write it with a real editor and CRLF line endings; writing cmd",
     "   files over ssh echo mangles % escaping)",
     "",
@@ -125,13 +125,13 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
     "   rem (e.g. openssl rand -hex 32), paste it in, keep this file private.",
     "   set \"UKP_SERVE_TOKEN=<paste-your-token>\"",
     "   rem ukp resolves through the logged-on task's per-user PATH; the",
-    "   rem launcher finds bun itself — no PATH export needed.",
+    "   rem launcher finds bun itself - no PATH export needed.",
     "   if not exist \"%USERPROFILE%\\.ukp\" mkdir \"%USERPROFILE%\\.ukp\"",
     `   ${serveLine} >> "%USERPROFILE%\\.ukp\\door.log" 2>&1`,
     "",
-    "2) Hidden launcher — save as %USERPROFILE%\\.ukp\\start-door-hidden.vbs",
+    "2) Hidden launcher - save as %USERPROFILE%\\.ukp\\start-door-hidden.vbs",
     "   (CRLF and a real editor again: the vbs carries literal % signs that",
-    "   ssh echo would expand — copy the file instead)",
+    "   ssh echo would expand - copy the file instead)",
     "",
     "   ' UKP door hidden launcher: runs start-door.cmd with NO visible",
     "   ' window (hidden at process creation - nothing flashes), captures",
@@ -150,7 +150,7 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
     "   Next",
     "   WScript.Quit rc",
     "",
-    "3) Scheduled task — starts the door at LOGON, hidden",
+    "3) Scheduled task - starts the door at LOGON, hidden",
     "   (create it from an elevated shell: creating an ONLOGON task from a",
     "    plain shell fails with Access denied)",
     "",
@@ -167,29 +167,29 @@ export function renderServeTaskArtifacts(input: ServeTaskInput): string {
           "- --tls self-signs at first start using an openssl on PATH (Git",
           "  for Windows' openssl qualifies). On a host with no openssl",
           "  anywhere, pre-generate the certificate once instead: re-run with",
-          "  --tls-cert/--tls-key — the handbook's Windows section carries",
+          "  --tls-cert/--tls-key - the handbook's Windows section carries",
           "  that recipe.",
         ]
       : []),
     "- No visible window, by design: the hidden launcher starts the console",
     "  hidden at process creation (nothing ever flashes on the desktop) and",
-    "  captures everything to door.log — that redirect is the paper trail (a",
+    "  captures everything to door.log - that redirect is the paper trail (a",
     "  silent EADDRINUSE exit leaves a line).",
     "- Crash self-recovery is the launcher's bounded retry: a non-zero exit",
     "  is retried up to 3 times, 30s apart; exhausted retries leave the",
     "  failure visible (non-zero task result + door.log). Do not rely on",
-    "  Task Scheduler's restart-on-failure setting — it does not fire on",
+    "  Task Scheduler's restart-on-failure setting - it does not fire on",
     "  exit codes.",
     "- To restart the door by hand (new token, ukp upgrade, new cert):",
     "  taskkill /PID <door-pid> /T /F, then schtasks /Run /TN ukp-door",
     "  (schtasks /End does not reliably kill the process tree).",
-    "- LOGON, not boot: the door starts when someone logs on — nobody",
+    "- LOGON, not boot: the door starts when someone logs on - nobody",
     "  logged on means no door. Unattended-boot always-on needs a service",
-    "  wrapper (WinSW-class) — deliberately outside this recipe; prefer the",
+    "  wrapper (WinSW-class) - deliberately outside this recipe; prefer the",
     "  ssh:// path or a Linux host (systemd socket activation) for that.",
     "- Re-run ukp serve --print-task with different flags to regenerate;",
     "  edits land by saving the files and re-running schtasks /Run.",
-    "- Full recipes and hardening: the deployment handbook —",
+    "- Full recipes and hardening: the deployment handbook -",
     "  docs/remote-deployment.md in this package, or",
     "  https://github.com/CatheadOwl/ukp/blob/main/docs/remote-deployment.md",
     "",

package/src/commands/serve.ts

@@ -34,23 +34,23 @@ function parseServeTokens(raw: string | undefined): string[] {
  * over `/e/<name>/` routing. */
 export const SERVE_SPEC: UkpCommandSpec = {
   name: "serve",
-  summary: "serve one endpoint — or the whole registry as a host door, one HTTP server for every endpoint — for remote UKP clients",
+  summary: "serve one endpoint - or the whole registry as a host door, one HTTP server for every endpoint - for remote UKP clients",
   group: "operations",
   description:
-    "Expose a registered endpoint over HTTP using the ukp-remote wire, or — without --endpoint — serve every local endpoint as one host door routed by name.",
-  usage: "[--endpoint <name>] [--host <addr>] [--port <n>] [--tls [--tls-san <ip|dns>]… | --tls-cert <pem> --tls-key <pem>] [--max-idle <seconds>] [--systemd-socket] [--print-task]",
+    "Expose a registered endpoint over HTTP using the ukp-remote wire, or - without --endpoint - serve every local endpoint as one host door routed by name.",
+  usage: "[--endpoint <name>] [--host <addr>] [--port <n>] [--tls [--tls-san <ip|dns>]... | --tls-cert <pem> --tls-key <pem>] [--max-idle <seconds>] [--systemd-socket] [--print-task]",
   options: [
     { flags: "--endpoint <name>", help: "the registered endpoint to expose; omit it to serve the whole registry as a host door (/e/<name>/ routing, all endpoints, one port)" },
     { flags: "--host <addr>", help: "listen address (default 127.0.0.1, loopback only without a token)" },
     { flags: "--port <n>", help: "listen port (default 8570)" },
     { flags: "--tls", help: "serve HTTPS with a self-signed identity (auto-generated under .ukp/tls/, SAN covers this host's addresses; clients pin it at registration)" },
     { flags: "--tls-san <ip|dns>", help: "extra SAN entry for the --tls self-signed identity (repeatable): a public/NAT IP or hostname no NIC of this host carries; a persisted certificate missing an entry is re-signed over the same key (pin unchanged, pinned clients re-anchor)", multi: true },
-    { flags: "--tls-cert <pem>", help: "TLS certificate (chain) PEM path — Let's Encrypt, mkcert, or a private CA; pair with --tls-key" },
+    { flags: "--tls-cert <pem>", help: "TLS certificate (chain) PEM path - Let's Encrypt, mkcert, or a private CA; pair with --tls-key" },
     { flags: "--tls-key <pem>", help: "TLS private key PEM path; pair with --tls-cert" },
     { flags: "--allow-anonymous", help: "permit tokenless access on loopback (local testing, or an ssh-forwarded host door where SSH carries encryption and auth; reverse-proxy deployments still require UKP_SERVE_TOKEN)" },
-    { flags: "--max-idle <seconds>", help: "exit after <seconds> without requests (self-reap; the orphan backstop for on-demand-woken doors — fractional values accepted for tests)" },
-    { flags: "--systemd-socket", help: "serve on the systemd socket-activation listener (LISTEN_FDS fd 3) instead of binding a port — the port belongs to your .socket unit; Linux-only" },
-    { flags: "--print-task", help: "Windows: print this door's process-manager artifacts (start script, hidden launcher, Task Scheduler command, firewall rule) instead of serving — review and apply them yourself; nothing is installed or started for you, and the token is yours to paste (never printed)" },
+    { flags: "--max-idle <seconds>", help: "exit after <seconds> without requests (self-reap; the orphan backstop for on-demand-woken doors - fractional values accepted for tests)" },
+    { flags: "--systemd-socket", help: "serve on the systemd socket-activation listener (LISTEN_FDS fd 3) instead of binding a port - the port belongs to your .socket unit; Linux-only" },
+    { flags: "--print-task", help: "Windows: print this door's process-manager artifacts (start script, hidden launcher, Task Scheduler command, firewall rule) instead of serving - review and apply them yourself; nothing is installed or started for you, and the token is yours to paste (never printed)" },
   ],
   helpSuffix: [
     "",
@@ -58,9 +58,9 @@ export const SERVE_SPEC: UkpCommandSpec = {
     `  GET  ${DISCOVERY_PATH}        discovery document (manifest projection,`,
     "                                protocol version, instance identity)",
     "  POST /v1/search              {query, limit} -> ukp.search.v1 envelope",
-    "  GET  /v1/read?ref=…|uri=…    endpoint-relative ref or ukp:// URI",
+    "  GET  /v1/read?ref=...|uri=...  endpoint-relative ref or ukp:// URI",
     "  GET  /v1/nav?path=&depth=    markdown route view (ukp.nav.v1)",
-    "  GET  /v1/rg?query=…          lexical search (ukp.rg.v1, ukp_uri handoff)",
+    "  GET  /v1/rg?query=...        lexical search (ukp.rg.v1, ukp_uri handoff)",
     "",
     "Wire (ukp-remote v1), host door (no --endpoint):",
     `  GET  ${DISCOVERY_PATH}        door document (scope:"host", endpoint roster)`,
@@ -75,26 +75,26 @@ export const SERVE_SPEC: UkpCommandSpec = {
     "  --allow-anonymous, loopback binds only. The discovery document stays",
     "  public. A reverse proxy on the same host forwards from the public side",
     "  to the loopback bind, so proxy deployments treat the token as",
-    "  mandatory — serve cannot see past its own bind address.",
+    "  mandatory - serve cannot see past its own bind address.",
     "",
     "  Loopback-without-token covers testing/dogfood AND the ssh door",
     "  deployment: bind the door on the remote host's loopback and let ssh",
     "  forwarding carry encryption and authentication (clients register",
-    "  'ukp register --url ssh://<host>' — zero tokens, docker",
+    "  'ukp register --url ssh://<host>' - zero tokens, docker",
     "  DOCKER_HOST=ssh:// posture). It is not the way to consume a",
-    "  same-machine endpoint — register its local path instead.",
+    "  same-machine endpoint - register its local path instead.",
     "  TLS: pass --tls to serve HTTPS with a self-signed identity",
-    "  (generated under .ukp/tls/ — under the registry directory in door",
-    "  mode —, SAN covers this host's addresses; remote clients TOFU-pin it",
+    "  (generated under .ukp/tls/ - under the registry directory in door",
+    "  mode -, SAN covers this host's addresses; remote clients TOFU-pin it",
     "  at registration and refresh by re-registering), or --tls-cert/--tls-key",
-    "  for your own certificate (Let's Encrypt — IP certs available since",
-    "  2026-01 —, mkcert, a private CA). Plain HTTP remains loopback-only by",
+    "  for your own certificate (Let's Encrypt - IP certs available since",
+    "  2026-01 -, mkcert, a private CA). Plain HTTP remains loopback-only by",
     "  admission; public exposure needs TLS or the ssh:// transport.",
     "",
     "  A cloud NAT/EIP host's public IP is on no NIC (--tls alone cannot",
     "  cover it): add --tls-san <public-ip> next to --tls. Repeatable; DNS",
     "  names accepted. The persisted certificate re-signs over the same key",
-    "  when a new entry appears — the pin is unchanged and pinned clients",
+    "  when a new entry appears - the pin is unchanged and pinned clients",
     "  re-anchor transparently; dropping entries never re-signs.",
     "",
   ].join("\n"),
@@ -136,7 +136,7 @@ function toParsedServe(parsed: KitParsed): ParsedServe {
   }
   const printTask = options.printTask === true;
   if (printTask && systemdSocket) {
-    throw new KitUsageError("--print-task is the Windows resident form; --systemd-socket is the Linux one (systemd holds the port — see the deployment handbook)");
+    throw new KitUsageError("--print-task is the Windows resident form; --systemd-socket is the Linux one (systemd holds the port - see the deployment handbook)");
   }
   let maxIdleSeconds: number | undefined;
   if (options.maxIdle !== undefined) {
@@ -183,10 +183,10 @@ export function renderServeBanner(info: ServeInfo): string {
       `serving host door (ukp-remote v1)`,
       `  listening: ${info.url}`,
       `  discovery: ${info.url.startsWith("http") ? `${info.url}${DISCOVERY_PATH}` : info.url} (host door)`,
-      `  endpoints: ${info.door!.endpoints.length > 0 ? info.door!.endpoints.join(", ") : "(none — register endpoints on this host)"}`,
+      `  endpoints: ${info.door!.endpoints.length > 0 ? info.door!.endpoints.join(", ") : "(none - register endpoints on this host)"}`,
       `  write: ${info.door!.write.length > 0 ? info.door!.write.join(", ") + " (propose via PUT /e/<name>/v1/propose/<id>)" : "(no endpoint declares propose)"}`,
       `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback bind; ssh-forwarded clients authenticate by SSH key)"}`,
-      `  rg: ${info.rg === "ok" ? "ok" : "missing (rg calls skip with a warning — install ripgrep on this door's PATH)"}`,
+      `  rg: ${info.rg === "ok" ? "ok" : "missing (rg calls skip with a warning - install ripgrep on this door's PATH)"}`,
       ...(info.maxIdleSeconds !== undefined
         ? [`  idle: exits after ${info.maxIdleSeconds}s without requests (--max-idle)`]
         : []),
@@ -201,7 +201,7 @@ export function renderServeBanner(info: ServeInfo): string {
     `  listening: ${info.url}`,
     `  discovery: ${info.url.startsWith("http") ? `${info.url}${DISCOVERY_PATH}` : info.url}`,
     `  auth: ${info.authRequired ? "bearer token required" : "no token (loopback only)"}`,
-    `  rg: ${info.rg === "ok" ? "ok" : "missing (rg calls skip with a warning — install ripgrep on this door's PATH)"}`,
+    `  rg: ${info.rg === "ok" ? "ok" : "missing (rg calls skip with a warning - install ripgrep on this door's PATH)"}`,
     ...(info.maxIdleSeconds !== undefined
       ? [`  idle: exits after ${info.maxIdleSeconds}s without requests (--max-idle)`]
       : []),
@@ -295,7 +295,7 @@ export function executeServeCommand(
     // premise of --allow-anonymous is unverifiable here (RQ-18 review P1).
     if (systemdSocket && tokens.length === 0) {
       throw new Error(
-        "refusing to serve on --systemd-socket without a token: the listener's bind address belongs to the socket unit and may be public — tokenless loopback serving cannot be verified here; set UKP_SERVE_TOKEN",
+        "refusing to serve on --systemd-socket without a token: the listener's bind address belongs to the socket unit and may be public - tokenless loopback serving cannot be verified here; set UKP_SERVE_TOKEN",
       );
     }
     const decision = serveAuthDecision(host, tokens, allowAnonymous);

package/src/registry.ts

@@ -230,7 +230,7 @@ export function assertRegistrableRemoteUrl(raw: string): void {
       + `${parts.endpointName !== undefined ? `/${parts.endpointName}` : ""}`;
     throw new RegistryError(
       `ssh:// urls take no port: the woken door listens on a client-chosen loopback port and the url port selects nothing`
-        + ` — register '${portless}' instead`
+        + ` - register '${portless}' instead`
         + ` (for a non-standard sshd port, use an ssh config Host alias)`,
     );
   }
@@ -240,7 +240,7 @@ export class RegistryBusyError extends RegistryError {
   constructor(path: string) {
     super(
       `registry_busy: ${path} (another ukp process holds the registry lock; ` +
-        `stale locks are reclaimed automatically — close other ukp commands or retry shortly)`,
+        `stale locks are reclaimed automatically - close other ukp commands or retry shortly)`,
     );
     this.name = "RegistryBusyError";
   }

package/src/server.ts

@@ -33,6 +33,7 @@ import {
   runRg,
   projectRgEnvelope,
   RG_DEFAULT_LIMIT,
+  RG_FILES_DEFAULT_LIMIT,
   RG_MAX_LIMIT,
   validateRgPassthrough,
   RgUsageError,
@@ -407,7 +408,7 @@ function parseReadParams(
   pin: string | null,
 ): { request: ReadRequest } | { error: string; class?: string } {
   if ((ref === null) === (uri === null)) {
-    return { error: "exactly one of 'ref' (endpoint-relative) or 'uri' (ukp://…) is required" };
+    return { error: "exactly one of 'ref' (endpoint-relative) or 'uri' (ukp://...) is required" };
   }
   const args = uri !== null
     ? [
@@ -463,18 +464,44 @@ function parseNavParams(
 }
 
 /** Wire rg params → ParsedRg with serve-fixed scope. Params are flat (no
- * argv reconstruction needed): query/limit/glob/type/i/count map onto
+ * argv reconstruction needed): query/limit/glob/type/i/count/files map onto
  * ParsedRg directly and passthrough re-validates against the same
- * allowlist (ADR-RG-002) before any endpoint work starts. */
+ * allowlist (ADR-RG-002) before any endpoint work starts. Files mode
+ * (ADR-RG-005) mirrors the CLI parse layer's mutual exclusions so the wire
+ * keeps the same strictness as query/limit. */
 function parseRgParams(
   endpointName: string,
   url: URL,
 ): { parsed: ParsedRg } | { error: string } {
+  // Boolean params are strictly "1"/"0" — same strictness as query/limit, so
+  // a hand-crafted `i=true` is a visible usage error, not a silent mode miss.
+  const booleanOf = (name: string): boolean | { error: string } => {
+    const raw = url.searchParams.get(name);
+    if (raw === null) return false;
+    if (raw === "1") return true;
+    if (raw === "0") return false;
+    return { error: `'${name}' must be 1 or 0` };
+  };
+  const files = booleanOf("files");
+  if (typeof files === "object") return files;
+  const ignoreCase = booleanOf("i");
+  if (typeof ignoreCase === "object") return ignoreCase;
+  const count = booleanOf("count");
+  if (typeof count === "object") return count;
   const query = url.searchParams.get("query");
-  if (query === null || query.length === 0) {
-    return { error: "'query' is required and must be a non-empty pattern" };
+  if (files && count) {
+    return { error: "'files' and 'count' cannot be used together (pick one output mode)" };
+  }
+  if (files && ignoreCase) {
+    return { error: "'files' cannot be combined with 'i': pass an --iglob passthrough arg for a case-insensitive glob filter" };
+  }
+  if (files && query !== null) {
+    return { error: "'files' takes no 'query' - use 'glob' to filter by name" };
   }
-  let limit = RG_DEFAULT_LIMIT;
+  if (!files && (query === null || query.length === 0)) {
+    return { error: "'query' is required and must be a non-empty pattern (or pass files=1 for enumeration mode)" };
+  }
+  let limit = files ? RG_FILES_DEFAULT_LIMIT : RG_DEFAULT_LIMIT;
   const rawLimit = url.searchParams.get("limit");
   if (rawLimit !== null) {
     if (!/^[0-9]+$/.test(rawLimit)) return { error: "'limit' must be a decimal integer" };
@@ -490,31 +517,19 @@ function parseRgParams(
     if (error instanceof RgUsageError) return { error: error.message };
     throw error;
   }
-  // Boolean params are strictly "1"/"0" — same strictness as query/limit, so
-  // a hand-crafted `i=true` is a visible usage error, not a silent mode miss.
-  const booleanOf = (name: string): boolean | { error: string } => {
-    const raw = url.searchParams.get(name);
-    if (raw === null) return false;
-    if (raw === "1") return true;
-    if (raw === "0") return false;
-    return { error: `'${name}' must be 1 or 0` };
-  };
-  const ignoreCase = booleanOf("i");
-  if (typeof ignoreCase === "object") return ignoreCase;
-  const count = booleanOf("count");
-  if (typeof count === "object") return count;
-  const glob = url.searchParams.get("glob");
+  const globs = url.searchParams.getAll("glob");
   const type = url.searchParams.get("type");
   return {
     parsed: {
-      request: { query, limit },
+      request: { query: files ? "" : query!, limit },
       options: {
         explicitEndpoints: [endpointName],
         global: false,
-        ...(glob !== null ? { glob } : {}),
+        ...(globs.length > 0 ? { globs } : {}),
         ...(type !== null ? { type } : {}),
         ...(ignoreCase ? { ignoreCase: true } : {}),
         ...(count ? { count: true } : {}),
+        ...(files ? { files: true } : {}),
         passthrough,
       },
       warnings: [],
@@ -546,14 +561,14 @@ export function parseListenFds(env: NodeJS.ProcessEnv): { fd: number } | { error
     };
   }
   if (Number(env.LISTEN_PID) !== process.pid) {
-    return { error: `LISTEN_PID ${env.LISTEN_PID} does not match this process (${process.pid}) — inherited activation variables belong to another process` };
+    return { error: `LISTEN_PID ${env.LISTEN_PID} does not match this process (${process.pid}) - inherited activation variables belong to another process` };
   }
   const count = Number(env.LISTEN_FDS);
   if (!Number.isSafeInteger(count) || count < 1) {
     return { error: `LISTEN_FDS=${String(env.LISTEN_FDS)} is not a positive integer` };
   }
   if (count !== 1) {
-    return { error: `expected exactly one listening fd (LISTEN_FDS=1), got ${count} — run one socket unit per serve instance` };
+    return { error: `expected exactly one listening fd (LISTEN_FDS=1), got ${count} - run one socket unit per serve instance` };
   }
   delete env.LISTEN_FDS;
   delete env.LISTEN_PID;
@@ -645,7 +660,7 @@ function startServeListener(
     isSocket = false;
   }
   if (!isSocket) {
-    throw new ServeSetupError(`fd ${parsed.fd} is not an open socket — socket activation must pass a bound listening socket`);
+    throw new ServeSetupError(`fd ${parsed.fd} is not an open socket - socket activation must pass a bound listening socket`);
   }
   const server = Bun.serve({ hostname: "127.0.0.1", port: 0, ...tls, fetch });
   const acceptor = netCreateServer();
@@ -1170,7 +1185,7 @@ function handleRg(url: URL, request: Request, config: ServeConfig, endpointName:
     currentDirectory: config.currentDirectory,
     registryPath: config.registryPath,
   });
-  return jsonResponse(projectRgEnvelope(result, parsed.parsed.options.count === true));
+  return jsonResponse(projectRgEnvelope(result));
 }
 
 /** PUT /v1/propose/{id} (W8 / ADR-REM-005): the write face. Body = the

package/src/spawn-relay.ts

@@ -0,0 +1,57 @@
+/**
+ * Win32 tool-spawn relay (2026-09-22 finding, ukp_remote TODO
+ * 20260922-win32-ssh-spawn-tax): Windows Defender holds the DIRECT
+ * bun-to-<tool>.exe child edge for seconds per spawn — measured 9.7-10.7s for
+ * ssh.exe and ~5.4s for rg.exe across stdio modes, windowsHide, and absolute
+ * paths, while the same binaries start in 0.16-0.26s from bash and in
+ * 0.55-0.8s from bun through ANY intermediary parent (cmd, node, powershell).
+ * The inspection keys on the parent-child edge, so routing the spawn through
+ * a one-level intermediary escapes it.
+ *
+ * The intermediary is powershell.exe driven by -EncodedCommand: the script
+ * rides as one base64 token (no quoting stress from the spawning side), and
+ * the script splats a single-quoted array so argv reaches the tool
+ * byte-identical — the only escape in a PS single-quoted literal is doubling
+ * inner single quotes; double quotes, backslashes, and cmd metacharacters
+ * are all literal (verified E2E: the pinned wake command's load-bearing
+ * quotes survive, door READY ~1.4s). powershell.exe ships with every
+ * Windows; no extra prerequisite is imposed.
+ *
+ * Exit-code contract: the script exits with the tool's own exit status. With
+ * the not-found guard requested, a tool that does not resolve on PATH exits
+ * TOOL_NOT_FOUND_EXIT before any invocation — distinct from every real tool
+ * exit, so callers can keep treating "tool missing" as a degradation instead
+ * of a fault.
+ */
+
+/** Distinct not-found sentinel: no real tool invocation ran when this is the
+ * exit status (ripgrep itself only ever exits 0/1/2; ssh diagnostics arrive
+ * via stderr instead). */
+export const TOOL_NOT_FOUND_EXIT = 127;
+
+/** PS single-quote literal: the only escape is doubling inner single quotes. */
+function psSingleQuoted(arg: string): string {
+  return `'${arg.replaceAll("'", "''")}'`;
+}
+
+/** 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. */
+export function toolRelayScript(argv: readonly string[], options: { notFoundGuard?: boolean } = {}): string {
+  const guard = options.notFoundGuard === true
+    ? " if (-not (Get-Command -LiteralName $a[0] -ErrorAction SilentlyContinue)) { exit 127 };"
+    : "";
+  return `$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
+ * the tool when the direct bun-to-tool edge is taxed (win32 real-tool
+ * spawns). Test-injected commands must not be wrapped. */
+export function toolRelayArgv(argv: readonly string[], options: { notFoundGuard?: boolean } = {}): string[] {
+  return [
+    "powershell",
+    "-NoProfile",
+    "-EncodedCommand",
+    Buffer.from(toolRelayScript(argv, options), "utf16le").toString("base64"),
+  ];
+}