@catheadowl/ukp 0.2.4 → 0.2.6

package/src/commands/serve.ts

@@ -7,9 +7,11 @@ import {
   type KitParsed,
   type UkpCommandSpec,
 } from "./kit.ts";
+import { readRegistry } from "../registry.ts";
+import { homedir } from "node:os";
 import { normalizeTlsSanEntry } from "../capabilities/tls-identity.ts";
 import { DISCOVERY_PATH, startUkpServer, type ServeInfo } from "../server.ts";
-import { printTaskPreflightError, renderServeTaskArtifacts, type ServeTaskTls } from "./serve-task.ts";
+import { printTaskPreflightError, renderServeTaskArtifacts, writeServeTaskArtifacts, type ServeTaskTls } from "./serve-task.ts";
 
 export interface ServeCommandContext {
   currentDirectory: string;
@@ -17,6 +19,10 @@ export interface ServeCommandContext {
   qmdCommand?: readonly string[];
   /** Overrides `process.env.UKP_SERVE_TOKEN` for tests. */
   tokens?: readonly string[];
+  /** Overrides the home directory `--print-task --write` writes into
+   * (tests point this at a scratch home; production resolves the real
+   * user home). */
+  homeDir?: string;
 }
 
 /** `UKP_SERVE_TOKEN=a,b,c` (RQ-16): comma-separated, trimmed, empty entries
@@ -30,17 +36,19 @@ function parseServeTokens(raw: string | undefined): string[] {
  * Bun.serve listener keeps the process alive after runCli returns its exit
  * code; SIGINT/SIGTERM stop the listener so the process exits with it.
  * `--endpoint` is optional (W7 / ADR-REM-004): present = the original
- * single-endpoint mode; absent = host door mode serving the whole registry
- * over `/e/<name>/` routing. */
+ * single-endpoint mode; absent = host door mode serving the registry over
+ * `/e/<name>/` routing — every local binding, or the `--select` whitelist
+ * subset (ADR-REM-010). */
 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, a selected subset, or the whole registry as a host door - one HTTP server, one port - 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 local endpoints as one host door routed by name: all of them, or just the ones --select names.",
+  usage: "[--endpoint <name>] [--select <names>] [--host <addr>] [--port <n>] [--tls [--tls-san <ip|dns>]... | --tls-cert <pem> --tls-key <pem>] [--max-idle <seconds>] [--systemd-socket] [--print-task [--write]]",
   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: "--endpoint <name>", help: "the registered endpoint to expose; omit it to serve a host door (/e/<name>/ routing, one port) instead" },
+    { flags: "--select <names>", help: "host door serving ONLY the named endpoints (comma-separated): one port, /e/<name>/ routing, and a door document that declares just this subset - unselected local endpoints are not served, routed, or declared; mutually exclusive with --endpoint" },
     { 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)" },
@@ -51,6 +59,7 @@ export const SERVE_SPEC: UkpCommandSpec = {
     { 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: "--write", help: "with --print-task: write the two artifact files (%USERPROFILE%\\.ukp\\start-door.cmd with the token interpolated from UKP_SERVE_TOKEN, plus the hidden launcher) instead of printing them - existing files are never overwritten, the token is never displayed, and the task/firewall steps stay on stdout for you to apply" },
   ],
   helpSuffix: [
     "",
@@ -63,7 +72,8 @@ export const SERVE_SPEC: UkpCommandSpec = {
     "  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)`,
+    `  GET  ${DISCOVERY_PATH}        door document (scope:"host", endpoint roster -`,
+    "                                the --select subset when --select is given)",
     "  GET  /e/<name>/.well-known/ukp.json   per-endpoint document (same shape",
     "                                as single-endpoint mode; TOFU pins anchor here)",
     "  POST /e/<name>/v1/search     capabilities routed by endpoint name",
@@ -103,6 +113,12 @@ export const SERVE_SPEC: UkpCommandSpec = {
 export interface ParsedServe {
   /** Present = single-endpoint mode; absent = host door mode (W7). */
   endpoint?: string;
+  /** `--select` names (ADR-REM-010): present next to an absent endpoint =
+   * subset door — the door serves, routes, and declares only these
+   * endpoints. Parsed here exactly the way register --select parses its
+   * list (comma-separated, trimmed, empty entries dropped); the execute
+   * layer's eager check (usage error with the roster) is the admission. */
+  select?: string[];
   host: string;
   port: number;
   /** Present = the --max-idle self-reap timer is armed (W9). */
@@ -112,6 +128,10 @@ export interface ParsedServe {
   /** Present = render the Windows process-manager artifacts instead of
    * serving (W12; Windows-only, print-only, never starts a listener). */
   printTask?: boolean;
+  /** Present = the print-task artifacts' file pair lands on disk with the
+   * env token interpolated (O-020 ruling C); only valid next to
+   * --print-task, and the print surface stays secret-free. */
+  write?: boolean;
   /** `--tls-san` values, normalized to `IP:x`/`DNS:y` SAN form (repeatable);
    * valid only next to `--tls` — the execute layer enforces the pairing.
    * Absent when the flag is not passed (parse output stays byte-identical
@@ -120,11 +140,24 @@ export interface ParsedServe {
 }
 
 function toParsedServe(parsed: KitParsed): ParsedServe {
-  const options = parsed.options as { host?: string; port?: string; endpoint?: string; maxIdle?: string; systemdSocket?: boolean; printTask?: boolean; tlsSan?: string[] };
+  const options = parsed.options as { host?: string; port?: string; endpoint?: string; select?: string; maxIdle?: string; systemdSocket?: boolean; printTask?: boolean; write?: boolean; tlsSan?: string[] };
   const endpoint = options.endpoint;
   if (endpoint !== undefined && endpoint.length === 0) {
     throw new KitUsageError("--endpoint <name> must not be empty (omit it to serve a host door)");
   }
+  // --select parses with register --select's exact list semantics (the same
+  // operation's other side): comma-separated, trimmed, empties dropped. A
+  // flag that parses to nothing is a usage error, not an empty whitelist.
+  let select: string[] | undefined;
+  if (options.select !== undefined) {
+    select = options.select.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+    if (select.length === 0) {
+      throw new KitUsageError("--select requires at least one endpoint name");
+    }
+  }
+  if (endpoint !== undefined && select !== undefined) {
+    throw new KitUsageError("--endpoint and --select cannot be used together (--endpoint is the N=1 form; --select narrows a host door)");
+  }
   const host = options.host ?? "127.0.0.1";
   const port = Number(options.port ?? "8570");
   if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
@@ -138,6 +171,10 @@ function toParsedServe(parsed: KitParsed): ParsedServe {
   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)");
   }
+  const write = options.write === true;
+  if (write && !printTask) {
+    throw new KitUsageError("--write modifies --print-task: run ukp serve --print-task --write (without --print-task, serve just serves)");
+  }
   let maxIdleSeconds: number | undefined;
   if (options.maxIdle !== undefined) {
     maxIdleSeconds = Number(options.maxIdle);
@@ -160,11 +197,13 @@ function toParsedServe(parsed: KitParsed): ParsedServe {
   }
   return {
     ...(endpoint !== undefined ? { endpoint } : {}),
+    ...(select !== undefined ? { select } : {}),
     host,
     port,
     ...(maxIdleSeconds !== undefined ? { maxIdleSeconds } : {}),
     ...(systemdSocket ? { systemdSocket } : {}),
     ...(printTask ? { printTask } : {}),
+    ...(write ? { write } : {}),
     ...(tlsSan.length > 0 ? { tlsSan } : {}),
   };
 }
@@ -184,6 +223,9 @@ export function renderServeBanner(info: ServeInfo): string {
       `  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)"}`,
+      ...(info.door!.select !== undefined
+        ? [`  select: ${info.door!.select.join(", ")} (subset door - unselected local endpoints are not served, routed, or declared)`]
+        : []),
       `  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)"}`,
@@ -241,7 +283,7 @@ export function executeServeCommand(
   context: ServeCommandContext,
 ): KitCommandResult {
   return executeKitCommand(SERVE_SPEC, args, (parsed) => {
-    const { endpoint, host, port, maxIdleSeconds, systemdSocket, tlsSan = [] } = toParsedServe(parsed);
+    const { endpoint, select, host, port, maxIdleSeconds, systemdSocket, write, tlsSan = [] } = toParsedServe(parsed);
     const allowAnonymous = (parsed.options as { allowAnonymous?: boolean }).allowAnonymous === true;
     const printTask = (parsed.options as { printTask?: boolean }).printTask === true;
     const options = parsed.options as { tls?: boolean; tlsCert?: string; tlsKey?: string };
@@ -258,10 +300,37 @@ export function executeServeCommand(
     if (tlsSan.length > 0 && options.tls !== true) {
       throw new KitUsageError("--tls-san is only used with --tls (an explicit --tls-cert certificate carries its own SAN)");
     }
-    // W12 print-only branch: render the Windows artifacts and stop. No
-    // listener, no admission token check (the token is pasted into the
-    // generated script later), and the env token is deliberately not read
-    // — the output is secret-free by construction.
+    // Subset-door admission (ADR-REM-010): a name not among the local
+    // bindings is a usage error with the roster — the eager check mirrors
+    // register --select's door-import behavior and the ingress admission
+    // precedent (a typo silently narrowing the door is a zero-signal
+    // misconfiguration). An unreadable registry skips the check: that
+    // failure surface is the door's own, shown per request like today.
+    if (select !== undefined && endpoint === undefined) {
+      let localNames: string[] | undefined;
+      try {
+        localNames = readRegistry(context.registryPath)
+          .filter((binding) => binding.kind !== "remote")
+          .map((binding) => binding.name);
+      } catch {
+        localNames = undefined;
+      }
+      if (localNames !== undefined) {
+        const unknown = select.filter((name) => !localNames!.includes(name));
+        if (unknown.length > 0) {
+          throw new KitUsageError(
+            `--select names not registered on this host: ${unknown.join(", ")} (available: ${localNames.join(", ")})`,
+          );
+        }
+      }
+    }
+    // W12 print branch: render the Windows artifacts and stop. No listener,
+    // no admission token check. Print mode never reads the env token - the
+    // output is secret-free by construction. Write mode (O-020 ruling C:
+    // the D-090 secret-free clause scopes to the print surface) reads
+    // UKP_SERVE_TOKEN to interpolate it into the files it writes - the
+    // token exists in exactly one place, the cmd file's bytes; stdout stays
+    // secret-free in both modes.
     if (printTask) {
       const preflight = printTaskPreflightError({
         platform: process.platform,
@@ -278,13 +347,25 @@ export function executeServeCommand(
           : options.tlsCert !== undefined && options.tlsKey !== undefined
             ? { mode: "certificates", certPath: options.tlsCert, keyPath: options.tlsKey }
             : undefined;
+      const input = {
+        host,
+        port,
+        ...(endpoint !== undefined ? { endpoint } : {}),
+        ...(select !== undefined ? { select } : {}),
+        ...(tls !== undefined ? { tls } : {}),
+      };
+      if (!write) {
+        return {
+          exitCode: 0,
+          stdout: renderServeTaskArtifacts(input),
+          stderr: "",
+        };
+      }
       return {
         exitCode: 0,
-        stdout: renderServeTaskArtifacts({
-          host,
-          port,
-          ...(endpoint !== undefined ? { endpoint } : {}),
-          ...(tls !== undefined ? { tls } : {}),
+        stdout: writeServeTaskArtifacts(input, {
+          token: process.env.UKP_SERVE_TOKEN,
+          homeDir: context.homeDir ?? homedir(),
         }),
         stderr: "",
       };
@@ -310,6 +391,7 @@ export function executeServeCommand(
       host,
       port,
       ...(endpoint !== undefined ? { endpointName: endpoint } : {}),
+      ...(select !== undefined ? { select } : {}),
       ...(tokens.length > 0 ? { tokens } : {}),
       ...(maxIdleSeconds !== undefined ? { maxIdleSeconds } : {}),
       ...(systemdSocket !== undefined && systemdSocket ? { systemdSocket } : {}),

package/src/server.ts

@@ -33,6 +33,7 @@ import {
   runRg,
   projectRgEnvelope,
   RG_DEFAULT_LIMIT,
+  RG_FILES_DEFAULT_LIMIT,
   RG_MAX_LIMIT,
   validateRgPassthrough,
   RgUsageError,
@@ -43,18 +44,22 @@ import { KitUsageError } from "./commands/kit.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
  * registered endpoint; door mode (`endpointName` absent, ADR-REM-004) serves
- * every local binding in the registry, routed by name at `/e/<name>/…` with
+ * local bindings in the registry, routed by name at `/e/<name>/…` with
  * a `scope:"host"` door document — the registry is read fresh per request so
- * the door grows without restart. Both shapes expose a discovery document
- * (manifest projection + protocol version + instance identity) plus the
- * read-side capability routes (search/read since W1, nav/rg since W6); the
- * per-endpoint documents are byte-identical across 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 session, no streaming, and
- * no server-side artifact: responses inline the reference data (RQ-07) and
- * generate a serve-scoped run id. */
+ * the door grows without restart. Door mode comes in two widths
+ * (ADR-REM-010): every local binding, or the `select` whitelist subset. To
+ * anyone the subset excludes, the door pretends those endpoints do not
+ * exist — roster, routes, per-endpoint documents, and 404 rosters all see
+ * the same effective set (select ∩ current registry). Both shapes expose a
+ * discovery document (manifest projection + protocol version + instance
+ * identity) plus the read-side capability routes (search/read since W1,
+ * nav/rg since W6); the per-endpoint documents are byte-identical across
+ * 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
+ * session, no streaming, and no server-side artifact: responses inline the
+ * reference data (RQ-07) and generate a serve-scoped run id. */
 
 export const PROTOCOL_NAME = "ukp-remote";
 export const PROTOCOL_VERSION = "1";
@@ -65,11 +70,20 @@ export const DISCOVERY_PATH = "/.well-known/ukp.json";
 export const PROPOSE_BODY_LIMIT_BYTES = 1024 * 1024;
 
 export interface ServeConfig {
-  /** Absent = host door mode (ADR-REM-004 / O-2): serve EVERY local binding
-   * in the registry over one listener, routed by name at `/e/<name>/…`, with
-   * a `scope:"host"` door document at the well-known path. Present = the
+  /** Absent = host door mode (ADR-REM-004 / O-2): serve local bindings in
+   * the registry over one listener, routed by name at `/e/<name>/…`, with a
+   * `scope:"host"` door document at the well-known path. Present = the
    * original single-endpoint mode (N=1 retreat stays legal long-term). */
   endpointName?: string;
+  /** Subset door (ADR-REM-010 / O-020 ruling D): a declarative name
+   * whitelist next to an ABSENT endpointName — the door serves only the
+   * selected local bindings, and to anyone the list excludes the door
+   * pretends those endpoints do not exist (roster, routes, per-endpoint
+   * documents, 404 rosters all carry the same effective set). The server
+   * layer does NOT validate the names at startup — the command layer's
+   * eager check (usage error with the roster) is the admission; here the
+   * set just intersects with the per-request registry read. */
+  select?: readonly string[];
   currentDirectory: string;
   registryPath: string;
   qmdCommand?: readonly string[];
@@ -143,10 +157,13 @@ export interface ServeInfo {
   folder?: string;
   instanceUid?: string;
   /** Door mode fields (present iff mode === "door"): the startup snapshot of
-   * servable endpoint names (the door itself grows without restart), plus
-   * the snapshot of write-capable (propose-declaring) names — the banner's
-   * "you opened a write face" line (ADR-REM-005 verdict C). */
-  door?: { endpoints: string[]; write: string[] };
+   * servable endpoint names (the door itself grows without restart), the
+   * snapshot of write-capable (propose-declaring) names — the banner's
+   * "you opened a write face" line (ADR-REM-005 verdict C) — and, on a
+   * subset door (ADR-REM-010), the declared select whitelist itself (the
+   * banner's `select:` line: what was asked for, next to what is being
+   * served). */
+  door?: { endpoints: string[]; write: string[]; select?: string[] };
   url: string;
   host: string;
   port: number;
@@ -157,7 +174,7 @@ export interface ServeInfo {
    * consumer-channel only. The banner line is the operator channel, and the
    * probe environment is by construction the one that matters (ukp diagnose
    * measures the invoking shell instead, which can differ from the door's
-   * schtasks / wake environment). */
+   * Task Scheduler / wake environment). */
   rg: "ok" | "missing";
   /** TLS identity summary (W5' / D-079) when serving over HTTPS; the pin is
    * what remote clients TOFU-pin at registration. `source` "re-signed" marks
@@ -278,21 +295,25 @@ export function buildDiscoveryDocument(
   };
 }
 
-/** Servable endpoints of a door (O-2): every LOCAL binding in the registry,
- * 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): Array<{ name: string; folder: string }> {
+/** Servable endpoints of a door (O-2): the LOCAL bindings in the registry
+ * 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 }> {
   return readRegistry(registryPath)
     .filter((binding) => binding.kind !== "remote")
+    .filter((binding) => select === undefined || select.includes(binding.name))
     .map((binding) => ({ name: binding.name, folder: binding.path! }));
 }
 
 /** Startup snapshot of write-capable (propose-declaring) door endpoints —
  * the banner line that makes the opened write face visible (ADR-REM-005
- * verdict C). Unreadable/name-drifted Services drop out silently here;
- * they are already reported by the roster/discovery paths. */
-function listWriteEndpoints(registryPath: string): string[] {
-  return listDoorEndpoints(registryPath).flatMap((endpoint) => {
+ * verdict C). Subset doors narrow it to the select set (ADR-REM-010).
+ * Unreadable/name-drifted Services drop out silently here; they are already
+ * reported by the roster/discovery paths. */
+function listWriteEndpoints(registryPath: string, select?: readonly string[]): string[] {
+  return listDoorEndpoints(registryPath, select).flatMap((endpoint) => {
     try {
       const loaded = loadManifest(endpoint.folder);
       return loaded.effectiveName === endpoint.name
@@ -463,18 +484,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 +537,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: [],
@@ -743,10 +778,14 @@ function bearerGate(
  * read fresh, the name segment has already passed ENDPOINT_NAME (injection
  * unreachable), unknown and non-servable names get the roster 404, and the
  * RQ-14 binding↔manifest identity check runs per request like the
- * single-mode discovery fetch does. */
+ * 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. */
 function resolveDoorRoute(
   registryPath: string,
   name: string,
+  select?: readonly string[],
 ): { folder: string } | { response: Response } {
   let binding;
   try {
@@ -755,8 +794,8 @@ 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") {
-    const roster = listDoorEndpoints(registryPath).map((endpoint) => endpoint.name).join(", ");
+  if (binding === undefined || binding.kind === "remote" || (select !== undefined && !select.includes(name))) {
+    const roster = listDoorEndpoints(registryPath, select).map((endpoint) => endpoint.name).join(", ");
     return {
       response: jsonResponse(
         errorBody("not-found", `no such endpoint '${name}' on this host door (available: ${roster})`),
@@ -793,10 +832,13 @@ function resolveDoorRoute(
 
 /** Door-mode routing table (ADR-REM-004 / O-2). The door document and the
  * per-endpoint documents stay public (ADR-REM-003 declaration/capability
- * divide); every `/e/<name>/v1/*` route passes the door-level bearer gate. */
-function doorNotFound(name: string | undefined, registryPath: string): Response {
+ * 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 {
   if (name !== undefined) {
-    const roster = listDoorEndpoints(registryPath).map((endpoint) => endpoint.name).join(", ");
+    const roster = listDoorEndpoints(registryPath, select).map((endpoint) => endpoint.name).join(", ");
     return jsonResponse(
       errorBody("not-found", `no such endpoint '${name}' on this host door (available: ${roster})`),
       404,
@@ -812,6 +854,11 @@ function doorNotFound(name: string | undefined, registryPath: string): Response
 }
 
 function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnType<typeof resolveTlsMaterial>): StartedServe {
+  // The door's width (ADR-REM-010): undefined = the whole registry, a name
+  // list = the subset whitelist. One variable feeds every surface below —
+  // door document, per-request routes, 404 rosters — so the subset cannot
+  // drift between them.
+  const select = config.select;
   const handler = async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
 
@@ -820,7 +867,7 @@ 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), (config.tokens?.length ?? 0) > 0));
+        return jsonResponse(buildDoorDocument(listDoorEndpoints(config.registryPath, select), (config.tokens?.length ?? 0) > 0));
       } catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
         return jsonResponse(errorBody("provider-unavailable", `Host Registry is not readable: ${reason}`), 503);
@@ -834,13 +881,13 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
       const name = routeMatch[1]!;
       const rest = routeMatch[2] ?? "/";
       if (!ENDPOINT_NAME.test(name)) {
-        return doorNotFound(name, config.registryPath);
+        return doorNotFound(name, config.registryPath, select);
       }
       if (rest === DISCOVERY_PATH) {
         if (request.method !== "GET") {
           return jsonResponse(errorBody("method-not-allowed", `the discovery document is a GET resource`), 405);
         }
-        const resolved = resolveDoorRoute(config.registryPath, name);
+        const resolved = resolveDoorRoute(config.registryPath, name, select);
         if ("response" in resolved) return resolved.response;
         try {
           const loaded = loadManifest(resolved.folder);
@@ -856,15 +903,15 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
         const denied = bearerGate(request, config.tokens);
         if (denied !== undefined) return denied;
         const id = rest.slice("/v1/propose/".length);
-        if (id.includes("/")) return doorNotFound(undefined, config.registryPath);
-        const resolved = resolveDoorRoute(config.registryPath, name);
+        if (id.includes("/")) return doorNotFound(undefined, config.registryPath, select);
+        const resolved = resolveDoorRoute(config.registryPath, name, select);
         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);
+        const resolved = resolveDoorRoute(config.registryPath, name, select);
         if ("response" in resolved) return resolved.response;
         if (rest === "/v1/search") {
           return await handleSearch(request, config, name, resolved.folder);
@@ -877,10 +924,10 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
         }
         return handleRg(url, request, config, name);
       }
-      return doorNotFound(undefined, config.registryPath);
+      return doorNotFound(undefined, config.registryPath, select);
     }
 
-    return doorNotFound(undefined, config.registryPath);
+    return doorNotFound(undefined, config.registryPath, select);
   };
 
   const listener = startServeListener(handler, {
@@ -895,8 +942,9 @@ function startDoorServer(config: ServeConfig, host: string, tlsMaterial: ReturnT
   const info: ServeInfo = {
     mode: "door",
     door: {
-      endpoints: listDoorEndpoints(config.registryPath).map((endpoint) => endpoint.name),
-      write: listWriteEndpoints(config.registryPath),
+      endpoints: listDoorEndpoints(config.registryPath, select).map((endpoint) => endpoint.name),
+      write: listWriteEndpoints(config.registryPath, select),
+      ...(select !== undefined ? { select: [...select] } : {}),
     },
     url: listener.publicUrl,
     host,
@@ -1170,7 +1218,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"),
+  ];
+}