@tiny-fish/cli 0.39.1-next.309 → 0.40.0

package/dist/lib/connect-all.js

@@ -7,7 +7,6 @@ import { installTinyFishCli, } from './cli-install.js';
 import { authGate, mapConnectError, OAUTH_SIGN_IN_TIMEOUT_MS } from './connect-all-auth.js';
 import { actionable, computeExitCode, reloadHint, renderSummary } from './connect-all-summary.js';
 import { planText, uninstallHarness, uninstallPlanText } from './connect-all-uninstall.js';
-import { NATIVE_BY_HARNESS } from './connect-clients.js';
 import { createStdinPrompt, runCliFallback } from './connect-fallback.js';
 import { gateApiKey } from './connect-preflight.js';
 import { ConnectInterruptedError } from './connect-runtime.js';
@@ -19,21 +18,6 @@ import { errLine, outLine, setErrIndent } from './output.js';
 import { sendSetupCompleted, sendSetupStarted, } from './setup-telemetry.js';
 import { verifyMcpAuth, verifyMcpHealth } from './verify.js';
 const STEP_INDENT = '  ';
-// Derived: a native add carries the key, or the CLI holds it itself.
-const KEY_AUTH_CAPABLE = new Set(ALL_HARNESSES.filter((harness) => !!NATIVE_BY_HARNESS.get(harness)?.keyAuth || harnessSpec(harness).keyHeldByCli));
-async function runHarnessConnect(harness, opts, extras) {
-    return connectHarness(harness, {
-        apiKey: opts.apiKey,
-        mcpUrl: opts.mcpUrl,
-        launch: false,
-        keyAuthOnly: extras.keyAuthOnly,
-        authTimeoutMs: extras.authTimeoutMs,
-        hoistedCliInstall: extras.hoistedCliInstall,
-        onPostInstallFailed: extras.onPostInstallFailed,
-        verbose: opts.verbose,
-        deferOutro: extras.deferOutro,
-    });
-}
 /** Undefined means Ctrl+C: the caller stops the whole run. */
 function runHoistedCliInstall(verbose) {
     const startedAt = Date.now();
@@ -90,8 +74,8 @@ async function processHarness(detection, opts, prompt, oauthBudget, hoistedCliIn
         return settled;
     const isTTY = detectHumanInitiated();
     const apiKey = validatedApiKey(opts.apiKey);
-    // A key only leaves the own-OAuth set where the harness can actually carry one.
-    const keyed = !!apiKey && KEY_AUTH_CAPABLE.has(harness);
+    // All harnesses carry a key; one that cannot fails harness_too_old.
+    const keyed = !!apiKey;
     const fixCommand = `tinyfish connect ${harness}`;
     const gate = await authGate(base, oauthBudget, fixCommand, { prompt, isTTY, keyed });
     if (gate.result)
@@ -103,7 +87,11 @@ async function processHarness(detection, opts, prompt, oauthBudget, hoistedCliIn
     let postInstallFailed = false;
     try {
         // A keyed install too old for key auth fails, no browser.
-        authMode = await runHarnessConnect(harness, opts, {
+        authMode = await connectHarness(harness, {
+            apiKey: opts.apiKey,
+            mcpUrl: opts.mcpUrl,
+            launch: false,
+            verbose: opts.verbose,
             keyAuthOnly: keyed && !isTTY,
             authTimeoutMs: headlessAuth ? OAUTH_SIGN_IN_TIMEOUT_MS : undefined,
             hoistedCliInstall,
@@ -139,13 +127,19 @@ function noWorkOutcome(d, uninstall) {
         return 'not_detected';
     if (!uninstall && isStaleConfig(d))
         return 'stale_config';
+    if (!uninstall && needsFirstRun(d))
+        return 'needs_first_run';
     return undefined;
 }
+/** The harness has never created its dir, so connecting would build one it does not own. */
+export function needsFirstRun(detection) {
+    return detection.detected && !detection.configDirExists;
+}
 /** A config-writing connect needs no binary; every other harness spawns one. */
 function isStaleConfig(detection) {
     const spec = harnessSpec(detection.harness);
-    // Cursor's IDE reads mcp.json binary-less; omp's path needs the binary.
-    const binaryless = spec.cliWritesConfig && !spec.configPathFromBinary;
+    // Cursor's IDE reads mcp.json binary-less; omp and pi have no second reader.
+    const binaryless = spec.cliWritesConfig && spec.readableWithoutBinary;
     return detection.detected && !detection.binaryOnPath && !binaryless;
 }
 async function resolvePick(detections, opts, prompt) {
@@ -153,7 +147,7 @@ async function resolvePick(detections, opts, prompt) {
     let mode = 'all';
     // Before willAttempt/cliNeeded: a cursor-only pick must not hoist the CLI.
     // A stale config dir has no binary to connect, so never offer it as a choice.
-    const offerable = detections.filter((d) => d.detected && !isStaleConfig(d));
+    const offerable = detections.filter((d) => d.detected && !isStaleConfig(d) && !needsFirstRun(d));
     if (opts.pick && offerable.length > 0) {
         const connected = new Set(Object.keys(loadConfig().connect ?? {}));
         const pick = await pickHarnesses(offerable, connected, { prompt });
@@ -248,13 +242,14 @@ async function connectLoop(detections, opts, deselected, io) {
         if (results.some((r) => r.harness === detection.harness))
             continue;
         const { harness, detected, configPath } = detection;
-        const staleConfig = isStaleConfig(detection);
+        // One source of truth with `stepped`, or a skipped harness lands on the wrong row.
+        const noWork = noWorkOutcome(detection, opts.uninstall);
         results.push({
             harness,
             detected,
             configPath,
             installed: false,
-            outcome: staleConfig ? 'stale_config' : detected ? 'not_reached' : 'not_detected',
+            outcome: noWork ?? 'not_reached',
             fixCommand: `tinyfish connect ${detection.harness}`,
         });
     }
@@ -337,10 +332,6 @@ export async function runConnectAll(opts) {
     const prompt = isTTY ? createStdinPrompt() : undefined;
     const detections = detectInstalledHarnesses();
     const gateKey = validatedApiKey(opts.apiKey);
-    // Keyed installs first: working tools land before sign-ins can block.
-    if (gateKey) {
-        detections.sort((a, b) => Number(KEY_AUTH_CAPABLE.has(b.harness)) - Number(KEY_AUTH_CAPABLE.has(a.harness)));
-    }
     const pick = await resolvePick(detections, opts, prompt);
     if (pick.cancelled) {
         // Before summary and telemetry: an explicit nothing is not a setup.
@@ -349,10 +340,7 @@ export async function runConnectAll(opts) {
     }
     const { deselected, mode } = pick;
     // Mirrors processHarness's gate: headless, only keyless CLI-login harnesses skip.
-    const willAttempt = (harness) => !deselected.has(harness) &&
-        (isTTY ||
-            !harnessSpec(harness).signInViaCliLogin ||
-            (!!gateKey && KEY_AUTH_CAPABLE.has(harness)));
+    const willAttempt = (harness) => !deselected.has(harness) && (isTTY || !harnessSpec(harness).signInViaCliLogin || !!gateKey);
     const hoisted = hoistCliIfNeeded(detections, opts, willAttempt);
     if (hoisted === 'interrupted') {
         errLine('Setup interrupted — run the command again to finish.');
@@ -408,6 +396,7 @@ const LAUNCHERS = [
     { harness: 'cursor', args: [FIRST_TASK_PROMPT] },
     { harness: 'claude-code', args: [FIRST_TASK_PROMPT] },
     { harness: 'omp', args: [FIRST_TASK_PROMPT] },
+    { harness: 'pi', args: [FIRST_TASK_PROMPT] },
 ];
 async function launchFirstTask(results) {
     const candidates = LAUNCHERS.filter((l) => results.some((r) => r.harness === l.harness && r.installed) &&

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

@@ -18,7 +18,9 @@ export declare const CURSOR_SKILL_TARGET: {
     readonly displayName: string;
 };
 /** The harness reads the key from its own store. */
-export interface SeededInstall {
+interface SeededInstall {
+    /** Reused by the plugin step, so a second probe cannot disagree. */
+    home: string;
     /** Pins the add child at the home the key landed in. */
     env: typeof process.env;
     /** Answers prompts `mcp add` still asks once the key is seeded. */
@@ -27,6 +29,8 @@ export interface SeededInstall {
     note: string;
     /** Undoes the seed, carrying the value it replaced. */
     rollback: () => void;
+    /** Writes the entry ourselves; false falls back to the harness command. */
+    register: (mcpUrl: string) => boolean;
     /** `mcp add` exits 0 even having saved nothing; the code lies. */
     confirmRegistered: () => {
         ok: boolean;
@@ -45,8 +49,6 @@ interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent'
         seedKey?: (apiKey: string) => SeededInstall;
     };
     loginArgs?: string[];
-    /** Keyless `mcp add` itself blocks on the browser OAuth. */
-    oauthInAdd?: boolean;
     removals: {
         args: string[];
         label: string;
@@ -59,6 +61,7 @@ interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent'
     extraPostInstall?: (options: {
         apiKey?: string;
         verbose: boolean;
+        seededHome?: string;
     }) => void;
     /** Pin `extraPostInstall` installs, reported on the plugin_installed checkpoint. */
     pluginVersion?: string;
@@ -69,17 +72,16 @@ interface BaseMcpClient extends SupportedCommand, Pick<HarnessSpec, 'skillAgent'
     };
 }
 /** Keyless installs use this argv; the harness signs itself in. */
-export interface OauthCapableMcpClient extends BaseMcpClient {
+interface OauthCapableMcpClient extends BaseMcpClient {
     keyRequired?: false;
     addArgs: (mcpUrl: string) => string[];
 }
 /** No sign-in exists here, so connect refuses a keyless install (Hermes). */
-export interface KeyRequiredMcpClient extends BaseMcpClient {
+interface KeyRequiredMcpClient extends BaseMcpClient {
     keyRequired: true;
     keyAuth: NonNullable<BaseMcpClient['keyAuth']>;
     /** Restoring any of these three would restore the OAuth fallback. */
     addArgs?: never;
-    oauthInAdd?: never;
     loginArgs?: never;
 }
 export type NativeMcpClient = OauthCapableMcpClient | KeyRequiredMcpClient;
@@ -89,7 +91,7 @@ export type NativeMcpClient = OauthCapableMcpClient | KeyRequiredMcpClient;
  * quotes back out. Untested on Windows.
  */
 export declare function openExternalUrl(url: string): ReturnType<typeof spawn.sync>;
-/** `mcp add` exits 0 after saving nothing, or a disabled entry. */
+/** Writes exit 0 having saved nothing, a disabled entry, or a keyless one. */
 export declare function hermesRegistrationEnabled(home: string): {
     ok: boolean;
     detail?: string;
@@ -97,7 +99,7 @@ export declare function hermesRegistrationEnabled(home: string): {
 };
 export declare const NATIVE_MCP_CLIENTS: readonly NativeMcpClient[];
 /** Native descriptor by harness id; Cursor and OpenClaw have none. */
-export declare const NATIVE_BY_HARNESS: Map<"openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "claude-code", NativeMcpClient>;
+export declare const NATIVE_BY_HARNESS: Map<"openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "pi" | "claude-code", NativeMcpClient>;
 export declare const OPENCLAW: SupportedCommand;
 /** "printed" = handed to the user to paste; the walkthrough was never started for them. */
 export type WalkthroughOutcome = 'launched' | 'printed';
@@ -105,4 +107,5 @@ export type WalkthroughOutcome = 'launched' | 'printed';
 type OnWalkthroughDecided = (outcome: WalkthroughOutcome) => void | Promise<void>;
 export declare function launchNativeMcpClient(client: NativeMcpClient, onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
 export declare function launchOmpWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
+export declare function launchPiWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;
 export declare function launchOpenClawWalkthrough(onDecided?: OnWalkthroughDecided): Promise<WalkthroughOutcome>;

package/dist/lib/connect-clients.js

@@ -3,12 +3,12 @@ import { SKILL_INSTALL_TIMEOUT_MS } from './cli-install.js';
 import { detectHumanInitiated } from './harness.js';
 import { harnessConfigPath } from './harness-detect.js';
 import { errLine, sanitizeLine, warnLine } from './output.js';
-import { ConnectStepError, spawnStepError, } from './connect-runtime.js';
+import { ConnectInterruptedError, ConnectStepError, spawnStepError, } from './connect-runtime.js';
 import { TINYFISH_API_KEY_VAR } from './constants.js';
 import { HARNESS_SPECS, NATIVE_HARNESSES, harnessSpec, } from './harness-spec.js';
 import { HERMES_KEY_VAR, captureHermesKeyRestore, hermesEnvPath, resolveHermesHome, writeHermesKey, } from './hermes-env.js';
 import { hermesConfigPath, readHermesEntry } from './hermes-config.js';
-import { HERMES_PLUGIN_VERSION, installHermesPlugin, setHermesWebBackends, } from './hermes-plugin.js';
+import { HERMES_PLUGIN_VERSION, installHermesPlugin, removeHermesMcpEntry, setHermesWebBackends, writeHermesMcpEntry, } from './hermes-plugin.js';
 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.
@@ -100,11 +100,19 @@ function launchHermesWalkthrough() {
     }
     handOverTerminal('hermes', ['--resume', sessionId], 'Hermes');
 }
-/** `mcp add` exits 0 after saving nothing, or a disabled entry. */
+/** Writes exit 0 having saved nothing, a disabled entry, or a keyless one. */
 export function hermesRegistrationEnabled(home) {
     const entry = readHermesEntry(home);
-    if (entry.state === 'enabled')
-        return { ok: true };
+    if (entry.state === 'enabled') {
+        if (entry.usesKeyHeader)
+            return { ok: true };
+        // Exit codes carry no signal, so a corrupt entry can only be caught here.
+        return {
+            ok: false,
+            detail: 'the entry does not read the seeded key',
+            tag: 'hermes_entry_no_key_header',
+        };
+    }
     // Each of these is a different repair, so none of them share wording.
     const detail = {
         disabled: 'the entry was saved disabled',
@@ -117,28 +125,47 @@ export function hermesRegistrationEnabled(home) {
 }
 // A plain Error settles unexpected_error; cli_connect_stage is load-bearing.
 function requireHermesHome() {
-    const home = resolveHermesHome();
-    if (!home) {
-        throw new ConnectStepError("Could not determine Hermes' home directory from `hermes dump`", 'invalid_config', { failureDetail: 'hermes_home_undetermined' });
+    const resolved = resolveHermesHome();
+    if (typeof resolved === 'string')
+        return resolved;
+    throw new ConnectStepError("Could not determine Hermes' home directory from `hermes dump`", 'invalid_config', { failureDetail: `hermes_home_undetermined_${resolved.reason}` });
+}
+/** Our own write, so `mcp add`'s install-time probe never disables the entry. */
+function registerHermesEntry(home, mcpUrl) {
+    try {
+        writeHermesMcpEntry(home, mcpUrl);
+    }
+    catch (error) {
+        // A Ctrl+C must abandon the attempt, not fall through to `mcp add`.
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        return false;
     }
-    return home;
+    return hermesRegistrationEnabled(home).ok;
 }
 function seedHermesKey(apiKey) {
     const home = requireHermesHome();
     const restore = captureHermesKeyRestore(home);
     writeHermesKey(home, apiKey);
+    // Set before the write, which can land even when it later throws.
+    let wroteEntry = false;
     return {
+        home,
         // Pins HERMES_HOME so a sticky profile can't shadow this key.
         env: { ...process.env, HERMES_HOME: home },
         // Three: a failed `mcp remove` adds an extra Overwrite prompt.
         stdinInput: 'y\ny\ny\n',
         note: `Wrote ${HERMES_KEY_VAR} to ${hermesEnvPath(home)} — Hermes reads the key from there.`,
-        rollback: () => rollbackHermesKey(home, restore),
+        rollback: () => rollbackHermesKey(home, restore, wroteEntry),
+        register: (mcpUrl) => {
+            wroteEntry = true;
+            return registerHermesEntry(home, mcpUrl);
+        },
         confirmRegistered: () => hermesRegistrationEnabled(home),
     };
 }
 // A failed re-run must not cost a working key.
-function rollbackHermesKey(home, restore) {
+function rollbackHermesKey(home, restore, wroteEntry) {
     try {
         // The next `hermes mcp add` silently reuses whatever value survives here.
         restore();
@@ -146,13 +173,23 @@ function rollbackHermesKey(home, restore) {
     catch {
         warnLine(`Could not restore ${HERMES_KEY_VAR} in ${hermesEnvPath(home)}; check it by hand.`);
     }
+    if (!wroteEntry)
+        return;
+    try {
+        // Left behind, the row stays enabled with no key behind it.
+        removeHermesMcpEntry(home);
+    }
+    catch {
+        warnLine(`Could not remove the tinyfish entry in ${hermesConfigPath(home)}; check it by hand.`);
+    }
 }
 // Hermes is keyRequired; a missing key here is a resolution bug.
-function installHermesWebPlugin({ apiKey, verbose }) {
+function installHermesWebPlugin({ apiKey, verbose, seededHome, }) {
     if (!apiKey) {
         throw new ConnectStepError('No TinyFish API key was available to install the Hermes web plugin', 'invalid_config');
     }
-    const home = requireHermesHome();
+    // Reuses the seed's home: a second `hermes dump` can disagree with the first.
+    const home = seededHome ?? requireHermesHome();
     installHermesPlugin(home, apiKey, { verbose });
     setHermesWebBackends(home);
 }
@@ -295,6 +332,9 @@ export async function launchNativeMcpClient(client, onDecided) {
 export function launchOmpWalkthrough(onDecided) {
     return deliverWalkthrough('omp', 'omp', DEFAULT_ONBOARDING_PROMPT, () => handOverTerminal('omp', [DEFAULT_ONBOARDING_PROMPT], 'omp'), onDecided);
 }
+export function launchPiWalkthrough(onDecided) {
+    return deliverWalkthrough('Pi', 'pi', DEFAULT_ONBOARDING_PROMPT, () => handOverTerminal('pi', [DEFAULT_ONBOARDING_PROMPT], 'Pi'), onDecided);
+}
 export function launchOpenClawWalkthrough(onDecided) {
     return deliverWalkthrough('OpenClaw', 'openclaw', OPENCLAW_ONBOARDING_PROMPT, () => handOverTerminal('openclaw', ['chat', '--message', OPENCLAW_ONBOARDING_PROMPT], 'OpenClaw'), onDecided);
 }

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

@@ -4,7 +4,7 @@ export declare const SEARCH_RETRY = "tinyfish search query --pretty -- \"<your q
 export declare const DEFAULT_VERIFICATION_QUERY = "today's top Hacker News story";
 export declare const MALFORMED_ENV_KEY_MESSAGE = "TINYFISH_API_KEY is set but malformed; it will override any stored key. Fix or unset it, then re-run.";
 export declare const MALFORMED_STORED_KEY_MESSAGE = "The stored TinyFish API key is malformed. Run: tinyfish auth login";
-export interface CliFallbackHooks {
+interface CliFallbackHooks {
     onStepStart?: (stage: ConnectFailureStage) => void;
     onStepDone?: (phase: ConnectCheckpoint) => void;
 }
@@ -22,3 +22,4 @@ export interface CliFallbackOptions {
 export declare function createStdinPrompt(): Prompt;
 /** Steps print retry lines and return outcomes; only interrupts throw. */
 export declare function runCliFallback(opts: CliFallbackOptions): Promise<CliFallbackOutcome>;
+export {};

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

@@ -1,11 +1,11 @@
 import type { Readable } from 'node:stream';
 import { type Harness, type HarnessDetection } from './harness-detect.js';
-export type PickSelection = Harness[] | 'cancel';
+type PickSelection = Harness[] | 'cancel';
 export interface PickResult {
     selection: PickSelection;
     mode: 'pick' | 'pick_numeric';
 }
-export type PickerStdin = Readable & {
+type PickerStdin = Readable & {
     setRawMode?: (raw: boolean) => unknown;
 };
 export interface PickerIo {
@@ -14,3 +14,4 @@ export interface PickerIo {
     prompt?: (question: string) => Promise<string>;
 }
 export declare function pickHarnesses(detections: HarnessDetection[], connectedBefore: ReadonlySet<string>, io?: PickerIo): Promise<PickResult>;
+export {};

package/dist/lib/connect-runtime.js

@@ -49,8 +49,6 @@ export function stageDurationOf(error) {
     const value = error?.stageDurationMs;
     return typeof value === 'number' ? value : undefined;
 }
-class PrerequisiteError extends ConnectStepError {
-}
 /** A bounded sign-in wait elapsed — unfinished, not broken. */
 export class SignInTimeoutError extends ConnectStepError {
     constructor(message, cause) {
@@ -190,7 +188,7 @@ function throwProbeFailure(client, result) {
             `${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) });
+    throw new ConnectStepError(client.supportCheck.unavailableMessage, 'harness_command_unsupported', { cause: result.error, harnessVersion: probeHarnessVersion(client) });
 }
 function supportProbeOutput(client) {
     const result = spawn.sync(client.command, client.supportCheck.args, {
@@ -201,7 +199,7 @@ function supportProbeOutput(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) {
-        throw new PrerequisiteError(`${client.displayName} is not installed or not available on PATH.`, 'harness_not_installed', { cause: result.error });
+        throw new ConnectStepError(`${client.displayName} is not installed or not available on PATH.`, 'harness_not_installed', { cause: result.error });
     }
     if (result.error || result.status !== 0) {
         throwProbeFailure(client, result);
@@ -218,7 +216,7 @@ 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', {
+    throw new ConnectStepError(client.supportCheck.unavailableMessage, 'harness_too_old', {
         harnessVersion: probeHarnessVersion(client),
     });
 }
@@ -235,7 +233,7 @@ function resolveVariant(client, output) {
         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. ` +
+    throw new ConnectStepError(`${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. */

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

@@ -11,6 +11,7 @@ export declare function checkCredential(): {
 };
 export declare function checkAuthCall(auth: VerifyResult | undefined): DoctorCheck;
 export declare function verifyHarnessKey(status: RegistrationStatus, cliAuth: Promise<VerifyResult> | undefined, mcpUrl: string): Promise<VerifyResult> | undefined;
+export declare function checkPiAdapter(status: RegistrationStatus): DoctorCheck;
 export interface HermesPluginResult {
     check: DoctorCheck;
     observedVersion?: string;

package/dist/lib/doctor-checks.js

@@ -4,6 +4,7 @@ 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 { PI_ADAPTER_INSTALL_COMMAND, piMcpAdapterState } from './pi-config.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.
@@ -250,6 +251,40 @@ function hermesPluginVerdict(home) {
         observedVersion: boundedVersion(probe.status.plugin_version ?? ''),
     };
 }
+// Warn, not fail: the TinyFish skill works in pi with no adapter, so nothing is broken.
+export function checkPiAdapter(status) {
+    const base = {
+        id: 'pi-adapter',
+        title: 'Pi MCP adapter',
+        harness: 'pi',
+        scope: 'harness',
+    };
+    if (!status.detected)
+        return { ...base, status: 'skip', detail: 'harness not installed' };
+    if (status.registered !== Registered.Yes) {
+        const why = status.registered === Registered.Unknown
+            ? 'pi registration could not be determined'
+            : 'TinyFish is not registered in pi';
+        return { ...base, status: 'skip', detail: why };
+    }
+    const state = piMcpAdapterState();
+    if (state === 'installed') {
+        return { ...base, status: 'pass', detail: 'installed, so pi reads the tinyfish MCP entry' };
+    }
+    if (state === 'unknown') {
+        return {
+            ...base,
+            status: 'warn',
+            detail: "could not read pi's settings.json, so whether the adapter is installed is unknown",
+        };
+    }
+    return {
+        ...base,
+        status: 'warn',
+        detail: 'not installed, so the tinyfish MCP entry is dormant (the TinyFish skill works without it). ' +
+            `Fix: ${PI_ADAPTER_INSTALL_COMMAND}`,
+    };
+}
 export function checkHermesPlugin(status) {
     const base = {
         id: 'hermes-plugin',
@@ -263,12 +298,12 @@ export function checkHermesPlugin(status) {
     if (status.registered !== Registered.Yes) {
         return { check: { ...base, status: 'skip', detail: 'TinyFish is not registered in Hermes' } };
     }
-    const home = resolveHermesHome();
-    if (!home) {
+    const resolved = resolveHermesHome();
+    if (typeof resolved !== 'string') {
         return {
             check: { ...base, status: 'warn', detail: "could not determine Hermes' home directory" },
         };
     }
-    const { observedVersion, ...verdict } = hermesPluginVerdict(home);
+    const { observedVersion, ...verdict } = hermesPluginVerdict(resolved);
     return { check: { ...base, ...verdict }, observedVersion };
 }

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

@@ -31,6 +31,7 @@ declare const doctorCheckSchema: z.ZodObject<{
         codex: "codex";
         hermes: "hermes";
         opencode: "opencode";
+        pi: "pi";
         "claude-code": "claude-code";
     }>>;
     scope: z.ZodEnum<{
@@ -48,6 +49,7 @@ declare const doctorHarnessSchema: z.ZodObject<{
         codex: "codex";
         hermes: "hermes";
         opencode: "opencode";
+        pi: "pi";
         "claude-code": "claude-code";
     }>;
     detected: z.ZodBoolean;
@@ -74,6 +76,7 @@ declare const doctorRepairSchema: z.ZodObject<{
         codex: "codex";
         hermes: "hermes";
         opencode: "opencode";
+        pi: "pi";
         "claude-code": "claude-code";
     }>>;
     command: z.ZodString;
@@ -102,6 +105,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             codex: "codex";
             hermes: "hermes";
             opencode: "opencode";
+            pi: "pi";
             "claude-code": "claude-code";
         }>>;
         scope: z.ZodEnum<{
@@ -119,6 +123,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             codex: "codex";
             hermes: "hermes";
             opencode: "opencode";
+            pi: "pi";
             "claude-code": "claude-code";
         }>;
         detected: z.ZodBoolean;
@@ -145,6 +150,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             codex: "codex";
             hermes: "hermes";
             opencode: "opencode";
+            pi: "pi";
             "claude-code": "claude-code";
         }>>;
         command: z.ZodString;

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

@@ -23,5 +23,7 @@ export interface HarnessDetection {
     configPath: string;
     /** False with `detected` true means a stale config dir: nothing to run. */
     binaryOnPath: boolean;
+    /** True with no config dir means installed but never launched. */
+    configDirExists: boolean;
 }
 export declare function detectInstalledHarnesses(): HarnessDetection[];

package/dist/lib/harness-detect.js

@@ -3,6 +3,7 @@ import * as os from 'os';
 import * as path from 'path';
 import which from 'which';
 import { ALL_HARNESSES, harnessSpec } from './harness-spec.js';
+import { piAgentDir, piBinaryIsPi } from './pi-config.js';
 export { ALL_HARNESSES };
 export const HARNESS_DISPLAY_NAMES = Object.fromEntries(ALL_HARNESSES.map((harness) => [harness, harnessSpec(harness).displayName]));
 export const RELOAD_ACTION = Object.fromEntries(ALL_HARNESSES.map((harness) => [harness, harnessSpec(harness).reloadAction]));
@@ -31,13 +32,18 @@ export function commandOnPath(command) {
         return false;
     }
 }
+// PI_CODING_AGENT_DIR moves pi's dir; a guessed path would be written unread.
+const CONFIG_PATH_RESOLVERS = { pi: piAgentDir };
 export function harnessConfigPath(harness) {
-    return path.join(os.homedir(), harnessSpec(harness).configDir); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+    const resolved = CONFIG_PATH_RESOLVERS[harness]?.();
+    return resolved ?? path.join(os.homedir(), harnessSpec(harness).configDir); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
 }
 /** For reason strings that name a location; keeps them in sync with the spec. */
 export function harnessDisplayPath(harness) {
     return `~/${harnessSpec(harness).configDir}`;
 }
+// `pi` is a two-letter name an unrelated npm package also claims; confirm before trusting it.
+const BINARY_VERIFIERS = { pi: piBinaryIsPi };
 export function detectInstalledHarnesses() {
     return ALL_HARNESSES.map((harness) => {
         const configPath = harnessConfigPath(harness);
@@ -48,13 +54,15 @@ export function detectInstalledHarnesses() {
         catch {
             configDirExists = false;
         }
-        // Config dir means ran once; PATH means runnable now.
-        const binaryOnPath = commandOnPath(HARNESS_COMMANDS[harness]);
+        // Config dir means ran once; a verified binary means runnable now.
+        const onPath = commandOnPath(HARNESS_COMMANDS[harness]);
+        const binaryOnPath = onPath && (BINARY_VERIFIERS[harness]?.() ?? true);
         return {
             harness,
             detected: configDirExists || binaryOnPath,
             configPath,
             binaryOnPath,
+            configDirExists,
         };
     });
 }