@tiny-fish/cli 0.52.4-next.432 → 0.52.4

package/dist/lib/config/mcp-json-config.d.ts

@@ -12,6 +12,10 @@ export interface McpJsonTarget {
     transportKey?: string;
     /** Read-side only; OpenCode and its Kilo fork nest servers under `mcp`. */
     serversKey?: string;
+    /** Read-side only; OpenCode 2.x nests once more, under `mcp.servers`. */
+    nestedServersKey?: string;
+    /** Read-side only; the harness writes JSONC, so comments and trailing commas parse. */
+    jsonc?: true;
 }
 export interface McpJsonWriteResult {
     status: 'written' | 'unchanged' | 'corrupt_skip';
@@ -22,6 +26,8 @@ export interface McpJsonWriteResult {
 }
 export declare function buildTinyfishServerEntry(mcpUrl: string, apiKey?: string): Record<string, unknown>;
 export declare function buildTinyfishKeylessServerEntry(mcpUrl: string): Record<string, unknown>;
+/** Comments and trailing commas only; strings pass through untouched. */
+export declare function stripJsonComments(text: string): string;
 /** Dry-run description of the pending write; touches nothing. */
 export declare function planWrite(target: McpJsonTarget, mcpUrl: string, apiKey?: string, serverEntry?: Record<string, unknown>): string;
 export interface McpJsonServerEntry {

package/dist/lib/config/mcp-json-config.js

@@ -11,9 +11,51 @@ export function buildTinyfishServerEntry(mcpUrl, apiKey) {
 export function buildTinyfishKeylessServerEntry(mcpUrl) {
     return { url: mcpUrl, headers: { [TINYFISH_ACCESS_MODE_HEADER]: TINYFISH_KEYLESS_ACCESS_MODE } };
 }
-function parseMcpJson(raw) {
+const TRAILING_COMMA = /\s*[}\]]/y;
+/** Comments and trailing commas only; strings pass through untouched. */
+export function stripJsonComments(text) {
+    // Twice: a comment can sit between a trailing comma and its bracket.
+    return strip(strip(text));
+}
+function strip(text) {
+    let out = '';
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '"') {
+            const end = closingQuote(text, i);
+            out += text.slice(i, end + 1);
+            i = end;
+        }
+        else if (ch === '/' && text[i + 1] === '/') {
+            const end = text.indexOf('\n', i);
+            if (end === -1)
+                break;
+            i = end - 1;
+        }
+        else if (ch === '/' && text[i + 1] === '*') {
+            const end = text.indexOf('*/', i + 2);
+            i = end === -1 ? text.length : end + 1;
+        }
+        else {
+            TRAILING_COMMA.lastIndex = i + 1;
+            if (ch !== ',' || !TRAILING_COMMA.test(text))
+                out += ch;
+        }
+    }
+    return out;
+}
+function closingQuote(text, start) {
+    for (let i = start + 1; i < text.length; i++) {
+        if (text[i] === '\\')
+            i++;
+        else if (text[i] === '"')
+            return i;
+    }
+    return text.length - 1;
+}
+function parseMcpJson(raw, jsonc) {
     try {
-        const parsed = JSON.parse(raw);
+        const parsed = JSON.parse(jsonc ? stripJsonComments(raw) : raw);
         if (!isPlainRecord(parsed))
             return { ok: false, error: 'mcp.json root is not a JSON object' };
         if ('mcpServers' in parsed && !isPlainRecord(parsed.mcpServers)) {
@@ -36,7 +78,7 @@ function readExisting(target) {
             return { parsed: {} };
         return { error: e instanceof Error ? e.message : String(e) };
     }
-    const parsed = parseMcpJson(raw);
+    const parsed = parseMcpJson(raw, target.jsonc);
     if (!parsed.ok)
         return { error: parsed.error };
     return { raw, parsed: parsed.value };
@@ -76,9 +118,8 @@ export function readTinyfishEntry(target) {
     if ('error' in existing) {
         return { present: false, hasApiKeyHeader: false, error: existing.error };
     }
-    const servers = existing.parsed[target.serversKey ?? 'mcpServers'];
-    const entry = isPlainRecord(servers) ? servers[target.serverKey] : undefined;
-    if (!isPlainRecord(entry))
+    const entry = findEntry(existing.parsed, target);
+    if (!entry)
         return { present: false, hasApiKeyHeader: false };
     const fields = entryFields(entry, target.transportKey);
     const key = readKeyHeader(fields.headers, target.keyHeader);
@@ -95,6 +136,19 @@ export function readTinyfishEntry(target) {
         ...(typeof fields.url === 'string' ? { url: fields.url } : {}),
     };
 }
+/** 2.x `mcp.servers.<name>` wins over the flat 1.x `mcp.<name>`. */
+function nestedServers(root, target) {
+    if (!target.nestedServersKey || !isPlainRecord(root))
+        return undefined;
+    const nested = root[target.nestedServersKey];
+    return isPlainRecord(nested) && target.serverKey in nested ? nested : undefined;
+}
+function findEntry(parsed, target) {
+    const root = parsed[target.serversKey ?? 'mcpServers'];
+    const servers = nestedServers(root, target) ?? root;
+    const entry = isPlainRecord(servers) ? servers[target.serverKey] : undefined;
+    return isPlainRecord(entry) ? entry : undefined;
+}
 /** Reports the key header's shape, never its value. */
 function readKeyHeader(headers, keyHeader) {
     const { name = 'x-api-key', valuePrefix = '' } = keyHeader ?? {};

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

@@ -3,7 +3,14 @@ import { type McpJsonServerEntry } from './mcp-json-config.js';
 export type OpencodeStyleHarness = 'kilo' | 'opencode';
 /** Narrows before any path is built, so a future removal-less harness cannot borrow these. */
 export declare function isOpencodeStyle(harness: Harness): harness is OpencodeStyleHarness;
-/** The file on disk, else the `.jsonc` default so messages still name something. */
-export declare function opencodeStyleConfigPath(harness: OpencodeStyleHarness): string;
-/** Reports the header's shape, never its value. JSONC comments read as unparseable. */
+/** The add target: the file on disk, else the `.json` default so messages still name something. */
+export declare function opencodeStyleConfigPath(harness: OpencodeStyleHarness, dir?: string): string;
+/** Reports the header's shape, never its value; the effective (last) definition, not the first. */
 export declare function readOpencodeStyleEntry(harness: OpencodeStyleHarness): McpJsonServerEntry;
+/** Project configs an older 2.x connect left the key in (PF-6613). */
+export declare function strayProjectKeyFiles(cwd?: string): string[];
+/**
+ * 2.1.4 walks to `/`, past the git root (1.x and Kilo stop there). Walking too far only
+ * withholds key credit; stopping early would grant it while a project key is live.
+ */
+export declare function projectDefinesTinyfish(harness: OpencodeStyleHarness, cwd?: string): boolean;

package/dist/lib/config/opencode-config.js

@@ -8,27 +8,68 @@ import { readTinyfishEntry, } from './mcp-json-config.js';
 export function isOpencodeStyle(harness) {
     return harness === 'kilo' || harness === 'opencode';
 }
-/** Both extensions are valid; `mcp add` keeps whichever already exists. */
-const EXTENSIONS = ['.jsonc', '.json'];
-function candidatePaths(harness) {
-    const dir = harnessConfigPath(harness);
-    const stem = harnessSpec(harness).command;
-    return EXTENSIONS.map((ext) => path.join(dir, `${stem}${ext}`)); // nosemgrep: path-join-resolve-traversal -- fixed names from the harness spec
-}
-/** The file on disk, else the `.jsonc` default so messages still name something. */
-export function opencodeStyleConfigPath(harness) {
-    const candidates = candidatePaths(harness);
+/** OpenCode 2.1 `mcp add` order; first existing wins, else the first. */
+function candidatePaths(dir, stem) {
+    return [
+        path.join(dir, `${stem}.json`), // nosemgrep: path-join-resolve-traversal -- fixed names from the harness spec
+        path.join(dir, `${stem}.jsonc`), // nosemgrep: path-join-resolve-traversal -- fixed names from the harness spec
+        path.join(dir, `.${stem}`, `${stem}.json`), // nosemgrep: path-join-resolve-traversal -- fixed names from the harness spec
+        path.join(dir, `.${stem}`, `${stem}.jsonc`), // nosemgrep: path-join-resolve-traversal -- fixed names from the harness spec
+    ];
+}
+/** The add target: the file on disk, else the `.json` default so messages still name something. */
+export function opencodeStyleConfigPath(harness, dir) {
+    const candidates = candidatePaths(dir ?? harnessConfigPath(harness), harnessSpec(harness).command);
     return candidates.find((file) => fs.existsSync(file)) ?? candidates[0];
 }
-function target(harness) {
+function target(harness, file) {
     return {
         serverKey: 'tinyfish',
         serversKey: 'mcp',
-        dir: () => harnessConfigPath(harness),
-        file: () => opencodeStyleConfigPath(harness),
+        nestedServersKey: 'servers',
+        jsonc: true,
+        dir: () => path.dirname(file),
+        file: () => file,
     };
 }
-/** Reports the header's shape, never its value. JSONC comments read as unparseable. */
+/** OpenCode loads `.json` then `.jsonc` from one dir and the later definition of a server wins. */
+function loadedEntries(harness, dir, projectWalk = false) {
+    const candidates = candidatePaths(dir, harnessSpec(harness).command);
+    // The `.opencode/` pair is read only on the project walk, never from the global dir.
+    return (projectWalk ? candidates : candidates.slice(0, 2))
+        .filter((file) => fs.existsSync(file))
+        .map((file) => ({ file, entry: readTinyfishEntry(target(harness, file)) }));
+}
+/** Reports the header's shape, never its value; the effective (last) definition, not the first. */
 export function readOpencodeStyleEntry(harness) {
-    return readTinyfishEntry(target(harness));
+    const entries = loadedEntries(harness, harnessConfigPath(harness)).map(({ entry }) => entry);
+    const effective = entries.filter((entry) => entry.present).at(-1);
+    return (effective ?? entries.find((entry) => entry.error) ?? { present: false, hasApiKeyHeader: false });
+}
+/** Project configs an older 2.x connect left the key in (PF-6613). */
+export function strayProjectKeyFiles(cwd = process.cwd()) {
+    return loadedEntries('opencode', cwd, true)
+        .filter(({ entry }) => entry.present && entry.hasApiKeyHeader)
+        .map(({ file }) => file);
+}
+const truthy = (value) => value === '1' || value?.toLowerCase() === 'true';
+// OpenCode 2.x reads the newer name first; `??` mirrors its `server-process.ts`.
+const PROJECT_CONFIG_DISABLED = {
+    opencode: () => truthy(process.env['OPENCODE_CONFIG_PROJECT_DISABLE'] ??
+        process.env['OPENCODE_DISABLE_PROJECT_CONFIG']),
+    kilo: () => truthy(process.env['KILO_DISABLE_PROJECT_CONFIG']),
+};
+/**
+ * 2.1.4 walks to `/`, past the git root (1.x and Kilo stop there). Walking too far only
+ * withholds key credit; stopping early would grant it while a project key is live.
+ */
+export function projectDefinesTinyfish(harness, cwd = process.cwd()) {
+    if (PROJECT_CONFIG_DISABLED[harness]())
+        return false;
+    for (let dir = cwd;; dir = path.dirname(dir)) {
+        if (loadedEntries(harness, dir, true).some(({ entry }) => entry.present))
+            return true;
+        if (path.dirname(dir) === dir)
+            return false;
+    }
 }

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

@@ -39,7 +39,7 @@ interface SeededInstall {
         tag?: string;
     };
 }
-interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent' | 'nonInteractiveAdd' | 'signInHint' | 'degradedAuthNotes' | 'postConnectNote'> {
+interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent' | 'nonInteractiveAdd' | 'signInHint' | 'degradedAuthNotes' | 'postConnectNote' | 'verifyListed'> {
     connectClient: Exclude<AgentClient, 'openclaw'>;
     /** Replaces `addArgs` when a stored key is available: key auth removes the OAuth hop. */
     keyAuth?: {
@@ -56,8 +56,8 @@ interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent'
         args: string[];
         label: string;
     }[];
-    /** Blocking terminal walkthrough; runs only behind the TTY gate. */
-    launchWalkthrough?: (prompt: string) => void;
+    /** Blocking terminal walkthrough; runs only behind the TTY gate. Spawns `command` (pinned). */
+    launchWalkthrough?: (prompt: string, command: string) => void;
     /** Own window, never inherits stdio; reports its own outcome. */
     detachedLaunch?: (prompt: string) => WalkthroughOutcome;
     /** Post-install like the skill step: failures warn, never fail the attempt. */

package/dist/lib/connect-clients.js

@@ -212,7 +212,7 @@ function installHermesWebPlugin({ apiKey, verbose, seededHome, }) {
 // These TUIs read a positional as a project directory, so a bare `<cmd> "<prompt>"` would be
 // read as a folder. `--prompt` seeds the interactive TUI with a first message
 // (opencode.ai/docs/cli), so the onboarding guide fires just like the other agents.
-const launchWithPromptFlag = (command, displayName) => (prompt) => {
+const launchWithPromptFlag = (displayName) => (prompt, command) => {
     handOverTerminal(command, ['--prompt', prompt], displayName);
 };
 // A bare `cline "<prompt>"` is a one-shot act run that auto-approves every tool, so it would
@@ -273,8 +273,8 @@ const HARNESS_OVERRIDES = {
         seedKey: seedHermesKey,
         prepareKeylessInstall: prepareHermesKeylessInstall,
     },
-    kilo: { launchWalkthrough: launchWithPromptFlag('kilo', 'Kilo Code') },
-    opencode: { launchWalkthrough: launchWithPromptFlag('opencode', 'OpenCode') },
+    kilo: { launchWalkthrough: launchWithPromptFlag('Kilo Code') },
+    opencode: { launchWalkthrough: launchWithPromptFlag('OpenCode') },
 };
 function toNativeClient(harness) {
     const spec = harnessSpec(harness);
@@ -306,6 +306,7 @@ function toNativeClient(harness) {
         postConnectNote: spec.postConnectNote,
         extraPostInstall: overrides.extraPostInstall,
         uninstallExtra: spec.uninstallExtra,
+        verifyListed: spec.verifyListed,
     };
     if (spec.keyRequired) {
         if (!keyAuth)
@@ -357,7 +358,7 @@ export async function launchNativeMcpClient(client, onDecided, prompt = DEFAULT_
         return outcome;
     }
     return deliverWalkthrough(client.displayName, client.command, prompt, () => client.launchWalkthrough
-        ? client.launchWalkthrough(prompt)
+        ? client.launchWalkthrough(prompt, client.command)
         : handOverTerminal(client.command, [prompt], client.displayName), onDecided);
 }
 // Via deliverWalkthrough: handOverTerminal alone would wedge a headless --launch.

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

@@ -1,4 +1,4 @@
 import { type NativeMcpClient } from './connect-clients.js';
 import { type ConnectAuthMode } from './connect-runtime.js';
 import { type NativeConnectOptions } from './connect-steps.js';
-export declare function connectNativeMcpClient(client: NativeMcpClient, options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
+export declare function connectNativeMcpClient(unpinned: NativeMcpClient, options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;

package/dist/lib/connect-native.js

@@ -5,14 +5,72 @@ import { captureStdio, capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MA
 import { ensureCliAuthenticated } from './connect-auth.js';
 import { installWebSkill } from './skill-install.js';
 import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, runGuarded, settle, SignInTimeoutError, spawnRemoval, spawnStepError, } from './connect-runtime.js';
-import { TINYFISH_API_KEY_VAR } from './constants.js';
-import { AuthMode, RELOAD_ACTION } from './harness/harness-detect.js';
-import { SIGN_IN_PROBES } from './registration-detect.js';
-import { errLine, warnLine } from './output.js';
+import { DASHBOARD_URL, TINYFISH_API_KEY_VAR } from './constants.js';
+import { strayProjectKeyFiles } from './config/opencode-config.js';
+import { AuthMode, HARNESS_COMMANDS, RELOAD_ACTION, resolveCommand, } from './harness/harness-detect.js';
+import { opencodeStrayKeyNote } from './harness/harness-messages.js';
+import { SIGN_IN_PROBES, TINYFISH_LIST_ROW } from './registration-detect.js';
+import { errLine, sanitizeLine, warnLine } from './output.js';
 import { verifyMcpAuth } from './verify.js';
 import { dotenvMarkerHead, harnessDotenvPath, writeDotenvKey } from './dotenv-file.js';
 import { apiBaseFromMcpUrl } from './mcp-endpoint.js';
 import { finishSetupHint, requireKeylessMcp, requireSupportOrRescue, runCliInstallStep, trackPostInstallFailure, walkthroughPhase, } from './connect-steps.js';
+/** Several installs can disagree; every later spawn reuses this one. */
+function pinExecutable(client) {
+    const resolved = resolveCommand(client.command);
+    return resolved ? { ...client, command: resolved } : client;
+}
+// A fresh background service answers empty, then `pending`, then settles within seconds.
+const LIST_SETTLE_TIMEOUT_MS = 20_000;
+const LIST_POLL_MS = 1_000;
+function listRowStatus(result) {
+    const output = sanitizeLine(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
+    return TINYFISH_LIST_ROW.exec(output)?.[1]?.trim();
+}
+/** Last settled status, or undefined when the row never appeared before the deadline. */
+async function pollListStatus(client, options) {
+    const deadline = Date.now() + (options.verifyTimeoutMs ?? LIST_SETTLE_TIMEOUT_MS);
+    for (;;) {
+        // One hung `mcp list` must not outlive the verification deadline.
+        const remaining = Math.max(deadline - Date.now(), LIST_POLL_MS);
+        const result = spawn.sync(client.command, ['mcp', 'list'], {
+            encoding: 'utf8',
+            timeout: Math.min(remaining, client.supportCheck.timeoutMs ?? SKILL_INSTALL_TIMEOUT_MS),
+            env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' },
+        });
+        const expired = Date.now() >= deadline;
+        // A spawn error is permanent; a non-zero exit can be the service still starting.
+        if (result.error || (result.status !== 0 && expired)) {
+            throw spawnStepError(`Could not list ${client.displayName}'s MCP servers`, result);
+        }
+        const status = result.status === 0 ? listRowStatus(result) : undefined;
+        if ((status && status !== 'pending') || expired)
+            return status;
+        await new Promise((resolve) => setTimeout(resolve, LIST_POLL_MS));
+    }
+}
+/** The TUI reads the background service, not the file; a stale service misreports both ways. */
+async function requireListedAndConnected(client, options, authMode) {
+    const status = await pollListStatus(client, options);
+    if (status === 'connected')
+        return;
+    const command = HARNESS_COMMANDS[client.connectClient];
+    const restart = `\`${command} service restart\`, then re-run: tinyfish connect ${client.connectClient}`;
+    const fail = (tag, message) => {
+        throw new ConnectStepError(`${client.displayName} ${message}`, 'invalid_config', {
+            failureDetail: tag,
+        });
+    };
+    if (!status || status === 'pending') {
+        fail('mcp_list_missing', `does not list TinyFish after the add. Check OPENCODE_CONFIG_DIR, run ${restart}`);
+    }
+    if (status === 'needs authentication') {
+        const signIn = authMode === AuthMode.OAuth ? `${command} mcp auth tinyfish` : 'tinyfish auth login';
+        fail('mcp_list_needs_auth', `reports TinyFish needs authentication. Run ${signIn} and ${restart}`);
+    }
+    // The status text can quote URLs and paths, so only the tag reaches telemetry.
+    fail('mcp_list_unhealthy', `reports TinyFish as "${status}". Fix that, run ${restart}`);
+}
 function removeExistingRegistration(client, removal, verbose) {
     const result = spawnRemoval(client.command, removal.args);
     if (result.status === 0)
@@ -287,7 +345,8 @@ function completeAuthFlow(client, options, state, telemetry, ctx) {
             : AuthMode.OAuth;
     return { authMode, signInDeferred };
 }
-export async function connectNativeMcpClient(client, options) {
+export async function connectNativeMcpClient(unpinned, options) {
+    const client = pinExecutable(unpinned);
     const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
     const state = { stage: 'prerequisite_check', settled: false };
     const probeAuthenticated = SIGN_IN_PROBES[client.connectClient];
@@ -316,6 +375,11 @@ export async function connectNativeMcpClient(client, options) {
             loginArgs && !probeAuthenticated ? 'registration' : 'registration_or_authentication';
         const { note: seededNote, seededHome } = performMcpAdd(client, options, plan, telemetry.attemptId);
         telemetry.track('checkpoint', { phase: 'registered' });
+        // Only 2.x lists a variant, and only 2.x wrote the project file (PF-6613).
+        const twoPointX = client.verifyListed && matchedVariant !== undefined;
+        for (const stray of twoPointX ? strayProjectKeyFiles() : []) {
+            warnLine(opencodeStrayKeyNote(stray, DASHBOARD_URL));
+        }
         const { authMode, signInDeferred } = completeAuthFlow(client, options, state, telemetry, {
             useKeyAuth,
             useKeyless,
@@ -324,6 +388,11 @@ export async function connectNativeMcpClient(client, options) {
             probeAuthenticated,
             seededNote,
         });
+        // A deferred sign-in legitimately lists as `needs authentication`.
+        if (twoPointX && !signInDeferred) {
+            state.stage = 'registration_or_authentication';
+            await requireListedAndConnected(client, options, authMode);
+        }
         state.authMode = authMode;
         // Registration/OAuth make MCP work; the steps below must not fail the attempt.
         settle(state, telemetry, 'completed', { authMode });

package/dist/lib/connect-runtime.js

@@ -217,8 +217,10 @@ function throwProbeFailure(client, result) {
     throw new ConnectStepError(unavailableMessage(client, harnessVersion), 'harness_command_unsupported', {
         cause: result.error,
         harnessVersion,
-        // A spawn error leaves stderr empty; its message is the diagnosis.
-        failureDetail: result.error?.message ?? spawnFailureDetail(result),
+        // A spawn error leaves stderr empty; its code is the diagnosis (the message quotes paths).
+        failureDetail: result.error
+            ? (result.error.code ?? 'spawn_error')
+            : spawnFailureDetail(result),
     });
 }
 function supportProbeOutput(client) {

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

@@ -22,6 +22,8 @@ export interface NativeConnectOptions {
     deferOutro?: (line: string) => void;
     /** Targeted connects only: --all keeps its per-harness failed row. */
     fallbackWhenMissing?: boolean;
+    /** Test seam: how long a 2.x `mcp list` may stay empty or `pending` after the add. */
+    verifyTimeoutMs?: number;
 }
 export declare function requireKeylessMcp(mcpUrl: string): Promise<void>;
 /** Undefined means the rescue ran; the caller returns immediately. */

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

@@ -14,6 +14,7 @@ export declare enum AuthMode {
     Unknown = "unknown"
 }
 export declare const HARNESS_COMMANDS: Record<Harness, string>;
+export declare function resolveCommand(command: string): string | undefined;
 export declare function commandOnPath(command: string): boolean;
 export declare function harnessConfigPath(harness: Harness): string;
 /** For reason strings that name a location; keeps them in sync with the spec. */

package/dist/lib/harness/harness-detect.js

@@ -27,18 +27,22 @@ export var AuthMode;
 // TODO(PF-3668): a same-named non-harness binary still reads as installed.
 export const HARNESS_COMMANDS = Object.fromEntries(ALL_HARNESSES.map((harness) => [harness, harnessSpec(harness).command]));
 // cross-spawn resolves the same way, so detection cannot disagree with the spawn.
-export function commandOnPath(command) {
+export function resolveCommand(command) {
     try {
-        return which.sync(command, { nothrow: true }) !== null;
+        return which.sync(command, { nothrow: true }) ?? undefined;
     }
     catch {
-        return false;
+        return undefined;
     }
 }
+export function commandOnPath(command) {
+    return resolveCommand(command) !== undefined;
+}
 // Env vars move these dirs; a guessed path would go unread.
 const CONFIG_PATH_RESOLVERS = {
     cline: clineConfigDir,
     codex: () => agentHome('CODEX_HOME', harnessSpec('codex').configDir),
+    opencode: () => process.env['OPENCODE_CONFIG_DIR'] || undefined,
     pi: piAgentDir,
 };
 export function harnessConfigPath(harness) {

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

@@ -10,6 +10,7 @@ export declare const GROK_SIGN_IN_HINT: string;
 export declare const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE: string;
 export declare const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE: string;
 export declare const OPENCODE_MODEL_NOTE: string;
+export declare const opencodeStrayKeyNote: (file: string, apiKeysUrl: string) => string;
 export declare const KILO_MCP_ADD_UNAVAILABLE_MESSAGE: string;
 export declare const HERMES_RESTART_NOTE = "Restart your Hermes session to pick up TinyFish \u2014 Hermes discovers MCP servers at startup.";
 export declare const CLINE_MCP_ADD_UNAVAILABLE_MESSAGE: string;

package/dist/lib/harness/harness-messages.js

@@ -37,6 +37,9 @@ export const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = 'Could not confirm this Open
 export const OPENCODE_MODEL_NOTE = 'Note: TinyFish runs on tool calls, so OpenCode needs a model that supports tool use. Image-only ' +
     'models (e.g. Nano Banana Pro) will show "No endpoints found that support tool use" — switch ' +
     "OpenCode's model if the walkthrough can't start.";
+// PF-6613 decision: notice and rotation prompt, never delete.
+export const opencodeStrayKeyNote = (file, apiKeysUrl) => `An earlier TinyFish connect saved your API key in ${file} (OpenCode 2.x project config). ` +
+    `Remove its tinyfish entry; if that file was shared or committed, rotate the key at ${apiKeysUrl}`;
 export const KILO_MCP_ADD_UNAVAILABLE_MESSAGE = 'Could not confirm this Kilo Code installation supports remote MCP servers: `kilo mcp add ' +
     '--help` did not list `--url`. Update Kilo Code with `kilo upgrade` and retry, or add ' +
     'TinyFish manually with `kilo mcp add`.';

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

@@ -87,6 +87,8 @@ export interface HarnessSpec {
     readableWithoutBinary?: true;
     /** `mcp add` succeeds unauthenticated; OAuth lands at first tool use. */
     authDeferredAtInstall?: true;
+    /** 2.x adds only: poll `mcp list` until the background service settles the tinyfish row. */
+    verifyListed?: true;
 }
 /** One entry per harness; every per-harness list derives from it. */
 export declare const HARNESS_SPECS: {
@@ -310,6 +312,7 @@ export declare const HARNESS_SPECS: {
         loginArgs: string[];
         removals: never[];
         postConnectNote: string;
+        verifyListed: true;
     };
     pi: {
         command: string;

package/dist/lib/harness/harness-spec.js

@@ -240,6 +240,7 @@ export const HARNESS_SPECS = {
         // `opencode mcp add` upserts by name and ships no `mcp remove`.
         removals: [],
         postConnectNote: OPENCODE_MODEL_NOTE,
+        verifyListed: true,
     },
     pi: {
         command: 'pi',

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

@@ -20,6 +20,8 @@ export interface RegistrationStatus {
     recordedAuthMode?: RecordedAuthMode;
     reason?: string;
 }
+/** Our row in any `mcp list`; group 1 is whatever status text follows the name. */
+export declare const TINYFISH_LIST_ROW: RegExp;
 /** Per-harness sign-in probes; connect composes these rather than the descriptor carrying them. */
 export declare const SIGN_IN_PROBES: Partial<Record<AgentClient, () => boolean | undefined>>;
 /** Never throws; a failed probe is `unknown` with a reason, so no caller can read it as healthy. */

package/dist/lib/registration-detect.js

@@ -10,7 +10,7 @@ import { readClineTinyfishEntry } from './config/cline-config.js';
 import { readCommandCodeTinyfishEntry } from './config/command-code-config.js';
 import { readCursorTinyfishEntry } from './config/cursor-config.js';
 import { readOmpTinyfishEntry } from './config/omp-config.js';
-import { readOpencodeStyleEntry } from './config/opencode-config.js';
+import { projectDefinesTinyfish, readOpencodeStyleEntry, } from './config/opencode-config.js';
 import { readPiTinyfishEntry } from './config/pi-config.js';
 import { harnessSpec } from './harness/harness-spec.js';
 import { readHermesKey, resolveHermesHome } from './hermes-env.js';
@@ -108,7 +108,8 @@ const MCP_LIST_TINYFISH_LINE = /^((?:\S*:)?tinyfish):\s+(https?:\S+)(.*)$/m;
 const SERVER_NAMED_TINYFISH = /^(?:\S*:)?tinyfish$/;
 // A bare substring also matches `not-tinyfish` and any row quoting a tinyfish URL, so the name
 // is required to be the first word on its line, after whatever status glyph the CLI prints.
-const LISTED_AS_TINYFISH = /^[^\w]*tinyfish(?![\w-])/m;
+/** Our row in any `mcp list`; group 1 is whatever status text follows the name. */
+export const TINYFISH_LIST_ROW = /^[^\w]*tinyfish(?![\w-])\s*(.*)$/m;
 // Claude Code reports its own live handshake; a config file cannot.
 const MCP_GET_STATUS = /^\s*Status:\s*(.+)$/m;
 // `mcp get <missing>` names every configured server, with no health check.
@@ -403,7 +404,7 @@ const MCP_LIST_HEADER = /mcp servers/i;
 // OpenCode and its Kilo fork print the endpoint under the row; Hermes truncates its column.
 const MCP_LIST_ROW_URL = /^[^\w]*tinyfish(?![\w-]).*\n[^\w]*(https?:\S+)/m;
 function fromMcpList(command, output, registeredMode, urlPattern) {
-    if (LISTED_AS_TINYFISH.test(output)) {
+    if (TINYFISH_LIST_ROW.test(output)) {
         const url = urlPattern?.exec(output)?.[1];
         return {
             registered: Registered.Yes,
@@ -472,6 +473,15 @@ function configFileAuth(harness) {
         ...(entry.keyMatchesCliKey ? { keyMatchesCliKey: true } : {}),
     };
 }
+// 2.x rows carry the service's handshake; 1.x prints `remote`, which decides nothing.
+function listHealth(output) {
+    const status = TINYFISH_LIST_ROW.exec(output)?.[1]?.trim();
+    if (status === 'connected')
+        return { connected: true };
+    if (status === 'needs authentication' || status?.startsWith('failed'))
+        return { connected: false };
+    return {};
+}
 // `mcp list` resolves project config too, so it stays the registration source of truth.
 function probeMcpList(harness) {
     const command = harnessSpec(harness).command;
@@ -484,8 +494,16 @@ function probeMcpList(harness) {
     const listed = fromMcpList(command, probe.output, AuthMode.Unknown, MCP_LIST_ROW_URL);
     if (listed.registered !== Registered.Yes)
         return listed;
-    // A project-scoped entry is listed but absent here, so auth mode stays unknown.
-    return { ...listed, ...configFileAuth(harness) };
+    const health = listHealth(probe.output);
+    // The global key is not the active credential when a project entry overrides it.
+    if (projectDefinesTinyfish(harness)) {
+        return { ...listed, ...health, keyReason: 'a project config overrides the global entry' };
+    }
+    const fileAuth = configFileAuth(harness);
+    // A failed handshake disproves the global key no matter whose it is.
+    if (health.connected === false)
+        delete fileAuth.keyMatchesCliKey;
+    return { ...listed, ...health, ...fileAuth };
 }
 // Verified against grok 0.0.60: a list. Header values stay `unknown`; only names are read.
 const grokEntrySchema = z.looseObject({

package/package.json

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