@tpsdev-ai/flair 0.20.1 → 0.22.0

package/dist/deploy.js

@@ -8,7 +8,6 @@ import { createRequire } from "node:module";
 export const REQUIRED_PACKAGE_FILES = [
     "dist",
     "schemas",
-    "ui",
     "config.yaml",
 ];
 // harper's own deploy CLI defaults to a 120s peer-replication timeout that's
@@ -39,9 +38,9 @@ export function validateOptions(opts) {
     const hasBasic = !!(opts.fabricUser && opts.fabricPassword);
     const hasBearer = !!opts.fabricToken;
     if (!hasBasic && !hasBearer) {
-        errors.push("credentials required: pass --fabric-user + --fabric-password " +
-            "(or FABRIC_USER / FABRIC_PASSWORD env), or --fabric-token " +
-            "(FABRIC_TOKEN env)");
+        errors.push("credentials required: set FABRIC_USER + FABRIC_PASSWORD env (safest), or pass " +
+            "--fabric-user + --fabric-password-file <path>, or --fabric-token (FABRIC_TOKEN env); " +
+            "inline --fabric-user/--fabric-password also work but leak to shell history");
     }
     return errors;
 }
@@ -187,7 +186,7 @@ function resolveHarperBin(packageRoot) {
 export function buildHarperDeployArgs(opts, url, project) {
     const deploymentTimeoutMs = opts.deploymentTimeoutMs ?? DEFAULT_DEPLOYMENT_TIMEOUT_MS;
     const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
-    return [
+    const args = [
         "deploy",
         `target=${url}`,
         `project=${project}`,
@@ -196,26 +195,108 @@ export function buildHarperDeployArgs(opts, url, project) {
         `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;
 }
-function spawnHarper(bin, args, cwd, env) {
+// 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
@@ -321,7 +402,7 @@ export async function deploy(opts) {
         CLI_TARGET_USERNAME: opts.fabricUser,
         CLI_TARGET_PASSWORD: opts.fabricPassword,
     };
-    await spawnHarper(harperBin, args, packageRoot, childEnv);
+    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
@@ -337,5 +418,5 @@ export async function deploy(opts) {
             onProgress: opts.onProgress,
         });
     }
-    return { url, project, version, packageRoot, dryRun: false };
+    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/fleet-presence.js

@@ -0,0 +1,98 @@
+// ─── Doctor: fleet presence / instance staleness (flair#639) ────────────────────
+//
+// `flair doctor` diagnosed a single instance only. Auto-presence (flair#608)
+// gives every agent a heartbeat, and each heartbeat now carries the SERVING
+// instance's own flair + harper version (resources/Presence.ts,
+// buildPresenceRecord()) — so the /Presence roster doubles as an org-level
+// fleet-version report, IF something reads it that way. This module is that
+// reading: pure classification over an already-fetched roster, no network,
+// no crypto, so it's fast and fully unit-testable in isolation — same split
+// as doctor-client.ts (pure logic here; the network fetch + Ed25519 signing
+// stay in src/cli.ts alongside authFetch/buildEd25519Auth, which they reuse).
+//
+// Deliberately NOT npm-latest aware: comparing against the newest version
+// PUBLISHED is version-nudge's job (src/version-check.ts, flair#587/#594).
+// This is comparing instances against EACH OTHER — "is anyone behind the
+// rest of the fleet" — which stays meaningful even fully offline, and is the
+// question flair#639 actually asks: an org-level answer without probing
+// every host by hand.
+//
+// Semver comparison reuses fabric-upgrade.ts's parseSemverCore/semverGte
+// (major.minor.patch only, pre-release/build suffixes ignored) — the one
+// semver implementation in this codebase; duplicating it here would risk the
+// two drifting on an edge case.
+import { parseSemverCore, semverGte } from "./fabric-upgrade.js";
+/** True only for a non-empty, parseable semver string — the one predicate every
+ *  function below needs, so it lives in exactly one place. */
+function hasParsableVersion(v) {
+    return typeof v === "string" && parseSemverCore(v) !== null;
+}
+/**
+ * Newest flairVersion seen across the roster. Entries with no (or an
+ * unparseable) version are excluded from the computation — an unversioned
+ * record can't be compared, so it can't set the bar. Returns null when NO
+ * entry in the roster reports a parseable version (nothing to compare
+ * against — e.g. a fleet that's entirely pre-flair#639, or a roster with a
+ * single unversioned instance).
+ */
+export function newestVersionSeen(rows) {
+    let newest = null;
+    for (const row of rows) {
+        if (!hasParsableVersion(row.flairVersion))
+            continue;
+        if (newest === null || semverGte(row.flairVersion, newest))
+            newest = row.flairVersion;
+    }
+    return newest;
+}
+/**
+ * Flag each roster row as stale relative to the newest flairVersion seen
+ * ACROSS THE WHOLE ROSTER (never against npm-latest — see module doc). A row
+ * is stale when:
+ *   - the roster has SOME newest version to compare against (newest !== null)
+ *     AND
+ *   - this row has no parseable version of its own (an older, pre-flair#639
+ *     instance — the loudest possible skew signal), OR its version is older
+ *     than the newest seen.
+ *
+ * A single-instance roster, or a roster where every instance reports the
+ * IDENTICAL version, has nothing to compare against → newest equals every
+ * row's own version (or is null) → nothing is flagged stale. A roster where
+ * NO instance has ever reported a version (newest === null) similarly flags
+ * nothing — there's no fleet-relative signal yet, only an org-wide gap this
+ * function can't see (that's what the "pass --agent to reveal versions" /
+ * "no versions reported yet" doctor messaging is for, not staleness).
+ */
+export function markStale(rows) {
+    const newest = newestVersionSeen(rows);
+    return rows.map((row) => {
+        const stale = newest !== null && (!hasParsableVersion(row.flairVersion) || !semverGte(row.flairVersion, newest));
+        return { ...row, stale, newestVersion: newest };
+    });
+}
+/**
+ * Sort oldest-version-first so problems top the listing (flair#639's stated
+ * requirement). Rows with no parseable version sort FIRST — an unversioned
+ * instance is the biggest unknown in the fleet, not a middling one, and
+ * markStale() always flags it stale whenever the roster has any signal at
+ * all, so surfacing it first keeps the "problems on top" contract even when
+ * mixed with real-but-old versions. Ties (equal versions) preserve roster
+ * order (stable sort).
+ */
+export function sortOldestVersionFirst(rows) {
+    return [...rows].sort((a, b) => {
+        const pa = hasParsableVersion(a.flairVersion) ? parseSemverCore(a.flairVersion) : null;
+        const pb = hasParsableVersion(b.flairVersion) ? parseSemverCore(b.flairVersion) : null;
+        if (!pa && !pb)
+            return 0;
+        if (!pa)
+            return -1;
+        if (!pb)
+            return 1;
+        for (let i = 0; i < 3; i++) {
+            if (pa[i] !== pb[i])
+                return pa[i] - pb[i];
+        }
+        return 0;
+    });
+}