@tpsdev-ai/flair 0.51.1 → 0.52.0

package/dist/doctor-client.js

@@ -839,6 +839,41 @@ export function detectWiredFlairMcp(homeDir) {
     }
     return { wired, pinnedVersion };
 }
+/** The `@tpsdev-ai/flair-mcp` version pinned in a client's MCP config, or null
+ *  when the client is unwired or wired unpinned. */
+export function readClientMcpPin(clientId, homeDir) {
+    const configPath = withHome(homeDir, () => clientConfigPath(clientId));
+    return extractFlairMcpPin(readTextFile(configPath) ?? "");
+}
+/**
+ * Compare a harness's SessionStart hook pin against its MCP client pin.
+ *
+ * `flair init`/`flair upgrade`/`flair hook install` keep both on the same
+ * @version. A skew means an upgrade moved the client block forward but left
+ * the hook behind (flair#1516) — so every session silently launches the OLD
+ * adapter while the client block advertises the new one. `flair doctor` used
+ * to report such a hook as wired "and still runs" without ever comparing the
+ * two pins.
+ *
+ * Only a concrete-vs-concrete difference is a skew: an unpinned hook (pre-
+ * #1143) or a missing pin on either side is "nothing to compare", never a
+ * false skew.
+ */
+export function checkSessionStartHookPinSkew(homeDir, harness) {
+    const hookPath = harness === "codex"
+        ? join(homeDir, ".codex", "hooks.json")
+        : join(homeDir, ".claude", "settings.json");
+    const hook = checkSessionStartHook(homeDir, hookPath);
+    const hookWired = hook.present && isFlairHookCommand(hook.command ?? "");
+    const hookPin = hookWired ? extractFlairMcpPin(hook.command ?? "") : null;
+    const clientPin = readClientMcpPin(harness, homeDir);
+    return {
+        hookWired,
+        hookPin,
+        clientPin,
+        skewed: !!hookPin && !!clientPin && hookPin !== clientPin,
+    };
+}
 /**
  * Merge-safe insert of a Flair SessionStart hook group into the harness
  * settings file (default ~/.claude/settings.json) — creates the file/array

package/dist/hook-install.js

@@ -55,6 +55,7 @@
 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, isSessionStartHookInvocation, readClientMcpBlock, } from "./doctor-client.js";
+import { mcpServerSpec } from "./lib/mcp-spec.js";
 // ── harness registry ────────────────────────────────────────────────────────
 /** SessionStart hook harnesses. A second harness is an additive registry
  *  entry, not a rewrite (Kern's #719 verdict: "a switch statement... is
@@ -352,6 +353,79 @@ export function installHook(opts) {
         backupPath, delta,
     };
 }
+/**
+ * Re-pin an ALREADY-WIRED Flair SessionStart hook to the current
+ * mcpServerSpec(), preserving the agent id and Flair URL the entry already
+ * carries.
+ *
+ * This is `flair upgrade`'s hook counterpart to refreshing the MCP client
+ * pins (flair#1516). `flair upgrade` re-pins every wired client's MCP block
+ * to the new @version but used to leave the SessionStart hook command on the
+ * OLD one — so a user who upgraded by the documented path kept launching the
+ * previous adapter on every session, silently, while `flair doctor` reported
+ * the hook "still runs" without noticing the skew.
+ *
+ * NEVER adds a hook — a home with no Flair hook is a clean `skip`, not an
+ * `add`: wiring a hook is `flair init` / `flair hook install`, an opt-in the
+ * upgrade path must not make on the user's behalf. Only rewrites the exact
+ * canonical `npx -y -p …` invocation Flair itself writes (pinned or the
+ * pre-#1143 unpinned form); a hand-edited command is the user's and is left
+ * untouched. Fail-closed on a malformed settings file and backs up before any
+ * real write — the same Sherlock conditions installHook implements. Idempotent:
+ * a second call is a `noop`.
+ */
+export function repinSessionStartHook(homeDir, harness) {
+    const path = hookSettingsPath(homeDir, harness);
+    const skip = (ok, message) => ({ ok, path, harness, action: "skip", message, backupPath: null });
+    const read = readSettingsFile(path);
+    if (read.parseError) {
+        return skip(false, `${read.parseError} — refusing to re-pin a file we can't safely parse; left untouched`);
+    }
+    const config = read.parsed ?? {};
+    const existing = findHookEntry(config);
+    if (!existing) {
+        return skip(true, `no Flair SessionStart hook in ${path} — nothing to re-pin`);
+    }
+    const current = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex]?.command ?? "";
+    // Only re-pin the canonical invocation Flair writes. A legacy (pre-#1143,
+    // no `-p`) or hand-edited command is NOT version-bumped here — `flair
+    // doctor`/`flair hook install` own the legacy → current rewrite, with their
+    // own consent.
+    if (!isSessionStartHookInvocation(current)) {
+        return skip(true, `SessionStart hook in ${path} is not the canonical form Flair writes — left untouched`);
+    }
+    const env = parseHookCommandEnv(current);
+    if (!env.agentId) {
+        return skip(true, `could not read the agent id from the SessionStart hook in ${path} — left untouched`);
+    }
+    let next;
+    try {
+        next = buildSessionStartHookCommand(env.agentId, env.flairUrl);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return skip(false, `could not rebuild the SessionStart hook command for ${path}: ${reason}`);
+    }
+    if (next === current) {
+        return { ok: true, path, harness, action: "noop", message: `SessionStart hook in ${path} already pinned to ${mcpServerSpec()}`, backupPath: null };
+    }
+    let backupPath = null;
+    try {
+        backupPath = takeBackup(path);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return skip(false, `could not back up ${path} before re-pinning it: ${reason} — refusing to touch it`);
+    }
+    const newConfig = deepClone(config);
+    newConfig.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex] = { type: "command", command: next };
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+    return {
+        ok: true, path, harness, action: "update",
+        message: `re-pinned the SessionStart hook in ${path} to ${mcpServerSpec()}`,
+        backupPath,
+    };
+}
 /** Symmetric removal — deletes ONLY our hook entry (found the same way
  *  install finds it: SESSION_START_HOOK_MARKER substring match), never
  *  touches unrelated hooks/keys. A no-op (ok:true, action "noop") when

package/dist/install/global-bin-path.js

@@ -145,6 +145,20 @@ export function prefixFromPackageDir(packageDir, platform = process.platform) {
     const kept = segments.slice(0, Math.max(1, segments.length - ups));
     return kept.join(win32 ? "\\" : "/") || (win32 ? packageDir : "/");
 }
+/**
+ * Inverse of {@link prefixFromPackageDir}: where a global
+ * `@tpsdev-ai/flair` install lives under `prefix`.
+ *
+ * String-based (not path.join) so the win32 shape stays faithful even in
+ * tests running on posix hosts.
+ */
+export function npmGlobalFlairPackageDir(prefix, platform = process.platform) {
+    const win32 = platform === "win32";
+    const clean = stripTrailingSeps(prefix.trim(), win32);
+    return win32
+        ? [clean, "node_modules", "@tpsdev-ai", "flair"].join("\\")
+        : [clean, "lib", "node_modules", "@tpsdev-ai", "flair"].join("/");
+}
 function defaultBinDirHasFlair(binDir, platform) {
     const names = platform === "win32" ? ["flair.cmd", "flair"] : ["flair"];
     return names.some((n) => existsSync(join(binDir, n)));

package/dist/lib/auth-resolve.js

@@ -445,6 +445,21 @@ export async function authedRequest(method, path, body, opts) {
             console.error(`Warning: Ed25519 auth failed for agent '${opts.agentId}': ${message}`);
         }
     }
+    // Tier 1.5: flag-pinned agent (flair#1500) — an --agent flag identity signs
+    // as THAT agent BEFORE env admin. A flag-pinned agent with no key on disk is
+    // a hard error (never a warning, never a silent substitution to env admin or
+    // the local admin-pass file): the operator named a specific identity and the
+    // CLI must not quietly sign as someone else.
+    if (!authHeader && opts.agentIdSource === "flag" && opts.agentId) {
+        const keyPath = resolveKeyPath(opts.agentId);
+        if (!keyPath) {
+            throw new Error(`--agent '${opts.agentId}' has no signing key. Expected a key at ` +
+                `${join(defaultKeysDir(), `${opts.agentId}.key`)} (or set FLAIR_KEY_DIR ` +
+                `to a directory containing it). Refusing to fall back to FLAIR_ADMIN_PASS ` +
+                `or the local admin-pass file.`);
+        }
+        authHeader = buildEd25519Auth(opts.agentId, method, path, keyPath);
+    }
     // Tier 2: env — FLAIR_TOKEN (Bearer), else FLAIR_ADMIN_PASS/HDB_ADMIN_PASSWORD (Basic).
     if (!authHeader) {
         if (process.env.FLAIR_TOKEN) {

package/dist/lib/doctor-run.js

@@ -53,19 +53,24 @@ function runMcpBlock(ctx) {
     if (mcp.length === 0) {
         return result(id, label, "skip", { detail: "no MCP client detected" });
     }
-    const missing = [];
-    for (const clientId of mcp) {
-        const block = readClientMcpBlock(clientId, ctx.homeDir);
-        if (!block.present)
-            missing.push(`${clientId} (${block.configPath})`);
-    }
-    if (missing.length > 0) {
-        return result(id, label, "fail", {
-            detail: `no Flair MCP server configured: ${missing.join(", ")}`,
-            remedy: "flair doctor --fix",
+    // flair#989: DETECTION is not OPT-IN. A client whose binary or config merely
+    // exists on the box — e.g. Codex is installed but the user ran `flair init
+    // --client claude-code` — is not an install FAILURE for lacking a Flair
+    // block; it was never opted into. The MCP block IS the opt-in signal, so the
+    // install-health subject is the WIRED clients only. An un-wired but detected
+    // client is surfaced as info by `flair doctor`, never counted as a failure
+    // here (which used to inflate the ✗ count with clients the user never chose).
+    const wired = mcp.filter((clientId) => readClientMcpBlock(clientId, ctx.homeDir).present);
+    if (wired.length === 0) {
+        // Detected clients exist, but Flair is wired to none of them. Not a
+        // per-client failure (nothing was opted in) — a skip that names the
+        // detected clients, so a zero-wiring run neither invents a failure the
+        // user didn't cause nor masquerades as a verified-healthy wiring.
+        return result(id, label, "skip", {
+            detail: `no Flair MCP server wired into any detected client (${mcp.join(", ")}) — wire one with: flair init --client <id>`,
         });
     }
-    return result(id, label, "pass", { detail: `configured for ${mcp.join(", ")}` });
+    return result(id, label, "pass", { detail: `configured for ${wired.join(", ")}` });
 }
 function runFlairUrl(ctx) {
     const id = "flair-url";
@@ -91,8 +96,11 @@ function runFlairUrl(ctx) {
 function runClaudeMd(ctx) {
     const id = "claude-md";
     const label = "CLAUDE.md bootstrap";
-    if (!ctx.detectedClientIds.includes("claude-code")) {
-        return result(id, label, "skip", { detail: "Claude Code not detected" });
+    // flair#989: only relevant once Claude Code is actually WIRED. A Claude Code
+    // binary merely present on the box (never `flair init`-ed) does not owe a
+    // CLAUDE.md bootstrap line — same opt-in rule as runMcpBlock/runSessionStartHook.
+    if (!ctx.detectedClientIds.includes("claude-code") || !readClientMcpBlock("claude-code", ctx.homeDir).present) {
+        return result(id, label, "skip", { detail: "Claude Code not wired" });
     }
     const check = checkClaudeMdBootstrap(ctx.cwd, ctx.homeDir);
     if (!check.present) {
@@ -106,9 +114,14 @@ function runClaudeMd(ctx) {
 function runSessionStartHook(ctx) {
     const id = "session-start-hook";
     const label = "SessionStart hook";
-    const harnesses = SUPPORTED_HARNESSES.filter((h) => ctx.detectedClientIds.includes(h));
+    // flair#989: only a harness the user actually WIRED (its MCP block is
+    // present) owes a SessionStart hook. A merely-detected harness — Codex on
+    // PATH that was never `flair init`-ed — is not an install failure for
+    // lacking a hook it was never asked to have. This mirrors runMcpBlock's
+    // opt-in rule so a detected-but-unwired client can't fail either check.
+    const harnesses = SUPPORTED_HARNESSES.filter((h) => ctx.detectedClientIds.includes(h) && readClientMcpBlock(h, ctx.homeDir).present);
     if (harnesses.length === 0) {
-        return result(id, label, "skip", { detail: "no hook-capable client detected" });
+        return result(id, label, "skip", { detail: "no wired hook-capable client detected" });
     }
     const missing = [];
     const loud = [];

package/dist/lib/upgrade-exec-path.js

@@ -0,0 +1,257 @@
+/**
+ * upgrade-exec-path.ts — flair#1109 (b)
+ *
+ * `flair upgrade` reports and upgrades the npm-global `@tpsdev-ai/flair`
+ * package. A host can also be serving from a different exec path — a plain
+ * extracted tree (npm pack + tar under systemd), a checkout, a second prefix.
+ * When those paths differ, the npm-global listing is not "the" install: it
+ * may be a stale relic, and upgrading it will not touch the tree serving
+ * traffic.
+ *
+ * This module is detection and wording only. It does not add an in-place
+ * tarball-swap upgrade lane (that is #1109 (a), kept elsewhere).
+ *
+ * Everything that classifies or formats is pure and dependency-injected
+ * except the default /proc and lsof readers used when the CLI asks about a
+ * live pid.
+ */
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { npmGlobalFlairPackageDir } from "../install/global-bin-path.js";
+/** The CLI / server package whose install path we are comparing. */
+export const FLAIR_PACKAGE = "@tpsdev-ai/flair";
+const PROCESS_PROBE_TIMEOUT_MS = 2000;
+/**
+ * Walk up from `startPath` looking for `@tpsdev-ai/flair`'s own package.json.
+ *
+ * Named search, not a hop count: a harper bin lives several levels under
+ * the package root, a CLI script lives at `dist/cli.js`, and a serving
+ * cwd may already BE the package root. Checking `name` means an intermediate
+ * `package.json` (harper, a workspace) cannot be mistaken for ours.
+ */
+export function findFlairPackageDir(startPath) {
+    let dir;
+    try {
+        const st = statSync(startPath);
+        dir = st.isDirectory() ? startPath : dirname(startPath);
+    }
+    catch {
+        dir = startPath;
+    }
+    for (let i = 0; i < 8; i++) {
+        const loc = readFlairPackageAt(dir);
+        if (loc)
+            return loc;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Read `@tpsdev-ai/flair` at exactly `dir`, or null if it is not that package. */
+export function readFlairPackageAt(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf-8"));
+        if (pkg?.name !== FLAIR_PACKAGE)
+            return null;
+        return {
+            dir: canonicalPath(dir),
+            version: typeof pkg.version === "string" && pkg.version ? pkg.version : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Canonical path for equality: realpath when it exists, else lexical resolve. */
+export function canonicalPath(p) {
+    const resolved = resolve(p);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+export function sameInstallPath(a, b) {
+    return canonicalPath(a) === canonicalPath(b);
+}
+/**
+ * Path-shaped tokens from a process command line (null- or space-separated).
+ * Flags and bare words (`run`, `.`) are dropped — they are not exec paths.
+ */
+export function extractPathHints(cmdline) {
+    return cmdline
+        .split(/\0|\s+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0)
+        .filter((t) => {
+        if (t.startsWith("-"))
+            return false;
+        if (t.startsWith("/") || t.startsWith("\\"))
+            return true;
+        if (/^[A-Za-z]:[\\/]/.test(t))
+            return true;
+        if (t.includes("node_modules") || t.includes("/") || t.includes("\\"))
+            return true;
+        return false;
+    });
+}
+export function defaultReadProcessCwd(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        return realpathSync(`/proc/${pid}/cwd`);
+    }
+    catch {
+        try {
+            const out = execFileSync("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], {
+                encoding: "utf-8",
+                timeout: PROCESS_PROBE_TIMEOUT_MS,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            const m = String(out).match(/^n(.+)$/m);
+            return m ? m[1] : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export function defaultReadProcessCmdline(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        return readFileSync(`/proc/${pid}/cmdline`, "utf-8");
+    }
+    catch {
+        try {
+            const out = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+                encoding: "utf-8",
+                timeout: PROCESS_PROBE_TIMEOUT_MS,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            const trimmed = String(out).trim();
+            return trimmed === "" ? null : trimmed;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Locate the `@tpsdev-ai/flair` tree a live pid is executing from.
+ *
+ * Prefers cwd (Harper is spawned with `cwd: <package dir>`), then path
+ * tokens on the command line (the harper bin lives under that tree).
+ * Returns null when neither hint resolves to our package — never guesses.
+ */
+export function resolveServingFlairPackage(pid, hooks = {}) {
+    const readCwd = hooks.readCwd ?? defaultReadProcessCwd;
+    const readCmdline = hooks.readCmdline ?? defaultReadProcessCmdline;
+    const hints = [];
+    try {
+        const cwd = readCwd(pid);
+        if (cwd)
+            hints.push(cwd);
+    }
+    catch { /* injected readers must not fail the check */ }
+    try {
+        const cmdline = readCmdline(pid);
+        if (cmdline)
+            hints.push(...extractPathHints(cmdline));
+    }
+    catch { /* same */ }
+    for (const hint of hints) {
+        const found = findFlairPackageDir(hint);
+        if (found)
+            return found;
+    }
+    return null;
+}
+export function resolveNpmGlobalFlairPackage(prefix, platform = process.platform) {
+    if (!prefix || prefix.trim() === "")
+        return null;
+    return readFlairPackageAt(npmGlobalFlairPackageDir(prefix, platform));
+}
+/**
+ * `prefixKnown` is true only when `npm prefix -g` actually returned a
+ * prefix. A failed/absent probe is not "the global package is missing" —
+ * that is `unknown` (no warning). A known prefix with no `@tpsdev-ai/flair`
+ * under it is a real mismatch.
+ */
+export function classifyExecPathVsNpmGlobal(input) {
+    const running = input.serving ?? input.cli;
+    if (!running)
+        return { kind: "unknown" };
+    if (!input.prefixKnown)
+        return { kind: "unknown" };
+    const source = input.serving ? "serving-instance" : "this-cli";
+    if (input.global && sameInstallPath(running.dir, input.global.dir)) {
+        return { kind: "match", runningPath: running.dir, globalPath: input.global.dir, source };
+    }
+    return {
+        kind: "mismatch",
+        runningPath: running.dir,
+        runningVersion: running.version,
+        globalPath: input.global?.dir ?? null,
+        globalVersion: input.global?.version ?? null,
+        source,
+    };
+}
+function versionLabel(version) {
+    return version ? `  (${version})` : "";
+}
+/**
+ * Operator-facing warning. Names both paths (and versions when readable)
+ * and says what `flair upgrade` will and will not touch. Does not propose
+ * an in-place tarball swap — that lane is out of scope for (b).
+ */
+export function formatExecPathMismatchWarning(check) {
+    if (check.kind !== "mismatch")
+        return null;
+    const subject = check.source === "serving-instance"
+        ? "The running instance's exec path is not the npm-global install."
+        : "This CLI's exec path is not the npm-global install.";
+    const runningLabel = check.source === "serving-instance" ? "Running" : "This CLI";
+    const lines = [
+        `⚠️  ${subject}`,
+        `   ${runningLabel}:  ${check.runningPath}${versionLabel(check.runningVersion)}`,
+    ];
+    if (check.globalPath) {
+        lines.push(`   npm-global: ${check.globalPath}${versionLabel(check.globalVersion)}`);
+    }
+    else {
+        lines.push("   npm-global: not installed (no @tpsdev-ai/flair under the npm global prefix)");
+    }
+    lines.push("   `flair upgrade` only upgrades the npm-global packages. The tree serving traffic is unchanged.");
+    return lines.join("\n");
+}
+/**
+ * The one function `flair upgrade` calls. Best-effort: a missing pid, a
+ * missing prefix, or an unreadable /proc entry degrades to "unknown"
+ * (no warning) rather than failing the command.
+ */
+export function collectUpgradeExecPathWarning(input) {
+    try {
+        const prefixKnown = typeof input.npmGlobalPrefix === "string" && input.npmGlobalPrefix.trim() !== "";
+        const serving = input.servingPid != null
+            ? resolveServingFlairPackage(input.servingPid, input.hooks)
+            : null;
+        const cli = findFlairPackageDir(input.cliPackageDir);
+        const global = prefixKnown
+            ? resolveNpmGlobalFlairPackage(input.npmGlobalPrefix, input.platform ?? process.platform)
+            : null;
+        return formatExecPathMismatchWarning(classifyExecPathVsNpmGlobal({
+            serving,
+            cli,
+            global,
+            prefixKnown,
+        }));
+    }
+    catch {
+        return null;
+    }
+}