@catheadowl/ukp 0.1.1 → 0.2.0

package/src/capabilities/remote-client.ts

@@ -1,4 +1,4 @@
-import { connect as netConnect, isIP } from "node:net";
+import { isIP } from "node:net";
 import { connect as tlsConnect } from "node:tls";
 import { X509Certificate } from "node:crypto";
 import {
@@ -87,24 +87,6 @@ function freePort(): Promise<number> {
   });
 }
 
-function portAccepts(hostname: string, port: number, timeoutMs: number): Promise<boolean> {
-  const deadline = Date.now() + timeoutMs;
-  return new Promise((resolve) => {
-    const attempt = () => {
-      const socket = netConnect({ host: hostname, port }, () => {
-        socket.destroy();
-        resolve(true);
-      });
-      socket.on("error", () => {
-        socket.destroy();
-        if (Date.now() > deadline) resolve(false);
-        else setTimeout(attempt, 120);
-      });
-    };
-    attempt();
-  });
-}
-
 /** TLS trust state for one invocation (W5' / D-079): `ca` is the pinned
  * certificate PEM handed to fetch as the trust anchor; `pin` is the RFC 7469
  * SPKI pin used to distinguish "server renewed its certificate, same key"
@@ -207,43 +189,278 @@ function directTransportHandle(
   };
 }
 
-/** One ephemeral ssh local forward (D-078): free local port → the remote
- * host's loopback on `port`; encryption + host auth come from the user's
- * SSH config/keys. Shared by the one-shot transport and the per-origin
- * pool; `sshCommand` is a test injection point for the ssh binary. */
-async function openSshTunnel(
-  parts: { user?: string; host: string; port: number },
-  options: { sshCommand?: readonly string[] },
-  endpointLabel: string,
-): Promise<{ proc: ReturnType<typeof Bun.spawn>; base: string }> {
-  const localPort = await freePort();
-  const target = parts.user !== undefined ? `${parts.user}@${parts.host}` : parts.host;
+/** W9 / ADR-REM-006: the woken door self-reaps after this idle window. The
+ * ali E2E falsified the "clean disconnect reaps via SIGHUP" assumption for
+ * no-TTY sessions — without a controlling terminal a remote command NEVER
+ * receives SIGHUP, normal disconnect included — so `-tt` (below) is what
+ * makes the door session-bound, and this window is the pure backstop for
+ * paths where even the pty session lingers (network death awaiting TCP
+ * keepalive). NOT a tuning knob. */
+const WAKE_DOOR_MAX_IDLE_SECONDS = 60;
+/** Probe budget for a woken door: ssh handshake + auth + remote bun startup. */
+const WAKE_READY_TIMEOUT_MS = 20_000;
+/** Remote door ports are client-chosen from this unprivileged band — the url
+ * port no longer selects anything under wake (the resident-door assumption is
+ * gone; per-binding door urls keep their identity role). The band sits BELOW
+ * the Linux (32768+) and Windows (49152+) ephemeral ranges, so OS-assigned
+ * short-lived listeners never collide with it; only an explicitly bound
+ * service in the band can (rare — absorbed by the bounded retry). */
+const WAKE_REMOTE_PORT_MIN = 20000;
+const WAKE_REMOTE_PORT_SPAN = 12768;
+
+function randomRemotePort(): number {
+  return WAKE_REMOTE_PORT_MIN + Math.floor(Math.random() * WAKE_REMOTE_PORT_SPAN);
+}
+
+/** Tier 1 (ADR-REM-006 §4): substrate-native handshake amortization. A
+ * dedicated `-N` mux master is spawned per origin before the wake client;
+ * with ControlPersist it daemonizes immediately and self-exits WINDOW
+ * seconds after the last session — ukp never reaps it. The wake client then
+ * multiplexes over the warm connection (no TCP+key handshake); only the
+ * remote bun startup stays per-call. The door STILL spawns per call as the
+ * client's own session and dies with it — this is NOT the deferred Tier-2
+ * persistent door. UKP-owned ControlPath namespace (keyed by %r/%h/%p = the
+ * SSH endpoint, not the forwarded ports) avoids colliding with the user's
+ * own multiplexing config. Native Windows OpenSSH has no ControlMaster
+ * support ("unix listener too long") — Tier 0 there, per-call handshake. */
+const WAKE_MUX_PERSIST_SECONDS = 120;
+const WAKE_MUX_CONTROL_PATH = "~/.ssh/ukp-cm-%r@%h-%p";
+/** A successful candidate daemonizes (its foreground exits within seconds of
+ * the handshake); one still alive after this window is by definition the
+ * degraded direct `-N` connection — reaped here. */
+const WAKE_MASTER_GRACE_MS = 10_000;
+
+/** The candidate's options: it OWNS master creation (ControlMaster=auto +
+ * ControlPersist — with them a becoming-master daemonizes immediately and
+ * self-exits after the persist window). */
+function muxCandidateOptions(): readonly string[] {
+  if (process.platform === "win32") return [];
+  return [
+    "-o", "ControlMaster=auto",
+    "-o", `ControlPersist=${WAKE_MUX_PERSIST_SECONDS}`,
+    "-o", `ControlPath=${WAKE_MUX_CONTROL_PATH}`,
+  ];
+}
+
+/** The wake client's options: attach-only (ControlMaster=no + ControlPath).
+ * OpenSSH attempts the control socket whenever ControlPath is set, so the
+ * client rides an existing master without any handshake; with no master (or
+ * a stale socket) it just connects directly. Crucially the client NEVER
+ * creates masters: a client-side auto racing the candidate resolves via
+ * temp-bind+link() where the loser disables mux and continues as a FOREGROUND
+ * connection — for the candidate that means an idle `-N` leaking forever
+ * (openssh mux.c muxserver_listen). */
+function muxClientOptions(): readonly string[] {
+  if (process.platform === "win32") return [];
+  return [
+    "-o", "ControlMaster=no",
+    "-o", `ControlPath=${WAKE_MUX_CONTROL_PATH}`,
+  ];
+}
+
+/** The detached mux master (Tier 1): no session, no forwards — with
+ * ControlPersist it backgrounds itself and holds just the authenticated
+ * connection for the persist window. If a master already exists (socket
+ * alive), this exits immediately and harmlessly. Only FAILED candidates are
+ * reaped, after the grace window: a daemonized master's foreground has
+ * already exited, while a candidate that lost the creation race or hit a
+ * stale socket lives on as a plain direct `-N` connection that would idle
+ * forever — one per invocation until the socket is cleaned by hand. Never
+ * spawned on win32: native OpenSSH has no ControlMaster support. */
+function spawnMuxMaster(
+  sshCommand: readonly string[] | undefined,
+  target: string,
+): void {
+  if (process.platform === "win32") return;
   const argv = [
-    ...(options.sshCommand ?? ["ssh"]),
+    ...(sshCommand ?? ["ssh"]),
     "-N",
-    "-o", "ExitOnForwardFailure=yes",
     "-o", "BatchMode=yes",
-    "-L", `127.0.0.1:${localPort}:127.0.0.1:${parts.port}`,
+    ...muxCandidateOptions(),
     target,
   ];
-  const proc = Bun.spawn(argv, { stdout: "ignore", stderr: "ignore", stdin: "ignore" });
-  const ready = await portAccepts("127.0.0.1", localPort, 15_000);
-  if (!ready) {
+  try {
+    const proc = Bun.spawn(argv, { stdout: "ignore", stderr: "ignore", stdin: "ignore" });
+    const grace = setTimeout(() => {
+      if (proc.exitCode === null) proc.kill();
+    }, WAKE_MASTER_GRACE_MS);
+    (grace as { unref?: () => void }).unref?.();
+  } catch {
+    // best-effort: without a master the wake client just handshakes itself
+  }
+}
+
+/** The pinned wake command (W9 / ADR-REM-006 §4 safety narrowing): a fixed shape where
+ * only the client-chosen integer port and idle window are interpolated — the
+ * exact string an operator can allowlist with git-shell / authorized_keys
+ * `command=`. Loopback-only, anonymous: SSH carries encryption and auth.
+ *
+ * The remote shell ssh runs commands in is NON-INTERACTIVE (bare system
+ * PATH), while every standard install mode lands in user-local,
+ * interactive-only dirs (bun's official script writes ~/.bashrc BEHIND its
+ * interactivity guard; `bun add -g` links into ~/.bun/bin; a user npm prefix
+ * like ~/.npm-global never leaves the user dir; brew lives outside the
+ * default ssh PATH). So the command prepends the standard install locations
+ * to PATH before exec — ukp AND its `#!/usr/bin/env bun` shebang both
+ * resolve for any usual install. nvm-style versioned layouts have no fixed
+ * path shape and need a system symlink (documented exception). */
+// The Linuxbrew segment is joined, not written as one literal: its standard
+// install location is a functional constant (part of the byte-pinned remote
+// command), while the release "absolute user path" leak scan rightly flags
+// any literal home-directory path in shipped sources. Constructing it keeps
+// the gate green for real leaks without weakening it for this deliberate
+// constant.
+const WAKE_REMOTE_PATH_PREFIX = [
+  "$HOME/.bun/bin",
+  "$HOME/.npm-global/bin",
+  "/opt/homebrew/bin",
+  ["/home", "linuxbrew", ".linuxbrew", "bin"].join("/"),
+].join(":");
+
+function wakeDoorCommand(remotePort: number): string {
+  return `sh -c 'PATH="${WAKE_REMOTE_PATH_PREFIX}:$PATH" exec ukp serve --allow-anonymous --host 127.0.0.1 --port ${remotePort} --max-idle ${WAKE_DOOR_MAX_IDLE_SECONDS}'`;
+}
+
+/** HTTP-level readiness probe through the tunnel (W9): a TCP accept on the
+ * local forward proves nothing — ssh accepts locally and connects remotely
+ * lazily — so we poll the door's public discovery document until it answers
+ * AND declares the ukp-remote protocol (a foreign listener that happens to
+ * occupy the remote port and answer 200 must not read as "ready"). An ssh
+ * that already exited aborts the wait (no point polling a dead forward; the
+ * caller classifies from the captured stderr). */
+async function probeWakeReady(
+  base: string,
+  timeoutMs: number,
+  proc: ReturnType<typeof Bun.spawn>,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      const response = await fetch(`${base}${DISCOVERY_PATH}`, { signal: AbortSignal.timeout(1000) });
+      if (response.ok) {
+        try {
+          const body: unknown = await response.json();
+          if (
+            typeof body === "object" && body !== null
+            && (body as Record<string, unknown>).protocol === PROTOCOL_NAME
+          ) {
+            return true;
+          }
+        } catch {
+          // not our door (non-JSON) — keep waiting; the real door may still
+          // be booting behind the forward
+        }
+      } else {
+        await response.body?.cancel().catch(() => {});
+      }
+    } catch {
+      // not ready yet — the door is still booting behind the forward
+    }
+    if (proc.exitCode !== null) return false;
+    if (Date.now() > deadline) return false;
+    await Bun.sleep(150);
+  }
+}
+
+/** Keep the tail of a spawn's output for failure diagnostics. The wake
+ * client runs under `-tt` (a pty merges the remote stderr into its stdout),
+ * 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> {
+  return Promise.all(
+    streams.map((stream) => new Response(stream).text().catch(() => "")),
+  ).then((texts) => {
+    const text = texts.join("").trim();
+    return text.length > keep ? `…${text.slice(-keep)}` : text;
+  });
+}
+
+/** On-demand wake (W9 / ADR-REM-006, replaces the W4 `-N -L` resident-door
+ * assumption): one ssh process both opens the local forward AND runs the
+ * pinned `ukp serve` loopback door as its remote command — the door lives and
+ * dies with the session (SIGHUP on clean close; `--max-idle` bounds the
+ * 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). */
+async function openSshTunnel(
+  parts: { user?: string; host: string },
+  options: { sshCommand?: readonly string[] },
+  endpointLabel: string,
+): Promise<{ proc: ReturnType<typeof Bun.spawn>; 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
+  // degrades to a full handshake when not (first call of a burst, win32).
+  spawnMuxMaster(options.sshCommand, target);
+  // Fatal mux conditions on the wake client (ControlPath expansion too long,
+  // unwritable socket dir) are fatal per attempt — once seen, drop the mux
+  // options for the remaining attempts so the endpoint degrades to Tier 0
+  // instead of hard-failing what worked without mux.
+  let muxDisabled = false;
+  const attempts = 3;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const localPort = await freePort();
+    const remotePort = randomRemotePort();
+    const argv = [
+      ...(options.sshCommand ?? ["ssh"]),
+      // Session-bound door (ali E2E): a no-TTY remote command NEVER receives
+      // SIGHUP on disconnect — normal disconnect included, the door only ever
+      // died to --max-idle. Forcing a pty gives the session a controlling
+      // terminal, so killing the client reaps the door in seconds (verified:
+      // kill -9 of the local ssh → door gone within 3s).
+      "-tt",
+      "-o", "ExitOnForwardFailure=yes",
+      "-o", "BatchMode=yes",
+      ...(muxDisabled ? [] : muxClientOptions()),
+      "-L", `127.0.0.1:${localPort}:127.0.0.1:${remotePort}`,
+      target,
+      wakeDoorCommand(remotePort),
+    ];
+    const proc = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+    const stderrTail = drainStderrTail([proc.stdout, proc.stderr]);
+    if (await probeWakeReady(`http://127.0.0.1:${localPort}`, WAKE_READY_TIMEOUT_MS, proc)) {
+      return { proc, base: `http://127.0.0.1:${localPort}` };
+    }
     proc.kill();
-    throw new RemoteTransportError(
-      `ssh tunnel to '${target}:${parts.port}' (endpoint '${endpointLabel}') did not become ready; check the host alias and key auth (BatchMode)`,
-    );
+    // Read `exited` only after the stderr stream ended (its end implies the
+    // process is dead) — reading before the probe's last tick could label a
+    // fast crash as a slow timeout.
+    const diagnostics = (await stderrTail).trim();
+    const exited = proc.exitCode !== null;
+    if (/ControlPath too long|muxserver_listen|unix_listener/i.test(diagnostics)) {
+      muxDisabled = true;
+    }
+    // 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`,
+      );
+    }
+    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)`,
+      );
+    }
   }
-  return { proc, base: `http://127.0.0.1:${localPort}` };
+  // Unreachable: the loop throws on its final attempt (attempts >= 1).
+  throw new RemoteTransportError(`waking the ukp door on '${target}' failed unexpectedly`);
 }
 
-/** Ensure a usable wire base for one invocation (D-078 transparent ssh):
- * http/https urls are used directly; `ssh://[user@]host[:port][/endpoint]`
- * opens an ephemeral local forward over SSH and returns the tunnel endpoint
- * (plus the `/e/<name>` prefix when the url selects a door endpoint). https
- * bindings with a pinned certificate carry their TLS anchor on the handle.
- * `sshCommand` is a test injection point for the ssh binary invocation;
- * `registryPath` lets the renewal re-anchor persist. */
+/** Ensure a usable wire base for one invocation (D-078 transparent ssh, W9
+ * on-demand wake): http/https urls are used directly; `ssh://[user@]host
+ * [:port][/endpoint]` spawns ONE ssh process that opens the local forward
+ * AND wakes the pinned loopback door as its remote command, then returns the
+ * tunnel endpoint (plus the `/e/<name>` prefix when the url selects a door
+ * endpoint). Under wake the url's `[:port]` selects nothing — the remote
+ * door port is client-chosen. https bindings with a pinned certificate carry
+ * their TLS anchor on the handle. `sshCommand` is a test injection point for
+ * the ssh binary invocation; `registryPath` lets the renewal re-anchor
+ * persist. */
 export async function openRemoteTransport(
   binding: RegistryBinding,
   options: { sshCommand?: readonly string[]; registryPath?: string } = {},
@@ -266,12 +483,15 @@ export async function openRemoteTransport(
   };
 }
 
-/** Per-invocation transport pool (W7 / O-5): same-origin ssh urls share ONE
- * tunnel for the pool's lifetime — a 3-endpoint door's `ukp list` is one
- * tunnel, not four (per-row + door fetch). Pure client-internal: handles it
- * hands out have a noop `close`; the caller closes the pool when the
- * invocation ends. Direct (https / loopback http) urls need no pooling and
- * get the same one-shot handles as `openRemoteTransport`. */
+/** Per-invocation transport pool (W7 / O-5, W9 wake): same-origin ssh urls
+ * share ONE woken ssh+door pair for the pool's lifetime — a 3-endpoint door's
+ * `ukp list` is one tunnel, not four (per-row + door fetch). The map stores
+ * the OPEN PROMISE, so overlapping acquires (a future fan-out) converge on
+ * one spawn instead of racing a second and orphaning the first door. Pure
+ * client-internal: handed-out handles have a noop `close`; the caller closes
+ * the pool when the invocation ends. Direct (https / loopback http) urls
+ * need no pooling and get the same one-shot handles as
+ * `openRemoteTransport`. */
 export interface RemoteTransportPool {
   acquire(binding: RegistryBinding): Promise<RemoteTransportHandle>;
   close(): void;
@@ -280,7 +500,7 @@ export interface RemoteTransportPool {
 export function createTransportPool(
   options: { sshCommand?: readonly string[]; registryPath?: string } = {},
 ): RemoteTransportPool {
-  const tunnels = new Map<string, { proc: ReturnType<typeof Bun.spawn>; base: string }>();
+  const tunnels = new Map<string, Promise<{ proc: ReturnType<typeof Bun.spawn>; base: string }>>();
   return {
     async acquire(binding) {
       if (binding.kind !== "remote" || binding.url === undefined) {
@@ -296,16 +516,22 @@ export function createTransportPool(
       }
       let tunnel = tunnels.get(parts.origin);
       if (tunnel === undefined) {
-        tunnel = await openSshTunnel(parts, options, binding.name);
+        // 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) => {
+          tunnels.delete(parts.origin);
+          throw error;
+        });
         tunnels.set(parts.origin, tunnel);
       }
+      const acquired = await tunnel;
       return {
-        base: tunnel.base + wirePrefix(parts.endpointName),
+        base: acquired.base + wirePrefix(parts.endpointName),
         close: () => {},
       };
     },
     close() {
-      for (const { proc } of tunnels.values()) proc.kill();
+      for (const tunnel of tunnels.values()) void tunnel.then(({ proc }) => proc.kill(), () => {});
       tunnels.clear();
     },
   };
@@ -558,10 +784,24 @@ export interface RemoteSearchExecution {
    * human result units, replacing local providerOutput's role. */
   results: unknown[];
   /** Inline references (wire `references`, RQ-07): per-result handoff keys
-   * with server-declared `ukp_uri`. */
+   * with server-declared `ukp_uri`, re-anchored to the local handle below. */
   references: Array<{ ukp_uri?: string }> | undefined;
 }
 
+/** Re-anchor a server-declared `ukp://` authority to the local handle
+ * (ADR-REM-007 / D-086): the server emits its own declared name, but this
+ * registry keys the endpoint under the consumer-chosen handle — a hand-off
+ * key must resolve where it is handed off. No-op when the two agree or when
+ * the binding predates declared_name (handle == declared under RQ-14). The
+ * request direction needs no inverse rewrite: URI-addressed reads travel as
+ * endpoint-relative `ref`s, and authority resolution is client-side. */
+export function reanchorRemoteUkpUri(uri: string, binding: RegistryBinding): string {
+  const declared = binding.declared_name;
+  if (declared === undefined || declared === binding.name) return uri;
+  const prefix = `ukp://${declared}/`;
+  return uri.startsWith(prefix) ? `ukp://${binding.name}/${uri.slice(prefix.length)}` : uri;
+}
+
 /** POST /v1/search → endpoint outcome in the local SearchEndpointOutcome
  * vocabulary (status/message/envelope-compatible fields). */
 export async function remoteSearch(
@@ -594,7 +834,11 @@ export async function remoteSearch(
   }
   const referencesRecord = record.references as { results?: unknown } | undefined;
   const references = referencesRecord !== undefined && Array.isArray(referencesRecord.results)
-    ? referencesRecord.results as Array<{ ukp_uri?: string }>
+    ? (referencesRecord.results as Array<{ ukp_uri?: string }>).map((reference) =>
+        reference.ukp_uri !== undefined
+          ? { ...reference, ukp_uri: reanchorRemoteUkpUri(reference.ukp_uri, binding) }
+          : reference,
+      )
     : undefined;
   return {
     outcome: {
@@ -788,7 +1032,9 @@ export async function remoteRg(
     };
   }
   const wireStatus = typeof entry.status === "string" && RG_WIRE_STATUSES.has(entry.status) ? entry.status : "failed";
-  const matches = remoteRgMatches(entry.matches);
+  const matches = remoteRgMatches(entry.matches)?.map((match) =>
+    match.ukp_uri !== undefined ? { ...match, ukp_uri: reanchorRemoteUkpUri(match.ukp_uri, binding) } : match,
+  );
   const counts = remoteRgCounts(entry.counts);
   const warnings = Array.isArray(record.warnings) ? record.warnings.filter((item): item is string => typeof item === "string") : [];
   return {

package/src/capabilities/rg.ts

@@ -43,6 +43,8 @@ export interface RgContext {
   currentDirectory: string;
   registryPath: string;
   rgCommand?: readonly string[];
+  /** Test injection point for the ssh binary the wake transport spawns. */
+  sshCommand?: readonly string[];
 }
 
 /** ADR 0021 aggregate classification — the adapter maps it onto exit codes;

package/src/capabilities/search.ts

@@ -55,6 +55,8 @@ export interface SearchContext {
   currentDirectory: string;
   registryPath: string;
   qmdCommand?: readonly string[];
+  /** Test injection point for the ssh binary the wake transport spawns. */
+  sshCommand?: readonly string[];
   artifactRoot?: string;
   artifactRunId?: string;
   now?: Date;
@@ -371,6 +373,25 @@ function renderTraversalProvenance(traversal: TraversalProvenance | undefined):
   return lines;
 }
 
+/** Zero hits by parsed content, not stdout size: qmd's JSON mode prints a
+ * non-empty `[]` for zero results. `null` marks non-array / unparseable
+ * provider-native output, which keeps the fallback render path `succeeded`. */
+function parseJsonArrayHitCount(providerOutput: string): number | null {
+  try {
+    const value: unknown = JSON.parse(providerOutput);
+    return Array.isArray(value) ? value.length : null;
+  } catch {
+    return null;
+  }
+}
+
+/** An empty provider result is indistinguishable from an unconfigured provider
+ * to a first-run caller — both classification sites surface the setup path
+ * (search's own contract stays: no matches is a result, not a failure, exit 0). */
+function noMatchesSetupHint(endpointName: string): string {
+  return `endpoint '${endpointName}' returned no matches; if the QMD provider has not been set up for this Service yet, see 'ukp guide service qmd'`;
+}
+
 function runHumanMode(
   parsed: ParsedSearch,
   plan: readonly PlannedEndpoint[],
@@ -458,12 +479,10 @@ function runHumanMode(
       outcome.providerErrorDetail = providerError;
       continue;
     }
-    outcome.status = providerOutput ? "succeeded" : "no_matches";
+    const hitCount = parseJsonArrayHitCount(providerOutput);
+    outcome.status = hitCount === 0 || !providerOutput ? "no_matches" : "succeeded";
     if (outcome.status === "no_matches") {
-      // An empty provider result is indistinguishable from an unconfigured
-      // provider to a first-run caller — surface the setup path as guidance
-      // (search's own contract stays: no matches is a result, not a failure).
-      warnings.push(`endpoint '${endpoint.name}' returned no matches; if the QMD provider has not been set up for this Service yet, see 'ukp guide service qmd'`);
+      warnings.push(noMatchesSetupHint(endpoint.name));
     }
   }
   return {
@@ -1132,6 +1151,7 @@ function runJsonMode(
 
       succeeded = true;
       outcome.status = status;
+      if (status === "no_matches") warnings.push(noMatchesSetupHint(endpoint.name));
       let hasReferenceSidecar = false;
       try {
         writeQmdReferenceSidecar(endpoint.name, endpoint.folder!, artifact, referencesArtifact);