@tiny-fish/cli 0.38.1-next.306 → 0.38.1-next.308

package/dist/commands/connect.js

@@ -1,6 +1,6 @@
 import spawn from 'cross-spawn';
 import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, } from '../lib/auth.js';
-import { CURSOR_SKILL_TARGET, OPENCLAW, OPENCLAW_SKILL_INSTALL_ARGS, NATIVE_BY_HARNESS, launchNativeMcpClient, launchOmpWalkthrough, launchOpenClawWalkthrough, openExternalUrl, } from '../lib/connect-clients.js';
+import { CURSOR_SKILL_TARGET, OPENCLAW, openclawSkillInstallArgs, NATIVE_BY_HARNESS, launchNativeMcpClient, launchOmpWalkthrough, launchOpenClawWalkthrough, openExternalUrl, } from '../lib/connect-clients.js';
 import { captureStdio, capturedOutput, HoistedFailureReportedError, installTinyFishCli, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from '../lib/cli-install.js';
 import { ensureCliAuthenticated } from '../lib/connect-auth.js';
 import { createStdinPrompt, runCliFallback } from '../lib/connect-fallback.js';
@@ -474,7 +474,7 @@ export async function connectOpenClaw(options) {
         }
         state.stage = 'skill_install';
         errLine('Installing the TinyFish skill in OpenClaw...');
-        const skillInstallResult = spawn.sync('openclaw', OPENCLAW_SKILL_INSTALL_ARGS, captureStdio(options.verbose ?? false));
+        const skillInstallResult = spawn.sync('openclaw', openclawSkillInstallArgs(support.matchedVariant), captureStdio(options.verbose ?? false));
         if (skillInstallResult.error || skillInstallResult.status !== 0) {
             // Built first: its interrupt check must run before any replay.
             const error = spawnStepError('Could not install the TinyFish skill in OpenClaw', skillInstallResult);

package/dist/commands/doctor.js

@@ -1,282 +1,15 @@
-import { apiKeyStatus } from '../lib/auth.js';
 import { CLI_VERSION } from '../lib/constants.js';
+import { checkAuthCall, checkCliVersion, checkConnectivity, checkCredential, checkHermesPlugin, checkRegistration, provesHarnessReach, verifyHarnessKey, } from '../lib/doctor-checks.js';
 import { DOCTOR_COULD_NOT_RUN, DOCTOR_INVALID_INPUT, DOCTOR_SCHEMA_VERSION, doctorReportSchema, exitCodeFor, renderPretty, verdictFor, } from '../lib/doctor-report.js';
 import { applyRepairs, repairsFor } from '../lib/doctor-repairs.js';
 import { couldNotRunPayload, telemetryKey, telemetryPayload } from '../lib/doctor-telemetry.js';
-import { ALL_HARNESSES, AuthMode, Registered } from '../lib/harness-detect.js';
-import { boundedVersion, err, errLine, out, outLine } from '../lib/output.js';
+import { ALL_HARNESSES } from '../lib/harness-detect.js';
+import { err, errLine, out, outLine } from '../lib/output.js';
 import { detectRegistrations } from '../lib/registration-detect.js';
 import { sendDoctorCompleted } from '../lib/setup-telemetry.js';
-import { verifyMcpAuth, verifyMcpHealth } from '../lib/verify.js';
-import { resolveHermesHome } from '../lib/hermes-env.js';
-import { HERMES_PLUGIN_VERSION, hermesWebBackendsOurs, readHermesPluginStatus, } from '../lib/hermes-plugin.js';
-import { DEFAULT_MCP_URL, endpointOf, isDefaultEndpoint } from '../lib/mcp-endpoint.js';
-// A green auth mode with a red auth call proves nothing, so the call's verdict gates the claim.
-function provesHarnessReach(status, keyAuth, healthOk, mcpUrl) {
-    // An endpoint doctor could not reach proves nothing about a harness pointed at it.
-    if (!healthOk)
-        return false;
-    if (pointsElsewhere(status.registeredUrl, mcpUrl))
-        return false;
-    if (status.registered !== Registered.Yes)
-        return false;
-    if (status.connected === true)
-        return true;
-    // Symmetric with registrationVerdict: a harness saying it cannot reach us is decisive.
-    if (status.connected === false)
-        return false;
-    // The harness's own key must have verified; the CLI's verdict says nothing about it.
-    return status.authMode === AuthMode.ApiKey && keyAuth?.ok === true;
-}
-// Reports the version, never judges it: staleness is the server's call via X-TF-Notice.
-function checkCliVersion() {
-    return {
-        id: 'cli-version',
-        title: `CLI ${CLI_VERSION}`,
-        status: 'pass',
-        detail: `${CLI_VERSION}; the server reports staleness via X-TF-Notice`,
-        harness: null,
-        scope: 'info',
-    };
-}
-async function checkConnectivity(mcpUrl) {
-    const health = await verifyMcpHealth(mcpUrl);
-    return {
-        id: 'mcp-connectivity',
-        title: 'MCP endpoint reachable',
-        status: health.ok ? 'pass' : 'fail',
-        detail: health.ok ? mcpUrl : (health.code ?? 'the endpoint is unreachable'),
-        // Harness-scoped: the CLI's own reachability is `cli-auth-call`'s claim.
-        harness: null,
-        scope: 'harness',
-    };
-}
-/** Host alone let `/wrong-path` and plain `http://` through and claim the harness reaches us. */
-function pointsElsewhere(registeredUrl, mcpUrl) {
-    if (!registeredUrl)
-        return undefined;
-    try {
-        const registered = endpointOf(registeredUrl);
-        return registered === endpointOf(mcpUrl) ? undefined : registered;
-    }
-    catch {
-        // An endpoint that will not parse cannot be shown to match, so it does not.
-        return 'an unparseable endpoint';
-    }
-}
-/** Either it reads the CLI's key at runtime or it holds a copy: the CLI's own verdict covers both. */
-function runsOnCliCredential(status) {
-    return status.usesCliKey === true || status.keyMatchesCliKey === true;
-}
-function keyedVerdict(status, keyAuth, cliKeyMissing) {
-    if (!keyAuth) {
-        // Its auth is the CLI credential; a warn would exit 0.
-        if (runsOnCliCredential(status)) {
-            return cliKeyMissing
-                ? {
-                    status: 'fail',
-                    detail: 'registered, but it runs on the CLI credential, which is missing or unusable',
-                }
-                : // Reachable with a key only when `--url` skipped verification.
-                    {
-                        status: 'warn',
-                        detail: 'registered, but its CLI credential was not verified against this endpoint',
-                    };
-        }
-        // A bare warn beside exit 0 reads as a pass.
-        const because = status.keyReason ?? 'the CLI cannot verify a key it does not hold';
-        return { status: 'warn', detail: `registered, but ${because}, so its reach is unproven` };
-    }
-    if (keyAuth.ok) {
-        return {
-            status: 'pass',
-            detail: 'registered, auth mode api-key (key verified against the TinyFish API)',
-        };
-    }
-    if (keyAuth.status === 401) {
-        return { status: 'fail', detail: 'registered, but TinyFish rejects its API key' };
-    }
-    // Only 401 blames the key; connect would loop on the rest.
-    if (keyAuth.status === 403) {
-        return { status: 'warn', detail: 'registered, but its API key is not allowed to list runs' };
-    }
-    return { status: 'warn', detail: 'registered, key could not be verified' };
-}
-function registrationVerdict(status, mcpUrl, keyAuth, cliKeyMissing) {
-    if (!status.detected)
-        return { status: 'skip', detail: 'harness not installed' };
-    if (status.registered === Registered.Unknown) {
-        return { status: 'warn', detail: status.reason ?? 'could not determine registration' };
-    }
-    if (status.registered === Registered.Yes) {
-        // A `tinyfish` entry aimed at a dev server is registered and still cannot reach TinyFish.
-        const elsewhere = pointsElsewhere(status.registeredUrl, mcpUrl);
-        if (elsewhere) {
-            return {
-                status: 'fail',
-                detail: `registered, but points at ${elsewhere} rather than ${endpointOf(mcpUrl)}`,
-            };
-        }
-        // Ordered before the key check: the harness's own verdict wins.
-        if (status.connected === false) {
-            return {
-                status: 'warn',
-                detail: 'registered, but the harness reports it cannot reach TinyFish; sign in again there',
-            };
-        }
-        // Symmetric with provesHarnessReach, which already reads a handshake as decisive.
-        if (status.connected === true) {
-            return { status: 'pass', detail: 'registered, and the harness reports it reaches TinyFish' };
-        }
-        // Widening past api-key would warn every healthy oauth install.
-        if (status.authMode === AuthMode.ApiKey)
-            return keyedVerdict(status, keyAuth, cliKeyMissing);
-        // Recorded, not verified: it never feeds provesHarnessReach.
-        if (status.recordedAuthMode) {
-            return {
-                status: 'pass',
-                detail: `registered, auth mode ${status.recordedAuthMode} ` +
-                    '(recorded at connect; this harness does not report its headers)',
-            };
-        }
-        // A probe that had to explain itself to reach `yes` is the only thing that explains `unknown`.
-        const because = status.reason ? ` (${status.reason})` : '';
-        return { status: 'pass', detail: `registered, auth mode ${status.authMode}${because}` };
-    }
-    // Connected once and now absent is a broken install; never connected is just not set up.
-    return status.connectedBefore
-        ? { status: 'fail', detail: 'connected previously but TinyFish is no longer registered' }
-        : { status: 'warn', detail: 'installed but TinyFish was never connected' };
-}
-function checkRegistration(status, mcpUrl, keyAuth, cliKeyMissing) {
-    return {
-        id: 'harness-registration',
-        title: `${status.harness} registration`,
-        harness: status.harness,
-        scope: 'harness',
-        ...registrationVerdict(status, mcpUrl, keyAuth, cliKeyMissing),
-    };
-}
-function checkCredential() {
-    const resolved = apiKeyStatus();
-    const check = {
-        id: 'cli-credential',
-        title: 'CLI credential',
-        status: 'key' in resolved ? 'pass' : 'fail',
-        detail: 'key' in resolved ? `key present from ${resolved.source}` : resolved.error,
-        harness: null,
-        scope: 'cli',
-    };
-    return 'key' in resolved ? { check, key: resolved.key } : { check };
-}
-function checkAuthCall(auth) {
-    if (!auth) {
-        return {
-            id: 'cli-auth-call',
-            title: 'Authenticated call',
-            status: 'skip',
-            detail: 'no credential to test',
-            harness: null,
-            scope: 'cli',
-        };
-    }
-    return {
-        id: 'cli-auth-call',
-        title: 'Authenticated call',
-        status: auth.ok ? 'pass' : 'fail',
-        detail: auth.ok ? 'listRuns succeeded' : (auth.code ?? 'the authenticated call failed'),
-        harness: null,
-        scope: 'cli',
-    };
-}
-function verifyHarnessKey(status, cliAuth, mcpUrl) {
-    if (!isDefaultEndpoint(mcpUrl))
-        return undefined;
-    // `pointsElsewhere` already fails; a second reason only misleads.
-    if (pointsElsewhere(status.registeredUrl, mcpUrl))
-        return undefined;
-    // The CLI never holds a harness's key, so only its own credential can be verified.
-    return runsOnCliCredential(status) ? cliAuth : undefined;
-}
-// `ok` is backends && key; provider_available re-reads the key through the provider.
-function hermesPluginStatusVerdict(status) {
-    if (status.ok) {
-        return status.provider_available === false
-            ? { status: 'warn', detail: 'plugin configured, but its provider cannot see the key' }
-            : {
-                status: 'pass',
-                detail: `plugin ${status.plugin_version ?? 'installed'}; backends and key configured`,
-            };
-    }
-    if (!status.web_backend_configured) {
-        return {
-            status: 'warn',
-            detail: 'plugin installed but the web backends do not point at tinyfish',
-        };
-    }
-    return {
-        status: 'fail',
-        detail: 'web backends point at tinyfish but no key resolves from ' +
-            'TINYFISH_API_KEY or MCP_TINYFISH_API_KEY',
-    };
-}
-/** An unreadable config cannot prove the backends are ours, so doctor never fails on it. */
-function backendsOurs(home) {
-    try {
-        return hermesWebBackendsOurs(home);
-    }
-    catch {
-        return false;
-    }
-}
-function hermesPluginVerdict(home) {
-    const probe = readHermesPluginStatus(home);
-    if (probe.state === 'not_installed') {
-        // Backends naming an absent provider are broken; never-installed keeps exit 0.
-        return backendsOurs(home)
-            ? {
-                status: 'fail',
-                detail: 'web backends point at tinyfish but the plugin is not installed or not enabled',
-            }
-            : { status: 'warn', detail: 'the TinyFish web plugin is not installed or not enabled' };
-    }
-    if (probe.state === 'unreachable') {
-        return { status: 'warn', detail: '`hermes tinyfish status` did not respond in time' };
-    }
-    if (probe.state === 'unparseable') {
-        return {
-            status: 'warn',
-            detail: '`hermes tinyfish status --json` returned unparseable output',
-        };
-    }
-    return {
-        ...hermesPluginStatusVerdict(probe.status),
-        // Machine-supplied, so it is bounded here rather than trusted onward.
-        observedVersion: boundedVersion(probe.status.plugin_version ?? ''),
-    };
-}
-function checkHermesPlugin(status) {
-    const base = {
-        id: 'hermes-plugin',
-        title: 'Hermes web plugin',
-        harness: 'hermes',
-        scope: 'harness',
-    };
-    if (!status.detected) {
-        return { check: { ...base, status: 'skip', detail: 'harness not installed' } };
-    }
-    if (status.registered !== Registered.Yes) {
-        return { check: { ...base, status: 'skip', detail: 'TinyFish is not registered in Hermes' } };
-    }
-    const home = resolveHermesHome();
-    if (!home) {
-        return {
-            check: { ...base, status: 'warn', detail: "could not determine Hermes' home directory" },
-        };
-    }
-    const { observedVersion, ...verdict } = hermesPluginVerdict(home);
-    return { check: { ...base, ...verdict }, observedVersion };
-}
+import { verifyMcpAuth } from '../lib/verify.js';
+import { HERMES_PLUGIN_VERSION } from '../lib/hermes-plugin.js';
+import { DEFAULT_MCP_URL } from '../lib/mcp-endpoint.js';
 /** Skips mean no Hermes; stamping those buries the drift share. */
 function hermesPluginVersions(result) {
     if (!result || result.check.status === 'skip')

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

@@ -1,7 +1,7 @@
 import spawn from 'cross-spawn';
 import { type AgentClient, type SupportedCommand } from './connect-runtime.js';
 import { type HarnessSpec, type SkillAgent } from './harness-spec.js';
-export declare const OPENCLAW_SKILL_INSTALL_ARGS: readonly string[];
+export declare function openclawSkillInstallArgs(ackFlag: string | undefined): string[];
 /** `openclaw skills` has no uninstall; ClawHub removes from the global dir. */
 export declare function openclawSkillUninstall(): {
     command: string;

package/dist/lib/connect-clients.js

@@ -12,14 +12,10 @@ import { HERMES_PLUGIN_VERSION, installHermesPlugin, setHermesWebBackends, } fro
 const HERMES_SEED_TIMEOUT_MS = 120_000;
 const OPENCLAW_SKILL = '@tinyfish/tinyfish';
 // --force makes this an unconditional overwrite, so the same call installs and refreshes.
-export const OPENCLAW_SKILL_INSTALL_ARGS = [
-    'skills',
-    'install',
-    OPENCLAW_SKILL,
-    '--global',
-    '--force',
-    '--acknowledge-clawhub-risk',
-];
+export function openclawSkillInstallArgs(ackFlag) {
+    const ack = ackFlag === undefined ? [] : [ackFlag];
+    return ['skills', 'install', OPENCLAW_SKILL, '--global', '--force', ...ack];
+}
 /** `openclaw skills` has no uninstall; ClawHub removes from the global dir. */
 export function openclawSkillUninstall() {
     return {

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

@@ -92,9 +92,12 @@ export interface SupportedCommand {
     displayName: string;
     supportCheck: HarnessSupportCheck;
 }
+/** Refresh paths need the advertised alternative without connect's version probe. */
+export declare function probeSupportVariant(client: SupportedCommand): string | undefined;
 export declare function requireCommandSupport(client: SupportedCommand): {
     optionalSupported: boolean;
     keyAuthSupported: boolean;
+    matchedVariant?: string;
     harnessVersion?: string;
 };
 export declare function createConnectTelemetry(mcpUrl: string, client: AgentClient, opts?: {

package/dist/lib/connect-runtime.js

@@ -178,23 +178,26 @@ export async function runGuarded(state, telemetry, body) {
         await telemetry.flush();
     }
 }
+function probeTimeoutMs(client) {
+    return client.supportCheck.timeoutMs ?? NON_INTERACTIVE_TIMEOUT_MS;
+}
 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,
-        });
+        const probe = `${client.command} ${client.supportCheck.args.join(' ')}`;
+        throw new ConnectStepError(`${client.displayName} did not respond to \`${probe}\` within ` +
+            `${probeTimeoutMs(client) / 1000}s. Retry.`, '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) });
+    throw new PrerequisiteError(client.supportCheck.unavailableMessage, 'harness_command_unsupported', { cause: result.error, harnessVersion: probeHarnessVersion(client) });
 }
-export function requireCommandSupport(client) {
+function supportProbeOutput(client) {
     const result = spawn.sync(client.command, client.supportCheck.args, {
         encoding: 'utf8',
         // Agent harnesses export FORCE_COLOR, which makes clients colourise even a piped --help.
         env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
-        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+        timeout: probeTimeoutMs(client),
     });
     // 127 is the shell's not-found code; a wrapper shim with no real binary behind it exits that.
     if (commandNotFound(result.error) || result.status === 127) {
@@ -204,31 +207,63 @@ export function requireCommandSupport(client) {
         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 ?? ''}`);
-    const listed = (patterns) => patterns.every((pattern) => pattern.test(output));
-    const essential = listed(client.supportCheck.patterns);
-    const optionalSupported = listed(client.supportCheck.optionalPatterns ?? []);
+    return sanitizeLine(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
+}
+function debugProbeOutput(client, output) {
+    if (!process.env['TINYFISH_DEBUG'])
+        return;
+    errLine(`${client.command} ${client.supportCheck.args.join(' ')} printed:\n${output.trim()}`);
+}
+function requireEssential(client, output) {
+    if (client.supportCheck.patterns.every((pattern) => pattern.test(output)))
+        return;
+    debugProbeOutput(client, output);
+    throw new PrerequisiteError(client.supportCheck.unavailableMessage, 'harness_too_old', {
+        harnessVersion: probeHarnessVersion(client),
+    });
+}
+/** Absence is a fact; an unknown flag means an upstream rename. */
+function resolveVariant(client, output) {
+    const check = client.supportCheck;
+    // Token equality, not a built regex: exact on both edges, and no dynamic RegExp.
+    const listed = new Set(output.split(/[\s,=]+/));
+    const matched = check.variants?.find((flag) => listed.has(flag));
+    if (matched)
+        return matched;
+    const unknown = check.unknownVariant?.exec(output)?.[0];
+    if (unknown === undefined)
+        return undefined;
+    // Unacknowledged policy warnings can block the install; fail before it does.
+    debugProbeOutput(client, output);
+    throw new PrerequisiteError(`${client.displayName} lists \`${unknown}\`, which this TinyFish CLI does not recognise. ` +
+        'Upgrade the TinyFish CLI with `tinyfish upgrade` and retry.', 'harness_too_old', { harnessVersion: probeHarnessVersion(client) });
+}
+/** Refresh paths need the advertised alternative without connect's version probe. */
+export function probeSupportVariant(client) {
+    const output = supportProbeOutput(client);
+    requireEssential(client, output);
+    return resolveVariant(client, output);
+}
+export function requireCommandSupport(client) {
+    const output = supportProbeOutput(client);
+    requireEssential(client, output);
+    const optionalSupported = (client.supportCheck.optionalPatterns ?? []).every((pattern) => pattern.test(output));
     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) {
-        throw new PrerequisiteError(client.supportCheck.unavailableMessage, 'harness_too_old', {
-            harnessVersion: probeHarnessVersion(client.command),
-        });
-    }
+    if (!optionalSupported || !keyAuthSupported)
+        debugProbeOutput(client, output);
     return {
         optionalSupported,
         keyAuthSupported,
-        harnessVersion: probeHarnessVersion(client.command),
+        matchedVariant: resolveVariant(client, output),
+        harnessVersion: probeHarnessVersion(client),
     };
 }
 /** Best-effort; the server rejects non-printable characters and >32 chars. */
-function probeHarnessVersion(command) {
-    const result = spawn.sync(command, ['--version'], {
+function probeHarnessVersion(client) {
+    const result = spawn.sync(client.command, ['--version'], {
         encoding: 'utf8',
-        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+        timeout: probeTimeoutMs(client),
     });
     if (result.error || result.status !== 0)
         return undefined;

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

@@ -0,0 +1,18 @@
+import type { DoctorCheck } from './doctor-report.js';
+import type { RegistrationStatus } from './registration-detect.js';
+import { type VerifyResult } from './verify.js';
+export declare function provesHarnessReach(status: RegistrationStatus, keyAuth: VerifyResult | undefined, healthOk: boolean, mcpUrl: string): boolean;
+export declare function checkCliVersion(): DoctorCheck;
+export declare function checkConnectivity(mcpUrl: string): Promise<DoctorCheck>;
+export declare function checkRegistration(status: RegistrationStatus, mcpUrl: string, keyAuth: VerifyResult | undefined, cliKeyMissing: boolean): DoctorCheck;
+export declare function checkCredential(): {
+    check: DoctorCheck;
+    key?: string;
+};
+export declare function checkAuthCall(auth: VerifyResult | undefined): DoctorCheck;
+export declare function verifyHarnessKey(status: RegistrationStatus, cliAuth: Promise<VerifyResult> | undefined, mcpUrl: string): Promise<VerifyResult> | undefined;
+export interface HermesPluginResult {
+    check: DoctorCheck;
+    observedVersion?: string;
+}
+export declare function checkHermesPlugin(status: RegistrationStatus): HermesPluginResult;

package/dist/lib/doctor-checks.js

@@ -0,0 +1,274 @@
+import { apiKeyStatus } from './auth.js';
+import { CLI_VERSION } from './constants.js';
+import { AuthMode, Registered } from './harness-detect.js';
+import { resolveHermesHome } from './hermes-env.js';
+import { hermesWebBackendsOurs, readHermesPluginStatus, } from './hermes-plugin.js';
+import { endpointOf, isDefaultEndpoint } from './mcp-endpoint.js';
+import { boundedVersion } from './output.js';
+import { verifyMcpHealth } from './verify.js';
+// A green auth mode with a red auth call proves nothing, so the call's verdict gates the claim.
+export function provesHarnessReach(status, keyAuth, healthOk, mcpUrl) {
+    // An endpoint doctor could not reach proves nothing about a harness pointed at it.
+    if (!healthOk)
+        return false;
+    if (pointsElsewhere(status.registeredUrl, mcpUrl))
+        return false;
+    if (status.registered !== Registered.Yes)
+        return false;
+    if (status.connected === true)
+        return true;
+    // Symmetric with registrationVerdict: a harness saying it cannot reach us is decisive.
+    if (status.connected === false)
+        return false;
+    // The harness's own key must have verified; the CLI's verdict says nothing about it.
+    return status.authMode === AuthMode.ApiKey && keyAuth?.ok === true;
+}
+// Reports the version, never judges it: staleness is the server's call via X-TF-Notice.
+export function checkCliVersion() {
+    return {
+        id: 'cli-version',
+        title: `CLI ${CLI_VERSION}`,
+        status: 'pass',
+        detail: `${CLI_VERSION}; the server reports staleness via X-TF-Notice`,
+        harness: null,
+        scope: 'info',
+    };
+}
+export async function checkConnectivity(mcpUrl) {
+    const health = await verifyMcpHealth(mcpUrl);
+    return {
+        id: 'mcp-connectivity',
+        title: 'MCP endpoint reachable',
+        status: health.ok ? 'pass' : 'fail',
+        detail: health.ok ? mcpUrl : (health.code ?? 'the endpoint is unreachable'),
+        // Harness-scoped: the CLI's own reachability is `cli-auth-call`'s claim.
+        harness: null,
+        scope: 'harness',
+    };
+}
+/** Host alone let `/wrong-path` and plain `http://` through and claim the harness reaches us. */
+function pointsElsewhere(registeredUrl, mcpUrl) {
+    if (!registeredUrl)
+        return undefined;
+    try {
+        const registered = endpointOf(registeredUrl);
+        return registered === endpointOf(mcpUrl) ? undefined : registered;
+    }
+    catch {
+        // An endpoint that will not parse cannot be shown to match, so it does not.
+        return 'an unparseable endpoint';
+    }
+}
+/** Either it reads the CLI's key at runtime or it holds a copy: the CLI's own verdict covers both. */
+function runsOnCliCredential(status) {
+    return status.usesCliKey === true || status.keyMatchesCliKey === true;
+}
+function keyedVerdict(status, keyAuth, cliKeyMissing) {
+    if (!keyAuth) {
+        // Its auth is the CLI credential; a warn would exit 0.
+        if (runsOnCliCredential(status)) {
+            return cliKeyMissing
+                ? {
+                    status: 'fail',
+                    detail: 'registered, but it runs on the CLI credential, which is missing or unusable',
+                }
+                : // Reachable with a key only when `--url` skipped verification.
+                    {
+                        status: 'warn',
+                        detail: 'registered, but its CLI credential was not verified against this endpoint',
+                    };
+        }
+        // A bare warn beside exit 0 reads as a pass.
+        const because = status.keyReason ?? 'the CLI cannot verify a key it does not hold';
+        return { status: 'warn', detail: `registered, but ${because}, so its reach is unproven` };
+    }
+    if (keyAuth.ok) {
+        return {
+            status: 'pass',
+            detail: 'registered, auth mode api-key (key verified against the TinyFish API)',
+        };
+    }
+    if (keyAuth.status === 401) {
+        return { status: 'fail', detail: 'registered, but TinyFish rejects its API key' };
+    }
+    // Only 401 blames the key; connect would loop on the rest.
+    if (keyAuth.status === 403) {
+        return { status: 'warn', detail: 'registered, but its API key is not allowed to list runs' };
+    }
+    return { status: 'warn', detail: 'registered, key could not be verified' };
+}
+function registrationVerdict(status, mcpUrl, keyAuth, cliKeyMissing) {
+    if (!status.detected)
+        return { status: 'skip', detail: 'harness not installed' };
+    if (status.registered === Registered.Unknown) {
+        return { status: 'warn', detail: status.reason ?? 'could not determine registration' };
+    }
+    if (status.registered === Registered.Yes) {
+        // A `tinyfish` entry aimed at a dev server is registered and still cannot reach TinyFish.
+        const elsewhere = pointsElsewhere(status.registeredUrl, mcpUrl);
+        if (elsewhere) {
+            return {
+                status: 'fail',
+                detail: `registered, but points at ${elsewhere} rather than ${endpointOf(mcpUrl)}`,
+            };
+        }
+        // Ordered before the key check: the harness's own verdict wins.
+        if (status.connected === false) {
+            return {
+                status: 'warn',
+                detail: 'registered, but the harness reports it cannot reach TinyFish; sign in again there',
+            };
+        }
+        // Symmetric with provesHarnessReach, which already reads a handshake as decisive.
+        if (status.connected === true) {
+            return { status: 'pass', detail: 'registered, and the harness reports it reaches TinyFish' };
+        }
+        // Widening past api-key would warn every healthy oauth install.
+        if (status.authMode === AuthMode.ApiKey)
+            return keyedVerdict(status, keyAuth, cliKeyMissing);
+        // Recorded, not verified: it never feeds provesHarnessReach.
+        if (status.recordedAuthMode) {
+            return {
+                status: 'pass',
+                detail: `registered, auth mode ${status.recordedAuthMode} ` +
+                    '(recorded at connect; this harness does not report its headers)',
+            };
+        }
+        // A probe that had to explain itself to reach `yes` is the only thing that explains `unknown`.
+        const because = status.reason ? ` (${status.reason})` : '';
+        return { status: 'pass', detail: `registered, auth mode ${status.authMode}${because}` };
+    }
+    // Connected once and now absent is a broken install; never connected is just not set up.
+    return status.connectedBefore
+        ? { status: 'fail', detail: 'connected previously but TinyFish is no longer registered' }
+        : { status: 'warn', detail: 'installed but TinyFish was never connected' };
+}
+export function checkRegistration(status, mcpUrl, keyAuth, cliKeyMissing) {
+    return {
+        id: 'harness-registration',
+        title: `${status.harness} registration`,
+        harness: status.harness,
+        scope: 'harness',
+        ...registrationVerdict(status, mcpUrl, keyAuth, cliKeyMissing),
+    };
+}
+export function checkCredential() {
+    const resolved = apiKeyStatus();
+    const check = {
+        id: 'cli-credential',
+        title: 'CLI credential',
+        status: 'key' in resolved ? 'pass' : 'fail',
+        detail: 'key' in resolved ? `key present from ${resolved.source}` : resolved.error,
+        harness: null,
+        scope: 'cli',
+    };
+    return 'key' in resolved ? { check, key: resolved.key } : { check };
+}
+export function checkAuthCall(auth) {
+    if (!auth) {
+        return {
+            id: 'cli-auth-call',
+            title: 'Authenticated call',
+            status: 'skip',
+            detail: 'no credential to test',
+            harness: null,
+            scope: 'cli',
+        };
+    }
+    return {
+        id: 'cli-auth-call',
+        title: 'Authenticated call',
+        status: auth.ok ? 'pass' : 'fail',
+        detail: auth.ok ? 'listRuns succeeded' : (auth.code ?? 'the authenticated call failed'),
+        harness: null,
+        scope: 'cli',
+    };
+}
+export function verifyHarnessKey(status, cliAuth, mcpUrl) {
+    if (!isDefaultEndpoint(mcpUrl))
+        return undefined;
+    // `pointsElsewhere` already fails; a second reason only misleads.
+    if (pointsElsewhere(status.registeredUrl, mcpUrl))
+        return undefined;
+    // The CLI never holds a harness's key, so only its own credential can be verified.
+    return runsOnCliCredential(status) ? cliAuth : undefined;
+}
+// `ok` is backends && key; provider_available re-reads the key through the provider.
+function hermesPluginStatusVerdict(status) {
+    if (status.ok) {
+        return status.provider_available === false
+            ? { status: 'warn', detail: 'plugin configured, but its provider cannot see the key' }
+            : {
+                status: 'pass',
+                detail: `plugin ${status.plugin_version ?? 'installed'}; backends and key configured`,
+            };
+    }
+    if (!status.web_backend_configured) {
+        return {
+            status: 'warn',
+            detail: 'plugin installed but the web backends do not point at tinyfish',
+        };
+    }
+    return {
+        status: 'fail',
+        detail: 'web backends point at tinyfish but no key resolves from ' +
+            'TINYFISH_API_KEY or MCP_TINYFISH_API_KEY',
+    };
+}
+/** An unreadable config cannot prove the backends are ours, so doctor never fails on it. */
+function backendsOurs(home) {
+    try {
+        return hermesWebBackendsOurs(home);
+    }
+    catch {
+        return false;
+    }
+}
+function hermesPluginVerdict(home) {
+    const probe = readHermesPluginStatus(home);
+    if (probe.state === 'not_installed') {
+        // Backends naming an absent provider are broken; never-installed keeps exit 0.
+        return backendsOurs(home)
+            ? {
+                status: 'fail',
+                detail: 'web backends point at tinyfish but the plugin is not installed or not enabled',
+            }
+            : { status: 'warn', detail: 'the TinyFish web plugin is not installed or not enabled' };
+    }
+    if (probe.state === 'unreachable') {
+        return { status: 'warn', detail: '`hermes tinyfish status` did not respond in time' };
+    }
+    if (probe.state === 'unparseable') {
+        return {
+            status: 'warn',
+            detail: '`hermes tinyfish status --json` returned unparseable output',
+        };
+    }
+    return {
+        ...hermesPluginStatusVerdict(probe.status),
+        // Machine-supplied, so it is bounded here rather than trusted onward.
+        observedVersion: boundedVersion(probe.status.plugin_version ?? ''),
+    };
+}
+export function checkHermesPlugin(status) {
+    const base = {
+        id: 'hermes-plugin',
+        title: 'Hermes web plugin',
+        harness: 'hermes',
+        scope: 'harness',
+    };
+    if (!status.detected) {
+        return { check: { ...base, status: 'skip', detail: 'harness not installed' } };
+    }
+    if (status.registered !== Registered.Yes) {
+        return { check: { ...base, status: 'skip', detail: 'TinyFish is not registered in Hermes' } };
+    }
+    const home = resolveHermesHome();
+    if (!home) {
+        return {
+            check: { ...base, status: 'warn', detail: "could not determine Hermes' home directory" },
+        };
+    }
+    const { observedVersion, ...verdict } = hermesPluginVerdict(home);
+    return { check: { ...base, ...verdict }, observedVersion };
+}

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

@@ -8,6 +8,12 @@ export interface HarnessSupportCheck {
     optionalPatterns?: RegExp[];
     /** Missing → this install cannot take a stored key; fall back to OAuth. */
     keyAuthPattern?: RegExp;
+    /** Ordered alternative flags in one help output; first match wins. */
+    variants?: string[];
+    /** Matches an alternative we do not know; renames fail loudly. */
+    unknownVariant?: RegExp;
+    /** Defaults to NON_INTERACTIVE_TIMEOUT_MS; raise for a slow cold start. */
+    timeoutMs?: number;
     unavailableMessage: string;
 }
 /** One entry per harness: every per-harness fact, and no behaviour. */
@@ -221,6 +227,9 @@ export declare const HARNESS_SPECS: {
         supportCheck: {
             args: string[];
             patterns: RegExp[];
+            variants: string[];
+            unknownVariant: RegExp;
+            timeoutMs: number;
             unavailableMessage: string;
         };
         signInViaCliLogin: true;

package/dist/lib/harness-spec.js

@@ -33,9 +33,8 @@ const GROK_HTTP_UNAVAILABLE_MESSAGE = 'Could not confirm this Grok installation
 const GROK_SIGN_IN_HINT = 'TinyFish is registered in Grok. Open Grok, run `/mcps`, select tinyfish, and press `i` to ' +
     'sign in.';
 const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = 'Could not confirm this OpenClaw installation supports global skill installation: `openclaw ' +
-    'skills install --help` did not list `--global` and `--acknowledge-clawhub-risk`. Update ' +
-    'OpenClaw and retry, or install manually with `openclaw skills install @tinyfish/tinyfish ' +
-    '--global --acknowledge-clawhub-risk`.' +
+    'skills install --help` did not list `--global`. Update OpenClaw and retry, or install ' +
+    'manually with `openclaw skills install @tinyfish/tinyfish --global`.' +
     SUPPORT_CHECK_DEBUG_HINT;
 const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = 'Could not confirm this OpenCode installation supports one-command MCP setup: `opencode mcp ' +
     'add --help` did not list `--url`. Update OpenCode and retry, or add TinyFish manually with ' +
@@ -202,7 +201,12 @@ export const HARNESS_SPECS = {
         reloadAction: 'restart it',
         supportCheck: {
             args: ['skills', 'install', '--help'],
-            patterns: [/--global(?:\s|$)/, /--acknowledge-clawhub-risk(?:\s|$)/],
+            patterns: [/--global(?:\s|$)/],
+            // Renamed in 2026.8.1; absent before 2026.7, where no trust gate existed.
+            variants: ['--acknowledge-install-policy-warning', '--acknowledge-clawhub-risk'],
+            unknownVariant: /--acknowledge-[a-z-]+/,
+            // 212MB dist; win32 cold starts drove most of the 10s timeouts.
+            timeoutMs: 30_000,
             unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
         },
         signInViaCliLogin: true,

package/dist/lib/skill-install.js

@@ -3,8 +3,8 @@ import spawn from 'cross-spawn';
 import { z } from 'zod';
 import { loadConfig } from './auth.js';
 import { captureStdio, capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from './cli-install.js';
-import { CURSOR_SKILL_TARGET, NATIVE_MCP_CLIENTS, OPENCLAW_SKILL_INSTALL_ARGS, } from './connect-clients.js';
-import { commandNotFound, spawnFailureDetail, spawnStepError, throwIfInterrupted, } from './connect-runtime.js';
+import { CURSOR_SKILL_TARGET, NATIVE_MCP_CLIENTS, OPENCLAW, openclawSkillInstallArgs, } from './connect-clients.js';
+import { ConnectInterruptedError, ConnectStepError, probeSupportVariant, spawnFailureDetail, spawnStepError, throwIfInterrupted, } from './connect-runtime.js';
 import { CLI_AGENT_IDENTITY } from './constants.js';
 import { errLine } from './output.js';
 // Supports Hermes without node:util.styleText, so the installer still runs on Node 20.11.
@@ -128,16 +128,37 @@ export function updateWebSkill({ verbose }) {
         refreshed = reinstallOpenClawSkill(verbose) || refreshed;
     return refreshed;
 }
+/** OpenClaw rejects an unknown ack flag, so never guess. */
+function openclawAckFlag() {
+    try {
+        return { ok: true, flag: probeSupportVariant(OPENCLAW) };
+    }
+    catch (error) {
+        // Ctrl+C during the probe must still abort the upgrade, not skip a step.
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        // A stale context entry must not fail an otherwise successful upgrade.
+        if (error instanceof ConnectStepError) {
+            const detail = error.failureReason === 'harness_not_installed'
+                ? 'OpenClaw is not on PATH.'
+                : error.message;
+            return { ok: false, reason: `${detail} Its TinyFish skill was left unchanged.` };
+        }
+        return {
+            ok: false,
+            reason: "Could not read OpenClaw's skill installer options, so its TinyFish skill was left unchanged.",
+        };
+    }
+}
 function reinstallOpenClawSkill(verbose) {
     if (verbose)
         errLine('Refreshing the TinyFish skill in OpenClaw...');
-    const result = spawn.sync('openclaw', OPENCLAW_SKILL_INSTALL_ARGS, captureStdio(verbose));
-    // OpenClaw may have been removed since connect; a stale context entry must not fail an
-    // upgrade that otherwise succeeded.
-    if (commandNotFound(result.error)) {
-        errLine('OpenClaw is not on PATH, so its TinyFish skill was left unchanged.');
+    const ack = openclawAckFlag();
+    if (!ack.ok) {
+        errLine(ack.reason);
         return false;
     }
+    const result = spawn.sync('openclaw', openclawSkillInstallArgs(ack.flag), captureStdio(verbose));
     if (result.error || result.status !== 0) {
         throwIfInterrupted(result);
         replay(capturedOutput(result));

package/package.json

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