@tiny-fish/cli 0.20.2-next.190 → 0.21.1-next.194

package/dist/commands/connect.js

@@ -2,9 +2,10 @@ import spawn from "cross-spawn";
 import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, } from "../lib/auth.js";
 import { CLAUDE_CODE, CODEX, HERMES, OPENCLAW, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, launchNativeMcpClient, launchOpenClawWalkthrough, openExternalUrl, } from "../lib/connect-clients.js";
 import { ensureCliAuthenticated, installTinyFishCli, installWebSkill, SKILL_INSTALL_TIMEOUT_MS, UPGRADE_HINT, } from "../lib/connect-install.js";
-import { ConnectInterruptedError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
+import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, spawnStepError, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
 import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig, } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
+import { AuthMode } from "../lib/harness-detect.js";
 import { detectHumanInitiated } from "../lib/harness.js";
 import { emitNotice } from "../lib/notice.js";
 import { errLine } from "../lib/output.js";
@@ -22,12 +23,7 @@ function removeExistingRegistration(client, removal) {
     const details = result.stderr?.trim() || result.error?.message || "unknown error";
     if (/No MCP server named "tinyfish"/i.test(details))
         return;
-    if (result.error) {
-        throw new Error(`Could not remove existing ${removal.label}: ${details}`, {
-            cause: result.error,
-        });
-    }
-    throw new Error(`Could not remove existing ${removal.label}: ${details}`);
+    throw spawnStepError(`Could not remove existing ${removal.label}: ${details}`, result);
 }
 /** false: fall back to OAuth — a config naming an unset variable authenticates nothing. */
 function exportApiKey(apiKey, displayName) {
@@ -49,7 +45,8 @@ async function connectNativeMcpClient(client, options) {
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, () => {
         telemetry.track("started");
-        const { optionalSupported, keyAuthSupported } = requireCommandSupport(client);
+        const { optionalSupported, keyAuthSupported, harnessVersion } = requireCommandSupport(client);
+        telemetry.setHarnessVersion(harnessVersion);
         state.harnessDegraded = !!client.loginArgs && !optionalSupported;
         // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
         const storedKey = validatedApiKey(options.apiKey);
@@ -92,10 +89,7 @@ async function connectNativeMcpClient(client, options) {
             stdio: "inherit",
         });
         if (addResult.error || addResult.status !== 0) {
-            throwIfInterrupted(addResult);
-            throw new Error(`Could not add TinyFish to ${client.displayName}`, {
-                cause: addResult.error,
-            });
+            throw spawnStepError(`Could not add TinyFish to ${client.displayName}`, addResult);
         }
         telemetry.track("checkpoint", { phase: "registered" });
         // Codex runs OAuth inside `mcp add` and exits 0 either way, so the recorded state decides
@@ -121,19 +115,16 @@ async function connectNativeMcpClient(client, options) {
                 stdio: "inherit",
             });
             if (loginResult.error || loginResult.status !== 0) {
-                throwIfInterrupted(loginResult);
-                throw new Error(`Could not authenticate TinyFish in ${client.displayName}`, {
-                    cause: loginResult.error,
-                });
+                throw spawnStepError(`Could not authenticate TinyFish in ${client.displayName}`, loginResult);
             }
             telemetry.track("checkpoint", { phase: "oauth_done" });
         }
         const signInDeferred = !useKeyAuth && !addSignedIn && !pendingLogin;
         const authMode = useKeyAuth
-            ? "api-key"
+            ? AuthMode.ApiKey
             : signInDeferred
                 ? "deferred"
-                : "oauth";
+                : AuthMode.OAuth;
         state.authMode = authMode;
         // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
         settle(state, telemetry, "completed", { authMode });
@@ -181,7 +172,10 @@ function runPostInstallSteps(client, options, state, telemetry, signInDeferred)
 /** Warn + report post_install_failed; interrupts are abandonment, not failure. */
 function reportPostInstallFailure(connectClient, displayName, state, telemetry, error) {
     if (!(error instanceof ConnectInterruptedError)) {
-        telemetry.track("post_install_failed", { failedStage: state.stage });
+        telemetry.track("post_install_failed", {
+            failedStage: state.stage,
+            ...(error instanceof ConnectStepError ? { failureReason: error.failureReason } : {}),
+        });
         errLine(`The ${displayName} MCP connection succeeded, but a finishing step ` +
             `(${state.stage}) failed: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -209,7 +203,7 @@ export async function connectOpenClaw(options) {
     };
     await runGuarded(state, telemetry, () => {
         telemetry.track("started");
-        requireCommandSupport(OPENCLAW);
+        telemetry.setHarnessVersion(requireCommandSupport(OPENCLAW).harnessVersion);
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
         if (options.installCli !== false) {
             state.stage = "cli_install";
@@ -223,10 +217,7 @@ export async function connectOpenClaw(options) {
             timeout: SKILL_INSTALL_TIMEOUT_MS,
         });
         if (skillInstallResult.error || skillInstallResult.status !== 0) {
-            throwIfInterrupted(skillInstallResult);
-            throw new Error("Could not install the TinyFish skill in OpenClaw", {
-                cause: skillInstallResult.error,
-            });
+            throw spawnStepError("Could not install the TinyFish skill in OpenClaw", skillInstallResult);
         }
         telemetry.track("checkpoint", { phase: "skill_installed" });
         // Stores the key before probing, so a passed --api-key never reaches an interactive login.
@@ -280,8 +271,8 @@ export async function connectCursor(options) {
         // Attempt id rides telemetry only; persisting it would break idempotency.
         const result = writeCursorMcpConfig(mcpUrl.toString(), resolvedKey);
         if (result.status === "corrupt_skip") {
-            throw new Error(`Could not update ${cursorMcpPath()}: existing file could not be read or is not valid JSON (${result.error}). ` +
-                `Fix the file, then re-run: tinyfish connect cursor`);
+            throw new ConnectStepError(`Could not update ${cursorMcpPath()}: existing file could not be read or is not valid JSON (${result.error}). ` +
+                `Fix the file, then re-run: tinyfish connect cursor`, "invalid_config");
         }
         if (result.backupPath) {
             errLine(`Backed up existing Cursor MCP config to ${result.backupPath}`);
@@ -308,7 +299,7 @@ export async function connectCursor(options) {
         else {
             errLine("TinyFish is connected. Reload the Cursor window, then approve/sign in under Settings → MCP.");
         }
-        settle(state, telemetry, "completed", { authMode: resolvedKey ? "api-key" : "deferred" });
+        settle(state, telemetry, "completed", { authMode: resolvedKey ? AuthMode.ApiKey : "deferred" });
     });
 }
 /** Best-effort: false when no handler/open fails — caller falls back to reload copy. */

package/dist/commands/doctor.js

@@ -2,20 +2,22 @@ import spawn from "cross-spawn";
 import { apiKeyStatus } from "../lib/auth.js";
 import { CLI_VERSION } from "../lib/constants.js";
 import { DOCTOR_COULD_NOT_RUN, DOCTOR_SCHEMA_VERSION, doctorReportSchema, exitCodeFor, renderPretty, } from "../lib/doctor-report.js";
-import { ALL_HARNESSES } from "../lib/harness-detect.js";
+import { ALL_HARNESSES, AuthMode, Registered } from "../lib/harness-detect.js";
 import { detectHumanInitiated } from "../lib/harness.js";
 import { err, errLine, out, outLine } from "../lib/output.js";
 import { detectRegistrations } from "../lib/registration-detect.js";
 import { verifyMcpAuth, verifyMcpHealth } from "../lib/verify.js";
 import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectOpenClaw, connectOpencode, DEFAULT_MCP_URL, } from "./connect.js";
 // A green auth mode with a red auth call proves nothing, so the call's verdict gates the claim.
-function provesHarnessReach(status, authCallPassed, healthOk, mcpUrl) {
+function provesHarnessReach(status, keyAuth, healthOk, mcpUrl) {
     // An endpoint doctor could not reach proves nothing about a harness pointed at it.
     if (!healthOk)
         return false;
     if (pointsElsewhere(status.registeredUrl, mcpUrl))
         return false;
-    return status.registered === "yes" && status.authMode === "api-key" && authCallPassed;
+    return (status.registered === Registered.Yes &&
+        status.authMode === AuthMode.ApiKey &&
+        keyAuth?.ok === true);
 }
 // Reports the version, never judges it: staleness is the server's call via X-TF-Notice.
 function checkCliVersion() {
@@ -55,13 +57,31 @@ function pointsElsewhere(registeredUrl, mcpUrl) {
         return "an unparseable endpoint";
     }
 }
-function registrationVerdict(status, mcpUrl) {
+function keyedVerdict(keyAuth) {
+    if (!keyAuth)
+        return { status: "warn", detail: "registered, API key present but unverified" };
+    if (keyAuth.ok) {
+        return {
+            status: "pass",
+            detail: "registered, auth mode api-key (key verified against the TinyFish API)",
+        };
+    }
+    if (keyAuth.status === 401) {
+        return { status: "fail", detail: "registered, but TinyFish rejects its API key" };
+    }
+    // Only 401 blames the key; connect would loop on the rest.
+    if (keyAuth.status === 403) {
+        return { status: "warn", detail: "registered, but its API key is not allowed to list runs" };
+    }
+    return { status: "warn", detail: "registered, key could not be verified" };
+}
+function registrationVerdict(status, mcpUrl, keyAuth) {
     if (!status.detected)
         return { status: "skip", detail: "harness not installed" };
-    if (status.registered === "unknown") {
+    if (status.registered === Registered.Unknown) {
         return { status: "warn", detail: status.reason ?? "could not determine registration" };
     }
-    if (status.registered === "yes") {
+    if (status.registered === Registered.Yes) {
         // A `tinyfish` entry aimed at a dev server is registered and still cannot reach TinyFish.
         const elsewhere = pointsElsewhere(status.registeredUrl, mcpUrl);
         if (elsewhere) {
@@ -70,6 +90,9 @@ function registrationVerdict(status, mcpUrl) {
                 detail: `registered, but points at ${elsewhere} rather than ${endpointOf(mcpUrl)}`,
             };
         }
+        // Widening past api-key would warn every healthy oauth install.
+        if (status.authMode === AuthMode.ApiKey)
+            return keyedVerdict(keyAuth);
         // A probe that had to explain itself to reach `yes` is the only thing that explains `unknown`.
         const because = status.reason ? ` (${status.reason})` : "";
         return { status: "pass", detail: `registered, auth mode ${status.authMode}${because}` };
@@ -79,12 +102,12 @@ function registrationVerdict(status, mcpUrl) {
         ? { status: "fail", detail: "connected previously but TinyFish is no longer registered" }
         : { status: "warn", detail: "installed but TinyFish was never connected" };
 }
-function checkRegistration(status, mcpUrl) {
+function checkRegistration(status, mcpUrl, keyAuth) {
     return {
         id: "harness-registration",
         title: `${status.harness} registration`,
         harness: status.harness,
-        ...registrationVerdict(status, mcpUrl),
+        ...registrationVerdict(status, mcpUrl, keyAuth),
     };
 }
 function checkCredential() {
@@ -98,8 +121,8 @@ function checkCredential() {
     };
     return "key" in resolved ? { check, key: resolved.key } : { check };
 }
-async function checkAuthCall(key) {
-    if (!key) {
+function checkAuthCall(auth) {
+    if (!auth) {
         return {
             id: "cli-auth-call",
             title: "Authenticated call",
@@ -108,7 +131,6 @@ async function checkAuthCall(key) {
             harness: null,
         };
     }
-    const auth = await verifyMcpAuth(key);
     return {
         id: "cli-auth-call",
         title: "Authenticated call",
@@ -117,32 +139,37 @@ async function checkAuthCall(key) {
         harness: null,
     };
 }
+// `verifyMcpAuth` hits BASE_URL; a sandbox key 401s against prod.
+function isDefaultEndpoint(mcpUrl) {
+    try {
+        return endpointOf(mcpUrl) === endpointOf(DEFAULT_MCP_URL);
+    }
+    catch {
+        return false;
+    }
+}
+function verifyHarnessKey(status, cliKey, cliAuth, mcpUrl) {
+    if (!isDefaultEndpoint(mcpUrl))
+        return undefined;
+    // `pointsElsewhere` already fails; a second reason only misleads.
+    if (pointsElsewhere(status.registeredUrl, mcpUrl))
+        return undefined;
+    // OpenClaw's skill shells this CLI, so its verdict stands in.
+    if (status.harness === "openclaw")
+        return cliAuth;
+    if (!status.apiKey)
+        return undefined;
+    if (status.apiKey === cliKey && cliAuth)
+        return cliAuth;
+    return verifyMcpAuth(status.apiKey);
+}
 // Only Cursor's repair is a pure local file write; every other one needs a browser sign-in.
 const UNATTENDED_SAFE = new Set(["cursor"]);
 function repairsFor(checks, statuses) {
     const repairs = [];
-    const credentialResolves = checks.some((c) => c.id === "cli-credential" && c.status === "pass");
-    for (const status of statuses) {
-        // `unknown` earns nothing: running connect off a failed probe contradicts the check's detail.
-        // A registered-but-misaimed entry does earn one, since connect rewrites the URL.
-        const misaimed = checks.some((c) => c.harness === status.harness && c.status === "fail");
-        if (!status.detected || (status.registered !== "no" && !misaimed))
-            continue;
-        repairs.push({
-            for: status.registered === "yes"
-                ? `${status.harness}-points-elsewhere`
-                : status.connectedBefore
-                    ? `${status.harness}-registration-lost`
-                    : `${status.harness}-not-connected`,
-            action: "connect",
-            harness: status.harness,
-            command: `tinyfish connect ${status.harness}`,
-            // Without a credential even Cursor's repair shells an interactive `auth login`.
-            unattended_safe: UNATTENDED_SAFE.has(status.harness) && credentialResolves,
-        });
-    }
     // A revoked-but-well-formed key passes the credential check and fails the call; both need login.
     const credentialBroken = checks.some((c) => (c.id === "cli-credential" || c.id === "cli-auth-call") && c.status === "fail");
+    // connect writes the stored key, so replace a dead one first.
     if (credentialBroken) {
         repairs.push({
             for: "cli-credential-invalid",
@@ -152,26 +179,51 @@ function repairsFor(checks, statuses) {
             unattended_safe: false,
         });
     }
+    const authCallPassed = checks.some((c) => c.id === "cli-auth-call" && c.status === "pass");
+    for (const status of statuses) {
+        // `unknown` earns nothing: connect would contradict the check's detail.
+        // A registered entry that still fails earns one too.
+        const brokenRegistration = checks.some((c) => c.harness === status.harness && c.status === "fail");
+        if (!status.detected || (status.registered !== Registered.No && !brokenRegistration))
+            continue;
+        repairs.push({
+            for: status.registered === Registered.Yes
+                ? `${status.harness}-registration-broken`
+                : status.connectedBefore
+                    ? `${status.harness}-registration-lost`
+                    : `${status.harness}-not-connected`,
+            action: "connect",
+            harness: status.harness,
+            command: `tinyfish connect ${status.harness}`,
+            // A dead well-formed key passes the format check.
+            unattended_safe: UNATTENDED_SAFE.has(status.harness) && authCallPassed,
+        });
+    }
     return repairs;
 }
 export async function runDoctor(options) {
     const statuses = detectRegistrations(options.harness ? [options.harness] : undefined);
     const credential = checkCredential();
+    const cliAuth = credential.key ? verifyMcpAuth(credential.key) : undefined;
+    const [connectivity, cliAuthResult, keyAuths] = await Promise.all([
+        checkConnectivity(options.mcpUrl),
+        cliAuth,
+        Promise.all(statuses.map((status) => verifyHarnessKey(status, credential.key, cliAuth, options.mcpUrl))),
+    ]);
     const checks = [
         checkCliVersion(),
-        await checkConnectivity(options.mcpUrl),
-        ...statuses.map((status) => checkRegistration(status, options.mcpUrl)),
+        connectivity,
+        ...statuses.map((status, i) => checkRegistration(status, options.mcpUrl, keyAuths[i])),
         credential.check,
-        await checkAuthCall(credential.key),
+        checkAuthCall(cliAuthResult),
     ];
-    const authCallPassed = checks.some((c) => c.id === "cli-auth-call" && c.status === "pass");
     const healthOk = checks.some((c) => c.id === "mcp-connectivity" && c.status === "pass");
-    const harnesses = statuses.map((status) => ({
+    const harnesses = statuses.map((status, i) => ({
         harness: status.harness,
         detected: status.detected,
         registered: status.registered,
         auth_mode: status.authMode,
-        proves_harness_reach: provesHarnessReach(status, authCallPassed, healthOk, options.mcpUrl),
+        proves_harness_reach: provesHarnessReach(status, keyAuths[i], healthOk, options.mcpUrl),
     }));
     const body = {
         schema_version: DOCTOR_SCHEMA_VERSION,

package/dist/lib/auth.d.ts

@@ -36,6 +36,8 @@ export declare function persistApiKeyToEnvironment(apiKey: string, options?: Env
 export declare function clearConfig(): boolean;
 /** The one rule that is ours to enforce: the key becomes an HTTP header, so CR/LF cannot pass. */
 export declare function isHeaderSafe(key: string): boolean;
+/** No length rule: short real keys must survive. */
+export declare function hasKeyPrefix(key: string): boolean;
 export declare function validateKeyFormat(key: string): boolean;
 export declare function maskKey(key: string): string;
 export type KeySource = "explicit" | "env" | "config" | "none";

package/dist/lib/auth.js

@@ -192,8 +192,12 @@ export function isHeaderSafe(key) {
     }
     return true;
 }
+/** No length rule: short real keys must survive. */
+export function hasKeyPrefix(key) {
+    return KEY_PREFIXES.some((p) => key.startsWith(p));
+}
 export function validateKeyFormat(key) {
-    return isHeaderSafe(key) && KEY_PREFIXES.some((p) => key.startsWith(p)) && key.length > MIN_KEY_LENGTH;
+    return isHeaderSafe(key) && hasKeyPrefix(key) && key.length > MIN_KEY_LENGTH;
 }
 export function maskKey(key) {
     if (key.length <= 8)

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.
@@ -122,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.");
 }
@@ -156,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];
@@ -168,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 = {
@@ -200,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 = {
@@ -252,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;
 }
@@ -267,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

@@ -2,7 +2,7 @@ import * as path from "node:path";
 import spawn from "cross-spawn";
 import { loadConfig, persistApiKeyToEnvironment, validateKeyFormat, writeConfig } from "./auth.js";
 import { NATIVE_MCP_CLIENTS, OPENCLAW_SKILL_INSTALL_ARGS, } from "./connect-clients.js";
-import { commandNotFound, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "./connect-runtime.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";
@@ -24,8 +24,7 @@ export function installTinyFishCli() {
         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. */
@@ -72,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);
     }
 }
 /**
@@ -164,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);
@@ -176,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;
@@ -184,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,18 +1,35 @@
-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;
@@ -34,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. */
@@ -57,6 +75,7 @@ export interface SupportedCommand {
 export declare function requireCommandSupport(client: SupportedCommand): {
     optionalSupported: boolean;
     keyAuthSupported: boolean;
+    harnessVersion?: string;
 };
 export declare function createConnectTelemetry(mcpUrl: string, client: AgentClient, opts?: {
     apiKey?: string;

package/dist/lib/connect-runtime.js

@@ -7,10 +7,22 @@ import { errLine, sanitizeLine } from "./output.js";
 import { postConnectEvent, telemetryDisabled } from "./setup-telemetry.js";
 import { installSignalGuard } from "./signals.js";
 export const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
+// Mirrors the route's Zod enum; tests both sides pin it.
+export const CONNECT_FAILURE_REASONS = [
+    "harness_not_installed",
+    "harness_command_unsupported",
+    "harness_too_old",
+    "command_not_found",
+    "timeout",
+    "spawn_error",
+    "nonzero_exit",
+    "invalid_config",
+];
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export class ConnectInterruptedError extends Error {
 }
-class PrerequisiteError extends Error {
+/** A classified step failure; runGuarded forwards the reason. */
+export class ConnectStepError extends Error {
     failureReason;
     harnessVersion;
     constructor(message, failureReason, opts) {
@@ -19,6 +31,8 @@ class PrerequisiteError extends Error {
         this.harnessVersion = opts?.harnessVersion;
     }
 }
+class PrerequisiteError extends ConnectStepError {
+}
 export function throwIfInterrupted(result) {
     // spawn.sync kills a timed-out child with SIGTERM, so signal alone would misread a slow
     // network as the user walking away. A timeout is a failure and must report as one.
@@ -28,6 +42,19 @@ export function throwIfInterrupted(result) {
         throw new ConnectInterruptedError("Setup interrupted");
     }
 }
+/** Classifies a spawn failure; interrupts throw instead. */
+export function spawnStepError(message, result) {
+    throwIfInterrupted(result);
+    const code = result.error?.code;
+    const reason = !result.error
+        ? "nonzero_exit"
+        : code === "ENOENT"
+            ? "command_not_found"
+            : code === "ETIMEDOUT"
+                ? "timeout"
+                : "spawn_error";
+    return new ConnectStepError(message, reason, { cause: result.error });
+}
 export function commandNotFound(error) {
     return error?.code === "ENOENT";
 }
@@ -65,7 +92,7 @@ export async function runGuarded(state, telemetry, body) {
         }
         settle(state, telemetry, "failed", {
             failedStage: state.stage,
-            ...(error instanceof PrerequisiteError
+            ...(error instanceof ConnectStepError
                 ? { failureReason: error.failureReason, harnessVersion: error.harnessVersion }
                 : {}),
         });
@@ -88,7 +115,14 @@ export function requireCommandSupport(client) {
     }
     if (result.error || result.status !== 0) {
         throwIfInterrupted(result);
-        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
+        // A hung probe is a timeout, not a missing capability.
+        if (result.error?.code === "ETIMEDOUT") {
+            throw new ConnectStepError(client.supportCheck.unavailableMessage, "timeout", {
+                cause: result.error,
+            });
+        }
+        // It ran and exited non-zero, so the version is still answerable.
+        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error, harnessVersion: probeHarnessVersion(client.command) });
     }
     // Belt and braces with the colour env: a client that ignores NO_COLOR still has to match.
     const output = sanitizeLine(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
@@ -105,7 +139,7 @@ export function requireCommandSupport(client) {
             harnessVersion: probeHarnessVersion(client.command),
         });
     }
-    return { optionalSupported, keyAuthSupported };
+    return { optionalSupported, keyAuthSupported, harnessVersion: probeHarnessVersion(client.command) };
 }
 /** Best-effort; the server rejects non-printable characters and >32 chars. */
 function probeHarnessVersion(command) {
@@ -115,7 +149,9 @@ function probeHarnessVersion(command) {
     });
     if (result.error || result.status !== 0)
         return undefined;
+    // First line only: sanitizeLine keeps newlines, so stripping splices lines.
     const version = sanitizeLine(result.stdout ?? "")
+        .split("\n")[0]
         .replace(/[^\x20-\x7E]/g, "")
         .trim();
     return version ? version.slice(0, 32) : undefined;
@@ -140,6 +176,8 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
     const attemptId = opts?.attemptId ?? seeded ?? randomUUID();
     const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
     const pending = [];
+    let lastTrackAt;
+    let harnessVersion;
     async function deliver(body) {
         // Ahead of the key read; postConnectEvent's own opt-out check is too late to skip it.
         if (telemetryDisabled())
@@ -156,7 +194,14 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
     return {
         attemptId,
         // Fire-and-forget; awaiting each event stalls setup when telemetry down.
+        setHarnessVersion(version) {
+            harnessVersion = version;
+        },
         track(stage, detail) {
+            const now = Date.now();
+            // Clamped: a backward clock step would send a route-rejected negative.
+            const stageDurationMs = lastTrackAt === undefined ? undefined : Math.max(0, now - lastTrackAt);
+            lastTrackAt = now;
             // Absorbed here, not in flush: flush runs in runGuarded's finally, so a rejection would
             // replace the error the flow is already reporting.
             pending.push(deliver(JSON.stringify({
@@ -166,9 +211,10 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
                 failed_stage: detail?.failedStage,
                 phase: detail?.phase,
                 failure_reason: detail?.failureReason,
-                harness_version: detail?.harnessVersion,
+                harness_version: detail?.harnessVersion ?? harnessVersion,
                 auth_mode: detail?.authMode,
                 harness_degraded: detail?.harnessDegraded,
+                stage_duration_ms: stageDurationMs,
                 runtime_platform: process.platform,
                 node_version: process.version,
                 cli_version: CLI_VERSION,

package/dist/lib/cursor-config.d.ts

@@ -14,9 +14,10 @@ export interface CursorTinyfishEntry {
     hasApiKeyHeader: boolean;
     /** Registered endpoint, so a caller can tell "registered" from "registered at the right place". */
     url?: string;
+    apiKey?: string;
     error?: string;
 }
-/** Read-only probe for doctor — reports shape, never the header value. */
+/** Carries the header value; callers keep it off the report. */
 export declare function readCursorTinyfishEntry(): CursorTinyfishEntry;
 /** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
 export declare function writeCursorMcpConfig(mcpUrl: string, apiKey?: string): CursorMcpWriteResult;

package/dist/lib/cursor-config.js

@@ -65,7 +65,7 @@ export function planCursorWrite(mcpUrl, apiKey) {
         ? `${filePath}: would create with a "tinyfish" MCP server entry${authNote}`
         : `${filePath}: would back up to a timestamped copy, then merge in the "tinyfish" MCP server entry${authNote}`;
 }
-/** Read-only probe for doctor — reports shape, never the header value. */
+/** Carries the header value; callers keep it off the report. */
 export function readCursorTinyfishEntry() {
     const existing = readExisting();
     if ("error" in existing)
@@ -77,10 +77,13 @@ export function readCursorTinyfishEntry() {
     const headers = entry.headers;
     // Header names are case-insensitive, and this file is hand-editable — matching only the
     // casing we write would understate auth mode for a user who typed it differently.
+    const keyHeader = isPlainRecord(headers)
+        ? Object.entries(headers).find(([name, value]) => name.toLowerCase() === "x-api-key" && typeof value === "string")
+        : undefined;
     return {
         present: true,
-        hasApiKeyHeader: isPlainRecord(headers) &&
-            Object.entries(headers).some(([name, value]) => name.toLowerCase() === "x-api-key" && typeof value === "string"),
+        hasApiKeyHeader: keyHeader !== undefined,
+        ...(keyHeader ? { apiKey: keyHeader[1] } : {}),
         ...(typeof entry.url === "string" ? { url: entry.url } : {}),
     };
 }

package/dist/lib/doctor-report.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { AuthMode, Registered } from "./harness-detect.js";
 /** Bumped whenever a consumer could misread the payload; the cookbook skill releases separately. */
-export declare const DOCTOR_SCHEMA_VERSION = 1;
+export declare const DOCTOR_SCHEMA_VERSION = 2;
 declare const checkStatusSchema: z.ZodEnum<{
     pass: "pass";
     fail: "fail";
@@ -36,16 +37,8 @@ declare const doctorHarnessSchema: z.ZodObject<{
         "claude-code": "claude-code";
     }>;
     detected: z.ZodBoolean;
-    registered: z.ZodEnum<{
-        unknown: "unknown";
-        yes: "yes";
-        no: "no";
-    }>;
-    auth_mode: z.ZodEnum<{
-        unknown: "unknown";
-        "api-key": "api-key";
-        oauth: "oauth";
-    }>;
+    registered: z.ZodEnum<typeof Registered>;
+    auth_mode: z.ZodEnum<typeof AuthMode>;
     proves_harness_reach: z.ZodBoolean;
 }, z.core.$strip>;
 declare const doctorRepairSchema: z.ZodObject<{
@@ -98,16 +91,8 @@ export declare const doctorReportSchema: z.ZodObject<{
             "claude-code": "claude-code";
         }>;
         detected: z.ZodBoolean;
-        registered: z.ZodEnum<{
-            unknown: "unknown";
-            yes: "yes";
-            no: "no";
-        }>;
-        auth_mode: z.ZodEnum<{
-            unknown: "unknown";
-            "api-key": "api-key";
-            oauth: "oauth";
-        }>;
+        registered: z.ZodEnum<typeof Registered>;
+        auth_mode: z.ZodEnum<typeof AuthMode>;
         proves_harness_reach: z.ZodBoolean;
     }, z.core.$strip>>;
     repairs: z.ZodArray<z.ZodObject<{

package/dist/lib/doctor-report.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { ALL_HARNESSES } from "./harness-detect.js";
+import { ALL_HARNESSES, AuthMode, Registered } from "./harness-detect.js";
 /** Bumped whenever a consumer could misread the payload; the cookbook skill releases separately. */
-export const DOCTOR_SCHEMA_VERSION = 1;
+export const DOCTOR_SCHEMA_VERSION = 2;
 const checkStatusSchema = z.enum(["pass", "fail", "warn", "skip"]);
 const harnessSchema = z.enum(ALL_HARNESSES);
 const doctorCheckSchema = z.object({
@@ -14,8 +14,8 @@ const doctorCheckSchema = z.object({
 const doctorHarnessSchema = z.object({
     harness: harnessSchema,
     detected: z.boolean(),
-    registered: z.enum(["yes", "no", "unknown"]),
-    auth_mode: z.enum(["api-key", "oauth", "unknown"]),
+    registered: z.enum(Registered),
+    auth_mode: z.enum(AuthMode),
     proves_harness_reach: z.boolean(),
 });
 // `action` is what `--fix` dispatches on, not the harness field: keying off a null harness

package/dist/lib/harness-detect.d.ts

@@ -1,5 +1,15 @@
 export declare const ALL_HARNESSES: readonly ["claude-code", "codex", "cursor", "hermes", "openclaw", "opencode"];
 export type Harness = (typeof ALL_HARNESSES)[number];
+export declare enum Registered {
+    Yes = "yes",
+    No = "no",
+    Unknown = "unknown"
+}
+export declare enum AuthMode {
+    ApiKey = "api-key",
+    OAuth = "oauth",
+    Unknown = "unknown"
+}
 export declare function harnessConfigPath(harness: Harness): string;
 /** For reason strings that name a location; keeps them in sync with the table above. */
 export declare function harnessDisplayPath(harness: Harness): string;

package/dist/lib/harness-detect.js

@@ -9,6 +9,19 @@ export const ALL_HARNESSES = [
     "openclaw",
     "opencode",
 ];
+// Values are the wire contract; the report schema derives from these.
+export var Registered;
+(function (Registered) {
+    Registered["Yes"] = "yes";
+    Registered["No"] = "no";
+    Registered["Unknown"] = "unknown";
+})(Registered || (Registered = {}));
+export var AuthMode;
+(function (AuthMode) {
+    AuthMode["ApiKey"] = "api-key";
+    AuthMode["OAuth"] = "oauth";
+    AuthMode["Unknown"] = "unknown";
+})(AuthMode || (AuthMode = {}));
 // Presence detection only — dir existence means "installed", nothing more.
 const CONFIG_DIRS = {
     "claude-code": ".claude",

package/dist/lib/registration-detect.d.ts

@@ -1,6 +1,4 @@
-import { type Harness } from "./harness-detect.js";
-export type Registered = "yes" | "no" | "unknown";
-export type AuthMode = "api-key" | "oauth" | "unknown";
+import { AuthMode, type Harness, Registered } from "./harness-detect.js";
 export interface RegistrationStatus {
     harness: Harness;
     detected: boolean;
@@ -9,6 +7,8 @@ export interface RegistrationStatus {
     connectedBefore: boolean;
     /** The endpoint the harness is actually pointed at, when the probe exposes it. */
     registeredUrl?: string;
+    /** For doctor to verify; never for the report. */
+    apiKey?: string;
     reason?: string;
 }
 export declare function codexOauthCompleted(): boolean | undefined;

package/dist/lib/registration-detect.js

@@ -2,10 +2,10 @@ import * as fs from "fs";
 import * as path from "path";
 import spawn from "cross-spawn";
 import { z } from "zod";
-import { loadConfig } from "./auth.js";
+import { hasKeyPrefix, loadConfig } from "./auth.js";
 import { errLine } from "./output.js";
 import { readCursorTinyfishEntry } from "./cursor-config.js";
-import { detectInstalledHarnesses, harnessConfigPath, harnessDisplayPath, } from "./harness-detect.js";
+import { detectInstalledHarnesses, harnessConfigPath, harnessDisplayPath, AuthMode, Registered, } from "./harness-detect.js";
 // 6s tripped on a cold `hermes mcp list`, measured at 6.34s.
 const PROBE_TIMEOUT_MS = 15_000;
 // A list, verified against codex 0.146. A name-keyed map was accepted here too, but every
@@ -24,6 +24,12 @@ const UNSUPPORTED_SUBCOMMAND = /unknown command|unrecognized subcommand|invalid
 // `claude mcp get` exits 1 for a usage error too, so only this message is evidence of absence.
 const NO_SUCH_SERVER = /no (?:mcp )?server named/i;
 const API_KEY_HEADER = /x-api-key/i;
+// `claude mcp get` prints the value; `mcp add` masks it.
+const API_KEY_HEADER_VALUE = /^\s*X-API-Key:\s*(\S+)\s*$/im;
+// Charset is the redaction guard: `***`, `[REDACTED]`, dotted masks.
+function extractableKey(value) {
+    return value && hasKeyPrefix(value) && /^[A-Za-z0-9_-]+$/.test(value) ? value : undefined;
+}
 // OpenCode colours its list even through a pipe, putting `\x1b[34m` between the line start and
 // the server name, so an unstripped probe reads a registered harness as absent.
 // eslint-disable-next-line no-control-regex
@@ -84,8 +90,8 @@ function fromPluginRegistration(command) {
         return undefined;
     // `mcp list` prints no headers, so the credential behind it is unproven, never assumed.
     return {
-        registered: "yes",
-        authMode: "unknown",
+        registered: Registered.Yes,
+        authMode: AuthMode.Unknown,
         registeredUrl: match[2],
         reason: `registered as ${match[1]}, which \`mcp get tinyfish\` does not resolve`,
     };
@@ -94,13 +100,13 @@ function fromPluginRegistration(command) {
 function fromMcpGet(command, keyAuthPattern) {
     const probe = runProbe(command, ["mcp", "get", "tinyfish"]);
     if (probe.outcome === "unavailable") {
-        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason: probe.reason };
     }
     if (probe.exitCode !== 0) {
         if (UNSUPPORTED_SUBCOMMAND.test(probe.output)) {
             return {
-                registered: "unknown",
-                authMode: "unknown",
+                registered: Registered.Unknown,
+                authMode: AuthMode.Unknown,
                 reason: `\`${command} mcp get\` is unsupported by this version`,
             };
         }
@@ -111,20 +117,22 @@ function fromMcpGet(command, keyAuthPattern) {
         // A broken CLI also exits nonzero, and reading that as absence earns a spurious repair.
         if (!NO_SUCH_SERVER.test(probe.output)) {
             return {
-                registered: "unknown",
-                authMode: "unknown",
+                registered: Registered.Unknown,
+                authMode: AuthMode.Unknown,
                 reason: `\`${command} mcp get\` failed without reporting the server as absent`,
             };
         }
-        return { registered: "no", authMode: "unknown" };
+        return { registered: Registered.No, authMode: AuthMode.Unknown };
     }
     // Positive evidence only: whether `mcp get` echoes headers at all is unverified, so absence
     // of the pattern is `unknown`, never proof of OAuth.
     const url = /^\s*URL:\s*(\S+)/m.exec(probe.output)?.[1];
+    const key = extractableKey(API_KEY_HEADER_VALUE.exec(probe.output)?.[1]);
     return {
-        registered: "yes",
-        authMode: keyAuthPattern.test(probe.output) ? "api-key" : "unknown",
+        registered: Registered.Yes,
+        authMode: keyAuthPattern.test(probe.output) ? AuthMode.ApiKey : AuthMode.Unknown,
         ...(url ? { registeredUrl: url } : {}),
+        ...(key ? { apiKey: key } : {}),
     };
 }
 // `codex mcp get <missing>` prints an error and exits 0, so presence must never be read from
@@ -170,20 +178,20 @@ export function codexOauthCompleted() {
 function probeCodex() {
     const read = readCodexEntry();
     if ("reason" in read)
-        return { registered: "unknown", authMode: "unknown", reason: read.reason };
+        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason: read.reason };
     const entry = read.entry;
     if (!entry)
-        return { registered: "no", authMode: "unknown" };
+        return { registered: Registered.No, authMode: AuthMode.Unknown };
     const codexUrl = entry.transport?.url;
     return {
-        registered: "yes",
+        registered: Registered.Yes,
         // Read from this entry: codex emits `bearer_token_env_var` on every HTTP server, so testing
         // the whole payload reports api-key for TinyFish because some other server carries a key.
         authMode: entry.auth_status === "o_auth"
-            ? "oauth"
+            ? AuthMode.OAuth
             : entry.transport?.bearer_token_env_var
-                ? "api-key"
-                : "unknown",
+                ? AuthMode.ApiKey
+                : AuthMode.Unknown,
         ...(codexUrl ? { registeredUrl: codexUrl } : {}),
     };
 }
@@ -191,17 +199,19 @@ function probeCursor() {
     const entry = readCursorTinyfishEntry();
     if (entry.error) {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: "mcp.json exists but could not be read or parsed",
         };
     }
     if (!entry.present)
-        return { registered: "no", authMode: "unknown" };
+        return { registered: Registered.No, authMode: AuthMode.Unknown };
+    const key = extractableKey(entry.apiKey);
     return {
-        registered: "yes",
-        authMode: entry.hasApiKeyHeader ? "api-key" : "unknown",
+        registered: Registered.Yes,
+        authMode: entry.hasApiKeyHeader ? AuthMode.ApiKey : AuthMode.Unknown,
         ...(entry.url ? { registeredUrl: entry.url } : {}),
+        ...(key ? { apiKey: key } : {}),
     };
 }
 // Both list commands print this header in every state, including "no servers configured".
@@ -213,31 +223,31 @@ const OPENCODE_ROW_URL = /^[^\w]*tinyfish(?![\w-]).*\n[^\w]*(https?:\S+)/m;
 function fromMcpList(command, output, registeredMode, urlPattern) {
     if (LISTED_AS_TINYFISH.test(output)) {
         const url = urlPattern?.exec(output)?.[1];
-        return { registered: "yes", authMode: registeredMode, ...(url ? { registeredUrl: url } : {}) };
+        return { registered: Registered.Yes, authMode: registeredMode, ...(url ? { registeredUrl: url } : {}) };
     }
     if (!MCP_LIST_HEADER.test(output)) {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: `could not interpret \`${command} mcp list\` output`,
         };
     }
-    return { registered: "no", authMode: "unknown" };
+    return { registered: Registered.No, authMode: AuthMode.Unknown };
 }
 // connect only ever writes an OAuth Hermes entry, so `oauth` is a fact, not a detection gap.
 function probeHermes() {
     const probe = runProbe("hermes", ["mcp", "list"]);
     if (probe.outcome === "unavailable") {
-        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason: probe.reason };
     }
     if (probe.exitCode !== 0) {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: `\`hermes mcp list\` exited ${probe.exitCode}`,
         };
     }
-    return fromMcpList("hermes", probe.output, "oauth");
+    return fromMcpList("hermes", probe.output, AuthMode.OAuth);
 }
 const SKILL_DIR_IS_TINYFISH = /^(?:@tinyfish[/_-])?tinyfish(?![\w-])/i;
 // OpenClaw installs a skill, not an MCP server; the skill shells the CLI, so auth is the CLI key.
@@ -249,30 +259,30 @@ function probeOpenClaw() {
     }
     catch {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: `no global skills directory at ${harnessDisplayPath("openclaw")}/skills; OpenClaw layout is unverified`,
         };
     }
     // A bare substring also matched a skill merely named `not-tinyfish-thing`.
     return entries.some((name) => SKILL_DIR_IS_TINYFISH.test(name))
-        ? { registered: "yes", authMode: "api-key" }
-        : { registered: "no", authMode: "unknown" };
+        ? { registered: Registered.Yes, authMode: AuthMode.ApiKey }
+        : { registered: Registered.No, authMode: AuthMode.Unknown };
 }
 // `opencode mcp list` prints no headers, so a key-authed registration is indistinguishable.
 function probeOpencode() {
     const probe = runProbe("opencode", ["mcp", "list"]);
     if (probe.outcome === "unavailable") {
-        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason: probe.reason };
     }
     if (probe.exitCode !== 0) {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: `\`opencode mcp list\` exited ${probe.exitCode}`,
         };
     }
-    return fromMcpList("opencode", probe.output, "unknown", OPENCODE_ROW_URL);
+    return fromMcpList("opencode", probe.output, AuthMode.Unknown, OPENCODE_ROW_URL);
 }
 const PROBES = {
     "claude-code": () => fromMcpGet("claude", API_KEY_HEADER),
@@ -295,7 +305,7 @@ export function detectRegistrations(harnesses) {
         };
         // Undetected means nothing to probe: no spawn cost, and no misleading "unknown".
         if (!detection.detected) {
-            return { ...base, registered: "no", authMode: "unknown" };
+            return { ...base, registered: Registered.No, authMode: AuthMode.Unknown };
         }
         try {
             return { ...base, ...PROBES[detection.harness]() };
@@ -308,8 +318,8 @@ export function detectRegistrations(harnesses) {
             }
             return {
                 ...base,
-                registered: "unknown",
-                authMode: "unknown",
+                registered: Registered.Unknown,
+                authMode: AuthMode.Unknown,
                 reason: "the probe failed unexpectedly",
             };
         }

package/dist/lib/verify.d.ts

@@ -5,6 +5,8 @@ export interface VerifyResult {
     reason?: string;
     /** Authored summary of `reason`, safe to publish. Additive: `connect` still prints `reason`. */
     code?: string;
+    /** Lets doctor tell 401 from 403 without matching prose. */
+    status?: number;
 }
 /** Reachability check. Verify failure is a warning, never install failure. */
 export declare function verifyMcpHealth(mcpUrl: string): Promise<VerifyResult>;

package/dist/lib/verify.js

@@ -74,6 +74,7 @@ export async function verifyMcpAuth(apiKey) {
             ok: false,
             reason: e instanceof Error ? e.message : String(e),
             code: authCode(e),
+            ...(e instanceof ApiError ? { status: e.status } : {}),
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.20.2-next.190",
+  "version": "0.21.1-next.194",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {