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

package/README.md

@@ -40,6 +40,10 @@ One-command OAuth requires a Codex release whose `codex mcp add` command support
 `--oauth-resource`. Update Codex if support is unavailable, or add TinyFish manually with
 `codex mcp add`.
 
+With `--api-key`, Codex reads the key from `TINYFISH_API_KEY` instead of signing in — the command
+exports it to your shell profile, so restart Codex (or open a new terminal) before using it. Needs
+`codex mcp add --bearer-token-env-var`; without that flag the command falls back to OAuth.
+
 ### Connect Hermes
 
 Add TinyFish MCP and the global `use-tinyfish` web skill, authenticate the CLI, and start the
@@ -49,8 +53,10 @@ interactive walkthrough with one command:
 npx -y @tiny-fish/cli@latest connect hermes --launch --api-key sk-tinyfish-...
 ```
 
-Hermes completes OAuth while adding the MCP server. After setup, the command starts the walkthrough
-in a Hermes session and leaves that session open for your replies.
+Hermes completes OAuth while adding the MCP server. `hermes mcp add` accepts no header flag, so
+`--api-key` cannot replace the Hermes sign-in — its only header path, `--auth header`, prompts
+interactively. After setup, the command starts the walkthrough in a Hermes session and leaves that
+session open for your replies.
 
 ### Connect OpenClaw
 

package/dist/commands/connect.d.ts

@@ -1,17 +1,20 @@
 import { Command } from "commander";
-import { type AgentClient } from "../lib/connect-runtime.js";
+import { type AgentClient, type ConnectAuthMode } from "../lib/connect-runtime.js";
 export declare const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 interface NativeConnectOptions {
     apiKey?: string;
     mcpUrl: string;
     launch: boolean;
     attemptId?: string;
+    /** Headless: refuse rather than fall back to an unfinishable browser sign-in. */
+    keyAuthOnly?: boolean;
 }
-export declare function connectClaudeCode(options: NativeConnectOptions): Promise<void>;
-export declare function connectCodex(options: NativeConnectOptions): Promise<void>;
-export declare function connectHermes(options: NativeConnectOptions): Promise<void>;
-export declare function connectOpencode(options: NativeConnectOptions): Promise<void>;
+export declare function connectClaudeCode(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
+export declare function connectCodex(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
+export declare function connectHermes(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
+export declare function connectOpencode(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
 export declare function connectOpenClaw(options: {
+    apiKey?: string;
     mcpUrl: string;
     launch: boolean;
     installCli?: boolean;

package/dist/commands/connect.js

@@ -1,10 +1,11 @@
 import spawn from "cross-spawn";
-import { CONNECT_SOURCE, saveConnectContext, validateKeyFormat, validatedApiKey, } from "../lib/auth.js";
+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, TINYFISH_CLI_NOT_FOUND_MESSAGE, UPGRADE_HINT, } from "../lib/connect-install.js";
-import { commandNotFound, ConnectInterruptedError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
+import { ensureCliAuthenticated, installTinyFishCli, installWebSkill, SKILL_INSTALL_TIMEOUT_MS, UPGRADE_HINT, } from "../lib/connect-install.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,20 +23,49 @@ 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 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) {
+    try {
+        persistApiKeyToEnvironment(apiKey);
     }
-    throw new Error(`Could not remove existing ${removal.label}: ${details}`);
+    catch (error) {
+        errLine(`Could not export TINYFISH_API_KEY (${error instanceof Error ? error.message : String(error)}); ` +
+            "signing in instead.");
+        return false;
+    }
+    process.env["TINYFISH_API_KEY"] = apiKey;
+    errLine(`Exported TINYFISH_API_KEY to your shell profile — ${displayName} reads the key from there, ` +
+        "so restart it (or open a new terminal) before use.");
+    return true;
 }
 async function connectNativeMcpClient(client, options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, () => {
         telemetry.track("started");
-        const { optionalSupported } = 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);
+        let keyedAdd = storedKey && keyAuthSupported && client.keyAuth
+            ? { key: storedKey, spec: client.keyAuth }
+            : undefined;
+        // Before the removals: a failed export must not strand the old registration.
+        if (keyedAdd?.spec.viaEnv && !exportApiKey(keyedAdd.key, client.displayName)) {
+            keyedAdd = undefined;
+        }
+        const useKeyAuth = !!keyedAdd;
+        if (options.keyAuthOnly && !useKeyAuth) {
+            // No keyAuth at all is structural (Hermes); a missing flag is just an old install.
+            throw new Error(client.keyAuth
+                ? `This ${client.displayName} install cannot take a TinyFish API key, and signing in ` +
+                    `needs a terminal. Update it, then re-run: tinyfish connect ${client.connectClient}`
+                : `${client.displayName} cannot take a TinyFish API key, and signing in needs a ` +
+                    `terminal. Run: tinyfish connect ${client.connectClient}`);
+        }
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
         state.stage = "registration_cleanup";
         for (const removal of client.removals)
@@ -44,9 +74,6 @@ async function connectNativeMcpClient(client, options) {
         mcpUrl.searchParams.set("source", CONNECT_SOURCE);
         mcpUrl.searchParams.set("client", client.connectClient);
         mcpUrl.searchParams.set("connect_attempt_id", telemetry.attemptId);
-        // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
-        const storedKey = validatedApiKey(options.apiKey);
-        const useKeyAuth = client.headerAuthSupported === true && !!storedKey;
         // Undefining `loginArgs` reuses the deferred-auth path codex/hermes already take.
         const loginDegraded = state.harnessDegraded === true;
         const loginArgs = loginDegraded ? undefined : client.loginArgs;
@@ -54,19 +81,15 @@ async function connectNativeMcpClient(client, options) {
         state.stage =
             loginArgs && !client.probeAuthenticated ? "registration" : "registration_or_authentication";
         errLine(`Adding TinyFish to ${client.displayName}...`);
-        const addResult = spawn.sync(client.command, [
-            ...client.addArgs(mcpUrl.toString(), options.mcpUrl),
-            // Key rides argv — readable via /proc/<pid>/cmdline. Accepted because these CLIs
-            // take headers no other way.
-            ...(useKeyAuth ? ["--header", `X-API-Key: ${storedKey}`] : []),
-        ], {
+        // Header keys ride argv (/proc/<pid>/cmdline); these CLIs take headers no other way.
+        const addArgs = keyedAdd
+            ? keyedAdd.spec.addArgs(mcpUrl.toString(), keyedAdd.key)
+            : client.addArgs(mcpUrl.toString(), options.mcpUrl);
+        const addResult = spawn.sync(client.command, addArgs, {
             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
@@ -92,23 +115,22 @@ 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 });
         runPostInstallSteps(client, options, state, telemetry, signInDeferred);
     });
+    return state.authMode;
 }
 function connectedLine(client, signInDeferred) {
     // The CLI never observes deferred auth, so don't claim "connected".
@@ -150,23 +172,26 @@ 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)}`);
     }
     errLine(`Finish setup with: npx -y @tiny-fish/cli@latest connect ${connectClient}`);
 }
 export async function connectClaudeCode(options) {
-    await connectNativeMcpClient(CLAUDE_CODE, options);
+    return connectNativeMcpClient(CLAUDE_CODE, options);
 }
 export async function connectCodex(options) {
-    await connectNativeMcpClient(CODEX, options);
+    return connectNativeMcpClient(CODEX, options);
 }
 export async function connectHermes(options) {
-    await connectNativeMcpClient(HERMES, options);
+    return connectNativeMcpClient(HERMES, options);
 }
 export async function connectOpencode(options) {
-    await connectNativeMcpClient(OPENCODE, options);
+    return connectNativeMcpClient(OPENCODE, options);
 }
 export async function connectOpenClaw(options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, "openclaw", options);
@@ -178,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";
@@ -192,35 +217,12 @@ 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.
         state.stage = "authentication";
-        const authStatus = spawn.sync("tinyfish", ["auth", "status"], {
-            stdio: "ignore",
-            timeout: NON_INTERACTIVE_TIMEOUT_MS,
-        });
-        if (commandNotFound(authStatus.error)) {
-            throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: authStatus.error });
-        }
-        if (authStatus.status !== 0) {
-            errLine("Signing in to TinyFish...");
-            const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", "openclaw"], {
-                stdio: "inherit",
-            });
-            if (commandNotFound(loginResult.error)) {
-                throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: loginResult.error });
-            }
-            if (loginResult.error || loginResult.status !== 0) {
-                throwIfInterrupted(loginResult);
-                throw new Error("Could not authenticate TinyFish for OpenClaw", {
-                    cause: loginResult.error,
-                });
-            }
-        }
+        ensureCliAuthenticated("openclaw", options.apiKey);
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("openclaw", telemetry.attemptId);
         errLine(UPGRADE_HINT);
@@ -269,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}`);
@@ -297,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. */
@@ -400,6 +402,8 @@ export function registerConnect(program) {
             mcpUrl,
             launch: options.launch ?? false,
             attemptId,
+            // A key that the install cannot use leaves only a browser hop no agent can finish.
+            keyAuthOnly: !detectHumanInitiated() && !!validatedApiKey(options.apiKey),
         };
         if (client === "claude-code") {
             await connectClaudeCode(connectOptions);

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/commands/upgrade.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
-export declare function runUpgrade(): void;
+/** Returns the version now installed, so the caller reports exactly what the user was told. */
+export declare function runUpgrade(): string | null;
 /** `runUpgrade` plus its outcome telemetry, which must never change what the upgrade does. */
 export declare function runUpgradeCommand(): Promise<void>;
 export declare function registerUpgrade(program: Command): void;

package/dist/commands/upgrade.js

@@ -1,6 +1,7 @@
 import spawn from "cross-spawn";
 import { resolvedApiKey } from "../lib/auth.js";
 import { CLI_VERSION, TINYFISH_CLI_PACKAGE } from "../lib/constants.js";
+import { installRoot, readInstalledVersion } from "../lib/install-root.js";
 import { suppressNotice } from "../lib/notice.js";
 import { errLine } from "../lib/output.js";
 import { sendUpgradeCompleted, telemetryDisabled, } from "../lib/setup-telemetry.js";
@@ -24,6 +25,7 @@ function attempt(label, run) {
         return message;
     }
 }
+/** Returns the version now installed, so the caller reports exactly what the user was told. */
 export function runUpgrade() {
     errLine("Upgrading TinyFish...");
     try {
@@ -40,12 +42,21 @@ export function runUpgrade() {
             throw error;
         errLine(INTERRUPTED_MESSAGE);
         process.exitCode = SIGNAL_EXIT_CODES.SIGINT;
-        return;
+        return null;
     }
-    errLine("TinyFish is up to date. Restart your agent to pick up the refreshed skill.");
+    const version = installedCliVersion();
+    errLine(version
+        ? `TinyFish CLI ${version} is up to date. Restart your agent to pick up the refreshed skill.`
+        : "TinyFish is up to date. Restart your agent to pick up the refreshed skill.");
+    return version;
 }
 /** The version now on disk. Only the upgrade's own npm call knows what "latest" resolved to. */
 function installedCliVersion() {
+    const root = installRoot();
+    return (root ? readInstalledVersion(root.nodeModules) : null) ?? globalCliVersion();
+}
+/** Fallback when no prefix was detected: npm's own global tree is the only place left to look. */
+function globalCliVersion() {
     try {
         const result = spawn.sync("npm", ["ls", "--global", "--depth=0", "--json", TINYFISH_CLI_PACKAGE], { encoding: "utf8", timeout: VERSION_READ_TIMEOUT_MS });
         const parsed = JSON.parse(result.stdout ?? "");
@@ -60,17 +71,17 @@ export async function runUpgradeCommand() {
     // This command is the upgrade, so a trailing "an update is available" would be noise.
     suppressNotice();
     let reported = false;
+    let printedVersion = null;
     // Read on the failed path too: a failed skill refresh still leaves an upgraded CLI, so
     // `outcome` reports whether every step ran and `to_version` whether the binary moved.
     const report = async (outcome) => {
         if (reported)
             return;
         reported = true;
-        // Ahead of the version and key reads; an opted-out run does neither.
         if (telemetryDisabled())
             return;
         // Interrupted skips the read — racing the exit. Undercounts; see posthog-events.md.
-        const toVersion = outcome === "interrupted" ? null : installedCliVersion();
+        const toVersion = outcome === "interrupted" ? null : (printedVersion ?? installedCliVersion());
         await sendUpgradeCompleted(CLI_VERSION, toVersion, outcome, resolvedApiKey());
     };
     const uninstallSignalGuard = installSignalGuard(async () => {
@@ -79,7 +90,7 @@ export async function runUpgradeCommand() {
     });
     let outcome = "updated";
     try {
-        runUpgrade();
+        printedVersion = runUpgrade();
         if (process.exitCode === SIGNAL_EXIT_CODES.SIGINT)
             outcome = "interrupted";
     }

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)