@tiny-fish/cli 0.30.1-next.251 → 0.30.1-next.253

package/dist/commands/connect.d.ts

@@ -50,5 +50,5 @@ export declare function connectCursor(options: {
     attemptId?: string;
     verbose?: boolean;
 }): Promise<void>;
-export declare function launchAgent(client: AgentClient): void;
+export declare function launchAgent(client: AgentClient): Promise<void>;
 export declare function registerConnect(program: Command): void;

package/dist/commands/connect.js

@@ -5,7 +5,7 @@ import { captureStdio, capturedOutput, HoistedFailureReportedError, installTinyF
 import { ensureCliAuthenticated } from "../lib/connect-auth.js";
 import { createStdinPrompt, runCliFallback } from "../lib/connect-fallback.js";
 import { installWebSkill } from "../lib/skill-install.js";
-import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, finishSetupCommand, requireCommandSupport, runGuarded, settle, SignInTimeoutError, spawnStepError, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
+import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, finishSetupCommand, requireCommandSupport, runGuarded, settle, SignInTimeoutError, spawnStepError, spawnRemoval, } from "../lib/connect-runtime.js";
 import { cursorInstallDeeplink, cursorMcpPath, readCursorTinyfishEntry, writeCursorMcpConfig, } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
 import { AuthMode, RELOAD_ACTION } from "../lib/harness-detect.js";
@@ -18,13 +18,9 @@ import { z } from "zod";
 import { verifyMcpAuth } from "../lib/verify.js";
 export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 function removeExistingRegistration(client, removal, verbose) {
-    const result = spawn.sync(client.command, removal.args, {
-        encoding: "utf8",
-        timeout: NON_INTERACTIVE_TIMEOUT_MS,
-    });
+    const result = spawnRemoval(client.command, removal.args);
     if (result.status === 0)
         return;
-    throwIfInterrupted(result);
     // Best-effort: a stale entry makes `mcp add` error or upsert, with a truer message.
     if (!verbose)
         return;
@@ -208,7 +204,7 @@ async function connectNativeMcpClient(client, options) {
         state.authMode = authMode;
         // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
         settle(state, telemetry, "completed", { authMode });
-        runPostInstallSteps(client, options, state, telemetry, signInDeferred);
+        await runPostInstallSteps(client, options, state, telemetry, signInDeferred);
     });
     return state.authMode;
 }
@@ -224,13 +220,13 @@ function connectedLine(client, signInDeferred) {
         `${RELOAD_ACTION[client.connectClient]} to pick up the tools.`);
 }
 // Runs after `completed` settled: steps fail alone, the rest still run.
-function runPostInstallSteps(client, options, state, telemetry, signInDeferred) {
+async 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) => {
+    const attempt = async (stage, run) => {
         state.stage = stage;
         try {
-            run();
+            await run();
         }
         catch (error) {
             if (error instanceof ConnectInterruptedError)
@@ -241,17 +237,17 @@ function runPostInstallSteps(client, options, state, telemetry, signInDeferred)
     };
     try {
         if (options.cliInstall !== false) {
-            attempt("cli_install", () => runCliInstallStep(options, telemetry));
+            await attempt("cli_install", () => runCliInstallStep(options, telemetry));
         }
         if (client.skillAgent) {
-            attempt("skill_install", () => {
+            await attempt("skill_install", () => {
                 installWebSkill(client, { verbose: options.verbose ?? false });
                 telemetry.track("checkpoint", { phase: "skill_installed" });
             });
         }
         // Before auth: a failed sign-in must not lose the harness record.
         saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
-        attempt("authentication", () => {
+        await attempt("authentication", () => {
             // A set timeout means headless; never shell an interactive login.
             ensureCliAuthenticated(client.connectClient, options.apiKey, {
                 interactiveLogin: options.authTimeoutMs === undefined,
@@ -266,11 +262,15 @@ function runPostInstallSteps(client, options, state, telemetry, signInDeferred)
                 errLine(connectedLine(client, signInDeferred));
         }
         else {
-            attempt("walkthrough_launch", () => {
+            await attempt("walkthrough_launch", async () => {
                 // Before the handover, or the only sign-in instructions scroll past under the agent.
                 if (signInDeferred && client.signInHint)
                     errLine(client.signInHint);
-                launchNativeMcpClient(client);
+                await launchNativeMcpClient(client, async (outcome) => {
+                    telemetry.track("checkpoint", { phase: walkthroughPhase(outcome) });
+                    // Flushed pre-block; the session-long handover would strand the delivery.
+                    await telemetry.flush();
+                });
             });
         }
     }
@@ -304,6 +304,9 @@ function runCliInstallStep(options, telemetry) {
     installTinyFishCli({ verbose: options.verbose ?? false, announce: true });
     telemetry.track("checkpoint", { phase: "cli_installed" });
 }
+function walkthroughPhase(outcome) {
+    return outcome === "printed" ? "walkthrough_prompt_printed" : "walkthrough_launched";
+}
 function finishSetupHint(connectClient) {
     return `Finish setup with: ${finishSetupCommand(connectClient)}`;
 }
@@ -396,7 +399,11 @@ export async function connectOpenClaw(options) {
         }
         state.stage = "walkthrough_launch";
         try {
-            launchOpenClawWalkthrough();
+            await launchOpenClawWalkthrough(async (outcome) => {
+                telemetry.track("checkpoint", { phase: walkthroughPhase(outcome) });
+                // Flushed pre-block; the session-long handover would strand the delivery.
+                await telemetry.flush();
+            });
         }
         catch (error) {
             trackPostInstallFailure("OpenClaw", state, telemetry, error);
@@ -515,8 +522,8 @@ const AGENT_LAUNCHERS = {
         throw new Error("Cursor has no launchable walkthrough. Open Cursor and start chatting.");
     },
 };
-export function launchAgent(client) {
-    AGENT_LAUNCHERS[client]();
+export async function launchAgent(client) {
+    await AGENT_LAUNCHERS[client]();
 }
 // A new client fails to compile until wired here.
 const CLIENT_CONNECTORS = {

package/dist/commands/onboard.js

@@ -187,7 +187,7 @@ async function runAgentSteps(interactive) {
     if (!launchId)
         return;
     try {
-        launchAgent(launchId);
+        await launchAgent(launchId);
     }
     catch (error) {
         errLine(`   Could not open ${agentLabel(launchId)}: ${errorMessage(error)}`);

package/dist/lib/auth.d.ts

@@ -32,6 +32,10 @@ export declare function writeConfig(apiKey: string): void;
 export declare function saveConfig(apiKey: string): void;
 /** `authMode` omitted rewrites the entry without one: a reconnect that degraded must not keep a stale key claim. */
 export declare function saveConnectContext(client: string, attemptId: string, authMode?: RecordedAuthMode): void;
+/** Distinguishes a missing entry from an unreadable config file. */
+export declare function connectContextState(client: string): "present" | "absent" | "unreadable";
+/** Kept marker after uninstall makes doctor offer to reinstall the harness. */
+export declare function clearConnectContext(client: string): void;
 interface EnvironmentOptions {
     platform?: typeof process.platform;
     shell?: string;

package/dist/lib/auth.js

@@ -142,6 +142,43 @@ export function saveConnectContext(client, attemptId, authMode) {
         errLine(`Warning: could not persist connect context: ${e instanceof Error ? e.message : String(e)}`);
     }
 }
+/** Distinguishes a missing entry from an unreadable config file. */
+export function connectContextState(client) {
+    let raw;
+    try {
+        raw = fs.readFileSync(configFile(), "utf8");
+    }
+    catch (e) {
+        return e.code === "ENOENT" ? "absent" : "unreadable";
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const entry = parsed && typeof parsed === "object" ? parsed.connect?.[client] : undefined;
+        return entry ? "present" : "absent";
+    }
+    catch {
+        return "unreadable";
+    }
+}
+/** Kept marker after uninstall makes doctor offer to reinstall the harness. */
+export function clearConnectContext(client) {
+    // Read-first: writing through an unreadable config would rewrite it as {}.
+    if (connectContextState(client) !== "present")
+        return;
+    try {
+        updateConfig((config) => {
+            if (!config.connect?.[client])
+                return config;
+            const remaining = Object.fromEntries(Object.entries(config.connect).filter(([key]) => key !== client));
+            const { connect, ...rest } = config;
+            void connect;
+            return Object.keys(remaining).length > 0 ? { ...rest, connect: remaining } : rest;
+        });
+    }
+    catch (e) {
+        errLine(`Warning: could not clear connect context: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
 export function persistApiKeyToEnvironment(apiKey, options = {}) {
     const platform = options.platform ?? process.platform;
     if (platform === "win32") {

package/dist/lib/connect-all.js

@@ -1,11 +1,11 @@
 import * as readline from "node:readline/promises";
 import spawn from "cross-spawn";
 import { connectClaudeCode, connectCodex, connectCursor, connectGrok, connectHermes, connectOpenClaw, connectOpencode, } from "../commands/connect.js";
-import { loadConfig, validatedApiKey } from "./auth.js";
+import { clearConnectContext, connectContextState, loadConfig, validatedApiKey, } from "./auth.js";
 import { installTinyFishCli, } from "./cli-install.js";
-import { HARNESS_CAPABILITIES, NATIVE_BY_HARNESS } from "./connect-clients.js";
+import { HARNESS_CAPABILITIES, NATIVE_BY_HARNESS, openclawSkillUninstall, } from "./connect-clients.js";
 import { createStdinPrompt, runCliFallback } from "./connect-fallback.js";
-import { ConnectInterruptedError, ConnectStepError, SignInTimeoutError, finishSetupCommand, } from "./connect-runtime.js";
+import { ConnectInterruptedError, ConnectStepError, SignInTimeoutError, finishSetupCommand, spawnRemoval, } from "./connect-runtime.js";
 import { pickHarnesses } from "./connect-picker.js";
 import { commandOnPath, detectInstalledHarnesses, HARNESS_COMMANDS, HARNESS_DISPLAY_NAMES as DISPLAY_NAMES, ALL_HARNESSES, RELOAD_ACTION, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
@@ -37,16 +37,8 @@ const BROWSER_SIGN_IN = new Set(ALL_HARNESSES.filter((harness) => {
 }));
 // Derived: a native add carries the key, or the CLI holds it itself.
 const KEY_AUTH_CAPABLE = new Set(ALL_HARNESSES.filter((harness) => !!NATIVE_BY_HARNESS.get(harness)?.keyAuth || HARNESS_CAPABILITIES[harness].keyHeldByCli));
-// 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",
-    grok: "grok mcp remove tinyfish",
-    hermes: "hermes mcp remove tinyfish",
-    openclaw: "openclaw skills uninstall @tinyfish/tinyfish --global",
-    // 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",
-};
+// OpenCode ships no `mcp remove`, so the only removal is editing the config it wrote.
+const OPENCODE_UNINSTALL_POINTER = "remove the tinyfish entry from ~/.config/opencode/opencode.json";
 // A new harness fails to compile until wired here.
 const HARNESS_CONNECTORS = {
     "claude-code": connectClaudeCode,
@@ -110,13 +102,97 @@ 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)`;
+    if (!uninstallRuns(harness)) {
+        return `would print \`${uninstallPointer(harness)}\` (no removal command exists)`;
+    }
+    return `would run \`${uninstallPointer(harness)}\``;
+}
+/** Undefined: no harness-CLI removal exists (opencode). */
+function uninstallRuns(harness) {
+    if (harness === "openclaw") {
+        const removal = openclawSkillUninstall();
+        return { command: removal.command, runs: [removal.args], timeoutMs: removal.timeoutMs };
+    }
+    const native = NATIVE_BY_HARNESS.get(harness);
+    if (!native || native.removals.length === 0)
+        return undefined;
+    return { command: native.command, runs: native.removals.map((r) => r.args) };
 }
-function uninstallHarness(harness, configPath) {
+/** Derived from the same args the spawn runs, so the advice cannot drift. */
+function uninstallPointer(harness) {
+    const removal = uninstallRuns(harness);
+    if (!removal)
+        return OPENCODE_UNINSTALL_POINTER;
+    // `;` runs every removal but breaks cmd.exe; `&&` is the reverse — see
+    // internal-docs/install-command-shell-quirks.md (PS 5.1 stays a known gap).
+    const joiner = process.platform === "win32" ? " && " : " ; ";
+    return removal.runs.map((args) => `${removal.command} ${args.join(" ")}`).join(joiner);
+}
+function uninstallHarness(harness, configPath, verbose, binaryOnPath) {
     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] };
+        const removal = uninstallRuns(harness);
+        if (!removal) {
+            return { ...detection, outcome: "uninstall_pointer", fixCommand: uninstallPointer(harness) };
+        }
+        // Stale config: the harness binary is gone, so its removal command cannot run.
+        // openclaw is exempt — its removal runs through npx, not the harness binary.
+        if (harness !== "openclaw" && !binaryOnPath) {
+            return {
+                ...detection,
+                outcome: "uninstall_pointer",
+                errorMessage: `no \`${removal.command}\` binary on PATH — nothing to run.`,
+                fixCommand: `Reinstall ${DISPLAY_NAMES[harness]} first, then: ${uninstallPointer(harness)}`,
+            };
+        }
+        // Absent marker = never connected here, so a non-zero removal exit is a no-op.
+        // Unreadable config cannot prove that, so it keeps the pointer.
+        const connectedBefore = connectContextState(harness) !== "absent";
+        let removed = false;
+        try {
+            for (const args of removal.runs) {
+                const result = spawnRemoval(removal.command, args, removal.timeoutMs);
+                if (result.status !== 0 && verbose) {
+                    const details = result.stderr?.trim() || result.error?.message || `exit ${result.status}`;
+                    errLine(`${removal.command} ${args.join(" ")}: ${details}`);
+                }
+                // Same binary: a spawn-level failure (ENOENT, EPERM) repeats identically.
+                if (result.error) {
+                    return {
+                        ...detection,
+                        outcome: "uninstalled",
+                        errorMessage: `could not run \`${removal.command} ${args.join(" ")}\` (${result.error.message}) — nothing removed.`,
+                        fixCommand: uninstallPointer(harness),
+                    };
+                }
+                // Non-zero is ambiguous (nothing registered vs real failure) — the pointer covers both.
+                if (result.status === 0)
+                    removed = true;
+            }
+        }
+        catch (e) {
+            if (e instanceof ConnectInterruptedError) {
+                return {
+                    ...detection,
+                    outcome: "interrupted",
+                    fixCommand: "tinyfish connect --all --uninstall",
+                };
+            }
+            throw e;
+        }
+        if (removed) {
+            // Kept marker makes doctor emit a registration-lost repair that undoes this.
+            clearConnectContext(harness);
+            return { ...detection, outcome: "uninstalled" };
+        }
+        if (!connectedBefore)
+            return { ...detection, outcome: "uninstall_noop" };
+        return {
+            ...detection,
+            outcome: "uninstall_pointer",
+            errorMessage: "could not confirm removal (command exited non-zero; there may have been nothing to remove).",
+            fixCommand: `Retry by hand: ${uninstallPointer(harness)}`,
+        };
     }
     let result;
     try {
@@ -136,6 +212,7 @@ function uninstallHarness(harness, configPath) {
     if (result.status === "unchanged") {
         return { ...detection, outcome: "uninstall_noop" };
     }
+    clearConnectContext("cursor");
     return { ...detection, outcome: "uninstalled" };
 }
 async function processHarness(detection, opts, prompt, oauthBudget, hoistedCliInstall, deferOutro) {
@@ -154,7 +231,7 @@ async function processHarness(detection, opts, prompt, oauthBudget, hoistedCliIn
         return { ...base, outcome: "dry_run", fixCommand: plan };
     }
     if (opts.uninstall)
-        return uninstallHarness(harness, configPath);
+        return uninstallHarness(harness, configPath, opts.verbose ?? false, detection.binaryOnPath);
     const isTTY = detectHumanInitiated();
     const apiKey = validatedApiKey(opts.apiKey);
     // A key only leaves the own-OAuth set where the harness can actually carry one.
@@ -285,7 +362,10 @@ function summaryLine(result, uninstall) {
             : `… ${name} — needs a browser sign-in. Run in a terminal: ${result.fixCommand}`;
     }
     if (result.outcome === "uninstall_pointer") {
-        return `… ${name} — not removed automatically (config is owned by ${name}). Run: ${result.fixCommand}`;
+        // errorMessage set = a removal was attempted or impossible; absent = no removal command exists.
+        return result.errorMessage
+            ? `… ${name} — ${result.errorMessage} ${result.fixCommand}`
+            : `… ${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`;
@@ -367,6 +447,12 @@ function actionable(result) {
     return result.detected && result.outcome !== "stale_config";
 }
 function computeExitCode(results) {
+    // Flag-independent: uninstall interrupts have no other 130 site.
+    if (results.some((r) => r.outcome === "interrupted"))
+        return 130;
+    // A removal that could not run is a failure, not a silent success.
+    if (results.some((r) => r.outcome === "uninstalled" && r.errorMessage))
+        return 1;
     const detected = results.filter(actionable);
     if (detected.length === 0)
         return 1;

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

@@ -1,7 +1,14 @@
 import spawn from "cross-spawn";
-import type { Harness } from "./harness-detect.js";
+import { type Harness } from "./harness-detect.js";
 import { type AgentClient, type SupportedCommand } from "./connect-runtime.js";
 export declare const OPENCLAW_SKILL_INSTALL_ARGS: readonly string[];
+/** `openclaw skills` has no uninstall; ClawHub removes from the global dir. */
+export declare function openclawSkillUninstall(): {
+    command: string;
+    args: string[];
+    /** npx fetches the package first; the 10s removal bound starves a cold cache. */
+    timeoutMs: number;
+};
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
 /** The `skills` CLI's own agent names — not ours, and not every harness has one. */
@@ -38,7 +45,10 @@ export interface NativeMcpClient extends SupportedCommand {
         label: string;
     }[];
     addArgs: (mcpUrl: string, oauthResource: string) => string[];
+    /** Blocking terminal walkthrough; runs only behind the TTY gate. */
     launchWalkthrough?: () => void;
+    /** Own window, never inherits stdio; reports its own outcome. */
+    detachedLaunch?: () => WalkthroughOutcome;
     /** Printed after a successful connect, on both the launch and non-launch paths. */
     postConnectNote?: string;
 }
@@ -73,5 +83,10 @@ export interface HarnessCapabilities {
 }
 /** Required booleans: a new harness or new flag fails to compile undecided. */
 export declare const HARNESS_CAPABILITIES: Record<Harness, HarnessCapabilities>;
-export declare function launchNativeMcpClient(client: NativeMcpClient): void;
-export declare function launchOpenClawWalkthrough(): void;
+/** "printed" = handed to the user to paste; the walkthrough was never started for them. */
+export type WalkthroughOutcome = "launched" | "printed";
+/** Awaited before the handover; track+flush must land pre-block. */
+type OnWalkthroughDecided = (outcome: WalkthroughOutcome) => void | Promise<void>;
+export declare function launchNativeMcpClient(client: NativeMcpClient, onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
+export declare function launchOpenClawWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
+export {};

package/dist/lib/connect-clients.js

@@ -1,4 +1,7 @@
 import spawn from "cross-spawn";
+import { SKILL_INSTALL_TIMEOUT_MS } from "./cli-install.js";
+import { detectHumanInitiated } from "./harness.js";
+import { harnessConfigPath } from "./harness-detect.js";
 import { errLine, sanitizeLine } from "./output.js";
 import { spawnStepError, } from "./connect-runtime.js";
 import { TINYFISH_API_KEY_VAR } from "./constants.js";
@@ -55,9 +58,30 @@ export const OPENCLAW_SKILL_INSTALL_ARGS = [
     "--force",
     "--acknowledge-clawhub-risk",
 ];
-export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Call the guide_next_step tool now to begin. Then follow its " +
-    "instructions one step at a time. Ask for my input and wait for my reply before each subsequent " +
-    "TinyFish tool call.";
+/** `openclaw skills` has no uninstall; ClawHub removes from the global dir. */
+export function openclawSkillUninstall() {
+    return {
+        command: "npx",
+        args: [
+            "-y",
+            // Pinned: npx would otherwise execute whatever is newest at run time.
+            "clawhub@0.23.3",
+            "--workdir",
+            harnessConfigPath("openclaw"),
+            "uninstall",
+            OPENCLAW_SKILL,
+            "--yes",
+        ],
+        timeoutMs: SKILL_INSTALL_TIMEOUT_MS,
+    };
+}
+export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Use the MCP server named `tinyfish` for every TinyFish tool call; " +
+    "if another TinyFish server is also registered, still use `tinyfish` and do not ask me which. " +
+    "Start by asking me what I want to look up on the web, and wait for my reply. Then call " +
+    "`guide_next_step` and follow its instructions one step at a time, asking for my input and " +
+    "waiting for my reply before each subsequent TinyFish tool call. If a tool call comes back " +
+    "blocked or not approved, tell me which tool needs approval and how to grant it, then wait for " +
+    "me instead of ending the walkthrough.";
 export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill. Guide me through it interactively: first ask what topic I " +
     "want to search and wait for my reply before using TinyFish Search. Show me the results, ask " +
     "which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task " +
@@ -133,9 +157,12 @@ function launchCodexWalkthrough() {
     deepLink.searchParams.set("path", process.cwd());
     const result = openExternalUrl(deepLink.toString());
     if (result.error || result.status !== 0) {
-        throw spawnStepError("Could not open Codex", result);
+        // Headless box: nothing can open a window; recover like the gated clients.
+        printPromptForHandoff("Codex", "codex", DEFAULT_ONBOARDING_PROMPT, "Codex could not be opened here (no `codex://` handler)");
+        return "printed";
     }
     errLine("Codex opened with the TinyFish walkthrough ready. Send the prompt to start.");
+    return "launched";
 }
 export const CODEX = {
     command: "codex",
@@ -154,7 +181,7 @@ export const CODEX = {
         envVar: TINYFISH_API_KEY_VAR,
         addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), "--bearer-token-env-var", TINYFISH_API_KEY_VAR],
     },
-    launchWalkthrough: launchCodexWalkthrough,
+    detachedLaunch: launchCodexWalkthrough,
     // Retry only: running it after a finished inline OAuth is a second browser hop.
     loginArgs: ["mcp", "login", "tinyfish"],
     removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
@@ -253,7 +280,7 @@ export const OPENCODE = {
     keyAuth: headerKeyAuth,
     // `opencode mcp add` upserts by name and there is no `opencode mcp remove`, so no cleanup step.
     removals: [],
-    // OpenCode writes ~/.config/opencode/opencode.jsonc itself; `mcp auth` is the separate OAuth step.
+    // OpenCode writes ~/.config/opencode/opencode.json itself; `mcp auth` is the separate OAuth step.
     addArgs: (mcpUrl) => urlAddArgs(mcpUrl),
     loginArgs: ["mcp", "auth", "tinyfish"],
     launchWalkthrough: launchOpencode,
@@ -331,15 +358,40 @@ export const HARNESS_CAPABILITIES = {
         authDeferredAtInstall: false,
     },
 };
-export function launchNativeMcpClient(client) {
-    errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
-    if (client.launchWalkthrough) {
-        client.launchWalkthrough();
-        return;
+function printPromptForHandoff(displayName, command, prompt, reason) {
+    // "set up", not "connected": sign-in can still be deferred here.
+    errLine(`TinyFish is set up in ${displayName}.`);
+    errLine(`${reason}, so TinyFish did not launch it. Start ${displayName} (\`${command}\`) yourself ` +
+        `and paste this first message:`);
+    errLine("");
+    errLine(prompt);
+}
+/** One gate + one decide-before-block path for every terminal handover. */
+async function deliverWalkthrough(displayName, command, prompt, handover, onDecided) {
+    // Inherited-stdio handover: a non-TTY parent cannot approve tool calls.
+    if (!detectHumanInitiated()) {
+        await onDecided?.("printed");
+        printPromptForHandoff(displayName, command, prompt, `This terminal cannot answer ${displayName}'s tool-approval prompts`);
+        return "printed";
+    }
+    // Decided and delivered first: the handover blocks for the whole session.
+    await onDecided?.("launched");
+    errLine(`Starting the TinyFish walkthrough in ${displayName}...`);
+    handover();
+    return "launched";
+}
+export async function launchNativeMcpClient(client, onDecided) {
+    if (client.detachedLaunch) {
+        // Detached: the open attempt never blocks, so decide after it.
+        errLine(`Starting the TinyFish walkthrough in ${client.displayName}...`);
+        const outcome = client.detachedLaunch();
+        await onDecided?.(outcome);
+        return outcome;
     }
-    handOverTerminal(client.command, [DEFAULT_ONBOARDING_PROMPT], client.displayName);
+    return deliverWalkthrough(client.displayName, client.command, DEFAULT_ONBOARDING_PROMPT, () => client.launchWalkthrough
+        ? client.launchWalkthrough()
+        : handOverTerminal(client.command, [DEFAULT_ONBOARDING_PROMPT], client.displayName), onDecided);
 }
-export function launchOpenClawWalkthrough() {
-    errLine("Starting the TinyFish walkthrough in OpenClaw...");
-    handOverTerminal("openclaw", ["chat", "--message", OPENCLAW_ONBOARDING_PROMPT], "OpenClaw");
+export function launchOpenClawWalkthrough(onDecided) {
+    return deliverWalkthrough("OpenClaw", "openclaw", OPENCLAW_ONBOARDING_PROMPT, () => handOverTerminal("openclaw", ["chat", "--message", OPENCLAW_ONBOARDING_PROMPT], "OpenClaw"), onDecided);
 }

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

@@ -6,7 +6,7 @@ export type ConnectFailureStage = "prerequisite_check" | "registration_cleanup"
 export declare const CONNECT_FAILURE_REASONS: readonly ["harness_not_installed", "harness_command_unsupported", "harness_too_old", "key_auth_unsupported", "command_not_found", "timeout", "spawn_error", "nonzero_exit", "invalid_config", "user_abandoned", "process_terminated", "unexpected_error"];
 export type ConnectFailureReason = (typeof CONNECT_FAILURE_REASONS)[number];
 export type ConnectAuthMode = Exclude<AuthMode, AuthMode.Unknown> | "deferred";
-export type ConnectCheckpoint = "prerequisite_ok" | "registered" | "oauth_done" | "cli_installed" | "skill_installed" | "authenticated" | "cli_verified";
+export type ConnectCheckpoint = "prerequisite_ok" | "registered" | "oauth_done" | "cli_installed" | "skill_installed" | "authenticated" | "cli_verified" | "walkthrough_launched" | "walkthrough_prompt_printed";
 export type CliFallbackOutcome = "cli_verified" | "cli_install_failed" | "no_credentials" | "invalid_credentials" | "authentication_failed" | "verification_failed" | "abandoned";
 /** Ctrl+C killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {
@@ -33,6 +33,8 @@ export interface SpawnStepResult {
     signal?: string | null;
     error?: Error;
 }
+/** Bounded removal spawn shared by install cleanup and --uninstall; Ctrl+C throws. */
+export declare function spawnRemoval(command: string, args: readonly string[], timeoutMs?: number): import("child_process").SpawnSyncReturns<string>;
 /** Classifies a spawn failure; interrupts throw instead. */
 export declare function spawnStepError(message: string, result: SpawnStepResult): ConnectStepError;
 export declare function commandNotFound(error: unknown): boolean;

package/dist/lib/connect-runtime.js

@@ -55,6 +55,15 @@ export function throwIfInterrupted(result) {
         throw new ConnectInterruptedError("Setup interrupted");
     }
 }
+/** Bounded removal spawn shared by install cleanup and --uninstall; Ctrl+C throws. */
+export function spawnRemoval(command, args, timeoutMs = NON_INTERACTIVE_TIMEOUT_MS) {
+    const result = spawn.sync(command, [...args], {
+        encoding: "utf8",
+        timeout: timeoutMs,
+    });
+    throwIfInterrupted(result);
+    return result;
+}
 /** Classifies a spawn failure; interrupts throw instead. */
 export function spawnStepError(message, result) {
     throwIfInterrupted(result);

package/package.json

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