@tpsdev-ai/flair 0.50.0 → 0.51.0

package/README.md

@@ -16,17 +16,28 @@ Runs on a laptop, a VPS, or anywhere Node does. Needs **Node.js 22+**.
 # 1. Install the CLI (no sudo)
 npm install -g @tpsdev-ai/flair
 
-# 2. Bootstrap the instance and register an agent
+# 2. Verify the command is on your PATH
+flair --version
+
+# 3. Bootstrap the instance and register an agent
 flair init --agent mybot
 
-# 3. Write a memory
+# 4. Write a memory
 flair memory add --agent mybot "Harper v5 sandbox blocks node:module but process.dlopen works"
 
-# 4. Find it back by meaning, not by keyword
+# 5. Find it back by meaning, not by keyword
 flair search --agent mybot "native addon loading in sandboxed runtimes"
 ```
 
-Step 4 finds the memory you never keyword-matched:
+If `flair --version` prints `command not found`, your npm global bin directory is not on `PATH`:
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+Re-run `flair --version` to confirm, then continue.
+
+Step 5 finds the memory you never keyword-matched:
 
 ```
   Harper v5 sandbox blocks node:module but process.dlopen works

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.50.0",
-  "commit": "d643b7f8addb9fd033209fad1d405f7c935a7247",
-  "builtAt": "2026-08-25T23:24:38.875Z",
+  "version": "0.51.0",
+  "commit": "92b5d12cc3aafe892e90af657f073ef88b180ba6",
+  "builtAt": "2026-08-30T16:10:24.457Z",
   "builder": "tsc"
 }

package/dist/cli.js

@@ -32,7 +32,8 @@ import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing
 import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snapshot-extract.js";
 import { entityFormatHint, parseEntitiesCsv } from "./lib/entity-vocab-cli.js";
 import { escapeXml, unescapeXml } from "./lib/xml-escape.js";
-import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, renderVerifiedSummary, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
+import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
+import { applyUpgradeHookConsent, catalogIssueDelta, renderCatalogDoctorLines, renderVerifiedSummary, runDoctorChecks, } from "./lib/doctor-run.js";
 // Value-only static import so `--interval`'s advertised default cannot drift
 // from the one the scheduler actually validates against. The module itself is
 // still loaded lazily at call time (the `await import()`s below) for the
@@ -60,14 +61,18 @@ function signBody(body, secretKey) {
     const sig = nacl.sign.detached(message, secretKey);
     return Buffer.from(sig).toString("base64url");
 }
-// Per-record principalId (federation-edge-hardening slice 3a) — INFORMATIONAL
-// only; the receiver (resources/Federation.ts) never treats it as verified
-// identity or uses it in any auth decision. Sourced from the write-time
-// provenance stamp (memory-provenance slice 1, Memory.ts's buildProvenance)
-// when present. `provenance` is persisted as a JSON STRING (not an object),
-// so it must be parsed — a raw `row.provenance?.verified?.agentId` would
-// silently always be undefined. Soul/Agent/Relationship rows never carry a
-// provenance stamp today, so this is a no-op for them.
+// Per-record principalId (federation-edge-hardening slice 3a / flair#1416).
+// Sourced from the write-time provenance stamp (memory-provenance slice 1,
+// Memory.ts's buildProvenance) when present. `provenance` is persisted as
+// a JSON STRING (not an object), so it must be parsed — a raw
+// `row.provenance?.verified?.agentId` would silently always be undefined.
+// Soul/Agent/Relationship rows never carry a provenance stamp today, so
+// this is a no-op for them (those tables are not principal-owning).
+//
+// As of v:2 this value is IN the signed payload. The receiver validates
+// it against data.agentId for Memory (PRINCIPAL_OWNING_TABLES); it is
+// no longer informational-only. Credential.principalId is an unrelated
+// owner field — do not grep that path when changing this one.
 function principalIdFromRow(row) {
     if (typeof row?.provenance !== "string" || row.provenance.length === 0)
         return undefined;
@@ -3002,7 +3007,7 @@ program
     .option("--no-mcp", "Skip MCP client wiring (instance + agent only)")
     .option("--skip-smoke", "Skip the MCP smoke test")
     .option("--skip-claude-md", "Skip appending the Flair bootstrap line to CLAUDE.md (claude-code only)")
-    .option("--skip-hook", "Skip installing the flair-session-start SessionStart hook (claude-code only)")
+    .option("--skip-hook", "Skip installing the flair-session-start SessionStart hook (claude-code and Codex)")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .option("--remote", "When used with --target, init as hub for remote federation")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
@@ -3864,6 +3869,18 @@ program
                     }
                     wiringResults.push({ client: clientId, message: result.message, wired: result.ok });
                     console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
+                    // Codex SessionStart hook (flair#1148 / #1439) — the hook is not
+                    // optional on Codex (no CLAUDE.md alternative). Init is the
+                    // consent to set up the client, same as the Claude Code hook
+                    // applied above. --skip-hook opts out and prints the JSON.
+                    if (clientId === "codex" && result.ok) {
+                        const hookResult = applyOrReportSessionStartHook(homedir(), agentId, !!opts.skipHook, hookSettingsPath(homedir(), "codex"));
+                        console.log(`   ${hookResult.ok ? "✓" : "•"} ${hookResult.message}`);
+                        if (hookResult.hint) {
+                            for (const line of hookResult.hint.split("\n"))
+                                console.log(`   ${line}`);
+                        }
+                    }
                 }
             }
         }
@@ -7030,22 +7047,40 @@ export async function runFederationSyncOnce(opts) {
                 // batch. Closes the hub-relay forgery hole — see
                 // resources/Federation.ts FederationSync.post's verification gate.
                 //
-                // CONTRACT — must match Federation.ts's verification payload
-                // byte-for-byte: keys { v, table, id, data, updatedAt,
-                // originatorInstanceId }. canonicalize() sorts keys, so field ORDER
-                // doesn't matter, but the field SET and values do. `v: 1` versions the
-                // canonical form itself: bump it on BOTH sides together if the signed
-                // field set ever changes, so an old signature fails closed instead of
-                // silently mis-verifying under a new form.
+                // CONTRACT — must match reconstructRecordVerifyBody
+                // (resources/federation-classify.ts) byte-for-byte. canonicalize()
+                // sorts keys, so field ORDER doesn't matter, but the field SET and
+                // values do. `v` versions the canonical form itself: a v:1
+                // signature cannot verify as v:2 (principalId in the field set).
                 //
-                // Additive/backward-compatible: pre-3a receivers don't read
-                // `signature`/`principalId` at all and merge exactly as before.
-                const signature = signBody({ v: 1, table, id: row.id, data: row, updatedAt, originatorInstanceId }, secretKey);
-                const sr = { table, id: row.id, data: row, updatedAt, originatorInstanceId, signature };
-                // Informational only (see principalIdFromRow) — never verified by the
-                // receiver as proof of authorship. Omitted entirely when the row
-                // carries no write-time provenance stamp.
+                // v: 2 puts principalId in the signed payload when the row carries
+                // a provenance stamp, and puts `v` on the wire so Phase 1
+                // receivers (`const v = record.v ?? 1`) don't default these
+                // records back to 1. Soul/Agent/Relationship have no stamp and
+                // omit principalId; Memory without a stamp also omits it (the
+                // receiver then skips Memory as principal_mismatch — absent is
+                // not an accept).
                 const principalId = principalIdFromRow(row);
+                const signedPayload = {
+                    v: 2,
+                    table,
+                    id: row.id,
+                    data: row,
+                    updatedAt,
+                    originatorInstanceId,
+                };
+                if (principalId)
+                    signedPayload.principalId = principalId;
+                const signature = signBody(signedPayload, secretKey);
+                const sr = {
+                    v: 2,
+                    table,
+                    id: row.id,
+                    data: row,
+                    updatedAt,
+                    originatorInstanceId,
+                    signature,
+                };
                 if (principalId)
                     sr.principalId = principalId;
                 const srBytes = JSON.stringify(sr).length;
@@ -10276,6 +10311,7 @@ program
     .option("--project <name>", "Fabric component name for --target", "flair")
     .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
     .option("--yes", "Skip the confirmation prompt for --target")
+    .option("--install-hooks", "Consent to installing missing SessionStart hooks (claude-code / Codex) during upgrade. The hook executes at every session start — upgrade will not write it unprompted. Interactive runs prompt; non-interactive runs state the gap and withhold ✅ unless this flag is passed.")
     .option("--no-fleet-verify", "Skip the automatic post-upgrade fleet convergence sweep for --target (default: sweep runs — see flair#636)")
     // ── flair#878 ─────────────────────────────────────────────────────────────
     // These existed on `flair deploy` but stopped at the upgrade boundary, so
@@ -10941,20 +10977,16 @@ program
     });
     const verdict = decideAfterVerify(verify, previousFlairVersion);
     if (verdict.kind === "ok") {
-        // flair#1022: the verified facts are unchanged and still stated — the
-        // upgrade did land. What changes is the MARKER and the claim around it.
-        // A run that ended up outside its process manager has not fully
-        // succeeded, so it does not get a ✅, and the line names the property
-        // that is wrong rather than only the ones that are right. The choice
-        // lives in renderVerifiedSummary so it is testable without performing an
-        // upgrade — no CI lane runs this darwin path.
-        const summary = renderVerifiedSummary(verify.version, management);
-        for (const line of summary.lines) {
-            if (summary.degraded)
-                console.error(line);
-            else
-                console.log(line);
-        }
+        // flair#1439: the success marker is the doctor runner's verdict, not
+        // a second, narrower notion of "verified". Launchd detach is one
+        // catalog member; the Codex SessionStart hook is another. Adding a
+        // doctor check widens this claim automatically.
+        const run = await doctorRunAfterUpgrade({
+            management,
+            port,
+            installHooksFlag: !!opts.installHooks,
+        });
+        printVerifiedSummary(renderVerifiedSummary(verify.version, run));
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -10966,21 +10998,23 @@ program
     // "print an honest note but roll back anyway" branch that used to sit below
     // is gone — that credentials case can no longer reach the rollback path.)
     if (verdict.kind === "healthy-unverified") {
-        // flair#1022: same rule as the "ok" branch above — the ✅ is withheld
-        // when the run left the instance outside launchd, and the reason is
-        // named. This branch already qualifies the version claim; the process
-        // manager is a second, independent qualification.
-        console.log(detached
-            ? `⚠️  upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}, but NOT under launchd.`
-            : `✅ upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}.`);
+        // Same doctor runner as the "ok" branch — an unverified version must
+        // not restore the unqualified ✅ while a catalog member is failing.
+        const run = await doctorRunAfterUpgrade({
+            management,
+            port,
+            installHooksFlag: !!opts.installHooks,
+        });
+        const versionNote = expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : "";
+        if (run.healthy) {
+            console.log(`✅ upgrade complete: the instance is up and healthy${versionNote}.`);
+        }
+        else {
+            printVerifiedSummary(renderVerifiedSummary(verify.version, run, { authenticated: false }));
+        }
         console.log(`   The version could not be verified — the checker couldn't authenticate to /HealthDetail (${verdict.reason}).`);
         console.log("   The server is confirmed running (public /Health passed); this is a verification gap, not an upgrade failure — nothing was rolled back.");
         console.log("   To enable full post-upgrade verification: set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key.");
-        if (detached) {
-            for (const line of renderDetachedWarning(management, "The instance is NOT running under launchd.")) {
-                console.error(line);
-            }
-        }
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
@@ -11299,6 +11333,83 @@ function resolveInstanceServingPid(dataDir, port) {
         listeningPids,
     });
 }
+/** Agent signing-key ids under `keysDir` — node-scoped federation keys excluded. */
+function collectKeyAgentIds(keysDir) {
+    if (!existsSync(keysDir))
+        return [];
+    try {
+        const keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key"));
+        const { agentKeyIds } = partitionKeyIds(keyFiles.map((f) => f.replace(/\.key$/, "")), keysDir);
+        return agentKeyIds;
+    }
+    catch {
+        return [];
+    }
+}
+async function confirmYes(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((res) => rl.question(question, (a) => { rl.close(); res(a); }));
+    return /^y(es)?$/i.test(answer.trim());
+}
+/**
+ * flair#1439 — run the enumerable doctor catalog after upgrade's instance
+ * probe, and offer a consented SessionStart-hook install when that check
+ * fails. Silent writes are refused: `--install-hooks` or an interactive
+ * yes is the only consent. The consent→write composition lives in
+ * applyUpgradeHookConsent so tests can drive the path that actually
+ * writes (or does not write) the hook file.
+ */
+async function doctorRunAfterUpgrade(args) {
+    const homeDir = homedir();
+    const keysDir = defaultKeysDir();
+    const ctx = {
+        homeDir,
+        cwd: process.cwd(),
+        detectedClientIds: detectClients().filter((c) => c.detected).map((c) => c.id),
+        launchd: args.management,
+        keysDir,
+        keyAgentIds: collectKeyAgentIds(keysDir),
+    };
+    const run = runDoctorChecks(ctx);
+    const apply = (promptAccepted) => applyUpgradeHookConsent({
+        homeDir,
+        ctx,
+        run,
+        installHooksFlag: args.installHooksFlag,
+        interactive: !!process.stdin.isTTY,
+        promptAccepted,
+        port: args.port,
+    });
+    let outcome = apply();
+    if (outcome.consent === "prompt" && outcome.prompt) {
+        console.log("");
+        for (const line of outcome.prompt.preamble)
+            console.log(`  ${line}`);
+        outcome = apply(await confirmYes(outcome.prompt.question));
+    }
+    if (outcome.consent === "install") {
+        for (const w of outcome.writes) {
+            console.log(`   ${w.ok ? "✓" : "•"} ${w.message}`);
+        }
+    }
+    if (outcome.consent === "skip-noninteractive") {
+        for (const line of outcome.messages) {
+            console.error(`   ${line}`);
+        }
+    }
+    return outcome.run;
+}
+function printVerifiedSummary(summary) {
+    for (const line of summary.lines) {
+        if (summary.degraded)
+            console.error(line);
+        else
+            console.log(line);
+    }
+}
 /**
  * Observe whether `dataDir`'s instance is running under launchd right now.
  *
@@ -13057,6 +13168,21 @@ program
         return /^y(es)?$/i.test(answer.trim());
     }
     const detectedClients = detectClients().filter((c) => c.detected);
+    // flair#1439 — install-health (MCP, FLAIR_URL, CLAUDE.md, SessionStart
+    // hook, verified-read plan, keys classification, launchd) is the same
+    // catalog upgrade asserts. Adding a check to DOCTOR_CHECK_IDS widens
+    // both. Extra doctor UX (pi, --fix, execution probe, continuity,
+    // agent registration) stays below and does not redefine those checks.
+    const doctorCtx = {
+        homeDir: homedir(),
+        cwd: process.cwd(),
+        detectedClientIds: detectedClients.map((c) => c.id),
+        launchd: observeLaunchdManagement(defaultDataDir(), effectivePort),
+        keysDir,
+        keyAgentIds,
+        agentFlag: typeof opts.agent === "string" ? opts.agent : undefined,
+    };
+    const catalogBefore = runDoctorChecks(doctorCtx);
     if (detectedClients.length === 0) {
         console.log(`  ${render.icons.info} No MCP client detected — skipping client-integration checks`);
     }
@@ -13291,7 +13417,6 @@ program
                                                 wireCursor(wireEnv);
                                 console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
                                 if (wireResult.ok) {
-                                    fixed++;
                                     if (client.id === "claude-code")
                                         claudeCodeAgentId = fixAgentId;
                                     if (client.id === "codex")
@@ -13311,7 +13436,6 @@ program
                     const agentHint = knownAgentId ? "" : fixCommandAgentHint(keyAgentIds);
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix${agentHint} ${render.wrap(render.c.dim, `(wires ${client.label} automatically)`)}`);
                 }
-                issues++;
                 continue;
             }
             console.log(`  ${render.icons.ok} ${client.label}: MCP server configured (${render.wrap(render.c.dim, block.configPath)})`);
@@ -13369,15 +13493,12 @@ program
                         else {
                             const fixRes = fixClaudeMdBootstrap(process.cwd());
                             console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
-                            if (fixRes.ok)
-                                fixed++;
                         }
                     }
                 }
                 else {
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(adds the mcp__flair__bootstrap line to ./CLAUDE.md)")}`);
                 }
-                issues++;
             }
             // flair#1007: presence was never the problem — the failing entry was
             // perfectly well-formed. inspectSessionStartHook() additionally RUNS
@@ -13446,8 +13567,6 @@ program
                                 else {
                                     const upgrade = upgradeSessionStartHookCommand(homedir());
                                     console.log(`     ${upgrade.ok ? render.icons.ok : render.icons.warn} ${upgrade.message}`);
-                                    if (upgrade.ok && upgrade.changed)
-                                        fixed++;
                                 }
                             }
                         }
@@ -13458,7 +13577,6 @@ program
                     else {
                         console.log(`     ${render.wrap(render.c.dim, "This hook was hand-edited, so Flair will not rewrite it. To adopt the current form:")} flair hook install`);
                     }
-                    issues++;
                 }
             }
             else {
@@ -13476,15 +13594,12 @@ program
                             const fixAgentId = claudeCodeAgentId || opts.agent || process.env.FLAIR_AGENT_ID;
                             const fixRes = fixSessionStartHook(homedir(), fixAgentId);
                             console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
-                            if (fixRes.ok)
-                                fixed++;
                         }
                     }
                 }
                 else {
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(adds the flair-session-start SessionStart hook)")}`);
                 }
-                issues++;
             }
             // flair#1257 slice 2 — continuity capture pair (the check-5 twin of
             // the SessionStart check above: installed / absent / stale-form).
@@ -13584,8 +13699,6 @@ program
                                 else {
                                     const upgrade = upgradeSessionStartHookCommand(homedir(), hook.path);
                                     console.log(`     ${upgrade.ok ? render.icons.ok : render.icons.warn} ${upgrade.message}`);
-                                    if (upgrade.ok && upgrade.changed)
-                                        fixed++;
                                 }
                             }
                         }
@@ -13596,7 +13709,6 @@ program
                     else {
                         console.log(`     ${render.wrap(render.c.dim, "This hook was hand-edited, so Flair will not rewrite it. To adopt the current form:")} flair hook install --harness codex`);
                     }
-                    issues++;
                 }
             }
             else {
@@ -13614,18 +13726,27 @@ program
                             const fixAgentId = resolveHookAgentId({ agent: opts.agent }, homedir(), "codex");
                             const fixRes = fixSessionStartHook(homedir(), fixAgentId, hook.path);
                             console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
-                            if (fixRes.ok)
-                                fixed++;
                         }
                     }
                 }
                 else {
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex`);
                 }
-                issues++;
             }
         }
     }
+    // Catalog is the install-health verdict — count fail/unrun here, not
+    // via a second issues++ on MCP / CLAUDE.md / SessionStart hook above.
+    // --fix that cleared a catalog member shows up in the found→fixed delta.
+    const catalogAfter = autoFix ? runDoctorChecks(doctorCtx) : catalogBefore;
+    const catalogDelta = catalogIssueDelta(catalogBefore, catalogAfter);
+    issues += catalogDelta.found;
+    if (autoFix)
+        fixed += catalogDelta.fixed;
+    console.log(`\n  ${render.wrap(render.c.bold, "Install health")}`);
+    for (const row of renderCatalogDoctorLines(catalogAfter)) {
+        console.log(`  ${render.icons[row.icon]} ${row.line}`);
+    }
     // 7a. Resolve which agent identities the two verified-read sections below
     // (Fleet presence, Migrations) iterate (flair#722). Previously both
     // sections required --agent explicitly; doctor already enumerates every

package/dist/doctor-client.js

@@ -1117,8 +1117,8 @@ function sessionStartHookHint(agentId, path) {
  * after the hook is present (whether from a prior call or already there)
  * reports ok:true, applied:false — safe to call on every `flair init`.
  */
-export function applyOrReportSessionStartHook(homeDir, agentId, skip) {
-    const existing = checkSessionStartHook(homeDir);
+export function applyOrReportSessionStartHook(homeDir, agentId, skip, settingsPath) {
+    const existing = checkSessionStartHook(homeDir, settingsPath);
     if (existing.present) {
         return { applied: false, ok: true, message: `SessionStart hook already wired in ${existing.path}` };
     }
@@ -1126,7 +1126,7 @@ export function applyOrReportSessionStartHook(homeDir, agentId, skip) {
     if (skip) {
         return { applied: false, ok: false, message: "SessionStart hook skipped (--skip-hook)", hint };
     }
-    const fix = fixSessionStartHook(homeDir, agentId);
+    const fix = fixSessionStartHook(homeDir, agentId, settingsPath ?? existing.path);
     return { applied: fix.ok, ok: fix.ok, message: fix.message, hint: fix.ok ? undefined : hint };
 }
 // ── check 5: per-agent iteration for verified-read sections (flair#722) ────

package/dist/install/clients.js

@@ -5,7 +5,9 @@
 // @tpsdev-ai/flair-mcp); pi is a native-extension host (kind:
 // "native-extension" — wired via pi's own settings.json `packages` key,
 // flair#1342). Each client has:
-//   - detection: `bin` on PATH, optionally widened by a declared detect() override
+//   - detection: `bin` on PATH OR the client's known config path exists
+//     (flair#1417 — GUI-only Cursor, PATH-quirky installs). A declared
+//     detect() override remains the exception (pi).
 //   - wire(env): { ok: boolean; message: string }
 //
 // Wiring contract (FIX 4 — onboarding dogfood round 1):
@@ -89,12 +91,13 @@ function binInPath(name) {
  *      elsewhere — the same defect already fixed for `flair upgrade`'s presence
  *      probes (see "Upgrade presence probes" in src/cli.ts).
  *
- * Nothing is lost by dropping it: an `npm install -g` links the package's bin
- * into the prefix's bin directory, which is on PATH by construction (it is where
- * `npm` itself is found from). A client whose binary is NOT on PATH is a client
- * the user cannot launch, and wiring an MCP config for it is at best a no-op.
- * `flair init --client <name>` still wires a client explicitly, bypassing
- * detection entirely, so an exotic install is never locked out.
+ * Nothing is lost by dropping the npm-list fallback: an `npm install -g` links
+ * the package's bin into the prefix's bin directory, which is on PATH by
+ * construction. Detection still asks PATH first. A second signal is the
+ * client's known config path (detectClients, flair#1417): a GUI install whose
+ * shell command is opt-in (Cursor) is still present when its config file
+ * exists. `flair init --client <name>` still wires a client explicitly,
+ * bypassing detection entirely, so an exotic install is never locked out.
  */
 function detectBin(bin) {
     try {
@@ -560,10 +563,12 @@ function antigravityConfigPath() {
     return join(resolveHome(), ".gemini", "config", "mcp_config.json");
 }
 /**
- * Single dispatcher for "where does this client's MCP config live" — used by
+ * Single dispatcher for "where does this client's config live" — used by
  * `flair doctor`'s client-integration checks (flair#588) to read the config
- * without duplicating the per-client path logic that already lives here.
- * Additive only: does not change existing wire/detect behavior.
+ * without duplicating the per-client path logic that already lives here,
+ * and by detectClients() as the config-path presence signal (flair#1417).
+ * Every current ClientId has a path; a future id must extend this switch
+ * or stay binary-only via a `detect` override — do not invent a path.
  */
 export function clientConfigPath(id) {
     switch (id) {
@@ -758,17 +763,23 @@ export function renderWiringSummary(results, opts = {}) {
     return lines;
 }
 /**
- * Detect every known client. One rule (`bin` on PATH) applied uniformly — a
- * client added to ALL_CLIENTS is detected by declaring its executable, with no
- * per-client branch here to forget to extend. A client may widen that with a
- * declared `detect` override (still a pure fs check — pi adds its settings
- * file as a second signal, flair#1342); the override lives on the registry
- * entry, so this function stays branch-free.
+ * Detect every known client. One rule applied uniformly: `bin` on PATH OR
+ * the client's known config path exists (flair#1417). A client added to
+ * ALL_CLIENTS is detected by declaring its executable; clientConfigPath()
+ * already names every current id, so the config-path fallback is not a
+ * per-client branch to forget. A declared `detect` override remains the
+ * exception (still a pure fs check — pi, flair#1342). Detection never
+ * spawns a subprocess (flair#946).
+ *
+ * A future client with no config path helper stays binary-only until it
+ * grows one here or a `detect` override — do not invent a path.
  */
 export function detectClients() {
     return ALL_CLIENTS.map((client) => ({
         ...client,
-        detected: client.detect ? client.detect() : detectBin(client.bin),
+        detected: client.detect
+            ? client.detect()
+            : detectBin(client.bin) || existsSync(clientConfigPath(client.id)),
     }));
 }
 export function wireClaudeCode(env) {