@tiny-fish/cli 0.14.1-next.151 → 0.15.1-next.158

package/dist/commands/config-claude.js

@@ -1,5 +1,5 @@
 import { err, errLine, out } from "../lib/output.js";
-import { loadConfig, validateKeyFormat } from "../lib/auth.js";
+import { validatedApiKey } from "../lib/auth.js";
 import { readSettingsJson, writeSettingsJson, readClaudeMd, writeClaudeMd, mergeSettings, removeFromSettings, mergeClaudeMd, removeFromClaudeMd, claudeSettingsPath, claudeMdPath, isTinyfishConfiguredInSettings, isTinyfishConfiguredInClaudeMd, } from "../lib/claude-config.js";
 function loadExistingConfig() {
     let settings;
@@ -25,11 +25,7 @@ function loadExistingConfig() {
     return { settings, claudeMd };
 }
 function isSignedIn() {
-    const envKey = process.env.TINYFISH_API_KEY;
-    if (envKey && validateKeyFormat(envKey))
-        return true;
-    const config = loadConfig();
-    return !!config.api_key && validateKeyFormat(config.api_key);
+    return !!validatedApiKey();
 }
 function install(settings, claudeMd) {
     errLine("Configuring Claude Code to use TinyFish...\n");

package/dist/commands/connect.d.ts

@@ -7,6 +7,12 @@ export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openc
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {
 }
+interface NativeConnectOptions {
+    apiKey?: string;
+    mcpUrl: string;
+    launch: boolean;
+    attemptId?: string;
+}
 export declare function installTinyFishCli(): void;
 /**
  * Refresh the skill we installed, for the harnesses we installed it in.
@@ -17,35 +23,22 @@ export declare function installTinyFishCli(): void;
  * every agent on the machine).
  */
 export declare function updateWebSkill(): void;
-export declare function connectClaudeCode(options: {
-    apiKey?: string;
-    mcpUrl: string;
-    launch: boolean;
-}): Promise<void>;
-export declare function connectCodex(options: {
-    apiKey?: string;
-    mcpUrl: string;
-    launch: boolean;
-}): Promise<void>;
-export declare function connectHermes(options: {
-    apiKey?: string;
-    mcpUrl: string;
-    launch: boolean;
-}): Promise<void>;
-export declare function connectOpencode(options: {
-    apiKey?: string;
-    mcpUrl: string;
-    launch: boolean;
-}): Promise<void>;
+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 connectOpenClaw(options: {
     mcpUrl: string;
     launch: boolean;
     installCli?: boolean;
+    attemptId?: string;
 }): Promise<void>;
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export declare function connectCursor(options: {
     apiKey?: string;
     mcpUrl: string;
+    attemptId?: string;
 }): Promise<void>;
 export declare function launchAgent(client: AgentClient): void;
 export declare function registerConnect(program: Command): void;
+export {};

package/dist/commands/connect.js

@@ -1,13 +1,14 @@
 import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import spawn from "cross-spawn";
-import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, resolvedApiKey, saveConnectContext, validateKeyFormat, writeConfig, } from "../lib/auth.js";
+import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, resolvedApiKey, saveConnectContext, validateKeyFormat, validatedApiKey, writeConfig, } from "../lib/auth.js";
 import { CLI_VERSION, TINYFISH_CLI_PACKAGE } from "../lib/constants.js";
 import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig, } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
 import { detectHumanInitiated } from "../lib/harness.js";
 import { emitNotice } from "../lib/notice.js";
-import { errLine } from "../lib/output.js";
+import { errLine, sanitizeLine } from "../lib/output.js";
+import { z } from "zod";
 import { installSignalGuard } from "../lib/signals.js";
 import { postConnectEvent, telemetryDisabled } from "../lib/setup-telemetry.js";
 import { verifyMcpAuth } from "../lib/verify.js";
@@ -15,17 +16,29 @@ export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
 const SKILL_INSTALL_TIMEOUT_MS = 120_000;
 const HERMES_SEED_TIMEOUT_MS = 120_000;
-const MCP_LOGIN_UNAVAILABLE_MESSAGE = "This Claude Code installation does not expose `claude mcp login`, which is required for " +
-    "one-command MCP authentication. Update Claude Code and retry, or authenticate TinyFish " +
-    "manually from /mcp.";
-const CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE = "This Codex installation does not support one-command MCP authentication. Update Codex and " +
-    "retry, or add TinyFish manually with `codex mcp add`.";
-const HERMES_OAUTH_UNAVAILABLE_MESSAGE = "This Hermes installation does not support one-command MCP authentication. Update Hermes and " +
-    "retry, or add TinyFish manually with `hermes mcp add`.";
-const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = "This OpenClaw installation does not support global skill installation. Update OpenClaw and " +
-    "retry.";
-const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = "This OpenCode installation does not support one-command MCP setup (`opencode mcp add --url`). " +
-    "Update OpenCode and retry, or add TinyFish manually with `opencode mcp add`.";
+// An old install is only one reason a flag can go unseen, so no message asserts the cause.
+const SUPPORT_CHECK_DEBUG_HINT = " Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.";
+const MCP_LOGIN_UNAVAILABLE_MESSAGE = "Could not confirm this Claude Code installation exposes `claude mcp login`: `claude mcp " +
+    "--help` did not list it. Update Claude Code and retry, or authenticate TinyFish manually " +
+    "from /mcp." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE = "Could not confirm this Codex installation supports one-command MCP authentication: `codex " +
+    "mcp add --help` did not list `--oauth-resource`. Update Codex and retry, or add TinyFish " +
+    "manually with `codex mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const HERMES_OAUTH_UNAVAILABLE_MESSAGE = "Could not confirm this Hermes installation supports one-command MCP authentication: `hermes " +
+    "mcp add --help` did not list `--auth oauth`. Update Hermes and retry, or add TinyFish " +
+    "manually with `hermes mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = "Could not confirm this OpenClaw installation supports global skill installation: `openclaw " +
+    "skills install --help` did not list `--global` and `--acknowledge-clawhub-risk`. Update " +
+    "OpenClaw and retry, or install manually with `openclaw skills install @tinyfish/tinyfish " +
+    "--global --acknowledge-clawhub-risk`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = "Could not confirm this OpenCode installation supports one-command MCP setup: `opencode mcp " +
+    "add --help` did not list `--url`. Update OpenCode and retry, or add TinyFish manually with " +
+    "`opencode mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
 // OpenCode is model-agnostic (unlike Claude Code / Codex), so a fresh install can default to a
 // model with no tool support — TinyFish runs entirely on tool calls, so it would fail there.
 const OPENCODE_MODEL_NOTE = "Note: TinyFish runs on tool calls, so OpenCode needs a model that supports tool use. Image-only " +
@@ -58,6 +71,15 @@ export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill.
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export class ConnectInterruptedError extends Error {
 }
+class PrerequisiteError extends Error {
+    failureReason;
+    harnessVersion;
+    constructor(message, failureReason, opts) {
+        super(message, { cause: opts?.cause });
+        this.failureReason = failureReason;
+        this.harnessVersion = opts?.harnessVersion;
+    }
+}
 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.
@@ -78,14 +100,15 @@ function settle(state, telemetry, stage, detail) {
 // (npm/npx/OAuth waits) land here.
 function installConnectSignalGuard(state, telemetry) {
     return installSignalGuard(async () => {
-        if (state.settled)
-            return;
-        settle(state, telemetry, "aborted", { failedStage: state.stage });
-        errLine("Setup interrupted — run the command again to finish.");
+        if (!state.settled) {
+            settle(state, telemetry, "aborted", { failedStage: state.stage });
+            errLine("Setup interrupted — run the command again to finish.");
+        }
+        // Settled spans the whole post-install phase; the `completed` POST may still be in flight.
         await telemetry.flush();
     });
 }
-/** Shared terminal handling: interrupted → aborted (or completed post-install), else failed. */
+/** Shared terminal handling: interrupted → aborted, else failed. */
 async function runGuarded(state, telemetry, body) {
     const uninstallSignalGuard = installConnectSignalGuard(state, telemetry);
     try {
@@ -93,16 +116,17 @@ async function runGuarded(state, telemetry, body) {
     }
     catch (error) {
         if (error instanceof ConnectInterruptedError) {
-            if (state.stage === "walkthrough_launch") {
-                settle(state, telemetry, "completed");
-                return;
-            }
             settle(state, telemetry, "aborted", { failedStage: state.stage });
             errLine("Setup interrupted — run the command again to finish.");
             process.exitCode = 130;
             return;
         }
-        settle(state, telemetry, "failed", { failedStage: state.stage });
+        settle(state, telemetry, "failed", {
+            failedStage: state.stage,
+            ...(error instanceof PrerequisiteError
+                ? { failureReason: error.failureReason, harnessVersion: error.harnessVersion }
+                : {}),
+        });
         throw error;
     }
     finally {
@@ -180,7 +204,8 @@ function launchHermesWalkthrough() {
             cause: seedResult.error,
         });
     }
-    const sessionId = seedResult.stderr?.match(/session_id:\s*([^\s]+)/i)?.[1];
+    // 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];
     if (!sessionId) {
         throw new Error("Hermes did not return a walkthrough session ID");
     }
@@ -252,8 +277,9 @@ const OPENCLAW = {
         unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
     },
 };
-function createConnectTelemetry(mcpUrl, client, apiKey) {
-    const attemptId = randomUUID();
+function createConnectTelemetry(mcpUrl, client, opts) {
+    // A setup-page id (via --url) joins "copied the command" to this install attempt.
+    const attemptId = opts?.attemptId ?? randomUUID();
     const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
     const pending = [];
     async function deliver(body) {
@@ -265,7 +291,7 @@ function createConnectTelemetry(mcpUrl, client, apiKey) {
             endpoint,
             body,
             attempts: 2,
-            apiKey: resolvedApiKey(apiKey),
+            apiKey: resolvedApiKey(opts?.apiKey),
             label: "connect",
         });
     }
@@ -279,9 +305,13 @@ function createConnectTelemetry(mcpUrl, client, apiKey) {
                 stage,
                 failed_stage: detail?.failedStage,
                 phase: detail?.phase,
+                failure_reason: detail?.failureReason,
+                harness_version: detail?.harnessVersion,
                 runtime_platform: process.platform,
                 node_version: process.version,
                 cli_version: CLI_VERSION,
+                // Same signal the usage events carry, so TTY and headless connects can be split.
+                is_human_initiated: detectHumanInitiated(),
             })));
         },
         // Awaited in finally so in-flight events land before exit.
@@ -293,22 +323,41 @@ function createConnectTelemetry(mcpUrl, client, apiKey) {
 function requireCommandSupport(client) {
     const result = spawn.sync(client.command, client.supportCheck.args, {
         encoding: "utf8",
+        // Agent harnesses export FORCE_COLOR, which makes clients colourise even a piped --help.
+        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
         timeout: NON_INTERACTIVE_TIMEOUT_MS,
     });
     if (commandNotFound(result.error)) {
-        throw new Error(`${client.displayName} is not installed or not available on PATH.`, {
-            cause: result.error,
-        });
+        throw new PrerequisiteError(`${client.displayName} is not installed or not available on PATH.`, "harness_not_installed", { cause: result.error });
     }
     if (result.error || result.status !== 0) {
         throwIfInterrupted(result);
-        throw new Error(client.supportCheck.unavailableMessage, { cause: result.error });
+        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
     }
-    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+    // 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 ?? ""}`);
     if (!client.supportCheck.patterns.every((pattern) => pattern.test(output))) {
-        throw new Error(client.supportCheck.unavailableMessage);
+        if (process.env["TINYFISH_DEBUG"]) {
+            errLine(`${client.command} ${client.supportCheck.args.join(" ")} printed:\n${output.trim()}`);
+        }
+        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_too_old", {
+            harnessVersion: probeHarnessVersion(client.command),
+        });
     }
 }
+/** Best-effort; the server rejects non-printable characters and >32 chars. */
+function probeHarnessVersion(command) {
+    const result = spawn.sync(command, ["--version"], {
+        encoding: "utf8",
+        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0)
+        return undefined;
+    const version = sanitizeLine(result.stdout ?? "")
+        .replace(/[^\x20-\x7E]/g, "")
+        .trim();
+    return version ? version.slice(0, 32) : undefined;
+}
 function commandNotFound(error) {
     return error?.code === "ENOENT";
 }
@@ -530,7 +579,7 @@ function launchOpenClawWalkthrough() {
     return true;
 }
 async function connectNativeMcpClient(client, options) {
-    const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options.apiKey);
+    const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, () => {
         telemetry.track("started");
@@ -544,8 +593,8 @@ async function connectNativeMcpClient(client, options) {
         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 = options.apiKey ?? process.env["TINYFISH_API_KEY"] ?? loadConfig().api_key;
-        const useKeyAuth = client.headerAuthSupported === true && !!storedKey && validateKeyFormat(storedKey);
+        const storedKey = validatedApiKey(options.apiKey);
+        const useKeyAuth = client.headerAuthSupported === true && !!storedKey;
         state.stage = client.loginArgs ? "registration" : "registration_or_authentication";
         errLine(`Adding TinyFish to ${client.displayName}...`);
         const addResult = spawn.sync(client.command, [
@@ -580,6 +629,22 @@ async function connectNativeMcpClient(client, options) {
             }
             telemetry.track("checkpoint", { phase: "oauth_done" });
         }
+        // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
+        settle(state, telemetry, "completed");
+        runPostInstallSteps(client, options, state, telemetry, useKeyAuth);
+    });
+}
+function connectedLine(client, useKeyAuth) {
+    // Deferred OAuth (codex/hermes): the CLI never observes auth, so don't claim "connected".
+    if (!client.loginArgs && !useKeyAuth) {
+        return (`TinyFish is configured in ${client.displayName}. ${client.displayName} will ask you ` +
+            "to sign in to TinyFish the first time you use it.");
+    }
+    return `TinyFish is connected. Open ${client.displayName} to start using it.`;
+}
+// Runs after `completed` settled: failures warn and report post_install_failed, exit 0.
+function runPostInstallSteps(client, options, state, telemetry, useKeyAuth) {
+    try {
         state.stage = "cli_install";
         installTinyFishCli();
         telemetry.track("checkpoint", { phase: "cli_installed" });
@@ -596,15 +661,24 @@ async function connectNativeMcpClient(client, options) {
         if (client.postConnectNote)
             errLine(client.postConnectNote);
         if (!options.launch) {
-            errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
-            settle(state, telemetry, "completed");
+            errLine(connectedLine(client, useKeyAuth));
             return;
         }
         state.stage = "walkthrough_launch";
-        // Install already done; walkthrough Ctrl+C still counts completed.
         launchNativeMcpClient(client);
-        settle(state, telemetry, "completed");
-    });
+    }
+    catch (error) {
+        reportPostInstallFailure(client.connectClient, client.displayName, state, telemetry, error);
+    }
+}
+/** 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 });
+        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);
@@ -619,7 +693,7 @@ export async function connectOpencode(options) {
     await connectNativeMcpClient(OPENCODE, options);
 }
 export async function connectOpenClaw(options) {
-    const telemetry = createConnectTelemetry(options.mcpUrl, "openclaw");
+    const telemetry = createConnectTelemetry(options.mcpUrl, "openclaw", options);
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, () => {
         telemetry.track("started");
@@ -668,20 +742,24 @@ export async function connectOpenClaw(options) {
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("openclaw", telemetry.attemptId);
         errLine(UPGRADE_HINT);
+        // For openclaw the skill install and auth ARE functional; only the walkthrough is cosmetic.
+        settle(state, telemetry, "completed");
         if (!options.launch) {
             errLine("TinyFish is connected. Open OpenClaw to start using it.");
-            settle(state, telemetry, "completed");
             return;
         }
         state.stage = "walkthrough_launch";
-        // Install already done; walkthrough Ctrl+C still counts completed.
-        launchOpenClawWalkthrough();
-        settle(state, telemetry, "completed");
+        try {
+            launchOpenClawWalkthrough();
+        }
+        catch (error) {
+            reportPostInstallFailure("openclaw", "OpenClaw", state, telemetry, error);
+        }
     });
 }
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export async function connectCursor(options) {
-    const telemetry = createConnectTelemetry(options.mcpUrl, "cursor", options.apiKey);
+    const telemetry = createConnectTelemetry(options.mcpUrl, "cursor", options);
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, async () => {
         telemetry.track("started");
@@ -690,9 +768,11 @@ export async function connectCursor(options) {
         state.stage = "authentication";
         ensureCliAuthenticated("cursor", options.apiKey);
         telemetry.track("checkpoint", { phase: "authenticated" });
-        // loadConfig() is unvalidated on read — a hand-edited key must not reach mcp.json.
-        const storedKey = options.apiKey ?? process.env["TINYFISH_API_KEY"] ?? loadConfig().api_key;
-        const resolvedKey = storedKey && validateKeyFormat(storedKey) ? storedKey : undefined;
+        const resolvedKey = validatedApiKey(options.apiKey);
+        // ensureCliAuthenticated leaves a key stored, and `auth status` exits 0 on a malformed one.
+        if (!resolvedKey) {
+            errLine("Ignoring the stored API key: invalid format. Run: tinyfish auth login");
+        }
         state.stage = "registration";
         errLine("Adding TinyFish to Cursor...");
         const mcpUrl = new URL(options.mcpUrl);
@@ -784,7 +864,7 @@ export function registerConnect(program) {
         if (options.apiKey && !validateKeyFormat(options.apiKey)) {
             throw new Error("Invalid --api-key value");
         }
-        const mcpUrl = options.url ?? DEFAULT_MCP_URL;
+        let mcpUrl = options.url ?? DEFAULT_MCP_URL;
         if (mcpUrl.startsWith("-")) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
         }
@@ -798,6 +878,16 @@ export function registerConnect(program) {
         if (!["http:", "https:"].includes(parsedUrl.protocol)) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
         }
+        // Page-minted attempt id rides in on --url. Strip before the URL becomes the MCP
+        // base — registration re-stamps it, and nothing else may carry it.
+        const pageAttemptId = parsedUrl.searchParams.get("connect_attempt_id");
+        let attemptId;
+        if (pageAttemptId !== null) {
+            parsedUrl.searchParams.delete("connect_attempt_id");
+            mcpUrl = parsedUrl.toString();
+            if (z.uuid().safeParse(pageAttemptId).success)
+                attemptId = pageAttemptId;
+        }
         if (options.all) {
             if (client) {
                 throw new Error("Pass either a client or --all, not both.");
@@ -823,7 +913,12 @@ export function registerConnect(program) {
         if (!client) {
             throw new Error("Pass a client (claude-code, codex, cursor, hermes, openclaw) or --all.");
         }
-        const connectOptions = { apiKey: options.apiKey, mcpUrl, launch: options.launch ?? false };
+        const connectOptions = {
+            apiKey: options.apiKey,
+            mcpUrl,
+            launch: options.launch ?? false,
+            attemptId,
+        };
         if (client === "claude-code") {
             await connectClaudeCode(connectOptions);
         }
@@ -837,12 +932,12 @@ export function registerConnect(program) {
             await connectOpencode(connectOptions);
         }
         else if (client === "openclaw") {
-            await connectOpenClaw({ mcpUrl: connectOptions.mcpUrl, launch: connectOptions.launch });
+            await connectOpenClaw(connectOptions);
         }
         else if (client === "cursor") {
             // `connect <client> --launch` is the shape every doc uses; connect anyway, then say
             // why nothing launched rather than throwing away a working install.
-            await connectCursor({ apiKey: connectOptions.apiKey, mcpUrl: connectOptions.mcpUrl });
+            await connectCursor(connectOptions);
             if (connectOptions.launch) {
                 errLine("Cursor has no launchable walkthrough. Open Cursor and start chatting.");
             }

package/dist/lib/auth.d.ts

@@ -20,8 +20,26 @@ interface EnvironmentOptions {
 }
 export declare function persistApiKeyToEnvironment(apiKey: string, options?: EnvironmentOptions): void;
 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;
 export declare function validateKeyFormat(key: string): boolean;
 export declare function maskKey(key: string): string;
+export type KeySource = "explicit" | "env" | "config" | "none";
+export interface ResolvedKey {
+    key: string;
+    source: Exclude<KeySource, "none">;
+}
+export interface UnresolvedKey {
+    error: string;
+    source: KeySource;
+}
 /** Key for optional paths (telemetry, auth probes) — absent is a valid answer, so never exits. */
 export declare function resolvedApiKey(explicitApiKey?: string): string | undefined;
+/** resolvedApiKey for keys that reach a config file or the wire — loadConfig() is unvalidated on read. */
+export declare function validatedApiKey(explicitApiKey?: string): string | undefined;
+/**
+ * The diagnosis, not the key: doctor must report a bad credential and say where it came from
+ * rather than exit like getApiKey does.
+ */
+export declare function apiKeyStatus(): ResolvedKey | UnresolvedKey;
 export declare function getApiKey(): string;

package/dist/lib/auth.js

@@ -132,52 +132,62 @@ export function clearConfig() {
         return false;
     }
 }
-export function validateKeyFormat(key) {
-    // Reject control characters (covers CR, LF, and others) — guards against header injection
+/** The one rule that is ours to enforce: the key becomes an HTTP header, so CR/LF cannot pass. */
+export function isHeaderSafe(key) {
     for (let i = 0; i < key.length; i += 1) {
         if (key.charCodeAt(i) < 0x20)
             return false;
     }
-    return KEY_PREFIXES.some((p) => key.startsWith(p)) && key.length > MIN_KEY_LENGTH;
+    return true;
+}
+export function validateKeyFormat(key) {
+    return isHeaderSafe(key) && KEY_PREFIXES.some((p) => key.startsWith(p)) && key.length > MIN_KEY_LENGTH;
 }
 export function maskKey(key) {
     if (key.length <= 8)
         return "***";
     return key.slice(0, 12) + "..." + key.slice(-4);
 }
-/** Key for optional paths (telemetry, auth probes) — absent is a valid answer, so never exits. */
-export function resolvedApiKey(explicitApiKey) {
+// The one flag/env/config precedence chain; `source` says which place a caller must name.
+function lookupApiKey(explicitApiKey) {
     if (explicitApiKey)
-        return explicitApiKey;
+        return { value: explicitApiKey, source: "explicit" };
     const envKey = process.env["TINYFISH_API_KEY"];
     if (envKey)
-        return envKey;
-    try {
-        return loadConfig().api_key;
+        return { value: envKey, source: "env" };
+    // No try/catch: loadConfig swallows its own errors and returns {}.
+    const stored = loadConfig().api_key;
+    return stored ? { value: stored, source: "config" } : { source: "none" };
+}
+/** Key for optional paths (telemetry, auth probes) — absent is a valid answer, so never exits. */
+export function resolvedApiKey(explicitApiKey) {
+    return lookupApiKey(explicitApiKey).value;
+}
+/** resolvedApiKey for keys that reach a config file or the wire — loadConfig() is unvalidated on read. */
+export function validatedApiKey(explicitApiKey) {
+    const key = resolvedApiKey(explicitApiKey);
+    return key && validateKeyFormat(key) ? key : undefined;
+}
+/**
+ * The diagnosis, not the key: doctor must report a bad credential and say where it came from
+ * rather than exit like getApiKey does.
+ */
+export function apiKeyStatus() {
+    const { value, source } = lookupApiKey();
+    if (!value || source === "none") {
+        return { error: "No API key found. Run: tinyfish auth login", source: "none" };
     }
-    catch {
-        return undefined;
+    // Shape is the server's call. A local prefix rule turns a key format we have not shipped
+    // support for yet into a hard failure the user cannot work around, and the 401 says more.
+    if (!isHeaderSafe(value)) {
+        return { error: "The API key contains control characters and cannot be sent", source };
     }
+    return { key: value, source };
 }
 export function getApiKey() {
-    const envKey = process.env.TINYFISH_API_KEY;
-    if (envKey) {
-        if (!validateKeyFormat(envKey)) {
-            err({
-                error: "TINYFISH_API_KEY has invalid format. Expected sk-tinyfish-... or sk-mino-...",
-            });
-            process.exit(1);
-        }
-        return envKey;
-    }
-    const config = loadConfig();
-    if (config.api_key) {
-        if (!validateKeyFormat(config.api_key)) {
-            err({ error: "Stored API key has invalid format. Run: tinyfish auth login" });
-            process.exit(1);
-        }
-        return config.api_key;
-    }
-    err({ error: "No API key found. Run: tinyfish auth login" });
+    const resolved = apiKeyStatus();
+    if ("key" in resolved)
+        return resolved.key;
+    err({ error: resolved.error });
     process.exit(1);
 }

package/dist/lib/connect-all.js

@@ -1,7 +1,7 @@
 import * as readline from "node:readline/promises";
 import spawn from "cross-spawn";
 import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectOpenClaw, } from "../commands/connect.js";
-import { resolvedApiKey, validateKeyFormat } from "./auth.js";
+import { validatedApiKey } from "./auth.js";
 import { detectInstalledHarnesses, FIVE_HARNESSES, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
 import { emitNotice } from "./notice.js";
@@ -29,10 +29,6 @@ const UNINSTALL_POINTERS = {
     hermes: "hermes mcp remove tinyfish",
     openclaw: "openclaw skills uninstall @tinyfish/tinyfish --global",
 };
-function hasStoredAuth(explicitApiKey) {
-    const key = resolvedApiKey(explicitApiKey);
-    return !!key && validateKeyFormat(key);
-}
 async function runHarnessConnect(harness, opts) {
     const base = { apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false };
     if (harness === "claude-code")
@@ -102,7 +98,7 @@ async function processHarness(detection, opts, prompt) {
     if (opts.dryRun) {
         const plan = opts.uninstall
             ? uninstallPlanText(harness)
-            : planText(harness, opts.mcpUrl, resolvedApiKey(opts.apiKey));
+            : planText(harness, opts.mcpUrl, validatedApiKey(opts.apiKey));
         return { ...base, outcome: "dry_run", fixCommand: plan };
     }
     if (opts.uninstall)
@@ -110,7 +106,7 @@ async function processHarness(detection, opts, prompt) {
     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 = hasStoredAuth(opts.apiKey);
+    const keyed = !!validatedApiKey(opts.apiKey);
     const ownAuthHarness = HARNESS_OWN_AUTH.has(harness) && !(harness === "claude-code" && keyed);
     const alreadyAuthed = !ownAuthHarness && keyed;
     if (!isTTY && !alreadyAuthed) {
@@ -142,7 +138,7 @@ 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, resolvedApiKey(opts.apiKey));
+    const verify = await verifyHarness(harness, opts.mcpUrl, validatedApiKey(opts.apiKey));
     return {
         ...base,
         installed: true,
@@ -279,7 +275,7 @@ export async function runConnectAll(opts) {
             verify_depth: r.verifyDepth ?? null,
             verify_ok: r.verifyOk ?? null,
         }));
-        await sendSetupCompleted(opts.mcpUrl, harnessTelemetry, resolvedApiKey(opts.apiKey));
+        await sendSetupCompleted(opts.mcpUrl, harnessTelemetry, validatedApiKey(opts.apiKey));
         // After the summary and before the launch, which is where the user is reading.
         emitNotice();
     }

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

@@ -9,6 +9,15 @@ export interface CursorMcpWriteResult {
 }
 /** Dry-run description of the pending write; touches nothing. */
 export declare function planCursorWrite(mcpUrl: string, apiKey?: string): string;
+export interface CursorTinyfishEntry {
+    present: boolean;
+    hasApiKeyHeader: boolean;
+    /** Registered endpoint, so a caller can tell "registered" from "registered at the right place". */
+    url?: string;
+    error?: string;
+}
+/** Read-only probe for doctor — reports shape, never the header value. */
+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;
 /** Cursor deeplink format: cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64 */

package/dist/lib/cursor-config.js

@@ -65,6 +65,25 @@ 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. */
+export function readCursorTinyfishEntry() {
+    const existing = readExisting();
+    if ("error" in existing)
+        return { present: false, hasApiKeyHeader: false, error: existing.error };
+    const servers = existing.parsed.mcpServers;
+    const entry = isPlainRecord(servers) ? servers[TINYFISH_SERVER_KEY] : undefined;
+    if (!isPlainRecord(entry))
+        return { present: false, hasApiKeyHeader: false };
+    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.
+    return {
+        present: true,
+        hasApiKeyHeader: isPlainRecord(headers) &&
+            Object.entries(headers).some(([name, value]) => name.toLowerCase() === "x-api-key" && typeof value === "string"),
+        ...(typeof entry.url === "string" ? { url: entry.url } : {}),
+    };
+}
 // Backup, then atomic temp+rename; pid avoids same-millisecond backup collisions.
 function commitServers(filePath, existing, servers) {
     fs.mkdirSync(cursorConfigDir(), { recursive: true, mode: 0o700 });

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

@@ -1,6 +1,8 @@
 export declare const FIVE_HARNESSES: readonly ["claude-code", "codex", "cursor", "hermes", "openclaw"];
 export type FiveHarness = (typeof FIVE_HARNESSES)[number];
 export declare function harnessConfigPath(harness: FiveHarness): string;
+/** For reason strings that name a location; keeps them in sync with the table above. */
+export declare function harnessDisplayPath(harness: FiveHarness): string;
 export interface HarnessDetection {
     harness: FiveHarness;
     detected: boolean;

package/dist/lib/harness-detect.js

@@ -13,6 +13,10 @@ const CONFIG_DIRS = {
 export function harnessConfigPath(harness) {
     return path.join(os.homedir(), CONFIG_DIRS[harness]); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
 }
+/** For reason strings that name a location; keeps them in sync with the table above. */
+export function harnessDisplayPath(harness) {
+    return `~/${CONFIG_DIRS[harness]}`;
+}
 export function detectInstalledHarnesses() {
     return FIVE_HARNESSES.map((harness) => {
         const configPath = harnessConfigPath(harness);

package/dist/lib/harness.js

@@ -3,7 +3,7 @@
 // value (unenumerated, lowercase-kebab, matching MCP client_name like
 // "claude-code"). Explicit TF_CLIENT_NAME always wins upstream in client.ts.
 //
-// Fingerprints verified by running scripts/harness-probe against each harness.
+// Fingerprints verified by running scripts/harness-probe.mjs (repo root) in each harness.
 // Order matters: wrappers that embed another agent must precede the embedded
 // one. OpenClaw drives Claude Code via `sdk-cli`, so its env carries both
 // CLAUDECODE=1 and OPENCLAW_MCP_*; it must be checked before claude-code.
@@ -21,9 +21,7 @@ const HARNESS_FINGERPRINTS = [
     // prefix so we catch a Codex run regardless of which of its vars are set.
     { name: "codex", matches: (env) => hasVarWithPrefix(env, "CODEX_") },
     { name: "hermes", matches: (env) => hasVarWithPrefix(env, "HERMES_") },
-    // OpenCode sets a bare `OPENCODE` env var globally at startup (opencode#9292), inherited by
-    // the commands it shells out. Exact key, not a prefix — `OPENCODE_*` are user config inputs.
-    // Sourced from OpenCode's docs, not yet confirmed against scripts/harness-probe.
+    // Exact key, not a prefix: opencode writes OPENCODE=1 at startup, reads every OPENCODE_* as config.
     { name: "opencode", matches: (env) => Boolean(env["OPENCODE"]) },
     {
         name: "claude-code",

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

@@ -0,0 +1,15 @@
+import { type FiveHarness } from "./harness-detect.js";
+export type Registered = "yes" | "no" | "unknown";
+export type AuthMode = "api-key" | "oauth" | "unknown";
+export interface RegistrationStatus {
+    harness: FiveHarness;
+    detected: boolean;
+    registered: Registered;
+    authMode: AuthMode;
+    connectedBefore: boolean;
+    /** The endpoint the harness is actually pointed at, when the probe exposes it. */
+    registeredUrl?: string;
+    reason?: string;
+}
+/** Never throws; a failed probe is `unknown` with a reason, so no caller can read it as healthy. */
+export declare function detectRegistrations(harnesses?: FiveHarness[]): RegistrationStatus[];

package/dist/lib/registration-detect.js

@@ -0,0 +1,239 @@
+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 { errLine } from "./output.js";
+import { readCursorTinyfishEntry } from "./cursor-config.js";
+import { detectInstalledHarnesses, harnessConfigPath, harnessDisplayPath, } from "./harness-detect.js";
+// 2s tripped on a cold `hermes mcp list` (0.3s warm), reporting `unknown` on a healthy install.
+const PROBE_TIMEOUT_MS = 6_000;
+// A list, verified against codex 0.146. A name-keyed map was accepted here too, but every
+// field is optional, so that arm parsed *any* object-of-objects: a wrapper like
+// `{"servers": {...}}` decoded as one entry named `servers` and reported TinyFish absent.
+const codexEntrySchema = z.looseObject({
+    name: z.string().optional(),
+    auth_status: z.string().optional(),
+    transport: z
+        .looseObject({ url: z.string().optional(), bearer_token_env_var: z.string().nullish() })
+        .optional(),
+});
+const codexListSchema = z.array(codexEntrySchema);
+// An old harness CLI without the subcommand exits non-zero too; that is unknown, not absent.
+const UNSUPPORTED_SUBCOMMAND = /unknown command|unrecognized subcommand|invalid subcommand/i;
+// `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;
+// The report is pasted in public, so every reason is authored here. A spawn error's own
+// message quotes absolute paths, which is how a home directory reaches the payload.
+function spawnFailureReason(command, code) {
+    if (code === "ENOENT")
+        return `\`${command}\` is not on PATH`;
+    if (code === "EACCES")
+        return `\`${command}\` is not executable`;
+    return `could not run \`${command}\``;
+}
+function runProbe(command, args) {
+    const result = spawn.sync(command, args, { encoding: "utf8", timeout: PROBE_TIMEOUT_MS });
+    if (result.error) {
+        const code = result.error.code;
+        // A timeout arrives as ETIMEDOUT here, not only as a signal, so it must be named before
+        // the generic spawn failure; otherwise a timeout reports "could not run".
+        if (code === "ETIMEDOUT") {
+            return { outcome: "unavailable", reason: `\`${command} ${args.join(" ")}\` timed out` };
+        }
+        return { outcome: "unavailable", reason: spawnFailureReason(command, code) };
+    }
+    // Reached only when something else killed the child, so this is a crash, not the timeout.
+    if (result.signal) {
+        return { outcome: "unavailable", reason: `\`${command}\` was killed by ${result.signal}` };
+    }
+    const stdout = result.stdout ?? "";
+    return {
+        outcome: "ran",
+        exitCode: result.status ?? 1,
+        stdout,
+        output: `${stdout}${result.stderr ?? ""}`,
+    };
+}
+// claude-code only. Codex cannot use this: its `mcp get` exits 0 on a missing server.
+function fromMcpGet(command, keyAuthPattern) {
+    const probe = runProbe(command, ["mcp", "get", "tinyfish"]);
+    if (probe.outcome === "unavailable") {
+        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+    }
+    if (probe.exitCode !== 0) {
+        if (UNSUPPORTED_SUBCOMMAND.test(probe.output)) {
+            return {
+                registered: "unknown",
+                authMode: "unknown",
+                reason: `\`${command} mcp get\` is unsupported by this version`,
+            };
+        }
+        // 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",
+                reason: `\`${command} mcp get\` failed without reporting the server as absent`,
+            };
+        }
+        return { registered: "no", 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];
+    return {
+        registered: "yes",
+        authMode: keyAuthPattern.test(probe.output) ? "api-key" : "unknown",
+        ...(url ? { registeredUrl: url } : {}),
+    };
+}
+// `codex mcp get <missing>` prints an error and exits 0, so presence must never be read from
+// its exit code; `mcp list --json` is the only trustworthy read-back.
+function probeCodex() {
+    const probe = runProbe("codex", ["mcp", "list", "--json"]);
+    if (probe.outcome === "unavailable") {
+        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+    }
+    // Presence is never inferred from exit code 0, but a nonzero exit means the output cannot
+    // be trusted either — that is `unknown`, not "no server".
+    if (probe.exitCode !== 0) {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: `\`codex mcp list --json\` exited ${probe.exitCode}`,
+        };
+    }
+    let servers;
+    try {
+        // stdout only: an update banner on stderr would otherwise break the parse and report a
+        // healthy install as `unknown`.
+        servers = JSON.parse(probe.stdout);
+    }
+    catch {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: "`codex mcp list --json` returned unparseable output",
+        };
+    }
+    // A scalar or a wrapper object decodes fine and then silently reports "no server", which
+    // would suggest a spurious repair. Anything but a list is unknown.
+    const shape = codexListSchema.safeParse(servers);
+    if (!shape.success) {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: "`codex mcp list --json` returned an unexpected shape",
+        };
+    }
+    const entry = shape.data.find((s) => s.name === "tinyfish");
+    if (!entry)
+        return { registered: "no", authMode: "unknown" };
+    // auth_status is the configured auth type, not whether a login succeeded — exactly auth_mode.
+    const codexUrl = entry.transport?.url;
+    return {
+        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"
+            : entry.transport?.bearer_token_env_var
+                ? "api-key"
+                : "unknown",
+        ...(codexUrl ? { registeredUrl: codexUrl } : {}),
+    };
+}
+function probeCursor() {
+    const entry = readCursorTinyfishEntry();
+    if (entry.error) {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: "mcp.json exists but could not be read or parsed",
+        };
+    }
+    if (!entry.present)
+        return { registered: "no", authMode: "unknown" };
+    return {
+        registered: "yes",
+        authMode: entry.hasApiKeyHeader ? "api-key" : "unknown",
+        ...(entry.url ? { registeredUrl: entry.url } : {}),
+    };
+}
+// Hermes registers with `--auth oauth` and has no key path today, so mode is fixed.
+function probeHermes() {
+    const probe = runProbe("hermes", ["mcp", "list"]);
+    if (probe.outcome === "unavailable") {
+        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+    }
+    if (probe.exitCode !== 0) {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: `\`hermes mcp list\` exited ${probe.exitCode}`,
+        };
+    }
+    return probe.output.includes("tinyfish")
+        ? { registered: "yes", authMode: "oauth" }
+        : { registered: "no", authMode: "unknown" };
+}
+// OpenClaw installs a skill, not an MCP server; the skill shells the CLI, so auth is the CLI key.
+function probeOpenClaw() {
+    const skillsDir = path.join(harnessConfigPath("openclaw"), "skills");
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir);
+    }
+    catch {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: `no global skills directory at ${harnessDisplayPath("openclaw")}/skills; OpenClaw layout is unverified`,
+        };
+    }
+    return entries.some((name) => /tinyfish/i.test(name))
+        ? { registered: "yes", authMode: "api-key" }
+        : { registered: "no", authMode: "unknown" };
+}
+const PROBES = {
+    "claude-code": () => fromMcpGet("claude", API_KEY_HEADER),
+    codex: probeCodex,
+    cursor: probeCursor,
+    hermes: probeHermes,
+    openclaw: probeOpenClaw,
+};
+/** Never throws; a failed probe is `unknown` with a reason, so no caller can read it as healthy. */
+export function detectRegistrations(harnesses) {
+    const connect = loadConfig().connect ?? {};
+    return detectInstalledHarnesses()
+        .filter((detection) => !harnesses || harnesses.includes(detection.harness))
+        .map((detection) => {
+        const base = {
+            harness: detection.harness,
+            detected: detection.detected,
+            connectedBefore: detection.harness in connect,
+        };
+        // Undetected means nothing to probe: no spawn cost, and no misleading "unknown".
+        if (!detection.detected) {
+            return { ...base, registered: "no", authMode: "unknown" };
+        }
+        try {
+            return { ...base, ...PROBES[detection.harness]() };
+        }
+        catch (e) {
+            // An arbitrary throw is the one message we cannot author, so it never ships. Full
+            // fidelity stays on stderr behind --debug, which is not the pasted artifact.
+            if (process.env["TINYFISH_DEBUG"]) {
+                errLine(`probe ${detection.harness} threw: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            return {
+                ...base,
+                registered: "unknown",
+                authMode: "unknown",
+                reason: "the probe failed unexpectedly",
+            };
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.14.1-next.151",
+  "version": "0.15.1-next.158",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {