@tpsdev-ai/flair 0.49.0 → 0.51.0

package/dist/deploy.js

@@ -631,9 +631,26 @@ export function publishedEntryNames(packageRoot) {
     }
     // `files` entries are npm patterns; the ones flair uses are plain top-level
     // names, optionally trailing-slashed ("dist/"). Normalise to the entry name.
-    const names = declared
-        .map((f) => String(f).replace(/^\.\//, "").replace(/\/+$/, ""))
-        .filter((f) => f !== "" && !f.includes("*") && !f.startsWith("!"));
+    //
+    // Honourable iff the entry is a plain top-level name. A blacklist of `*` and
+    // `!` lets `?`, `[]`, `{}` (and anything else minimatch understands) through
+    // as a literal that matches no real file — the same silent drop this fix
+    // exists to prevent (Sherlock on #1398). Whitelist: there is no
+    // differently-malformed form that slips through.
+    const names = [];
+    for (const raw of declared) {
+        const f = String(raw).replace(/^\.\//, "").replace(/\/+$/, "");
+        // Empty after normalize (`""`, `./`, `/`) is a listed entry we cannot
+        // honour as a plain top-level name. Skipping it left hasDeclaredFiles
+        // true and shipped only the always-includes — the same silent omit
+        // (Bugbot on #1398).
+        if (f === "." || f === ".." || !/^[a-zA-Z0-9._-]+$/.test(f)) {
+            throw new Error(`Cannot honour files entry ${JSON.stringify(String(raw))}: the deploy payload filter supports plain ` +
+                `top-level entries only. Either simplify the entry, or extend publishedEntryNames() ` +
+                `to match npm pack semantics.`);
+        }
+        names.push(f);
+    }
     return new Set([...names, ...always]);
 }
 /**

package/dist/doctor-client.js

@@ -23,7 +23,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { ALL_CLIENTS, clientConfigPath, piSettingsPath, resolvePiExtensionPath, scanPiSettings, } from "./install/clients.js";
-import { FLAIR_MCP_PACKAGE } from "./lib/mcp-spec.js";
+import { FLAIR_MCP_PACKAGE, mcpServerSpec } from "./lib/mcp-spec.js";
 // The exact substring `flair init` writes into CLAUDE.md (src/cli.ts, the
 // `init` action) and that the doctor check + fix both key off of.
 export const CLAUDE_MD_BOOTSTRAP_MARKER = "mcp__flair__bootstrap";
@@ -42,9 +42,10 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 //
 // WHY THE INVOCATION IS WRAPPED
 // -----------------------------
-// The hook runs `npx -y -p @tpsdev-ai/flair-mcp flair-session-start`: it resolves
-// a package binary through whatever Node runtime the user's shell happens to
-// expose. Under a Node version manager, globally installed packages are
+// The hook runs `npx -y -p @tpsdev-ai/flair-mcp@<version> flair-session-start`
+// (same mcpServerSpec() pin as `flair init`'s user-local MCP client configs —
+// flair#1143). It resolves a package binary through whatever Node runtime the
+// user's shell happens to expose. Under a Node version manager, globally installed packages are
 // per-runtime-version, so a routine and entirely unrelated runtime upgrade
 // orphans that binary. The command then stops resolving and the harness
 // reports a hook error on EVERY session, indefinitely, in wording that names
@@ -64,7 +65,7 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 // spawns with `shell: true` and never consults $SHELL (verified against the
 // 2.1.220 bundle; the settings schema's claim that `"shell": "bash"` uses your
 // $SHELL is not what the code does on POSIX). So a bare POSIX fragment would
-// in fact be enough for the one harness we support today.
+// in fact be enough for the JSON-command harnesses we support today.
 //
 // It is still wrapped, because this string is not private to that harness:
 // SUPPORTED_HARNESSES (src/hook-install.ts) is a registry meant to grow, and
@@ -118,9 +119,23 @@ export function buildSessionStartHookCommand(agentId, flairUrl) {
         throw new Error(`Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
     }
     const env = flairUrl ? `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl}` : `FLAIR_AGENT_ID=${agentId}`;
-    const invocation = `${env} npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+    // Same pin as user-local MCP client configs (mcpServerSpec / flair#907).
+    // Public plugin mcp.json stays unpinned (flair#1308) — that is a scraped
+    // listing, not a machine we just wired.
+    const invocation = `${env} npx -y -p ${mcpServerSpec()} ${SESSION_START_HOOK_MARKER}`;
     return `sh -c 'out=$(${invocation} 2>/dev/null) && printf %s "$out" || true'`;
 }
+/**
+ * The `npx -y -p` invocation that runs `flair-session-start` — pinned
+ * (`@tpsdev-ai/flair-mcp@<ver>`) or the pre-#1143 unpinned form. Used by
+ * `flair hook status` so a freshly-pinned hook is not reported as
+ * hand-edited, and an older unpinned hook is not reported as broken.
+ * Rejects the pre-#1166 form (no `-p`), which runs the MCP shim.
+ */
+export const SESSION_START_HOOK_INVOCATION_RE = /npx -y -p @tpsdev-ai\/flair-mcp(?:@[^\s"']+)? flair-session-start/;
+export function isSessionStartHookInvocation(command) {
+    return typeof command === "string" && SESSION_START_HOOK_INVOCATION_RE.test(command);
+}
 /**
  * Does this command absorb a failure instead of surfacing it? Checked as two
  * independent PROPERTIES (stderr discarded, non-zero exit absorbed) rather
@@ -249,8 +264,8 @@ function continuityEventReport(config, event) {
  * pure fs read, no probe. A missing or unparseable settings.json reads as
  * "absent" (not enabled), matching checkSessionStartHook's tolerance.
  */
-export function checkContinuityCaptureHooks(homeDir) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function checkContinuityCaptureHooks(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     let config = {};
     const raw = readTextFile(path);
     if (raw && raw.trim()) {
@@ -728,12 +743,14 @@ export function fixClaudeMdBootstrap(cwd) {
     }
 }
 /**
- * Pass when ~/.claude/settings.json exists, parses as JSON, and ANY hook
+ * Pass when the harness settings file exists, parses as JSON, and ANY hook
  * command anywhere under hooks.SessionStart[*].hooks[*].command contains the
  * flair-session-start marker (see docs/mcp-clients.md for the exact shape).
+ * `settingsPath` defaults to ~/.claude/settings.json; pass the Codex
+ * `~/.codex/hooks.json` path (or any other hookSettingsPath) for that harness.
  */
-export function checkSessionStartHook(homeDir) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function checkSessionStartHook(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     const raw = readTextFile(path);
     if (!raw || !raw.trim())
         return { present: false, path };
@@ -772,10 +789,9 @@ export function checkSessionStartHook(homeDir) {
  * command. Returns the version when the spec is written
  * `@tpsdev-ai/flair-mcp@<ver>`; null for a bare/unpinned spec.
  *
- * The SessionStart hook is deliberately unpinned (`npx -y -p
- * @tpsdev-ai/flair-mcp`, buildSessionStartHookCommand above), so a hook
- * establishes that flair-mcp is wired but never carries a version — the pin
- * comes from the client MCP config.
+ * SessionStart hooks written since flair#1143 carry the same pin as a
+ * client MCP config (`mcpServerSpec()`). A pre-#1143 unpinned hook still
+ * establishes that flair-mcp is wired but contributes no version.
  */
 export function extractFlairMcpPin(text) {
     if (typeof text !== "string")
@@ -800,27 +816,39 @@ export function detectWiredFlairMcp(homeDir) {
                 pinnedVersion = pin;
         }
     };
-    // 1. The SessionStart hook (claude-code). Establishes wiring; unpinned by design.
-    const hook = checkSessionStartHook(homeDir);
-    if (hook.present && isFlairHookCommand(hook.command ?? ""))
-        note(hook.command);
-    // 2. Every known client's MCP config — a wired flair block carries the spec.
+    // 1. Every known client's MCP config — a wired flair block carries the spec.
+    //    Scanned first so a client pin wins (see module note above).
     for (const client of ALL_CLIENTS) {
         const configPath = withHome(homeDir, () => clientConfigPath(client.id));
         note(readTextFile(configPath));
     }
+    // 2. SessionStart hooks (claude-code settings.json + Codex hooks.json).
+    //    Establish wiring; may carry a pin, but NEVER override a client pin
+    //    already taken above — `note()` only sets pinnedVersion when it is still
+    //    unset, so THIS ORDERING IS THE PRECEDENCE RULE, not decoration. The
+    //    Codex path is additive (flair#1148); it must not reorder these two steps.
+    //    Paths match hookSettingsPath in src/hook-install.ts — listed here to
+    //    avoid a cycle (hook-install already imports this module).
+    for (const hookPath of [
+        join(homeDir, ".claude", "settings.json"),
+        join(homeDir, ".codex", "hooks.json"),
+    ]) {
+        const hook = checkSessionStartHook(homeDir, hookPath);
+        if (hook.present && isFlairHookCommand(hook.command ?? ""))
+            note(hook.command);
+    }
     return { wired, pinnedVersion };
 }
 /**
- * Merge-safe insert of a Flair SessionStart hook group into
- * ~/.claude/settings.json — creates the file/array if absent, preserves any
- * other existing hooks/keys (read-parse-merge-write, mirroring wireJsonMcp's
- * merge safety in src/install/clients.ts; never a blind overwrite). Dedupes:
- * a no-op (ok:true) if a matching hook is already present, so it's safe to
- * call twice.
+ * Merge-safe insert of a Flair SessionStart hook group into the harness
+ * settings file (default ~/.claude/settings.json) — creates the file/array
+ * if absent, preserves any other existing hooks/keys (read-parse-merge-write,
+ * mirroring wireJsonMcp's merge safety in src/install/clients.ts; never a
+ * blind overwrite). Dedupes: a no-op (ok:true) if a matching hook is already
+ * present, so it's safe to call twice.
  */
-export function fixSessionStartHook(homeDir, agentId) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function fixSessionStartHook(homeDir, agentId, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     if (!agentId) {
         return {
             ok: false,
@@ -953,7 +981,7 @@ export function classifyHookProbe(outcome) {
  * (or null via `{ probe: false }`) to keep a caller hermetic.
  */
 export function inspectSessionStartHook(homeDir, opts = {}) {
-    const found = checkSessionStartHook(homeDir);
+    const found = checkSessionStartHook(homeDir, opts.settingsPath);
     if (!found.present || !found.command) {
         return { path: found.path, present: false, ours: false, silenced: false, upgradable: false, execution: null };
     }
@@ -995,8 +1023,8 @@ export function classifyHookReadiness(report) {
  * decision to un-wire ambient memory, and `flair hook uninstall` is the
  * command for that when the user does decide.
  */
-export function upgradeSessionStartHookCommand(homeDir) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function upgradeSessionStartHookCommand(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     try {
         const raw = readTextFile(path);
         if (!raw || !raw.trim())
@@ -1089,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}` };
     }
@@ -1098,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/federation/scheduler.js

@@ -62,7 +62,7 @@ import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, resolveFlairBin, formatFlairBinWarning, verifyFirstRun, probeUserLingerEnabled, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 export const LAUNCHD_LABEL = "dev.flair.federation.sync";
 export const SYSTEMD_TIMER_UNIT = "flair-federation-sync.timer";
 export const SYSTEMD_SERVICE_UNIT = "flair-federation-sync.service";
@@ -165,7 +165,8 @@ function launchdDomain() {
  */
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
-    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const resolvedFlair = resolveFlairBin(opts.flairBin);
+    const flairBin = resolvedFlair.path;
     const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
@@ -221,6 +222,7 @@ export function enableScheduler(opts) {
         return {
             platform: plat, shimPath, schedulerPath: plistPath, intervalSeconds: opts.intervalSeconds,
             loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+            flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
         };
     }
     // Linux: systemd user units.
@@ -249,6 +251,7 @@ export function enableScheduler(opts) {
     return {
         platform: plat, shimPath, schedulerPath: timerPath, intervalSeconds: opts.intervalSeconds,
         loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+        flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
     };
 }
 /** Removes the scheduler entry. Peer records and sync history are untouched. */
@@ -485,6 +488,15 @@ export function assessDriver(input) {
  * asked for — a sync run through the service manager — has been observed to
  * happen once.
  */
+function appendFlairBinWarning(lines, r) {
+    if (r.flairBinCanonical !== false || !r.flairBin)
+        return;
+    const warning = formatFlairBinWarning(r.flairBin, r.flairBinPublic ?? null, "flair federation sync enable");
+    if (warning.length === 0)
+        return;
+    lines.push("");
+    lines.push(...warning);
+}
 export function formatEnableReport(r, input) {
     const activationFailed = !!r.loadResult && r.loadResult.code !== 0;
     const credLine = input.adminPassFile
@@ -504,11 +516,18 @@ export function formatEnableReport(r, input) {
         lines.push(`   Activation:  ${r.loadCommand.join(" ")} → code ${lr.code}`);
         if (lr.stderr)
             lines.push(`     stderr: ${lr.stderr.trim()}`);
-        const remedy = describeLoadFailureFor(r.platform, lr, "flair federation sync enable");
+        const lingerEnabled = input.lingerEnabled !== undefined
+            ? input.lingerEnabled
+            : (r.platform === "linux" ? (input.probeLinger ?? probeUserLingerEnabled)() : undefined);
+        const remedy = describeLoadFailureFor(r.platform, lr, "flair federation sync enable", {
+            lingerEnabled,
+            env: input.env,
+        });
         lines.push("");
         lines.push(remedy ? `   ${remedy}` : `   Re-run the activation command above manually to see the full diagnostic.`);
         lines.push("");
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair federation sync status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     if (!r.firstRunVerified) {
@@ -561,6 +580,7 @@ export function formatEnableReport(r, input) {
         }
         lines.push("");
         lines.push(`   Check anytime with: flair federation sync status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     const lines = [
@@ -579,6 +599,7 @@ export function formatEnableReport(r, input) {
     lines.push(`Confirm anytime with \`flair federation status\`,`);
     lines.push(`which reports whether anything is actually driving sync.`);
     lines.push(`Disable with \`flair federation sync disable\`.`);
+    appendFlairBinWarning(lines, r);
     return { lines, ok: true };
 }
 /** Formats the `flair federation sync status` report. */

package/dist/hook-install.js

@@ -54,12 +54,13 @@
 //      reuses bootstrap's own maxTokens machinery.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, hookCommandIsSilenced, isHookCommandValueSafe, } from "./doctor-client.js";
+import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, hookCommandIsSilenced, isHookCommandValueSafe, isSessionStartHookInvocation, readClientMcpBlock, } from "./doctor-client.js";
 // ── harness registry ────────────────────────────────────────────────────────
-/** v1 supports exactly one harness. The flag/type exist so a second harness
- *  is an additive registry entry, not a rewrite (Kern's #719 verdict: "a
- *  switch statement... is fine until we have 3+ harnesses"). */
-export const SUPPORTED_HARNESSES = ["claude-code"];
+/** SessionStart hook harnesses. A second harness is an additive registry
+ *  entry, not a rewrite (Kern's #719 verdict: "a switch statement... is
+ *  fine until we have 3+ harnesses"). Codex writes the same JSON hook
+ *  schema Claude Code uses, into `~/.codex/hooks.json` (flair#1148). */
+export const SUPPORTED_HARNESSES = ["claude-code", "codex"];
 export function isSupportedHarness(value) {
     return SUPPORTED_HARNESSES.includes(value);
 }
@@ -70,8 +71,37 @@ export function hookSettingsPath(homeDir, harness) {
     switch (harness) {
         case "claude-code":
             return join(homeDir, ".claude", "settings.json");
+        case "codex":
+            return join(homeDir, ".codex", "hooks.json");
     }
 }
+/** Continuity capture (PostToolUse + Stop) is Claude Code only. The matcher
+ *  is Claude tool names; writing it into another harness looks enabled and
+ *  never journals (flair#1148 Bugbot). SessionStart stays per-harness. */
+export function harnessSupportsContinuity(harness) {
+    return harness === "claude-code";
+}
+/** Status/doctor hint for `flair hook install`. Claude Code stays the bare
+ *  default; every other harness is named so the hint cannot silently write
+ *  the wrong file (flair#1148 Bugbot). */
+export function hookInstallHint(harness, extraFlags = "") {
+    const parts = ["flair hook install"];
+    if (extraFlags)
+        parts.push(extraFlags);
+    if (harness !== "claude-code")
+        parts.push(`--harness ${harness}`);
+    return parts.join(" ");
+}
+/** Agent id for a hook install: flag, env, this harness's MCP block, then
+ *  Claude Code's block as a last resort (same agent is often shared). */
+export function resolveHookAgentId(opts, homeDir, harness) {
+    return (opts.agent ||
+        opts.agentId ||
+        process.env.FLAIR_AGENT_ID ||
+        readClientMcpBlock(harness, homeDir).agentId ||
+        (harness !== "claude-code" ? readClientMcpBlock("claude-code", homeDir).agentId : undefined) ||
+        undefined);
+}
 /** Backup path convention: a single sibling `<path>.bak`, overwritten on
  *  every mutating run — recovery insurance for the mutation that's about to
  *  happen, not a version history. Exported so tests assert against the same
@@ -131,7 +161,7 @@ export const HOOK_STATUS_UNPARSED = "(unknown — could not parse command)";
  *  Recovered values are shown. The installer-no-URL omit (flair#1325) is
  *  allowed ONLY when agentId was parsed — that is the real `flair init`
  *  shape (`FLAIR_AGENT_ID` set, `FLAIR_URL` omitted). correctShape alone
- *  is not enough: it is an npx-substring check and a wired correct-shape
+ *  is not enough: it is an npx-invocation check and a wired correct-shape
  *  command with no env assignments must still show the unknown lines,
  *  not a silent all-clear. */
 export function hookStatusIdentityLines(status) {
@@ -392,7 +422,7 @@ export function hookStatus(homeDir, harness) {
     }
     const hookEntry = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex];
     const command = typeof hookEntry?.command === "string" ? hookEntry.command : "";
-    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
+    const correctShape = hookEntry?.type === "command" && isSessionStartHookInvocation(command);
     const env = parseHookCommandEnv(command);
     return {
         harness, path, wired: true, correctShape,
@@ -425,6 +455,13 @@ export function installContinuityHooks(opts) {
     const { homeDir, harness, agentId, flairUrl } = opts;
     const dryRun = !!opts.dryRun;
     const path = hookSettingsPath(homeDir, harness);
+    if (!harnessSupportsContinuity(harness)) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `continuity capture is Claude Code only — ${harness} has no PostToolUse/Stop matcher Flair can journal (SessionStart is still ${hookInstallHint(harness)})`,
+            backupPath: null, actions: null,
+        };
+    }
     for (const [label, value] of [["agent id", agentId], ["Flair URL", flairUrl]]) {
         if (!isHookCommandValueSafe(value)) {
             return {
@@ -542,10 +579,5 @@ export function uninstallContinuityHooks(opts) {
 /** Read-only continuity status for `flair hook status` — the same report
  *  doctor's check consumes, resolved through the harness's settings path. */
 export function continuityHookStatus(homeDir, harness) {
-    // hookSettingsPath and checkContinuityCaptureHooks both resolve
-    // ~/.claude/settings.json from homeDir; asserting through the harness
-    // registry keeps a future second harness from silently reading the wrong
-    // file.
-    void hookSettingsPath(homeDir, harness);
-    return checkContinuityCaptureHooks(homeDir);
+    return checkContinuityCaptureHooks(homeDir, hookSettingsPath(homeDir, harness));
 }

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) {