@catheadowl/ukp 0.2.4 → 0.2.5

package/README.md

@@ -61,7 +61,9 @@ predictable scope, and a single command surface. Use UKP when:
   Requirements). `read` and `nav` are derived defaults of every local
   Service.
 - Run base lexical search with `rg` across endpoint files — no search
-  provider needed, on by default, shaped into `read`-ready references.
+  provider needed, on by default, shaped into `read`-ready references —
+  or enumerate them with `rg --files` (a tree walk: empty and binary files
+  included, hidden files behind `-- --hidden`).
 - Search indexed content, QMD-backed: one endpoint, the workspace default
   scope, or the whole local Registry. `--recursive` additionally searches
   the endpoints a Service declares in its manifest `dependencies` —
@@ -143,7 +145,7 @@ Endpoint commands:
 | `ukp search` | Indexed search through the endpoint's provider (QMD today); `--recursive` expands the manifest's declared `dependencies`. Results hand off via docid session keys and verified `ukp://` references. |
 | `ukp read` | Reads an endpoint-scoped resource — exact path, `ukp://` URI, or a `docid` handed off by search results. |
 | `ukp nav` | Markdown outline of an endpoint (`--depth`, respects `.gitignore`); on by default, configurable via `[capabilities.nav]`. |
-| `ukp rg` | Lexical grep (ripgrep) across endpoint files — provider-free, on by default; results become `read`-ready `ukp://` references. A missing rg binary skips the endpoint with a warning. |
+| `ukp rg` | Lexical grep (ripgrep) across endpoint files — provider-free, on by default; `--files` enumerates them instead of searching. Results become `read`-ready `ukp://` references. A missing rg binary skips the endpoint with a warning. |
 | `ukp propose` | Submits an idempotent change proposal (suggestion box — the owner decides what happens next). Created/unchanged/updated; the revision bumps only on `updated`. |
 
 Registry commands:
@@ -171,6 +173,7 @@ Help commands:
 | `ukp guide service` | Provider-agnostic Service setup path. |
 | `ukp guide service qmd` | Provider-owned setup for the QMD provider. |
 | `ukp guide client` | How a workspace uses registered Services by default. |
+| `ukp guide rg` | The rg quickstart: modes, glob semantics, visibility tiers. |
 | `ukp guide remote` | How to serve and consume endpoints across machines. |
 | `ukp guide propose` | The propose quickstart. |
 

package/docs/remote-deployment.md

@@ -65,6 +65,13 @@ Notes:
   wake — the client chooses the door port per invocation, which a fixed
   forced command cannot express.
 
+Windows note: some antivirus setups (Windows Defender behavioral inspection
+included) delay a process spawned directly by the runtime by several seconds
+per call — 5-10s per ssh/rg spawn was measured before ukp routed its
+Windows tool spawns through a one-level relay. ukp does this automatically;
+if you also add your own exclusion for your package manager's runtimes the
+residual per-call cost is just the real ssh handshake plus the door spawn.
+
 Windows hosts work out of the box: when the host's OpenSSH default shell
 (cmd.exe) rejects the POSIX wake form, the client detects the signature and
 resends the pinned cmd.exe form automatically — nothing to configure beyond

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catheadowl/ukp",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "engines": {
     "bun": ">=1.3.14"

package/src/capabilities/remote-client.ts

@@ -19,11 +19,12 @@ import {
   type RemoteUrlParts,
 } from "../registry.ts";
 import { spkiPinOf } from "./tls-identity.ts";
+import { toolRelayScript } from "../spawn-relay.ts";
 import type { SearchEndpointOutcome } from "./search.ts";
 import type { NavEnvelope } from "./nav.ts";
 import type { ProposeResult, ProposeStatus } from "./propose.ts";
 import { EXTERNAL_PROVIDER } from "../config/external-tool.ts";
-import type { RgEndpointOutcome, RgMatch, RgCountEntry } from "./rg.ts";
+import type { RgEndpointOutcome, RgMatch, RgCountEntry, RgFileEntry } from "./rg.ts";
 
 /** Remote transport for the client side (ukp-remote wire v1, ADR-REM-002/003;
  * ukp_remote W2). All calls fetch fresh (no cross-invocation cache), carry the
@@ -381,6 +382,71 @@ function wrongShellSignature(form: WakeShellForm, diagnostics: string): boolean
   return /['"]cmd['"]|cmd: (?:command )?not found/i.test(diagnostics);
 }
 
+/** Wake failure classes from ssh's own diagnostics (ADR-REM-008 / D-093):
+ * OpenSSH's stderr wording is locale-stable (unlike cmd.exe's), so stable
+ * substrings classify the deterministic failures — verdicts a re-run against
+ * the same host reproduces, which is why none of them belongs in the retry
+ * ladder. One taxonomy, three matchers: these connect/auth signatures here,
+ * missing-ukp (127/9009 dictionary) and shell-mismatch keep their existing
+ * branches. Pure function by design — the signature table is unit-testable
+ * without spawning ssh. */
+export type WakeFailureClass = "unreachable" | "refused" | "auth" | "hostkey";
+
+export function classifyWakeFailure(diagnostics: string): WakeFailureClass | undefined {
+  if (/Connection timed out|No route to host|Could not resolve hostname/i.test(diagnostics)) return "unreachable";
+  if (/Connection refused/i.test(diagnostics)) return "refused";
+  if (/Host key verification failed/i.test(diagnostics)) return "hostkey";
+  // Auth failures always carry the method-list suffix ("Permission denied
+  // (publickey,password).") — ssh's own format. The bare phrase also appears
+  // in REMOTE-COMMAND exec errors (a found-but-not-executable ukp on a
+  // noexec mount), which reach these diagnostics under -tt and must keep
+  // falling through to the generic wording, not get the key-auth remedy
+  // (review P2).
+  if (/Permission denied \(/i.test(diagnostics)) return "auth";
+  return undefined;
+}
+
+/** A probe-stage timeout verdict is not trustworthy on its own (ADR-REM-008
+ * §3, implementation-time refinement): the probe's 5s race window is shorter
+ * than the full ConnectTimeout budget a slow-but-alive host may legitimately
+ * need — its wake would succeed in the ladder's window — so black-hole
+ * signatures defer to the ladder, which runs the full budget before the same
+ * classifier issues the verdict. Instant verdicts (refused, auth, hostkey,
+ * resolve and no-route failures) settle within one roundtrip and are trusted
+ * wherever they appear; a probe-local short ConnectTimeout would have
+ * misjudged every host slower than it. */
+function wakeFailureDefersToLadder(failureClass: WakeFailureClass, diagnostics: string): boolean {
+  return failureClass === "unreachable"
+    && /Connection timed out/i.test(diagnostics)
+    && !/No route to host|Could not resolve hostname/i.test(diagnostics);
+}
+
+/** Classified wake-failure text (ADR-REM-008 §4): names the ssh TARGET (an
+ * origin-level fact under fan-out — never an endpoint label), quotes the ssh
+ * diagnostics as evidence, and gives the class its one remedy. Printable
+ * ASCII only — the frozen vocabulary rule for runtime strings. */
+export function wakeFailureMessage(failureClass: WakeFailureClass, target: string, diagnostics: string): string {
+  const evidence = diagnostics.length > 0 ? `: ${diagnostics}` : "";
+  switch (failureClass) {
+    case "unreachable":
+      return `waking the ukp door on '${target}' failed - the host is unreachable${evidence}. The machine appears off, firewalled, or its address no longer resolves; verify it is powered on and reachable`;
+    case "refused":
+      return `waking the ukp door on '${target}' failed - the host is reachable but nothing is listening for ssh${evidence}. Start the ssh server on the host (on Windows: the optional OpenSSH Server feature) or fix the port`;
+    case "auth":
+      return `waking the ukp door on '${target}' failed - ssh rejected the credentials (BatchMode, no password prompt)${evidence}. Fix key auth: add the public key to the host's authorized_keys, or check the ssh config's IdentityFile`;
+    case "hostkey":
+      return `waking the ukp door on '${target}' failed - the host key was not accepted${evidence}. If the host was reinstalled this is expected: re-verify it (ssh-keygen -R), then retry`;
+  }
+}
+
+/** Not-ready wording (ADR-REM-008): the old text blamed the host alias and
+ * key auth — both, by the time this message is reached, have already
+ * succeeded (their failures classify earlier); what failed is the door
+ * behind a working connection. */
+export function wakeNotReadyMessage(target: string, timeoutMs: number): string {
+  return `the ssh connection to '${target}' worked but the ukp door did not become ready within ${Math.round(timeoutMs / 1000)}s. Host prerequisite (W9): ukp on the remote PATH; a slow first start also lands here - retry once before investigating`;
+}
+
 /** Cross-invocation shell-family cache (ukp_list W1 / L-1, ADR 0026's
  * implementation-time note): a host's shell family is a static fact, but
  * learning it costs a full ssh roundtrip per origin per invocation — on
@@ -426,6 +492,60 @@ function persistShellFamily(cachePath: string | undefined, target: string, form:
   }
 }
 
+/** Structural subset of Bun's Subprocess that the ssh paths consume (a Pick,
+ * not a hand-written interface — the ADR 0021 guard scans for CLI-shaped
+ * member declarations). Direct spawns return the Subprocess itself; the win32
+ * relay below returns a delegating wrapper because its kill semantics differ
+ * (tree-kill). */
+type HostSshProcess = Pick<ReturnType<typeof Bun.spawn>, "pid" | "exitCode" | "stdout" | "stderr" | "kill">;
+
+/** Win32 Defender tax (2026-09-22 finding, ukp_remote TODO
+ * 20260922-win32-ssh-spawn-tax): the DIRECT bun-to-ssh.exe child edge is held
+ * ~10s by behavioral inspection — measured across stdio modes, windowsHide,
+ * and absolute paths, while bash-to-ssh is 0.16s and ANY intermediary parent
+ * (cmd, node, powershell) escapes to 0.5-0.8s. Every ssh spawn in this file
+ * pays it once, so on win32 real-ssh spawns go through a powershell.exe
+ * relay. -EncodedCommand carries the script as one base64 token (no quoting
+ * stress from Bun), and the script splats a PS array so the pinned wake
+ * command's load-bearing quotes reach ssh byte-identical (verified E2E: door
+ * READY in ~1.4s). Test injection (explicit sshCommand) bypasses the relay —
+ * the fakes must not be wrapped. Killing the relay orphans the ssh child
+ * (tunnel + door outlive the killed handle — verified), so the wrapped kill
+ * reaps the tree via taskkill /T /F. */
+function spawnHostSsh(options: { sshCommand?: readonly string[] }, argv: readonly string[]): HostSshProcess {
+  if (process.platform !== "win32" || options.sshCommand !== undefined) {
+    return Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+  }
+  const script = toolRelayScript(argv);
+  const encoded = Buffer.from(script, "utf16le").toString("base64");
+  const proc = Bun.spawn(["powershell", "-NoProfile", "-EncodedCommand", encoded], {
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+  const { pid, stdout, stderr } = proc;
+  return {
+    pid,
+    stdout,
+    stderr,
+    get exitCode() {
+      return proc.exitCode;
+    },
+    kill() {
+      // taskkill also carries the Defender tax when spawned directly from
+      // bun (measured 10.1s direct vs 105ms through cmd — same finding as
+      // the ssh/rg edges); the PID is digits-only, so the cmd payload needs
+      // no quoting. /T /F takes the relay AND its ssh child down together
+      // (killing the relay alone orphans the tunnel).
+      Bun.spawnSync(["cmd", "/d", "/c", `taskkill /PID ${pid} /T /F`], {
+        stdout: "ignore",
+        stderr: "ignore",
+        stdin: "ignore",
+      });
+    },
+  };
+}
+
 /** One cheap, language-independent roundtrip to learn the host shell family
  * BEFORE the first wake attempt (2026-09-20, liku 9.5 finding): cmd.exe
  * expands `%OS%` to `Windows_NT`; a POSIX shell echoes the literal token.
@@ -436,21 +556,32 @@ function persistShellFamily(cachePath: string | undefined, target: string, form:
  * build LOSES a quoted remote command under a pty (an interactive cmd
  * swallows it and waits on stdin forever — the no-pty path executes it
  * correctly). Defaults to POSIX (the common server shape) when the probe
- * errors or times out; the ladder remains as the backstop. */
+ * errors or times out; the ladder remains as the backstop.
+ *
+ * The probe doubles as the first failure classifier (ADR-REM-008 §3): its
+ * merged output — the `%OS%` answer on stdout, ssh's own diagnostics on
+ * stderr — feeds `classifyWakeFailure`, so instant verdicts (refused / auth
+ * / hostkey / resolve failures) classify here and the ladder is never
+ * entered for them. */
 async function probeHostShellFamily(
   options: { sshCommand?: readonly string[] },
   target: string,
-): Promise<WakeShellForm> {
-  const proc = Bun.spawn(
+): Promise<{ form: WakeShellForm; diagnostics: string }> {
+  const proc = spawnHostSsh(
+    options,
     [...(options.sshCommand ?? ["ssh"]), "-o", "BatchMode=yes", ...connectTimeoutOptions(), target, "echo %OS%"],
-    { stdout: "pipe", stderr: "pipe", stdin: "ignore" },
   );
-  const output = await Promise.race([
-    new Response(proc.stdout).text().catch(() => ""),
+  // One merged read of BOTH streams, raced against the 5s cap: resolves when
+  // the process dies (a healthy probe answers and exits), else returns empty
+  // at the cap and the default form stands — a slow host is never punished.
+  // A generous keep (review P3): the tail-trimmed merge must not push the
+  // stdout %OS% answer out the front even behind unusual stderr volume.
+  const text = await Promise.race([
+    drainStderrTail([proc.stdout, proc.stderr], 8192),
     Bun.sleep(5_000).then(() => ""),
   ]);
   proc.kill();
-  return /Windows_NT/i.test(output) ? "cmd" : "posix";
+  return { form: /Windows_NT/i.test(text) ? "cmd" : "posix", diagnostics: text };
 }
 
 /** HTTP-level readiness probe through the tunnel (W9): a TCP accept on the
@@ -463,7 +594,7 @@ async function probeHostShellFamily(
 async function probeWakeReady(
   base: string,
   timeoutMs: number,
-  proc: ReturnType<typeof Bun.spawn>,
+  proc: HostSshProcess,
 ): Promise<boolean> {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
@@ -499,9 +630,12 @@ async function probeWakeReady(
  * so diagnostics can arrive on either stream — both are drained and
  * concatenated. Resolves when the streams end (i.e. after the process is
  * dead) — only await once the proc has been killed or has exited. */
-function drainStderrTail(streams: readonly ReadableStream<Uint8Array>[], keep = 2000): Promise<string> {
+function drainStderrTail(
+  streams: readonly (ReadableStream<Uint8Array> | number | undefined)[],
+  keep = 2000,
+): Promise<string> {
   return Promise.all(
-    streams.map((stream) => new Response(stream).text().catch(() => "")),
+    streams.map((stream) => (typeof stream === "object" && stream !== null ? new Response(stream).text().catch(() => "") : "")),
   ).then((texts) => {
     const text = texts.join("").trim();
     return text.length > keep ? `...${text.slice(-keep)}` : text;
@@ -525,7 +659,7 @@ function drainStderrTail(streams: readonly ReadableStream<Uint8Array>[], keep =
 async function openSshTunnel(
   parts: { user?: string; host: string },
   options: { sshCommand?: readonly string[]; registryPath?: string },
-): Promise<{ proc: ReturnType<typeof Bun.spawn>; base: string }> {
+): Promise<{ proc: HostSshProcess; base: string }> {
   const target = parts.user !== undefined ? `${parts.user}@${parts.host}` : parts.host;
   // Tier 1 first: a detached mux master per origin (no-op when one already
   // holds the socket); the wake client below rides it when possible and
@@ -539,8 +673,25 @@ async function openSshTunnel(
   // Shell form (2026-09-20): probed up front via `echo %OS%` (language-
   // independent — see probeHostShellFamily), POSIX by default; the wrong-
   // shell ladder below remains the backstop for a lying or timed-out probe.
-  let form: WakeShellForm = readCachedShellFamily(shellFamilyCachePath(options), target)
-    ?? await probeHostShellFamily(options, target);
+  // Cold cache: the probe doubles as the first failure classifier
+  // (ADR-REM-008 §3) — its instant verdicts (refused / auth / hostkey /
+  // resolve failures) reject the origin here, before any ladder attempt;
+  // black-hole timeouts defer to the ladder's full ConnectTimeout budget.
+  // Warm cache (the probe is skipped): the ladder's first attempt carries
+  // the same classifier, so the classified verdicts cost at most one
+  // ConnectTimeout either way.
+  let form: WakeShellForm;
+  const cachedForm = readCachedShellFamily(shellFamilyCachePath(options), target);
+  if (cachedForm !== undefined) {
+    form = cachedForm;
+  } else {
+    const probed = await probeHostShellFamily(options, target);
+    const probeClass = classifyWakeFailure(probed.diagnostics);
+    if (probeClass !== undefined && !wakeFailureDefersToLadder(probeClass, probed.diagnostics)) {
+      throw new RemoteTransportError(wakeFailureMessage(probeClass, target, probed.diagnostics));
+    }
+    form = probed.form;
+  }
   const attempts = 3;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     const localPort = await freePort();
@@ -564,7 +715,7 @@ async function openSshTunnel(
       target,
       wakeDoorCommand(remotePort, form),
     ];
-    const proc = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+    const proc = spawnHostSsh(options, argv);
     const stderrTail = drainStderrTail([proc.stdout, proc.stderr]);
     if (await probeWakeReady(`http://127.0.0.1:${localPort}`, WAKE_READY_TIMEOUT_MS, proc)) {
       // Ground truth for the shell-family cache: the form that actually woke
@@ -579,6 +730,15 @@ async function openSshTunnel(
     // fast crash as a slow timeout.
     const diagnostics = (await stderrTail).trim();
     const exited = proc.exitCode !== null;
+    // Deterministic connect/auth verdicts never consume the ladder's
+    // remaining attempts (ADR-REM-008 §2): re-running against the same host
+    // reproduces them, so attempt 1's verdict IS the origin's verdict. The
+    // ladder stays for what it was built for — port-collision binds and
+    // not-ready timeouts.
+    const failureClass = exited ? classifyWakeFailure(diagnostics) : undefined;
+    if (failureClass !== undefined) {
+      throw new RemoteTransportError(wakeFailureMessage(failureClass, target, diagnostics));
+    }
     if (/ControlPath too long|muxserver_listen|unix_listener/i.test(diagnostics)) {
       muxDisabled = true;
     }
@@ -604,7 +764,7 @@ async function openSshTunnel(
       throw new RemoteTransportError(
         exited
           ? `waking the ukp door on '${target}' failed: ${diagnostics}`
-          : `the ukp door on '${target}' did not become ready within ${WAKE_READY_TIMEOUT_MS / 1000}s; check the host alias and key auth (BatchMode)`,
+          : wakeNotReadyMessage(target, WAKE_READY_TIMEOUT_MS),
       );
     }
   }
@@ -662,7 +822,7 @@ export interface RemoteTransportPool {
 export function createTransportPool(
   options: { sshCommand?: readonly string[]; registryPath?: string } = {},
 ): RemoteTransportPool {
-  const tunnels = new Map<string, Promise<{ proc: ReturnType<typeof Bun.spawn>; base: string }>>();
+  const tunnels = new Map<string, Promise<{ proc: HostSshProcess; base: string }>>();
   return {
     async acquire(binding) {
       if (binding.kind !== "remote" || binding.url === undefined) {
@@ -1168,10 +1328,23 @@ function remoteRgCounts(raw: unknown): RgCountEntry[] | undefined {
   });
 }
 
+function remoteRgFiles(raw: unknown): RgFileEntry[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  return raw.flatMap((entry): RgFileEntry[] => {
+    if (typeof entry !== "object" || entry === null) return [];
+    const file = entry as Record<string, unknown>;
+    if (typeof file.path !== "string") return [];
+    return [{ path: file.path, ...(typeof file.ukp_uri === "string" ? { ukp_uri: file.ukp_uri } : {}) }];
+  });
+}
+
 const RG_WIRE_STATUSES = new Set(["succeeded", "no_matches", "skipped", "failed", "interrupted", "cancelled"]);
 
 /** GET /v1/rg — single-endpoint outcome in the local RgEndpointOutcome
- * vocabulary (provider is rg's external tier regardless of transport). */
+ * vocabulary (provider is rg's external tier regardless of transport).
+ * Files mode (ADR-RG-005) sends files=1 and omits query — an older serve
+ * without files support answers its query-required usage error, which
+ * lands here as a failed outcome carrying the server's message. */
 export async function remoteRg(
   binding: RegistryBinding,
   transport: RemoteTransportHandle,
@@ -1179,16 +1352,19 @@ export async function remoteRg(
   params: {
     query: string;
     limit: number;
-    glob?: string;
+    globs?: readonly string[];
     type?: string;
     ignoreCase?: boolean;
     count?: boolean;
+    files?: boolean;
     passthrough: readonly string[];
   },
 ): Promise<RemoteRgExecution> {
   const base = transport.base;
-  const search = new URLSearchParams({ query: params.query, limit: String(params.limit) });
-  if (params.glob !== undefined) search.set("glob", params.glob);
+  const search = new URLSearchParams({ limit: String(params.limit) });
+  if (params.files === true) search.set("files", "1");
+  else search.set("query", params.query);
+  for (const glob of params.globs ?? []) search.append("glob", glob);
   if (params.type !== undefined) search.set("type", params.type);
   if (params.ignoreCase === true) search.set("i", "1");
   if (params.count === true) search.set("count", "1");
@@ -1223,6 +1399,9 @@ export async function remoteRg(
     match.ukp_uri !== undefined ? { ...match, ukp_uri: reanchorRemoteUkpUri(match.ukp_uri, binding) } : match,
   );
   const counts = remoteRgCounts(entry.counts);
+  const files = remoteRgFiles(entry.files)?.map((file) =>
+    file.ukp_uri !== undefined ? { ...file, ukp_uri: reanchorRemoteUkpUri(file.ukp_uri, binding) } : file,
+  );
   const warnings = Array.isArray(record.warnings) ? record.warnings.filter((item): item is string => typeof item === "string") : [];
   return {
     outcome: {
@@ -1232,6 +1411,7 @@ export async function remoteRg(
       ...(typeof entry.message === "string" ? { message: entry.message } : {}),
       ...(matches !== undefined ? { matches } : {}),
       ...(counts !== undefined ? { counts } : {}),
+      ...(files !== undefined ? { files } : {}),
       ...(entry.truncated === true ? { truncated: true } : {}),
     },
     warnings,

package/src/capabilities/rg.ts

@@ -6,6 +6,7 @@ import { resolveExternalToolCapability, EXTERNAL_PROVIDER } from "../config/exte
 import { localPathOf, readRegistry } from "../registry.ts";
 import { resolveScope } from "../scope.ts";
 import { isInsideRealRoot } from "../path-safety.ts";
+import { toolRelayArgv, TOOL_NOT_FOUND_EXIT } from "../spawn-relay.ts";
 
 // rg capability (ADR-RG-001..004): an independent atomic
 // capability parallel to `search` — base lexical search over the endpoint's
@@ -15,6 +16,8 @@ import { isInsideRealRoot } from "../path-safety.ts";
 // Structured outcome per ADR 0021 — never rendered text, never exit codes.
 
 export interface RgRequest {
+  /** Search pattern (match/count modes). Empty only in files mode, where
+   * the parse layer guarantees it was omitted (ADR-RG-005 mutual exclusion). */
   query: string;
   limit: number;
 }
@@ -22,10 +25,15 @@ export interface RgRequest {
 export interface RgOptions {
   explicitEndpoints?: string[];
   global: boolean;
-  glob?: string;
+  /** Ordered glob filters (repeatable top-level flag, ADR-RG-005: rg glob
+   * grammar lets a later glob negate with `!` — include+exclude combos). */
+  globs?: readonly string[];
   type?: string;
   ignoreCase?: boolean;
   count?: boolean;
+  /** Files enumeration mode (ADR-RG-005): true tree walk via `rg --files` —
+   * no content matching, so empty and binary files are visible. */
+  files?: boolean;
   /** Validated passthrough args (allowlist + scope protection, ADR-RG-002). */
   passthrough: readonly string[];
   /** Surface concern (propose precedent): the capability never consumes it —
@@ -72,6 +80,14 @@ export interface RgCountEntry {
   count: number;
 }
 
+/** One enumerated file (files mode, ADR-RG-005): endpoint-relative path plus
+ * the durable slot key under the same containment-gated emission rule as
+ * matches (ADR 0019 stance). */
+export interface RgFileEntry {
+  path: string;
+  ukp_uri?: string;
+}
+
 export interface RgEndpointOutcome {
   name: string;
   provider: typeof EXTERNAL_PROVIDER;
@@ -91,13 +107,20 @@ export interface RgEndpointOutcome {
   matches?: RgMatch[];
   /** Count mode results (`--count`). */
   counts?: RgCountEntry[];
+  /** Files mode results (`--files`, sorted then capped). */
+  files?: RgFileEntry[];
   /** True when matches were truncated at the request limit. */
   truncated?: boolean;
 }
 
+/** The run's output mode — drives tool argv, intake, and both presentation
+ * stages (envelope count_mode/files_mode and the human render branches). */
+export type RgMode = "match" | "count" | "files";
+
 export interface RgResult {
   query: string;
   limit: number;
+  mode: RgMode;
   endpoints: RgEndpointOutcome[];
   warnings: string[];
   aggregate: RgAggregateStatus;
@@ -118,6 +141,10 @@ export class RgPlanningError extends Error {
 }
 
 export const RG_DEFAULT_LIMIT = 50;
+/** Files-mode request limit default (ADR-RG-005): enumeration units are a
+ * single path line vs the 3-4 line match unit, so the same consumer-comfort
+ * calibration that set 50 for matches lands on 500 here. */
+export const RG_FILES_DEFAULT_LIMIT = 500;
 export const RG_MAX_LIMIT = 1000;
 
 export function defaultRgCommand(): readonly string[] {
@@ -125,10 +152,23 @@ export function defaultRgCommand(): readonly string[] {
 }
 
 /** Base-tool availability probe (diagnose / provider resolver): true when a
- * ripgrep executable starts. */
+ * ripgrep executable starts. Memoized per process — PATH does not change
+ * mid-process, and server startup (the door's ServeInfo carries this field)
+ * must not pay the probe again per start; the win32 relay costs ~0.8s where
+ * the direct spawn was Defender-taxed ~5s (2026-09-22 finding, see
+ * spawn-relay.ts). The relay's not-found guard exits TOOL_NOT_FOUND_EXIT,
+ * which no real ripgrep invocation produces (rg exits 0/1/2 only). */
+let rgAvailabilityMemo: boolean | undefined;
+
 export function rgExecutableAvailable(): boolean {
-  const result = spawnSync("rg", ["--version"], { encoding: "utf8", windowsHide: true, timeout: 5_000 });
-  return !result.error;
+  if (rgAvailabilityMemo === undefined) {
+    const probeArgv = process.platform === "win32"
+      ? toolRelayArgv(["rg", "--version"], { notFoundGuard: true })
+      : ["rg", "--version"];
+    const result = spawnSync(probeArgv[0]!, probeArgv.slice(1), { encoding: "utf8", windowsHide: true, timeout: 5_000 });
+    rgAvailabilityMemo = !result.error && result.status !== TOOL_NOT_FOUND_EXIT;
+  }
+  return rgAvailabilityMemo;
 }
 
 export function rgTimeoutMs(): number {
@@ -142,8 +182,9 @@ export function rgTimeoutMs(): number {
 // Passthrough validation (ADR-RG-002): allowlist + scope protection.
 // ---------------------------------------------------------------------------
 
-/** Value flags consume the next token (or an attached value: `-C2`). */
-const PASSTHROUGH_VALUE_FLAGS = new Set(["-A", "-B", "-C", "-m", "--max-count", "-g", "--glob", "-t", "--type", "--max-filesize"]);
+/** Value flags consume the next token (or an attached value: `-C2`). `--iglob`
+ * joined with ADR-RG-005 (case-insensitive glob variant, probe friction 2/8). */
+const PASSTHROUGH_VALUE_FLAGS = new Set(["-A", "-B", "-C", "-m", "--max-count", "-g", "--glob", "--iglob", "-t", "--type", "--max-filesize"]);
 const PASSTHROUGH_BOOL_FLAGS = new Set(["-i", "--ignore-case", "-S", "--smart-case", "-s", "--case-sensitive", "-w", "--word-regexp", "-F", "--fixed-strings", "-v", "--invert-match", "-U", "--multiline", "--no-ignore", "--hidden", "--no-messages", "--column", "--no-heading"]);
 
 /** Validates passthrough args: allowlist membership + scope protection.
@@ -234,13 +275,15 @@ function toUkpUri(endpointName: string, path: string): string {
  * provider-location mapping. A miss silently drops the `ukp_uri` field
  * (the match and its `path` stay): rg output is tool output, not user
  * error. Output-side filtering is the second line of defense; the
- * passthrough allowlist (no path operands) is the first. */
-function ukpUriIfInside(endpointFolder: string, endpointName: string, path: string): string | undefined {
+ * passthrough allowlist (no path operands) is the first. The folder's
+ * realpath is passed in pre-resolved (per endpoint, not per entry — review
+ * 2026-09-22: per-file resolution paid 2 realpaths/file on exactly the
+ * win32 Defender-taxed path); an unresolvable folder emits nothing. */
+function ukpUriIfInside(folderReal: string | undefined, endpointFolder: string, endpointName: string, path: string): string | undefined {
+  if (folderReal === undefined) return undefined;
   const absolute = resolve(endpointFolder, ...path.replace(/\\/g, "/").split("/"));
-  let folderReal: string;
   let targetReal: string;
   try {
-    folderReal = realpathSync(endpointFolder);
     targetReal = realpathSync(absolute);
   } catch {
     return undefined;
@@ -259,6 +302,16 @@ interface RgJsonEvent {
 }
 
 function rgToolArgs(parsed: ParsedRg): string[] {
+  if (parsed.options.files) {
+    // Files mode (ADR-RG-005): true tree walk — rg lists paths without
+    // reading content, so empty and binary files are visible. No `-e`:
+    // the parse layer guarantees no pattern rides along.
+    const args: string[] = ["--files", "--no-messages"];
+    for (const glob of parsed.options.globs ?? []) args.push("--glob", glob);
+    if (parsed.options.type !== undefined) args.push("--type", parsed.options.type);
+    args.push(...parsed.options.passthrough);
+    return args;
+  }
   const args: string[] = ["--no-heading", "--no-messages"];
   if (parsed.options.count) {
     args.push("--count");
@@ -266,7 +319,7 @@ function rgToolArgs(parsed: ParsedRg): string[] {
     args.push("--json");
   }
   if (parsed.options.ignoreCase) args.push("-i");
-  if (parsed.options.glob !== undefined) args.push("--glob", parsed.options.glob);
+  for (const glob of parsed.options.globs ?? []) args.push("--glob", glob);
   if (parsed.options.type !== undefined) args.push("--type", parsed.options.type);
   args.push(...parsed.options.passthrough);
   args.push("-e", parsed.request.query);
@@ -280,6 +333,7 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
   validateRgPassthrough(parsed.options.passthrough);
   const { plan, warnings } = planRg(parsed, context);
   const command = context.rgCommand ?? defaultRgCommand();
+  const mode: RgMode = parsed.options.files === true ? "files" : parsed.options.count === true ? "count" : "match";
   const endpoints: RgEndpointOutcome[] = [];
   let succeeded = false;
   let failed = false;
@@ -293,13 +347,36 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
       continue;
     }
 
+    // Lazy once-per-endpoint folder realpath for the uri emission rule: the
+    // folder cannot change mid-run, and a skip/fail path never pays for it.
+    // `null` marks "not attempted yet" vs `undefined` = "attempted, failed"
+    // (a failed resolution emits no uris without re-attempting per entry).
+    let endpointFolderReal: string | undefined | null = null;
+    const folderRealpath = (): string | undefined => {
+      if (endpointFolderReal === null) {
+        try {
+          endpointFolderReal = realpathSync(endpoint.folder);
+        } catch {
+          endpointFolderReal = undefined;
+        }
+      }
+      return endpointFolderReal;
+    };
+
     // Explicit search root: with no path operand rg searches stdin instead
     // of the cwd whenever stdin is not a tty (ISSUE-013 root cause,
     // confirmed on the ali repro host: spawned rg read an empty pipe and
     // exited 1 with zero traversal; tty and /dev/null stdin walk the cwd).
     // "." keeps rg's rendered paths endpoint-relative; the "./" prefix is
-    // stripped at both intakes below.
-    const result = spawnSync(command[0]!, [...command.slice(1), ...rgToolArgs(parsed), "."], {
+    // stripped at both intakes below. Win32: the real-tool invocation routes
+    // through the spawn relay (Defender taxes the direct bun-to-rg.exe edge
+    // ~5s — 2026-09-22 finding, see spawn-relay.ts); the injected test
+    // command is never wrapped, and the relay's not-found guard maps a
+    // missing rg onto the same skip path the spawn error always took.
+    const runArgv = process.platform === "win32" && context.rgCommand === undefined
+      ? toolRelayArgv([...command, ...rgToolArgs(parsed), "."], { notFoundGuard: true })
+      : [command[0]!, ...command.slice(1), ...rgToolArgs(parsed), "."];
+    const result = spawnSync(runArgv[0]!, runArgv.slice(1), {
       cwd: endpoint.folder,
       encoding: "utf8",
       windowsHide: true,
@@ -307,7 +384,7 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
       timeout: rgTimeoutMs(),
     });
 
-    if (result.error) {
+    if (result.error || result.status === TOOL_NOT_FOUND_EXIT) {
       // ADR-RG-003/R-7: a missing base tool is a degradation, not a fault —
       // skipped + warning, the run continues with other endpoints.
       warnings.push(`endpoint '${endpoint.name}' rg unavailable: rg executable is not available`);
@@ -340,6 +417,42 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
       continue;
     }
 
+    if (mode === "files") {
+      // Plain path-per-line intake. The full list is sorted BEFORE the
+      // client-side cap so truncation yields a deterministic window (the
+      // first N paths in lexicographic order, ADR-RG-005) rather than an
+      // arbitrary subset of rg's parallel-walk order.
+      const paths = (result.stdout ?? "")
+        .split(/\r?\n/)
+        .filter((line) => line.length > 0)
+        .map((line) => line.replace(/\\/g, "/").replace(/^\.\//, ""))
+        .sort();
+      const files: RgFileEntry[] = [];
+      let truncated = false;
+      for (const path of paths) {
+        if (files.length >= parsed.request.limit) {
+          truncated = true;
+          break;
+        }
+        const entry: RgFileEntry = { path };
+        const uri = ukpUriIfInside(folderRealpath(), endpoint.folder, endpoint.name, path);
+        if (uri !== undefined) entry.ukp_uri = uri;
+        files.push(entry);
+      }
+      if (files.length === 0 && !truncated) {
+        // An empty enumeration (empty folder or everything filtered out) is
+        // a successful result — same D-036 stance as a no-match search.
+        succeeded = true;
+        outcome.status = "no_matches";
+      } else {
+        succeeded = true;
+        outcome.status = "succeeded";
+        outcome.files = files;
+        if (truncated) outcome.truncated = true;
+      }
+      continue;
+    }
+
     if (parsed.options.count) {
       const counts: RgCountEntry[] = [];
       for (const line of (result.stdout ?? "").split(/\r?\n/)) {
@@ -386,7 +499,7 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
         const firstLine = text.split(/\r?\n/)[0] ?? "";
         if (firstLine.length > 0) entry.text = firstLine.length > 240 ? `${firstLine.slice(0, 240)}...` : firstLine;
       }
-      const uri = ukpUriIfInside(endpoint.folder, endpoint.name, entry.path);
+      const uri = ukpUriIfInside(folderRealpath(), endpoint.folder, endpoint.name, entry.path);
       if (uri !== undefined) entry.ukp_uri = uri;
       matches.push(entry);
     }
@@ -406,6 +519,7 @@ export function runRg(parsed: ParsedRg, context: RgContext): RgResult {
   return {
     query: parsed.request.query,
     limit: parsed.request.limit,
+    mode,
     endpoints,
     warnings,
     aggregate: interrupted
@@ -426,35 +540,41 @@ export interface RgEnvelope {
   schema: "ukp.rg.v1";
   command: "rg";
   capability: "rg";
-  query: string;
+  /** Omitted in files mode (ADR-RG-005): there is no pattern to echo. */
+  query?: string;
   limit: number;
   count_mode: boolean;
+  files_mode: boolean;
   endpoints: Array<{
     name: string;
     provider: string;
     status: string;
     match_count?: number;
+    file_count?: number;
     truncated?: boolean;
     message?: string;
     matches?: RgMatch[];
     counts?: RgCountEntry[];
+    files?: RgFileEntry[];
   }>;
   warnings: string[];
 }
 
-export function projectRgEnvelope(result: RgResult, countMode: boolean): RgEnvelope {
+export function projectRgEnvelope(result: RgResult): RgEnvelope {
   return {
     schema: "ukp.rg.v1",
     command: "rg",
     capability: "rg",
-    query: result.query,
+    ...(result.mode === "files" ? {} : { query: result.query }),
     limit: result.limit,
-    count_mode: countMode,
+    count_mode: result.mode === "count",
+    files_mode: result.mode === "files",
     endpoints: result.endpoints.map((endpoint) => ({
       name: endpoint.name,
       provider: endpoint.provider,
       status: endpoint.status ?? "failed",
       ...(endpoint.matches !== undefined ? { match_count: endpoint.matches.length, matches: endpoint.matches } : {}),
+      ...(endpoint.files !== undefined ? { file_count: endpoint.files.length, files: endpoint.files } : {}),
       ...(endpoint.counts !== undefined ? { counts: endpoint.counts } : {}),
       ...(endpoint.truncated !== undefined ? { truncated: endpoint.truncated } : {}),
       ...(endpoint.message !== undefined ? { message: endpoint.message } : {}),
@@ -480,7 +600,14 @@ export function renderRgHuman(result: RgResult): RgHumanView {
       continue;
     }
     if (endpoint.status === "no_matches") {
-      lines.push("(no matches)");
+      lines.push(result.mode === "files" ? "(no files)" : "(no matches)");
+      continue;
+    }
+    if (endpoint.files !== undefined) {
+      // Exhibit form (probe 20260922, zero misreads): one line per file,
+      // the durable uri when containment allows it, the raw path otherwise.
+      for (const file of endpoint.files) lines.push(file.ukp_uri ?? file.path);
+      if (endpoint.truncated) lines.push(`(truncated at the result limit ${result.limit}; raise --limit)`);
       continue;
     }
     if (endpoint.counts !== undefined) {

package/src/cli.ts

@@ -24,7 +24,7 @@ import { executeSearchCommand, SEARCH_SPEC } from "./commands/search.ts";
 export { renderSearchHelp } from "./commands/search.ts";
 export { renderDiagnoseHelp } from "./commands/diagnose.ts";
 export { renderReadHelp } from "./commands/read.ts";
-export { renderGuideHelp, renderServiceGuide, renderServiceQmdGuide, renderClientGuide, renderRemoteGuide, renderProposeGuide } from "./commands/guide.ts";
+export { renderGuideHelp, renderServiceGuide, renderServiceQmdGuide, renderClientGuide, renderRgGuide, renderRemoteGuide, renderProposeGuide } from "./commands/guide.ts";
 export { renderInitHelp, renderInitServiceHelp } from "./commands/init.ts";
 export { renderInspectHelp } from "./commands/inspect.ts";
 export { renderUpdateHelp } from "./commands/update.ts";

package/src/commands/guide-content/remote.txt

@@ -12,6 +12,8 @@ Current model:
 Owner path over SSH (zero ceremony - nothing to start on the host):
 1. Prerequisites (once): the host accepts your SSH key and has ukp installed the usual way
    ssh <host> ukp --help
+   Peek at the door before importing: ssh <host> ukp list shows the endpoint
+   names and capabilities the host declares
 
 2. On the consuming machine, import the door (the first call wakes it)
    ukp register --url ssh://<host>
@@ -45,7 +47,7 @@ Use this when you deliberately want to expose only one endpoint instead of the w
    ukp register --url https://<ip>:8570 --endpoint <name> --token <token>
 
 Name and identity:
-- register --url fetches /.well-known/ukp.json and registers the declared name under a local handle (--name <handle> chooses another, e.g. when the name is taken).
+- register --url fetches /.well-known/ukp.json and registers the declared name under a local handle (--name <handle> chooses another, e.g. when the name is taken). That document is public - curl it before registering to preview the endpoint names and capabilities the door declares (self-signed doors: curl -k).
 - --endpoint <name> on register asserts the expected name; if discovery declares a different name, registration fails.
 - A host door can import everything, --select a comma-separated subset, or --endpoint exactly one endpoint.
 - Self-signed HTTPS certificates are pinned on first registration; compare the pinned fingerprint with the serve banner on untrusted networks.

package/src/commands/guide-content/rg.txt

@@ -0,0 +1,35 @@
+UKP rg quickstart
+
+Goal: search or enumerate a Service's own files with ripgrep - no index, no declaration, real-time.
+
+Model:
+- rg is the lexical baseline: it scans files at call time, so it works on every registered endpoint. 'ukp search' is the indexed path and needs the Service to declare a provider.
+- Output is ukp:// references that 'ukp read' consumes directly.
+- Three modes: match (default), --count (per-file totals), --files (enumeration).
+
+1. Search
+   ukp rg --endpoint <name> "pattern"
+   -i is case-insensitive; --glob narrows by name; --limit raises the cap (default 50 matches).
+
+2. Enumerate files (no pattern)
+   ukp rg --endpoint <name> --files
+   A true tree walk, not a content match: empty and binary files are listed too.
+   Narrow by name with --glob, by kind with --type. Output is sorted; the
+   cap defaults to 500 (--limit to change).
+
+3. Glob semantics
+   --glob follows ripgrep/gitignore rules: a glob without "/" matches the
+   file name at any depth ("*.md"); a glob containing "/" anchors to the
+   endpoint-relative path ("docs/*"). Matching is case-sensitive; pass
+   -- --iglob "<glob>" after '--' for a case-insensitive variant.
+   --glob repeats: a leading "!" excludes, so "*.md" plus "!docs/*" is
+   markdown outside docs/.
+
+4. Visibility (every rg mode)
+   Hidden files (dot-prefixed, including the .ukp/ wiring) are skipped by
+   default. Add -- --hidden after '--' to include them; -uu also lifts
+   .gitignore rules. 'ukp read' can address hidden files directly either way.
+
+Remember:
+- Exact flags and the passthrough allowlist live in 'ukp rg --help'.
+- Remote endpoints behave the same: one command drives local and door-registered endpoints alike.

package/src/commands/guide.ts

@@ -20,10 +20,11 @@ const GUIDE_CONTENT_URL = new URL("./guide-content/", import.meta.url);
  * `ukp guide --help` render the same summaries (blank-agent sweep 2026-09-11:
  * the inversion of root help describing guides better than guide's own help
  * was a confirmed doc-gap). */
-export const GUIDE_TOPICS: ReadonlyArray<readonly [topic: string, summary: string]> = [
+export const GUIDE_TOPICS: ReadonlyArray<readonly [string, string]> = [
   ["service", "first Service setup with provider-free nav/read/rg baseline"],
   ["service qmd", "provider setup for the default QMD provider"],
   ["client", "use registered Services by default from a workspace; set your default scope here"],
+  ["rg", "lexical search and file enumeration: modes, glob semantics, visibility tiers"],
   ["remote", "serve and consume remote endpoints with a host door, ssh, or TLS"],
   ["propose", "submit idempotent change proposals to a Service"],
 ];
@@ -38,7 +39,7 @@ export const GUIDE_SPEC: UkpCommandSpec = {
   description: "Show short operational guides.",
   usage: "<topic> [subtopic]",
   arguments: [
-    { name: "topic", required: true, help: "guide topic: service | service qmd | client | remote | propose" },
+    { name: "topic", required: true, help: "guide topic: service | service qmd | client | rg | remote | propose" },
     { name: "subtopic", help: "provider subtopic for a topic, e.g. 'qmd' as in 'ukp guide service qmd'" },
   ],
   strictArguments: true,
@@ -72,17 +73,19 @@ export function executeGuideCommand(args: readonly string[]): GuideCommandResult
       return { exitCode: 0, stdout: renderServiceGuide(), stderr: "" };
     }
     if (subtopic) {
-      throw new KitUsageError(`unknown guide topic '${topic} ${subtopic}'. Available topics: service, service qmd, client, remote, propose`);
+      throw new KitUsageError(`unknown guide topic '${topic} ${subtopic}'. Available topics: service, service qmd, client, rg, remote, propose`);
     }
     switch (topic) {
       case "client":
         return { exitCode: 0, stdout: renderClientGuide(), stderr: "" };
+      case "rg":
+        return { exitCode: 0, stdout: renderRgGuide(), stderr: "" };
       case "remote":
         return { exitCode: 0, stdout: renderRemoteGuide(), stderr: "" };
       case "propose":
         return { exitCode: 0, stdout: renderProposeGuide(), stderr: "" };
       default:
-        throw new KitUsageError(`unknown guide topic '${topic}'. Available topics: service, service qmd, client, remote, propose`);
+        throw new KitUsageError(`unknown guide topic '${topic}'. Available topics: service, service qmd, client, rg, remote, propose`);
     }
   } catch (error) {
     if (error instanceof HelpRequestError) {
@@ -115,6 +118,10 @@ export function renderClientGuide(): string {
   return readGuideContent("client.txt");
 }
 
+export function renderRgGuide(): string {
+  return readGuideContent("rg.txt");
+}
+
 export function renderRemoteGuide(): string {
   return readGuideContent("remote.txt");
 }

package/src/commands/rg.ts

@@ -3,6 +3,7 @@ import {
   projectRgEnvelope,
   renderRgHuman,
   RG_DEFAULT_LIMIT,
+  RG_FILES_DEFAULT_LIMIT,
   RG_MAX_LIMIT,
   RgPlanningError,
   RgUsageError,
@@ -11,6 +12,7 @@ import {
   type RgAggregateStatus,
   type RgContext,
   type RgEndpointOutcome,
+  type RgMode,
   type RgResult,
 } from "../capabilities/rg.ts";
 import { EXTERNAL_PROVIDER } from "../config/external-tool.ts";
@@ -50,17 +52,19 @@ export const RG_SPEC: UkpCommandSpec = {
   summary: "grep raw endpoint files with ripgrep (no index or declaration needed; results as ukp:// references)",
   group: "endpoint",
   description:
-    "Run base lexical search (ripgrep) across one or more Service endpoints. "
+    "Run base lexical search (ripgrep) across one or more Service endpoints, "
+    + "or enumerate their files with --files. "
     + "Available on every registered endpoint by default; results are shaped into ukp:// references that 'ukp read' consumes directly. "
     + "For indexed/semantic search use 'ukp search'.",
-  usage: "[--endpoint <name> ... | -g] <pattern> [--limit <1-1000>] [--count] [--glob <glob>] [--type <type>] [-i] [-- <rg flags>]",
-  arguments: [{ name: "pattern", help: "one non-empty regex pattern; quote to escape the shell" }],
+  usage: "[--endpoint <name> ... | -g] (<pattern> | --files) [--limit <1-1000>] [--count] [--glob <glob> ...] [--type <type>] [-i] [-- <rg flags>]",
+  arguments: [{ name: "pattern", help: "one non-empty regex pattern; quote to escape the shell (omit with --files)" }],
   options: [
     { flags: "-c, --endpoint <name>", help: "select one endpoint; repeat to select multiple endpoints", multi: true },
     { flags: "-g", help: "search every endpoint in the Host Registry; takes no value" },
-    { flags: "--limit <1-1000>", help: `maximum matches per run (default: ${RG_DEFAULT_LIMIT})` },
+    { flags: "--limit <1-1000>", help: `maximum results per run (default: ${RG_DEFAULT_LIMIT}; ${RG_FILES_DEFAULT_LIMIT} with --files)` },
     { flags: "--count", help: "count mode: per-file match counts instead of matches" },
-    { flags: "--glob <glob>", help: "glob filter passed to rg (e.g. \"*.md\")" },
+    { flags: "--files", help: "files mode: enumerate files by tree walk with no pattern (empty and binary files included; combine with --glob/--type)" },
+    { flags: "--glob <glob>", help: "glob filter passed to rg (e.g. \"*.md\"); repeat to combine - a later glob may negate with !", multi: true },
     { flags: "--type <type>", help: "file type filter passed to rg (e.g. md, py)" },
     { flags: "-i", help: "case-insensitive search" },
     { flags: "--json", help: "emit the structured response envelope" },
@@ -69,7 +73,8 @@ export const RG_SPEC: UkpCommandSpec = {
     "",
     "Passthrough:",
     "  After '--', rg native flags are passed through on an allowlist",
-    "  (-A/-B/-C/-m/--glob/--type/--max-filesize and common boolean flags).",
+    "  (-A/-B/-C/-m/--glob/--iglob/--type/--max-filesize and common boolean",
+    "  flags).",
     "  Path operands and output-changing flags (--json, -r, --pre, --config)",
     "  are rejected: the endpoint selector owns scope, UKP owns the output.",
     "",
@@ -84,6 +89,12 @@ export const RG_SPEC: UkpCommandSpec = {
     "  'ukp search' covers indexed search where the Service declares a search",
     "  capability provider.",
     "",
+    "Visibility:",
+    "  Every rg mode skips hidden files (dot-prefixed, including the .ukp/",
+    "  wiring) by default; pass -- --hidden after '--' to include them",
+    "  (-uu additionally lifts .gitignore rules). --files lists every",
+    "  non-hidden file, including empty and binary ones.",
+    "",
   ].join("\n"),
 };
 
@@ -92,7 +103,8 @@ interface RgCommandOptions extends Record<string, unknown> {
   g?: boolean;
   limit?: string;
   count?: boolean;
-  glob?: string;
+  files?: boolean;
+  glob?: string[];
   type?: string;
   i?: boolean;
   json?: boolean;
@@ -102,10 +114,13 @@ export function parseRgArgs(args: readonly string[]): ParsedRg {
   const parsed = parseKitArgs<RgCommandOptions>(RG_SPEC, args);
   const explicit: string[] = [];
   const warnings: string[] = [];
+  const files = parsed.options.files === true;
 
   // Command-side semantic checks, in the pre-kit order: limit validation,
-  // duplicate warnings, excess positional, emptiness, conflict.
-  let limit = RG_DEFAULT_LIMIT;
+  // duplicate warnings, excess positional, mode conflicts, pattern rule,
+  // scope conflict. Files mode (ADR-RG-005) relaxes the pattern requirement
+  // and rejects combinations that would silently no-op.
+  let limit = files ? RG_FILES_DEFAULT_LIMIT : RG_DEFAULT_LIMIT;
   if (parsed.options.limit !== undefined) {
     if (!/^[0-9]+$/.test(parsed.options.limit)) throw new KitUsageError("--limit must be a decimal integer");
     limit = Number(parsed.options.limit);
@@ -125,20 +140,34 @@ export function parseRgArgs(args: readonly string[]): ParsedRg {
       `unexpected argument '${unexpected}'; rg accepts exactly one pattern. Use '--endpoint <name>' to select an endpoint; '-g' takes no value.`,
     );
   }
-  if (pattern === undefined || pattern.length === 0) throw new KitUsageError("rg pattern must be non-empty");
+  if (files && parsed.options.count === true) {
+    throw new KitUsageError("--files and --count cannot be used together (pick one output mode)");
+  }
+  if (files && parsed.options.i === true) {
+    throw new KitUsageError("--files cannot be combined with -i: there is no pattern to match; pass '-- --iglob <glob>' for a case-insensitive glob filter");
+  }
+  if (files) {
+    if (pattern !== undefined) {
+      throw new KitUsageError(`unexpected argument '${pattern}'; --files takes no pattern - use --glob to filter by name`);
+    }
+  } else if (pattern === undefined || pattern.length === 0) {
+    throw new KitUsageError("rg pattern must be non-empty (or pass --files to enumerate files without a pattern)");
+  }
   if (parsed.options.g && explicit.length > 0) {
     throw new KitUsageError("--endpoint and -g cannot be used together");
   }
 
+  const globs = parsed.options.glob ?? [];
   return {
-    request: { query: pattern, limit },
+    request: { query: files ? "" : pattern!, limit },
     options: {
       explicitEndpoints: explicit.length > 0 ? explicit : undefined,
       global: parsed.options.g ?? false,
-      ...(parsed.options.glob === undefined ? {} : { glob: parsed.options.glob }),
+      ...(globs.length > 0 ? { globs } : {}),
       ...(parsed.options.type === undefined ? {} : { type: parsed.options.type }),
       ...(parsed.options.i === true ? { ignoreCase: true } : {}),
       ...(parsed.options.count === true ? { count: true } : {}),
+      ...(files ? { files: true } : {}),
       ...(parsed.options.json === true ? { json: true } : {}),
       passthrough: [],
     },
@@ -238,7 +267,7 @@ function renderRgCommandResult(parsed: ParsedRg, result: RgResult): RgCommandRes
   if (parsed.options.json === true) {
     return {
       exitCode: RG_EXIT_BY_AGGREGATE[result.aggregate],
-      stdout: `${JSON.stringify(projectRgEnvelope(result, parsed.options.count === true), null, 2)}\n`,
+      stdout: `${JSON.stringify(projectRgEnvelope(result), null, 2)}\n`,
       stderr: view.diagnostics,
     };
   }
@@ -305,10 +334,11 @@ async function executeMixedRg(
         const execution = await remoteRg(binding, transport, token, {
           query: parsed.request.query,
           limit: parsed.request.limit,
-          ...(parsed.options.glob !== undefined ? { glob: parsed.options.glob } : {}),
+          ...(parsed.options.globs !== undefined ? { globs: parsed.options.globs } : {}),
           ...(parsed.options.type !== undefined ? { type: parsed.options.type } : {}),
           ...(parsed.options.ignoreCase === true ? { ignoreCase: true } : {}),
           ...(parsed.options.count === true ? { count: true } : {}),
+          ...(parsed.options.files === true ? { files: true } : {}),
           passthrough: parsed.options.passthrough,
         });
         remoteOutcomes.set(binding.name, execution.outcome);
@@ -343,6 +373,7 @@ async function executeMixedRg(
   return renderRgCommandResult(parsed, {
     query: parsed.request.query,
     limit: parsed.request.limit,
+    mode: (parsed.options.files === true ? "files" : parsed.options.count === true ? "count" : "match") as RgMode,
     endpoints,
     warnings,
     aggregate,

package/src/server.ts

@@ -33,6 +33,7 @@ import {
   runRg,
   projectRgEnvelope,
   RG_DEFAULT_LIMIT,
+  RG_FILES_DEFAULT_LIMIT,
   RG_MAX_LIMIT,
   validateRgPassthrough,
   RgUsageError,
@@ -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: [],
@@ -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"),
+  ];
+}