@tiny-fish/cli 0.12.1-next.137 → 0.12.1-next.139

package/README.md

@@ -277,6 +277,14 @@ TINYFISH_DEBUG=1 tinyfish agent run "..." --url https://example.com
 tinyfish --debug agent run "..." --url https://example.com
 ```
 
+### Telemetry
+
+The CLI reports setup outcomes (which harnesses connected, whether verification passed) and
+checks npm once a day for a newer CLI. Set `TINYFISH_NO_TELEMETRY` to any value other than
+`0`/`false` to disable both. API keys are never sent — only a SHA-256 lookup hash, and only to
+TinyFish-owned origins (`*.tinyfish.ai`, `*.tinyfish.io`) or a local development endpoint
+(`localhost`, `127.0.0.1`, `[::1]`).
+
 ## CI/CD
 
 ```yaml

package/dist/commands/connect.js

@@ -1,10 +1,15 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import spawn from "cross-spawn";
 import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, writeConfig, } from "../lib/auth.js";
 import { CLI_VERSION } from "../lib/constants.js";
-import { cursorMcpPath, writeCursorMcpConfig } from "../lib/cursor-config.js";
+import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig } from "../lib/cursor-config.js";
+import { runConnectAll } from "../lib/connect-all.js";
+import { detectHumanInitiated } from "../lib/harness.js";
 import { errLine } from "../lib/output.js";
+import { telemetryDisabled, telemetryHeaders } from "../lib/setup-telemetry.js";
+import { verifyMcpAuth } from "../lib/verify.js";
+import { recordInstalledVersion } from "../lib/version-marker.js";
 export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
 const SKILL_INSTALL_TIMEOUT_MS = 120_000;
@@ -92,7 +97,7 @@ function installSignalGuard(state, telemetry) {
 async function runGuarded(state, telemetry, body) {
     const uninstallSignalGuard = installSignalGuard(state, telemetry);
     try {
-        body();
+        await body();
     }
     catch (error) {
         if (error instanceof ConnectInterruptedError) {
@@ -123,6 +128,7 @@ const CLAUDE_CODE = {
         patterns: [/^\s*login(?:\s|\[)/m],
         unavailableMessage: MCP_LOGIN_UNAVAILABLE_MESSAGE,
     },
+    headerAuthSupported: true,
     loginArgs: ["mcp", "login", "tinyfish"],
     // Project scope is shared in .mcp.json; a user setup command must not rewrite it.
     removals: [
@@ -220,27 +226,6 @@ const OPENCLAW = {
         unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
     },
 };
-// TinyFish-owned domains plus loopback are the only origins the API key may be sent to.
-// `--url` accepts any http(s) URL, so a user-supplied origin must never receive the key.
-const TRUSTED_TELEMETRY_HOST_SUFFIXES = [".tinyfish.ai", ".tinyfish.io"];
-const TRUSTED_TELEMETRY_LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
-function isTrustedTelemetryOrigin(endpoint) {
-    let url;
-    try {
-        url = new URL(endpoint);
-    }
-    catch {
-        return false;
-    }
-    const host = url.hostname.toLowerCase();
-    // Loopback may use http for local dev; every other trusted origin must be https so the
-    // key is never sent over cleartext.
-    if (TRUSTED_TELEMETRY_LOOPBACK_HOSTS.includes(host))
-        return true;
-    if (url.protocol !== "https:")
-        return false;
-    return TRUSTED_TELEMETRY_HOST_SUFFIXES.some((suffix) => host === suffix.slice(1) || host.endsWith(suffix));
-}
 function storedApiKey() {
     try {
         return loadConfig().api_key;
@@ -253,14 +238,11 @@ function createConnectTelemetry(mcpUrl, client, apiKey) {
     const attemptId = randomUUID();
     const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
     const telemetryKey = apiKey || process.env["TINYFISH_API_KEY"] || storedApiKey();
-    const headers = { "content-type": "application/json" };
-    // SHA-256 lookup key only — the raw key never rides a telemetry request
-    // (OWASP: keep credentials out of anything logging infra might capture).
-    if (telemetryKey && validateKeyFormat(telemetryKey) && isTrustedTelemetryOrigin(endpoint)) {
-        headers["x-api-key-lookup"] = createHash("sha256").update(telemetryKey).digest("hex");
-    }
+    const headers = telemetryHeaders(endpoint, telemetryKey);
     const pending = [];
     async function deliver(body) {
+        if (telemetryDisabled())
+            return;
         // One retry: stale keep-alive sockets eat post-install POSTs. 5xx retries;
         // 4xx never will (schema mismatch, e.g. new stages hitting an old server).
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -560,9 +542,17 @@ async function connectNativeMcpClient(client, options) {
         mcpUrl.searchParams.set("source", CONNECT_SOURCE);
         mcpUrl.searchParams.set("client", client.connectClient);
         mcpUrl.searchParams.set("connect_attempt_id", telemetry.attemptId);
+        // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
+        const storedKey = options.apiKey ?? process.env["TINYFISH_API_KEY"] ?? loadConfig().api_key;
+        const useKeyAuth = client.headerAuthSupported === true && !!storedKey && validateKeyFormat(storedKey);
         state.stage = client.loginArgs ? "registration" : "registration_or_authentication";
         errLine(`Adding TinyFish to ${client.displayName}...`);
-        const addResult = spawn.sync(client.command, client.addArgs(mcpUrl.toString(), options.mcpUrl), {
+        const addResult = spawn.sync(client.command, [
+            ...client.addArgs(mcpUrl.toString(), options.mcpUrl),
+            // Key rides argv — readable via /proc/<pid>/cmdline. Accepted because these CLIs
+            // take headers no other way.
+            ...(useKeyAuth ? ["--header", `X-API-Key: ${storedKey}`] : []),
+        ], {
             stdio: "inherit",
         });
         if (addResult.error || addResult.status !== 0) {
@@ -572,7 +562,10 @@ async function connectNativeMcpClient(client, options) {
             });
         }
         telemetry.track("checkpoint", { phase: "registered" });
-        if (client.loginArgs) {
+        if (useKeyAuth) {
+            errLine("Using your stored TinyFish API key — no browser sign-in needed.");
+        }
+        if (client.loginArgs && !useKeyAuth) {
             state.stage = "client_oauth";
             errLine("Signing in to TinyFish...");
             const loginResult = spawn.sync(client.command, client.loginArgs, {
@@ -598,6 +591,7 @@ async function connectNativeMcpClient(client, options) {
         // Persist once here (skill installed + authenticated) so both success paths, launch
         // or not, record the install; buildConnectHeaders reads it on subsequent requests.
         saveConnectContext(client.connectClient, telemetry.attemptId);
+        recordInstalledVersion();
         errLine(UPGRADE_HINT);
         if (!options.launch) {
             errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
@@ -628,15 +622,7 @@ export async function connectOpenClaw(options) {
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
         if (options.installCli !== false) {
             state.stage = "cli_install";
-            errLine("Installing the TinyFish CLI...");
-            const cliInstallResult = spawn.sync("npm", ["install", "--global", "@tiny-fish/cli@latest"], {
-                stdio: "inherit",
-                timeout: SKILL_INSTALL_TIMEOUT_MS,
-            });
-            if (cliInstallResult.error || cliInstallResult.status !== 0) {
-                throwIfInterrupted(cliInstallResult);
-                throw new Error("Could not install the TinyFish CLI", { cause: cliInstallResult.error });
-            }
+            installTinyFishCli();
             telemetry.track("checkpoint", { phase: "cli_installed" });
         }
         state.stage = "skill_install";
@@ -676,6 +662,7 @@ export async function connectOpenClaw(options) {
         }
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("openclaw", telemetry.attemptId);
+        recordInstalledVersion();
         errLine(UPGRADE_HINT);
         if (!options.launch) {
             errLine("TinyFish is connected. Open OpenClaw to start using it.");
@@ -692,16 +679,21 @@ export async function connectOpenClaw(options) {
 export async function connectCursor(options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, "cursor", options.apiKey);
     const state = { stage: "prerequisite_check", settled: false };
-    await runGuarded(state, telemetry, () => {
+    await runGuarded(state, telemetry, async () => {
         telemetry.track("started");
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
+        // Auth first: a key lets the config carry an X-API-Key header, removing the sign-in hand-back.
+        state.stage = "authentication";
+        ensureCliAuthenticated("cursor", options.apiKey);
+        telemetry.track("checkpoint", { phase: "authenticated" });
+        const resolvedKey = options.apiKey ?? process.env["TINYFISH_API_KEY"] ?? loadConfig().api_key;
         state.stage = "registration";
         errLine("Adding TinyFish to Cursor...");
         const mcpUrl = new URL(options.mcpUrl);
         mcpUrl.searchParams.set("source", CONNECT_SOURCE);
         mcpUrl.searchParams.set("client", "cursor");
         // Attempt id rides telemetry only; persisting it would break idempotency.
-        const result = writeCursorMcpConfig(mcpUrl.toString());
+        const result = writeCursorMcpConfig(mcpUrl.toString(), resolvedKey);
         if (result.status === "corrupt_skip") {
             throw new Error(`Could not update ${cursorMcpPath()}: existing file could not be read or is not valid JSON (${result.error}). ` +
                 `Fix the file, then re-run: tinyfish connect cursor`);
@@ -709,18 +701,43 @@ export async function connectCursor(options) {
         if (result.backupPath) {
             errLine(`Backed up existing Cursor MCP config to ${result.backupPath}`);
         }
+        if (result.repaired) {
+            errLine("Repaired the existing TinyFish entry (updated auth/config to current).");
+        }
         telemetry.track("checkpoint", { phase: "registered" });
-        state.stage = "authentication";
-        ensureCliAuthenticated("cursor", options.apiKey);
-        telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("cursor", telemetry.attemptId);
-        // A server written into mcp.json lands unauthenticated: only Cursor's own "Add to
-        // Cursor" deep link auto-starts OAuth, so name the click or the install never completes.
-        errLine("Added to Cursor. Restart Cursor (or reload the window), then open");
-        errLine('Settings -> Tools & MCP and click Connect on "tinyfish" to sign in.');
+        recordInstalledVersion();
+        if (resolvedKey) {
+            // Deeplink would embed the key in a URL (process args, LaunchServices logs) — reload instead.
+            const verify = await verifyMcpAuth(resolvedKey);
+            if (verify.ok) {
+                errLine("TinyFish is connected and verified (health+auth). Reload the Cursor window (or restart cursor-agent) and it's live.");
+            }
+            else {
+                errLine(`TinyFish is configured, but the authenticated check failed (${verify.reason ?? "unknown"}). ` +
+                    "Fix: rotate/re-enter your key with `tinyfish auth login`, then re-run: tinyfish connect cursor");
+            }
+        }
+        else if (detectHumanInitiated() && launchCursorDeeplink(mcpUrl.toString())) {
+            errLine("Cursor should pop a TinyFish install confirmation — approve it, then sign in when prompted.");
+        }
+        else {
+            errLine("TinyFish is connected. Reload the Cursor window, then approve/sign in under Settings → MCP.");
+        }
         settle(state, telemetry, "completed");
     });
 }
+/** Best-effort: false when no handler/open fails — caller falls back to reload copy. */
+function launchCursorDeeplink(mcpUrl) {
+    const deepLink = cursorInstallDeeplink(mcpUrl);
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [deepLink]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", deepLink]]
+            : ["xdg-open", [deepLink]];
+    const result = spawn.sync(command, args, { stdio: "ignore" });
+    return !result.error && result.status === 0;
+}
 export function launchAgent(client) {
     if (client === "claude-code") {
         launchNativeMcpClient(CLAUDE_CODE);
@@ -747,7 +764,11 @@ export function registerConnect(program) {
     program
         .command("connect")
         .description("Connect TinyFish to an AI agent")
-        .argument("<client>", "Agent client to connect (claude-code, codex, cursor, hermes, or openclaw)")
+        .argument("[client]", "Agent client to connect (claude-code, codex, cursor, hermes, or openclaw)")
+        .option("--all", "Detect and connect every supported harness found on this machine")
+        .option("--dry-run", "Print planned writes per harness without touching anything (--all only)")
+        .option("--uninstall", "Remove TinyFish entries written by connect --all")
+        .option("--skip-launch", "Skip the end-of-install agent launch (--all only)")
         .option("--api-key <apiKey>", "TinyFish API key to persist for the installed skill")
         .option("--launch", "Launch the agent and start the TinyFish walkthrough")
         .option("--url <mcpUrl>", "MCP endpoint override")
@@ -769,6 +790,31 @@ export function registerConnect(program) {
         if (!["http:", "https:"].includes(parsedUrl.protocol)) {
             throw new Error(`Invalid --url value: ${mcpUrl}`);
         }
+        if (options.all) {
+            if (client) {
+                throw new Error("Pass either a client or --all, not both.");
+            }
+            if (options.launch) {
+                throw new Error("--launch is not supported with --all. Connect a single client to launch it.");
+            }
+            const exitCode = await runConnectAll({
+                apiKey: options.apiKey,
+                mcpUrl,
+                dryRun: options.dryRun ?? false,
+                uninstall: options.uninstall ?? false,
+                noLaunch: options.skipLaunch === true,
+            });
+            // Preserve the 130 runGuarded set on Ctrl+C.
+            if (!process.exitCode)
+                process.exitCode = exitCode;
+            return;
+        }
+        if (options.dryRun || options.uninstall) {
+            throw new Error("--dry-run and --uninstall are only supported with --all.");
+        }
+        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 };
         if (client === "claude-code") {
             await connectClaudeCode(connectOptions);

package/dist/lib/client.d.ts

@@ -7,7 +7,7 @@ export declare function buildConnectHeaders(connect: ConnectMap, caller: string
 export declare function runSync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunResponse>;
 export declare function runAsync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunAsyncResponse>;
 export declare function runStream(req: CliAgentRunParams, apiKey: string, signal?: AbortSignal): AsyncGenerator<AgentRunWithStreamingResponse>;
-export declare function listRuns(opts: RunListParams, apiKey: string): Promise<RunListResponse>;
+export declare function listRuns(opts: RunListParams, apiKey: string, timeout?: number): Promise<RunListResponse>;
 export declare function getRun(runId: string, apiKey: string): Promise<Run>;
 export declare function getRunSteps(runId: string, apiKey: string): Promise<RunStepsResponse>;
 export declare function searchQuery(params: SearchQueryParams, apiKey: string): Promise<SearchQueryResponse>;

package/dist/lib/client.js

@@ -256,9 +256,9 @@ export async function* runStream(req, apiKey, signal) {
         }
     }
 }
-export async function listRuns(opts, apiKey) {
+export async function listRuns(opts, apiKey, timeout) {
     try {
-        return await createSdkClient(apiKey).runs.list(opts);
+        return await createSdkClient(apiKey, timeout).runs.list(opts);
     }
     catch (error) {
         rethrowSdkError(error);

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

@@ -0,0 +1,9 @@
+export interface ConnectAllOptions {
+    apiKey?: string;
+    mcpUrl: string;
+    dryRun: boolean;
+    uninstall: boolean;
+    /** Skip the end-of-install agent launch (finale still prints the ask). */
+    noLaunch?: boolean;
+}
+export declare function runConnectAll(opts: ConnectAllOptions): Promise<number>;

package/dist/lib/connect-all.js

@@ -0,0 +1,345 @@
+import * as readline from "node:readline/promises";
+import spawn from "cross-spawn";
+import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectOpenClaw, } from "../commands/connect.js";
+import { loadConfig, validateKeyFormat } from "./auth.js";
+import { detectInstalledHarnesses, FIVE_HARNESSES, } from "./harness-detect.js";
+import { detectHumanInitiated } from "./harness.js";
+import { removeCursorMcpServer, planCursorWrite } from "./cursor-config.js";
+import { errLine, outLine } from "./output.js";
+import { sendSetupCompleted } from "./setup-telemetry.js";
+import { verifyMcpAuth, verifyMcpHealth } from "./verify.js";
+import { printUpdateNoticeIfDrifted, recordInstalledVersion } from "./version-marker.js";
+const DISPLAY_NAMES = {
+    "claude-code": "Claude Code",
+    codex: "Codex",
+    cursor: "Cursor",
+    hermes: "Hermes",
+    openclaw: "OpenClaw",
+};
+// `codex mcp add` succeeds unauthenticated; OAuth lands at first tool use.
+const AUTH_DEFERRED_AT_INSTALL = new Set(["codex"]);
+// Harnesses that drive their own OAuth at install — a stored TinyFish key says nothing
+// about their session, so it must never unlock a headless run for them.
+const HARNESS_OWN_AUTH = new Set(["claude-code", "codex", "hermes"]);
+const AUTH_CHECK_CAPABLE = new Set(["cursor", "openclaw"]);
+// Real removal commands — harness id is not the binary name.
+const UNINSTALL_POINTERS = {
+    "claude-code": "claude mcp remove tinyfish --scope user",
+    codex: "codex mcp remove tinyfish",
+    hermes: "hermes mcp remove tinyfish",
+    openclaw: "openclaw skills uninstall @tinyfish/tinyfish --global",
+};
+function resolvedApiKey(explicitApiKey) {
+    if (explicitApiKey)
+        return explicitApiKey;
+    const envKey = process.env["TINYFISH_API_KEY"];
+    if (envKey)
+        return envKey;
+    try {
+        return loadConfig().api_key;
+    }
+    catch {
+        return undefined;
+    }
+}
+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")
+        return connectClaudeCode(base);
+    if (harness === "codex")
+        return connectCodex(base);
+    if (harness === "hermes")
+        return connectHermes(base);
+    if (harness === "openclaw")
+        return connectOpenClaw({ mcpUrl: opts.mcpUrl, launch: false });
+    return connectCursor({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl });
+}
+async function verifyHarness(harness, mcpUrl, apiKey) {
+    const health = await verifyMcpHealth(mcpUrl);
+    // claude-code is auth-checkable only in key mode (header-authed config).
+    const capable = AUTH_CHECK_CAPABLE.has(harness) || (harness === "claude-code" && !!apiKey);
+    if (!capable || !health.ok)
+        return health;
+    if (!apiKey)
+        return { depth: "health+auth", ok: false, reason: "no stored API key" };
+    return verifyMcpAuth(apiKey);
+}
+function planText(harness, mcpUrl, apiKey) {
+    if (harness === "cursor")
+        return planCursorWrite(mcpUrl, apiKey);
+    return `would run \`tinyfish connect ${harness}\` (harness-owned MCP write; no local file touched by the CLI)`;
+}
+function uninstallPlanText(harness) {
+    if (harness === "cursor") {
+        return "would remove the tinyfish entry from ~/.cursor/mcp.json";
+    }
+    return `would print the removal command \`${UNINSTALL_POINTERS[harness]}\` (config is harness-owned; the CLI removes nothing)`;
+}
+function uninstallHarness(harness, configPath) {
+    const detection = { harness, detected: true, configPath, installed: false };
+    if (harness !== "cursor") {
+        // Harness-owned config — removal happens via each tool's own CLI.
+        return { ...detection, outcome: "uninstall_pointer", fixCommand: UNINSTALL_POINTERS[harness] };
+    }
+    let result;
+    try {
+        result = removeCursorMcpServer();
+    }
+    catch (e) {
+        result = { status: "corrupt_skip", error: e instanceof Error ? e.message : String(e) };
+    }
+    if (result.status === "corrupt_skip") {
+        return {
+            ...detection,
+            outcome: "uninstalled",
+            errorMessage: `could not update Cursor's mcp.json (${result.error}) — nothing removed.`,
+            fixCommand: "Fix ~/.cursor/mcp.json by hand, then re-run: tinyfish connect --all --uninstall",
+        };
+    }
+    if (result.status === "unchanged") {
+        return { ...detection, outcome: "uninstall_noop" };
+    }
+    return { ...detection, outcome: "uninstalled" };
+}
+async function processHarness(detection, opts, prompt) {
+    const { harness, configPath } = detection;
+    if (!detection.detected) {
+        return { harness, detected: false, configPath, installed: false, outcome: "not_detected" };
+    }
+    const base = { harness, detected: true, configPath, installed: false };
+    // dryRun first: --dry-run --uninstall must plan, never reach removeCursorMcpServer().
+    if (opts.dryRun) {
+        const plan = opts.uninstall ? uninstallPlanText(harness) : planText(harness, opts.mcpUrl, resolvedApiKey(opts.apiKey));
+        return { ...base, outcome: "dry_run", fixCommand: plan };
+    }
+    if (opts.uninstall)
+        return uninstallHarness(harness, configPath);
+    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 ownAuthHarness = HARNESS_OWN_AUTH.has(harness) && !(harness === "claude-code" && keyed);
+    const alreadyAuthed = !ownAuthHarness && keyed;
+    if (!isTTY && !alreadyAuthed) {
+        return { ...base, outcome: "no_tty_auth_skip", fixCommand: `tinyfish connect ${harness}` };
+    }
+    if (isTTY && !alreadyAuthed && prompt) {
+        errLine(`step: waiting for browser sign-in to TinyFish for ${DISPLAY_NAMES[harness]}`);
+        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}` };
+        }
+    }
+    // runGuarded swallows Ctrl+C and sets exitCode 130 instead of throwing.
+    const interruptedBefore = process.exitCode === 130;
+    try {
+        await runHarnessConnect(harness, opts);
+    }
+    catch (e) {
+        return {
+            ...base,
+            outcome: "failed",
+            errorMessage: e instanceof Error ? e.message : String(e),
+            fixCommand: `tinyfish connect ${harness}`,
+        };
+    }
+    if (!interruptedBefore && process.exitCode === 130) {
+        return { ...base, outcome: "interrupted", fixCommand: `tinyfish connect ${harness}` };
+    }
+    recordInstalledVersion();
+    const verify = await verifyHarness(harness, opts.mcpUrl, resolvedApiKey(opts.apiKey));
+    return {
+        ...base,
+        installed: true,
+        outcome: "installed",
+        verifyDepth: verify.depth,
+        verifyOk: verify.ok,
+        verifyReason: verify.reason,
+    };
+}
+function summaryLine(result, uninstall) {
+    const name = DISPLAY_NAMES[result.harness];
+    if (!result.detected) {
+        const next = uninstall
+            ? "nothing to remove"
+            : `Install ${name}, then run: tinyfish connect ${result.harness}`;
+        return `- ${name} — not detected (searched ${result.configPath}). ${next}`;
+    }
+    if (result.outcome === "not_reached") {
+        return `… ${name} — not reached, the run stopped early. Fix: ${result.fixCommand}`;
+    }
+    if (result.outcome === "dry_run") {
+        return `… ${name} — ${result.fixCommand}`;
+    }
+    if (result.outcome === "no_tty_auth_skip") {
+        return `… ${name} — skipped, no stored credentials and no terminal to sign in. Fix: ${result.fixCommand}`;
+    }
+    if (result.outcome === "uninstall_pointer") {
+        return `… ${name} — not removed automatically (config is owned by ${name}). Run: ${result.fixCommand}`;
+    }
+    if (result.outcome === "uninstall_noop") {
+        return `… ${name} — no tinyfish entry found, nothing removed`;
+    }
+    if (result.outcome === "uninstalled") {
+        return result.errorMessage
+            ? `✗ ${name} — ${result.errorMessage} Fix: ${result.fixCommand}`
+            : `✓ ${name} — removed`;
+    }
+    if (result.outcome === "interrupted") {
+        return `✗ ${name} — interrupted before finishing. Fix: ${result.fixCommand}`;
+    }
+    if (result.outcome === "failed") {
+        return `✗ ${name} — install failed: ${result.errorMessage}. Fix: ${result.fixCommand}`;
+    }
+    const authDeferred = AUTH_DEFERRED_AT_INSTALL.has(result.harness);
+    const verifyLabel = result.verifyDepth ? `verified: ${result.verifyDepth}` : "not verified";
+    if (authDeferred || result.verifyOk === false) {
+        const reason = authDeferred
+            ? "one step left: sign in when your agent first runs"
+            : `verify warning (${verifyLabel}): ${result.verifyReason ?? "unknown"}`;
+        return `⚠ ${name} — installed, ${reason}. Fix: run \`/tinyfish:doctor\` in ${name} once it's open.`;
+    }
+    return `✓ ${name} — installed, ${verifyLabel}`;
+}
+function computeExitCode(results) {
+    const detected = results.filter((r) => r.detected);
+    if (detected.length === 0)
+        return 1;
+    // Only real install attempts count toward the success/failure denominator.
+    const attempted = detected.filter((r) => r.outcome === "installed" || r.outcome === "failed" || r.outcome === "interrupted");
+    if (attempted.length === 0)
+        return 0;
+    return attempted.some((r) => r.outcome === "installed") ? 0 : 1;
+}
+export async function runConnectAll(opts) {
+    const isTTY = detectHumanInitiated();
+    const rl = isTTY
+        ? readline.createInterface({ input: process.stdin, output: process.stderr })
+        : undefined;
+    let prompt;
+    if (rl) {
+        // Without a close-linked signal, question() never settles on Ctrl+D.
+        const closed = new AbortController();
+        rl.on("close", () => closed.abort());
+        prompt = (question) => rl.question(question, { signal: closed.signal });
+    }
+    const detections = detectInstalledHarnesses();
+    const results = [];
+    try {
+        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);
+            }
+            catch (e) {
+                // Isolation: one harness throwing never stops the others.
+                result = {
+                    harness,
+                    detected: detection.detected,
+                    configPath: detection.configPath,
+                    installed: false,
+                    outcome: "failed",
+                    errorMessage: e instanceof Error ? e.message : String(e),
+                    fixCommand: `tinyfish connect ${harness}`,
+                };
+            }
+            results.push(result);
+            // Ctrl+C means stop, not continue to the next harness.
+            if (result.outcome === "interrupted")
+                break;
+        }
+    }
+    finally {
+        rl?.close();
+    }
+    // The interrupt break truncates `results`; pad so the 5-entry telemetry schema still parses.
+    for (const detection of detections) {
+        if (results.some((r) => r.harness === detection.harness))
+            continue;
+        results.push({
+            ...detection,
+            installed: false,
+            outcome: detection.detected ? "not_reached" : "not_detected",
+            fixCommand: `tinyfish connect ${detection.harness}`,
+        });
+    }
+    outLine("");
+    outLine("TinyFish setup summary:");
+    for (const result of results)
+        outLine(summaryLine(result, opts.uninstall));
+    if (results.every((r) => !r.detected)) {
+        outLine("");
+        outLine("No supported harness found. Install one of: " + FIVE_HARNESSES.join(", "));
+        if (!opts.uninstall)
+            outLine("Then run: npx @tiny-fish/cli connect --all");
+        return 1;
+    }
+    if (!opts.dryRun && !opts.uninstall) {
+        const harnessTelemetry = results.map((r) => ({
+            harness: r.harness,
+            detected: r.detected,
+            installed: r.installed,
+            verify_depth: r.verifyDepth ?? null,
+            verify_ok: r.verifyOk ?? null,
+        }));
+        await sendSetupCompleted(opts.mcpUrl, harnessTelemetry, resolvedApiKey(opts.apiKey));
+        await printUpdateNoticeIfDrifted();
+    }
+    const exitCode = computeExitCode(results);
+    const interrupted = results.some((r) => r.outcome === "interrupted");
+    if (exitCode === 0 && !interrupted && !opts.dryRun && !opts.uninstall && results.some((r) => r.installed)) {
+        outLine("");
+        if (isTTY && !opts.noLaunch && (await launchFirstTask(results))) {
+            return exitCode;
+        }
+        outLine('Now ask your agent: "use TinyFish to find today\'s top Hacker News story"');
+    }
+    return exitCode;
+}
+const FIRST_TASK_PROMPT = "My TinyFish setup just finished — verify it with a real run: use the TinyFish search tool to " +
+    "find today's top Hacker News story, then fetch that page with the TinyFish fetch tool and give " +
+    "me a two-line summary. Show which tools you call.";
+// Launchable seeded agents, best-first — cursor-agent shares ~/.cursor/mcp.json with the IDE.
+const LAUNCHERS = [
+    { harness: "cursor", command: "cursor-agent", args: [FIRST_TASK_PROMPT] },
+    { harness: "claude-code", command: "claude", args: [FIRST_TASK_PROMPT] },
+];
+async function launchFirstTask(results) {
+    const candidates = LAUNCHERS.filter((l) => results.some((r) => r.harness === l.harness && r.installed));
+    if (candidates.length === 0)
+        return false;
+    // Several installs: ask rather than pick a favorite; plain enter skips.
+    let chosen = candidates[0];
+    if (candidates.length > 1) {
+        const menu = candidates.map((l, i) => `[${i + 1}] ${DISPLAY_NAMES[l.harness]}`).join("  ");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        let answer;
+        try {
+            answer = await rl.question(`Try your first TinyFish task now? ${menu}  [enter] skip: `);
+        }
+        catch {
+            return false;
+        }
+        finally {
+            rl.close();
+        }
+        const pick = Number.parseInt(answer.trim(), 10);
+        if (!pick || pick < 1 || pick > candidates.length)
+            return false;
+        chosen = candidates[pick - 1];
+    }
+    if (!chosen)
+        return false;
+    outLine(`Starting ${DISPLAY_NAMES[chosen.harness]} with your first TinyFish task...`);
+    const result = spawn.sync(chosen.command, chosen.args, { stdio: "inherit" });
+    return !result.error;
+}

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

@@ -4,10 +4,14 @@ export interface CursorMcpWriteResult {
     status: "written" | "unchanged" | "corrupt_skip";
     backupPath?: string;
     error?: string;
+    /** A pre-existing tinyfish entry was replaced — a repair, not a fresh install. */
+    repaired?: boolean;
 }
 /** Dry-run description of the pending write; touches nothing. */
-export declare function planCursorWrite(mcpUrl: string): string;
+export declare function planCursorWrite(mcpUrl: string, apiKey?: string): string;
 /** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
-export declare function writeCursorMcpConfig(mcpUrl: string): CursorMcpWriteResult;
+export declare function writeCursorMcpConfig(mcpUrl: string, apiKey?: string): CursorMcpWriteResult;
+/** Cursor deeplink format: cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64 */
+export declare function cursorInstallDeeplink(mcpUrl: string): string;
 /** Removes only the `tinyfish` key. */
 export declare function removeCursorMcpServer(): CursorMcpWriteResult;

package/dist/lib/cursor-config.js

@@ -12,8 +12,9 @@ export function cursorMcpPath() {
 function isPlainRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function buildTinyfishServerEntry(mcpUrl) {
-    return { url: mcpUrl };
+// Footgun: the key lands plaintext in mcp.json (0600) — per-device keys are the GA hardening.
+function buildTinyfishServerEntry(mcpUrl, apiKey) {
+    return apiKey ? { url: mcpUrl, headers: { "X-API-Key": apiKey } } : { url: mcpUrl };
 }
 function parseMcpJson(raw) {
     try {
@@ -46,20 +47,23 @@ function readExisting() {
     return { raw, parsed: parsed.value };
 }
 /** Dry-run description of the pending write; touches nothing. */
-export function planCursorWrite(mcpUrl) {
+export function planCursorWrite(mcpUrl, apiKey) {
     const existing = readExisting();
     const filePath = cursorMcpPath();
     if ("error" in existing) {
         return `${filePath}: existing file is corrupt (${existing.error}) — would skip and leave it untouched`;
     }
+    const authNote = apiKey
+        ? " with an API-key header — the key is stored in plaintext in that file (value not shown here)"
+        : "";
     const servers = existing.parsed.mcpServers;
     const current = isPlainRecord(servers) ? servers[TINYFISH_SERVER_KEY] : undefined;
-    if (JSON.stringify(current) === JSON.stringify(buildTinyfishServerEntry(mcpUrl))) {
+    if (JSON.stringify(current) === JSON.stringify(buildTinyfishServerEntry(mcpUrl, apiKey))) {
         return `${filePath}: already has the tinyfish MCP entry — no change`;
     }
     return existing.raw === undefined
-        ? `${filePath}: would create with a "tinyfish" MCP server entry`
-        : `${filePath}: would back up to a timestamped copy, then merge in the "tinyfish" MCP server entry`;
+        ? `${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}`;
 }
 // Backup, then atomic temp+rename; pid avoids same-millisecond backup collisions.
 function commitServers(filePath, existing, servers) {
@@ -82,7 +86,7 @@ function commitServers(filePath, existing, servers) {
     return { status: "written", backupPath };
 }
 /** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
-export function writeCursorMcpConfig(mcpUrl) {
+export function writeCursorMcpConfig(mcpUrl, apiKey) {
     const filePath = cursorMcpPath();
     const existing = readExisting();
     if ("error" in existing)
@@ -90,12 +94,18 @@ export function writeCursorMcpConfig(mcpUrl) {
     const servers = isPlainRecord(existing.parsed.mcpServers)
         ? { ...existing.parsed.mcpServers }
         : {};
-    const nextEntry = buildTinyfishServerEntry(mcpUrl);
+    const nextEntry = buildTinyfishServerEntry(mcpUrl, apiKey);
     if (JSON.stringify(servers[TINYFISH_SERVER_KEY]) === JSON.stringify(nextEntry)) {
         return { status: "unchanged" };
     }
+    const repaired = TINYFISH_SERVER_KEY in servers;
     servers[TINYFISH_SERVER_KEY] = nextEntry;
-    return commitServers(filePath, existing, servers);
+    return { ...commitServers(filePath, existing, servers), repaired };
+}
+/** Cursor deeplink format: cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64 */
+export function cursorInstallDeeplink(mcpUrl) {
+    const config = Buffer.from(JSON.stringify(buildTinyfishServerEntry(mcpUrl))).toString("base64");
+    return `cursor://anysphere.cursor-deeplink/mcp/install?name=${TINYFISH_SERVER_KEY}&config=${encodeURIComponent(config)}`;
 }
 /** Removes only the `tinyfish` key. */
 export function removeCursorMcpServer() {

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

@@ -0,0 +1,9 @@
+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;
+export interface HarnessDetection {
+    harness: FiveHarness;
+    detected: boolean;
+    configPath: string;
+}
+export declare function detectInstalledHarnesses(): HarnessDetection[];

package/dist/lib/harness-detect.js

@@ -0,0 +1,28 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+export const FIVE_HARNESSES = ["claude-code", "codex", "cursor", "hermes", "openclaw"];
+// Presence detection only — dir existence means "installed", nothing more.
+const CONFIG_DIRS = {
+    "claude-code": ".claude",
+    codex: ".codex",
+    cursor: ".cursor",
+    hermes: ".hermes",
+    openclaw: ".openclaw",
+};
+export function harnessConfigPath(harness) {
+    return path.join(os.homedir(), CONFIG_DIRS[harness]); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+}
+export function detectInstalledHarnesses() {
+    return FIVE_HARNESSES.map((harness) => {
+        const configPath = harnessConfigPath(harness);
+        let detected;
+        try {
+            detected = fs.statSync(configPath).isDirectory();
+        }
+        catch {
+            detected = false;
+        }
+        return { harness, detected, configPath };
+    });
+}

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

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * `TINYFISH_NO_TELEMETRY` suppresses ALL CLI-emitted network analytics
+ * (setup_completed, connect-event, update check). Any value except `0`/`false`
+ * opts out — a privacy switch must not fail closed on `true`.
+ */
+export declare function telemetryDisabled(): boolean;
+export declare function isTrustedTelemetryOrigin(endpoint: string): boolean;
+/** SHA-256 lookup key only, and only to trusted origins — the raw key never rides telemetry. */
+export declare function telemetryHeaders(endpoint: string, apiKey?: string): Record<string, string>;
+declare const harnessResultSchema: z.ZodObject<{
+    harness: z.ZodEnum<{
+        openclaw: "openclaw";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        "claude-code": "claude-code";
+    }>;
+    detected: z.ZodBoolean;
+    installed: z.ZodBoolean;
+    verify_depth: z.ZodNullable<z.ZodEnum<{
+        health: "health";
+        "health+auth": "health+auth";
+    }>>;
+    verify_ok: z.ZodNullable<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const setupCompletedPayloadSchema: z.ZodObject<{
+    harnesses: z.ZodArray<z.ZodObject<{
+        harness: z.ZodEnum<{
+            openclaw: "openclaw";
+            cursor: "cursor";
+            codex: "codex";
+            hermes: "hermes";
+            "claude-code": "claude-code";
+        }>;
+        detected: z.ZodBoolean;
+        installed: z.ZodBoolean;
+        verify_depth: z.ZodNullable<z.ZodEnum<{
+            health: "health";
+            "health+auth": "health+auth";
+        }>>;
+        verify_ok: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    cli_version: z.ZodString;
+}, z.core.$strip>;
+export type SetupCompletedPayload = z.infer<typeof setupCompletedPayloadSchema>;
+export type HarnessResult = z.infer<typeof harnessResultSchema>;
+/** Fire-and-forget, 2s cap; raw keys never ride telemetry. */
+export declare function sendSetupCompleted(mcpUrl: string, harnesses: HarnessResult[], apiKey?: string): Promise<void>;
+export {};

package/dist/lib/setup-telemetry.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { validateKeyFormat } from "./auth.js";
+import { CLI_VERSION } from "./constants.js";
+import { FIVE_HARNESSES } from "./harness-detect.js";
+import { errLine } from "./output.js";
+const SETUP_TELEMETRY_TIMEOUT_MS = 2_000;
+/**
+ * `TINYFISH_NO_TELEMETRY` suppresses ALL CLI-emitted network analytics
+ * (setup_completed, connect-event, update check). Any value except `0`/`false`
+ * opts out — a privacy switch must not fail closed on `true`.
+ */
+export function telemetryDisabled() {
+    const value = (process.env["TINYFISH_NO_TELEMETRY"] ?? "").trim().toLowerCase();
+    return value !== "" && value !== "0" && value !== "false";
+}
+// TinyFish-owned domains plus loopback are the only origins the API key may be sent to.
+// `--url` accepts any http(s) URL, so a user-supplied origin must never receive the key.
+const TRUSTED_TELEMETRY_HOST_SUFFIXES = [".tinyfish.ai", ".tinyfish.io"];
+const TRUSTED_TELEMETRY_LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+export function isTrustedTelemetryOrigin(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        return false;
+    }
+    const host = url.hostname.toLowerCase();
+    // Loopback may use http for local dev; every other trusted origin must be https so the
+    // key is never sent over cleartext.
+    if (TRUSTED_TELEMETRY_LOOPBACK_HOSTS.includes(host))
+        return true;
+    if (url.protocol !== "https:")
+        return false;
+    return TRUSTED_TELEMETRY_HOST_SUFFIXES.some((suffix) => host === suffix.slice(1) || host.endsWith(suffix));
+}
+/** SHA-256 lookup key only, and only to trusted origins — the raw key never rides telemetry. */
+export function telemetryHeaders(endpoint, apiKey) {
+    const headers = { "content-type": "application/json" };
+    if (apiKey && validateKeyFormat(apiKey) && isTrustedTelemetryOrigin(endpoint)) {
+        headers["x-api-key-lookup"] = createHash("sha256").update(apiKey).digest("hex");
+    }
+    return headers;
+}
+const harnessResultSchema = z.object({
+    harness: z.enum(FIVE_HARNESSES),
+    detected: z.boolean(),
+    installed: z.boolean(),
+    verify_depth: z.enum(["health", "health+auth"]).nullable(),
+    verify_ok: z.boolean().nullable(),
+});
+export const setupCompletedPayloadSchema = z.object({
+    harnesses: z
+        .array(harnessResultSchema)
+        .length(FIVE_HARNESSES.length)
+        .refine((results) => new Set(results.map((r) => r.harness)).size === FIVE_HARNESSES.length, {
+        message: "expected one result per harness",
+    }),
+    cli_version: z.string(),
+});
+/** Fire-and-forget, 2s cap; raw keys never ride telemetry. */
+export async function sendSetupCompleted(mcpUrl, harnesses, apiKey) {
+    if (telemetryDisabled())
+        return;
+    let endpoint;
+    let body;
+    try {
+        // Parse inside try — schema violation must not crash finished setup.
+        const payload = setupCompletedPayloadSchema.parse({ harnesses, cli_version: CLI_VERSION });
+        endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
+        body = JSON.stringify({ event: "setup_completed", ...payload });
+    }
+    catch (e) {
+        if (process.env["TINYFISH_DEBUG"]) {
+            errLine(`setup telemetry skipped: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return;
+    }
+    const headers = telemetryHeaders(endpoint, apiKey);
+    // One retry: stale keep-alive sockets eat post-install POSTs, and this is the
+    // headline `--all` metric. 5xx retries; 4xx never will.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers,
+                body,
+                redirect: "error",
+                signal: AbortSignal.timeout(SETUP_TELEMETRY_TIMEOUT_MS),
+            });
+            if (response.ok)
+                return;
+            if (response.status < 500) {
+                if (process.env["TINYFISH_DEBUG"]) {
+                    errLine(`setup telemetry rejected: HTTP ${response.status}`);
+                }
+                return;
+            }
+        }
+        catch (e) {
+            if (process.env["TINYFISH_DEBUG"]) {
+                errLine(`setup telemetry failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+}

package/dist/lib/verify.d.ts

@@ -0,0 +1,10 @@
+export type VerifyDepth = "health" | "health+auth";
+export interface VerifyResult {
+    depth: VerifyDepth;
+    ok: boolean;
+    reason?: string;
+}
+/** Reachability check. Verify failure is a warning, never install failure. */
+export declare function verifyMcpHealth(mcpUrl: string): Promise<VerifyResult>;
+/** Authenticated check — only where the CLI holds the key (Cursor, OpenClaw). */
+export declare function verifyMcpAuth(apiKey: string): Promise<VerifyResult>;

package/dist/lib/verify.js

@@ -0,0 +1,36 @@
+import { listRuns } from "./client.js";
+const VERIFY_TIMEOUT_MS = 5_000;
+/** Reachability check. Verify failure is a warning, never install failure. */
+export async function verifyMcpHealth(mcpUrl) {
+    try {
+        const response = await fetch(mcpUrl, {
+            method: "GET",
+            // Redirect (captive portal, typo'd --url) is not healthy.
+            redirect: "error",
+            signal: AbortSignal.timeout(VERIFY_TIMEOUT_MS),
+        });
+        // MCP rejects bare GET with 4xx — still proves endpoint routed.
+        if (response.status >= 500) {
+            return { depth: "health", ok: false, reason: `endpoint returned HTTP ${response.status}` };
+        }
+        return { depth: "health", ok: true };
+    }
+    catch (e) {
+        return {
+            depth: "health",
+            ok: false,
+            reason: e instanceof Error ? e.message : "network error reaching MCP endpoint",
+        };
+    }
+}
+/** Authenticated check — only where the CLI holds the key (Cursor, OpenClaw). */
+export async function verifyMcpAuth(apiKey) {
+    try {
+        // Bound it: the SDK default is 600s, and a warning-only check must never hang an install.
+        await listRuns({ limit: 1 }, apiKey, VERIFY_TIMEOUT_MS);
+        return { depth: "health+auth", ok: true };
+    }
+    catch (e) {
+        return { depth: "health+auth", ok: false, reason: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/lib/version-marker.d.ts

@@ -0,0 +1,10 @@
+/** Install-time, offline-safe; best-effort — never fails a finished install. */
+export declare function recordInstalledVersion(): void;
+interface UpdateCheckResult {
+    updateAvailable: boolean;
+    latest?: string;
+}
+/** Throttled npm-currency check; never auto-mutates the install. */
+export declare function checkForCliUpdate(now?: number): Promise<UpdateCheckResult>;
+export declare function printUpdateNoticeIfDrifted(): Promise<void>;
+export {};

package/dist/lib/version-marker.js

@@ -0,0 +1,109 @@
+import * as fs from "fs";
+import * as path from "path";
+import { z } from "zod";
+import { configDir } from "./auth.js";
+import { CLI_VERSION } from "./constants.js";
+import { errLine } from "./output.js";
+import { telemetryDisabled } from "./setup-telemetry.js";
+const MARKER_FILE = "skill-version-marker.json";
+const THROTTLE_MS = 24 * 60 * 60 * 1000;
+const CHECK_TIMEOUT_MS = 5_000;
+// npm is the only currency signal with a publisher behind it: the cookbook repo has no
+// releases and no release automation, so a tag check would report "up to date" forever.
+const REGISTRY_URL = "https://registry.npmjs.org/@tiny-fish/cli/latest";
+const markerSchema = z.object({
+    last_checked_at: z.number().optional(),
+    last_known_latest: z.string().optional(),
+});
+function markerPath() {
+    return path.join(configDir(), MARKER_FILE);
+}
+function readMarker() {
+    try {
+        const parsed = markerSchema.safeParse(JSON.parse(fs.readFileSync(markerPath(), "utf8")));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeMarker(state) {
+    fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    const tmpPath = `${markerPath()}.tmp-${process.pid}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(state), { mode: 0o600 });
+    fs.renameSync(tmpPath, markerPath());
+}
+/** Install-time, offline-safe; best-effort — never fails a finished install. */
+export function recordInstalledVersion() {
+    try {
+        writeMarker({ ...readMarker() });
+    }
+    catch {
+        // marker is a nice-to-have
+    }
+}
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)$/;
+/** Strictly newer; false on unparsable input. */
+function isNewer(current, latest) {
+    const c = SEMVER.exec(current);
+    const l = SEMVER.exec(latest);
+    if (!c || !l)
+        return false;
+    for (let i = 1; i <= 3; i++) {
+        const cn = Number(c[i]);
+        const ln = Number(l[i]);
+        if (ln !== cn)
+            return ln > cn;
+    }
+    return false;
+}
+/** Throttled npm-currency check; never auto-mutates the install. */
+export async function checkForCliUpdate(now = Date.now()) {
+    const marker = readMarker();
+    // No marker means the CLI never installed anything — nothing to nag about.
+    if (!marker || telemetryDisabled())
+        return { updateAvailable: false };
+    const cached = () => ({
+        updateAvailable: marker.last_known_latest !== undefined && isNewer(CLI_VERSION, marker.last_known_latest),
+        ...(marker.last_known_latest !== undefined ? { latest: marker.last_known_latest } : {}),
+    });
+    // Time-based only — failed fetch must not stall every invocation.
+    if (marker.last_checked_at !== undefined && now - marker.last_checked_at < THROTTLE_MS) {
+        return cached();
+    }
+    let latest;
+    try {
+        const response = await fetch(REGISTRY_URL, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+        });
+        if (response.ok) {
+            const body = (await response.json());
+            if (typeof body.version === "string")
+                latest = body.version;
+        }
+    }
+    catch {
+        // Unreachable registry — don't fail setup, don't erase the cache.
+    }
+    try {
+        writeMarker({
+            ...marker,
+            last_checked_at: now,
+            last_known_latest: latest ?? marker.last_known_latest,
+        });
+    }
+    catch {
+        // best-effort
+    }
+    // Fall back to the cache so consecutive invocations can't disagree.
+    if (!latest)
+        return cached();
+    return { updateAvailable: isNewer(CLI_VERSION, latest), latest };
+}
+export async function printUpdateNoticeIfDrifted() {
+    const { updateAvailable } = await checkForCliUpdate();
+    if (updateAvailable) {
+        errLine("a newer TinyFish CLI is available — re-run `npx @tiny-fish/cli connect --all`");
+    }
+}

package/package.json

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