@tiny-fish/cli 0.20.1 → 0.21.1-next.194

package/dist/lib/connect-all.js

@@ -2,6 +2,7 @@ import * as readline from "node:readline/promises";
 import spawn from "cross-spawn";
 import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectOpenClaw, connectOpencode, } from "../commands/connect.js";
 import { validatedApiKey } from "./auth.js";
+import { NATIVE_MCP_CLIENTS } from "./connect-clients.js";
 import { detectInstalledHarnesses, ALL_HARNESSES, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
 import { emitNotice } from "./notice.js";
@@ -20,10 +21,14 @@ const DISPLAY_NAMES = {
 // `codex mcp add` succeeds unauthenticated; OAuth lands at first tool use.
 // TODO(PF-3580): connect now probes Codex sign-in, so this over-warns a signed-in install.
 const AUTH_DEFERRED_AT_INSTALL = new Set(["codex"]);
-// Harnesses that drive their own OAuth at install — a stored TinyFish key says nothing
-// about their session, so it must never unlock a headless run for them.
-const HARNESS_OWN_AUTH = new Set(["claude-code", "codex", "hermes", "opencode"]);
 const AUTH_CHECK_CAPABLE = new Set(["cursor", "openclaw"]);
+// Descriptor-derived so a harness that cannot carry a key is skipped, not failed, when headless.
+// Cursor and OpenClaw hold the key themselves rather than handing it to a harness `mcp add`.
+const KEY_AUTH_CAPABLE = new Set([
+    ...NATIVE_MCP_CLIENTS.filter((client) => !!client.keyAuth).map((client) => client.connectClient),
+    "cursor",
+    "openclaw",
+]);
 // Real removal commands — harness id is not the binary name.
 const UNINSTALL_POINTERS = {
     "claude-code": "claude mcp remove tinyfish --scope user",
@@ -33,24 +38,28 @@ const UNINSTALL_POINTERS = {
     // OpenCode ships no `mcp remove`, so the only removal is editing the config it wrote.
     opencode: "remove the tinyfish entry from ~/.config/opencode/opencode.json",
 };
-async function runHarnessConnect(harness, opts) {
-    const base = { apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false };
+async function runHarnessConnect(harness, opts, keyAuthOnly) {
+    const base = { apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false, keyAuthOnly };
     if (harness === "claude-code")
         return connectClaudeCode(base);
     if (harness === "codex")
         return connectCodex(base);
     if (harness === "hermes")
         return connectHermes(base);
-    if (harness === "openclaw")
-        return connectOpenClaw({ mcpUrl: opts.mcpUrl, launch: false });
+    if (harness === "openclaw") {
+        // Without the key the child shells an interactive `tinyfish auth login`.
+        await connectOpenClaw({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false });
+        return undefined;
+    }
     if (harness === "opencode")
         return connectOpencode(base);
-    return connectCursor({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl });
+    await connectCursor({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl });
+    return undefined;
 }
-async function verifyHarness(harness, mcpUrl, apiKey) {
+async function verifyHarness(harness, mcpUrl, keyed, apiKey) {
     const health = await verifyMcpHealth(mcpUrl);
-    // claude-code is auth-checkable only in key mode (header-authed config).
-    const capable = AUTH_CHECK_CAPABLE.has(harness) || (harness === "claude-code" && !!apiKey);
+    // The own-OAuth harnesses are auth-checkable only in key mode (key-authed config).
+    const capable = AUTH_CHECK_CAPABLE.has(harness) || keyed;
     if (!capable || !health.ok)
         return health;
     if (!apiKey)
@@ -110,15 +119,18 @@ async function processHarness(detection, opts, prompt) {
     if (opts.uninstall)
         return uninstallHarness(harness, configPath);
     const isTTY = detectHumanInitiated();
-    // claude-code leaves the own-OAuth set when a key is stored: `mcp add --header
-    // X-API-Key` replaces its login. codex/hermes have no header path, so they keep the skip.
-    const keyed = !!validatedApiKey(opts.apiKey);
-    const ownAuthHarness = HARNESS_OWN_AUTH.has(harness) && !(harness === "claude-code" && keyed);
-    const alreadyAuthed = !ownAuthHarness && keyed;
-    if (!isTTY && !alreadyAuthed) {
-        return { ...base, outcome: "no_tty_auth_skip", fixCommand: `tinyfish connect ${harness}` };
+    const apiKey = validatedApiKey(opts.apiKey);
+    // A key only leaves the own-OAuth set where the harness can actually carry one.
+    const keyed = !!apiKey && KEY_AUTH_CAPABLE.has(harness);
+    if (!isTTY && !keyed) {
+        return {
+            ...base,
+            outcome: "no_tty_auth_skip",
+            keyUnusable: !!apiKey,
+            fixCommand: `tinyfish connect ${harness}`,
+        };
     }
-    if (isTTY && !alreadyAuthed && prompt) {
+    if (isTTY && !keyed && prompt) {
         errLine(`step: waiting for browser sign-in to TinyFish for ${DISPLAY_NAMES[harness]}`);
         try {
             await prompt(`Press enter to open the browser and sign in to TinyFish for ${DISPLAY_NAMES[harness]}... `);
@@ -130,8 +142,10 @@ async function processHarness(detection, opts, prompt) {
     }
     // runGuarded swallows Ctrl+C and sets exitCode 130 instead of throwing.
     const interruptedBefore = process.exitCode === 130;
+    let authMode;
     try {
-        await runHarnessConnect(harness, opts);
+        // Headless: an install too old for key auth must fail, not open a browser.
+        authMode = await runHarnessConnect(harness, opts, !isTTY);
     }
     catch (e) {
         return {
@@ -144,7 +158,9 @@ async function processHarness(detection, opts, prompt) {
     if (!interruptedBefore && process.exitCode === 130) {
         return { ...base, outcome: "interrupted", fixCommand: `tinyfish connect ${harness}` };
     }
-    const verify = await verifyHarness(harness, opts.mcpUrl, validatedApiKey(opts.apiKey));
+    // The probe, not the flag, decides: a harness that degraded to OAuth is not key-authed.
+    const keyAuthed = authMode ? authMode === "api-key" : keyed;
+    const verify = await verifyHarness(harness, opts.mcpUrl, keyAuthed, apiKey);
     return {
         ...base,
         installed: true,
@@ -152,6 +168,7 @@ async function processHarness(detection, opts, prompt) {
         verifyDepth: verify.depth,
         verifyOk: verify.ok,
         verifyReason: verify.reason,
+        keyAuthed,
     };
 }
 function summaryLine(result, uninstall) {
@@ -169,7 +186,10 @@ function summaryLine(result, uninstall) {
         return `… ${name} — ${result.fixCommand}`;
     }
     if (result.outcome === "no_tty_auth_skip") {
-        return `… ${name} — skipped, no stored credentials and no terminal to sign in. Fix: ${result.fixCommand}`;
+        const why = result.keyUnusable
+            ? `${name} cannot take an API key and there is no terminal to sign in`
+            : "no stored credentials and no terminal to sign in";
+        return `… ${name} — skipped, ${why}. Fix: ${result.fixCommand}`;
     }
     if (result.outcome === "uninstall_pointer") {
         return `… ${name} — not removed automatically (config is owned by ${name}). Run: ${result.fixCommand}`;
@@ -188,7 +208,8 @@ function summaryLine(result, uninstall) {
     if (result.outcome === "failed") {
         return `✗ ${name} — install failed: ${result.errorMessage}. Fix: ${result.fixCommand}`;
     }
-    const authDeferred = AUTH_DEFERRED_AT_INSTALL.has(result.harness);
+    // A keyed install has no sign-in left, so the deferred-auth warning would contradict it.
+    const authDeferred = AUTH_DEFERRED_AT_INSTALL.has(result.harness) && !result.keyAuthed;
     const verifyLabel = result.verifyDepth ? `verified: ${result.verifyDepth}` : "not verified";
     if (authDeferred || result.verifyOk === false) {
         const reason = authDeferred

package/dist/lib/connect-clients.d.ts

@@ -6,8 +6,12 @@ export declare const OPENCLAW_ONBOARDING_PROMPT: string;
 export interface NativeMcpClient extends SupportedCommand {
     connectClient: Exclude<AgentClient, "openclaw">;
     skillAgent: "claude-code" | "codex" | "hermes-agent" | "opencode";
-    /** `mcp add --header` support: a stored TinyFish key replaces the OAuth login. */
-    headerAuthSupported?: boolean;
+    /** Replaces `addArgs` when a stored key is available: key auth removes the OAuth hop. */
+    keyAuth?: {
+        /** Key reaches the client through TINYFISH_API_KEY, not argv. */
+        viaEnv?: boolean;
+        addArgs: (mcpUrl: string, apiKey: string) => string[];
+    };
     loginArgs?: string[];
     /** Replaces the `loginArgs` step when `supportCheck.optionalPatterns` miss. */
     degradedAuthNotes?: {
@@ -35,6 +39,8 @@ export declare function openExternalUrl(url: string): ReturnType<typeof spawn.sy
 export declare const CODEX: NativeMcpClient;
 export declare const HERMES: NativeMcpClient;
 export declare const OPENCODE: NativeMcpClient;
+/** Every native MCP client. Derive from this, so a new harness cannot be missed. */
+export declare const NATIVE_MCP_CLIENTS: readonly NativeMcpClient[];
 export declare const OPENCLAW: SupportedCommand;
 export declare function launchNativeMcpClient(client: NativeMcpClient): boolean;
 export declare function launchOpenClawWalkthrough(): boolean;

package/dist/lib/connect-clients.js

@@ -1,6 +1,6 @@
 import spawn from "cross-spawn";
 import { errLine, sanitizeLine } from "./output.js";
-import { throwIfInterrupted } from "./connect-runtime.js";
+import { spawnStepError, } from "./connect-runtime.js";
 import { codexOauthCompleted } from "./registration-detect.js";
 const HERMES_SEED_TIMEOUT_MS = 120_000;
 // An old install is only one reason a flag can go unseen, so no message asserts the cause.
@@ -54,6 +54,22 @@ export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill.
     "want to search and wait for my reply before using TinyFish Search. Show me the results, ask " +
     "which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task " +
     "I want to complete and wait before using TinyFish Agent. Never skip ahead or choose for me.";
+const HEADER_FLAG = /(?:^|\s)--header(?:[\s<=]|$)/m;
+const claudeAddArgs = (mcpUrl) => [
+    "mcp",
+    "add",
+    "--scope",
+    "user",
+    "--transport",
+    "http",
+    "tinyfish",
+    mcpUrl,
+];
+const urlAddArgs = (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl];
+// OpenCode takes `--header NAME=VALUE`, not Claude Code's `NAME: VALUE`.
+const headerKeyAuth = {
+    addArgs: (mcpUrl, apiKey) => [...urlAddArgs(mcpUrl), "--header", `X-API-Key=${apiKey}`],
+};
 export const CLAUDE_CODE = {
     command: "claude",
     connectClient: "claude-code",
@@ -63,9 +79,12 @@ export const CLAUDE_CODE = {
         args: ["mcp", "--help"],
         patterns: [/^\s*add(?:\s|\[)/m],
         optionalPatterns: [/^\s*login(?:\s|\[)/m],
+        keyAuthPattern: HEADER_FLAG,
         unavailableMessage: MCP_ADD_UNAVAILABLE_MESSAGE,
     },
-    headerAuthSupported: true,
+    keyAuth: {
+        addArgs: (mcpUrl, apiKey) => [...claudeAddArgs(mcpUrl), "--header", `X-API-Key: ${apiKey}`],
+    },
     loginArgs: ["mcp", "login", "tinyfish"],
     degradedAuthNotes: {
         keyed: CLAUDE_CODE_KEYED_FALLBACK_NOTE,
@@ -79,7 +98,7 @@ export const CLAUDE_CODE = {
             label: "local TinyFish registration",
         },
     ],
-    addArgs: (mcpUrl) => ["mcp", "add", "--scope", "user", "--transport", "http", "tinyfish", mcpUrl],
+    addArgs: (mcpUrl) => claudeAddArgs(mcpUrl),
 };
 /**
  * `cmd` re-parses its command line after `/c`, so an unquoted `&` in the query string ends the
@@ -103,7 +122,7 @@ function launchCodexWalkthrough() {
     deepLink.searchParams.set("path", process.cwd());
     const result = openExternalUrl(deepLink.toString());
     if (result.error || result.status !== 0) {
-        throw new Error("Could not open Codex", { cause: result.error });
+        throw spawnStepError("Could not open Codex", result);
     }
     errLine("Codex opened with the TinyFish walkthrough ready. Send the prompt to start.");
 }
@@ -115,22 +134,21 @@ export const CODEX = {
     supportCheck: {
         args: ["mcp", "add", "--help"],
         patterns: [/--oauth-resource(?:\s|<)/],
+        keyAuthPattern: /(?:^|\s)--bearer-token-env-var(?:[\s<=]|$)/m,
         unavailableMessage: CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE,
     },
+    // Codex has no `--header`; the MCP server takes a key as `Bearer sk-…`.
+    // Omitting `--oauth-resource` is what keeps `mcp add` from running OAuth.
+    keyAuth: {
+        viaEnv: true,
+        addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), "--bearer-token-env-var", "TINYFISH_API_KEY"],
+    },
     launchWalkthrough: launchCodexWalkthrough,
     probeAuthenticated: codexOauthCompleted,
     // Retry only: running it after a finished inline OAuth is a second browser hop.
     loginArgs: ["mcp", "login", "tinyfish"],
     removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
-    addArgs: (mcpUrl, oauthResource) => [
-        "mcp",
-        "add",
-        "tinyfish",
-        "--url",
-        mcpUrl,
-        "--oauth-resource",
-        oauthResource,
-    ],
+    addArgs: (mcpUrl, oauthResource) => [...urlAddArgs(mcpUrl), "--oauth-resource", oauthResource],
 };
 function launchHermesWalkthrough() {
     const seedResult = spawn.sync("hermes", ["chat", "-Q", "-q", DEFAULT_ONBOARDING_PROMPT], {
@@ -138,10 +156,7 @@ function launchHermesWalkthrough() {
         timeout: HERMES_SEED_TIMEOUT_MS,
     });
     if (seedResult.error || seedResult.status !== 0) {
-        throwIfInterrupted(seedResult);
-        throw new Error("Could not start the TinyFish walkthrough in Hermes", {
-            cause: seedResult.error,
-        });
+        throw spawnStepError("Could not start the TinyFish walkthrough in Hermes", seedResult);
     }
     // A colourised id would carry its trailing escape sequence into `--resume` (PF-3452).
     const sessionId = sanitizeLine(seedResult.stderr ?? "").match(/session_id:\s*([^\s]+)/i)?.[1];
@@ -150,12 +165,12 @@ function launchHermesWalkthrough() {
     }
     const result = spawn.sync("hermes", ["--resume", sessionId], { stdio: "inherit" });
     if (result.error) {
-        throw new Error("Could not launch Hermes", { cause: result.error });
+        throw spawnStepError("Could not launch Hermes", result);
     }
     if (result.signal === "SIGINT" || result.signal === "SIGTERM")
         return;
     if (result.status !== 0) {
-        throw new Error(`Hermes walkthrough exited with status ${result.status ?? "unknown"}`);
+        throw spawnStepError(`Hermes walkthrough exited with status ${result.status ?? "unknown"}`, result);
     }
 }
 export const HERMES = {
@@ -168,9 +183,10 @@ export const HERMES = {
         patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
         unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
     },
+    // No `keyAuth`: `hermes mcp add` has no --header, and `--auth header` prompts interactively.
     removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Hermes" }],
     // Hermes completes OAuth while adding the server; a separate `mcp login` would authenticate twice.
-    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl, "--auth", "oauth"],
+    addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), "--auth", "oauth"],
     launchWalkthrough: launchHermesWalkthrough,
 };
 // OpenCode's TUI takes a positional as a project directory, so a bare `opencode "<prompt>"`
@@ -181,12 +197,12 @@ function launchOpencode() {
         stdio: "inherit",
     });
     if (result.error) {
-        throw new Error("Could not launch OpenCode", { cause: result.error });
+        throw spawnStepError("Could not launch OpenCode", result);
     }
     if (result.signal === "SIGINT" || result.signal === "SIGTERM")
         return;
     if (result.status !== 0) {
-        throw new Error(`OpenCode exited with status ${result.status ?? "unknown"}`);
+        throw spawnStepError(`OpenCode exited with status ${result.status ?? "unknown"}`, result);
     }
 }
 export const OPENCODE = {
@@ -197,16 +213,25 @@ export const OPENCODE = {
     supportCheck: {
         args: ["mcp", "add", "--help"],
         patterns: [/--url(?:\s|$)/m],
+        keyAuthPattern: HEADER_FLAG,
         unavailableMessage: OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE,
     },
+    keyAuth: headerKeyAuth,
     // `opencode mcp add` upserts by name and there is no `opencode mcp remove`, so no cleanup step.
     removals: [],
     // OpenCode writes ~/.config/opencode/opencode.jsonc itself; `mcp auth` is the separate OAuth step.
-    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl],
+    addArgs: (mcpUrl) => urlAddArgs(mcpUrl),
     loginArgs: ["mcp", "auth", "tinyfish"],
     launchWalkthrough: launchOpencode,
     postConnectNote: OPENCODE_MODEL_NOTE,
 };
+/** Every native MCP client. Derive from this, so a new harness cannot be missed. */
+export const NATIVE_MCP_CLIENTS = [
+    CLAUDE_CODE,
+    CODEX,
+    HERMES,
+    OPENCODE,
+];
 export const OPENCLAW = {
     command: "openclaw",
     displayName: "OpenClaw",
@@ -224,12 +249,12 @@ export function launchNativeMcpClient(client) {
     }
     const result = spawn.sync(client.command, [DEFAULT_ONBOARDING_PROMPT], { stdio: "inherit" });
     if (result.error) {
-        throw new Error(`Could not launch ${client.displayName}`, { cause: result.error });
+        throw spawnStepError(`Could not launch ${client.displayName}`, result);
     }
     if (result.signal === "SIGINT" || result.signal === "SIGTERM")
         return false;
     if (result.status !== 0) {
-        throw new Error(`${client.displayName} walkthrough exited with status ${result.status ?? "unknown"}`);
+        throw spawnStepError(`${client.displayName} walkthrough exited with status ${result.status ?? "unknown"}`, result);
     }
     return true;
 }
@@ -239,12 +264,12 @@ export function launchOpenClawWalkthrough() {
         stdio: "inherit",
     });
     if (result.error) {
-        throw new Error("Could not launch OpenClaw", { cause: result.error });
+        throw spawnStepError("Could not launch OpenClaw", result);
     }
     if (result.signal === "SIGINT" || result.signal === "SIGTERM")
         return false;
     if (result.status !== 0) {
-        throw new Error(`OpenClaw walkthrough exited with status ${result.status ?? "unknown"}`);
+        throw spawnStepError(`OpenClaw walkthrough exited with status ${result.status ?? "unknown"}`, result);
     }
     return true;
 }

package/dist/lib/connect-install.js

@@ -1,9 +1,10 @@
 import * as path from "node:path";
 import spawn from "cross-spawn";
 import { loadConfig, persistApiKeyToEnvironment, validateKeyFormat, writeConfig } from "./auth.js";
-import { CLAUDE_CODE, CODEX, HERMES, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, } from "./connect-clients.js";
-import { commandNotFound, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "./connect-runtime.js";
+import { NATIVE_MCP_CLIENTS, OPENCLAW_SKILL_INSTALL_ARGS, } from "./connect-clients.js";
+import { commandNotFound, ConnectStepError, spawnStepError, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "./connect-runtime.js";
 import { TINYFISH_CLI_PACKAGE } from "./constants.js";
+import { installRoot } from "./install-root.js";
 import { errLine } from "./output.js";
 export const SKILL_INSTALL_TIMEOUT_MS = 120_000;
 export const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
@@ -15,13 +16,15 @@ const TINYFISH_WEB_SKILL_SOURCE = "tinyfish-io/tinyfish-cookbook";
 const TINYFISH_WEB_SKILL = "use-tinyfish";
 export function installTinyFishCli() {
     errLine("Installing the TinyFish CLI...");
-    const result = spawn.sync("npm", ["install", "--global", TINYFISH_CLI_INSTALL_SPEC], {
+    // Without the prefix, a curl install upgrades npm's global tree and never the PATH binary.
+    const root = installRoot();
+    const prefixArgs = root ? ["--prefix", root.prefix] : [];
+    const result = spawn.sync("npm", ["install", "--global", ...prefixArgs, TINYFISH_CLI_INSTALL_SPEC], {
         stdio: "inherit",
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
     if (result.error || result.status !== 0) {
-        throwIfInterrupted(result);
-        throw new Error("Could not install the TinyFish CLI", { cause: result.error });
+        throw spawnStepError("Could not install the TinyFish CLI", result);
     }
 }
 /** `skills add` is an unconditional overwrite, so it doubles as the refresh path. */
@@ -68,10 +71,7 @@ export function installWebSkill(client) {
     if (output.trim())
         errLine(output.trimEnd());
     if (result.error || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output)) {
-        throwIfInterrupted(result);
-        throw new Error(`Could not install the TinyFish web skill in ${client.displayName}`, {
-            cause: result.error,
-        });
+        throw spawnStepError(`Could not install the TinyFish web skill in ${client.displayName}`, result);
     }
 }
 /**
@@ -85,7 +85,7 @@ export function installWebSkill(client) {
 export function updateWebSkill() {
     // One entry per `tinyfish connect <client>`, persisted by PF-3169.
     const connected = loadConfig().connect ?? {};
-    const skillAgents = [CLAUDE_CODE, CODEX, HERMES, OPENCODE]
+    const skillAgents = NATIVE_MCP_CLIENTS
         .filter((client) => connected[client.connectClient])
         .map((client) => client.skillAgent);
     const hasOpenClaw = Boolean(connected["openclaw"]);
@@ -160,7 +160,7 @@ export function ensureCliAuthenticated(source, apiKey) {
     const envKey = apiKey ?? process.env["TINYFISH_API_KEY"];
     if (envKey) {
         if (!validateKeyFormat(envKey)) {
-            throw new Error("TINYFISH_API_KEY has invalid format");
+            throw new ConnectStepError("TINYFISH_API_KEY has invalid format", "invalid_config");
         }
         // Throwing variant: a write failure must reach connect's catch/flush, not exit(1) past it.
         writeConfig(envKey);
@@ -172,7 +172,7 @@ export function ensureCliAuthenticated(source, apiKey) {
         timeout: NON_INTERACTIVE_TIMEOUT_MS,
     });
     if (commandNotFound(authStatus.error)) {
-        throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: authStatus.error });
+        throw spawnStepError(TINYFISH_CLI_NOT_FOUND_MESSAGE, authStatus);
     }
     if (authStatus.status === 0)
         return;
@@ -180,17 +180,16 @@ export function ensureCliAuthenticated(source, apiKey) {
     // "not signed in" and drop the user into an interactive login they never asked for.
     throwIfInterrupted(authStatus);
     if (authStatus.error) {
-        throw new Error("Could not read TinyFish CLI auth status", { cause: authStatus.error });
+        throw spawnStepError("Could not read TinyFish CLI auth status", authStatus);
     }
     errLine("Signing in to the TinyFish CLI...");
     const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", source], {
         stdio: "inherit",
     });
     if (commandNotFound(loginResult.error)) {
-        throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: loginResult.error });
+        throw spawnStepError(TINYFISH_CLI_NOT_FOUND_MESSAGE, loginResult);
     }
     if (loginResult.error || loginResult.status !== 0) {
-        throwIfInterrupted(loginResult);
-        throw new Error("Could not authenticate the TinyFish CLI", { cause: loginResult.error });
+        throw spawnStepError("Could not authenticate the TinyFish CLI", loginResult);
     }
 }

package/dist/lib/connect-runtime.d.ts

@@ -1,24 +1,43 @@
-import { type AuthMode } from "./registration-detect.js";
+import { AuthMode } from "./harness-detect.js";
 export declare const NON_INTERACTIVE_TIMEOUT_MS = 10000;
 export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openclaw" | "opencode";
 type ConnectStage = "started" | "checkpoint" | "completed" | "failed" | "aborted" | "post_install_failed";
 type ConnectFailureStage = "prerequisite_check" | "registration_cleanup" | "registration" | "registration_or_authentication" | "client_oauth" | "cli_install" | "skill_install" | "authentication" | "walkthrough_launch";
-type ConnectFailureReason = "harness_not_installed" | "harness_command_unsupported" | "harness_too_old";
-export type ConnectAuthMode = Extract<AuthMode, "oauth" | "api-key"> | "deferred";
+export declare const CONNECT_FAILURE_REASONS: readonly ["harness_not_installed", "harness_command_unsupported", "harness_too_old", "command_not_found", "timeout", "spawn_error", "nonzero_exit", "invalid_config"];
+type ConnectFailureReason = (typeof CONNECT_FAILURE_REASONS)[number];
+export type ConnectAuthMode = Exclude<AuthMode, AuthMode.Unknown> | "deferred";
 type ConnectCheckpoint = "prerequisite_ok" | "registered" | "oauth_done" | "cli_installed" | "skill_installed" | "authenticated";
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {
 }
+/** A classified step failure; runGuarded forwards the reason. */
+export declare class ConnectStepError extends Error {
+    readonly failureReason: ConnectFailureReason;
+    readonly harnessVersion?: string;
+    constructor(message: string, failureReason: ConnectFailureReason, opts?: {
+        harnessVersion?: string;
+        cause?: unknown;
+    });
+}
 export declare function throwIfInterrupted(result: {
     signal?: string | null;
     error?: Error;
 }): void;
+interface SpawnStepResult {
+    status?: number | null;
+    signal?: string | null;
+    error?: Error;
+}
+/** Classifies a spawn failure; interrupts throw instead. */
+export declare function spawnStepError(message: string, result: SpawnStepResult): ConnectStepError;
 export declare function commandNotFound(error: unknown): boolean;
 export interface ConnectRunState {
     stage: ConnectFailureStage;
     settled: boolean;
     /** On state, not per-call: otherwise degraded installs never appear to fail. */
     harnessDegraded?: boolean;
+    /** Resolved after the probe, so callers read real key use rather than key presence. */
+    authMode?: ConnectAuthMode;
 }
 interface ConnectStageDetail {
     failedStage?: ConnectFailureStage;
@@ -32,6 +51,7 @@ interface ConnectStageDetail {
 export interface ConnectTelemetry {
     attemptId: string;
     track(stage: ConnectStage, detail?: ConnectStageDetail): void;
+    setHarnessVersion(version?: string): void;
     flush(): Promise<void>;
 }
 /** Terminal events exactly once, whichever of flow or signal handler wins. */
@@ -47,11 +67,15 @@ export interface SupportedCommand {
         patterns: RegExp[];
         /** Missing → degrade to key or deferred auth, never refuse. */
         optionalPatterns?: RegExp[];
+        /** Missing → this install cannot take a stored key; fall back to OAuth. */
+        keyAuthPattern?: RegExp;
         unavailableMessage: string;
     };
 }
 export declare function requireCommandSupport(client: SupportedCommand): {
     optionalSupported: boolean;
+    keyAuthSupported: boolean;
+    harnessVersion?: string;
 };
 export declare function createConnectTelemetry(mcpUrl: string, client: AgentClient, opts?: {
     apiKey?: string;