@tiny-fish/cli 0.20.1 → 0.21.1-next.194

package/dist/lib/connect-runtime.js

@@ -7,10 +7,22 @@ import { errLine, sanitizeLine } from "./output.js";
 import { postConnectEvent, telemetryDisabled } from "./setup-telemetry.js";
 import { installSignalGuard } from "./signals.js";
 export const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
+// Mirrors the route's Zod enum; tests both sides pin it.
+export const CONNECT_FAILURE_REASONS = [
+    "harness_not_installed",
+    "harness_command_unsupported",
+    "harness_too_old",
+    "command_not_found",
+    "timeout",
+    "spawn_error",
+    "nonzero_exit",
+    "invalid_config",
+];
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export class ConnectInterruptedError extends Error {
 }
-class PrerequisiteError extends Error {
+/** A classified step failure; runGuarded forwards the reason. */
+export class ConnectStepError extends Error {
     failureReason;
     harnessVersion;
     constructor(message, failureReason, opts) {
@@ -19,6 +31,8 @@ class PrerequisiteError extends Error {
         this.harnessVersion = opts?.harnessVersion;
     }
 }
+class PrerequisiteError extends ConnectStepError {
+}
 export function throwIfInterrupted(result) {
     // spawn.sync kills a timed-out child with SIGTERM, so signal alone would misread a slow
     // network as the user walking away. A timeout is a failure and must report as one.
@@ -28,6 +42,19 @@ export function throwIfInterrupted(result) {
         throw new ConnectInterruptedError("Setup interrupted");
     }
 }
+/** Classifies a spawn failure; interrupts throw instead. */
+export function spawnStepError(message, result) {
+    throwIfInterrupted(result);
+    const code = result.error?.code;
+    const reason = !result.error
+        ? "nonzero_exit"
+        : code === "ENOENT"
+            ? "command_not_found"
+            : code === "ETIMEDOUT"
+                ? "timeout"
+                : "spawn_error";
+    return new ConnectStepError(message, reason, { cause: result.error });
+}
 export function commandNotFound(error) {
     return error?.code === "ENOENT";
 }
@@ -65,7 +92,7 @@ export async function runGuarded(state, telemetry, body) {
         }
         settle(state, telemetry, "failed", {
             failedStage: state.stage,
-            ...(error instanceof PrerequisiteError
+            ...(error instanceof ConnectStepError
                 ? { failureReason: error.failureReason, harnessVersion: error.harnessVersion }
                 : {}),
         });
@@ -88,14 +115,23 @@ export function requireCommandSupport(client) {
     }
     if (result.error || result.status !== 0) {
         throwIfInterrupted(result);
-        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
+        // 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) });
     }
     // 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 ?? ""}`);
     const listed = (patterns) => patterns.every((pattern) => pattern.test(output));
     const essential = listed(client.supportCheck.patterns);
     const optionalSupported = listed(client.supportCheck.optionalPatterns ?? []);
-    if ((!essential || !optionalSupported) && process.env["TINYFISH_DEBUG"]) {
+    const keyAuthPattern = client.supportCheck.keyAuthPattern;
+    const keyAuthSupported = keyAuthPattern ? keyAuthPattern.test(output) : true;
+    if ((!essential || !optionalSupported || !keyAuthSupported) && process.env["TINYFISH_DEBUG"]) {
         errLine(`${client.command} ${client.supportCheck.args.join(" ")} printed:\n${output.trim()}`);
     }
     if (!essential) {
@@ -103,7 +139,7 @@ export function requireCommandSupport(client) {
             harnessVersion: probeHarnessVersion(client.command),
         });
     }
-    return { optionalSupported };
+    return { optionalSupported, keyAuthSupported, harnessVersion: probeHarnessVersion(client.command) };
 }
 /** Best-effort; the server rejects non-printable characters and >32 chars. */
 function probeHarnessVersion(command) {
@@ -113,7 +149,9 @@ function probeHarnessVersion(command) {
     });
     if (result.error || result.status !== 0)
         return undefined;
+    // First line only: sanitizeLine keeps newlines, so stripping splices lines.
     const version = sanitizeLine(result.stdout ?? "")
+        .split("\n")[0]
         .replace(/[^\x20-\x7E]/g, "")
         .trim();
     return version ? version.slice(0, 32) : undefined;
@@ -138,6 +176,8 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
     const attemptId = opts?.attemptId ?? seeded ?? randomUUID();
     const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
     const pending = [];
+    let lastTrackAt;
+    let harnessVersion;
     async function deliver(body) {
         // Ahead of the key read; postConnectEvent's own opt-out check is too late to skip it.
         if (telemetryDisabled())
@@ -154,7 +194,14 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
     return {
         attemptId,
         // Fire-and-forget; awaiting each event stalls setup when telemetry down.
+        setHarnessVersion(version) {
+            harnessVersion = version;
+        },
         track(stage, detail) {
+            const now = Date.now();
+            // Clamped: a backward clock step would send a route-rejected negative.
+            const stageDurationMs = lastTrackAt === undefined ? undefined : Math.max(0, now - lastTrackAt);
+            lastTrackAt = now;
             // Absorbed here, not in flush: flush runs in runGuarded's finally, so a rejection would
             // replace the error the flow is already reporting.
             pending.push(deliver(JSON.stringify({
@@ -164,9 +211,10 @@ export function createConnectTelemetry(mcpUrl, client, opts) {
                 failed_stage: detail?.failedStage,
                 phase: detail?.phase,
                 failure_reason: detail?.failureReason,
-                harness_version: detail?.harnessVersion,
+                harness_version: detail?.harnessVersion ?? harnessVersion,
                 auth_mode: detail?.authMode,
                 harness_degraded: detail?.harnessDegraded,
+                stage_duration_ms: stageDurationMs,
                 runtime_platform: process.platform,
                 node_version: process.version,
                 cli_version: CLI_VERSION,

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

@@ -14,9 +14,10 @@ export interface CursorTinyfishEntry {
     hasApiKeyHeader: boolean;
     /** Registered endpoint, so a caller can tell "registered" from "registered at the right place". */
     url?: string;
+    apiKey?: string;
     error?: string;
 }
-/** Read-only probe for doctor — reports shape, never the header value. */
+/** Carries the header value; callers keep it off the report. */
 export declare function readCursorTinyfishEntry(): CursorTinyfishEntry;
 /** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
 export declare function writeCursorMcpConfig(mcpUrl: string, apiKey?: string): CursorMcpWriteResult;

package/dist/lib/cursor-config.js

@@ -65,7 +65,7 @@ export function planCursorWrite(mcpUrl, apiKey) {
         ? `${filePath}: would create with a "tinyfish" MCP server entry${authNote}`
         : `${filePath}: would back up to a timestamped copy, then merge in the "tinyfish" MCP server entry${authNote}`;
 }
-/** Read-only probe for doctor — reports shape, never the header value. */
+/** Carries the header value; callers keep it off the report. */
 export function readCursorTinyfishEntry() {
     const existing = readExisting();
     if ("error" in existing)
@@ -77,10 +77,13 @@ export function readCursorTinyfishEntry() {
     const headers = entry.headers;
     // Header names are case-insensitive, and this file is hand-editable — matching only the
     // casing we write would understate auth mode for a user who typed it differently.
+    const keyHeader = isPlainRecord(headers)
+        ? Object.entries(headers).find(([name, value]) => name.toLowerCase() === "x-api-key" && typeof value === "string")
+        : undefined;
     return {
         present: true,
-        hasApiKeyHeader: isPlainRecord(headers) &&
-            Object.entries(headers).some(([name, value]) => name.toLowerCase() === "x-api-key" && typeof value === "string"),
+        hasApiKeyHeader: keyHeader !== undefined,
+        ...(keyHeader ? { apiKey: keyHeader[1] } : {}),
         ...(typeof entry.url === "string" ? { url: entry.url } : {}),
     };
 }

package/dist/lib/doctor-report.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { AuthMode, Registered } from "./harness-detect.js";
 /** Bumped whenever a consumer could misread the payload; the cookbook skill releases separately. */
-export declare const DOCTOR_SCHEMA_VERSION = 1;
+export declare const DOCTOR_SCHEMA_VERSION = 2;
 declare const checkStatusSchema: z.ZodEnum<{
     pass: "pass";
     fail: "fail";
@@ -36,16 +37,8 @@ declare const doctorHarnessSchema: z.ZodObject<{
         "claude-code": "claude-code";
     }>;
     detected: z.ZodBoolean;
-    registered: z.ZodEnum<{
-        unknown: "unknown";
-        yes: "yes";
-        no: "no";
-    }>;
-    auth_mode: z.ZodEnum<{
-        unknown: "unknown";
-        "api-key": "api-key";
-        oauth: "oauth";
-    }>;
+    registered: z.ZodEnum<typeof Registered>;
+    auth_mode: z.ZodEnum<typeof AuthMode>;
     proves_harness_reach: z.ZodBoolean;
 }, z.core.$strip>;
 declare const doctorRepairSchema: z.ZodObject<{
@@ -98,16 +91,8 @@ export declare const doctorReportSchema: z.ZodObject<{
             "claude-code": "claude-code";
         }>;
         detected: z.ZodBoolean;
-        registered: z.ZodEnum<{
-            unknown: "unknown";
-            yes: "yes";
-            no: "no";
-        }>;
-        auth_mode: z.ZodEnum<{
-            unknown: "unknown";
-            "api-key": "api-key";
-            oauth: "oauth";
-        }>;
+        registered: z.ZodEnum<typeof Registered>;
+        auth_mode: z.ZodEnum<typeof AuthMode>;
         proves_harness_reach: z.ZodBoolean;
     }, z.core.$strip>>;
     repairs: z.ZodArray<z.ZodObject<{

package/dist/lib/doctor-report.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { ALL_HARNESSES } from "./harness-detect.js";
+import { ALL_HARNESSES, AuthMode, Registered } from "./harness-detect.js";
 /** Bumped whenever a consumer could misread the payload; the cookbook skill releases separately. */
-export const DOCTOR_SCHEMA_VERSION = 1;
+export const DOCTOR_SCHEMA_VERSION = 2;
 const checkStatusSchema = z.enum(["pass", "fail", "warn", "skip"]);
 const harnessSchema = z.enum(ALL_HARNESSES);
 const doctorCheckSchema = z.object({
@@ -14,8 +14,8 @@ const doctorCheckSchema = z.object({
 const doctorHarnessSchema = z.object({
     harness: harnessSchema,
     detected: z.boolean(),
-    registered: z.enum(["yes", "no", "unknown"]),
-    auth_mode: z.enum(["api-key", "oauth", "unknown"]),
+    registered: z.enum(Registered),
+    auth_mode: z.enum(AuthMode),
     proves_harness_reach: z.boolean(),
 });
 // `action` is what `--fix` dispatches on, not the harness field: keying off a null harness

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

@@ -1,5 +1,15 @@
 export declare const ALL_HARNESSES: readonly ["claude-code", "codex", "cursor", "hermes", "openclaw", "opencode"];
 export type Harness = (typeof ALL_HARNESSES)[number];
+export declare enum Registered {
+    Yes = "yes",
+    No = "no",
+    Unknown = "unknown"
+}
+export declare enum AuthMode {
+    ApiKey = "api-key",
+    OAuth = "oauth",
+    Unknown = "unknown"
+}
 export declare function harnessConfigPath(harness: Harness): string;
 /** For reason strings that name a location; keeps them in sync with the table above. */
 export declare function harnessDisplayPath(harness: Harness): string;

package/dist/lib/harness-detect.js

@@ -9,6 +9,19 @@ export const ALL_HARNESSES = [
     "openclaw",
     "opencode",
 ];
+// Values are the wire contract; the report schema derives from these.
+export var Registered;
+(function (Registered) {
+    Registered["Yes"] = "yes";
+    Registered["No"] = "no";
+    Registered["Unknown"] = "unknown";
+})(Registered || (Registered = {}));
+export var AuthMode;
+(function (AuthMode) {
+    AuthMode["ApiKey"] = "api-key";
+    AuthMode["OAuth"] = "oauth";
+    AuthMode["Unknown"] = "unknown";
+})(AuthMode || (AuthMode = {}));
 // Presence detection only — dir existence means "installed", nothing more.
 const CONFIG_DIRS = {
     "claude-code": ".claude",

package/dist/lib/install-root.d.ts

@@ -0,0 +1,15 @@
+/** Where this CLI is installed: `prefix` for npm, `nodeModules` for reading the version back. */
+export type InstallRoot = {
+    prefix: string;
+    nodeModules: string;
+};
+/**
+ * The prefix to upgrade in place, or null when the layout is not npm's.
+ *
+ * Guarded on purpose: npx, pnpm and bun all nest the package under a bare `node_modules`, and
+ * installing into their trees would report a success the PATH binary never sees.
+ */
+export declare function resolveInstallRoot(packageRoot: string, platform: typeof process.platform, onDisk?: (candidate: string) => boolean): InstallRoot | null;
+export declare function installRoot(): InstallRoot | null;
+/** The version on disk under a prefix, which is the only account of what `@latest` resolved to. */
+export declare function readInstalledVersion(nodeModules: string): string | null;

package/dist/lib/install-root.js

@@ -0,0 +1,49 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { TINYFISH_CLI_PACKAGE } from "./constants.js";
+function isDirectory(candidate) {
+    try {
+        return fs.statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The prefix to upgrade in place, or null when the layout is not npm's.
+ *
+ * Guarded on purpose: npx, pnpm and bun all nest the package under a bare `node_modules`, and
+ * installing into their trees would report a success the PATH binary never sees.
+ */
+export function resolveInstallRoot(packageRoot, platform, onDisk = isDirectory) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    // npx's win32 cache uses the same bare layout as a global install.
+    if (packageRoot.split(p.sep).includes("_npx"))
+        return null;
+    const nodeModules = p.resolve(packageRoot, "..", "..");
+    if (p.basename(nodeModules) !== "node_modules")
+        return null;
+    const container = p.dirname(nodeModules);
+    // Only win32 puts node_modules directly under the prefix.
+    if (platform !== "win32" && p.basename(container) !== "lib")
+        return null;
+    if (!onDisk(nodeModules))
+        return null;
+    return { prefix: platform === "win32" ? container : p.dirname(container), nodeModules };
+}
+export function installRoot() {
+    // Two levels up from dist/lib/ is the package root, and tsc mirrors src/ into dist/.
+    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    return resolveInstallRoot(packageRoot, process.platform);
+}
+/** The version on disk under a prefix, which is the only account of what `@latest` resolved to. */
+export function readInstalledVersion(nodeModules) {
+    try {
+        const manifest = fs.readFileSync(path.join(nodeModules, ...TINYFISH_CLI_PACKAGE.split("/"), "package.json"), "utf8");
+        return JSON.parse(manifest).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -1,6 +1,4 @@
-import { type Harness } from "./harness-detect.js";
-export type Registered = "yes" | "no" | "unknown";
-export type AuthMode = "api-key" | "oauth" | "unknown";
+import { AuthMode, type Harness, Registered } from "./harness-detect.js";
 export interface RegistrationStatus {
     harness: Harness;
     detected: boolean;
@@ -9,6 +7,8 @@ export interface RegistrationStatus {
     connectedBefore: boolean;
     /** The endpoint the harness is actually pointed at, when the probe exposes it. */
     registeredUrl?: string;
+    /** For doctor to verify; never for the report. */
+    apiKey?: string;
     reason?: string;
 }
 export declare function codexOauthCompleted(): boolean | undefined;

package/dist/lib/registration-detect.js

@@ -2,10 +2,10 @@ import * as fs from "fs";
 import * as path from "path";
 import spawn from "cross-spawn";
 import { z } from "zod";
-import { loadConfig } from "./auth.js";
+import { hasKeyPrefix, loadConfig } from "./auth.js";
 import { errLine } from "./output.js";
 import { readCursorTinyfishEntry } from "./cursor-config.js";
-import { detectInstalledHarnesses, harnessConfigPath, harnessDisplayPath, } from "./harness-detect.js";
+import { detectInstalledHarnesses, harnessConfigPath, harnessDisplayPath, AuthMode, Registered, } from "./harness-detect.js";
 // 6s tripped on a cold `hermes mcp list`, measured at 6.34s.
 const PROBE_TIMEOUT_MS = 15_000;
 // A list, verified against codex 0.146. A name-keyed map was accepted here too, but every
@@ -24,6 +24,12 @@ const UNSUPPORTED_SUBCOMMAND = /unknown command|unrecognized subcommand|invalid
 // `claude mcp get` exits 1 for a usage error too, so only this message is evidence of absence.
 const NO_SUCH_SERVER = /no (?:mcp )?server named/i;
 const API_KEY_HEADER = /x-api-key/i;
+// `claude mcp get` prints the value; `mcp add` masks it.
+const API_KEY_HEADER_VALUE = /^\s*X-API-Key:\s*(\S+)\s*$/im;
+// Charset is the redaction guard: `***`, `[REDACTED]`, dotted masks.
+function extractableKey(value) {
+    return value && hasKeyPrefix(value) && /^[A-Za-z0-9_-]+$/.test(value) ? value : undefined;
+}
 // OpenCode colours its list even through a pipe, putting `\x1b[34m` between the line start and
 // the server name, so an unstripped probe reads a registered harness as absent.
 // eslint-disable-next-line no-control-regex
@@ -84,8 +90,8 @@ function fromPluginRegistration(command) {
         return undefined;
     // `mcp list` prints no headers, so the credential behind it is unproven, never assumed.
     return {
-        registered: "yes",
-        authMode: "unknown",
+        registered: Registered.Yes,
+        authMode: AuthMode.Unknown,
         registeredUrl: match[2],
         reason: `registered as ${match[1]}, which \`mcp get tinyfish\` does not resolve`,
     };
@@ -94,13 +100,13 @@ function fromPluginRegistration(command) {
 function fromMcpGet(command, keyAuthPattern) {
     const probe = runProbe(command, ["mcp", "get", "tinyfish"]);
     if (probe.outcome === "unavailable") {
-        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason: probe.reason };
     }
     if (probe.exitCode !== 0) {
         if (UNSUPPORTED_SUBCOMMAND.test(probe.output)) {
             return {
-                registered: "unknown",
-                authMode: "unknown",
+                registered: Registered.Unknown,
+                authMode: AuthMode.Unknown,
                 reason: `\`${command} mcp get\` is unsupported by this version`,
             };
         }
@@ -111,20 +117,22 @@ function fromMcpGet(command, keyAuthPattern) {
         // A broken CLI also exits nonzero, and reading that as absence earns a spurious repair.
         if (!NO_SUCH_SERVER.test(probe.output)) {
             return {
-                registered: "unknown",
-                authMode: "unknown",
+                registered: Registered.Unknown,
+                authMode: AuthMode.Unknown,
                 reason: `\`${command} mcp get\` failed without reporting the server as absent`,
             };
         }
-        return { registered: "no", authMode: "unknown" };
+        return { registered: Registered.No, authMode: AuthMode.Unknown };
     }
     // Positive evidence only: whether `mcp get` echoes headers at all is unverified, so absence
     // of the pattern is `unknown`, never proof of OAuth.
     const url = /^\s*URL:\s*(\S+)/m.exec(probe.output)?.[1];
+    const key = extractableKey(API_KEY_HEADER_VALUE.exec(probe.output)?.[1]);
     return {
-        registered: "yes",
-        authMode: keyAuthPattern.test(probe.output) ? "api-key" : "unknown",
+        registered: Registered.Yes,
+        authMode: keyAuthPattern.test(probe.output) ? AuthMode.ApiKey : AuthMode.Unknown,
         ...(url ? { registeredUrl: url } : {}),
+        ...(key ? { apiKey: key } : {}),
     };
 }
 // `codex mcp get <missing>` prints an error and exits 0, so presence must never be read from
@@ -170,20 +178,20 @@ export function codexOauthCompleted() {
 function probeCodex() {
     const read = readCodexEntry();
     if ("reason" in read)
-        return { registered: "unknown", authMode: "unknown", reason: read.reason };
+        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason: read.reason };
     const entry = read.entry;
     if (!entry)
-        return { registered: "no", authMode: "unknown" };
+        return { registered: Registered.No, authMode: AuthMode.Unknown };
     const codexUrl = entry.transport?.url;
     return {
-        registered: "yes",
+        registered: Registered.Yes,
         // Read from this entry: codex emits `bearer_token_env_var` on every HTTP server, so testing
         // the whole payload reports api-key for TinyFish because some other server carries a key.
         authMode: entry.auth_status === "o_auth"
-            ? "oauth"
+            ? AuthMode.OAuth
             : entry.transport?.bearer_token_env_var
-                ? "api-key"
-                : "unknown",
+                ? AuthMode.ApiKey
+                : AuthMode.Unknown,
         ...(codexUrl ? { registeredUrl: codexUrl } : {}),
     };
 }
@@ -191,17 +199,19 @@ function probeCursor() {
     const entry = readCursorTinyfishEntry();
     if (entry.error) {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: "mcp.json exists but could not be read or parsed",
         };
     }
     if (!entry.present)
-        return { registered: "no", authMode: "unknown" };
+        return { registered: Registered.No, authMode: AuthMode.Unknown };
+    const key = extractableKey(entry.apiKey);
     return {
-        registered: "yes",
-        authMode: entry.hasApiKeyHeader ? "api-key" : "unknown",
+        registered: Registered.Yes,
+        authMode: entry.hasApiKeyHeader ? AuthMode.ApiKey : AuthMode.Unknown,
         ...(entry.url ? { registeredUrl: entry.url } : {}),
+        ...(key ? { apiKey: key } : {}),
     };
 }
 // Both list commands print this header in every state, including "no servers configured".
@@ -213,31 +223,31 @@ const OPENCODE_ROW_URL = /^[^\w]*tinyfish(?![\w-]).*\n[^\w]*(https?:\S+)/m;
 function fromMcpList(command, output, registeredMode, urlPattern) {
     if (LISTED_AS_TINYFISH.test(output)) {
         const url = urlPattern?.exec(output)?.[1];
-        return { registered: "yes", authMode: registeredMode, ...(url ? { registeredUrl: url } : {}) };
+        return { registered: Registered.Yes, authMode: registeredMode, ...(url ? { registeredUrl: url } : {}) };
     }
     if (!MCP_LIST_HEADER.test(output)) {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: `could not interpret \`${command} mcp list\` output`,
         };
     }
-    return { registered: "no", authMode: "unknown" };
+    return { registered: Registered.No, authMode: AuthMode.Unknown };
 }
-// Hermes registers with `--auth oauth` and has no key path today, so mode is fixed.
+// connect only ever writes an OAuth Hermes entry, so `oauth` is a fact, not a detection gap.
 function probeHermes() {
     const probe = runProbe("hermes", ["mcp", "list"]);
     if (probe.outcome === "unavailable") {
-        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason: probe.reason };
     }
     if (probe.exitCode !== 0) {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: `\`hermes mcp list\` exited ${probe.exitCode}`,
         };
     }
-    return fromMcpList("hermes", probe.output, "oauth");
+    return fromMcpList("hermes", probe.output, AuthMode.OAuth);
 }
 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.
@@ -249,30 +259,30 @@ function probeOpenClaw() {
     }
     catch {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: `no global skills directory at ${harnessDisplayPath("openclaw")}/skills; OpenClaw layout is unverified`,
         };
     }
     // A bare substring also matched a skill merely named `not-tinyfish-thing`.
     return entries.some((name) => SKILL_DIR_IS_TINYFISH.test(name))
-        ? { registered: "yes", authMode: "api-key" }
-        : { registered: "no", authMode: "unknown" };
+        ? { registered: Registered.Yes, authMode: AuthMode.ApiKey }
+        : { registered: Registered.No, authMode: AuthMode.Unknown };
 }
-// Connect registers with `mcp add --url` then `mcp auth`, so there is no key path today.
+// `opencode mcp list` prints no headers, so a key-authed registration is indistinguishable.
 function probeOpencode() {
     const probe = runProbe("opencode", ["mcp", "list"]);
     if (probe.outcome === "unavailable") {
-        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+        return { registered: Registered.Unknown, authMode: AuthMode.Unknown, reason: probe.reason };
     }
     if (probe.exitCode !== 0) {
         return {
-            registered: "unknown",
-            authMode: "unknown",
+            registered: Registered.Unknown,
+            authMode: AuthMode.Unknown,
             reason: `\`opencode mcp list\` exited ${probe.exitCode}`,
         };
     }
-    return fromMcpList("opencode", probe.output, "oauth", OPENCODE_ROW_URL);
+    return fromMcpList("opencode", probe.output, AuthMode.Unknown, OPENCODE_ROW_URL);
 }
 const PROBES = {
     "claude-code": () => fromMcpGet("claude", API_KEY_HEADER),
@@ -295,7 +305,7 @@ export function detectRegistrations(harnesses) {
         };
         // Undetected means nothing to probe: no spawn cost, and no misleading "unknown".
         if (!detection.detected) {
-            return { ...base, registered: "no", authMode: "unknown" };
+            return { ...base, registered: Registered.No, authMode: AuthMode.Unknown };
         }
         try {
             return { ...base, ...PROBES[detection.harness]() };
@@ -308,8 +318,8 @@ export function detectRegistrations(harnesses) {
             }
             return {
                 ...base,
-                registered: "unknown",
-                authMode: "unknown",
+                registered: Registered.Unknown,
+                authMode: AuthMode.Unknown,
                 reason: "the probe failed unexpectedly",
             };
         }

package/dist/lib/verify.d.ts

@@ -5,6 +5,8 @@ export interface VerifyResult {
     reason?: string;
     /** Authored summary of `reason`, safe to publish. Additive: `connect` still prints `reason`. */
     code?: string;
+    /** Lets doctor tell 401 from 403 without matching prose. */
+    status?: number;
 }
 /** Reachability check. Verify failure is a warning, never install failure. */
 export declare function verifyMcpHealth(mcpUrl: string): Promise<VerifyResult>;

package/dist/lib/verify.js

@@ -74,6 +74,7 @@ export async function verifyMcpAuth(apiKey) {
             ok: false,
             reason: e instanceof Error ? e.message : String(e),
             code: authCode(e),
+            ...(e instanceof ApiError ? { status: e.status } : {}),
         };
     }
 }

package/package.json

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