@tiny-fish/cli 0.30.2-next.259 → 0.30.2-next.264

package/dist/lib/connect-clients.js

@@ -2,9 +2,11 @@ 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 { errLine, sanitizeLine, warnLine } from './output.js';
+import { ConnectStepError, spawnStepError, } from './connect-runtime.js';
 import { TINYFISH_API_KEY_VAR } from './constants.js';
+import { HERMES_KEY_VAR, captureHermesKeyRestore, hermesEnvPath, resolveHermesHome, writeHermesKey, } from './hermes-env.js';
+import { hermesConfigPath, readHermesEntry } from './hermes-config.js';
 const HERMES_SEED_TIMEOUT_MS = 120_000;
 // An old install is only one reason a flag can go unseen, so no message asserts the cause.
 const SUPPORT_CHECK_DEBUG_HINT = ' Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.';
@@ -242,6 +244,48 @@ function launchHermesWalkthrough() {
     }
     handOverTerminal('hermes', ['--resume', sessionId], 'Hermes');
 }
+/** `mcp add` exits 0 after saving nothing, or a disabled entry. */
+export function hermesRegistrationEnabled(home) {
+    const entry = readHermesEntry(home);
+    if (entry.state === 'enabled')
+        return { ok: true };
+    // Each of these is a different repair, so none of them share wording.
+    const detail = {
+        disabled: 'the entry was saved disabled',
+        absent: 'no tinyfish entry was saved',
+        unreadable: `${hermesConfigPath(home)} could not be read`,
+        unparseable: `${hermesConfigPath(home)} could not be parsed`,
+    }[entry.state];
+    return { ok: false, detail };
+}
+function seedHermesKey(apiKey) {
+    const home = resolveHermesHome();
+    // A plain Error settles unexpected_error; cli_connect_stage is load-bearing.
+    if (!home) {
+        throw new ConnectStepError("Could not determine Hermes' home directory from `hermes dump`", 'invalid_config');
+    }
+    const restore = captureHermesKeyRestore(home);
+    writeHermesKey(home, apiKey);
+    return {
+        // Pins HERMES_HOME so a sticky profile can't shadow this key.
+        env: { ...process.env, HERMES_HOME: home },
+        // Three: a failed `mcp remove` adds an extra Overwrite prompt.
+        stdinInput: 'y\ny\ny\n',
+        note: `Wrote ${HERMES_KEY_VAR} to ${hermesEnvPath(home)} — Hermes reads the key from there.`,
+        rollback: () => rollbackHermesKey(home, restore),
+        confirmRegistered: () => hermesRegistrationEnabled(home),
+    };
+}
+// A failed re-run must not cost a working key.
+function rollbackHermesKey(home, restore) {
+    try {
+        // The next `hermes mcp add` silently reuses whatever value survives here.
+        restore();
+    }
+    catch {
+        warnLine(`Could not restore ${HERMES_KEY_VAR} in ${hermesEnvPath(home)}; check it by hand.`);
+    }
+}
 export const HERMES = {
     command: 'hermes',
     connectClient: 'hermes',
@@ -250,14 +294,20 @@ export const HERMES = {
     supportCheck: {
         args: ['mcp', 'add', '--help'],
         patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
+        keyAuthPattern: /--auth\s+\{[^}]*header[^}]*\}/,
         unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
     },
-    // No `keyAuth`: `hermes mcp add` has no --header, and `--auth header` prompts interactively.
+    // No envVar: key goes into Hermes' .env, not the shell.
+    keyAuth: {
+        addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), '--auth', 'header'],
+        seedKey: seedHermesKey,
+    },
     removals: [{ args: ['mcp', 'remove', 'tinyfish'], label: 'TinyFish registration from Hermes' }],
     // Hermes completes OAuth while adding the server; a separate `mcp login` would authenticate twice.
     oauthInAdd: true,
     addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), '--auth', 'oauth'],
     launchWalkthrough: launchHermesWalkthrough,
+    postConnectNote: 'Restart your Hermes session to pick up TinyFish — Hermes discovers MCP servers at startup.',
 };
 // OpenCode's TUI takes a positional as a project directory, so a bare `opencode "<prompt>"`
 // would be read as a folder. The `--prompt` flag seeds the interactive TUI with a first message
@@ -338,8 +388,9 @@ export const HARNESS_CAPABILITIES = {
     },
     hermes: {
         signInViaCliLogin: false,
+        // Stays false: keyed already covers auth; true breaks keyless installs.
         canVerifyAuth: false,
-        keyHeldByCli: false,
+        keyHeldByCli: true,
         cliWritesConfig: false,
         authDeferredAtInstall: false,
     },

package/dist/lib/connect-fallback.js

@@ -49,12 +49,10 @@ export function createStdinPrompt() {
         }
     };
 }
-/** Steps print retry lines and return outcomes; only interrupts throw. */
-export async function runCliFallback(opts) {
-    const { hooks, prompt } = opts;
-    hooks?.onStepStart?.('cli_install');
+function installStep(opts) {
     try {
         installTinyFishCli({ verbose: opts.verbose, announce: true });
+        return null;
     }
     catch (error) {
         if (error instanceof ConnectInterruptedError)
@@ -63,8 +61,8 @@ export async function runCliFallback(opts) {
         outLine(`Retry: ${opts.retryCommand}`);
         return 'cli_install_failed';
     }
-    hooks?.onStepDone?.('cli_installed');
-    hooks?.onStepStart?.('authentication');
+}
+function authStep(opts) {
     // Resolved raw: validatedApiKey collapses a malformed key into "no key".
     const rawKey = resolvedApiKey(opts.apiKey);
     if (rawKey && !validateKeyFormat(rawKey)) {
@@ -73,7 +71,7 @@ export async function runCliFallback(opts) {
         outLine(`Retry: ${opts.retryCommand}`);
         return 'invalid_credentials';
     }
-    if (!prompt && !rawKey) {
+    if (!opts.prompt && !rawKey) {
         outLine(`Retry in a terminal: ${opts.retryCommand}`);
         return 'no_credentials';
     }
@@ -81,8 +79,9 @@ export async function runCliFallback(opts) {
         // Gate-only widening: a config-only key must not re-persist anywhere.
         // Headless has no one to answer a login prompt; never inherit stdio there.
         ensureCliAuthenticated('cli', opts.apiKey ?? process.env[TINYFISH_API_KEY_VAR], {
-            interactiveLogin: !!prompt,
+            interactiveLogin: !!opts.prompt,
         });
+        return null;
     }
     catch (error) {
         if (error instanceof ConnectInterruptedError)
@@ -93,33 +92,31 @@ export async function runCliFallback(opts) {
             : 'Retry: tinyfish auth login');
         return 'authentication_failed';
     }
-    hooks?.onStepDone?.('authenticated');
-    hooks?.onStepStart?.('cli_verification');
+}
+/** null = abandoned; the retry line is already printed. */
+async function promptQuery(prompt) {
     let query;
-    if (prompt) {
-        try {
-            query = (await prompt('What would you like to search? ')).trim();
-        }
-        catch (error) {
-            if (error instanceof ConnectInterruptedError)
-                throw error;
-            outLine(`Retry: ${SEARCH_RETRY}`);
-            return 'abandoned';
-        }
-        if (!query) {
-            outLine(`Retry: ${SEARCH_RETRY}`);
-            return 'abandoned';
-        }
+    try {
+        query = (await prompt('What would you like to search? ')).trim();
     }
-    else {
-        // Headless with a key: a canned query still proves the pipe.
-        query = DEFAULT_VERIFICATION_QUERY;
+    catch (error) {
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        outLine(`Retry: ${SEARCH_RETRY}`);
+        return null;
     }
+    if (!query) {
+        outLine(`Retry: ${SEARCH_RETRY}`);
+        return null;
+    }
+    return query;
+}
+function verifyStep(query, interactive) {
     const search = spawn.sync('tinyfish', ['search', 'query', '--pretty', '--', query], {
         stdio: 'inherit',
         env: { ...process.env, TF_SETUP_VERIFICATION: '1' },
         // A user-driven search must never be cut off.
-        timeout: prompt ? undefined : HEADLESS_VERIFY_TIMEOUT_MS,
+        timeout: interactive ? undefined : HEADLESS_VERIFY_TIMEOUT_MS,
     });
     if (commandNotFound(search.error)) {
         errLine(TINYFISH_CLI_NOT_FOUND_MESSAGE);
@@ -131,6 +128,37 @@ export async function runCliFallback(opts) {
         outLine(`Retry: ${searchRetry(query)}`);
         return 'verification_failed';
     }
-    hooks?.onStepDone?.('cli_verified');
     return 'cli_verified';
 }
+/** Steps print retry lines and return outcomes; only interrupts throw. */
+export async function runCliFallback(opts) {
+    const { hooks, prompt } = opts;
+    const stepStart = hooks?.onStepStart ?? (() => { });
+    const stepDone = hooks?.onStepDone ?? (() => { });
+    stepStart('cli_install');
+    const installFailure = installStep(opts);
+    if (installFailure)
+        return installFailure;
+    stepDone('cli_installed');
+    stepStart('authentication');
+    const authFailure = authStep(opts);
+    if (authFailure)
+        return authFailure;
+    stepDone('authenticated');
+    stepStart('cli_verification');
+    let query;
+    if (prompt) {
+        const answered = await promptQuery(prompt);
+        if (answered === null)
+            return 'abandoned';
+        query = answered;
+    }
+    else {
+        // Headless with a key: a canned query still proves the pipe.
+        query = DEFAULT_VERIFICATION_QUERY;
+    }
+    const outcome = verifyStep(query, !!prompt);
+    if (outcome === 'cli_verified')
+        stepDone('cli_verified');
+    return outcome;
+}

package/dist/lib/connect-picker.js

@@ -19,6 +19,24 @@ function frame(items, checked, cursor) {
     const count = checked.filter(Boolean).length;
     return [...rows, '', `  ${enterHint(count, items.length)}`, KEY_HELP, ''].join('\n');
 }
+function keyCommand(key) {
+    const name = key.name ?? '';
+    // Raw mode eats terminal SIGINT, so Ctrl+C arrives only here.
+    if ((key.ctrl && (name === 'c' || name === 'd')) || name === 'q' || name === 'escape') {
+        return 'cancel';
+    }
+    if (name === 'return' || name === 'enter')
+        return 'submit';
+    if (name === 'up' || name === 'k')
+        return 'up';
+    if (name === 'down' || name === 'j')
+        return 'down';
+    if (name === 'space')
+        return 'toggle';
+    if (name === 'a')
+        return 'toggle-all';
+    return 'none';
+}
 async function pickWithKeys(items, stdin, write) {
     const checked = items.map(() => true);
     let cursor = 0;
@@ -38,24 +56,23 @@ async function pickWithKeys(items, stdin, write) {
         return await new Promise((resolve, reject) => {
             onKeypress = (_chunk, key = {}) => {
                 try {
-                    const name = key.name ?? '';
-                    // Raw mode eats terminal SIGINT, so Ctrl+C arrives only here.
-                    if ((key.ctrl && (name === 'c' || name === 'd')) || name === 'q' || name === 'escape') {
+                    const command = keyCommand(key);
+                    if (command === 'cancel') {
                         resolve('cancel');
                         return;
                     }
-                    if (name === 'return' || name === 'enter') {
+                    if (command === 'submit') {
                         const picked = items.filter((_, i) => checked[i]).map((item) => item.harness);
                         resolve(picked.length > 0 ? picked : 'cancel');
                         return;
                     }
-                    if (name === 'up' || name === 'k')
+                    if (command === 'up')
                         cursor = (cursor + items.length - 1) % items.length;
-                    else if (name === 'down' || name === 'j')
+                    else if (command === 'down')
                         cursor = (cursor + 1) % items.length;
-                    else if (name === 'space')
+                    else if (command === 'toggle')
                         checked[cursor] = !checked[cursor];
-                    else if (name === 'a')
+                    else if (command === 'toggle-all')
                         checked.fill(!checked.every(Boolean));
                     paint();
                 }

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

@@ -11,6 +11,9 @@ export type CliFallbackOutcome = 'cli_verified' | 'cli_install_failed' | 'no_cre
 /** Ctrl+C killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {
 }
+/** Carried hoisted-install failure an earlier harness already reported. */
+export declare class HoistedFailureReportedError extends Error {
+}
 /** A classified step failure; runGuarded forwards the reason. */
 export declare class ConnectStepError extends Error {
     readonly failureReason: ConnectFailureReason;
@@ -20,6 +23,9 @@ export declare class ConnectStepError extends Error {
         cause?: unknown;
     });
 }
+/** Hoisted install predates this attempt's telemetry; the gap reads ~0 ms. */
+export declare function withStageDuration(error: Error, stageDurationMs: number): Error;
+export declare function stageDurationOf(error: unknown): number | undefined;
 /** A bounded sign-in wait elapsed — unfinished, not broken. */
 export declare class SignInTimeoutError extends ConnectStepError {
     constructor(message: string, cause?: unknown);

package/dist/lib/connect-runtime.js

@@ -25,6 +25,9 @@ export const CONNECT_FAILURE_REASONS = [
 /** Ctrl+C killed a setup child — abandonment, not error. */
 export class ConnectInterruptedError extends Error {
 }
+/** Carried hoisted-install failure an earlier harness already reported. */
+export class HoistedFailureReportedError extends Error {
+}
 /** A classified step failure; runGuarded forwards the reason. */
 export class ConnectStepError extends Error {
     failureReason;
@@ -35,6 +38,15 @@ export class ConnectStepError extends Error {
         this.harnessVersion = opts?.harnessVersion;
     }
 }
+/** Hoisted install predates this attempt's telemetry; the gap reads ~0 ms. */
+export function withStageDuration(error, stageDurationMs) {
+    error.stageDurationMs = stageDurationMs;
+    return error;
+}
+export function stageDurationOf(error) {
+    const value = error?.stageDurationMs;
+    return typeof value === 'number' ? value : undefined;
+}
 class PrerequisiteError extends ConnectStepError {
 }
 /** A bounded sign-in wait elapsed — unfinished, not broken. */
@@ -127,10 +139,14 @@ export async function runGuarded(state, telemetry, body) {
             settle(state, telemetry, 'aborted', { failedStage: state.stage, failureReason: 'timeout' });
             throw error;
         }
+        // An earlier attempt owns the shared failure's terminal row.
+        if (error instanceof HoistedFailureReportedError)
+            throw error;
         settle(state, telemetry, 'failed', {
             failedStage: state.stage,
             failureReason: error instanceof ConnectStepError ? error.failureReason : 'unexpected_error',
             ...(error instanceof ConnectStepError ? { harnessVersion: error.harnessVersion } : {}),
+            stageDurationMs: stageDurationOf(error),
         });
         throw error;
     }
@@ -139,6 +155,17 @@ export async function runGuarded(state, telemetry, body) {
         await telemetry.flush();
     }
 }
+function throwProbeFailure(client, result) {
+    throwIfInterrupted(result);
+    // A hung probe is a timeout, not a missing capability.
+    if (result.error?.code === 'ETIMEDOUT') {
+        throw new ConnectStepError(client.supportCheck.unavailableMessage, 'timeout', {
+            cause: result.error,
+        });
+    }
+    // It ran and exited non-zero, so the version is still answerable.
+    throw new PrerequisiteError(client.supportCheck.unavailableMessage, 'harness_command_unsupported', { cause: result.error, harnessVersion: probeHarnessVersion(client.command) });
+}
 export function requireCommandSupport(client) {
     const result = spawn.sync(client.command, client.supportCheck.args, {
         encoding: 'utf8',
@@ -151,15 +178,7 @@ export function requireCommandSupport(client) {
         throw new PrerequisiteError(`${client.displayName} is not installed or not available on PATH.`, 'harness_not_installed', { cause: result.error });
     }
     if (result.error || result.status !== 0) {
-        throwIfInterrupted(result);
-        // A hung probe is a timeout, not a missing capability.
-        if (result.error?.code === 'ETIMEDOUT') {
-            throw new ConnectStepError(client.supportCheck.unavailableMessage, 'timeout', {
-                cause: result.error,
-            });
-        }
-        // It ran and exited non-zero, so the version is still answerable.
-        throw new PrerequisiteError(client.supportCheck.unavailableMessage, 'harness_command_unsupported', { cause: result.error, harnessVersion: probeHarnessVersion(client.command) });
+        throwProbeFailure(client, result);
     }
     // Belt and braces with the colour env: a client that ignores NO_COLOR still has to match.
     const output = sanitizeLine(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);

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

@@ -0,0 +1,18 @@
+/** Every message about the entry names this path. */
+export declare function hermesConfigPath(home: string): string;
+/** Callers branch on these; each is a different repair. */
+export type HermesEntry = {
+    state: 'unreadable';
+} | {
+    state: 'unparseable';
+} | {
+    state: 'absent';
+} | {
+    state: 'disabled';
+    usesKeyHeader: boolean;
+} | {
+    state: 'enabled';
+    usesKeyHeader: boolean;
+};
+/** Connect's gate and doctor's probe share this, so they cannot disagree. */
+export declare function readHermesEntry(home: string): HermesEntry;

package/dist/lib/hermes-config.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import { z } from 'zod';
+import { HERMES_KEY_VAR } from './hermes-env.js';
+/** Every message about the entry names this path. */
+export function hermesConfigPath(home) {
+    return path.join(home, 'config.yaml');
+}
+// Hermes persists the key as an interpolation template (mcp_config.py:174-182).
+const HEADER_TEMPLATE = `Bearer \${${HERMES_KEY_VAR}}`;
+// Foreign file: model only what we read, tolerate the rest.
+const entrySchema = z.looseObject({
+    // Anything goes: the runtime defaults unrecognised values to enabled.
+    enabled: z.unknown().optional(),
+    headers: z.record(z.string(), z.unknown()).optional(),
+});
+const configSchema = z
+    .looseObject({ mcp_servers: z.looseObject({ tinyfish: entrySchema.nullish() }).nullish() })
+    .nullish();
+const TRUTHY_STRINGS = new Set(['true', '1', 'yes', 'on']);
+const FALSY_STRINGS = new Set(['false', '0', 'no', 'off']);
+/**
+ * Mirrors the runtime's _parse_boolish (mcp_tool.py:5656), which decides whether
+ * tools are served. `hermes mcp list` coerces differently and disagrees on
+ * numbers and "on"; the runtime wins because it is what actually serves.
+ */
+function isEnabled(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string') {
+        const lowered = value.trim().toLowerCase();
+        if (TRUTHY_STRINGS.has(lowered))
+            return true;
+        if (FALSY_STRINGS.has(lowered))
+            return false;
+    }
+    return true;
+}
+/** Only the header template proves this entry uses the seeded key. */
+function hasKeyHeader(headers) {
+    const authorization = Object.entries(headers ?? {}).find(([name]) => name.toLowerCase() === 'authorization');
+    return authorization?.[1] === HEADER_TEMPLATE;
+}
+/** Connect's gate and doctor's probe share this, so they cannot disagree. */
+export function readHermesEntry(home) {
+    let raw;
+    try {
+        raw = fs.readFileSync(hermesConfigPath(home), 'utf8');
+    }
+    catch {
+        return { state: 'unreadable' };
+    }
+    let config;
+    try {
+        config = configSchema.parse(parse(raw));
+    }
+    catch {
+        return { state: 'unparseable' };
+    }
+    const entry = config?.mcp_servers?.tinyfish;
+    if (!entry)
+        return { state: 'absent' };
+    const usesKeyHeader = hasKeyHeader(entry.headers);
+    return isEnabled(entry.enabled)
+        ? { state: 'enabled', usesKeyHeader }
+        : { state: 'disabled', usesKeyHeader };
+}

package/dist/lib/hermes-env.d.ts

@@ -2,5 +2,11 @@ export declare const HERMES_PROBE_TIMEOUT_MS = 15000;
 /** Asking Hermes beats reimplementing its profile override, which we'd drift from. */
 export declare function resolveHermesHome(): string | undefined;
 export declare const HERMES_KEY_VAR = "MCP_TINYFISH_API_KEY";
+/** Named in every message about the seeded key, so no caller rebuilds the path. */
+export declare function hermesEnvPath(home: string): string;
 export declare function writeHermesKey(home: string, key: string): void;
+/** Doctor needs this to tell key auth from OAuth. */
+export declare function readHermesKey(home: string): string | undefined;
+/** Restores the exact line writeHermesKey replaces, quotes and comment included. */
+export declare function captureHermesKeyRestore(home: string): () => void;
 export declare function removeHermesKey(home: string): boolean;

package/dist/lib/hermes-env.js

@@ -25,6 +25,10 @@ export function resolveHermesHome() {
     return path.isAbsolute(expanded) ? expanded : undefined;
 }
 export const HERMES_KEY_VAR = 'MCP_TINYFISH_API_KEY';
+/** Named in every message about the seeded key, so no caller rebuilds the path. */
+export function hermesEnvPath(home) {
+    return path.join(home, '.env');
+}
 const MARKER_HEAD = `# tinyfish-cli: TinyFish MCP key, managed by \`tinyfish connect hermes\``;
 const MARKER_TAIL = '# tinyfish-cli: end';
 // Keys are `sk-tinyfish-<alnum>`; refusing anything else beats shipping unreachable escaping.
@@ -37,12 +41,18 @@ function definesKey(line) {
 function isMarker(line) {
     return line.trim() === MARKER_HEAD || line.trim() === MARKER_TAIL;
 }
-// utf-8 read keeps the BOM; rewriting it breaks Hermes' first key.
+// A leading BOM would otherwise ride into the first key's name.
 function readLines(envPath) {
     if (!fs.existsSync(envPath))
         return [];
-    return fs
-        .readFileSync(envPath, 'utf8')
+    const raw = fs.readFileSync(envPath);
+    // A valid UTF-8 .env has no NUL; every wide encoding does.
+    if (raw.includes(0)) {
+        throw new Error(`${envPath} contains NUL bytes, so it is a wide encoding or corrupt; TinyFish can only ` +
+            `edit a UTF-8 .env. Re-save it as UTF-8 and retry.`);
+    }
+    return raw
+        .toString('utf8')
         .replace(/^\uFEFF/, '')
         .split(/(?<=\n)/);
 }
@@ -75,7 +85,7 @@ export function writeHermesKey(home, key) {
     if (!BARE_SAFE.test(clean)) {
         throw new Error('TinyFish API key contains characters that cannot be written to a .env file');
     }
-    const envPath = path.join(home, '.env');
+    const envPath = hermesEnvPath(home);
     fs.mkdirSync(home, { recursive: true });
     const lines = readLines(envPath);
     const assignment = `${HERMES_KEY_VAR}=${clean}\n`;
@@ -91,8 +101,43 @@ export function writeHermesKey(home, key) {
     // load_env() is last-wins; a surviving duplicate would beat this value.
     writeAtomic(envPath, lines.filter((line, i) => i === index || !definesKey(line)));
 }
+/** Doctor needs this to tell key auth from OAuth. */
+export function readHermesKey(home) {
+    const line = readLines(hermesEnvPath(home)).find(definesKey);
+    if (!line)
+        return undefined;
+    // We never write quoted values, so a quoted one isn't ours.
+    const raw = line
+        .trim()
+        .replace(/^export\s+/, '')
+        .slice(HERMES_KEY_VAR.length + 1)
+        .trim();
+    return BARE_SAFE.test(raw) ? raw : undefined;
+}
+/** Restores the exact line writeHermesKey replaces, quotes and comment included. */
+export function captureHermesKeyRestore(home) {
+    // Raw, not readHermesKey: its parse drops quoted and comment-trailed values.
+    const previous = readLines(hermesEnvPath(home)).find(definesKey);
+    return () => {
+        if (previous === undefined) {
+            removeHermesKey(home);
+            return;
+        }
+        const envPath = hermesEnvPath(home);
+        let restored = false;
+        const lines = readLines(envPath).flatMap((line) => {
+            if (!definesKey(line))
+                return [line];
+            if (restored)
+                return [];
+            restored = true;
+            return [previous];
+        });
+        writeAtomic(envPath, restored ? lines : [...lines, previous]);
+    };
+}
 export function removeHermesKey(home) {
-    const envPath = path.join(home, '.env');
+    const envPath = hermesEnvPath(home);
     const lines = readLines(envPath);
     if (!lines.length)
         return false;

package/dist/lib/mcp-endpoint.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
+export declare function endpointOf(url: string): string;
+/** `verifyMcpAuth` hits BASE_URL, so a sandbox key would 401 against prod. */
+export declare function isDefaultEndpoint(mcpUrl: string): boolean;

package/dist/lib/mcp-endpoint.js

@@ -0,0 +1,15 @@
+export const DEFAULT_MCP_URL = 'https://agent.tinyfish.ai/mcp';
+// Query strings carry the connect attempt id, so they differ on every healthy install.
+export function endpointOf(url) {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname.replace(/\/$/, '')}`;
+}
+/** `verifyMcpAuth` hits BASE_URL, so a sandbox key would 401 against prod. */
+export function isDefaultEndpoint(mcpUrl) {
+    try {
+        return endpointOf(mcpUrl) === endpointOf(DEFAULT_MCP_URL);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/registration-detect.js

@@ -7,6 +7,8 @@ import { NATIVE_BY_HARNESS } from './connect-clients.js';
 import { HARNESS_PROBE_TIMEOUT_MS } from './constants.js';
 import { errLine } from './output.js';
 import { readCursorTinyfishEntry } from './cursor-config.js';
+import { readHermesKey, resolveHermesHome } from './hermes-env.js';
+import { readHermesEntry } from './hermes-config.js';
 import { detectInstalledHarnesses, harnessConfigPath, harnessDisplayPath, AuthMode, Registered, } from './harness-detect.js';
 // A list, verified against codex 0.146. A name-keyed map was accepted here too, but every
 // field is optional, so that arm parsed *any* object-of-objects: a wrapper like
@@ -303,15 +305,39 @@ function fromMcpList(command, output, registeredMode, urlPattern) {
     }
     return { registered: Registered.No, authMode: AuthMode.Unknown };
 }
-// connect only ever writes an OAuth Hermes entry, so `oauth` is a fact, not a detection gap.
+// `hermes mcp list` only pretty-prints this file, so connect's gate reads it too.
 function probeHermes() {
-    const args = ['mcp', 'list'];
-    const probe = runProbe('hermes', args);
-    if (probe.outcome !== 'ran' || probe.exitCode !== 0) {
-        const reason = probeReason('hermes', args, probe);
-        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason };
+    const home = resolveHermesHome();
+    if (!home) {
+        return {
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
+            reason: '`hermes dump` did not report a home directory',
+        };
     }
-    return fromMcpList('hermes', probe.output, AuthMode.OAuth);
+    const entry = readHermesEntry(home);
+    if (entry.state === 'unreadable' || entry.state === 'unparseable') {
+        return {
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
+            reason: `Hermes' config.yaml could not be ${entry.state === 'unreadable' ? 'read' : 'parsed'}`,
+        };
+    }
+    if (entry.state === 'absent')
+        return { registered: Registered.No, authMode: AuthMode.Unknown };
+    // `mcp add` saves a disabled entry on a failed connect, which connect refuses too.
+    const enabled = entry.state === 'enabled' ? {} : { connected: false };
+    // The .env key is Hermes-wide; the header template ties it here.
+    const storedKey = entry.usesKeyHeader ? readHermesKey(home) : undefined;
+    if (!storedKey) {
+        return { registered: Registered.Yes, authMode: AuthMode.OAuth, ...enabled };
+    }
+    return {
+        registered: Registered.Yes,
+        authMode: AuthMode.ApiKey,
+        ...enabled,
+        ...(matchesCliKey(storedKey) ? { keyMatchesCliKey: true } : {}),
+    };
 }
 const SKILL_DIR_IS_TINYFISH = /^(?:@tinyfish[/_-])?tinyfish(?![\w-])/i;
 // OpenClaw installs a skill, not an MCP server; the skill shells the CLI, so auth is the CLI key.

package/dist/lib/verify.d.ts

@@ -10,5 +10,5 @@ export interface VerifyResult {
 }
 /** Reachability check. Verify failure is a warning, never install failure. */
 export declare function verifyMcpHealth(mcpUrl: string): Promise<VerifyResult>;
-/** Authenticated check — only where the CLI holds the key (Cursor, OpenClaw). */
+/** Authenticated check — where the CLI holds the key (Cursor, OpenClaw, Hermes). */
 export declare function verifyMcpAuth(apiKey: string): Promise<VerifyResult>;