@catheadowl/ukp 0.2.4 → 0.2.6

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,