@saptools/cf-hana 0.5.0 → 0.5.2

package/dist/index.js

@@ -6,7 +6,7 @@ import { homedir } from "os";
 import { join } from "path";
 
 // src/config.ts
-var CLI_VERSION = "0.5.0";
+var CLI_VERSION = "0.5.2";
 var ENV_PREFIX = "CF_HANA";
 var DEFAULT_QUERY_TIMEOUT_MS = 6e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 6e4;
@@ -244,7 +244,7 @@ function formatResult(result, format, compactColumn) {
   }
 }
 
-// src/003-backup-sql-parser.ts
+// src/backup-sql-parser.ts
 function isIdentifierChar(char) {
   return char !== void 0 && /[A-Za-z0-9_$#]/.test(char);
 }
@@ -438,7 +438,7 @@ function findTopLevelChar(sql, target, startIndex, endIndex) {
 }
 
 // src/statements.ts
-var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT", "WITH"]);
+var SELECT_KEYWORDS = /* @__PURE__ */ new Set(["SELECT"]);
 var DML_KEYWORDS = /* @__PURE__ */ new Set(["INSERT", "UPDATE", "DELETE", "MERGE", "UPSERT", "REPLACE"]);
 var DDL_KEYWORDS = /* @__PURE__ */ new Set(["CREATE", "DROP", "ALTER", "TRUNCATE", "RENAME", "COMMENT"]);
 function firstKeyword(sql) {
@@ -478,8 +478,189 @@ function firstKeyword(sql) {
   }
   return sql.slice(index, keywordEnd).toUpperCase();
 }
-function classifyStatement(sql) {
-  const keyword = firstKeyword(sql);
+function skipQuotedText2(sql, start) {
+  const quote = sql[start];
+  let index = start + 1;
+  while (index < sql.length) {
+    if (sql[index] === quote) {
+      if (sql[index + 1] === quote) {
+        index += 2;
+        continue;
+      }
+      index += 1;
+      break;
+    }
+    index += 1;
+  }
+  return index;
+}
+function skipLineComment2(sql, start) {
+  let index = start + 2;
+  while (index < sql.length && sql[index] !== "\n") {
+    index += 1;
+  }
+  return index;
+}
+function skipBlockComment2(sql, start) {
+  let index = start + 2;
+  while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
+    index += 1;
+  }
+  return Math.min(index + 2, sql.length);
+}
+function maskIgnoredSqlText(sql) {
+  let masked = "";
+  let index = 0;
+  while (index < sql.length) {
+    const char = sql[index];
+    if (char === "'" || char === '"') {
+      const end = skipQuotedText2(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    if (char === "-" && sql[index + 1] === "-") {
+      const end = skipLineComment2(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    if (char === "/" && sql[index + 1] === "*") {
+      const end = skipBlockComment2(sql, index);
+      masked += " ".repeat(end - index);
+      index = end;
+      continue;
+    }
+    masked += char ?? "";
+    index += 1;
+  }
+  return masked;
+}
+function topLevelKeywordIndex(sql, keyword) {
+  const masked = maskIgnoredSqlText(sql);
+  let depth = 0;
+  for (let index = 0; index < masked.length; index += 1) {
+    const char = masked[index];
+    if (char === "(") {
+      depth += 1;
+      continue;
+    }
+    if (char === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (depth === 0 && masked.slice(index, index + keyword.length).toUpperCase() === keyword && !/[A-Za-z0-9_$#]/.test(masked.charAt(index - 1)) && !/[A-Za-z0-9_$#]/.test(masked.charAt(index + keyword.length))) {
+      return index;
+    }
+  }
+  return void 0;
+}
+function hasTopLevelKeyword(sql, keyword) {
+  return topLevelKeywordIndex(sql, keyword) !== void 0;
+}
+function isIdentifierChar2(char) {
+  return /[A-Za-z0-9_$#]/.test(char);
+}
+function skipWhitespace(masked, start) {
+  let index = start;
+  while (index < masked.length && /\s/.test(masked.charAt(index))) {
+    index += 1;
+  }
+  return index;
+}
+function matchingCloseParenIndex(masked, openIndex) {
+  let depth = 0;
+  for (let index = openIndex; index < masked.length; index += 1) {
+    const char = masked.charAt(index);
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return void 0;
+}
+function isAsKeywordAt(masked, index) {
+  return masked.slice(index, index + 2).toUpperCase() === "AS" && !isIdentifierChar2(masked.charAt(index - 1)) && !isIdentifierChar2(masked.charAt(index + 2));
+}
+function skipCteName(sql, masked, start) {
+  let index = start;
+  while (index < sql.length) {
+    const char = sql.charAt(index);
+    if (char.trim().length === 0) {
+      index += 1;
+      continue;
+    }
+    if (char === "-" && sql.charAt(index + 1) === "-") {
+      index = skipLineComment2(sql, index);
+      continue;
+    }
+    if (char === "/" && sql.charAt(index + 1) === "*") {
+      index = skipBlockComment2(sql, index);
+      continue;
+    }
+    break;
+  }
+  if (sql.charAt(index) === "'" || sql.charAt(index) === '"') {
+    return skipQuotedText2(sql, index);
+  }
+  let end = index;
+  while (end < masked.length && isIdentifierChar2(masked.charAt(end))) {
+    end += 1;
+  }
+  return end;
+}
+function cteListEndIndex(sql, masked, afterWith) {
+  let index = afterWith;
+  for (; ; ) {
+    index = skipCteName(sql, masked, index);
+    index = skipWhitespace(masked, index);
+    if (masked.charAt(index) === "(") {
+      const columnListEnd = matchingCloseParenIndex(masked, index);
+      if (columnListEnd === void 0) {
+        return void 0;
+      }
+      index = skipWhitespace(masked, columnListEnd + 1);
+    }
+    if (!isAsKeywordAt(masked, index)) {
+      return void 0;
+    }
+    index = skipWhitespace(masked, index + 2);
+    if (masked.charAt(index) !== "(") {
+      return void 0;
+    }
+    const closeIndex = matchingCloseParenIndex(masked, index);
+    if (closeIndex === void 0) {
+      return void 0;
+    }
+    index = skipWhitespace(masked, closeIndex + 1);
+    if (masked.charAt(index) === ",") {
+      index += 1;
+      continue;
+    }
+    return index;
+  }
+}
+function resolveWithStatement(sql) {
+  const withIndex = topLevelKeywordIndex(sql, "WITH");
+  if (withIndex === void 0) {
+    return void 0;
+  }
+  const masked = maskIgnoredSqlText(sql);
+  const trailingIndex = cteListEndIndex(sql, masked, withIndex + "WITH".length);
+  if (trailingIndex === void 0) {
+    return void 0;
+  }
+  let keywordEnd = trailingIndex;
+  while (keywordEnd < masked.length && isIdentifierChar2(masked.charAt(keywordEnd))) {
+    keywordEnd += 1;
+  }
+  return { keyword: masked.slice(trailingIndex, keywordEnd).toUpperCase(), index: trailingIndex };
+}
+function classifyByKeyword(keyword) {
   if (SELECT_KEYWORDS.has(keyword)) {
     return "select";
   }
@@ -491,6 +672,14 @@ function classifyStatement(sql) {
   }
   return "unknown";
 }
+function classifyStatement(sql) {
+  const keyword = firstKeyword(sql);
+  if (keyword === "WITH") {
+    const resolved = resolveWithStatement(sql);
+    return resolved === void 0 ? "unknown" : classifyByKeyword(resolved.keyword);
+  }
+  return classifyByKeyword(keyword);
+}
 function quoteIdentifier(identifier) {
   if (identifier.length === 0) {
     throw new QueryError("A SQL identifier must not be empty");
@@ -556,7 +745,7 @@ function assertParamArity(sql, params) {
   }
 }
 
-// src/001-backup-planner.ts
+// src/backup-planner.ts
 var WRITE_KEYWORDS = /* @__PURE__ */ new Set([
   "UPDATE",
   "UPSERT",
@@ -654,11 +843,11 @@ function mergeTargetReference(statementSql, target, usingStart) {
     return target.reference;
   }
   if (/^PARTITION\b/i.test(suffix)) {
-    const open = suffix.indexOf("(");
-    if (open === -1) {
+    const open2 = suffix.indexOf("(");
+    if (open2 === -1) {
       return void 0;
     }
-    const close = findTopLevelChar(suffix, ")", open + 1, suffix.length);
+    const close = findTopLevelChar(suffix, ")", open2 + 1, suffix.length);
     if (close === void 0) {
       return void 0;
     }
@@ -841,13 +1030,24 @@ function dispatchWriteBackupPlan(keyword, statementSql, params) {
   }
 }
 function buildWriteBackupPlan(sql, params = []) {
-  const statementSql = trimStatementSql(sql);
-  const keyword = firstKeyword(statementSql);
+  const trimmed = trimStatementSql(sql);
+  const leading = firstKeyword(trimmed);
+  const withResolved = leading === "WITH" ? resolveWithStatement(trimmed) : void 0;
+  if (leading === "WITH" && withResolved === void 0) {
+    throw new BackupRequiredError(
+      "WITH write refused: cannot determine the statement's real trailing keyword"
+    );
+  }
+  const keyword = withResolved?.keyword ?? leading;
   if (!isWriteKeyword(keyword)) {
     return void 0;
   }
-  assertParamArity(statementSql, params);
-  return dispatchWriteBackupPlan(keyword, statementSql, params);
+  const startIndex = withResolved?.index ?? 0;
+  const statementSql = trimmed.slice(startIndex);
+  const slicedParams = params.slice(countPlaceholders(trimmed.slice(0, startIndex)));
+  assertParamArity(statementSql, slicedParams);
+  const plan = dispatchWriteBackupPlan(keyword, statementSql, slicedParams);
+  return plan === void 0 ? void 0 : { ...plan, statementSql: trimmed };
 }
 
 // src/backup.ts
@@ -1176,9 +1376,9 @@ function buildEnv(ctx, overrides = {}) {
   env["CF_HOME"] = ctx.cfHome;
   return env;
 }
-async function execWithRetries(bin, args, env, timeoutMs = DEFAULT_TIMEOUT_MS) {
+async function execWithRetries(bin, args, env, timeoutMs = DEFAULT_TIMEOUT_MS, maxAttempts = CF_RETRY_ATTEMPTS) {
   let lastErr;
-  for (let attempt = 0; attempt < CF_RETRY_ATTEMPTS; attempt++) {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
     try {
       const { stdout } = await execFileAsync(bin, args, {
         env,
@@ -1197,18 +1397,24 @@ async function execWithRetries(bin, args, env, timeoutMs = DEFAULT_TIMEOUT_MS) {
       if (isEnoent || !isTimeout && !isNetworkFlake) {
         throw err;
       }
-      if (attempt < CF_RETRY_ATTEMPTS - 1) {
+      if (attempt < maxAttempts - 1) {
         await new Promise((r) => setTimeout(r, CF_RETRY_BASE_DELAY_MS * (attempt + 1)));
       }
     }
   }
   throw lastErr;
 }
-async function runCf(args, ctx, overrides = {}) {
+async function runCf(args, ctx, overrides = {}, execOptions = {}) {
   const { bin, argsPrefix } = resolveCfBin();
   const env = buildEnv(ctx, overrides);
   try {
-    return await execWithRetries(bin, [...argsPrefix, ...args], env);
+    return await execWithRetries(
+      bin,
+      [...argsPrefix, ...args],
+      env,
+      execOptions.timeoutMs,
+      execOptions.maxAttempts
+    );
   } catch (lastErr) {
     const e = lastErr;
     const detail = e?.stderr ? String(e.stderr) : e?.message ?? "";
@@ -1238,15 +1444,26 @@ async function cfEnvDirect(appName) {
   delete env["SAP_PASSWORD"];
   return await execWithRetries(bin, [...argsPrefix, "env", appName], env);
 }
-async function cfApps(ctx) {
-  return await runCf(["apps"], ctx);
+async function cfApps(ctx, timeoutMs) {
+  return await runCf(
+    ["apps"],
+    ctx,
+    {},
+    timeoutMs === void 0 ? {} : { timeoutMs, maxAttempts: 1 }
+  );
 }
-async function cfAppsDirect() {
+async function cfAppsDirect(timeoutMs) {
   const { bin, argsPrefix } = resolveCfBin();
   const env = { ...process.env };
   delete env["SAP_EMAIL"];
   delete env["SAP_PASSWORD"];
-  return await execWithRetries(bin, [...argsPrefix, "apps"], env);
+  return await execWithRetries(
+    bin,
+    [...argsPrefix, "apps"],
+    env,
+    timeoutMs,
+    timeoutMs === void 0 ? void 0 : 1
+  );
 }
 async function readCurrentCfTarget() {
   const { bin, argsPrefix } = resolveCfBin();
@@ -2153,6 +2370,13 @@ async function connectHdb(params) {
     password: params.password,
     ca: params.certificate,
     useTLS: true,
+    // HANA Cloud can reactively redirect a connection mid-auth to an
+    // internal per-node hostname (pod-locality routing). That target is
+    // often unreachable outside SAP's own network, and for a tunneled
+    // connection it would silently abandon the SSH forward for a fresh,
+    // untunneled socket. The original bound host is always a real, working
+    // endpoint, so disabling the redirect is safe on the direct path too.
+    disableCloudRedirect: true,
     ...params.servername === void 0 ? {} : { servername: params.servername }
   });
   await openClient(client, params.connectTimeoutMs);
@@ -2262,83 +2486,6 @@ async function appendSqlHistory(input, options = {}) {
 // src/safety.ts
 var DESTRUCTIVE_DDL_KEYWORDS = /* @__PURE__ */ new Set(["DROP", "TRUNCATE", "ALTER"]);
 var UNSCOPED_WRITE_KEYWORDS = /* @__PURE__ */ new Set(["UPDATE", "DELETE"]);
-function skipQuotedText2(sql, start) {
-  const quote = sql[start];
-  let index = start + 1;
-  while (index < sql.length) {
-    if (sql[index] === quote) {
-      if (sql[index + 1] === quote) {
-        index += 2;
-        continue;
-      }
-      index += 1;
-      break;
-    }
-    index += 1;
-  }
-  return index;
-}
-function skipLineComment2(sql, start) {
-  let index = start + 2;
-  while (index < sql.length && sql[index] !== "\n") {
-    index += 1;
-  }
-  return index;
-}
-function skipBlockComment2(sql, start) {
-  let index = start + 2;
-  while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
-    index += 1;
-  }
-  return Math.min(index + 2, sql.length);
-}
-function maskIgnoredSqlText(sql) {
-  let masked = "";
-  let index = 0;
-  while (index < sql.length) {
-    const char = sql[index];
-    if (char === "'" || char === '"') {
-      const end = skipQuotedText2(sql, index);
-      masked += " ".repeat(end - index);
-      index = end;
-      continue;
-    }
-    if (char === "-" && sql[index + 1] === "-") {
-      const end = skipLineComment2(sql, index);
-      masked += " ".repeat(end - index);
-      index = end;
-      continue;
-    }
-    if (char === "/" && sql[index + 1] === "*") {
-      const end = skipBlockComment2(sql, index);
-      masked += " ".repeat(end - index);
-      index = end;
-      continue;
-    }
-    masked += char ?? "";
-    index += 1;
-  }
-  return masked;
-}
-function hasTopLevelKeyword(sql, keyword) {
-  const masked = maskIgnoredSqlText(sql);
-  let depth = 0;
-  for (let index = 0; index < masked.length; index += 1) {
-    const char = masked[index];
-    if (char === "(") {
-      depth += 1;
-      continue;
-    }
-    if (char === ")") {
-      depth = Math.max(0, depth - 1);
-      continue;
-    }
-    if (depth === 0 && masked.slice(index, index + keyword.length).toUpperCase() === keyword && !/[A-Za-z0-9_$#]/.test(masked.charAt(index - 1)) && !/[A-Za-z0-9_$#]/.test(masked.charAt(index + keyword.length))) {
-      return true;
-    }
-  }
-  return false;
-}
 function isUnconditionalMergeDelete(sql) {
   return /\bWHEN\s+MATCHED\s+THEN\s+DELETE\b/i.test(maskIgnoredSqlText(sql));
 }
@@ -2381,17 +2528,24 @@ function appendLimit(sql, limit) {
 }
 function inspectStatement(sql) {
   const kind = classifyStatement(sql);
-  const keyword = firstKeyword(sql);
+  const leading = firstKeyword(sql);
+  const withResolved = leading === "WITH" ? resolveWithStatement(sql) : void 0;
+  const keyword = withResolved?.keyword ?? leading;
+  const tail = withResolved === void 0 ? sql : sql.slice(withResolved.index);
   if (kind === "ddl") {
     return { kind, destructive: DESTRUCTIVE_DDL_KEYWORDS.has(keyword) };
   }
   if (kind === "dml") {
-    const destructive = UNSCOPED_WRITE_KEYWORDS.has(keyword) && !hasTopLevelKeyword(sql, "WHERE") || keyword === "MERGE" && isUnconditionalMergeDelete(sql) || keyword === "REPLACE" && isMalformedReplace(sql);
+    const destructive = UNSCOPED_WRITE_KEYWORDS.has(keyword) && !hasTopLevelKeyword(tail, "WHERE") || keyword === "MERGE" && isUnconditionalMergeDelete(tail) || keyword === "REPLACE" && isMalformedReplace(tail);
     return {
       kind,
       destructive
     };
   }
+  if (kind === "unknown") {
+    const unresolvedWith = leading === "WITH" && withResolved === void 0;
+    return { kind, destructive: keyword === "CALL" || unresolvedWith };
+  }
   return { kind, destructive: false };
 }
 function evaluateGuard(sql, config) {
@@ -2436,13 +2590,13 @@ function applyAutoLimit(sql, limit) {
 
 // src/tunnel/cache.ts
 import { createHash } from "crypto";
-import { mkdir as mkdir3, readdir as readdir2, readFile, rename, rm as rm4, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir3, readdir as readdir2, readFile as readFile2, rename, rm as rm4, writeFile as writeFile2 } from "fs/promises";
 import { homedir as homedir3 } from "os";
 import { join as join5 } from "path";
 
 // src/tunnel/process.ts
 import { spawn } from "child_process";
-import { mkdtemp as mkdtemp2, rm as rm3 } from "fs/promises";
+import { mkdtemp as mkdtemp2, open, readFile, rm as rm3 } from "fs/promises";
 import { connect as netConnect, createServer } from "net";
 import { tmpdir as tmpdir2 } from "os";
 import { join as join4 } from "path";
@@ -2549,8 +2703,8 @@ function raceTunnelReadiness(child, localPort, boundMs, probePort, killProcess)
     child.on("exit", onAbort);
     child.on("error", onAbort);
     timers.poll = setInterval(() => {
-      void probePort(localPort).then((open) => {
-        if (open && child.pid !== void 0) {
+      void probePort(localPort).then((open2) => {
+        if (open2 && child.pid !== void 0) {
           finish({ localPort, pid: child.pid });
         }
       });
@@ -2558,6 +2712,36 @@ function raceTunnelReadiness(child, localPort, boundMs, probePort, killProcess)
     timers.deadline = setTimeout(finish, boundMs);
   });
 }
+var STDERR_TAIL_MAX_CHARS = 4096;
+async function openStderrCapture() {
+  try {
+    const dir = await mkdtemp2(join4(tmpdir2(), "saptools-cf-hana-tunnel-log-"));
+    const path = join4(dir, "stderr.log");
+    const handle = await open(path, "w");
+    return {
+      path,
+      fd: handle.fd,
+      close: async () => {
+        await handle.close().catch(() => {
+        });
+        await rm3(dir, { recursive: true, force: true });
+      }
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function readStderrTail(path) {
+  try {
+    const content = (await readFile(path, "utf8")).trim().replace(/\s+/g, " ");
+    if (content.length === 0) {
+      return void 0;
+    }
+    return content.length > STDERR_TAIL_MAX_CHARS ? content.slice(-STDERR_TAIL_MAX_CHARS) : content;
+  } catch {
+    return void 0;
+  }
+}
 async function spawnTunnel(params, deps = {}) {
   assertPositiveSafeInteger("tunnel keepalive seconds", params.keepaliveSeconds);
   const remainingMs = params.deadline - Date.now();
@@ -2582,8 +2766,24 @@ async function spawnTunnel(params, deps = {}) {
     `sleep ${String(params.keepaliveSeconds)}`
   ];
   const env = params.cfHome === void 0 ? { ...process.env } : { ...process.env, CF_HOME: params.cfHome };
-  const child = spawnProcess(bin, args, { detached: true, stdio: "ignore", env });
-  return await raceTunnelReadiness(child, localPort, boundMs, probePort, killProcess);
+  const openCapture = deps.openStderrCapture ?? openStderrCapture;
+  const capture = await openCapture();
+  const stdio = capture === void 0 ? "ignore" : ["ignore", "ignore", capture.fd];
+  const child = spawnProcess(bin, args, { detached: true, stdio, env });
+  const result = await raceTunnelReadiness(child, localPort, boundMs, probePort, killProcess);
+  if (capture !== void 0) {
+    if (result === void 0) {
+      try {
+        const tail = await readStderrTail(capture.path);
+        if (tail !== void 0) {
+          deps.onFailureDiagnostic?.(tail);
+        }
+      } catch {
+      }
+    }
+    await capture.close();
+  }
+  return result;
 }
 
 // src/tunnel/cache.ts
@@ -2628,7 +2828,7 @@ function isTunnelCacheRecord(value) {
 }
 async function parseTunnelCacheFile(path) {
   try {
-    const raw = JSON.parse(await readFile(path, "utf8"));
+    const raw = JSON.parse(await readFile2(path, "utf8"));
     return isTunnelCacheRecord(raw) ? raw : void 0;
   } catch {
     return void 0;
@@ -2846,6 +3046,9 @@ function isConnectivityFailure(error) {
   }
   return hasOpenConnectionCause(error.cause, 0);
 }
+function isUnattributedQueryFailure(error) {
+  return error instanceof QueryError && error.databaseCode === void 0 && error.sqlState === void 0;
+}
 
 // src/tunnel/fallback.ts
 var EXPIRY_SAFETY_MARGIN_MS = 3e4;
@@ -2875,30 +3078,40 @@ async function discardQuietly(work) {
   await work.catch(() => {
   });
 }
+function shouldDiscardTunnel(error) {
+  return isConnectivityFailure(error) || isUnattributedQueryFailure(error);
+}
 async function tryReadyRecord(record, driver, config, directParams, cacheOptions) {
   try {
     const connection = await driver.connect(tunneledParams(directParams, record.localPort));
     config.onTunnelStatus?.(`connected via SSH tunnel through ${record.app}`);
     return connection;
   } catch (error) {
-    if (isConnectivityFailure(error)) {
+    if (shouldDiscardTunnel(error)) {
       await discardQuietly(evictTunnelCache(config.host, cacheOptions));
       return void 0;
     }
     throw error;
   }
 }
-async function discoverAppsStdout(ctx) {
+function knownCandidates(targetAppName, hintApp) {
+  return hintApp === void 0 || hintApp === targetAppName ? [targetAppName] : [targetAppName, hintApp];
+}
+async function discoverAppsStdout(ctx, timeoutMs) {
   try {
-    return ctx === void 0 ? await cfAppsDirect() : await cfApps(ctx);
+    return ctx === void 0 ? await cfAppsDirect(timeoutMs) : await cfApps(ctx, timeoutMs);
   } catch {
     return;
   }
 }
-async function buildCandidates(config, ctx, hintApp) {
-  const stdout = await discoverAppsStdout(ctx);
+async function discoverExtraCandidates(config, ctx, alreadyTried, deadline) {
+  const remainingMs = deadline - Date.now();
+  if (remainingMs <= 0) {
+    return [];
+  }
+  const stdout = await discoverAppsStdout(ctx, remainingMs);
   const base = buildCandidateList(config.appName, stdout, DEFAULT_TUNNEL_MAX_CANDIDATES);
-  return hintApp === void 0 || base.includes(hintApp) ? base : [hintApp, ...base];
+  return base.filter((app) => !alreadyTried.includes(app));
 }
 async function finalizeCandidateConnection(app, spawned, driver, config, directParams, cacheOptions) {
   const readyRecord = {
@@ -2914,7 +3127,7 @@ async function finalizeCandidateConnection(app, spawned, driver, config, directP
     config.onTunnelStatus?.(`connected via SSH tunnel through ${app}`);
     return connection;
   } catch (error) {
-    if (isConnectivityFailure(error)) {
+    if (shouldDiscardTunnel(error)) {
       await discardQuietly(finalizeEstablishingFailed(config.host, cacheOptions));
       killTunnelProcess(spawned.pid);
       return void 0;
@@ -2931,7 +3144,8 @@ async function tryCandidate(app, ctx, driver, config, directParams, deadline, ov
     return await tryReadyRecord(claim.record, driver, config, directParams, cacheOptions);
   }
   if (claim.outcome === "wait") {
-    const ready = await waitForEstablishment(config.host, deadline, void 0, cacheOptions);
+    const waitDeadline = Math.min(deadline, Date.now() + DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS);
+    const ready = await waitForEstablishment(config.host, waitDeadline, void 0, cacheOptions);
     return ready === void 0 ? void 0 : await tryReadyRecord(ready, driver, config, directParams, cacheOptions);
   }
   const spawned = await spawnTunnel(
@@ -2944,7 +3158,12 @@ async function tryCandidate(app, ctx, driver, config, directParams, deadline, ov
       deadline,
       candidateTimeoutMs: DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS
     },
-    overrides.process ?? {}
+    {
+      ...overrides.process,
+      onFailureDiagnostic: (message) => {
+        config.onTunnelStatus?.(`tunnel via ${app} failed: ${message}`);
+      }
+    }
   );
   if (spawned === void 0) {
     await discardQuietly(finalizeEstablishingFailed(config.host, cacheOptions));
@@ -2954,7 +3173,11 @@ async function tryCandidate(app, ctx, driver, config, directParams, deadline, ov
 }
 async function tryCachedTunnel(driver, config, directParams, cacheOptions) {
   if (config.refreshTunnel) {
+    const superseded = await readTunnelCacheEntry(config.host, cacheOptions);
     await discardQuietly(evictTunnelCache(config.host, cacheOptions));
+    if (superseded?.status === "ready") {
+      (cacheOptions.killProcess ?? killTunnelProcess)(superseded.pid);
+    }
     return { connection: void 0, hintApp: void 0 };
   }
   const entry = await readTunnelCacheEntry(config.host, cacheOptions);
@@ -2972,8 +3195,12 @@ async function tryDirectConnect(driver, config, directParams) {
   if (config.tunnelMode !== "auto") {
     return { connection: void 0, directError: void 0 };
   }
+  const boundedDirectParams = {
+    ...directParams,
+    connectTimeoutMs: Math.min(directParams.connectTimeoutMs, DEFAULT_TUNNEL_CANDIDATE_TIMEOUT_MS)
+  };
   try {
-    return { connection: await driver.connect(directParams), directError: void 0 };
+    return { connection: await driver.connect(boundedDirectParams), directError: void 0 };
   } catch (error) {
     if (!isConnectivityFailure(error)) {
       throw error;
@@ -2990,18 +3217,47 @@ function buildExhaustionError(host, directError, candidates) {
     `Could not establish an SSH tunnel to ${host} through any candidate app (tried: ${candidates.length > 0 ? candidates.join(", ") : "none"})`
   );
 }
-async function runCandidateLoop(ctx, driver, config, directParams, deadline, hintApp, overrides) {
-  const candidatesTried = await buildCandidates(config, ctx, hintApp);
-  for (const app of candidatesTried) {
+async function tryCandidateList(apps, ctx, driver, config, directParams, deadline, overrides, tried) {
+  for (const app of apps) {
     if (Date.now() >= deadline) {
-      break;
+      return void 0;
     }
+    tried.push(app);
     const connection = await tryCandidate(app, ctx, driver, config, directParams, deadline, overrides);
     if (connection !== void 0) {
-      return { connection, candidatesTried };
+      return connection;
     }
   }
-  return { connection: void 0, candidatesTried };
+  return void 0;
+}
+async function runCandidateLoop(ctx, driver, config, directParams, deadline, hintApp, overrides) {
+  const tried = [];
+  const known = knownCandidates(config.appName, hintApp);
+  const knownConnection = await tryCandidateList(
+    known,
+    ctx,
+    driver,
+    config,
+    directParams,
+    deadline,
+    overrides,
+    tried
+  );
+  if (knownConnection !== void 0) {
+    return { connection: knownConnection, candidatesTried: tried };
+  }
+  const discovered = await discoverExtraCandidates(config, ctx, tried, deadline);
+  const discoveredConnection = await tryCandidateList(
+    discovered,
+    ctx,
+    driver,
+    config,
+    directParams,
+    deadline,
+    overrides,
+    tried
+  );
+  return { connection: discoveredConnection, candidatesTried: tried };
 }
 async function connectWithTunnelFallback(driver, config, overrides = {}) {
   const directParams = directParamsOf(config);