@tiny-fish/cli 0.21.1-next.195 → 0.21.1-next.197

package/README.md

@@ -80,6 +80,9 @@ Brings both halves of an install current: the global `@tiny-fish/cli` package an
 `use-tinyfish` skill. Use this rather than remembering `npm i -g @tiny-fish/cli@latest` and
 `skills update -g` separately.
 
+Successful steps are summarised in one line each. Add `--verbose` to see the full npm and skills
+output; a failing step prints its output either way.
+
 The skill step refreshes only the TinyFish skill, and only for the agents you ran
 `tinyfish connect` against. Other global skills, and agents you never connected, are left alone.
 The refresh overwrites your copy of the skill, including any local edits to it. Restart your

package/dist/commands/connect.js

@@ -144,7 +144,8 @@ function connectedLine(client, signInDeferred) {
 function runPostInstallSteps(client, options, state, telemetry, signInDeferred) {
     try {
         state.stage = "cli_install";
-        installTinyFishCli();
+        // Verbose on purpose: first-run setup must not go silent.
+        installTinyFishCli({ verbose: true });
         telemetry.track("checkpoint", { phase: "cli_installed" });
         state.stage = "skill_install";
         installWebSkill(client);
@@ -207,7 +208,7 @@ export async function connectOpenClaw(options) {
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
         if (options.installCli !== false) {
             state.stage = "cli_install";
-            installTinyFishCli();
+            installTinyFishCli({ verbose: true });
             telemetry.track("checkpoint", { phase: "cli_installed" });
         }
         state.stage = "skill_install";

package/dist/commands/doctor.js

@@ -1,7 +1,7 @@
 import spawn from "cross-spawn";
 import { apiKeyStatus } from "../lib/auth.js";
 import { CLI_VERSION } from "../lib/constants.js";
-import { DOCTOR_COULD_NOT_RUN, DOCTOR_SCHEMA_VERSION, doctorReportSchema, exitCodeFor, renderPretty, } from "../lib/doctor-report.js";
+import { DOCTOR_COULD_NOT_RUN, DOCTOR_SCHEMA_VERSION, doctorReportSchema, exitCodeFor, renderPretty, verdictFor, } from "../lib/doctor-report.js";
 import { ALL_HARNESSES, AuthMode, Registered } from "../lib/harness-detect.js";
 import { detectHumanInitiated } from "../lib/harness.js";
 import { err, errLine, out, outLine } from "../lib/output.js";
@@ -30,6 +30,7 @@ function checkCliVersion() {
         status: "pass",
         detail: `${CLI_VERSION}; the server reports staleness via X-TF-Notice`,
         harness: null,
+        scope: "info",
     };
 }
 async function checkConnectivity(mcpUrl) {
@@ -39,7 +40,9 @@ async function checkConnectivity(mcpUrl) {
         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",
     };
 }
 // Query strings carry the connect attempt id, so they differ on every healthy install.
@@ -60,8 +63,21 @@ function pointsElsewhere(registeredUrl, mcpUrl) {
         return "an unparseable endpoint";
     }
 }
-function keyedVerdict(status, keyAuth) {
+function keyedVerdict(status, keyAuth, cliKeyMissing) {
     if (!keyAuth) {
+        // Its auth is the CLI credential; a warn would exit 0.
+        if (status.usesCliKey) {
+            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 ?? "its key is not readable here";
         return { status: "warn", detail: `registered, but ${because}, so its reach is unproven` };
@@ -88,7 +104,7 @@ function keyedVerdict(status, keyAuth) {
     }
     return { status: "warn", detail: "registered, key could not be verified" };
 }
-function registrationVerdict(status, mcpUrl, keyAuth) {
+function registrationVerdict(status, mcpUrl, keyAuth, cliKeyMissing) {
     if (!status.detected)
         return { status: "skip", detail: "harness not installed" };
     if (status.registered === Registered.Unknown) {
@@ -116,7 +132,7 @@ function registrationVerdict(status, mcpUrl, keyAuth) {
         }
         // Widening past api-key would warn every healthy oauth install.
         if (status.authMode === AuthMode.ApiKey)
-            return keyedVerdict(status, keyAuth);
+            return keyedVerdict(status, keyAuth, cliKeyMissing);
         // 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}` };
@@ -126,12 +142,13 @@ function registrationVerdict(status, mcpUrl, keyAuth) {
         ? { 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) {
+function checkRegistration(status, mcpUrl, keyAuth, cliKeyMissing) {
     return {
         id: "harness-registration",
         title: `${status.harness} registration`,
         harness: status.harness,
-        ...registrationVerdict(status, mcpUrl, keyAuth),
+        scope: "harness",
+        ...registrationVerdict(status, mcpUrl, keyAuth, cliKeyMissing),
     };
 }
 function checkCredential() {
@@ -142,6 +159,7 @@ function checkCredential() {
         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 };
 }
@@ -153,6 +171,7 @@ function checkAuthCall(auth) {
             status: "skip",
             detail: "no credential to test",
             harness: null,
+            scope: "cli",
         };
     }
     return {
@@ -161,6 +180,7 @@ function checkAuthCall(auth) {
         status: auth.ok ? "pass" : "fail",
         detail: auth.ok ? "listRuns succeeded" : (auth.code ?? "the authenticated call failed"),
         harness: null,
+        scope: "cli",
     };
 }
 // `verifyMcpAuth` hits BASE_URL; a sandbox key 401s against prod.
@@ -178,8 +198,8 @@ function verifyHarnessKey(status, cliKey, cliAuth, mcpUrl) {
     // `pointsElsewhere` already fails; a second reason only misleads.
     if (pointsElsewhere(status.registeredUrl, mcpUrl))
         return undefined;
-    // OpenClaw's skill shells this CLI, so its verdict stands in.
-    if (status.harness === "openclaw")
+    // A harness with no key of its own reads the CLI's.
+    if (status.usesCliKey)
         return cliAuth;
     if (!status.apiKey)
         return undefined;
@@ -237,7 +257,7 @@ export async function runDoctor(options) {
     const checks = [
         checkCliVersion(),
         connectivity,
-        ...statuses.map((status, i) => checkRegistration(status, options.mcpUrl, keyAuths[i])),
+        ...statuses.map((status, i) => checkRegistration(status, options.mcpUrl, keyAuths[i], !credential.key)),
         credential.check,
         checkAuthCall(cliAuthResult),
     ];
@@ -252,7 +272,7 @@ export async function runDoctor(options) {
     const body = {
         schema_version: DOCTOR_SCHEMA_VERSION,
         cli_version: CLI_VERSION,
-        ok: exitCodeFor(checks) === 0,
+        ...verdictFor(checks),
         checks,
         harnesses,
         repairs: repairsFor(checks, statuses),

package/dist/commands/upgrade.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 /** Returns the version now installed, so the caller reports exactly what the user was told. */
-export declare function runUpgrade(): string | null;
+export declare function runUpgrade(verbose?: boolean): string | null;
 /** `runUpgrade` plus its outcome telemetry, which must never change what the upgrade does. */
-export declare function runUpgradeCommand(): Promise<void>;
+export declare function runUpgradeCommand(verbose?: boolean): Promise<void>;
 export declare function registerUpgrade(program: Command): void;

package/dist/commands/upgrade.js

@@ -26,13 +26,16 @@ function attempt(label, run) {
     }
 }
 /** Returns the version now installed, so the caller reports exactly what the user was told. */
-export function runUpgrade() {
+export function runUpgrade(verbose = false) {
     errLine("Upgrading TinyFish...");
+    let refreshed = false;
     try {
         // Both steps always run: neither artifact should stay stale because the other failed.
         const failures = [
-            attempt("update the TinyFish CLI", installTinyFishCli),
-            attempt("refresh the TinyFish web skill", updateWebSkill),
+            attempt("update the TinyFish CLI", () => installTinyFishCli({ verbose })),
+            attempt("refresh the TinyFish web skill", () => {
+                refreshed = updateWebSkill({ verbose });
+            }),
         ].filter((failure) => failure !== undefined);
         if (failures.length > 0)
             throw new Error(`tinyfish upgrade failed: ${failures.join("; ")}`);
@@ -45,9 +48,9 @@ export function runUpgrade() {
         return null;
     }
     const version = installedCliVersion();
-    errLine(version
-        ? `TinyFish CLI ${version} is up to date. Restart your agent to pick up the refreshed skill.`
-        : "TinyFish is up to date. Restart your agent to pick up the refreshed skill.");
+    const upToDate = version ? `TinyFish CLI ${version} is up to date.` : "TinyFish is up to date.";
+    // Only a rewritten skill needs an agent restart.
+    errLine(refreshed ? `${upToDate} Restart your agent to pick up the refreshed skill.` : upToDate);
     return version;
 }
 /** The version now on disk. Only the upgrade's own npm call knows what "latest" resolved to. */
@@ -67,7 +70,7 @@ function globalCliVersion() {
     }
 }
 /** `runUpgrade` plus its outcome telemetry, which must never change what the upgrade does. */
-export async function runUpgradeCommand() {
+export async function runUpgradeCommand(verbose = false) {
     // This command is the upgrade, so a trailing "an update is available" would be noise.
     suppressNotice();
     let reported = false;
@@ -90,7 +93,7 @@ export async function runUpgradeCommand() {
     });
     let outcome = "updated";
     try {
-        printedVersion = runUpgrade();
+        printedVersion = runUpgrade(verbose);
         if (process.exitCode === SIGNAL_EXIT_CODES.SIGINT)
             outcome = "interrupted";
     }
@@ -108,7 +111,8 @@ export function registerUpgrade(program) {
     program
         .command("upgrade")
         .description("Update the TinyFish CLI and the use-tinyfish skill to the latest versions")
-        .action(async () => {
-        await runUpgradeCommand();
+        .option("--verbose", "Print the full npm and skills output instead of only on failure")
+        .action(async (options) => {
+        await runUpgradeCommand(Boolean(options.verbose));
     });
 }

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

@@ -3,7 +3,11 @@ import { type AgentClient } from "./connect-runtime.js";
 export declare const SKILL_INSTALL_TIMEOUT_MS = 120000;
 export declare const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
 export declare const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
-export declare function installTinyFishCli(): void;
+/** Quiet captures subprocess output and replays it only on failure. */
+export type InstallOptions = {
+    verbose: boolean;
+};
+export declare function installTinyFishCli({ verbose }: InstallOptions): void;
 export declare function installWebSkill(client: NativeMcpClient): void;
 /**
  * Refresh the skill we installed, for the harnesses we installed it in.
@@ -12,6 +16,8 @@ export declare function installWebSkill(client: NativeMcpClient): void;
  * only in prose, it repairs a copy whose lock entry lost its hash, and it cannot spread the
  * skill to agents the user never connected (`update` re-adds with no --agent, which targets
  * every agent on the machine).
+ *
+ * Returns whether a skill was actually rewritten.
  */
-export declare function updateWebSkill(): void;
+export declare function updateWebSkill({ verbose }: InstallOptions): boolean;
 export declare function ensureCliAuthenticated(source: AgentClient, apiKey?: string): void;

package/dist/lib/connect-install.js

@@ -14,17 +14,37 @@ export const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI a
 const SKILLS_CLI_PACKAGE = "skills@1.5.15";
 const TINYFISH_WEB_SKILL_SOURCE = "tinyfish-io/tinyfish-cookbook";
 const TINYFISH_WEB_SKILL = "use-tinyfish";
-export function installTinyFishCli() {
-    errLine("Installing the TinyFish CLI...");
+// spawnSync caps piped output at 1 MiB by default.
+const STEP_MAX_BUFFER = 10 * 1024 * 1024;
+function captureStdio(verbose) {
+    return verbose
+        ? { stdio: "inherit", timeout: SKILL_INSTALL_TIMEOUT_MS }
+        : { encoding: "utf8", maxBuffer: STEP_MAX_BUFFER, timeout: SKILL_INSTALL_TIMEOUT_MS };
+}
+/** Inherited stdio leaves these null; only piped runs yield text. */
+function capturedOutput(result) {
+    return `${asText(result.stdout)}${asText(result.stderr)}`;
+}
+function asText(stream) {
+    return typeof stream === "string" ? stream : "";
+}
+/** A verbose run captured nothing, so this is a no-op. */
+function replay(output) {
+    if (output.trim())
+        errLine(output.trimEnd());
+}
+export function installTinyFishCli({ verbose }) {
+    if (verbose)
+        errLine("Installing the TinyFish CLI...");
     // Without the prefix, a curl install upgrades npm's global tree and never the PATH binary.
     const root = installRoot();
     const prefixArgs = root ? ["--prefix", root.prefix] : [];
-    const result = spawn.sync("npm", ["install", "--global", ...prefixArgs, TINYFISH_CLI_INSTALL_SPEC], {
-        stdio: "inherit",
-        timeout: SKILL_INSTALL_TIMEOUT_MS,
-    });
+    const result = spawn.sync("npm", ["install", "--global", ...prefixArgs, TINYFISH_CLI_INSTALL_SPEC], captureStdio(verbose));
     if (result.error || result.status !== 0) {
-        throw spawnStepError("Could not install the TinyFish CLI", result);
+        // Built first: it runs the interrupt check, and abandonment must not replay.
+        const error = spawnStepError("Could not install the TinyFish CLI", result);
+        replay(capturedOutput(result));
+        throw error;
     }
 }
 /** `skills add` is an unconditional overwrite, so it doubles as the refresh path. */
@@ -53,6 +73,8 @@ function skillSpawnEnv() {
 // Safe to match on because SKILLS_CLI_PACKAGE is pinned.
 const SKILL_UPDATE_FAILURE_PATTERN = /Failed to (?:update|check|fetch)/;
 const SKILL_NOT_INSTALLED_PATTERN = /No installed skills found matching/;
+// Nothing was rewritten, so nothing needs an agent restart.
+const SKILL_ALREADY_CURRENT_PATTERN = /All global skills are up to date/;
 // A lock entry with no recorded hash is untrackable, so `skills` reports it as skipped rather
 // than failed. Left undetected that reads as "up to date" while nothing was refreshed.
 const SKILL_UNCHECKABLE_PATTERN = /cannot be checked automatically/;
@@ -65,6 +87,7 @@ export function installWebSkill(client) {
     const result = spawn.sync("npx", skillAddArgs([client.skillAgent]), {
         encoding: "utf8",
         env: skillSpawnEnv(),
+        maxBuffer: STEP_MAX_BUFFER,
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
     const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
@@ -81,8 +104,10 @@ export function installWebSkill(client) {
  * only in prose, it repairs a copy whose lock entry lost its hash, and it cannot spread the
  * skill to agents the user never connected (`update` re-adds with no --agent, which targets
  * every agent on the machine).
+ *
+ * Returns whether a skill was actually rewritten.
  */
-export function updateWebSkill() {
+export function updateWebSkill({ verbose }) {
     // One entry per `tinyfish connect <client>`, persisted by PF-3169.
     const connected = loadConfig().connect ?? {};
     const skillAgents = NATIVE_MCP_CLIENTS
@@ -90,71 +115,82 @@ export function updateWebSkill() {
         .map((client) => client.skillAgent);
     const hasOpenClaw = Boolean(connected["openclaw"]);
     // Installs predating PF-3169 recorded nothing; ask `skills` to refresh what it tracks.
-    if (skillAgents.length === 0 && !hasOpenClaw) {
-        refreshWebSkillByHash();
-        return;
+    if (skillAgents.length === 0 && !hasOpenClaw)
+        return refreshWebSkillByHash(verbose);
+    let refreshed = false;
+    if (skillAgents.length > 0) {
+        reinstallWebSkill(skillAgents, verbose);
+        refreshed = true;
     }
-    if (skillAgents.length > 0)
-        reinstallWebSkill(skillAgents);
     // OpenClaw keeps its skill under its own CLI, so it needs its own refresh.
     if (hasOpenClaw)
-        reinstallOpenClawSkill();
+        refreshed = reinstallOpenClawSkill(verbose) || refreshed;
+    return refreshed;
 }
-function reinstallOpenClawSkill() {
-    errLine("Refreshing the TinyFish skill in OpenClaw...");
-    const result = spawn.sync("openclaw", OPENCLAW_SKILL_INSTALL_ARGS, {
-        stdio: "inherit",
-        timeout: SKILL_INSTALL_TIMEOUT_MS,
-    });
+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.");
-        return;
+        return false;
     }
     if (result.error || result.status !== 0) {
         throwIfInterrupted(result);
+        replay(capturedOutput(result));
         throw new Error("Could not refresh the TinyFish skill in OpenClaw", { cause: result.error });
     }
+    return true;
 }
-function reinstallWebSkill(skillAgents) {
-    errLine(`Refreshing the TinyFish web skill for ${skillAgents.join(", ")}...`);
+function reinstallWebSkill(skillAgents, verbose) {
+    if (verbose)
+        errLine(`Refreshing the TinyFish web skill for ${skillAgents.join(", ")}...`);
     const result = spawn.sync("npx", skillAddArgs(skillAgents), {
         encoding: "utf8",
         env: skillSpawnEnv(),
+        maxBuffer: STEP_MAX_BUFFER,
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    if (output.trim())
-        errLine(output.trimEnd());
-    if (result.error || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output)) {
+    const output = capturedOutput(result);
+    const failed = Boolean(result.error) || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output);
+    if (failed)
         throwIfInterrupted(result);
+    if (verbose || failed)
+        replay(output);
+    if (failed)
         throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
-    }
 }
 /** Fallback when no harness is recorded: ask `skills` to refresh whatever it tracks. */
-function refreshWebSkillByHash() {
-    errLine("Refreshing the TinyFish web skill...");
+function refreshWebSkillByHash(verbose) {
+    if (verbose)
+        errLine("Refreshing the TinyFish web skill...");
     const result = spawn.sync("npx", ["-y", SKILLS_CLI_PACKAGE, "update", TINYFISH_WEB_SKILL, "--global", "--yes"], {
         encoding: "utf8",
         env: skillSpawnEnv(),
+        maxBuffer: STEP_MAX_BUFFER,
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
-    // Piped rather than inherited so the output can be inspected; echoed back for the user.
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    if (output.trim())
-        errLine(output.trimEnd());
-    if (result.error || result.status !== 0 || SKILL_UPDATE_FAILURE_PATTERN.test(output)) {
+    // Piped so prose-only failures can be matched; skills exits 0 anyway.
+    const output = capturedOutput(result);
+    const unchecked = SKILL_UNCHECKABLE_PATTERN.test(output);
+    const failed = Boolean(result.error) || result.status !== 0 || SKILL_UPDATE_FAILURE_PATTERN.test(output);
+    if (failed)
         throwIfInterrupted(result);
+    if (verbose || failed || unchecked)
+        replay(output);
+    if (failed)
         throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
-    }
-    if (SKILL_UNCHECKABLE_PATTERN.test(output)) {
+    if (unchecked) {
         errLine("Run `tinyfish connect <client>` to reinstall the skill and restore update tracking.");
         throw new Error("The TinyFish web skill cannot be checked for updates");
     }
     if (SKILL_NOT_INSTALLED_PATTERN.test(output)) {
         errLine("No use-tinyfish skill installed. Run `tinyfish connect <client>` to add it.");
+        return false;
     }
+    return !SKILL_ALREADY_CURRENT_PATTERN.test(output);
 }
 export function ensureCliAuthenticated(source, apiKey) {
     const envKey = apiKey ?? process.env["TINYFISH_API_KEY"];

package/dist/lib/connect-runtime.js

@@ -33,10 +33,13 @@ export class ConnectStepError extends Error {
 }
 class PrerequisiteError extends ConnectStepError {
 }
+// A maxBuffer overflow is also killed with SIGTERM, and is a failure too.
+const NOT_INTERRUPTIONS = new Set(["ETIMEDOUT", "ENOBUFS"]);
 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.
-    if (result.error?.code === "ETIMEDOUT")
+    const code = result.error?.code;
+    if (code && NOT_INTERRUPTIONS.has(code))
         return;
     if (result.signal === "SIGINT" || result.signal === "SIGTERM") {
         throw new ConnectInterruptedError("Setup interrupted");

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

@@ -1,13 +1,18 @@
 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 = 2;
+export declare const DOCTOR_SCHEMA_VERSION = 3;
 declare const checkStatusSchema: z.ZodEnum<{
     pass: "pass";
     fail: "fail";
     warn: "warn";
     skip: "skip";
 }>;
+declare const checkScopeSchema: z.ZodEnum<{
+    cli: "cli";
+    harness: "harness";
+    info: "info";
+}>;
 declare const doctorCheckSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -26,6 +31,11 @@ declare const doctorCheckSchema: z.ZodObject<{
         opencode: "opencode";
         "claude-code": "claude-code";
     }>>;
+    scope: z.ZodEnum<{
+        cli: "cli";
+        harness: "harness";
+        info: "info";
+    }>;
 }, z.core.$strip>;
 declare const doctorHarnessSchema: z.ZodObject<{
     harness: z.ZodEnum<{
@@ -61,7 +71,8 @@ declare const doctorRepairSchema: z.ZodObject<{
 export declare const doctorReportSchema: z.ZodObject<{
     schema_version: z.ZodInt;
     cli_version: z.ZodString;
-    ok: z.ZodBoolean;
+    ok_harnesses: z.ZodBoolean;
+    ok_cli: z.ZodBoolean;
     checks: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
@@ -80,6 +91,11 @@ export declare const doctorReportSchema: z.ZodObject<{
             opencode: "opencode";
             "claude-code": "claude-code";
         }>>;
+        scope: z.ZodEnum<{
+            cli: "cli";
+            harness: "harness";
+            info: "info";
+        }>;
     }, z.core.$strip>>;
     harnesses: z.ZodArray<z.ZodObject<{
         harness: z.ZodEnum<{
@@ -114,6 +130,7 @@ export declare const doctorReportSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CheckStatus = z.infer<typeof checkStatusSchema>;
+export type CheckScope = z.infer<typeof checkScopeSchema>;
 export type DoctorCheck = z.infer<typeof doctorCheckSchema>;
 export type DoctorHarness = z.infer<typeof doctorHarnessSchema>;
 export type DoctorRepair = z.infer<typeof doctorRepairSchema>;
@@ -121,6 +138,11 @@ export type DoctorReport = z.infer<typeof doctorReportSchema>;
 /** Doctor itself broke, which is a different claim from "your setup is broken". */
 export declare const DOCTOR_COULD_NOT_RUN = 2;
 /** Skips never fail the run; a skip means not applicable, not broken. */
+export declare function verdictFor(checks: DoctorCheck[]): {
+    ok_harnesses: boolean;
+    ok_cli: boolean;
+};
+/** Harness scope only: the caller asked about its agent, not us. */
 export declare function exitCodeFor(checks: DoctorCheck[]): 0 | 1;
 export declare function renderPretty(report: DoctorReport): string;
 export {};

package/dist/lib/doctor-report.js

@@ -1,15 +1,18 @@
 import { z } from "zod";
 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 = 2;
+export const DOCTOR_SCHEMA_VERSION = 3;
 const checkStatusSchema = z.enum(["pass", "fail", "warn", "skip"]);
 const harnessSchema = z.enum(ALL_HARNESSES);
+// Not derived from `harness`: connectivity is harness-null yet harness-scoped.
+const checkScopeSchema = z.enum(["harness", "cli", "info"]);
 const doctorCheckSchema = z.object({
     id: z.string(),
     title: z.string(),
     status: checkStatusSchema,
     detail: z.string(),
     harness: harnessSchema.nullable(),
+    scope: checkScopeSchema,
 });
 const doctorHarnessSchema = z.object({
     harness: harnessSchema,
@@ -27,27 +30,54 @@ const doctorRepairSchema = z.object({
     command: z.string(),
     unattended_safe: z.boolean(),
 });
+function hasFailure(checks, scope) {
+    return checks.some((check) => check.scope === scope && check.status === "fail");
+}
+// One `ok` could not answer both questions, and answered neither.
 export const doctorReportSchema = z
     .object({
     // Not `z.literal`: a consumer must be able to read a future version and say so.
     schema_version: z.int().positive(),
     cli_version: z.string(),
-    ok: z.boolean(),
+    ok_harnesses: z.boolean(),
+    ok_cli: z.boolean(),
     checks: z.array(doctorCheckSchema),
     harnesses: z.array(doctorHarnessSchema),
     repairs: z.array(doctorRepairSchema),
 })
-    // A report that says ok while a check failed is worse than no report.
-    .refine((report) => !report.ok || report.checks.every((check) => check.status !== "fail"), {
-    message: "ok cannot be true while a check has failed",
-    path: ["ok"],
+    // Claiming ok while that scope failed is worse than no report.
+    .refine((report) => !report.ok_harnesses || !hasFailure(report.checks, "harness"), {
+    message: "ok_harnesses cannot be true while a harness check has failed",
+    path: ["ok_harnesses"],
+})
+    .refine((report) => !report.ok_cli || !hasFailure(report.checks, "cli"), {
+    message: "ok_cli cannot be true while a CLI check has failed",
+    path: ["ok_cli"],
 });
 const GLYPHS = { pass: "✓", fail: "✗", warn: "⚠", skip: "…" };
 /** Doctor itself broke, which is a different claim from "your setup is broken". */
 export const DOCTOR_COULD_NOT_RUN = 2;
 /** Skips never fail the run; a skip means not applicable, not broken. */
+export function verdictFor(checks) {
+    return { ok_harnesses: !hasFailure(checks, "harness"), ok_cli: !hasFailure(checks, "cli") };
+}
+/** Harness scope only: the caller asked about its agent, not us. */
 export function exitCodeFor(checks) {
-    return checks.some((check) => check.status === "fail") ? 1 : 0;
+    return verdictFor(checks).ok_harnesses ? 0 : 1;
+}
+// A red line above exit 0 reads as a contradiction.
+function footnotes(report) {
+    const notes = [];
+    // Alongside exit 1 this is noise; something did fail.
+    if (hasFailure(report.checks, "cli") && report.ok_harnesses) {
+        notes.push("The CLI's own credential is broken; that does not affect the exit code.");
+    }
+    // Per-harness rows, not the scope: connectivity is harness-scoped and never skips.
+    const harnessChecks = report.checks.filter((c) => c.harness !== null);
+    if (harnessChecks.length > 0 && harnessChecks.every((c) => c.status === "skip")) {
+        notes.push("No harness was checked here, so a green harness verdict proves nothing.");
+    }
+    return notes;
 }
 export function renderPretty(report) {
     const lines = report.checks.map((c) => `${GLYPHS[c.status]} ${c.title}${c.detail ? ` — ${c.detail}` : ""}`);
@@ -56,5 +86,8 @@ export function renderPretty(report) {
         for (const repair of report.repairs)
             lines.push(`  ${repair.command}`);
     }
+    const notes = footnotes(report);
+    if (notes.length > 0)
+        lines.push("", ...notes);
     return lines.join("\n");
 }

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

@@ -11,6 +11,8 @@ export interface RegistrationStatus {
     apiKey?: string;
     /** From the environment, not the config, so a 401 is ambiguous. */
     keyIsIndirect?: boolean;
+    /** Holds no key; reads the CLI's at runtime. */
+    usesCliKey?: boolean;
     connected?: boolean;
     /** Why a keyed registration's key could not be read; not `reason`. */
     keyReason?: string;

package/dist/lib/registration-detect.js

@@ -324,7 +324,7 @@ function probeOpenClaw() {
     }
     // A bare substring also matched a skill merely named `not-tinyfish-thing`.
     return entries.some((name) => SKILL_DIR_IS_TINYFISH.test(name))
-        ? { registered: Registered.Yes, authMode: AuthMode.ApiKey }
+        ? { registered: Registered.Yes, authMode: AuthMode.ApiKey, usesCliKey: true }
         : { registered: Registered.No, authMode: AuthMode.Unknown };
 }
 // `opencode mcp list` prints no headers, so a key-authed registration is indistinguishable.

package/package.json

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