@tiny-fish/cli 0.30.1-next.247 → 0.30.1-next.250

package/dist/commands/connect.d.ts

@@ -21,6 +21,8 @@ export interface NativeConnectOptions {
     verbose?: boolean;
     /** Set by `--all`: repeated outro lines print once, after the summary. */
     deferOutro?: (line: string) => void;
+    /** Targeted connects only: --all keeps its per-harness failed row. */
+    fallbackWhenMissing?: boolean;
 }
 export declare function connectClaudeCode(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
 export declare function connectCodex(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
@@ -38,6 +40,8 @@ export declare function connectOpenClaw(options: {
     verbose?: boolean;
     /** Set by `--all`: repeated outro lines print once, after the summary. */
     deferOutro?: (line: string) => void;
+    /** Targeted connects only: --all keeps its per-harness failed row. */
+    fallbackWhenMissing?: boolean;
 }): Promise<void>;
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export declare function connectCursor(options: {

package/dist/commands/connect.js

@@ -3,11 +3,12 @@ import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validat
 import { CLAUDE_CODE, CODEX, CURSOR_SKILL_TARGET, GROK, HERMES, OPENCLAW, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, launchNativeMcpClient, launchOpenClawWalkthrough, openExternalUrl, } from "../lib/connect-clients.js";
 import { captureStdio, capturedOutput, HoistedFailureReportedError, installTinyFishCli, replay, } from "../lib/cli-install.js";
 import { ensureCliAuthenticated } from "../lib/connect-auth.js";
+import { createStdinPrompt, runCliFallback } from "../lib/connect-fallback.js";
 import { installWebSkill } from "../lib/skill-install.js";
 import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, finishSetupCommand, requireCommandSupport, runGuarded, settle, SignInTimeoutError, spawnStepError, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
 import { cursorInstallDeeplink, cursorMcpPath, readCursorTinyfishEntry, writeCursorMcpConfig, } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
-import { AuthMode } from "../lib/harness-detect.js";
+import { AuthMode, RELOAD_ACTION } from "../lib/harness-detect.js";
 import { detectHumanInitiated } from "../lib/harness.js";
 import { TINYFISH_API_KEY_VAR } from "../lib/constants.js";
 import { emitNotice } from "../lib/notice.js";
@@ -58,13 +59,62 @@ function signInStepError(message, result, bounded) {
         ? new SignInTimeoutError(error.message, error.cause)
         : error;
 }
+function isMissingHarness(error) {
+    return error instanceof ConnectStepError && error.failureReason === "harness_not_installed";
+}
+/** Undefined means the rescue ran; the caller returns immediately. */
+async function requireSupportOrRescue(client, connectClient, state, telemetry, options) {
+    try {
+        return requireCommandSupport(client);
+    }
+    catch (error) {
+        if (!options.fallbackWhenMissing || !isMissingHarness(error))
+            throw error;
+        await runMissingHarnessFallback(client.displayName, connectClient, state, telemetry, options);
+        return undefined;
+    }
+}
+// The harness attempt stays failed; the rescue rides fallback_outcome (PF-3707).
+async function runMissingHarnessFallback(displayName, connectClient, state, telemetry, options) {
+    // Stamped before any step: Ctrl+C settles before an outcome exists.
+    telemetry.setFallbackOutcome("abandoned");
+    errLine(`${displayName} was not found on PATH. Setting up the TinyFish CLI instead.`);
+    const outcome = await runCliFallback({
+        apiKey: options.apiKey,
+        verbose: options.verbose ?? false,
+        prompt: detectHumanInitiated() ? createStdinPrompt() : undefined,
+        retryCommand: `npx @tiny-fish/cli connect ${connectClient}`,
+        hooks: {
+            // Terminal detail is explicit below; abort rows still name the step.
+            onStepStart: (stage) => {
+                state.stage = stage;
+            },
+            onStepDone: (phase) => telemetry.track("checkpoint", { phase }),
+        },
+    });
+    telemetry.setFallbackOutcome(outcome);
+    // Never `completed`: dashboards read that as "the harness install worked".
+    settle(state, telemetry, "failed", {
+        failedStage: "prerequisite_check",
+        failureReason: "harness_not_installed",
+    });
+    if (outcome !== "cli_verified") {
+        process.exitCode = 1;
+        return;
+    }
+    errLine("The TinyFish CLI is installed and working.");
+    errLine("Using a different agent? Run: tinyfish connect --all");
+}
 async function connectNativeMcpClient(client, options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
     const state = { stage: "prerequisite_check", settled: false };
     const probeAuthenticated = SIGN_IN_PROBES[client.connectClient];
-    await runGuarded(state, telemetry, () => {
+    await runGuarded(state, telemetry, async () => {
         telemetry.track("started");
-        const { optionalSupported, keyAuthSupported, harnessVersion } = requireCommandSupport(client);
+        const support = await requireSupportOrRescue(client, client.connectClient, state, telemetry, options);
+        if (!support)
+            return;
+        const { optionalSupported, keyAuthSupported, harnessVersion } = support;
         telemetry.setHarnessVersion(harnessVersion);
         state.harnessDegraded = !!client.loginArgs && !optionalSupported;
         // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
@@ -170,7 +220,8 @@ function connectedLine(client, signInDeferred) {
         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.`;
+    return (`TinyFish is connected. Open ${client.displayName}; if it is already running, ` +
+        `${RELOAD_ACTION[client.connectClient]} to pick up the tools.`);
 }
 // Runs after `completed` settled: steps fail alone, the rest still run.
 function runPostInstallSteps(client, options, state, telemetry, signInDeferred) {
@@ -293,9 +344,12 @@ export async function connectOpenClaw(options) {
         settled: false,
         harnessDegraded: false,
     };
-    await runGuarded(state, telemetry, () => {
+    await runGuarded(state, telemetry, async () => {
         telemetry.track("started");
-        telemetry.setHarnessVersion(requireCommandSupport(OPENCLAW).harnessVersion);
+        const support = await requireSupportOrRescue(OPENCLAW, "openclaw", state, telemetry, options);
+        if (!support)
+            return;
+        telemetry.setHarnessVersion(support.harnessVersion);
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
         if (options.hoistedCliInstall) {
             state.stage = "cli_install";
@@ -334,8 +388,10 @@ export async function connectOpenClaw(options) {
         settle(state, telemetry, "completed");
         if (!options.launch) {
             // Under --all the summary already lists OpenClaw.
-            if (!options.deferOutro)
-                errLine("TinyFish is connected. Open OpenClaw to start using it.");
+            if (!options.deferOutro) {
+                errLine("TinyFish is connected. Open OpenClaw; if it is already running, " +
+                    `${RELOAD_ACTION.openclaw} to pick up the skill.`);
+            }
             return;
         }
         state.stage = "walkthrough_launch";
@@ -570,6 +626,8 @@ export function registerConnect(program) {
             attemptId,
             // A key that the install cannot use leaves only a browser hop no agent can finish.
             keyAuthOnly: !detectHumanInitiated() && !!validatedApiKey(options.apiKey),
+            // Only here: a missing harness rescues via the CLI (PF-3707).
+            fallbackWhenMissing: true,
             verbose: options.verbose ?? false,
         };
         const connector = CLIENT_CONNECTORS[client];

package/dist/lib/connect-all.js

@@ -2,13 +2,12 @@ import * as readline from "node:readline/promises";
 import spawn from "cross-spawn";
 import { connectClaudeCode, connectCodex, connectCursor, connectGrok, connectHermes, connectOpenClaw, connectOpencode, } from "../commands/connect.js";
 import { loadConfig, validatedApiKey } from "./auth.js";
-import { TINYFISH_API_KEY_VAR } from "./constants.js";
 import { installTinyFishCli, } from "./cli-install.js";
 import { HARNESS_CAPABILITIES, NATIVE_BY_HARNESS } from "./connect-clients.js";
-import { ensureCliAuthenticated, TINYFISH_CLI_NOT_FOUND_MESSAGE } from "./connect-auth.js";
-import { commandNotFound, ConnectInterruptedError, ConnectStepError, SignInTimeoutError, finishSetupCommand, throwIfInterrupted, } from "./connect-runtime.js";
+import { createStdinPrompt, runCliFallback } from "./connect-fallback.js";
+import { ConnectInterruptedError, ConnectStepError, SignInTimeoutError, finishSetupCommand, } from "./connect-runtime.js";
 import { pickHarnesses } from "./connect-picker.js";
-import { commandOnPath, detectInstalledHarnesses, HARNESS_COMMANDS, HARNESS_DISPLAY_NAMES as DISPLAY_NAMES, ALL_HARNESSES, } from "./harness-detect.js";
+import { commandOnPath, detectInstalledHarnesses, HARNESS_COMMANDS, HARNESS_DISPLAY_NAMES as DISPLAY_NAMES, ALL_HARNESSES, RELOAD_ACTION, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
 import { emitNotice } from "./notice.js";
 import { removeCursorMcpServer, planCursorWrite } from "./cursor-config.js";
@@ -184,9 +183,14 @@ async function processHarness(detection, opts, prompt, oauthBudget, hoistedCliIn
         try {
             await prompt(`Press enter to open the browser and sign in to TinyFish for ${DISPLAY_NAMES[harness]}... `);
         }
-        catch {
-            // Ctrl+D closed stdin — treat like the no-TTY skip.
-            return { ...base, outcome: "no_tty_auth_skip", fixCommand: `tinyfish connect ${harness}` };
+        catch (error) {
+            // Ctrl+C stops the run; Ctrl+D only skips this harness.
+            if (error instanceof ConnectInterruptedError) {
+                errLine("Setup interrupted — run the command again to finish.");
+                process.exitCode = 130;
+                return { ...base, outcome: "interrupted", fixCommand };
+            }
+            return { ...base, outcome: "no_tty_auth_skip", fixCommand };
         }
     }
     // runGuarded swallows Ctrl+C and sets exitCode 130 instead of throwing.
@@ -316,6 +320,20 @@ function summaryLine(result, uninstall) {
     }
     return `✓ ${name} — installed, ${verifyLabel}`;
 }
+/** One line for every harness: seven near-identical paragraphs is what this replaces. */
+function reloadHint(results) {
+    const byAction = new Map();
+    for (const result of results) {
+        if (!result.installed)
+            continue;
+        const action = RELOAD_ACTION[result.harness];
+        byAction.set(action, [...(byAction.get(action) ?? []), DISPLAY_NAMES[result.harness]]);
+    }
+    if (byAction.size === 0)
+        return undefined;
+    const parts = [...byAction].map(([action, names]) => `${names.join(", ")} — ${action}`);
+    return `TinyFish tools load when a harness starts. If one is already open: ${parts.join("; ")}.`;
+}
 /** Absent and unpicked harnesses are noise once something real happened. */
 function renderSummary(results, uninstall) {
     if (!results.some(actionable))
@@ -361,96 +379,10 @@ function computeExitCode(results) {
         return 0;
     return attempted.some((r) => r.outcome === "installed") ? 0 : 1;
 }
-const SEARCH_RETRY = 'tinyfish search query --pretty -- "<your query>"';
-function searchRetry(query) {
-    if (process.platform === "win32")
-        return SEARCH_RETRY;
-    return `tinyfish search query --pretty -- '${query.replaceAll("'", "'\\''")}'`;
-}
-async function runCliFallback(opts, prompt) {
-    try {
-        installTinyFishCli({ verbose: opts.verbose ?? false, announce: true });
-    }
-    catch (error) {
-        if (error instanceof ConnectInterruptedError)
-            throw error;
-        errLine(error instanceof Error ? error.message : String(error));
-        outLine("Retry: npx @tiny-fish/cli connect --all");
-        return 1;
-    }
-    const apiKey = opts.apiKey ?? process.env[TINYFISH_API_KEY_VAR];
-    if (!prompt && !apiKey) {
-        outLine("Retry in a terminal: npx @tiny-fish/cli connect --all");
-        return 1;
-    }
-    try {
-        ensureCliAuthenticated("cli", apiKey);
-    }
-    catch (error) {
-        if (error instanceof ConnectInterruptedError)
-            throw error;
-        errLine(error instanceof Error ? error.message : String(error));
-        outLine(error instanceof ConnectStepError && error.failureReason === "command_not_found"
-            ? "Retry in a new terminal: tinyfish auth login"
-            : "Retry: tinyfish auth login");
-        return 1;
-    }
-    if (!prompt) {
-        outLine(`Retry in a terminal: ${SEARCH_RETRY}`);
-        return 1;
-    }
-    let query;
-    try {
-        query = (await prompt("What would you like to search? ")).trim();
-    }
-    catch {
-        outLine(`Retry: ${SEARCH_RETRY}`);
-        return 1;
-    }
-    if (!query) {
-        outLine(`Retry: ${SEARCH_RETRY}`);
-        return 1;
-    }
-    const search = spawn.sync("tinyfish", ["search", "query", "--pretty", "--", query], {
-        stdio: "inherit",
-        env: { ...process.env, TF_SETUP_VERIFICATION: "1" },
-    });
-    if (commandNotFound(search.error)) {
-        errLine(TINYFISH_CLI_NOT_FOUND_MESSAGE);
-        outLine(`Retry in a new terminal: ${searchRetry(query)}`);
-        return 1;
-    }
-    throwIfInterrupted(search);
-    if (search.error || search.status !== 0) {
-        outLine(`Retry: ${searchRetry(query)}`);
-        return 1;
-    }
-    return 0;
-}
 export async function runConnectAll(opts) {
     const isTTY = detectHumanInitiated();
-    let stdinClosed = false;
     // Open interface holds stdin raw; hermes' input() then wedges.
-    const prompt = isTTY
-        ? async (question) => {
-            if (stdinClosed)
-                throw new Error("stdin is closed");
-            const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-            // Without a close-linked signal, question() never settles on Ctrl+D.
-            const closed = new AbortController();
-            rl.on("close", () => closed.abort());
-            try {
-                return await rl.question(question, { signal: closed.signal });
-            }
-            catch (e) {
-                stdinClosed = true;
-                throw e;
-            }
-            finally {
-                rl.close();
-            }
-        }
-        : undefined;
+    const prompt = isTTY ? createStdinPrompt() : undefined;
     const detections = detectInstalledHarnesses();
     const gateKey = validatedApiKey(opts.apiKey);
     // Keyed installs first: working tools land before sign-ins can block.
@@ -571,13 +503,24 @@ export async function runConnectAll(opts) {
     outLine("TinyFish setup summary:");
     for (const line of renderSummary(results, opts.uninstall))
         outLine(line);
+    const reload = opts.uninstall ? undefined : reloadHint(results);
+    if (reload) {
+        outLine("");
+        outLine(reload);
+    }
     // Before the launch handover: anything printed after it is never seen.
     for (const line of outro)
         errLine(line);
     if (!results.some(actionable)) {
         if (!opts.dryRun && !opts.uninstall) {
             try {
-                return await runCliFallback(opts, prompt);
+                const outcome = await runCliFallback({
+                    apiKey: opts.apiKey,
+                    verbose: opts.verbose ?? false,
+                    prompt,
+                    retryCommand: "npx @tiny-fish/cli connect --all",
+                });
+                return outcome === "cli_verified" ? 0 : 1;
             }
             catch (error) {
                 if (!(error instanceof ConnectInterruptedError))

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

@@ -0,0 +1,24 @@
+import { type CliFallbackOutcome, type ConnectCheckpoint, type ConnectFailureStage } from "./connect-runtime.js";
+export type Prompt = (question: string) => Promise<string>;
+export declare const SEARCH_RETRY = "tinyfish search query --pretty -- \"<your query>\"";
+export declare const DEFAULT_VERIFICATION_QUERY = "today's top Hacker News story";
+export declare const MALFORMED_ENV_KEY_MESSAGE = "TINYFISH_API_KEY is set but malformed; it will override any stored key. Fix or unset it, then re-run.";
+export declare const MALFORMED_STORED_KEY_MESSAGE = "The stored TinyFish API key is malformed. Run: tinyfish auth login";
+export interface CliFallbackHooks {
+    onStepStart?: (stage: ConnectFailureStage) => void;
+    onStepDone?: (phase: ConnectCheckpoint) => void;
+}
+export interface CliFallbackOptions {
+    apiKey?: string;
+    verbose: boolean;
+    /** Absent means headless: no interactive login, no query prompt. */
+    prompt?: Prompt;
+    /** Whole-command retry line, per entry point. */
+    retryCommand: string;
+    /** Absent under --all's zero-harness path, which has no telemetry object. */
+    hooks?: CliFallbackHooks;
+}
+/** One readline per question; a held-open interface wedges raw-stdin children. */
+export declare function createStdinPrompt(): Prompt;
+/** Steps print retry lines and return outcomes; only interrupts throw. */
+export declare function runCliFallback(opts: CliFallbackOptions): Promise<CliFallbackOutcome>;

package/dist/lib/connect-fallback.js

@@ -0,0 +1,136 @@
+import * as readline from "node:readline/promises";
+import spawn from "cross-spawn";
+import { resolvedApiKey, validateKeyFormat } from "./auth.js";
+import { installTinyFishCli } from "./cli-install.js";
+import { ensureCliAuthenticated, TINYFISH_CLI_NOT_FOUND_MESSAGE } from "./connect-auth.js";
+import { TINYFISH_API_KEY_VAR } from "./constants.js";
+import { commandNotFound, ConnectInterruptedError, ConnectStepError, throwIfInterrupted, } from "./connect-runtime.js";
+import { errLine, outLine } from "./output.js";
+export const SEARCH_RETRY = 'tinyfish search query --pretty -- "<your query>"';
+// Echoes the finale suggestion, so headless rescues rehearse the same task.
+export const DEFAULT_VERIFICATION_QUERY = "today's top Hacker News story";
+// Must undercut agent tool-call budgets (Claude Code Bash defaults to 120s).
+const HEADLESS_VERIFY_TIMEOUT_MS = 90_000;
+// An exported var must be unset, not re-logged-in.
+export const MALFORMED_ENV_KEY_MESSAGE = "TINYFISH_API_KEY is set but malformed; it will override any stored key. Fix or unset it, then re-run.";
+export const MALFORMED_STORED_KEY_MESSAGE = "The stored TinyFish API key is malformed. Run: tinyfish auth login";
+function searchRetry(query) {
+    if (process.platform === "win32")
+        return SEARCH_RETRY;
+    return `tinyfish search query --pretty -- '${query.replaceAll("'", "'\\''")}'`;
+}
+/** One readline per question; a held-open interface wedges raw-stdin children. */
+export function createStdinPrompt() {
+    let stdinClosed = false;
+    return async (question) => {
+        if (stdinClosed)
+            throw new Error("stdin is closed");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        // Without a close-linked signal, question() never settles on Ctrl+D.
+        const closed = new AbortController();
+        rl.on("close", () => closed.abort());
+        // Raw mode swallows Ctrl+C here; resurface it as the interrupt.
+        let interrupted = false;
+        rl.on("SIGINT", () => {
+            interrupted = true;
+            rl.close();
+        });
+        try {
+            return await rl.question(question, { signal: closed.signal });
+        }
+        catch (error) {
+            if (interrupted)
+                throw new ConnectInterruptedError("Setup interrupted");
+            stdinClosed = true;
+            throw error;
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
+/** Steps print retry lines and return outcomes; only interrupts throw. */
+export async function runCliFallback(opts) {
+    const { hooks, prompt } = opts;
+    hooks?.onStepStart?.("cli_install");
+    try {
+        installTinyFishCli({ verbose: opts.verbose, announce: true });
+    }
+    catch (error) {
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        errLine(error instanceof Error ? error.message : String(error));
+        outLine(`Retry: ${opts.retryCommand}`);
+        return "cli_install_failed";
+    }
+    hooks?.onStepDone?.("cli_installed");
+    hooks?.onStepStart?.("authentication");
+    // Resolved raw: validatedApiKey collapses a malformed key into "no key".
+    const rawKey = resolvedApiKey(opts.apiKey);
+    if (rawKey && !validateKeyFormat(rawKey)) {
+        // Terminal even in a TTY: login writes config; env shadows it.
+        errLine(process.env[TINYFISH_API_KEY_VAR] ? MALFORMED_ENV_KEY_MESSAGE : MALFORMED_STORED_KEY_MESSAGE);
+        outLine(`Retry: ${opts.retryCommand}`);
+        return "invalid_credentials";
+    }
+    if (!prompt && !rawKey) {
+        outLine(`Retry in a terminal: ${opts.retryCommand}`);
+        return "no_credentials";
+    }
+    try {
+        // Gate-only widening: a config-only key must not re-persist anywhere.
+        // Headless has no one to answer a login prompt; never inherit stdio there.
+        ensureCliAuthenticated("cli", opts.apiKey ?? process.env[TINYFISH_API_KEY_VAR], {
+            interactiveLogin: !!prompt,
+        });
+    }
+    catch (error) {
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        errLine(error instanceof Error ? error.message : String(error));
+        outLine(error instanceof ConnectStepError && error.failureReason === "command_not_found"
+            ? "Retry in a new terminal: tinyfish auth login"
+            : "Retry: tinyfish auth login");
+        return "authentication_failed";
+    }
+    hooks?.onStepDone?.("authenticated");
+    hooks?.onStepStart?.("cli_verification");
+    let query;
+    if (prompt) {
+        try {
+            query = (await prompt("What would you like to search? ")).trim();
+        }
+        catch (error) {
+            if (error instanceof ConnectInterruptedError)
+                throw error;
+            outLine(`Retry: ${SEARCH_RETRY}`);
+            return "abandoned";
+        }
+        if (!query) {
+            outLine(`Retry: ${SEARCH_RETRY}`);
+            return "abandoned";
+        }
+    }
+    else {
+        // Headless with a key: a canned query still proves the pipe.
+        query = DEFAULT_VERIFICATION_QUERY;
+    }
+    const search = spawn.sync("tinyfish", ["search", "query", "--pretty", "--", query], {
+        stdio: "inherit",
+        env: { ...process.env, TF_SETUP_VERIFICATION: "1" },
+        // A user-driven search must never be cut off.
+        timeout: prompt ? undefined : HEADLESS_VERIFY_TIMEOUT_MS,
+    });
+    if (commandNotFound(search.error)) {
+        errLine(TINYFISH_CLI_NOT_FOUND_MESSAGE);
+        outLine(`Retry in a new terminal: ${searchRetry(query)}`);
+        return "verification_failed";
+    }
+    throwIfInterrupted(search);
+    if (search.error || search.status !== 0) {
+        outLine(`Retry: ${searchRetry(query)}`);
+        return "verification_failed";
+    }
+    hooks?.onStepDone?.("cli_verified");
+    return "cli_verified";
+}

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

@@ -2,11 +2,12 @@ import { AuthMode } from "./harness-detect.js";
 export declare const NON_INTERACTIVE_TIMEOUT_MS = 10000;
 export type AgentClient = "claude-code" | "codex" | "cursor" | "grok" | "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";
+export type ConnectFailureStage = "prerequisite_check" | "registration_cleanup" | "registration" | "registration_or_authentication" | "client_oauth" | "cli_install" | "skill_install" | "authentication" | "walkthrough_launch" | "cli_verification";
 export declare const CONNECT_FAILURE_REASONS: readonly ["harness_not_installed", "harness_command_unsupported", "harness_too_old", "key_auth_unsupported", "command_not_found", "timeout", "spawn_error", "nonzero_exit", "invalid_config", "user_abandoned", "process_terminated", "unexpected_error"];
 export 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";
+export type ConnectCheckpoint = "prerequisite_ok" | "registered" | "oauth_done" | "cli_installed" | "skill_installed" | "authenticated" | "cli_verified";
+export type CliFallbackOutcome = "cli_verified" | "cli_install_failed" | "no_credentials" | "invalid_credentials" | "authentication_failed" | "verification_failed" | "abandoned";
 /** Ctrl+C killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {
 }
@@ -60,6 +61,7 @@ export interface ConnectTelemetry {
     attemptId: string;
     track(stage: ConnectStage, detail?: ConnectStageDetail): void;
     setHarnessVersion(version?: string): void;
+    setFallbackOutcome(outcome: CliFallbackOutcome): void;
     flush(): Promise<void>;
 }
 /** Terminal events exactly once, whichever of flow or signal handler wins. */

package/dist/lib/connect-runtime.js

@@ -210,6 +210,7 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
     const pending = [];
     let lastTrackAt;
     let harnessVersion;
+    let fallbackOutcome;
     async function deliver(body) {
         // Ahead of the key read; postConnectEvent's own opt-out check is too late to skip it.
         if (telemetryDisabled())
@@ -229,6 +230,9 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
         setHarnessVersion(version) {
             harnessVersion = version;
         },
+        setFallbackOutcome(outcome) {
+            fallbackOutcome = outcome;
+        },
         track(stage, detail) {
             const now = Date.now();
             // Clamped: a backward clock step would send a route-rejected negative.
@@ -244,6 +248,8 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
                 failed_stage: detail?.failedStage,
                 phase: detail?.phase,
                 failure_reason: detail?.failureReason,
+                // Terminal rows only: rescue checkpoints stay wire-identical to normal ones.
+                fallback_outcome: stage === "failed" || stage === "aborted" ? fallbackOutcome : undefined,
                 harness_version: detail?.harnessVersion ?? harnessVersion,
                 auth_mode: detail?.authMode,
                 harness_degraded: detail?.harnessDegraded,

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

@@ -1,6 +1,8 @@
 export declare const ALL_HARNESSES: readonly ["claude-code", "codex", "cursor", "grok", "hermes", "openclaw", "opencode"];
 export type Harness = (typeof ALL_HARNESSES)[number];
 export declare const HARNESS_DISPLAY_NAMES: Record<Harness, string>;
+/** MCP config is read at startup, so a running harness needs this to see TinyFish. */
+export declare const RELOAD_ACTION: Record<Harness, string>;
 export declare enum Registered {
     Yes = "yes",
     No = "no",

package/dist/lib/harness-detect.js

@@ -20,6 +20,17 @@ export const HARNESS_DISPLAY_NAMES = {
     openclaw: "OpenClaw",
     opencode: "OpenCode",
 };
+/** MCP config is read at startup, so a running harness needs this to see TinyFish. */
+export const RELOAD_ACTION = {
+    "claude-code": "restart it",
+    codex: "restart it",
+    // docs.x.ai/build/features/mcp-servers: `r` in /mcps rereads the config.
+    grok: "run /mcps and press r",
+    hermes: "restart it",
+    openclaw: "restart it",
+    opencode: "restart it",
+    cursor: "reload the window",
+};
 // Values are the wire contract; the report schema derives from these.
 export var Registered;
 (function (Registered) {

package/package.json

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