@tiny-fish/cli 0.24.1-next.208 → 0.24.1-next.212

package/README.md

@@ -101,6 +101,9 @@ Brings both halves of an install current: the global `@tiny-fish/cli` package an
 Successful steps are summarised in one line each. Add `--verbose` to see the full npm and skills
 output; a failing step prints its output either way.
 
+`--cli-only` updates just the global package and `--skill-only` refreshes just the skill. The two
+flags are mutually exclusive.
+
 The skill step refreshes only the TinyFish skill, and only for the agents you ran
 `tinyfish connect` against. Other global skills, and agents you never connected, are left alone.
 The refresh overwrites your copy of the skill, including any local edits to it. Restart your

package/dist/commands/connect.d.ts

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { type TakeHoistedCliInstall } from "../lib/cli-install.js";
 import { type AgentClient, type ConnectAuthMode } from "../lib/connect-runtime.js";
 export declare const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 interface NativeConnectOptions {
@@ -8,6 +9,12 @@ interface NativeConnectOptions {
     attemptId?: string;
     /** Headless: refuse rather than fall back to an unfinishable browser sign-in. */
     keyAuthOnly?: boolean;
+    /** Internal only: false leaves the global npm tree untouched. */
+    cliInstall?: boolean;
+    /** Set by `--all`: the CLI install already ran once, upfront. */
+    hoistedCliInstall?: TakeHoistedCliInstall;
+    /** Lets `--all` warn in its summary instead of all-green. */
+    onPostInstallFailed?: () => void;
 }
 export declare function connectClaudeCode(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
 export declare function connectCodex(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
@@ -18,8 +25,10 @@ export declare function connectOpenClaw(options: {
     apiKey?: string;
     mcpUrl: string;
     launch: boolean;
-    installCli?: boolean;
+    cliInstall?: boolean;
     attemptId?: string;
+    /** Set by `--all`: the CLI install already ran once, upfront. */
+    hoistedCliInstall?: TakeHoistedCliInstall;
 }): Promise<void>;
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export declare function connectCursor(options: {

package/dist/commands/connect.js

@@ -1,8 +1,10 @@
 import spawn from "cross-spawn";
 import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, } from "../lib/auth.js";
 import { CLAUDE_CODE, CODEX, CURSOR_SKILL_TARGET, GROK, HERMES, OPENCLAW, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, launchNativeMcpClient, launchOpenClawWalkthrough, openExternalUrl, } from "../lib/connect-clients.js";
-import { ensureCliAuthenticated, installTinyFishCli, installWebSkill, SKILL_INSTALL_TIMEOUT_MS, UPGRADE_HINT, } from "../lib/connect-install.js";
-import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, spawnStepError, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
+import { HoistedFailureReportedError, installTinyFishCli, SKILL_INSTALL_TIMEOUT_MS, UPGRADE_HINT, } from "../lib/cli-install.js";
+import { ensureCliAuthenticated } from "../lib/connect-auth.js";
+import { installWebSkill } from "../lib/skill-install.js";
+import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, finishSetupCommand, 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";
@@ -143,52 +145,97 @@ function connectedLine(client, signInDeferred) {
     }
     return `TinyFish is connected. Open ${client.displayName} to start using it.`;
 }
-// Runs after `completed` settled: failures warn and report post_install_failed, exit 0.
+// Runs after `completed` settled: steps fail alone, the rest still run.
 function runPostInstallSteps(client, options, state, telemetry, signInDeferred) {
+    let failed = false;
+    // Modelled on upgrade's attempt(); interrupts rethrow and abandon remaining steps.
+    const attempt = (stage, run) => {
+        state.stage = stage;
+        try {
+            run();
+        }
+        catch (error) {
+            if (error instanceof ConnectInterruptedError)
+                throw error;
+            failed = true;
+            trackPostInstallFailure(client.displayName, state, telemetry, error);
+        }
+    };
     try {
-        state.stage = "cli_install";
-        // Verbose on purpose: first-run setup must not go silent.
-        installTinyFishCli({ verbose: true });
-        telemetry.track("checkpoint", { phase: "cli_installed" });
+        if (options.cliInstall !== false) {
+            attempt("cli_install", () => runCliInstallStep(options, telemetry));
+        }
         if (client.skillAgent) {
-            state.stage = "skill_install";
-            installWebSkill(client);
-            telemetry.track("checkpoint", { phase: "skill_installed" });
+            attempt("skill_install", () => {
+                installWebSkill(client);
+                telemetry.track("checkpoint", { phase: "skill_installed" });
+            });
         }
-        state.stage = "authentication";
-        ensureCliAuthenticated(client.connectClient, options.apiKey);
-        telemetry.track("checkpoint", { phase: "authenticated" });
-        // Persist once here (skill installed + authenticated) so both success paths, launch
-        // or not, record the install; buildConnectHeaders reads it on subsequent requests.
+        // Before auth: a failed sign-in must not lose the harness record.
         saveConnectContext(client.connectClient, telemetry.attemptId);
+        attempt("authentication", () => {
+            ensureCliAuthenticated(client.connectClient, options.apiKey);
+            telemetry.track("checkpoint", { phase: "authenticated" });
+        });
         errLine(UPGRADE_HINT);
         if (client.postConnectNote)
             errLine(client.postConnectNote);
         if (!options.launch) {
             errLine(connectedLine(client, signInDeferred));
-            return;
         }
-        state.stage = "walkthrough_launch";
-        // Before the handover, or the only sign-in instructions scroll past under the agent.
-        if (signInDeferred && client.signInHint)
-            errLine(client.signInHint);
-        launchNativeMcpClient(client);
+        else {
+            attempt("walkthrough_launch", () => {
+                // Before the handover, or the only sign-in instructions scroll past under the agent.
+                if (signInDeferred && client.signInHint)
+                    errLine(client.signInHint);
+                launchNativeMcpClient(client);
+            });
+        }
     }
     catch (error) {
-        reportPostInstallFailure(client.connectClient, client.displayName, state, telemetry, error);
+        // Interrupts stop quietly; anything else escapes to runGuarded.
+        if (!(error instanceof ConnectInterruptedError))
+            throw error;
+        failed = true;
+    }
+    if (failed) {
+        errLine(finishSetupHint(client.connectClient));
+        options.onPostInstallFailed?.();
     }
 }
+/** Consumes the `--all` hoist when present; installs inline otherwise. */
+function runCliInstallStep(options, telemetry) {
+    if (options.hoistedCliInstall) {
+        const { outcome, firstTake } = options.hoistedCliInstall();
+        if (!outcome.ok) {
+            // Late takers fail too; only the first reports the install.
+            throw firstTake ? outcome.error : new HoistedFailureReportedError(outcome.error.message);
+        }
+        if (firstTake) {
+            telemetry.track("checkpoint", { phase: "cli_installed", stageDurationMs: outcome.durationMs });
+        }
+        return;
+    }
+    // Verbose on purpose: first-run setup must not go silent.
+    installTinyFishCli({ verbose: true });
+    telemetry.track("checkpoint", { phase: "cli_installed" });
+}
+function finishSetupHint(connectClient) {
+    return `Finish setup with: ${finishSetupCommand(connectClient)}`;
+}
 /** Warn + report post_install_failed; interrupts are abandonment, not failure. */
-function reportPostInstallFailure(connectClient, displayName, state, telemetry, error) {
-    if (!(error instanceof ConnectInterruptedError)) {
+function trackPostInstallFailure(displayName, state, telemetry, error) {
+    if (error instanceof ConnectInterruptedError)
+        return;
+    // An earlier harness already owns the shared install's failure record.
+    if (!(error instanceof HoistedFailureReportedError)) {
         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}`);
+    errLine(`The ${displayName} MCP connection succeeded, but a finishing step ` +
+        `(${state.stage}) failed: ${error instanceof Error ? error.message : String(error)}`);
 }
 export async function connectClaudeCode(options) {
     return connectNativeMcpClient(CLAUDE_CODE, options);
@@ -217,7 +264,20 @@ export async function connectOpenClaw(options) {
         telemetry.track("started");
         telemetry.setHarnessVersion(requireCommandSupport(OPENCLAW).harnessVersion);
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
-        if (options.installCli !== false) {
+        if (options.hoistedCliInstall) {
+            state.stage = "cli_install";
+            const { outcome, firstTake } = options.hoistedCliInstall();
+            // A carried failure fails openclaw exactly like the inline install.
+            if (!outcome.ok)
+                throw outcome.error;
+            if (firstTake) {
+                telemetry.track("checkpoint", {
+                    phase: "cli_installed",
+                    stageDurationMs: outcome.durationMs,
+                });
+            }
+        }
+        else if (options.cliInstall !== false) {
             state.stage = "cli_install";
             installTinyFishCli({ verbose: true });
             telemetry.track("checkpoint", { phase: "cli_installed" });
@@ -249,7 +309,8 @@ export async function connectOpenClaw(options) {
             launchOpenClawWalkthrough();
         }
         catch (error) {
-            reportPostInstallFailure("openclaw", "OpenClaw", state, telemetry, error);
+            trackPostInstallFailure("OpenClaw", state, telemetry, error);
+            errLine(finishSetupHint("openclaw"));
         }
     });
 }

package/dist/commands/onboard.js

@@ -87,7 +87,7 @@ async function connectAgent(id) {
         return;
     const mcpUrl = new URL("/mcp", BASE_URL).toString();
     if (id === "openclaw") {
-        await connectOpenClaw({ mcpUrl, launch: false, installCli: false });
+        await connectOpenClaw({ mcpUrl, launch: false, cliInstall: false });
     }
     else {
         await agent.connect({ mcpUrl, launch: false });

package/dist/commands/upgrade.d.ts

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

package/dist/commands/upgrade.js

@@ -6,7 +6,8 @@ import { suppressNotice } from "../lib/notice.js";
 import { errLine } from "../lib/output.js";
 import { sendUpgradeCompleted, telemetryDisabled, } from "../lib/setup-telemetry.js";
 import { installSignalGuard, SIGNAL_EXIT_CODES } from "../lib/signals.js";
-import { installTinyFishCli, updateWebSkill } from "../lib/connect-install.js";
+import { installTinyFishCli } from "../lib/cli-install.js";
+import { updateWebSkill } from "../lib/skill-install.js";
 import { ConnectInterruptedError } from "../lib/connect-runtime.js";
 const VERSION_READ_TIMEOUT_MS = 2_000;
 const INTERRUPTED_MESSAGE = "Upgrade interrupted — run `tinyfish upgrade` again to finish.";
@@ -26,16 +27,20 @@ function attempt(label, run) {
     }
 }
 /** Returns the version now installed, so the caller reports exactly what the user was told. */
-export function runUpgrade(verbose = false) {
+export function runUpgrade(verbose = false, scope = "both") {
     errLine("Upgrading TinyFish...");
     let refreshed = false;
     try {
-        // Both steps always run: neither artifact should stay stale because the other failed.
+        // Every selected step runs: one failing must not stall the other.
         const failures = [
-            attempt("update the TinyFish CLI", () => installTinyFishCli({ verbose })),
-            attempt("refresh the TinyFish web skill", () => {
-                refreshed = updateWebSkill({ verbose });
-            }),
+            scope === "skill"
+                ? undefined
+                : attempt("update the TinyFish CLI", () => installTinyFishCli({ verbose })),
+            scope === "cli"
+                ? undefined
+                : attempt("refresh the TinyFish web skill", () => {
+                    refreshed = updateWebSkill({ verbose });
+                }),
         ].filter((failure) => failure !== undefined);
         if (failures.length > 0)
             throw new Error(`tinyfish upgrade failed: ${failures.join("; ")}`);
@@ -48,7 +53,10 @@ export function runUpgrade(verbose = false) {
         return null;
     }
     const version = installedCliVersion();
-    const upToDate = version ? `TinyFish CLI ${version} is up to date.` : "TinyFish is up to date.";
+    // --skill-only never checked the CLI, so no versioned claim.
+    const upToDate = version && scope !== "skill"
+        ? `TinyFish CLI ${version} is up to date.`
+        : "TinyFish is up to date.";
     // Only a rewritten skill needs an agent restart.
     errLine(refreshed ? `${upToDate} Restart your agent to pick up the refreshed skill.` : upToDate);
     return version;
@@ -70,7 +78,7 @@ function globalCliVersion() {
     }
 }
 /** `runUpgrade` plus its outcome telemetry, which must never change what the upgrade does. */
-export async function runUpgradeCommand(verbose = false) {
+export async function runUpgradeCommand(verbose = false, scope = "both") {
     // This command is the upgrade, so a trailing "an update is available" would be noise.
     suppressNotice();
     let reported = false;
@@ -85,7 +93,7 @@ export async function runUpgradeCommand(verbose = false) {
             return;
         // Interrupted skips the read — racing the exit. Undercounts; see posthog-events.md.
         const toVersion = outcome === "interrupted" ? null : (printedVersion ?? installedCliVersion());
-        await sendUpgradeCompleted(CLI_VERSION, toVersion, outcome, resolvedApiKey());
+        await sendUpgradeCompleted(CLI_VERSION, toVersion, outcome, scope, resolvedApiKey());
     };
     const uninstallSignalGuard = installSignalGuard(async () => {
         errLine(INTERRUPTED_MESSAGE);
@@ -93,7 +101,7 @@ export async function runUpgradeCommand(verbose = false) {
     });
     let outcome = "updated";
     try {
-        printedVersion = runUpgrade(verbose);
+        printedVersion = runUpgrade(verbose, scope);
         if (process.exitCode === SIGNAL_EXIT_CODES.SIGINT)
             outcome = "interrupted";
     }
@@ -112,7 +120,13 @@ export function registerUpgrade(program) {
         .command("upgrade")
         .description("Update the TinyFish CLI and the use-tinyfish skill to the latest versions")
         .option("--verbose", "Print the full npm and skills output instead of only on failure")
+        .option("--cli-only", "Update only the TinyFish CLI, leaving the skill untouched")
+        .option("--skill-only", "Refresh only the use-tinyfish skill, leaving the CLI untouched")
         .action(async (options) => {
-        await runUpgradeCommand(Boolean(options.verbose));
+        if (options.cliOnly && options.skillOnly) {
+            throw new Error("Pass either --cli-only or --skill-only, not both.");
+        }
+        const scope = options.cliOnly ? "cli" : options.skillOnly ? "skill" : "both";
+        await runUpgradeCommand(Boolean(options.verbose), scope);
     });
 }

package/dist/lib/cli-install.d.ts

@@ -0,0 +1,42 @@
+export declare const SKILL_INSTALL_TIMEOUT_MS = 120000;
+export declare const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
+export declare const STEP_MAX_BUFFER: number;
+/** Quiet captures subprocess output and replays it only on failure. */
+export type InstallOptions = {
+    verbose: boolean;
+};
+/** Outcome of `--all`'s one npm install; error keeps ConnectStepError.failureReason. */
+export type HoistedCliInstall = {
+    ok: true;
+    durationMs: number;
+} | {
+    ok: false;
+    error: Error;
+};
+/** Every harness reads the outcome; only the first take reports it. */
+export type TakeHoistedCliInstall = () => {
+    outcome: HoistedCliInstall;
+    firstTake: boolean;
+};
+/** Carried failure an earlier harness already reported. */
+export declare class HoistedFailureReportedError extends Error {
+}
+export declare function captureStdio(verbose: boolean): {
+    stdio: "inherit";
+    timeout: number;
+    encoding?: undefined;
+    maxBuffer?: undefined;
+} | {
+    encoding: "utf8";
+    maxBuffer: number;
+    timeout: number;
+    stdio?: undefined;
+};
+/** Inherited stdio leaves these null; only piped runs yield text. */
+export declare function capturedOutput(result: {
+    stdout?: unknown;
+    stderr?: unknown;
+}): string;
+/** A verbose run captured nothing, so this is a no-op. */
+export declare function replay(output: string): void;
+export declare function installTinyFishCli({ verbose }: InstallOptions): void;

package/dist/lib/cli-install.js

@@ -0,0 +1,44 @@
+import spawn from "cross-spawn";
+import { spawnStepError } from "./connect-runtime.js";
+import { TINYFISH_CLI_PACKAGE } from "./constants.js";
+import { installRoot } from "./install-root.js";
+import { errLine } from "./output.js";
+export const SKILL_INSTALL_TIMEOUT_MS = 120_000;
+const TINYFISH_CLI_INSTALL_SPEC = `${TINYFISH_CLI_PACKAGE}@latest`;
+export const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
+// spawnSync caps piped output at 1 MiB by default.
+export const STEP_MAX_BUFFER = 10 * 1024 * 1024;
+/** Carried failure an earlier harness already reported. */
+export class HoistedFailureReportedError extends Error {
+}
+export function captureStdio(verbose) {
+    return verbose
+        ? { stdio: "inherit", timeout: SKILL_INSTALL_TIMEOUT_MS }
+        : { encoding: "utf8", maxBuffer: STEP_MAX_BUFFER, timeout: SKILL_INSTALL_TIMEOUT_MS };
+}
+/** Inherited stdio leaves these null; only piped runs yield text. */
+export function capturedOutput(result) {
+    return `${asText(result.stdout)}${asText(result.stderr)}`;
+}
+function asText(stream) {
+    return typeof stream === "string" ? stream : "";
+}
+/** A verbose run captured nothing, so this is a no-op. */
+export function replay(output) {
+    if (output.trim())
+        errLine(output.trimEnd());
+}
+export function installTinyFishCli({ verbose }) {
+    if (verbose)
+        errLine("Installing the TinyFish CLI...");
+    // Without the prefix, a curl install upgrades npm's global tree and never the PATH binary.
+    const root = installRoot();
+    const prefixArgs = root ? ["--prefix", root.prefix] : [];
+    const result = spawn.sync("npm", ["install", "--global", ...prefixArgs, TINYFISH_CLI_INSTALL_SPEC], captureStdio(verbose));
+    if (result.error || result.status !== 0) {
+        // Built first: it runs the interrupt check, and abandonment must not replay.
+        const error = spawnStepError("Could not install the TinyFish CLI", result);
+        replay(capturedOutput(result));
+        throw error;
+    }
+}

package/dist/lib/connect-all.js

@@ -2,9 +2,10 @@ 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 { validatedApiKey } from "./auth.js";
+import { installTinyFishCli, } from "./cli-install.js";
 import { NATIVE_MCP_CLIENTS } from "./connect-clients.js";
-import { ensureCliAuthenticated, installTinyFishCli, TINYFISH_CLI_NOT_FOUND_MESSAGE, } from "./connect-install.js";
-import { commandNotFound, ConnectInterruptedError, ConnectStepError, throwIfInterrupted, } from "./connect-runtime.js";
+import { ensureCliAuthenticated, TINYFISH_CLI_NOT_FOUND_MESSAGE } from "./connect-auth.js";
+import { commandNotFound, ConnectInterruptedError, ConnectStepError, finishSetupCommand, throwIfInterrupted, } from "./connect-runtime.js";
 import { detectInstalledHarnesses, ALL_HARNESSES, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
 import { emitNotice } from "./notice.js";
@@ -46,8 +47,15 @@ const UNINSTALL_POINTERS = {
     // OpenCode ships no `mcp remove`, so the only removal is editing the config it wrote.
     opencode: "remove the tinyfish entry from ~/.config/opencode/opencode.json",
 };
-async function runHarnessConnect(harness, opts, keyAuthOnly) {
-    const base = { apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false, keyAuthOnly };
+async function runHarnessConnect(harness, opts, keyAuthOnly, hoistedCliInstall, onPostInstallFailed) {
+    const base = {
+        apiKey: opts.apiKey,
+        mcpUrl: opts.mcpUrl,
+        launch: false,
+        keyAuthOnly,
+        hoistedCliInstall,
+        onPostInstallFailed,
+    };
     if (harness === "claude-code")
         return connectClaudeCode(base);
     if (harness === "codex")
@@ -56,7 +64,12 @@ async function runHarnessConnect(harness, opts, keyAuthOnly) {
         return connectHermes(base);
     if (harness === "openclaw") {
         // Without the key the child shells an interactive `tinyfish auth login`.
-        await connectOpenClaw({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false });
+        await connectOpenClaw({
+            apiKey: opts.apiKey,
+            mcpUrl: opts.mcpUrl,
+            launch: false,
+            hoistedCliInstall,
+        });
         return undefined;
     }
     if (harness === "opencode")
@@ -70,6 +83,20 @@ async function runHarnessConnect(harness, opts, keyAuthOnly) {
     // Explicit: a new harness reaching an untested branch must fail, not write Cursor's config.
     throw new Error(`No installer is wired for ${harness}`);
 }
+/** Undefined means Ctrl+C: the caller stops the whole run. */
+function runHoistedCliInstall() {
+    const startedAt = Date.now();
+    try {
+        installTinyFishCli({ verbose: true });
+        // Clamped: a backward clock step would send a route-rejected negative.
+        return { ok: true, durationMs: Math.max(0, Date.now() - startedAt) };
+    }
+    catch (error) {
+        if (error instanceof ConnectInterruptedError)
+            return undefined;
+        return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+}
 async function verifyHarness(harness, mcpUrl, keyed, apiKey) {
     const health = await verifyMcpHealth(mcpUrl);
     // The own-OAuth harnesses are auth-checkable only in key mode (key-authed config).
@@ -117,7 +144,7 @@ function uninstallHarness(harness, configPath) {
     }
     return { ...detection, outcome: "uninstalled" };
 }
-async function processHarness(detection, opts, prompt) {
+async function processHarness(detection, opts, prompt, hoistedCliInstall) {
     const { harness, configPath } = detection;
     if (!detection.detected) {
         return { harness, detected: false, configPath, installed: false, outcome: "not_detected" };
@@ -157,9 +184,12 @@ async function processHarness(detection, opts, prompt) {
     // runGuarded swallows Ctrl+C and sets exitCode 130 instead of throwing.
     const interruptedBefore = process.exitCode === 130;
     let authMode;
+    let postInstallFailed = false;
     try {
         // Headless: an install too old for key auth must fail, not open a browser.
-        authMode = await runHarnessConnect(harness, opts, !isTTY);
+        authMode = await runHarnessConnect(harness, opts, !isTTY, hoistedCliInstall, () => {
+            postInstallFailed = true;
+        });
     }
     catch (e) {
         return {
@@ -183,6 +213,7 @@ async function processHarness(detection, opts, prompt) {
         verifyOk: verify.ok,
         verifyReason: verify.reason,
         keyAuthed,
+        postInstallFailed,
     };
 }
 function summaryLine(result, uninstall) {
@@ -222,6 +253,11 @@ function summaryLine(result, uninstall) {
     if (result.outcome === "failed") {
         return `✗ ${name} — install failed: ${result.errorMessage}. Fix: ${result.fixCommand}`;
     }
+    // The summary is what users read; stderr hints scroll away.
+    if (result.postInstallFailed) {
+        return (`⚠ ${name} — installed, but a finishing step failed. ` +
+            `Fix: ${finishSetupCommand(result.harness)}`);
+    }
     // A keyed install has no sign-in left, so the deferred-auth warning would contradict it.
     const authDeferred = AUTH_DEFERRED_AT_INSTALL.has(result.harness) && !result.keyAuthed;
     const verifyLabel = result.verifyDepth ? `verified: ${result.verifyDepth}` : "not verified";
@@ -334,13 +370,36 @@ export async function runConnectAll(opts) {
         }
         : undefined;
     const detections = detectInstalledHarnesses();
+    const gateKey = validatedApiKey(opts.apiKey);
+    // Mirrors processHarness's skip gate: a skipped harness installs nothing today.
+    const willAttempt = (harness) => isTTY || (!!gateKey && KEY_AUTH_CAPABLE.has(harness));
+    // Machine-global, so once per invocation; cursor's connect never installs it.
+    const cliNeeded = !opts.dryRun &&
+        !opts.uninstall &&
+        detections.some((d) => d.detected && d.harness !== "cursor" && willAttempt(d.harness));
+    let takeHoistedCli;
+    if (cliNeeded) {
+        errLine("First: the TinyFish CLI, shared by every harness.");
+        const outcome = runHoistedCliInstall();
+        if (!outcome) {
+            errLine("Setup interrupted — run the command again to finish.");
+            return 130;
+        }
+        let taken = false;
+        // Every harness gets the outcome; only the first take reports it.
+        takeHoistedCli = () => {
+            const firstTake = !taken;
+            taken = true;
+            return { outcome, firstTake };
+        };
+    }
     const results = [];
     for (const [index, detection] of detections.entries()) {
         const { harness } = detection;
         errLine(`step ${index + 1} of ${detections.length} — ${DISPLAY_NAMES[harness]}`);
         let result;
         try {
-            result = await processHarness(detection, opts, prompt);
+            result = await processHarness(detection, opts, prompt, takeHoistedCli);
         }
         catch (e) {
             // Isolation: one harness throwing never stops the others.

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

@@ -0,0 +1,3 @@
+import { type AgentClient } from "./connect-runtime.js";
+export declare const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
+export declare function ensureCliAuthenticated(source: AgentClient | "cli", apiKey?: string): void;

package/dist/lib/connect-auth.js

@@ -0,0 +1,42 @@
+import spawn from "cross-spawn";
+import { persistApiKeyToEnvironment, validateKeyFormat, writeConfig } from "./auth.js";
+import { commandNotFound, ConnectStepError, spawnStepError, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "./connect-runtime.js";
+import { errLine } from "./output.js";
+export const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
+export function ensureCliAuthenticated(source, apiKey) {
+    const envKey = apiKey ?? process.env["TINYFISH_API_KEY"];
+    if (envKey) {
+        if (!validateKeyFormat(envKey)) {
+            throw new ConnectStepError("TINYFISH_API_KEY has invalid format", "invalid_config");
+        }
+        // Throwing variant: a write failure must reach connect's catch/flush, not exit(1) past it.
+        writeConfig(envKey);
+        persistApiKeyToEnvironment(envKey);
+        return;
+    }
+    const authStatus = spawn.sync("tinyfish", ["auth", "status"], {
+        stdio: "ignore",
+        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+    });
+    if (commandNotFound(authStatus.error)) {
+        throw spawnStepError(TINYFISH_CLI_NOT_FOUND_MESSAGE, authStatus);
+    }
+    if (authStatus.status === 0)
+        return;
+    // A crashed or timed-out probe says nothing about the stored key, so it must not read as
+    // "not signed in" and drop the user into an interactive login they never asked for.
+    throwIfInterrupted(authStatus);
+    if (authStatus.error) {
+        throw spawnStepError("Could not read TinyFish CLI auth status", authStatus);
+    }
+    errLine("Signing in to the TinyFish CLI...");
+    const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", source], {
+        stdio: "inherit",
+    });
+    if (commandNotFound(loginResult.error)) {
+        throw spawnStepError(TINYFISH_CLI_NOT_FOUND_MESSAGE, loginResult);
+    }
+    if (loginResult.error || loginResult.status !== 0) {
+        throw spawnStepError("Could not authenticate the TinyFish CLI", loginResult);
+    }
+}

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

@@ -31,6 +31,8 @@ interface SpawnStepResult {
 /** Classifies a spawn failure; interrupts throw instead. */
 export declare function spawnStepError(message: string, result: SpawnStepResult): ConnectStepError;
 export declare function commandNotFound(error: unknown): boolean;
+/** One command redoes every post-install step for a client. */
+export declare function finishSetupCommand(client: AgentClient): string;
 export interface ConnectRunState {
     stage: ConnectFailureStage;
     settled: boolean;
@@ -47,6 +49,8 @@ interface ConnectStageDetail {
     authMode?: ConnectAuthMode;
     /** Orthogonal to `authMode`: a stored key wins over `mcp login` on a healthy client too. */
     harnessDegraded?: boolean;
+    /** Overrides the event-gap duration; the hoisted CLI install measures itself. */
+    stageDurationMs?: number;
 }
 export interface ConnectTelemetry {
     attemptId: string;

package/dist/lib/connect-runtime.js

@@ -61,6 +61,10 @@ export function spawnStepError(message, result) {
 export function commandNotFound(error) {
     return error?.code === "ENOENT";
 }
+/** One command redoes every post-install step for a client. */
+export function finishSetupCommand(client) {
+    return `npx -y @tiny-fish/cli@latest connect ${client}`;
+}
 /** Terminal events exactly once, whichever of flow or signal handler wins. */
 export function settle(state, telemetry, stage, detail) {
     if (state.settled)
@@ -203,7 +207,8 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
         track(stage, detail) {
             const now = Date.now();
             // Clamped: a backward clock step would send a route-rejected negative.
-            const stageDurationMs = lastTrackAt === undefined ? undefined : Math.max(0, now - lastTrackAt);
+            const stageDurationMs = detail?.stageDurationMs ??
+                (lastTrackAt === undefined ? undefined : Math.max(0, now - lastTrackAt));
             lastTrackAt = now;
             // Absorbed here, not in flush: flush runs in runGuarded's finally, so a rejection would
             // replace the error the flow is already reporting.

package/dist/lib/setup-telemetry.d.ts

@@ -64,7 +64,9 @@ export declare const setupCompletedPayloadSchema: z.ZodObject<{
 export type SetupCompletedPayload = z.infer<typeof setupCompletedPayloadSchema>;
 export type HarnessResult = z.infer<typeof harnessResultSchema>;
 export type UpgradeOutcome = "updated" | "failed" | "interrupted";
+/** Step selection; "updated" means every selected step ran. */
+export type UpgradeScope = "both" | "cli" | "skill";
 /** `toVersion` is null when the run was interrupted or the installed version could not be read. */
-export declare function sendUpgradeCompleted(fromVersion: string, toVersion: string | null, outcome: UpgradeOutcome, apiKey?: string): Promise<void>;
+export declare function sendUpgradeCompleted(fromVersion: string, toVersion: string | null, outcome: UpgradeOutcome, scope: UpgradeScope, apiKey?: string): Promise<void>;
 export declare function sendSetupCompleted(mcpUrl: string, harnesses: HarnessResult[], apiKey?: string): Promise<void>;
 export {};

package/dist/lib/setup-telemetry.js

@@ -111,7 +111,7 @@ export const setupCompletedPayloadSchema = z.object({
     cli_version: z.string(),
 });
 /** `toVersion` is null when the run was interrupted or the installed version could not be read. */
-export async function sendUpgradeCompleted(fromVersion, toVersion, outcome, apiKey) {
+export async function sendUpgradeCompleted(fromVersion, toVersion, outcome, scope, apiKey) {
     await postConnectEvent({
         endpoint: new URL("/api/cli/connect-event", BASE_URL).toString(),
         body: JSON.stringify({
@@ -119,6 +119,7 @@ export async function sendUpgradeCompleted(fromVersion, toVersion, outcome, apiK
             from_version: fromVersion,
             to_version: toVersion,
             outcome,
+            scope,
         }),
         attempts: 1,
         label: "upgrade",

package/dist/lib/{connect-install.d.ts → skill-install.d.ts}

@@ -1,13 +1,5 @@
+import { type InstallOptions } from "./cli-install.js";
 import { type SkillAgent } from "./connect-clients.js";
-import { type AgentClient } from "./connect-runtime.js";
-export declare const SKILL_INSTALL_TIMEOUT_MS = 120000;
-export declare const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
-export declare const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
-/** Quiet captures subprocess output and replays it only on failure. */
-export type InstallOptions = {
-    verbose: boolean;
-};
-export declare function installTinyFishCli({ verbose }: InstallOptions): void;
 export declare function installWebSkill(client: {
     skillAgent?: SkillAgent;
     displayName: string;
@@ -23,4 +15,3 @@ export declare function installWebSkill(client: {
  * Returns whether a skill was actually rewritten.
  */
 export declare function updateWebSkill({ verbose }: InstallOptions): boolean;
-export declare function ensureCliAuthenticated(source: AgentClient | "cli", apiKey?: string): void;

package/dist/lib/{connect-install.js → skill-install.js}

@@ -1,52 +1,17 @@
 import * as path from "node:path";
 import spawn from "cross-spawn";
-import { loadConfig, persistApiKeyToEnvironment, validateKeyFormat, writeConfig } from "./auth.js";
+import { z } from "zod";
+import { loadConfig } from "./auth.js";
+import { captureStdio, capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from "./cli-install.js";
 import { CURSOR_SKILL_TARGET, NATIVE_MCP_CLIENTS, OPENCLAW_SKILL_INSTALL_ARGS, } from "./connect-clients.js";
-import { commandNotFound, ConnectStepError, spawnStepError, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "./connect-runtime.js";
-import { CLI_AGENT_IDENTITY, TINYFISH_CLI_PACKAGE } from "./constants.js";
-import { installRoot } from "./install-root.js";
+import { commandNotFound, spawnStepError, throwIfInterrupted } from "./connect-runtime.js";
+import { CLI_AGENT_IDENTITY } from "./constants.js";
 import { errLine } from "./output.js";
-export const SKILL_INSTALL_TIMEOUT_MS = 120_000;
-export const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
-const TINYFISH_CLI_INSTALL_SPEC = `${TINYFISH_CLI_PACKAGE}@latest`;
-export const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
 // Supports Hermes without node:util.styleText, so the installer still runs on Node 20.11.
+// A bump must re-verify SKILL_AGENT_DISPLAY_NAMES against `skills list --json`.
 const SKILLS_CLI_PACKAGE = "skills@1.5.15";
 const TINYFISH_WEB_SKILL_SOURCE = "tinyfish-io/tinyfish-cookbook";
 const TINYFISH_WEB_SKILL = "use-tinyfish";
-// spawnSync caps piped output at 1 MiB by default.
-const STEP_MAX_BUFFER = 10 * 1024 * 1024;
-function captureStdio(verbose) {
-    return verbose
-        ? { stdio: "inherit", timeout: SKILL_INSTALL_TIMEOUT_MS }
-        : { encoding: "utf8", maxBuffer: STEP_MAX_BUFFER, timeout: SKILL_INSTALL_TIMEOUT_MS };
-}
-/** Inherited stdio leaves these null; only piped runs yield text. */
-function capturedOutput(result) {
-    return `${asText(result.stdout)}${asText(result.stderr)}`;
-}
-function asText(stream) {
-    return typeof stream === "string" ? stream : "";
-}
-/** A verbose run captured nothing, so this is a no-op. */
-function replay(output) {
-    if (output.trim())
-        errLine(output.trimEnd());
-}
-export function installTinyFishCli({ verbose }) {
-    if (verbose)
-        errLine("Installing the TinyFish CLI...");
-    // Without the prefix, a curl install upgrades npm's global tree and never the PATH binary.
-    const root = installRoot();
-    const prefixArgs = root ? ["--prefix", root.prefix] : [];
-    const result = spawn.sync("npm", ["install", "--global", ...prefixArgs, TINYFISH_CLI_INSTALL_SPEC], captureStdio(verbose));
-    if (result.error || result.status !== 0) {
-        // Built first: it runs the interrupt check, and abandonment must not replay.
-        const error = spawnStepError("Could not install the TinyFish CLI", result);
-        replay(capturedOutput(result));
-        throw error;
-    }
-}
 /** `skills add` is an unconditional overwrite, so it doubles as the refresh path. */
 function skillAddArgs(skillAgents) {
     return [
@@ -80,25 +45,57 @@ const SKILL_ALREADY_CURRENT_PATTERN = /All global skills are up to date/;
 // A lock entry with no recorded hash is untrackable, so `skills` reports it as skipped rather
 // than failed. Left undetected that reads as "up to date" while nothing was refreshed.
 const SKILL_UNCHECKABLE_PATTERN = /cannot be checked automatically/;
-// `skills add` exits non-zero on a fatal error, but per-skill install failures only print.
-const SKILL_INSTALL_FAILURE_PATTERN = /Failed to install/;
+// `skills list --json` reports display names, never slugs (verified on 1.5.15).
+const SKILL_AGENT_DISPLAY_NAMES = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+    "hermes-agent": "Hermes Agent",
+    opencode: "OpenCode",
+};
+const skillListSchema = z.array(z.object({ name: z.string(), agents: z.array(z.string()) }));
+// `add` exits 0 on per-skill failure; the piped list is the verdict.
+function failedListVerdict(skillAgents) {
+    const list = spawn.sync("npx", ["-y", SKILLS_CLI_PACKAGE, "list", "--global", "--json"], {
+        encoding: "utf8",
+        env: skillSpawnEnv(),
+        maxBuffer: STEP_MAX_BUFFER,
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    const verified = !list.error && list.status === 0 && verifiedForAgents(list.stdout ?? "", skillAgents);
+    return verified ? null : list;
+}
+// `list` folds in every agent's dir, so name-only matches stale copies.
+function verifiedForAgents(stdout, skillAgents) {
+    const parsed = skillListSchema.safeParse(parseJson(stdout));
+    if (!parsed.success)
+        return false;
+    const agents = parsed.data
+        .filter((skill) => skill.name === TINYFISH_WEB_SKILL)
+        .flatMap((skill) => skill.agents);
+    return skillAgents.every((agent) => agents.includes(SKILL_AGENT_DISPLAY_NAMES[agent]));
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function installWebSkill(client) {
     if (!client.skillAgent)
         return;
     errLine(`Installing the TinyFish web skill in ${client.displayName}...`);
-    // Piped rather than inherited so the per-skill failure line can be matched; echoed back
-    // so the user still sees what `skills` reported.
-    const result = spawn.sync("npx", skillAddArgs([client.skillAgent]), {
-        encoding: "utf8",
+    // Inherited stdio renders the spinner live as one overwriting line.
+    const add = spawn.sync("npx", skillAddArgs([client.skillAgent]), {
+        stdio: "inherit",
         env: skillSpawnEnv(),
-        maxBuffer: STEP_MAX_BUFFER,
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    if (output.trim())
-        errLine(output.trimEnd());
-    if (result.error || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output)) {
-        throw spawnStepError(`Could not install the TinyFish web skill in ${client.displayName}`, result);
+    const failed = add.error || add.status !== 0 ? add : failedListVerdict([client.skillAgent]);
+    if (failed) {
+        throw spawnStepError(`Could not install the TinyFish web skill in ${client.displayName}`, failed);
     }
 }
 /**
@@ -163,13 +160,19 @@ function reinstallWebSkill(skillAgents, verbose) {
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
     const output = capturedOutput(result);
-    const failed = Boolean(result.error) || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output);
+    // Quiet capture stays (#4434); the list verdict replaced prose matching.
+    const addFailed = Boolean(result.error) || result.status !== 0;
+    const failedList = addFailed ? null : failedListVerdict(skillAgents);
+    const failed = addFailed || failedList !== null;
     if (failed)
-        throwIfInterrupted(result);
+        throwIfInterrupted(failedList ?? result);
     if (verbose || failed)
         replay(output);
-    if (failed)
-        throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
+    if (failed) {
+        throw new Error("Could not refresh the TinyFish web skill", {
+            cause: (failedList ?? result).error,
+        });
+    }
 }
 /** Fallback when no skill-bearing harness is recorded: refresh whatever `skills` tracks. */
 function refreshWebSkillByHash(verbose, untrackedIsExpected = false) {
@@ -203,40 +206,3 @@ function refreshWebSkillByHash(verbose, untrackedIsExpected = false) {
     }
     return !SKILL_ALREADY_CURRENT_PATTERN.test(output);
 }
-export function ensureCliAuthenticated(source, apiKey) {
-    const envKey = apiKey ?? process.env["TINYFISH_API_KEY"];
-    if (envKey) {
-        if (!validateKeyFormat(envKey)) {
-            throw new ConnectStepError("TINYFISH_API_KEY has invalid format", "invalid_config");
-        }
-        // Throwing variant: a write failure must reach connect's catch/flush, not exit(1) past it.
-        writeConfig(envKey);
-        persistApiKeyToEnvironment(envKey);
-        return;
-    }
-    const authStatus = spawn.sync("tinyfish", ["auth", "status"], {
-        stdio: "ignore",
-        timeout: NON_INTERACTIVE_TIMEOUT_MS,
-    });
-    if (commandNotFound(authStatus.error)) {
-        throw spawnStepError(TINYFISH_CLI_NOT_FOUND_MESSAGE, authStatus);
-    }
-    if (authStatus.status === 0)
-        return;
-    // A crashed or timed-out probe says nothing about the stored key, so it must not read as
-    // "not signed in" and drop the user into an interactive login they never asked for.
-    throwIfInterrupted(authStatus);
-    if (authStatus.error) {
-        throw spawnStepError("Could not read TinyFish CLI auth status", authStatus);
-    }
-    errLine("Signing in to the TinyFish CLI...");
-    const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", source], {
-        stdio: "inherit",
-    });
-    if (commandNotFound(loginResult.error)) {
-        throw spawnStepError(TINYFISH_CLI_NOT_FOUND_MESSAGE, loginResult);
-    }
-    if (loginResult.error || loginResult.status !== 0) {
-        throw spawnStepError("Could not authenticate the TinyFish CLI", loginResult);
-    }
-}

package/package.json

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