@tpsdev-ai/flair 0.20.0 → 0.21.0

package/dist/deploy.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 // Files that must be present in a Flair package for deployment.
@@ -11,6 +11,23 @@ export const REQUIRED_PACKAGE_FILES = [
     "ui",
     "config.yaml",
 ];
+// harper's own deploy CLI defaults to a 120s peer-replication timeout that's
+// too short for Fabric — the CLI aborts mid-replicate with no override,
+// which is exactly the incident this module now guards against. 10 minutes
+// gives cluster-wide replication + install room to actually finish.
+export const DEFAULT_DEPLOYMENT_TIMEOUT_MS = 600_000;
+export const DEFAULT_INSTALL_TIMEOUT_MS = 600_000;
+// Post-deploy verification: how long we'll wait for the served API to come
+// back up after harper's restart, how often we poll while waiting, and how
+// many consecutive reachable responses count as "settled" (a single
+// reachable probe right after restart can be a fluke mid-flap).
+export const DEFAULT_VERIFY_TIMEOUT_MS = 300_000;
+export const VERIFY_POLL_INTERVAL_MS = 15_000;
+export const VERIFY_SETTLE_STREAK = 3;
+// Fallback when dist/resources can't be scanned (e.g. an unusual package
+// layout via --package-root). Memory is Flair's original, always-present
+// resource — a reasonable single thing to check when derivation fails.
+export const FALLBACK_VERIFY_RESOURCE = "Memory";
 export function validateOptions(opts) {
     const errors = [];
     if (!opts.target) {
@@ -81,6 +98,65 @@ export function validatePackageLayout(packageRoot) {
             missing.join(", "));
     }
 }
+// Derive the list of served, table-backed REST resources from the compiled
+// package — no hardcoded resource list. Flair's jsResource files (dist/resources/*.js)
+// contain both real Resource classes (routable, GET-able) and plain helper
+// modules (embeddings, auth, scoring, etc). We only ship dist/ in the
+// published package (resources/*.ts source is not in package.json's `files`),
+// so this scans the COMPILED output, matching the convention every current
+// table-backed resource follows:
+//
+//   export class <Name> extends databases.<db>.<Name> { ... }
+//
+// i.e. the exported class name equals the filename equals the underlying
+// table name (Memory.js -> `export class Memory extends databases.flair.Memory`,
+// same for Agent, Soul, MemoryGrant, Credential, OrgEvent, etc). Helper
+// modules are lowercase-first (agent-auth.js, embeddings-provider.js, ...)
+// and never match, so they're skipped without needing a denylist. Files
+// that export a resource extending a *generic* `Resource` base (AgentCard,
+// WorkspaceLatest, action-style endpoints) are deliberately excluded here —
+// they're action/command endpoints, not GET-able collections, and asserting
+// non-404 on them would be the wrong check.
+// Literal regex (no interpolation — satisfies semgrep detect-non-literal-regexp):
+// matches `export class <Name> extends databases.<db>.<Name>` where the `\1`
+// backreference forces the class name and the table name to be identical.
+// Capture group 1 is the resource name; the caller matches it against the filename.
+const EXPORTED_TABLE_CLASS_RE = /export class (\w+) extends databases\.[A-Za-z_$][\w$]*\.\1\b/g;
+export function deriveVerifyResources(packageRoot) {
+    const resourcesDir = join(packageRoot, "dist", "resources");
+    let entries;
+    try {
+        entries = readdirSync(resourcesDir);
+    }
+    catch {
+        return [FALLBACK_VERIFY_RESOURCE];
+    }
+    const names = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".js"))
+            continue;
+        const base = entry.slice(0, -3);
+        if (!/^[A-Z]/.test(base))
+            continue; // helper modules are camelCase/lowercase
+        let src;
+        try {
+            src = readFileSync(join(resourcesDir, entry), "utf8");
+        }
+        catch {
+            continue;
+        }
+        // The file serves a table resource iff it exports a class whose name matches
+        // its filename (base) and extends databases.<db>.<sameName>.
+        for (const m of src.matchAll(EXPORTED_TABLE_CLASS_RE)) {
+            if (m[1] === base) {
+                names.push(base);
+                break;
+            }
+        }
+    }
+    names.sort();
+    return names.length ? names : [FALLBACK_VERIFY_RESOURCE];
+}
 function resolveHarperBin(packageRoot) {
     const local = join(packageRoot, "node_modules/@harperfast/harper/dist/bin/harper.js");
     if (existsSync(local))
@@ -105,22 +181,199 @@ function resolveHarperBin(packageRoot) {
     throw new Error("Could not locate Harper CLI binary (@harperfast/harper). " +
         "Flair deploy requires Harper to be installed alongside Flair.");
 }
-function spawnHarper(bin, args, cwd, env) {
+// Pure arg-array builder — separated from spawnHarper so the timeout
+// passthrough (and the rest of the arg shape) is unit-testable without
+// mocking child_process / actually spawning harper.
+export function buildHarperDeployArgs(opts, url, project) {
+    const deploymentTimeoutMs = opts.deploymentTimeoutMs ?? DEFAULT_DEPLOYMENT_TIMEOUT_MS;
+    const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+    const args = [
+        "deploy",
+        `target=${url}`,
+        `project=${project}`,
+        `restart=${opts.restart !== false}`,
+        `replicated=${opts.replicated !== false}`,
+        `deployment_timeout=${deploymentTimeoutMs}`,
+        `install_timeout=${installTimeoutMs}`,
+    ];
+    // --ignore-replication-errors escape hatch. Only appended when
+    // set — omitted entirely otherwise, so this is a no-op for every existing
+    // caller/test that doesn't pass it.
+    if (opts.ignoreReplicationErrors) {
+        args.push("ignore_replication_errors=true");
+    }
+    return args;
+}
+// Flaky-peer-replication resilience defaults. See DeployOptions
+// for the full incident writeup this closes.
+export const DEFAULT_DEPLOY_RETRIES = 2;
+export const DEPLOY_RETRY_BACKOFF_MS = [5_000, 10_000];
+// The signature of a Fabric PEER-REPLICATION failure specifically — harper
+// deploys fine to the origin node, but pushing the component to a peer
+// fails, e.g.:
+//   "Component 'flair' was deployed on the origin node but failed to
+//    replicate to 1 of 1 peer node(s): ... (Error: Connection closed 1006)"
+// This is the CORRECTNESS-CRITICAL part of the fix: matching this pattern
+// (and ONLY this pattern) is what lets us retry a known flake while still
+// failing fast on a real deploy failure (bad package, auth, missing files —
+// none of which mention peer replication and must never be retried).
+// Literal regex, no interpolation.
+export const REPLICATION_FAILURE_RE = /failed to replicate to \d+ (of \d+ )?peer|connection closed\s+1006|ignore_replication_errors/i;
+// Tee-style capture: streams harper's stdout/stderr to the user in real time
+// (unchanged UX — a multi-minute deploy needs live progress, not a black
+// box) while ALSO buffering the combined text so the caller can
+// pattern-match REPLICATION_FAILURE_RE against it after exit. This replaces
+// the previous stdio:"inherit" passthrough, which gave no way to inspect
+// harper's output. stdin stays "inherit" — harper's deploy never reads
+// from it, so there's nothing to tee there.
+function spawnHarperCaptured(bin, args, cwd, env) {
     return new Promise((resolveP, rejectP) => {
         const p = spawn(process.execPath, [bin, ...args], {
             cwd,
-            stdio: "inherit",
+            stdio: ["inherit", "pipe", "pipe"],
             env,
         });
-        p.on("error", rejectP);
-        p.on("exit", (code) => {
-            if (code === 0)
-                resolveP();
-            else
-                rejectP(new Error(`harper deploy exited with code ${code}`));
+        const chunks = [];
+        p.stdout?.on("data", (d) => {
+            process.stdout.write(d);
+            chunks.push(d.toString("utf8"));
         });
+        p.stderr?.on("data", (d) => {
+            process.stderr.write(d);
+            chunks.push(d.toString("utf8"));
+        });
+        p.on("error", rejectP);
+        p.on("exit", (code) => resolveP({ code, output: chunks.join("") }));
     });
 }
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// Runs `harper deploy`, retrying ONLY on the flaky peer-replication failure
+// signature (REPLICATION_FAILURE_RE) — the real incident this closes: the
+// origin deployed fine, replication to a peer failed with a transient
+// "Connection closed 1006", and a bare manual retry cleared it with no
+// other change. This re-runs the FULL harper deploy (prepare/install/
+// replicate), not just a peer-only re-push — wasteful, but it's exactly
+// what worked by hand, and harper's CLI has no "retry replication only"
+// entry point. Any other failure (bad package, auth, missing files, ...)
+// is never retried — it fails fast, same as before this change.
+async function runHarperDeploy(bin, args, cwd, env, opts) {
+    const maxRetries = opts.deployRetries ?? DEFAULT_DEPLOY_RETRIES;
+    const backoff = opts.deployRetryBackoffMs ?? DEPLOY_RETRY_BACKOFF_MS;
+    const totalAttempts = Math.max(1, maxRetries + 1);
+    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
+        const { code, output } = await spawnHarperCaptured(bin, args, cwd, env);
+        if (code === 0)
+            return { replicationWarning: false };
+        const isReplicationFailure = REPLICATION_FAILURE_RE.test(output);
+        const isLastAttempt = attempt === totalAttempts;
+        if (isReplicationFailure && !isLastAttempt) {
+            const waitMs = backoff[Math.min(attempt - 1, backoff.length - 1)];
+            // Self-healing must be visible, never silent — console.warn directly
+            // (not gated behind onProgress, which some callers like
+            // fabric-upgrade.ts don't wire up) so this is loud regardless of caller.
+            console.warn(`⚠ flair deploy: replication flake on attempt ${attempt}/${totalAttempts} ` +
+                `(harper deploy exited ${code}, peer-replication signature matched) — ` +
+                `retrying in ${Math.round(waitMs / 1000)}s...`);
+            opts.onProgress?.(`replication flake on attempt ${attempt}/${totalAttempts} — retrying in ${Math.round(waitMs / 1000)}s...`);
+            await sleep(waitMs);
+            continue;
+        }
+        if (isReplicationFailure && opts.ignoreReplicationErrors) {
+            console.warn(`⚠ flair deploy: peer replication still failing after ${attempt} attempt(s), ` +
+                `but --ignore-replication-errors is set — treating this as a WARNED SUCCESS ` +
+                `(deployed to the origin node only; the peer will need to catch up via normal ` +
+                `federation sync or a later deploy).`);
+            opts.onProgress?.(`WARNING: proceeding origin-only — peer replication did not complete after ${attempt} attempt(s)`);
+            return { replicationWarning: true };
+        }
+        if (isReplicationFailure) {
+            throw new Error(`harper deploy exited with code ${code}: peer replication failed after ${attempt} attempt(s) ` +
+                `(retries exhausted). Pass --ignore-replication-errors to accept an origin-only deploy, ` +
+                `or re-run once the peer link recovers.`);
+        }
+        throw new Error(`harper deploy exited with code ${code}`);
+    }
+    // Unreachable — the loop always returns or throws — but keeps TS happy.
+    throw new Error("harper deploy: exhausted retry loop without resolving");
+}
+// A single reachability probe against the served (REST) base URL. Harper
+// restarts the process after every deploy, so the endpoint FLAPS for a bit —
+// connection refused / reset / DNS blips are all EXPECTED right after
+// restart, not a failure signal by themselves. Any HTTP response at all
+// (regardless of status code — a 404 on `/` is normal) proves the process
+// is back up and terminating TLS/HTTP again; that's all "reachable" means
+// here. Resource-level 404s are a separate, later check.
+async function probeReachable(baseUrl, fetchImpl) {
+    try {
+        await fetchImpl(baseUrl, { method: "GET", signal: AbortSignal.timeout(10_000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function pollUntilSettled(baseUrl, timeoutMs, pollIntervalMs, settleStreak, fetchImpl, onProgress) {
+    const deadline = Date.now() + timeoutMs;
+    let streak = 0;
+    let attempt = 0;
+    for (;;) {
+        attempt++;
+        const reachable = await probeReachable(baseUrl, fetchImpl);
+        streak = reachable ? streak + 1 : 0;
+        if (!reachable) {
+            onProgress?.(`waiting for ${baseUrl} to come back up after restart (attempt ${attempt})...`);
+        }
+        if (streak >= settleStreak)
+            return;
+        if (Date.now() >= deadline) {
+            throw new Error(`deploy verification: ${baseUrl} did not settle within ${timeoutMs}ms after restart ` +
+                `(Harper never came back up, or is unusually slow to restart post-deploy)`);
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+async function verifyResourcesServing(baseUrl, resources, fetchImpl) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const notServing = [];
+    for (const name of resources) {
+        const path = `${base}/${name}`;
+        let status;
+        try {
+            const res = await fetchImpl(path, { method: "GET", signal: AbortSignal.timeout(10_000) });
+            status = res.status;
+        }
+        catch (err) {
+            throw new Error(`deploy verification: request to ${path} failed even after the endpoint settled: ${err?.message ?? err}`);
+        }
+        // 404 = the resource genuinely isn't being served (this is the incident:
+        // harper reported "Successfully deployed" while the component was empty).
+        // 401 = auth-gated, which means the resource IS being served correctly.
+        // 200 = served + accessible. Both count as pass.
+        if (status === 404)
+            notServing.push(name);
+    }
+    if (notServing.length) {
+        const list = notServing.map((n) => `/${n}`).join(", ");
+        throw new Error(`deploy reported success but ${list} return${notServing.length === 1 ? "s" : ""} 404 — ` +
+            `component is not serving; likely deployed the wrong package root`);
+    }
+}
+// The tool must not be able to lie. harper's deploy CLI can print
+// "Successfully deployed" for an empty component — the only way to know the
+// deploy actually worked is to curl the served API and check it isn't 404.
+// This polls the served base URL (443, NOT the :9925 ops API deploy talks
+// to) until it settles after harper's post-deploy restart, then asserts the
+// derived resource(s) respond non-404.
+export async function verifyDeployServing(o) {
+    const { baseUrl, resources, timeoutMs = DEFAULT_VERIFY_TIMEOUT_MS, pollIntervalMs = VERIFY_POLL_INTERVAL_MS, settleStreak = VERIFY_SETTLE_STREAK, fetchImpl = fetch, onProgress, } = o;
+    onProgress?.(`verifying ${baseUrl} is actually serving (not just reported deployed)...`);
+    await pollUntilSettled(baseUrl, timeoutMs, pollIntervalMs, settleStreak, fetchImpl, onProgress);
+    onProgress?.(`settled — checking ${resources.map((r) => `/${r}`).join(", ")}...`);
+    await verifyResourcesServing(baseUrl, resources, fetchImpl);
+    onProgress?.(`served API verified non-404 for ${resources.length} resource(s)`);
+}
 export async function deploy(opts) {
     const errors = validateOptions(opts);
     if (errors.length) {
@@ -141,13 +394,7 @@ export async function deploy(opts) {
             "Pass --fabric-user + --fabric-password instead.");
     }
     const harperBin = resolveHarperBin(packageRoot);
-    const args = [
-        "deploy",
-        `target=${url}`,
-        `project=${project}`,
-        `restart=${opts.restart !== false}`,
-        `replicated=${opts.replicated !== false}`,
-    ];
+    const args = buildHarperDeployArgs(opts, url, project);
     // Credentials go via env, not argv, so they don't appear in `ps` output
     // for the lifetime of the Harper child process. Harper's cliOperations
     // reads CLI_TARGET_USERNAME / CLI_TARGET_PASSWORD as env fallbacks.
@@ -156,6 +403,21 @@ export async function deploy(opts) {
         CLI_TARGET_USERNAME: opts.fabricUser,
         CLI_TARGET_PASSWORD: opts.fabricPassword,
     };
-    await spawnHarper(harperBin, args, packageRoot, childEnv);
-    return { url, project, version, packageRoot, dryRun: false };
+    const { replicationWarning } = await runHarperDeploy(harperBin, args, packageRoot, childEnv, opts);
+    // harper can print "Successfully deployed" for a component that isn't
+    // actually serving anything (the incident this closes: an empty deploy,
+    // reported success, /Memory 404ing in prod). Verify by curling the served
+    // API — on by default, escape hatch via --no-verify.
+    if (opts.verify !== false) {
+        const resources = opts.verifyResources?.length
+            ? opts.verifyResources
+            : deriveVerifyResources(packageRoot);
+        await verifyDeployServing({
+            baseUrl: url,
+            resources,
+            timeoutMs: opts.verifyTimeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS,
+            onProgress: opts.onProgress,
+        });
+    }
+    return { url, project, version, packageRoot, dryRun: false, replicationWarning };
 }

package/dist/doctor-client.js

@@ -0,0 +1,312 @@
+// ─── Doctor: client integration checks (flair#588) ──────────────────────────────
+//
+// `flair doctor` diagnosed the SERVER side only (Harper port, keys, config,
+// embeddings, data dir). It had zero visibility into whether the CLIENT
+// integration — the MCP wiring an agent like Claude Code actually uses — is
+// working. A real incident found users with partial setups (MCP block wired
+// but no CLAUDE.md line; or no SessionStart hook) that silently no-op, with
+// no way to tell "is Flair working for my agent?" short of an incident.
+//
+// This module is pure filesystem logic (no network, no crypto) so it's fast
+// and fully unit-testable in isolation — mirrors test/unit/client-wiring.test.ts's
+// technique of overriding process.env.HOME to a temp dir. The two
+// network-dependent checks (reachability + agent registration) live in
+// src/cli.ts alongside authFetch/resolveKeyPath, which they reuse.
+//
+// Every read here is try/catch-wrapped: a missing or malformed config file is
+// "not present", never a thrown error — doctor must never crash or hang on a
+// broken client config.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { clientConfigPath } from "./install/clients.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";
+const CLAUDE_MD_BOOTSTRAP_LINE = "At the start of every session, run mcp__flair__bootstrap before responding.";
+// The exact substring identifying a Flair SessionStart hook command (see
+// docs/mcp-clients.md "Auto-recall on session start").
+export const SESSION_START_HOOK_MARKER = "flair-session-start";
+// ── shared helpers ──────────────────────────────────────────────────────────
+/**
+ * Run `fn` with process.env.HOME temporarily pointed at `homeDir`, then
+ * restore it. clientConfigPath() (src/install/clients.ts) resolves the home
+ * dir via HOME/USERPROFILE at call time (not cached), so this lets us reuse
+ * that single source of truth for per-client config paths while keeping
+ * doctor-client's own functions parameterized by an explicit homeDir for
+ * tests — no test ever touches the real ~/.claude.json etc. The override is
+ * synchronous and restored before this function returns, so it's safe even
+ * though process.env is process-global.
+ */
+function withHome(homeDir, fn) {
+    const prev = process.env.HOME;
+    process.env.HOME = homeDir;
+    try {
+        return fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = prev;
+    }
+}
+function readTextFile(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the Flair MCP server block from `clientId`'s config file. `present`
+ * is true only when the block exists AND both FLAIR_AGENT_ID and FLAIR_URL
+ * are set (non-empty) — a half-wired block (e.g. block present, env missing)
+ * counts as absent for the pass/fail check, but agentId/flairUrl are still
+ * returned when partially found so callers can use whatever is known.
+ */
+export function readClientMcpBlock(clientId, homeDir) {
+    const configPath = withHome(homeDir, () => clientConfigPath(clientId));
+    return clientId === "codex" ? readCodexFlairBlock(configPath) : readJsonFlairBlock(configPath);
+}
+function readJsonFlairBlock(configPath) {
+    const raw = readTextFile(configPath);
+    if (!raw || !raw.trim())
+        return { present: false, configPath };
+    try {
+        const config = JSON.parse(raw);
+        const flair = config?.mcpServers?.flair;
+        if (!flair || typeof flair !== "object")
+            return { present: false, configPath };
+        const agentId = typeof flair.env?.FLAIR_AGENT_ID === "string" && flair.env.FLAIR_AGENT_ID ? flair.env.FLAIR_AGENT_ID : undefined;
+        const flairUrl = typeof flair.env?.FLAIR_URL === "string" && flair.env.FLAIR_URL ? flair.env.FLAIR_URL : undefined;
+        return { present: !!agentId && !!flairUrl, configPath, agentId, flairUrl };
+    }
+    catch {
+        // Malformed JSON — treat as "not present", never throw.
+        return { present: false, configPath };
+    }
+}
+/**
+ * Codex's config is TOML, and this repo carries no TOML parser (see the
+ * comment on _wireCodex in src/install/clients.ts) — so this is a lightweight
+ * string scan, matching the exact shape _wireCodex/tomlSnippet() produce:
+ *
+ *   [mcp_servers.flair]
+ *   command = "npx"
+ *   args = ["-y", "@tpsdev-ai/flair-mcp"]
+ *
+ *   [mcp_servers.flair.env]
+ *   FLAIR_AGENT_ID = "..."
+ *   FLAIR_URL = "..."
+ *
+ * We locate the `[mcp_servers.flair]` header, then collect lines until a
+ * header that is NOT part of this table (i.e. doesn't start with
+ * "[mcp_servers.flair") — deliberately does NOT stop at the nested
+ * `[mcp_servers.flair.env]` sub-table, since that's where the two env keys
+ * actually live.
+ */
+function readCodexFlairBlock(configPath) {
+    const raw = readTextFile(configPath);
+    if (!raw)
+        return { present: false, configPath };
+    const scanned = scanCodexFlairBlock(raw);
+    return { present: scanned.present, configPath, agentId: scanned.agentId, flairUrl: scanned.flairUrl };
+}
+function scanCodexFlairBlock(raw) {
+    const startMatch = raw.match(/^\[mcp_servers\.flair\]\s*$/m);
+    if (!startMatch || startMatch.index === undefined)
+        return { present: false };
+    const rest = raw.slice(startMatch.index);
+    const lines = rest.split("\n");
+    const blockLines = [lines[0]];
+    for (let i = 1; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith("[") && !trimmed.startsWith("[mcp_servers.flair"))
+            break;
+        blockLines.push(lines[i]);
+    }
+    const block = blockLines.join("\n");
+    const agentMatch = block.match(/^\s*FLAIR_AGENT_ID\s*=\s*"([^"]*)"/m);
+    const urlMatch = block.match(/^\s*FLAIR_URL\s*=\s*"([^"]*)"/m);
+    const agentId = agentMatch?.[1] || undefined;
+    const flairUrl = urlMatch?.[1] || undefined;
+    return { present: !!agentId && !!flairUrl, agentId, flairUrl };
+}
+/**
+ * Pass when EITHER the project-scoped `${cwd}/CLAUDE.md` or the user-level
+ * `~/.claude/CLAUDE.md` contains the bootstrap marker — Claude Code loads
+ * both. Checks cwd first (the convention docs/claude-code.md documents and
+ * what `flair init` tells users to edit).
+ */
+export function checkClaudeMdBootstrap(cwd, homeDir) {
+    const cwdPath = join(cwd, "CLAUDE.md");
+    const cwdContent = readTextFile(cwdPath);
+    if (cwdContent && cwdContent.includes(CLAUDE_MD_BOOTSTRAP_MARKER)) {
+        return { present: true, path: cwdPath };
+    }
+    const homePath = join(homeDir, ".claude", "CLAUDE.md");
+    const homeContent = readTextFile(homePath);
+    if (homeContent && homeContent.includes(CLAUDE_MD_BOOTSTRAP_MARKER)) {
+        return { present: true, path: homePath };
+    }
+    return { present: false, path: null };
+}
+/**
+ * Append the bootstrap instruction to `${cwd}/CLAUDE.md` (creating it if
+ * absent). Idempotent — safe to call twice; a second call is a no-op that
+ * still reports ok:true.
+ */
+export function fixClaudeMdBootstrap(cwd) {
+    const path = join(cwd, "CLAUDE.md");
+    try {
+        const existing = readTextFile(path) ?? "";
+        if (existing.includes(CLAUDE_MD_BOOTSTRAP_MARKER)) {
+            return { ok: true, path, message: `already present in ${path}` };
+        }
+        const separator = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        const block = `${separator}## Flair memory\n\n${CLAUDE_MD_BOOTSTRAP_LINE}\n`;
+        writeFileSync(path, existing + block);
+        return { ok: true, path, message: `added bootstrap instruction to ${path}` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, message: `could not write ${path}: ${reason}` };
+    }
+}
+/**
+ * Pass when ~/.claude/settings.json 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).
+ */
+export function checkSessionStartHook(homeDir) {
+    const path = join(homeDir, ".claude", "settings.json");
+    const raw = readTextFile(path);
+    if (!raw || !raw.trim())
+        return { present: false, path };
+    try {
+        const config = JSON.parse(raw);
+        const groups = config?.hooks?.SessionStart;
+        if (!Array.isArray(groups))
+            return { present: false, path };
+        for (const group of groups) {
+            const hooks = group?.hooks;
+            if (!Array.isArray(hooks))
+                continue;
+            for (const hook of hooks) {
+                if (typeof hook?.command === "string" && hook.command.includes(SESSION_START_HOOK_MARKER)) {
+                    return { present: true, path };
+                }
+            }
+        }
+        return { present: false, path };
+    }
+    catch {
+        return { present: false, path };
+    }
+}
+/**
+ * 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.
+ */
+export function fixSessionStartHook(homeDir, agentId) {
+    const path = join(homeDir, ".claude", "settings.json");
+    if (!agentId) {
+        return {
+            ok: false,
+            path,
+            message: "no agent id known — pass --agent <id> (or set FLAIR_AGENT_ID) so doctor knows which agent to wire the hook to",
+        };
+    }
+    try {
+        let config = {};
+        const raw = readTextFile(path);
+        if (raw && raw.trim())
+            config = JSON.parse(raw);
+        config.hooks = config.hooks && typeof config.hooks === "object" ? config.hooks : {};
+        config.hooks.SessionStart = Array.isArray(config.hooks.SessionStart) ? config.hooks.SessionStart : [];
+        const alreadyPresent = config.hooks.SessionStart.some((group) => Array.isArray(group?.hooks) &&
+            group.hooks.some((h) => typeof h?.command === "string" && h.command.includes(SESSION_START_HOOK_MARKER)));
+        if (alreadyPresent) {
+            return { ok: true, path, message: `already present in ${path}` };
+        }
+        config.hooks.SessionStart.push({
+            hooks: [
+                {
+                    type: "command",
+                    command: `FLAIR_AGENT_ID=${agentId} npx -y @tpsdev-ai/flair-mcp flair-session-start`,
+                },
+            ],
+        });
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+        return { ok: true, path, message: `added SessionStart hook to ${path} (agent '${agentId}')` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, message: `could not write ${path}: ${reason}` };
+    }
+}
+function indentLines(s) {
+    return s
+        .split("\n")
+        .map((l) => `     ${l}`)
+        .join("\n");
+}
+/**
+ * Apply-or-report for the CLAUDE.md bootstrap leg. Idempotent: a second call
+ * after the line is present (whether from a prior call or already there)
+ * reports ok:true, applied:false — safe to call on every `flair init`.
+ */
+export function applyOrReportClaudeMdBootstrap(cwd, homeDir, skip) {
+    const existing = checkClaudeMdBootstrap(cwd, homeDir);
+    if (existing.present) {
+        return { applied: false, ok: true, message: `CLAUDE.md already has the bootstrap instruction (${existing.path})` };
+    }
+    const hint = `Add to your CLAUDE.md:\n${indentLines(CLAUDE_MD_BOOTSTRAP_LINE)}`;
+    if (skip) {
+        return { applied: false, ok: false, message: "CLAUDE.md bootstrap instruction skipped (--skip-claude-md)", hint };
+    }
+    const fix = fixClaudeMdBootstrap(cwd);
+    return { applied: fix.ok, ok: fix.ok, message: fix.message, hint: fix.ok ? undefined : hint };
+}
+function sessionStartHookHint(agentId, path) {
+    const snippet = {
+        hooks: {
+            SessionStart: [
+                {
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `FLAIR_AGENT_ID=${agentId} npx -y @tpsdev-ai/flair-mcp flair-session-start`,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+    return `Add this to ${path}:\n${indentLines(JSON.stringify(snippet, null, 2))}`;
+}
+/**
+ * Apply-or-report for the SessionStart hook leg. Idempotent: a second call
+ * 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);
+    if (existing.present) {
+        return { applied: false, ok: true, message: `SessionStart hook already wired in ${existing.path}` };
+    }
+    const hint = sessionStartHookHint(agentId, existing.path);
+    if (skip) {
+        return { applied: false, ok: false, message: "SessionStart hook skipped (--skip-hook)", hint };
+    }
+    const fix = fixSessionStartHook(homeDir, agentId);
+    return { applied: fix.ok, ok: fix.ok, message: fix.message, hint: fix.ok ? undefined : hint };
+}

package/dist/install/clients.js

@@ -179,6 +179,24 @@ function geminiConfigPath() {
 function codexConfigPath() {
     return join(resolveHome(), ".codex", "config.toml");
 }
+/**
+ * Single dispatcher for "where does this client's MCP 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.
+ */
+export function clientConfigPath(id) {
+    switch (id) {
+        case "claude-code":
+            return join(resolveHome(), ".claude.json");
+        case "codex":
+            return codexConfigPath();
+        case "gemini":
+            return geminiConfigPath();
+        case "cursor":
+            return cursorConfigPath();
+    }
+}
 // ---- Internal wiring functions --------------------------------------------------
 //
 // Claude Code wiring lives inline in src/cli.ts (it writes ~/.claude.json, the