@tpsdev-ai/flair 0.34.0 → 0.36.0

package/config.yaml

@@ -81,3 +81,20 @@ authentication:
   # own risk.
   authorizeLocal: false
   enableSessions: true
+
+# @harperfast/oauth — authorization server component declaration.
+# Commented out by default: the plugin is only needed when FLAIR_MCP_OAUTH=on.
+# When you enable the flag without uncommenting this block, the boot guard
+# (resources/mcp-oauth.ts) logs an error with the exact YAML to add — uncomment
+# the block below and add mcp.* config. The issuer is derived at runtime from
+# FLAIR_MCP_ISSUER / FLAIR_PUBLIC_URL; do not hardcode one here.
+#
+# "@harperfast/oauth":
+#   providers:
+#     default:
+#       authorizationEndpoint: "/OAuthAuthorize"
+#       tokenEndpoint: "/OAuthToken"
+#       revocationEndpoint: "/OAuthRevoke"
+#       registrationEndpoint: "/OAuthRegister"
+#       jwksUri: "/.well-known/jwks.json"
+#       discoveryEndpoint: "/.well-known/oauth-authorization-server"

package/dist/cli.js

@@ -14,6 +14,7 @@ import { deploy as deployToFabric, validateOptions as validateDeployOptions, bui
 import { COMPONENT_ENV_FILENAME, PUBLIC_URL_KEY, assertNoSecretKeysAdded, describePublicUrlFinding, planComponentEnv, readEnvValue, } from "./component-env.js";
 import { fabricUpgrade } from "./fabric-upgrade.js";
 import { checkVersion, formatVersionNudge, primeVersionCheckCache, FLAIR_PKG_NAME } from "./version-check.js";
+import { readInstalledHarperVersion, fetchDeclaredHarperVersion, writeEngineVersionStamp, checkEngineVersionBackwards, UPGRADE_SNAPSHOT_ROOT, } from "./engine-version.js";
 import { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache } from "./version-handshake.js";
 import { probeInstance } from "./probe.js";
 import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verify.js";
@@ -8823,7 +8824,8 @@ async function runFabricUpgrade(opts) {
 // standalone filesystem utility). Rejected in favor of the file-level
 // snapshot below. See docs/upgrade.md for the restore procedure this
 // produces.
-const UPGRADE_SNAPSHOT_ROOT = resolve(homedir(), ".flair", "upgrade-snapshots");
+// UPGRADE_SNAPSHOT_ROOT is defined in engine-version.ts (the module that owns the path)
+// and imported from there for all callers.
 const UPGRADE_SNAPSHOT_RETAIN = 3;
 function upgradeSnapshotFileName() {
     const ts = new Date().toISOString().replace(/[:.]/g, "-");
@@ -8947,9 +8949,12 @@ export function pruneOldSnapshots(retain = UPGRADE_SNAPSHOT_RETAIN, snapshotRoot
     }
     return removed;
 }
-export function decideUpgradeSnapshotAction(flairIsUpgrading, snapshotRequested, hasDataDir) {
+export function decideUpgradeSnapshotAction(flairIsUpgrading, snapshotRequested, hasDataDir, engineVersionChanging, engineSnapshotOptOut) {
     if (!flairIsUpgrading)
         return "not-upgrading";
+    // Engine version change forces a snapshot unless explicitly opted out.
+    if (engineVersionChanging && hasDataDir && !engineSnapshotOptOut)
+        return "engine-version-change";
     if (!snapshotRequested)
         return hasDataDir ? "nudge" : "not-upgrading";
     return hasDataDir ? "snapshot" : "no-data";
@@ -8967,6 +8972,75 @@ export const UPGRADE_SNAPSHOT_NUDGE_LINES = [
     "No pre-upgrade snapshot will be taken.",
     "To capture one first: `flair snapshot create` (physical) or `flair backup` (logical export), or re-run with --snapshot.",
 ];
+/**
+ * Run the stop → snapshot → prune → restart dance for a pre-upgrade snapshot.
+ * Extracted from the upgrade action so the --snapshot and engine-version-change
+ * branches share the same mechanism (flair#1047).
+ *
+ * On snapshot failure: aborts the upgrade (process.exit(1)), restarting Flair
+ * first if it was stopped. On restart-after-snapshot failure: also exits.
+ */
+async function runUpgradeSnapshot(port, dataDir) {
+    // Consistency: a running Harper's data dir can be mid-write, and a
+    // plain file copy of a live database directory isn't guaranteed
+    // point-in-time consistent (Harper 5.x = RocksDB: WAL/SST/MANIFEST
+    // can tear under a live copy). Stopping first — then immediately
+    // restarting the OLD version, before any package changes — gives a
+    // quiesced, safe-to-copy directory with only a brief blip, even for
+    // --no-restart (the snapshot's correctness doesn't depend on
+    // whether the caller wants a restart AFTER the upgrade — those are
+    // orthogonal). See docs/upgrade.md for the native-backup alternative
+    // considered and rejected (Harper's `get_backup` op backs up one
+    // table/schema at a time over the running HTTP API — not the whole
+    // data dir — and rejecting it here means this path never depends on
+    // the server being up).
+    let stoppedForSnapshot = false;
+    let snapshotPath = null;
+    try {
+        await stopFlairProcess(port, dataDir);
+        stoppedForSnapshot = true;
+        const snapshot = await createDataSnapshot(dataDir);
+        snapshotPath = snapshot.path;
+        const removed = pruneOldSnapshots();
+        console.log(`✅ Snapshot: ${snapshotPath} (${humanBytes(snapshot.bytes)})`);
+        console.log(`   Restore: flair snapshot restore "${snapshotPath}"`);
+        if (removed.length > 0) {
+            console.log(`   Pruned ${removed.length} older snapshot${removed.length > 1 ? "s" : ""} (keeping last ${UPGRADE_SNAPSHOT_RETAIN})`);
+        }
+    }
+    catch (err) {
+        console.error(`❌ snapshot failed: ${err.message}`);
+        console.error("   Aborting upgrade — no packages were changed.");
+        if (stoppedForSnapshot) {
+            try {
+                await startFlairProcess(port, dataDir);
+            }
+            catch { /* best effort — surface the original snapshot error, not this */ }
+        }
+        process.exit(1);
+    }
+    try {
+        await startFlairProcess(port, dataDir);
+    }
+    catch (err) {
+        console.error(`❌ failed to restart Flair after the pre-upgrade snapshot: ${err.message}`);
+        console.error(`   The snapshot itself succeeded (${snapshotPath}) — no packages were changed. Check: flair doctor`);
+        process.exit(1);
+    }
+}
+/**
+ * Stamp the data directory with the currently-installed Harper engine version
+ * (flair#1047). Called after every successful boot — start, restart, upgrade.
+ * Best-effort: a failure to stamp is not a boot failure.
+ */
+function stampEngineVersionIfRunning(dataDir) {
+    try {
+        const version = readInstalledHarperVersion(flairPackageDir());
+        if (version)
+            writeEngineVersionStamp(dataDir, version);
+    }
+    catch { /* best-effort — stamp failure must not prevent boot */ }
+}
 // ─── flair snapshot ─────────────────────────────────────────────────────────
 // Explicit, first-class surface for the physical data-dir snapshot mechanism
 // above (createDataSnapshot / pruneOldSnapshots / UPGRADE_SNAPSHOT_ROOT).
@@ -9204,6 +9278,7 @@ program
     .option("--no-restart", "Skip the restart after upgrade (stage new packages now, restart later)")
     .option("--no-verify", "Skip post-restart health/version/auth verification (default: verify — so a broken upgrade can't report success; see flair#635)")
     .option("--snapshot", "Take a pre-upgrade ~/.flair/data snapshot before the package swap, keep-last-3 retention (default: off — see `flair snapshot create` to take one by hand, or `flair backup` for a logical export; flair#637)")
+    .option("--no-engine-snapshot", "Skip the pre-upgrade snapshot even when the Harper engine version is changing (flair#1047). The snapshot is automatic on engine-version changes because the tested-downgrade guarantee does not hold across engine boundaries. Opting out prints what is being given up.")
     .option("--all", "Show transitive packages (e.g. flair-client) in the listing — verbose mode for debugging dep versions")
     // ── Fabric upgrade (--target) ────────────────────────────────────────────
     // When --target is passed, upgrade the Flair component DEPLOYED to that
@@ -9457,8 +9532,40 @@ program
     // moved from opt-out to opt-in. `flair snapshot create` (below) exposes
     // the exact same mechanism as a standalone command for anyone who wants
     // one without wrapping it around an upgrade.
+    //
+    // flair#1047: the tested-downgrade guarantee does not hold across engine
+    // version boundaries — a Harper bump is the only realistic source of a
+    // cross-version boot break. When the engine version is changing, the
+    // snapshot is unconditional. Opting out requires --no-engine-snapshot
+    // and prints what is being given up.
     const flairIsUpgrading = npmUpgrades.some((u) => u.pkg === "@tpsdev-ai/flair");
-    const snapshotDecision = decideUpgradeSnapshotAction(flairIsUpgrading, !!opts.snapshot, existsSync(upgradeDataDir));
+    const hasDataDir = existsSync(upgradeDataDir);
+    const flairFinding = findings.find((f) => f.name === "@tpsdev-ai/flair");
+    // Determine whether the engine (Harper) version is changing.
+    let engineVersionChanging = false;
+    let currentEngineVersion = null;
+    let targetEngineVersion = null;
+    if (flairIsUpgrading && hasDataDir) {
+        currentEngineVersion = readInstalledHarperVersion(flairPackageDir());
+        const targetFlairVersion = flairFinding?.latest;
+        if (targetFlairVersion && currentEngineVersion) {
+            targetEngineVersion = await fetchDeclaredHarperVersion(targetFlairVersion);
+            if (targetEngineVersion === null) {
+                // Registry lookup failed — cannot determine the target Harper
+                // version. Assume it might change (safe default) and print why.
+                engineVersionChanging = true;
+                console.log(render.wrap(render.c.dim, `Could not determine the target Harper version from the npm registry — forcing a pre-upgrade snapshot as a precaution.`));
+            }
+            else {
+                engineVersionChanging = targetEngineVersion !== currentEngineVersion;
+            }
+        }
+        else {
+            // Cannot determine — assume it might change (safe default).
+            engineVersionChanging = true;
+        }
+    }
+    const snapshotDecision = decideUpgradeSnapshotAction(flairIsUpgrading, !!opts.snapshot, hasDataDir, engineVersionChanging, !!opts.noEngineSnapshot);
     let snapshotPath = null;
     if (snapshotDecision === "nudge") {
         // Non-blocking nudge only — never prompt/block here, this must stay
@@ -9473,53 +9580,20 @@ program
     else if (snapshotDecision === "no-data") {
         console.log(`\n(no data directory at ${upgradeDataDir} yet — nothing to snapshot)`);
     }
+    else if (snapshotDecision === "engine-version-change") {
+        // Engine version is changing — snapshot is unconditional (flair#1047).
+        // The operator can opt out with --no-engine-snapshot, which prints what
+        // is being given up (handled in the nudge branch above).
+        const fromLabel = currentEngineVersion ?? "unknown";
+        const toLabel = targetEngineVersion ?? "unknown";
+        console.log(`\nHarper engine version changing (${fromLabel} → ${toLabel}) — snapshotting data before upgrade...`);
+        console.log(render.wrap(render.c.dim, "The tested-downgrade guarantee does not hold across engine version boundaries."));
+        console.log(render.wrap(render.c.dim, "Pass --no-engine-snapshot to skip this (not recommended)."));
+        await runUpgradeSnapshot(upgradePort, upgradeDataDir);
+    }
     else if (snapshotDecision === "snapshot") {
         console.log("\nSnapshotting data before upgrade...");
-        // Consistency: a running Harper's data dir can be mid-write, and a
-        // plain file copy of a live database directory isn't guaranteed
-        // point-in-time consistent (Harper 5.x = RocksDB: WAL/SST/MANIFEST
-        // can tear under a live copy). Stopping first — then immediately
-        // restarting the OLD version, before any package changes — gives a
-        // quiesced, safe-to-copy directory with only a brief blip, even for
-        // --no-restart (the snapshot's correctness doesn't depend on
-        // whether the caller wants a restart AFTER the upgrade — those are
-        // orthogonal). See docs/upgrade.md for the native-backup alternative
-        // considered and rejected (Harper's `get_backup` op backs up one
-        // table/schema at a time over the running HTTP API — not the whole
-        // data dir — and rejecting it here means this path never depends on
-        // the server being up).
-        let stoppedForSnapshot = false;
-        try {
-            await stopFlairProcess(upgradePort, upgradeDataDir);
-            stoppedForSnapshot = true;
-            const snapshot = await createDataSnapshot(upgradeDataDir);
-            snapshotPath = snapshot.path;
-            const removed = pruneOldSnapshots();
-            console.log(`✅ Snapshot: ${snapshotPath} (${humanBytes(snapshot.bytes)})`);
-            console.log(`   Restore: flair snapshot restore "${snapshotPath}"`);
-            if (removed.length > 0) {
-                console.log(`   Pruned ${removed.length} older snapshot${removed.length > 1 ? "s" : ""} (keeping last ${UPGRADE_SNAPSHOT_RETAIN})`);
-            }
-        }
-        catch (err) {
-            console.error(`❌ snapshot failed: ${err.message}`);
-            console.error("   Aborting upgrade — no packages were changed. Omit --snapshot to proceed without one (not recommended).");
-            if (stoppedForSnapshot) {
-                try {
-                    await startFlairProcess(upgradePort, upgradeDataDir);
-                }
-                catch { /* best effort — surface the original snapshot error, not this */ }
-            }
-            process.exit(1);
-        }
-        try {
-            await startFlairProcess(upgradePort, upgradeDataDir);
-        }
-        catch (err) {
-            console.error(`❌ failed to restart Flair after the pre-upgrade snapshot: ${err.message}`);
-            console.error(`   The snapshot itself succeeded (${snapshotPath}) — no packages were changed. Check: flair doctor`);
-            process.exit(1);
-        }
+        await runUpgradeSnapshot(upgradePort, upgradeDataDir);
     }
     // Perform upgrade. `latest` comes from the npm registry's HTTP
     // response, so CodeQL (correctly) treats it as untrusted input.
@@ -9571,7 +9645,6 @@ program
     // --restart is kept as a deprecated no-op for old muscle memory.
     // Upgrade = install → restart → verify → (rollback on failure), one
     // transaction — never report success on a broken restart.
-    const flairFinding = findings.find((f) => f.name === "@tpsdev-ai/flair");
     const previousFlairVersion = flairFinding?.installed ?? null;
     const expectedFlairVersion = flairFinding?.status === "outdated" && !flairInstallFailed
         ? flairFinding.latest
@@ -9880,6 +9953,16 @@ program
         console.error("❌ No Flair data directory found. Run 'flair init' first.");
         process.exit(1);
     }
+    // flair#1047: refuse to boot if the store was written by a newer engine.
+    const runningHarperVersion = readInstalledHarperVersion(flairPackageDir());
+    if (runningHarperVersion) {
+        const backwardsError = checkEngineVersionBackwards(dataDir, runningHarperVersion);
+        if (backwardsError) {
+            console.error(`❌ Cannot start Flair — the data directory was written by a newer Harper engine.\n`);
+            console.error(backwardsError);
+            process.exit(1);
+        }
+    }
     const platform = process.platform;
     if (platform === "darwin") {
         // resolveLaunchdLabel (flair#693) finds whichever label this data
@@ -9902,6 +9985,7 @@ program
                     console.log(`Migrated launchd service off the legacy label (${LEGACY_LAUNCHD_LABEL}) → ${label} ✓`);
                 await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
                 readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture on the freshly-created socket
+                stampEngineVersionIfRunning(dataDir); // flair#1047: stamp the store with the engine version
                 console.log("✅ Flair started (launchd)");
                 return;
             }
@@ -9942,6 +10026,7 @@ program
     try {
         await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
         readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture on the freshly-created socket
+        stampEngineVersionIfRunning(dataDir); // flair#1047: stamp the store with the engine version
         console.log(`✅ Flair started on port ${port}`);
     }
     catch {
@@ -10275,6 +10360,7 @@ async function startFlairProcess(port, dataDir) {
                 ensureLaunchdServiceLoaded(dataDir, (cmd) => execSync(cmd, { stdio: "pipe" }));
                 await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
                 readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture across restart/upgrade
+                stampEngineVersionIfRunning(dataDir); // flair#1047: stamp the store with the engine version
                 return;
             }
             catch (err) {
@@ -10322,6 +10408,7 @@ async function startFlairProcess(port, dataDir) {
     proc.unref();
     await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
     readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture across restart/upgrade
+    stampEngineVersionIfRunning(dataDir); // flair#1047: stamp the store with the engine version
 }
 /**
  * The ONE restart mechanism for a local Flair install. Shared by `flair

package/dist/doctor-client.js

@@ -867,7 +867,19 @@ export function resolveCollisionSafeName(existingNames, filename) {
  */
 export function classifyKeyFile(agentId, seedValid, registration, baseUrl) {
     if (!seedValid) {
-        return { class: "invalid", reason: "not a parseable Ed25519 private key seed" };
+        // NOT "invalid", and therefore NOT prunable. "I could not parse this" and
+        // "this is a stale agent key" are different findings, and only the second
+        // is safe to act on. `~/.flair/keys/<id>.key` is a namespace shared by two
+        // writers: plaintext Ed25519 seeds, and AES-256-GCM keystore blobs written
+        // by FileKeyStore (flair#1026). A keystore blob is unparseable AS A SEED
+        // while being a LIVE federation key — classifying it "invalid" moved a key
+        // that was in use. An unidentified file is reported for a human and left
+        // exactly where it is.
+        return {
+            class: "unidentified",
+            reason: "not a parseable Ed25519 private key seed — may be a keystore blob or another format; " +
+                "left in place, inspect it before removing anything (flair#1026)",
+        };
     }
     if (registration?.state === "registered") {
         return { class: "keep", reason: `agent '${agentId}' is registered on ${baseUrl} — never pruned` };

package/dist/engine-version.js

@@ -0,0 +1,239 @@
+// engine-version.ts — Harper engine version tracking (flair#1047)
+//
+// Two concerns, one module:
+//
+// 1. STORE STAMP — flair records the engine version that last wrote the data
+//    directory. At boot, if the store was written by a NEWER engine than the
+//    one running, flair refuses to start and says so: which version wrote the
+//    store, which is running now, and what to do about it.
+//
+// 2. VERSION READ — read the Harper version installed alongside this flair
+//    package, and (when a target flair version is known) the Harper version
+//    that target declares. Used by the upgrade path to decide whether the
+//    engine version is changing and a pre-upgrade snapshot is therefore
+//    mandatory.
+//
+// The stamp is a single-line file in the data directory. It must survive the
+// data directory being moved and must not require a Harper query to read — if
+// the engine cannot boot, we still need to read it.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+/** Filename of the engine-version stamp inside the data directory. */
+export const ENGINE_VERSION_STAMP = "engine-version.txt";
+/** Root directory for pre-upgrade snapshots (~/.flair/upgrade-snapshots). */
+export const UPGRADE_SNAPSHOT_ROOT = resolve(homedir(), ".flair", "upgrade-snapshots");
+/** Read the Harper version installed alongside this flair package. */
+export function readInstalledHarperVersion(packageRoot) {
+    for (const name of ["harper", "@harperfast/harper"]) {
+        const pkgPath = join(packageRoot, "node_modules", ...name.split("/"), "package.json");
+        if (!existsSync(pkgPath))
+            continue;
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (pkg.version)
+                return pkg.version;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Fetch the Harper version that a given @tpsdev-ai/flair version declares as
+ * a dependency. Returns null when the lookup fails (network, unparseable, etc.)
+ * — callers treat null as "cannot determine, assume it might change."
+ */
+export async function fetchDeclaredHarperVersion(flairVersion) {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/@tpsdev-ai/flair/${flairVersion}`, { signal: AbortSignal.timeout(5000) });
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        return data.dependencies?.harper ?? data.dependencies?.["@harperfast/harper"] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Store stamp ─────────────────────────────────────────────────────────────
+/** Write the engine version stamp into the data directory. */
+export function writeEngineVersionStamp(dataDir, version) {
+    writeFileSync(join(dataDir, ENGINE_VERSION_STAMP), `${version}\n`, "utf-8");
+}
+/** Read the engine version stamp from the data directory, or null if absent. */
+export function readEngineVersionStamp(dataDir) {
+    const stampPath = join(dataDir, ENGINE_VERSION_STAMP);
+    if (!existsSync(stampPath))
+        return null;
+    try {
+        return readFileSync(stampPath, "utf-8").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check whether the running engine is OLDER than the engine that last wrote
+ * the store. Returns null when the check passes (no stamp, or stamp ≤ running),
+ * or an error message when the store is newer.
+ *
+ * The error must be actionable: actor, state, remedy.
+ */
+export function checkEngineVersionBackwards(dataDir, runningVersion) {
+    const stamp = readEngineVersionStamp(dataDir);
+    if (!stamp)
+        return null; // no stamp — nothing to compare (pre-stamp install)
+    const parsed = compareVersions(stamp, runningVersion);
+    if (parsed === null) {
+        // Genuinely unparseable — cannot determine ordering. Refuse with a
+        // message that does NOT claim one is newer than the other.
+        return [
+            `This Flair install is running Harper ${runningVersion}, but the data directory at`,
+            `  ${dataDir}`,
+            `was last written by Harper ${stamp}.`,
+            ``,
+            `The engine version stamp could not be compared to the running version.`,
+            `An older Harper cannot safely read a store written by a newer one.`,
+            ``,
+            ...buildRecoveryLines(),
+        ].join("\n");
+    }
+    if (parsed > 0) {
+        // stamp > running — backwards boot, refuse.
+        return [
+            `This Flair install is running Harper ${runningVersion}, but the data directory at`,
+            `  ${dataDir}`,
+            `was last written by Harper ${stamp} — a newer engine version.`,
+            ``,
+            `An older Harper cannot safely read a store written by a newer one.`,
+            `The data may appear intact but can be silently unreadable.`,
+            ``,
+            ...buildRecoveryLines(),
+        ].join("\n");
+    }
+    return null; // running >= stamp — allowed
+}
+// ─── Version comparison (flair#1047) ─────────────────────────────────────────
+/**
+ * Compare two semver-like version strings.
+ * Returns negative when a < b, positive when a > b, zero when equal,
+ * or null when either version is genuinely unparseable (not N.N.N at all).
+ *
+ * Pre-release ordering follows semver: a version WITH a pre-release tag is
+ * LOWER than the same core without one (5.2.0-rc1 < 5.2.0). When both have
+ * pre-releases, identifiers are compared dot by dot — numeric parts
+ * numerically, the rest as strings.
+ */
+function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (!pa || !pb)
+        return null;
+    // Compare major.minor.patch (and any additional numeric components) numerically.
+    const coreLen = Math.max(pa.core.length, pb.core.length);
+    for (let i = 0; i < coreLen; i++) {
+        const ac = pa.core[i] ?? 0;
+        const bc = pb.core[i] ?? 0;
+        if (ac !== bc)
+            return ac - bc;
+    }
+    // Cores are equal — compare pre-release tags.
+    if (pa.pre === null && pb.pre === null)
+        return 0;
+    if (pa.pre === null)
+        return 1; // a has no pre-release → a > b
+    if (pb.pre === null)
+        return -1; // b has no pre-release → a < b
+    // Both have pre-releases — compare identifiers dot by dot.
+    const len = Math.max(pa.pre.length, pb.pre.length);
+    for (let i = 0; i < len; i++) {
+        const ai = pa.pre[i];
+        const bi = pb.pre[i];
+        if (ai === undefined)
+            return -1; // fewer identifiers → lower
+        if (bi === undefined)
+            return 1;
+        const an = Number(ai);
+        const bn = Number(bi);
+        const aIsNum = !isNaN(an);
+        const bIsNum = !isNaN(bn);
+        if (aIsNum && bIsNum) {
+            if (an !== bn)
+                return an - bn;
+        }
+        else if (aIsNum) {
+            return -1; // numeric < string
+        }
+        else if (bIsNum) {
+            return 1;
+        }
+        else {
+            if (ai !== bi)
+                return ai < bi ? -1 : 1;
+        }
+    }
+    return 0;
+}
+function parseVersion(v) {
+    // Split off pre-release: everything after the first hyphen.
+    const hyphenIdx = v.indexOf("-");
+    const coreStr = hyphenIdx === -1 ? v : v.slice(0, hyphenIdx);
+    const preStr = hyphenIdx === -1 ? null : v.slice(hyphenIdx + 1);
+    const coreParts = coreStr.split(".");
+    if (coreParts.length < 3)
+        return null; // not at least N.N.N
+    const core = coreParts.map(Number);
+    if (core.some(isNaN))
+        return null; // non-numeric core component
+    const pre = preStr ? preStr.split(".") : null;
+    return { core, pre };
+}
+/**
+ * Build the recovery lines for a backwards-boot refusal message.
+ * Inspects the snapshot directory so the operator gets a runnable command
+ * (or a clear "nothing to restore" message) instead of a literal placeholder.
+ */
+export function buildRecoveryLines(snapshotDir) {
+    const effectiveSnapshotDir = snapshotDir ?? UPGRADE_SNAPSHOT_ROOT;
+    const snapshots = readSnapshotFiles(effectiveSnapshotDir);
+    if (snapshots.length === 0) {
+        return [
+            `To recover:`,
+            `  No pre-upgrade snapshot was found.`,
+            `  1. Reinstall the newer version:  npm install -g @tpsdev-ai/flair@latest`,
+            `  2. Or restore from a flair backup export (if you have one).`,
+            ``,
+            `This check only helps from the release that ships it onward — it cannot`,
+            `rescue a downgrade to a build that predates the stamp.`,
+        ];
+    }
+    const newest = snapshots[0];
+    const lines = [`To recover:`];
+    if (snapshots.length > 1) {
+        lines.push(`  1. Reinstall the newer version:  npm install -g @tpsdev-ai/flair@latest`, `  2. Or restore from the newest pre-upgrade snapshot:`, `     flair snapshot restore ${newest.path}`, ``, `     (To see all snapshots:  flair snapshot list)`);
+    }
+    else {
+        lines.push(`  1. Reinstall the newer version:  npm install -g @tpsdev-ai/flair@latest`, `  2. Or restore from the pre-upgrade snapshot:`, `     flair snapshot restore ${newest.path}`);
+    }
+    lines.push(``, `This check only helps from the release that ships it onward — it cannot`, `rescue a downgrade to a build that predates the stamp.`);
+    return lines;
+}
+/** Read snapshot files (.tar.gz), newest first. Lexical sort = chronological, because the
+    filename carries an ISO 8601 timestamp (see upgradeSnapshotFileName). If that format ever
+    changes, this sort must be revisited. */
+function readSnapshotFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.startsWith("flair-data-") && f.endsWith(".tar.gz"))
+            .sort() // alphabetical = chronological (flair-data-<timestamp>.tar.gz)
+            .reverse() // newest first
+            .map((f) => ({ name: f, path: join(dir, f) }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/resources/AdminInstance.js

@@ -113,7 +113,7 @@ export class AdminInstance extends Resource {
         // actionable and still teaches them the surface exists.
         const mcp = mcpRouteState();
         const mcpCell = mcp.mounted
-            ? `<code>${publicUrl}/mcp</code>`
+            ? `<code>${esc(publicUrl)}/mcp</code>`
             : `<span class="badge badge-gray">${esc(mcp.status)}</span>` +
                 `<div style="margin-top:4px;color:#666;font-size:0.9em">${esc(mcp.reason)}</div>`;
         // Try to read instance public key
@@ -141,7 +141,7 @@ export class AdminInstance extends Resource {
         </div>
         <div class="card">
           <h3>Public URL</h3>
-          <div style="font-family:monospace;font-size:0.9em;word-break:break-all">${publicUrl}</div>
+          <div style="font-family:monospace;font-size:0.9em;word-break:break-all">${esc(publicUrl)}</div>
         </div>
       </div>
 
@@ -156,12 +156,12 @@ export class AdminInstance extends Resource {
       <div class="card">
         <h3>Endpoints</h3>
         <table style="box-shadow:none">
-          <tr><td>API</td><td><code>${publicUrl}/</code></td></tr>
+          <tr><td>API</td><td><code>${esc(publicUrl)}/</code></td></tr>
           <tr><td>MCP</td><td>${mcpCell}</td></tr>
-          <tr><td>OAuth Discovery</td><td><code>${publicUrl}/OAuthMetadata</code></td></tr>
-          <tr><td>OAuth Authorize</td><td><code>${publicUrl}/OAuthAuthorize</code></td></tr>
-          <tr><td>OAuth Token</td><td><code>${publicUrl}/OAuthToken</code></td></tr>
-          <tr><td>Admin</td><td><code>${publicUrl}/AdminDashboard</code></td></tr>
+          <tr><td>OAuth Discovery</td><td><code>${esc(publicUrl)}/OAuthMetadata</code></td></tr>
+          <tr><td>OAuth Authorize</td><td><code>${esc(publicUrl)}/OAuthAuthorize</code></td></tr>
+          <tr><td>OAuth Token</td><td><code>${esc(publicUrl)}/OAuthToken</code></td></tr>
+          <tr><td>Admin</td><td><code>${esc(publicUrl)}/AdminDashboard</code></td></tr>
         </table>
       </div>
     `;