@tiny-fish/cli 0.52.4-next.431 → 0.52.4-next.433

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,13 +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)
@@ -43,12 +102,35 @@ function exportApiKey(apiKey, displayName, deferOutro) {
     }
     return true;
 }
+/** Best-effort: the profile export still covers terminal launches. */
+function seedHarnessDotenv(client, keyed, deferOutro) {
+    const { envVar } = keyed.spec;
+    const envPath = harnessDotenvPath(client.connectClient);
+    if (!envPath || !envVar)
+        return false;
+    try {
+        // Unlike Hermes, nothing else needs this file group-readable.
+        writeDotenvKey(envPath, envVar, keyed.key, dotenvMarkerHead(client.connectClient), {
+            ownerOnly: true,
+        });
+    }
+    catch (error) {
+        warnLine(`Could not write ${envVar} to ${envPath} (${error instanceof Error ? error.message : String(error)}).`);
+        return false;
+    }
+    const line = `Wrote ${envVar} to ${envPath} — ${client.displayName} reads the key from there.`;
+    (deferOutro ?? errLine)(line);
+    return true;
+}
 function resolveKeyedAdd(client, storedKey, keyAuthSupported, keyAuthOnly, deferOutro) {
     if (!storedKey || !keyAuthSupported || !client.keyAuth)
         return undefined;
     const keyed = { key: storedKey, spec: client.keyAuth };
+    const seededDotenv = seedHarnessDotenv(client, keyed, deferOutro);
     // Before the removals: a failed export must not strand the old registration.
-    if (keyed.spec.envVar && !exportApiKey(keyed.key, client.displayName, deferOutro)) {
+    if (keyed.spec.envVar &&
+        !exportApiKey(keyed.key, client.displayName, deferOutro) &&
+        !seededDotenv) {
         if (keyAuthOnly)
             refuseFailedKeyExport(client);
         errLine(`Signing in to ${client.displayName} instead.`);
@@ -263,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];
@@ -292,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,
@@ -300,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/doctor-checks.js

@@ -116,6 +116,8 @@ function registrationVerdict(status, mcpUrl, keyAuth, cliKeyMissing) {
         }
         // Ordered before the key check: the harness's own verdict wins.
         if (status.connected === false) {
+            if (status.keyReason)
+                return { status: 'warn', detail: `registered, but ${status.keyReason}` };
             return {
                 status: 'warn',
                 detail: 'registered, but the harness reports it cannot reach TinyFish; sign in again there',

package/dist/lib/dotenv-file.d.ts

@@ -1,5 +1,9 @@
+import { type Harness } from './harness/harness-spec.js';
+export declare function harnessDotenvPath(harness: Harness): string | undefined;
 export declare function dotenvMarkerHead(client: string): string;
-export declare function writeDotenvKey(envPath: string, varName: string, key: string, markerHead: string): void;
+export declare function writeDotenvKey(envPath: string, varName: string, key: string, markerHead: string, { ownerOnly }?: {
+    ownerOnly?: boolean;
+}): void;
 export declare function readDotenvKey(envPath: string, varName: string): string | undefined;
 /** Restores the exact line writeDotenvKey replaces, quotes and comment included. */
 export declare function captureDotenvKeyRestore(envPath: string, varName: string, markerHead: string): () => void;

package/dist/lib/dotenv-file.js

@@ -1,9 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { harnessSpec } from './harness/harness-spec.js';
+import { harnessConfigPath } from './harness/harness-detect.js';
 const MARKER_TAIL = '# tinyfish-cli: end';
 // Keys are `sk-tinyfish-<alnum>`; refusing anything else beats shipping unreachable escaping.
 const BARE_SAFE = /^[A-Za-z0-9._\-/:+=]+$/;
+export function harnessDotenvPath(harness) {
+    return harnessSpec(harness).keyDotenv ? path.join(harnessConfigPath(harness), '.env') : undefined;
+}
 export function dotenvMarkerHead(client) {
     return `# tinyfish-cli: TinyFish MCP key, managed by \`tinyfish connect ${client}\``;
 }
@@ -28,7 +33,7 @@ function readLines(envPath) {
         .split(/(?<=\n)/);
 }
 // Hermes preserves the original mode so Docker volume mounts survive (config.py:3921-3929).
-function writeAtomic(envPath, lines) {
+function writeAtomic(envPath, lines, ownerOnly = false) {
     let mode = 0o600;
     try {
         mode = fs.statSync(envPath).mode & 0o777;
@@ -36,6 +41,8 @@ function writeAtomic(envPath, lines) {
     catch {
         // No existing file: 0600 is the right default for credentials.
     }
+    if (ownerOnly)
+        mode &= 0o700;
     const tmp = `${envPath}.${randomUUID()}.tmp`;
     try {
         fs.writeFileSync(tmp, lines.join(''), { encoding: 'utf8', mode });
@@ -48,7 +55,7 @@ function writeAtomic(envPath, lines) {
         throw error;
     }
 }
-export function writeDotenvKey(envPath, varName, key, markerHead) {
+export function writeDotenvKey(envPath, varName, key, markerHead, { ownerOnly = false } = {}) {
     const clean = key.replace(/[\r\n]/g, '').trim();
     // An empty key reads as "bad characters" without its own branch.
     if (!clean)
@@ -64,12 +71,12 @@ export function writeDotenvKey(envPath, varName, key, markerHead) {
         if (lines.length && !lines[lines.length - 1].endsWith('\n'))
             lines[lines.length - 1] += '\n';
         lines.push(`${markerHead}\n`, assignment, `${MARKER_TAIL}\n`);
-        writeAtomic(envPath, lines);
+        writeAtomic(envPath, lines, ownerOnly);
         return;
     }
     lines[index] = assignment;
     // Dotenv loaders are last-wins; a surviving duplicate would beat this value.
-    writeAtomic(envPath, lines.filter((line, i) => i === index || !definesKey(line, varName)));
+    writeAtomic(envPath, lines.filter((line, i) => i === index || !definesKey(line, varName)), ownerOnly);
 }
 export function readDotenvKey(envPath, varName) {
     const line = readLines(envPath).find((l) => definesKey(l, varName));

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

@@ -5,6 +5,7 @@ import which from 'which';
 import { ALL_HARNESSES, harnessSpec } from './harness-spec.js';
 import { clineConfigDir } from '../config/cline-config.js';
 import { piAgentDir, piBinaryIsPi } from '../config/pi-config.js';
+import { agentHome } from '../skill-paths.js';
 export { ALL_HARNESSES };
 export const HARNESS_DISPLAY_NAMES = Object.fromEntries(ALL_HARNESSES.map((harness) => [harness, harnessSpec(harness).displayName]));
 export const RELOAD_ACTION = Object.fromEntries(ALL_HARNESSES.map((harness) => [harness, harnessSpec(harness).reloadAction]));
@@ -26,17 +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;
     }
 }
-// PI_CODING_AGENT_DIR and CLINE_DIR move these dirs; a guessed path would be written unread.
+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

@@ -48,6 +48,8 @@ export interface HarnessSpec {
     };
     /** Keyed adds append this flag plus the env var name (Codex). */
     keyEnvFlag?: string;
+    /** The harness loads `<config dir>/.env` at launch (Codex). */
+    keyDotenv?: boolean;
     /** Keyed adds append these flags; the key itself is seeded elsewhere (Hermes). */
     keyAddFlags?: string[];
     /** No sign-in exists here, so connect refuses a keyless install (Hermes). */
@@ -85,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: {
@@ -156,6 +160,7 @@ export declare const HARNESS_SPECS: {
         };
         urlStyle: "flag";
         keyEnvFlag: string;
+        keyDotenv: true;
         degradedAuthNotes: {
             keyed: string;
             deferred: string;
@@ -307,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

@@ -78,6 +78,8 @@ export const HARNESS_SPECS = {
         urlStyle: 'flag',
         // Codex has no `--header`; the MCP server takes a key as `Bearer sk-…`.
         keyEnvFlag: '--bearer-token-env-var',
+        // GUI launches skip the shell profile; unset variable drops the server.
+        keyDotenv: true,
         degradedAuthNotes: { keyed: CODEX_KEYED_FALLBACK_NOTE, deferred: CODEX_DEFERRED_AUTH_NOTE },
         // `--oauth-resource` duplicates the resource Codex discovers; Clerk rejects both.
         // `mcp add` still runs OAuth inline, so `loginArgs` stays a retry.
@@ -238,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,10 +10,11 @@ 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';
+import { harnessDotenvPath, readDotenvKey } from './dotenv-file.js';
 import { readHermesEntry } from './config/hermes-config.js';
 import { detectInstalledHarnesses, harnessConfigPath, harnessDisplayPath, AuthMode, Registered, } from './harness/harness-detect.js';
 const NOT_REGISTERED = Object.freeze({
@@ -107,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.
@@ -245,15 +247,30 @@ const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function declaredKeyEnvVar(harness) {
     return NATIVE_BY_HARNESS.get(harness)?.keyAuth?.envVar;
 }
+/** An unreadable .env reads as unset, not as a failed probe. */
+function readDotenvKeySafe(dotenvPath, envVar) {
+    try {
+        return readDotenvKey(dotenvPath, envVar);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Codex stores a variable name; resolving it only answers whether it is the CLI's key. */
-function envKeyVerdict(envVar) {
+function envKeyVerdict(envVar, dotenvPath) {
     if (!ENV_VAR_NAME.test(envVar)) {
         return { keyReason: 'its key comes from an unusable variable name' };
     }
-    if (matchesCliKey(process.env[envVar]))
+    const fromDotenv = dotenvPath ? readDotenvKeySafe(dotenvPath, envVar) : undefined;
+    // GUI launches read only the .env; a shell export masks that.
+    if (dotenvPath && !fromDotenv) {
+        return { connected: false, keyReason: `$${envVar} is not in ${dotenvPath}` };
+    }
+    const value = process.env[envVar] || fromDotenv;
+    if (matchesCliKey(value))
         return { keyMatchesCliKey: true };
     return {
-        keyReason: process.env[envVar]
+        keyReason: value
             ? `$${envVar} holds a key this CLI cannot verify`
             : `$${envVar} is not set here`,
     };
@@ -279,7 +296,7 @@ function probeCodex() {
         // Codex's own verdict: a stale `oauth_resource` strands installs here.
         ...(entry.auth_status === CodexAuthStatus.NotLoggedIn && !envVar ? { connected: false } : {}),
         ...(codexUrl ? { registeredUrl: codexUrl } : {}),
-        ...(envVar ? envKeyVerdict(envVar) : {}),
+        ...(envVar ? envKeyVerdict(envVar, harnessDotenvPath('codex')) : {}),
     };
 }
 // No `cline mcp list`, so the settings file is the only registration evidence.
@@ -387,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,
@@ -456,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;
@@ -468,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/dist/lib/skill-paths.d.ts

@@ -1,4 +1,5 @@
 import type { SkillAgent } from './harness/harness-spec.js';
+export declare function agentHome(override: string, fallback: string): string;
 /** Where skills@1.5.15 wrote skill dirs for this agent. */
 export declare function skillRootDir(agent: SkillAgent): string;
 /** Mirrors skills@1.5.15 getSkillLockPath(); missing the XDG branch strands entries. */

package/dist/lib/skill-paths.js

@@ -1,7 +1,7 @@
 import * as os from 'node:os';
 import * as path from 'node:path';
 // Mirrors skills@1.5.15 exactly: it trims and falls back on empty values.
-function agentHome(override, fallback) {
+export function agentHome(override, fallback) {
     return process.env[override]?.trim() || path.join(os.homedir(), fallback); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
 }
 // `skills` writes here for the universal agents, whose own config dirs it never touches.

package/package.json

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