@catheadowl/ukp 0.2.3 → 0.2.5

package/src/capabilities/remote-client.ts

@@ -1,6 +1,9 @@
 import { isIP } from "node:net";
 import { connect as tlsConnect } from "node:tls";
 import { X509Certificate } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import {
   DISCOVERY_PATH,
   PROTOCOL_NAME,
@@ -16,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
@@ -54,6 +58,25 @@ function remoteTimeoutMs(): number {
   return Number.isSafeInteger(value) && value >= 1000 ? value : 60_000;
 }
 
+/** Connection-establishment bound (ADR 0026 rule 2 / D-091): every ssh
+ * process UKP spawns carries ConnectTimeout, so an unreachable host fails
+ * in seconds instead of waiting out the OS TCP timeout — which then
+ * multiplied through the wake ladder's attempts and the serial origin
+ * chain. Default 10s (the Ansible baseline); `UKP_SSH_CONNECT_TIMEOUT_MS`
+ * overrides, mirroring UKP_REMOTE_TIMEOUT_MS. ssh takes whole seconds, so
+ * an integer ms value ≥1000 floors (1500 → 1s); anything else — non-numeric,
+ * fractional, below 1000 — keeps the default. */
+function sshConnectTimeoutSeconds(): number {
+  const raw = process.env.UKP_SSH_CONNECT_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === "") return 10;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value >= 1000 ? Math.floor(value / 1000) : 10;
+}
+
+function connectTimeoutOptions(): string[] {
+  return ["-o", `ConnectTimeout=${sshConnectTimeoutSeconds()}`];
+}
+
 /** TOFU mismatch policy (RQ-17): `warn` (default) appends a warning and
  * continues; `block` refuses the endpoint until it is explicitly
  * re-registered. */
@@ -64,6 +87,11 @@ function tofuMode(): "warn" | "block" {
 export interface RemoteTransportHandle {
   /** Wire base the client actually fetches (tunnel endpoint or the url itself). */
   base: string;
+  /** The url the caller knows — the registered binding url. Error and remedy
+   * text quotes THIS, never the wire base: a door-endpoint binding's wire
+   * base carries the `/e/<name>` route prefix (and, over ssh, a loopback
+   * tunnel port) that no user ever typed or could act on. */
+  displayUrl: string;
   /** Releases per-invocation resources (kills an ephemeral tunnel); noop for
    * direct connections. */
   close: () => void;
@@ -178,12 +206,13 @@ function tlsAnchorOf(binding: RegistryBinding, options: { registryPath?: string
 }
 
 function directTransportHandle(
-  binding: RegistryBinding,
+  binding: RegistryBinding & { url: string },
   parts: RemoteUrlParts,
   options: { registryPath?: string },
 ): RemoteTransportHandle {
   return {
     base: parts.origin + wirePrefix(parts.endpointName),
+    displayUrl: binding.url,
     close: () => {},
     ...(tlsAnchorOf(binding, options) !== undefined ? { tls: tlsAnchorOf(binding, options)! } : {}),
   };
@@ -276,6 +305,7 @@ function spawnMuxMaster(
     ...(sshCommand ?? ["ssh"]),
     "-N",
     "-o", "BatchMode=yes",
+    ...connectTimeoutOptions(),
     ...muxCandidateOptions(),
     target,
   ];
@@ -352,6 +382,170 @@ 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
+ * win32 (no ControlMaster) a full TCP+key handshake. Cached beside the
+ * registry (`<registry dir>/wake-shell.toml`, keyed by ssh target), the
+ * probe is skipped when an entry exists. The wake ladder stays the
+ * backstop: a stale entry (host reinstalled under a different shell) costs
+ * one wrong-shell retry, and the successful form is written back — the
+ * cache can only lose time, never correctness. Best-effort by design:
+ * missing/corrupt/unwritable ⇒ re-probe or run uncached. */
+function shellFamilyCachePath(options: { registryPath?: string }): string | undefined {
+  return options.registryPath === undefined ? undefined : join(dirname(options.registryPath), "wake-shell.toml");
+}
+
+function readCachedShellFamily(cachePath: string | undefined, target: string): WakeShellForm | undefined {
+  if (cachePath === undefined) return undefined;
+  try {
+    const parsed = parseToml(readFileSync(cachePath, "utf8")) as { shells?: Record<string, unknown> };
+    const value = parsed.shells?.[target];
+    return value === "posix" || value === "cmd" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function persistShellFamily(cachePath: string | undefined, target: string, form: WakeShellForm): void {
+  if (cachePath === undefined) return;
+  try {
+    let shells: Record<string, unknown> = {};
+    try {
+      const parsed = parseToml(readFileSync(cachePath, "utf8")) as { shells?: Record<string, unknown> };
+      if (parsed.shells !== undefined && typeof parsed.shells === "object") shells = parsed.shells;
+    } catch {
+      // corrupt or absent: a fresh map replaces whatever was there
+    }
+    // Unchanged value: no write — a per-origin-per-invocation rewrite would
+    // only amplify disk churn and widen the concurrent-writer window.
+    if (shells[target] === form) return;
+    shells[target] = form;
+    writeFileSync(cachePath, stringifyToml({ shells }), { mode: 0o600 });
+  } catch {
+    // unwritable (read-only dir, concurrent writer): run without cache
+  }
+}
+
+/** 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.
@@ -362,21 +556,32 @@ function wrongShellSignature(form: WakeShellForm, diagnostics: string): boolean
  * 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(
-    [...(options.sshCommand ?? ["ssh"]), "-o", "BatchMode=yes", target, "echo %OS%"],
-    { stdout: "pipe", stderr: "pipe", stdin: "ignore" },
+): Promise<{ form: WakeShellForm; diagnostics: string }> {
+  const proc = spawnHostSsh(
+    options,
+    [...(options.sshCommand ?? ["ssh"]), "-o", "BatchMode=yes", ...connectTimeoutOptions(), target, "echo %OS%"],
   );
-  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
@@ -389,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 (;;) {
@@ -425,12 +630,15 @@ 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;
+    return text.length > keep ? `...${text.slice(-keep)}` : text;
   });
 }
 
@@ -441,12 +649,17 @@ function drainStderrTail(streams: readonly ReadableStream<Uint8Array>[], keep =
  * abrupt-disconnect orphan). Encryption + host/user auth come from the user's
  * SSH config/keys. `sshCommand` is a test injection point for the ssh binary.
  * Bounded retries absorb a client-chosen remote port colliding with an
- * in-use one (the door fails to bind and the command exits). */
+ * in-use one (the door fails to bind and the command exits).
+ *
+ * Failure messages name the TARGET (an origin-level fact), never an endpoint
+ * label: under fan-out (ADR 0026 rule 1) every same-origin binding shares
+ * this one ladder and its one rejection — the per-endpoint identity belongs
+ * to the caller's row warning ("endpoint '<name>' capabilities unavailable:
+ * …"), which each row supplies itself. */
 async function openSshTunnel(
   parts: { user?: string; host: string },
-  options: { sshCommand?: readonly string[] },
-  endpointLabel: string,
-): Promise<{ proc: ReturnType<typeof Bun.spawn>; base: string }> {
+  options: { sshCommand?: readonly string[]; registryPath?: 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
@@ -460,7 +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 = 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();
@@ -478,14 +709,19 @@ async function openSshTunnel(
       ...(form === "posix" ? ["-tt"] : []),
       "-o", "ExitOnForwardFailure=yes",
       "-o", "BatchMode=yes",
+      ...connectTimeoutOptions(),
       ...(muxDisabled ? [] : muxClientOptions()),
       "-L", `127.0.0.1:${localPort}:127.0.0.1:${remotePort}`,
       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
+      // the door — a probe's first guess, or the ladder's flip past a stale
+      // cache entry, both converge here.
+      persistShellFamily(shellFamilyCachePath(options), target, form);
       return { proc, base: `http://127.0.0.1:${localPort}` };
     }
     proc.kill();
@@ -494,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;
     }
@@ -505,21 +750,21 @@ async function openSshTunnel(
       // Both forms rejected: this is a shell mismatch, not a missing-ukp
       // failure — say so instead of falling into the missing-ukp wording.
       throw new RemoteTransportError(
-        `waking the ukp door on '${target}' (endpoint '${endpointLabel}') failed — the remote shell rejected both wake command forms (POSIX and cmd.exe): ${diagnostics}. Supported host shells: POSIX login shells, cmd.exe default, Git-Bash-style DefaultShell; a powershell DefaultShell is not supported`,
+        `waking the ukp door on '${target}' failed - the remote shell rejected both wake command forms (POSIX and cmd.exe): ${diagnostics}. Supported host shells: POSIX login shells, cmd.exe default, Git-Bash-style DefaultShell; a powershell DefaultShell is not supported`,
       );
     }
     // POSIX login shells print "…: ukp: command not found" (exit 127); Windows
     // OpenSSH under cmd prints "'ukp' is not recognized…" (exit 9009).
     if (exited && /not found|not recognized|exit status 127|status 9009/i.test(diagnostics)) {
       throw new RemoteTransportError(
-        `waking the ukp door on '${target}' (endpoint '${endpointLabel}') failed — the remote shell cannot find 'ukp': ${diagnostics}. Host prerequisite (W9): ssh reachable AND ukp on the remote PATH`,
+        `waking the ukp door on '${target}' failed - the remote shell cannot find 'ukp': ${diagnostics}. Host prerequisite (W9): ssh reachable AND ukp on the remote PATH`,
       );
     }
     if (attempt === attempts) {
       throw new RemoteTransportError(
         exited
-          ? `waking the ukp door on '${target}' (endpoint '${endpointLabel}') failed: ${diagnostics}`
-          : `the ukp door on '${target}' (endpoint '${endpointLabel}') did not become ready within ${WAKE_READY_TIMEOUT_MS / 1000}s; check the host alias and key auth (BatchMode)`,
+          ? `waking the ukp door on '${target}' failed: ${diagnostics}`
+          : wakeNotReadyMessage(target, WAKE_READY_TIMEOUT_MS),
       );
     }
   }
@@ -550,11 +795,12 @@ export async function openRemoteTransport(
     throw new RemoteTransportError(`remote endpoint url is not admissible: ${binding.url}`);
   }
   if (parts.scheme !== "ssh") {
-    return directTransportHandle(binding, parts, options);
+    return directTransportHandle({ ...binding, url: binding.url }, parts, options);
   }
-  const tunnel = await openSshTunnel(parts, options, binding.name);
+  const tunnel = await openSshTunnel(parts, options);
   return {
     base: tunnel.base + wirePrefix(parts.endpointName),
+    displayUrl: binding.url,
     close: () => tunnel.proc.kill(),
   };
 }
@@ -576,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) {
@@ -588,13 +834,13 @@ export function createTransportPool(
         throw new RemoteTransportError(`remote endpoint url is not admissible: ${binding.url}`);
       }
       if (parts.scheme !== "ssh") {
-        return directTransportHandle(binding, parts, options);
+        return directTransportHandle({ ...binding, url: binding.url }, parts, options);
       }
       let tunnel = tunnels.get(parts.origin);
       if (tunnel === undefined) {
         // Drop the entry on failure so a retry inside the same invocation
         // spawns fresh instead of re-throwing a stale rejected promise.
-        tunnel = openSshTunnel(parts, options, binding.name).catch((error: unknown) => {
+        tunnel = openSshTunnel(parts, options).catch((error: unknown) => {
           tunnels.delete(parts.origin);
           throw error;
         });
@@ -603,6 +849,7 @@ export function createTransportPool(
       const acquired = await tunnel;
       return {
         base: acquired.base + wirePrefix(parts.endpointName),
+        displayUrl: binding.url,
         close: () => {},
       };
     },
@@ -621,11 +868,11 @@ function isTimeoutError(error: unknown): boolean {
   return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
 }
 
-function unreachableError(url: string, error: unknown): RemoteTransportError {
+function unreachableError(displayUrl: string, error: unknown): RemoteTransportError {
   const code = (error as { code?: unknown }).code;
   const detail = error instanceof Error ? error.message : String(error);
   return new RemoteTransportError(
-    `remote endpoint unreachable: ${url} (${detail}${typeof code === "string" && code !== "" ? ` [${code}]` : ""})`,
+    `remote endpoint unreachable: ${displayUrl} (${detail}${typeof code === "string" && code !== "" ? ` [${code}]` : ""})`,
   );
 }
 
@@ -640,7 +887,7 @@ async function reanchorFromProbe(url: string, anchor: RemoteTlsAnchor): Promise<
   if (probe === undefined) return false;
   if (anchor.pin !== undefined && probe.spkiPin !== anchor.pin) {
     throw new RemoteTransportError(
-      `remote '${anchor.name ?? "endpoint"}' TLS identity changed — pinned ${anchor.pin}, got ${probe.spkiPin}; if the server was reinstalled this is expected: refresh trust with 'ukp register --url <url> --token <token>'`,
+      `remote '${anchor.name ?? "endpoint"}' TLS identity changed - pinned ${anchor.pin}, got ${probe.spkiPin}; if the server was reinstalled this is expected: refresh trust with 'ukp register --url <url> --token <token>'`,
     );
   }
   anchor.ca = probe.certPem;
@@ -657,12 +904,16 @@ async function reanchorFromProbe(url: string, anchor: RemoteTlsAnchor): Promise<
 
 /** Fetch + JSON-decode with one transparent renewal re-anchor: a pinned
  * https anchor turns a certificate-verification fetch failure into a probe —
- * same SPKI keeps going (anchor swapped in place), a different SPKI blocks. */
+ * same SPKI keeps going (anchor swapped in place), a different SPKI blocks.
+ * `displayUrl` (the url the caller knows) replaces the wire url in error
+ * text; without one the wire url itself is the best available label. */
 async function fetchJson(
   url: string,
   init: RequestInit,
   anchor?: RemoteTlsAnchor,
+  displayUrl?: string,
 ): Promise<{ status: number; body: unknown }> {
+  const label = displayUrl ?? url;
   const attempt = async (ca?: string, wrap = true): Promise<{ status: number; body: unknown }> => {
     let response: Response;
     try {
@@ -675,13 +926,13 @@ async function fetchJson(
       // wrap=false keeps the raw error so the anchored caller can classify
       // it (TLS verification failure → re-anchor probe) before wrapping.
       if (!wrap) throw error;
-      throw unreachableError(url, error);
+      throw unreachableError(label, error);
     }
     let body: unknown;
     try {
       body = await response.json();
     } catch {
-      throw new RemoteTransportError(`remote endpoint returned a non-JSON body (status ${response.status}): ${url}`);
+      throw new RemoteTransportError(`remote endpoint returned a non-JSON body (status ${response.status}): ${label}`);
     }
     return { status: response.status, body };
   };
@@ -691,17 +942,17 @@ async function fetchJson(
     return await attempt(anchor.ca, false);
   } catch (error) {
     if (error instanceof RemoteTransportError) throw error; // non-JSON body: not a TLS event
-    if (isTimeoutError(error)) throw unreachableError(url, error);
+    if (isTimeoutError(error)) throw unreachableError(label, error);
     // Re-anchoring needs a pinned identity: only the SPKI pin distinguishes
     // "renewed certificate, same key" from "different identity".
     if (anchor.pin !== undefined && await reanchorFromProbe(url, anchor)) return await attempt(anchor.ca);
-    throw unreachableError(url, error);
+    throw unreachableError(label, error);
   }
 }
 
-function asRecord(body: unknown, url: string): Record<string, unknown> {
+function asRecord(body: unknown, displayUrl: string): Record<string, unknown> {
   if (typeof body !== "object" || body === null || Array.isArray(body)) {
-    throw new RemoteTransportError(`remote endpoint returned an unexpected payload shape: ${url}`);
+    throw new RemoteTransportError(`remote endpoint returned an unexpected payload shape: ${displayUrl}`);
   }
   return body as Record<string, unknown>;
 }
@@ -720,6 +971,7 @@ export async function fetchDiscoveryDocument(
   token?: string,
 ): Promise<DiscoveryFetch> {
   return fetchDiscoveryDocumentAt(transport.base, {
+    displayUrl: transport.displayUrl,
     name: binding.name,
     ...(binding.instance_uid !== undefined ? { pinnedUid: binding.instance_uid } : {}),
     ...(token !== undefined ? { token } : {}),
@@ -734,16 +986,17 @@ export async function fetchDiscoveryDocument(
  * (ADR-REM-004 / O-1). */
 async function fetchWellKnownRecord(
   base: string,
-  options: { token?: string; tlsAnchor?: RemoteTlsAnchor },
+  options: { token?: string; tlsAnchor?: RemoteTlsAnchor; displayUrl?: string },
 ): Promise<{ record: Record<string, unknown>; bearerRequired: boolean }> {
   const url = `${base}${DISCOVERY_PATH}`;
-  const { body } = await fetchJson(url, { headers: authorizationHeaders(options.token) }, options.tlsAnchor);
-  const record = asRecord(body, url);
+  const display = options.displayUrl ?? base;
+  const { body } = await fetchJson(url, { headers: authorizationHeaders(options.token) }, options.tlsAnchor, display);
+  const record = asRecord(body, display);
   if (record.protocol !== PROTOCOL_NAME) {
-    throw new RemoteTransportError(`service at ${base} is not a ukp-remote service (protocol: ${String(record.protocol)})`);
+    throw new RemoteTransportError(`service at ${display} is not a ukp-remote service (protocol: ${String(record.protocol)})`);
   }
   if (record.protocol_version !== "1") {
-    throw new RemoteTransportError(`service at ${base} speaks ukp-remote protocol version ${String(record.protocol_version)}; this client supports 1`);
+    throw new RemoteTransportError(`service at ${display} speaks ukp-remote protocol version ${String(record.protocol_version)}; this client supports 1`);
   }
   const schemes = (record.security as { schemes?: unknown } | undefined)?.schemes;
   return { record, bearerRequired: Array.isArray(schemes) && schemes.includes("bearer") };
@@ -756,14 +1009,22 @@ async function fetchWellKnownRecord(
  * documents; doors go through `fetchRegistrationDocument`. */
 export async function fetchDiscoveryDocumentAt(
   url: string,
-  options: { name?: string; pinnedUid?: string; token?: string; tlsAnchor?: RemoteTlsAnchor } = {},
+  options: { name?: string; pinnedUid?: string; token?: string; tlsAnchor?: RemoteTlsAnchor; displayUrl?: string } = {},
 ): Promise<DiscoveryFetch> {
   const base = url.replace(/\/+$/, "");
-  const label = options.name ?? base;
-  const { record, bearerRequired } = await fetchWellKnownRecord(base, options);
+  const display = options.displayUrl ?? base;
+  const label = options.name ?? display;
+  const { record, bearerRequired } = await fetchWellKnownRecord(base, {
+    token: options.token,
+    tlsAnchor: options.tlsAnchor,
+    displayUrl: display,
+  });
   if (record.scope === "host") {
+    // The remedy registers the DOOR, not the endpoint path the wire base
+    // carries: derive the origin from the url the caller knows.
+    const doorOrigin = parseRemoteUrl(display)?.origin ?? display;
     throw new RemoteTransportError(
-      `service at ${base} is a host door (scope:"host"); register it with 'ukp register --url ${base}' to import its endpoints`,
+      `service at ${display} is a host door (scope:"host"); register it with 'ukp register --url ${doorOrigin}' to import its endpoints`,
     );
   }
   const warnings: string[] = [];
@@ -815,15 +1076,20 @@ export interface DoorFetch {
  * itself carries no identity. */
 export async function fetchDoorDocument(
   url: string,
-  options: { token?: string; tlsAnchor?: RemoteTlsAnchor } = {},
+  options: { token?: string; tlsAnchor?: RemoteTlsAnchor; displayUrl?: string } = {},
 ): Promise<DoorFetch> {
   const base = url.replace(/\/+$/, "");
-  const { record, bearerRequired } = await fetchWellKnownRecord(base, options);
+  const display = options.displayUrl ?? base;
+  const { record, bearerRequired } = await fetchWellKnownRecord(base, {
+    token: options.token,
+    tlsAnchor: options.tlsAnchor,
+    displayUrl: display,
+  });
   if (record.scope !== "host") {
-    throw new RemoteTransportError(`service at ${base} is not a host door (scope: ${String(record.scope)}); register it directly with 'ukp register --url ${base}'`);
+    throw new RemoteTransportError(`service at ${display} is not a host door (scope: ${String(record.scope)}); register it directly with 'ukp register --url ${display}'`);
   }
   return {
-    doc: { ...(record as unknown as DoorDocument), endpoints: parseDoorEndpoints(record, base) },
+    doc: { ...(record as unknown as DoorDocument), endpoints: parseDoorEndpoints(record, display) },
     bearerRequired,
   };
 }
@@ -838,15 +1104,20 @@ export type RegistrationFetch =
 
 export async function fetchRegistrationDocument(
   url: string,
-  options: { token?: string; tlsAnchor?: RemoteTlsAnchor } = {},
+  options: { token?: string; tlsAnchor?: RemoteTlsAnchor; displayUrl?: string } = {},
 ): Promise<RegistrationFetch> {
   const base = url.replace(/\/+$/, "");
-  const { record, bearerRequired } = await fetchWellKnownRecord(base, options);
+  const display = options.displayUrl ?? base;
+  const { record, bearerRequired } = await fetchWellKnownRecord(base, {
+    token: options.token,
+    tlsAnchor: options.tlsAnchor,
+    displayUrl: display,
+  });
   if (record.scope === "host") {
     return {
       kind: "door",
       door: {
-        doc: { ...(record as unknown as DoorDocument), endpoints: parseDoorEndpoints(record, base) },
+        doc: { ...(record as unknown as DoorDocument), endpoints: parseDoorEndpoints(record, display) },
         bearerRequired,
       },
     };
@@ -892,8 +1163,8 @@ export async function remoteSearch(
     method: "POST",
     headers: { "content-type": "application/json", ...authorizationHeaders(token) },
     body: JSON.stringify({ query, limit }),
-  }, transport.tls);
-  const record = asRecord(body, `${base}/v1/search`);
+  }, transport.tls, transport.displayUrl);
+  const record = asRecord(body, transport.displayUrl);
   const envelope = record.endpoints as Array<Record<string, unknown>> | undefined;
   const entry = Array.isArray(envelope) ? envelope[0] : undefined;
 
@@ -930,7 +1201,7 @@ export async function remoteSearch(
 
 function authMessage(token: string | undefined): string {
   return token === undefined
-    ? "remote endpoint requires a bearer token; set UKP_ENDPOINT_<NAME>_TOKEN (NAME upper-cased, '-' → '_')"
+    ? "remote endpoint requires a bearer token; set UKP_ENDPOINT_<NAME>_TOKEN (NAME upper-cased, '-' -> '_')"
     : "remote endpoint rejected the bearer token (401)";
 }
 
@@ -969,8 +1240,8 @@ export async function remoteRead(
   if (params.pin !== undefined) search.set("pin", params.pin);
   const { status, body } = await fetchJson(`${base}/v1/read?${search.toString()}`, {
     headers: authorizationHeaders(token),
-  }, transport.tls);
-  const record = asRecord(body, `${base}/v1/read`);
+  }, transport.tls, transport.displayUrl);
+  const record = asRecord(body, transport.displayUrl);
   const error = record.error as { class?: unknown; message?: unknown } | undefined;
   return {
     status,
@@ -1007,8 +1278,8 @@ export async function remoteNav(
   const query = search.size > 0 ? `?${search.toString()}` : "";
   const { status, body } = await fetchJson(`${base}/v1/nav${query}`, {
     headers: authorizationHeaders(token),
-  }, transport.tls);
-  const record = asRecord(body, `${base}/v1/nav`);
+  }, transport.tls, transport.displayUrl);
+  const record = asRecord(body, transport.displayUrl);
   const error = record.error as { class?: unknown; message?: unknown } | undefined;
   // Shape gate (read precedent validates what it consumes): a body claiming
   // the schema but missing the rendered fields would crash the shared
@@ -1057,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,
@@ -1068,24 +1352,27 @@ 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");
   for (const arg of params.passthrough) search.append("passthrough", arg);
   const { status, body } = await fetchJson(`${base}/v1/rg?${search.toString()}`, {
     headers: authorizationHeaders(token),
-  }, transport.tls);
-  const record = asRecord(body, `${base}/v1/rg`);
+  }, transport.tls, transport.displayUrl);
+  const record = asRecord(body, transport.displayUrl);
   const error = record.error as { class?: unknown; message?: unknown } | undefined;
 
   if (status === 401) {
@@ -1112,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: {
@@ -1121,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,
@@ -1156,8 +1447,8 @@ export async function remotePropose(
     method: "PUT",
     headers: { "content-type": "text/plain; charset=utf-8", ...authorizationHeaders(token) },
     body: content,
-  }, transport.tls);
-  const record = asRecord(body, url);
+  }, transport.tls, transport.displayUrl);
+  const record = asRecord(body, transport.displayUrl);
   const error = record.error as { class?: unknown; message?: unknown } | undefined;
   const ok = record.schema === "ukp.propose.v1"
     && typeof record.id === "string"