@tpsdev-ai/flair 0.50.0 → 0.51.1

package/dist/cli.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import nacl from "tweetnacl";
 import { load as parseYaml } from "js-yaml";
 import * as render from "./render.js";
-import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, lstatSync, realpathSync, unlinkSync, chownSync, } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, openSync, closeSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, lstatSync, realpathSync, unlinkSync, chownSync, constants as fsConstants, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve, sep, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -32,12 +32,15 @@ import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing
 import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snapshot-extract.js";
 import { entityFormatHint, parseEntitiesCsv } from "./lib/entity-vocab-cli.js";
 import { escapeXml, unescapeXml } from "./lib/xml-escape.js";
-import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, renderVerifiedSummary, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
+import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
+import { applyUpgradeHookConsent, catalogIssueDelta, renderCatalogDoctorLines, renderVerifiedSummary, runDoctorChecks, } from "./lib/doctor-run.js";
+import { classifyDaemonState, verifyIdentity, parseProcStatStartTime, procStartTimeToEpochMs, parsePsLstart, parseSidecarJson, } from "./lib/daemon-liveness.js";
 // Value-only static import so `--interval`'s advertised default cannot drift
 // from the one the scheduler actually validates against. The module itself is
 // still loaded lazily at call time (the `await import()`s below) for the
 // functions — this pulls in nothing but node builtins.
 import { DEFAULT_INTERVAL_SECONDS as FEDERATION_SYNC_DEFAULT_INTERVAL } from "./federation/scheduler.js";
+import { applyUpgradeMigrations } from "./lib/upgrade-migrations.js";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
 // src/ into resources/, which don't survive npm packaging (see also
 // resources/federation-crypto.ts; the two must stay in sync).
@@ -60,14 +63,18 @@ function signBody(body, secretKey) {
     const sig = nacl.sign.detached(message, secretKey);
     return Buffer.from(sig).toString("base64url");
 }
-// Per-record principalId (federation-edge-hardening slice 3a) — INFORMATIONAL
-// only; the receiver (resources/Federation.ts) never treats it as verified
-// identity or uses it in any auth decision. Sourced from the write-time
-// provenance stamp (memory-provenance slice 1, Memory.ts's buildProvenance)
-// when present. `provenance` is persisted as a JSON STRING (not an object),
-// so it must be parsed — a raw `row.provenance?.verified?.agentId` would
-// silently always be undefined. Soul/Agent/Relationship rows never carry a
-// provenance stamp today, so this is a no-op for them.
+// Per-record principalId (federation-edge-hardening slice 3a / flair#1416).
+// Sourced from the write-time provenance stamp (memory-provenance slice 1,
+// Memory.ts's buildProvenance) when present. `provenance` is persisted as
+// a JSON STRING (not an object), so it must be parsed — a raw
+// `row.provenance?.verified?.agentId` would silently always be undefined.
+// Soul/Agent/Relationship rows never carry a provenance stamp today, so
+// this is a no-op for them (those tables are not principal-owning).
+//
+// As of v:2 this value is IN the signed payload. The receiver validates
+// it against data.agentId for Memory (PRINCIPAL_OWNING_TABLES); it is
+// no longer informational-only. Credential.principalId is an unrelated
+// owner field — do not grep that path when changing this one.
 function principalIdFromRow(row) {
     if (typeof row?.provenance !== "string" || row.provenance.length === 0)
         return undefined;
@@ -3002,7 +3009,7 @@ program
     .option("--no-mcp", "Skip MCP client wiring (instance + agent only)")
     .option("--skip-smoke", "Skip the MCP smoke test")
     .option("--skip-claude-md", "Skip appending the Flair bootstrap line to CLAUDE.md (claude-code only)")
-    .option("--skip-hook", "Skip installing the flair-session-start SessionStart hook (claude-code only)")
+    .option("--skip-hook", "Skip installing the flair-session-start SessionStart hook (claude-code and Codex)")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .option("--remote", "When used with --target, init as hub for remote federation")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
@@ -3463,6 +3470,11 @@ program
             console.log(`Starting Harper on port ${httpPort}...`);
             const proc = spawn(process.execPath, [bin, "run", "."], { cwd: flairPackageDir(), env, detached: true, stdio: "ignore" });
             proc.unref();
+            // flair#1454: write the identity sidecar immediately after spawn so
+            // `flair stop` and `flair status` can classify this daemon's state
+            // without lsof. Same call as startFlairProcess() uses.
+            if (proc.pid)
+                writeDaemonSidecar(dataDir, proc.pid, httpPort);
         }
         console.log("Waiting for Harper health check...");
         await waitForHealth(httpPort, adminUser, adminPass, STARTUP_TIMEOUT_MS);
@@ -3864,6 +3876,18 @@ program
                     }
                     wiringResults.push({ client: clientId, message: result.message, wired: result.ok });
                     console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
+                    // Codex SessionStart hook (flair#1148 / #1439) — the hook is not
+                    // optional on Codex (no CLAUDE.md alternative). Init is the
+                    // consent to set up the client, same as the Claude Code hook
+                    // applied above. --skip-hook opts out and prints the JSON.
+                    if (clientId === "codex" && result.ok) {
+                        const hookResult = applyOrReportSessionStartHook(homedir(), agentId, !!opts.skipHook, hookSettingsPath(homedir(), "codex"));
+                        console.log(`   ${hookResult.ok ? "✓" : "•"} ${hookResult.message}`);
+                        if (hookResult.hint) {
+                            for (const line of hookResult.hint.split("\n"))
+                                console.log(`   ${line}`);
+                        }
+                    }
                 }
             }
         }
@@ -7030,22 +7054,40 @@ export async function runFederationSyncOnce(opts) {
                 // batch. Closes the hub-relay forgery hole — see
                 // resources/Federation.ts FederationSync.post's verification gate.
                 //
-                // CONTRACT — must match Federation.ts's verification payload
-                // byte-for-byte: keys { v, table, id, data, updatedAt,
-                // originatorInstanceId }. canonicalize() sorts keys, so field ORDER
-                // doesn't matter, but the field SET and values do. `v: 1` versions the
-                // canonical form itself: bump it on BOTH sides together if the signed
-                // field set ever changes, so an old signature fails closed instead of
-                // silently mis-verifying under a new form.
+                // CONTRACT — must match reconstructRecordVerifyBody
+                // (resources/federation-classify.ts) byte-for-byte. canonicalize()
+                // sorts keys, so field ORDER doesn't matter, but the field SET and
+                // values do. `v` versions the canonical form itself: a v:1
+                // signature cannot verify as v:2 (principalId in the field set).
                 //
-                // Additive/backward-compatible: pre-3a receivers don't read
-                // `signature`/`principalId` at all and merge exactly as before.
-                const signature = signBody({ v: 1, table, id: row.id, data: row, updatedAt, originatorInstanceId }, secretKey);
-                const sr = { table, id: row.id, data: row, updatedAt, originatorInstanceId, signature };
-                // Informational only (see principalIdFromRow) — never verified by the
-                // receiver as proof of authorship. Omitted entirely when the row
-                // carries no write-time provenance stamp.
+                // v: 2 puts principalId in the signed payload when the row carries
+                // a provenance stamp, and puts `v` on the wire so Phase 1
+                // receivers (`const v = record.v ?? 1`) don't default these
+                // records back to 1. Soul/Agent/Relationship have no stamp and
+                // omit principalId; Memory without a stamp also omits it (the
+                // receiver then skips Memory as principal_mismatch — absent is
+                // not an accept).
                 const principalId = principalIdFromRow(row);
+                const signedPayload = {
+                    v: 2,
+                    table,
+                    id: row.id,
+                    data: row,
+                    updatedAt,
+                    originatorInstanceId,
+                };
+                if (principalId)
+                    signedPayload.principalId = principalId;
+                const signature = signBody(signedPayload, secretKey);
+                const sr = {
+                    v: 2,
+                    table,
+                    id: row.id,
+                    data: row,
+                    updatedAt,
+                    originatorInstanceId,
+                    signature,
+                };
                 if (principalId)
                     sr.principalId = principalId;
                 const srBytes = JSON.stringify(sr).length;
@@ -10276,6 +10318,7 @@ program
     .option("--project <name>", "Fabric component name for --target", "flair")
     .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
     .option("--yes", "Skip the confirmation prompt for --target")
+    .option("--install-hooks", "Consent to installing missing SessionStart hooks (claude-code / Codex) during upgrade. The hook executes at every session start — upgrade will not write it unprompted. Interactive runs prompt; non-interactive runs state the gap and withhold ✅ unless this flag is passed.")
     .option("--no-fleet-verify", "Skip the automatic post-upgrade fleet convergence sweep for --target (default: sweep runs — see flair#636)")
     // ── flair#878 ─────────────────────────────────────────────────────────────
     // These existed on `flair deploy` but stopped at the upgrade boundary, so
@@ -10941,20 +10984,18 @@ program
     });
     const verdict = decideAfterVerify(verify, previousFlairVersion);
     if (verdict.kind === "ok") {
-        // flair#1022: the verified facts are unchanged and still stated — the
-        // upgrade did land. What changes is the MARKER and the claim around it.
-        // A run that ended up outside its process manager has not fully
-        // succeeded, so it does not get a ✅, and the line names the property
-        // that is wrong rather than only the ones that are right. The choice
-        // lives in renderVerifiedSummary so it is testable without performing an
-        // upgrade — no CI lane runs this darwin path.
-        const summary = renderVerifiedSummary(verify.version, management);
-        for (const line of summary.lines) {
-            if (summary.degraded)
-                console.error(line);
-            else
-                console.log(line);
-        }
+        // flair#1439: the success marker is the doctor runner's verdict, not
+        // a second, narrower notion of "verified". Launchd detach is one
+        // catalog member; the Codex SessionStart hook is another. Adding a
+        // doctor check widens this claim automatically.
+        const run = await doctorRunAfterUpgrade({
+            management,
+            port,
+            installHooksFlag: !!opts.installHooks,
+            fromVersion: previousFlairVersion,
+            toVersion: expectedFlairVersion,
+        });
+        printVerifiedSummary(renderVerifiedSummary(verify.version, run));
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -10966,21 +11007,25 @@ program
     // "print an honest note but roll back anyway" branch that used to sit below
     // is gone — that credentials case can no longer reach the rollback path.)
     if (verdict.kind === "healthy-unverified") {
-        // flair#1022: same rule as the "ok" branch above — the ✅ is withheld
-        // when the run left the instance outside launchd, and the reason is
-        // named. This branch already qualifies the version claim; the process
-        // manager is a second, independent qualification.
-        console.log(detached
-            ? `⚠️  upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}, but NOT under launchd.`
-            : `✅ upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}.`);
+        // Same doctor runner as the "ok" branch — an unverified version must
+        // not restore the unqualified ✅ while a catalog member is failing.
+        const run = await doctorRunAfterUpgrade({
+            management,
+            port,
+            installHooksFlag: !!opts.installHooks,
+            fromVersion: previousFlairVersion,
+            toVersion: expectedFlairVersion,
+        });
+        const versionNote = expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : "";
+        if (run.healthy) {
+            console.log(`✅ upgrade complete: the instance is up and healthy${versionNote}.`);
+        }
+        else {
+            printVerifiedSummary(renderVerifiedSummary(verify.version, run, { authenticated: false }));
+        }
         console.log(`   The version could not be verified — the checker couldn't authenticate to /HealthDetail (${verdict.reason}).`);
         console.log("   The server is confirmed running (public /Health passed); this is a verification gap, not an upgrade failure — nothing was rolled back.");
         console.log("   To enable full post-upgrade verification: set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key.");
-        if (detached) {
-            for (const line of renderDetachedWarning(management, "The instance is NOT running under launchd.")) {
-                console.error(line);
-            }
-        }
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
@@ -10991,6 +11036,240 @@ program
     }
     await rollbackTo(verdict.toVersion, verdict.reason);
 });
+/**
+ * Read a file with O_NOFOLLOW so a symlink planted at the pidfile/sidecar path
+ * cannot redirect the read (flair#1454 decision 6). `readFileSync` has no such
+ * flag, so this opens the fd first and reads from it.
+ */
+function readFileNoFollow(path) {
+    let fd;
+    try {
+        fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return { kind: "absent" };
+        if (err?.code === "ELOOP")
+            return { kind: "unreadable", reason: `${path} is a symbolic link` };
+        return { kind: "unreadable", reason: `cannot open ${path}: ${err?.code ?? err?.message}` };
+    }
+    try {
+        return { kind: "present", content: readFileSync(fd, "utf-8") };
+    }
+    catch (err) {
+        return { kind: "unreadable", reason: `cannot read ${path}: ${err?.code ?? err?.message}` };
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch { /* already closed */ }
+    }
+}
+/**
+ * Refuse to trust a data dir that is a symlink or world-writable (flair#1454
+ * decision 6). Returns a reason, or null when the dir is safe (or absent — a
+ * missing dir is "no data", not "unsafe"; the pidfile read reports absent).
+ */
+function checkDataDirSafe(dataDir) {
+    let lst;
+    try {
+        lst = lstatSync(dataDir);
+    }
+    catch {
+        return null;
+    }
+    if (lst.isSymbolicLink()) {
+        return `data directory ${dataDir} is a symbolic link — refusing to trust its pidfile`;
+    }
+    let st;
+    try {
+        st = statSync(dataDir);
+    }
+    catch {
+        return null;
+    }
+    if (st.mode & 0o002) {
+        return `data directory ${dataDir} is world-writable — refusing to trust its pidfile`;
+    }
+    return null;
+}
+/** Read `hdb.pid` (O_NOFOLLOW) into a `PidfileRead`. */
+function readPidfile(dataDir) {
+    const r = readFileNoFollow(join(dataDir, "hdb.pid"));
+    if (r.kind !== "present")
+        return r;
+    const n = Number(r.content.trim());
+    if (!Number.isInteger(n) || n <= 0) {
+        return { kind: "unreadable", reason: `${join(dataDir, "hdb.pid")} does not contain a valid pid` };
+    }
+    return { kind: "present", pid: n };
+}
+/** Read `flair-daemon.json` (O_NOFOLLOW) into a `SidecarRead`. */
+function readSidecar(dataDir) {
+    const r = readFileNoFollow(join(dataDir, "flair-daemon.json"));
+    if (r.kind !== "present")
+        return r;
+    const parsed = parseSidecarJson(r.content);
+    if (parsed === null) {
+        return { kind: "unreadable", reason: `${join(dataDir, "flair-daemon.json")} is malformed` };
+    }
+    return { kind: "present", ...parsed };
+}
+/** `kill(pid, 0)` as a three-way: alive / gone (ESRCH) / eperm (another user's). */
+function probePidLiveness(pid) {
+    try {
+        process.kill(pid, 0);
+        return { kind: "alive" };
+    }
+    catch (err) {
+        if (err?.code === "ESRCH")
+            return { kind: "gone" };
+        if (err?.code === "EPERM")
+            return { kind: "eperm" };
+        return { kind: "gone" };
+    }
+}
+/**
+ * The live process's start time in epoch ms, or null when it cannot be read.
+ * Linux reads `/proc/<pid>/stat` field 22 (starttime in clock ticks) plus
+ * `/proc/uptime`; macOS shells out to `ps -o lstart=`. A null answer degrades
+ * to "identity unverified" — it never decides a verdict toward the destructive
+ * branch (flair#1454 decision 4).
+ */
+function readProcessStartTimeMs(pid) {
+    if (process.platform === "linux") {
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+            const starttime = parseProcStatStartTime(stat);
+            if (starttime === null)
+                return null;
+            const uptimeRaw = readFileSync("/proc/uptime", "utf-8").trim().split(/\s+/)[0];
+            const uptime = Number(uptimeRaw);
+            if (!Number.isFinite(uptime))
+                return null;
+            return procStartTimeToEpochMs(starttime, uptime, Date.now());
+        }
+        catch {
+            return null;
+        }
+    }
+    if (process.platform === "darwin") {
+        try {
+            const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+                encoding: "utf-8",
+                env: { ...process.env, LC_ALL: "C" },
+                timeout: 2000,
+            });
+            return parsePsLstart(out);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** The health probe, three-way: ok / refused (ECONNREFUSED) / unreachable. */
+async function probeHealth(port) {
+    try {
+        await fetch(`http://127.0.0.1:${port}/Health`, { signal: AbortSignal.timeout(2000) });
+        return { kind: "ok" };
+    }
+    catch (err) {
+        // Node's undici fetch reports ECONNREFUSED on `err.cause.code`; Bun reports
+        // `ConnectionRefused` on `err.code`. Both mean "nothing is listening".
+        const code = err?.cause?.code ?? err?.code;
+        if (code === "ECONNREFUSED" || code === "ConnectionRefused") {
+            return { kind: "refused" };
+        }
+        return { kind: "unreachable" };
+    }
+}
+/** Gather every piece of evidence the classifier needs, in one place. */
+async function gatherDaemonEvidence(port, dataDir) {
+    const dataDirUnsafe = checkDataDirSafe(dataDir);
+    const pidfile = readPidfile(dataDir);
+    const pidLiveness = pidfile.kind === "present" ? probePidLiveness(pidfile.pid) : null;
+    let sidecar = readSidecar(dataDir);
+    // Probe health first so the self-heal gate below can use it without a
+    // second round-trip. Also consumed at the end for the classifier.
+    const health = await probeHealth(port);
+    // flair#1454 self-heal: a daemon started by a pre-sidecar version of flair
+    // (upgrade-across-#1454) has a live pid in hdb.pid but no flair-daemon.json.
+    // Without this path, classifyDaemonState returns DISAGREEMENT and `flair stop`
+    // refuses — breaking the upgrade flow for every existing user.
+    //
+    // SECURITY: the real guard is /Health, NOT the ±2s start-time check.
+    // The ±2s check is circular in the self-heal path: we write the sidecar
+    // with the live process's OWN start time, then verifyIdentity reads the
+    // same process — it matches by construction for ANY live pid, including a
+    // recycled pid belonging to an unrelated process. Requiring /Health OK is
+    // the correct proof: only the flair daemon responds 200 at
+    // http://127.0.0.1:<port>/Health. An unrelated recycled pid does not.
+    //
+    // Therefore: self-heal is gated on health.kind === "ok". A live pid that
+    // does NOT serve /Health — a recycled pid, a wedged pre-#1454 daemon that
+    // can no longer respond — is left as DISAGREEMENT (refuse to signal).
+    // Never WEDGED, never SIGTERM, on an unverified pid.
+    //
+    // The write uses the same O_NOFOLLOW / 0600 / atomic-rename posture as every
+    // other sidecar write. We skip self-heal when the dataDir is unsafe
+    // (symlink / world-writable) — the check has already happened above.
+    if (sidecar.kind === "absent" &&
+        dataDirUnsafe === null &&
+        pidfile.kind === "present" &&
+        pidLiveness?.kind === "alive" &&
+        health.kind === "ok" // ← the real proof: only flair serves this
+    ) {
+        const pid = pidfile.pid;
+        const startTimeMs = readProcessStartTimeMs(pid);
+        if (startTimeMs !== null) {
+            try {
+                writeDaemonSidecar(dataDir, pid, port, startTimeMs);
+                // Re-read: now that the sidecar exists, classify through the normal path.
+                sidecar = readSidecar(dataDir);
+            }
+            catch {
+                // Self-heal is best-effort. If the write fails (e.g. read-only dataDir),
+                // we proceed with sidecar === absent and fall through to DISAGREEMENT
+                // — the same outcome as before the self-heal path, so no regression.
+            }
+        }
+    }
+    const identity = verifyIdentity({
+        pidfilePid: pidfile.kind === "present" ? pidfile.pid : null,
+        sidecar,
+        readStartTime: readProcessStartTimeMs,
+    });
+    return { dataDirUnsafe, pidfile, pidLiveness, identity, health };
+}
+/**
+ * Write the identity sidecar atomically (temp + rename) at spawn time or
+ * during self-heal (flair#1454 decision 3). `pid` is the spawned process's
+ * pid — the same number Harper writes to `hdb.pid`, since Harper runs
+ * in-process. `startTimeMs` defaults to `Date.now()` for a fresh spawn.
+ *
+ * Self-heal callers pass the live process's actual start time (from
+ * readProcessStartTimeMs) so the sidecar records an accurate epoch, not a
+ * wall-clock approximation. Note: in the self-heal path the ±2s start-time
+ * check in verifyIdentity is NOT what prevents recycled-pid adoption —
+ * that guard is the /Health probe that the self-heal caller already required
+ * before reaching this point. The start time is recorded faithfully for
+ * forward compatibility and audit, not as a security gate here.
+ */
+function writeDaemonSidecar(dataDir, pid, port, startTimeMs = Date.now()) {
+    const sidecar = { pid, startTimeMs, port, flairVersion: __pkgVersion };
+    const tmpPath = join(dataDir, `.flair-daemon.json.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+    // Write with mode 0600 so the tmp file is never world-readable (flair#1454
+    // decision 6 — same posture as admin-pass and key material).
+    writeFileSync(tmpPath, JSON.stringify(sidecar, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    const finalPath = join(dataDir, "flair-daemon.json");
+    renameSync(tmpPath, finalPath);
+    // Re-assert 0600 after the rename: rename preserves the tmp permissions but
+    // a pre-existing file at the destination retains its original mode on some
+    // kernels. An explicit chmod is the only guarantee (flair#1454 decision 6).
+    chmodSync(finalPath, 0o600);
+}
 // ─── flair stop ───────────────────────────────────────────────────────────────
 program
     .command("stop")
@@ -11016,49 +11295,55 @@ program
             }
         }
     }
-    // Fallback: find process by port. Listening sockets only, never our own
-    // PID — see parseListeningPids (flair#800/flair#905): this used to SIGTERM
-    // every process holding ANY socket on the port, so `flair stop` could kill
-    // itself (leaving Flair running) or kill an unrelated client of it.
-    //
-    // Attribution guard (flair#915): the port is not an identity. Refuse to
-    // SIGTERM a PID that cannot be attributed to this instance.
-    try {
-        const { execSync } = await import("node:child_process");
-        const pids = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
-        if (pids.length > 0) {
-            const dataDir = defaultDataDir();
-            const harperPid = readHarperPid(dataDir);
-            if (harperPid !== null && !pids.includes(harperPid)) {
-                console.error(`⚠️  Process(es) on port ${port} (PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")}) `
-                    + `do not match this Flair instance (PID ${harperPid}). `
-                    + `Not stopping — cannot attribute the process to this instance. `
-                    + `Stop the process manually if it is not Flair.`);
-                process.exit(1);
+    // Non-launchd: the five-state liveness machine (flair#1454). The old
+    // decision tree (launchd -> lsof -> "not running") is REPLACED, not
+    // patched: `lsof` absence used to render as a definite "not running", and
+    // the pidfile was only consulted to attribute port-derived PIDs. Now the
+    // pidfile + identity sidecar are the primary evidence, and the health
+    // probe is a cross-check — never the verdict.
+    const dataDir = defaultDataDir();
+    const evidence = await gatherDaemonEvidence(port, dataDir);
+    const state = classifyDaemonState(evidence, { port, dataDir });
+    switch (state.state) {
+        case "RUNNING":
+        case "WEDGED": {
+            // Identity is already proven for both of these — killing a wedged
+            // daemon is recovery, not a recycled-PID gamble.
+            const pid = state.pid;
+            const label = state.state === "WEDGED" ? "wedged daemon" : "daemon";
+            try {
+                process.kill(pid, "SIGTERM");
             }
-            else if (harperPid === null) {
-                console.error(`⚠️  Process(es) on port ${port} (PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")}) `
-                    + `but no PID file in data directory — not a running Flair instance. `
-                    + `Not stopping — cannot attribute the process to this instance. `
-                    + `Stop the process manually if it is not Flair.`);
-                process.exit(1);
+            catch (err) {
+                if (err?.code !== "ESRCH") {
+                    console.error(`❌ failed to signal pid ${pid}: ${err?.code ?? err?.message}`);
+                    process.exit(1);
+                }
+            }
+            await waitForProcessExit(pid, STARTUP_TIMEOUT_MS);
+            const after = await probeHealth(port);
+            if (after.kind === "refused") {
+                console.log(`✅ Flair stopped (${label}, pid ${pid})`);
             }
             else {
-                for (const pid of pids) {
-                    try {
-                        process.kill(pid, "SIGTERM");
-                    }
-                    catch { /* already gone */ }
-                }
-                console.log(`✅ Flair stopped (killed PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")})`);
+                console.log(`✅ Flair stopped (${label}, pid ${pid}; port ${port} may still be releasing)`);
             }
+            return;
         }
-        else {
+        case "NOT_RUNNING":
             console.log("Flair is not running.");
-        }
-    }
-    catch {
-        console.log("Flair is not running (nothing found on port " + port + ").");
+            return;
+        case "DISAGREEMENT":
+            console.error(`⚠️  ${state.detail}`);
+            console.error(`   Not stopping — the evidence conflicts.`);
+            console.error(`   pidfile: ${join(dataDir, "hdb.pid")}`);
+            console.error(`   port: ${port}`);
+            console.error(`   To inspect: flair doctor`);
+            process.exit(1);
+        case "UNKNOWN":
+            console.error(`⚠️  ${state.detail}`);
+            console.error(`   Not stopping — could not determine whether Flair is running.`);
+            process.exit(1);
     }
 });
 // ─── flair start ──────────────────────────────────────────────────────────────
@@ -11068,16 +11353,35 @@ program
     .option("--port <port>", "Harper HTTP port")
     .action(async (opts) => {
     const port = resolveHttpPort(opts);
-    // Check if already running
-    try {
-        const res = await fetch(`http://127.0.0.1:${port}/Health`, { signal: AbortSignal.timeout(2000) });
-        if (res.status > 0) {
-            console.log(`Flair is already running on port ${port}.`);
-            return;
-        }
-    }
-    catch { /* not running — good */ }
     const dataDir = defaultDataDir();
+    // Already-running check via the five-state liveness machine (flair#1454).
+    // The old check was a bare `fetch /Health` that treated "got a response"
+    // as "already running" and exited 0 — half of #1454. Now the machine
+    // classifies, and every non-NOT_RUNNING state refuses with a non-zero exit.
+    const evidence = await gatherDaemonEvidence(port, dataDir);
+    const state = classifyDaemonState(evidence, { port, dataDir });
+    switch (state.state) {
+        case "NOT_RUNNING":
+            break; // proceed to boot
+        case "RUNNING":
+            console.error(`Flair is already running on port ${port} (pid ${state.pid}).`);
+            process.exit(1);
+        case "WEDGED":
+            console.error(`⚠️  A wedged Flair daemon (pid ${state.pid}) is holding port ${port}.`);
+            console.error(`   Run 'flair stop' first — never start over a live pid.`);
+            process.exit(1);
+        case "DISAGREEMENT":
+            console.error(`⚠️  ${state.detail}`);
+            console.error(`   Refusing to start — the evidence conflicts.`);
+            console.error(`   pidfile: ${join(dataDir, "hdb.pid")}`);
+            console.error(`   port: ${port}`);
+            console.error(`   To inspect: flair doctor`);
+            process.exit(1);
+        case "UNKNOWN":
+            console.error(`⚠️  ${state.detail}`);
+            console.error(`   Refusing to start — could not determine whether Flair is running.`);
+            process.exit(1);
+    }
     if (!existsSync(dataDir)) {
         console.error("❌ No Flair data directory found. Run 'flair init' first.");
         process.exit(1);
@@ -11155,6 +11459,12 @@ program
         cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
     });
     proc.unref();
+    // Write the identity sidecar immediately after spawn (flair#1454 decision
+    // 3) — BEFORE waitForHealth, so startTimeMs stays within the ±2s tolerance
+    // of the process's real start time. `proc.pid` is the pid Harper writes to
+    // hdb.pid, since Harper runs in-process.
+    if (proc.pid)
+        writeDaemonSidecar(dataDir, proc.pid, port);
     try {
         await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
         readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture on the freshly-created socket
@@ -11217,51 +11527,6 @@ export function assertLaunchdServiceOwnedBy(dataDir, label, plistPath, action) {
         `Re-run with --data-dir ${resolve(declared)} to act on that one, or run ` +
         `'flair init --data-dir ${resolve(dataDir)}' to register a service for this one.`);
 }
-/**
- * Refuse a port-based SIGTERM that cannot be attributed to `dataDir`
- * (flair#902).
- *
- * The port fallback below identifies its target by port number and nothing
- * else, so `--data-dir <scratch>` with a port that scratch instance does not
- * serve signals whichever instance DOES serve it. That is the whole of this
- * bug on Linux, where there is no launchd path at all.
- *
- * Scoped deliberately to a non-default data dir. For the default install the
- * port genuinely is that instance's port by every convention in this CLI
- * (`writeConfig`/`readPortFromConfig`), and the only evidence available here
- * — `<dataDir>/hdb.pid` vs the listening PIDs — is not something we can
- * require without risking a false refusal on a working install whose PID file
- * is missing or whose listener is a worker. So the default path keeps today's
- * behavior exactly, and the residual gap is stated rather than papered over:
- * a default-dir port stop is still unattributed. The new refusal can only
- * fire for a caller that explicitly named another data dir — the case that is
- * wrong today whenever the port does not match.
- */
-function assertPortInstanceOwnedBy(port, dataDir, listeningPids) {
-    // (flair#915) Apply the attribution check for ALL data directories, not
-    // just non-default ones. The default-dir bypass was the residual gap that
-    // #910 left behind — it allowed an unattributed SIGTERM on the default
-    // install's port. The old concern (false refusal when hdb.pid is missing)
-    // is actually the RIGHT behavior: no PID file means we cannot attribute the
-    // listener, so we refuse. That is safer than killing the wrong process.
-    const expected = readHarperPid(dataDir);
-    // No PID file — Harper is not (or was not) running in this directory.
-    // The port is stale or held by something else; refuse to SIGTERM it.
-    if (expected === null) {
-        throw new Error(`refusing to stop the process listening on port ${port}: no hdb.pid under `
-            + `${resolve(dataDir)}, so that is not a running instance. `
-            + `Stopping by port alone would signal a process we cannot attribute. `
-            + `If it is not Flair, stop it manually.`);
-    }
-    // PID file exists — the PID on the port must be Harper.
-    if (listeningPids.includes(expected))
-        return;
-    throw new Error(`refusing to stop the process listening on port ${port}: its recorded PID ${expected} `
-        + `is not the process listening on ${port}. `
-        + `Stopping by port alone would signal a different instance. `
-        + `Pass --port with the port ${resolve(dataDir)} actually serves, `
-        + `or stop the process manually.`);
-}
 // ─── "is it still under launchd?" (flair#1022) ─────────────────────────────
 //
 // The pure logic lives in src/lib/launchd-management.ts; these two adapters
@@ -11299,6 +11564,117 @@ function resolveInstanceServingPid(dataDir, port) {
         listeningPids,
     });
 }
+/** Agent signing-key ids under `keysDir` — node-scoped federation keys excluded. */
+function collectKeyAgentIds(keysDir) {
+    if (!existsSync(keysDir))
+        return [];
+    try {
+        const keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key"));
+        const { agentKeyIds } = partitionKeyIds(keyFiles.map((f) => f.replace(/\.key$/, "")), keysDir);
+        return agentKeyIds;
+    }
+    catch {
+        return [];
+    }
+}
+async function confirmYes(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((res) => rl.question(question, (a) => { rl.close(); res(a); }));
+    return /^y(es)?$/i.test(answer.trim());
+}
+/**
+ * flair#1439 — run the enumerable doctor catalog after upgrade's instance
+ * probe, and offer a consented SessionStart-hook install when that check
+ * fails. Silent writes are refused: `--install-hooks` or an interactive
+ * yes is the only consent. The consent→write composition lives in
+ * applyUpgradeHookConsent so tests can drive the path that actually
+ * writes (or does not write) the hook file.
+ *
+ * Before the catalog run, `applyUpgradeMigrations` fires any version-keyed
+ * migrations that are pending for the fromVersion→toVersion pair. These do
+ * NOT require `--install-hooks` because the user already consented to the
+ * affected integration when they ran `flair init` — the migration just
+ * applies a new artifact that the old init could not have written.
+ */
+async function doctorRunAfterUpgrade(args) {
+    const homeDir = homedir();
+    const keysDir = defaultKeysDir();
+    const detectedClientIds = detectClients().filter((c) => c.detected).map((c) => c.id);
+    // ── Version-keyed upgrade migrations (flair#1439) ─────────────────────────
+    // Apply any pending migrations BEFORE the doctor catalog run so that the
+    // catalog sees the post-migration state (e.g. the hook is present, so the
+    // session-start-hook check passes and the upgrade prints ✅ verified: healthy).
+    const migCtx = {
+        homeDir,
+        port: args.port,
+        detectedClientIds,
+    };
+    const migrations = applyUpgradeMigrations(args.fromVersion, args.toVersion, migCtx);
+    for (const { results } of migrations.applied) {
+        for (const r of results) {
+            if (r.wrote) {
+                console.log(`   ✓ ${r.message}`);
+            }
+            else if (!r.ok) {
+                console.error(`   • ${r.message}`);
+            }
+            // Silently skip no-op (ok, !wrote) — nothing changed, nothing to say.
+        }
+    }
+    if (!migrations.allOk) {
+        // A migration reported a non-fatal issue (each is logged above). Say so
+        // plainly rather than let the upcoming ✅ verified summary imply the upgrade
+        // finished cleanly — the doctor catalog below reflects the real state.
+        console.error("   • one or more upgrade migrations did not complete cleanly — the doctor check below shows the current state.");
+    }
+    const ctx = {
+        homeDir,
+        cwd: process.cwd(),
+        detectedClientIds,
+        launchd: args.management,
+        keysDir,
+        keyAgentIds: collectKeyAgentIds(keysDir),
+    };
+    const run = runDoctorChecks(ctx);
+    const apply = (promptAccepted) => applyUpgradeHookConsent({
+        homeDir,
+        ctx,
+        run,
+        installHooksFlag: args.installHooksFlag,
+        interactive: !!process.stdin.isTTY,
+        promptAccepted,
+        port: args.port,
+    });
+    let outcome = apply();
+    if (outcome.consent === "prompt" && outcome.prompt) {
+        console.log("");
+        for (const line of outcome.prompt.preamble)
+            console.log(`  ${line}`);
+        outcome = apply(await confirmYes(outcome.prompt.question));
+    }
+    if (outcome.consent === "install") {
+        for (const w of outcome.writes) {
+            console.log(`   ${w.ok ? "✓" : "•"} ${w.message}`);
+        }
+    }
+    if (outcome.consent === "skip-noninteractive") {
+        for (const line of outcome.messages) {
+            console.error(`   ${line}`);
+        }
+    }
+    return outcome.run;
+}
+function printVerifiedSummary(summary) {
+    for (const line of summary.lines) {
+        if (summary.degraded)
+            console.error(line);
+        else
+            console.log(line);
+    }
+}
 /**
  * Observe whether `dataDir`'s instance is running under launchd right now.
  *
@@ -11343,13 +11719,13 @@ function observeLaunchdManagement(dataDir, port) {
  * data dir does, via `resolveLaunchdLabel`.
  *
  * Idempotent-ish: stopping an already-stopped instance is a harmless no-op
- * on both paths (launchctl stop on an unloaded/idle service, or an empty
- * `lsof` match).
+ * on both paths (launchctl stop on an unloaded/idle service, or a
+ * NOT_RUNNING classification from the liveness machine).
  *
  * Throws when the resolved target provably belongs to a different instance
- * — see assertLaunchdServiceOwnedBy / assertPortInstanceOwnedBy. Callers
- * already treat a failed stop as fatal, which is the point: refusing beats
- * quiescing the wrong install.
+ * — see assertLaunchdServiceOwnedBy, or a DISAGREEMENT/UNKNOWN verdict from
+ * the liveness machine. Callers already treat a failed stop as fatal, which
+ * is the point: refusing beats quiescing the wrong install.
  */
 async function stopFlairProcess(port, dataDir) {
     if (process.platform === "darwin") {
@@ -11421,43 +11797,42 @@ async function stopFlairProcess(port, dataDir) {
             }
         }
     }
-    // Port-based stop (Linux, or macOS fallback when no launchd plist)
+    // Port-based stop (Linux, or macOS fallback when no launchd plist) — the
+    // five-state liveness machine (flair#1454). The old lsof-based tree is
+    // REPLACED, not patched: `lsof` absence used to render as "not running", and
+    // the pidfile was only consulted to attribute port-derived PIDs. Now the
+    // pidfile + identity sidecar are the primary evidence, and the health probe
+    // is a cross-check — never the verdict.
     console.log("Stopping...");
-    const { execSync } = await import("node:child_process");
-    // -sTCP:LISTEN plus a self-PID guard, both inside listeningPidsOnPort: a bare
-    // `lsof -ti :port` also matches CLIENT sockets referencing the port, including
-    // THIS CLI's own keep-alive connections left by the credential pre-flight's
-    // probeInstance() HTTP calls (flair#741). Without the filter, the upgrade
-    // path SIGTERM'd its own process mid-restart — "Stopping..." then death
-    // (exit 143) before "Starting..." ever ran, leaving the server down
-    // (flair#800, deterministic on the Linux/non-launchd default path).
-    // flair#905 moved both halves into that one helper because the same
-    // unfiltered pattern had survived in `flair stop`, `flair uninstall` and
-    // `flair doctor` — one guarded resolver is what keeps the next site honest.
-    // It returns [] when lsof matches nothing, which is this path's "not running".
-    const targets = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
-    if (targets.length === 0)
-        return;
-    // Deliberately outside any catch: a refusal must reach the caller, not be
-    // swallowed as "not running" and reported as a successful stop.
-    assertPortInstanceOwnedBy(port, dataDir, targets);
-    for (const target of targets) {
-        try {
-            process.kill(target, "SIGTERM");
-        }
-        catch { }
-    }
-    // flair#905 / lrf5: wait for every signalled process to actually exit.
-    // A blind 2-second sleep is not a guarantee — Harper may be flushing
-    // RocksDB WAL/MANIFEST, and the next start will fail with a locked data
-    // directory if the old process hasn't released it yet. The launchd path
-    // above already does this via waitForProcessExit; the port-based path
-    // must match that guarantee.
-    for (const target of targets) {
-        try {
-            await waitForProcessExit(target, STARTUP_TIMEOUT_MS);
+    const evidence = await gatherDaemonEvidence(port, dataDir);
+    const state = classifyDaemonState(evidence, { port, dataDir });
+    switch (state.state) {
+        case "RUNNING":
+        case "WEDGED": {
+            // Identity is already proven for both — killing a wedged daemon is
+            // recovery, not a recycled-PID gamble.
+            const pid = state.pid;
+            try {
+                process.kill(pid, "SIGTERM");
+            }
+            catch { /* already gone */ }
+            // flair#905 / lrf5: wait for the signalled process to actually exit. A
+            // blind sleep is not a guarantee — Harper may be flushing RocksDB
+            // WAL/MANIFEST, and the next start fails with a locked data directory if
+            // the old process hasn't released it yet.
+            try {
+                await waitForProcessExit(pid, STARTUP_TIMEOUT_MS);
+            }
+            catch { /* best-effort — the next start will surface the real problem */ }
+            return;
         }
-        catch { /* best-effort — the next start will surface the real problem */ }
+        case "NOT_RUNNING":
+            return; // idempotent no-op
+        case "DISAGREEMENT":
+        case "UNKNOWN":
+            // Deliberately outside any catch: a refusal must reach the caller, not
+            // be swallowed as "not running" and reported as a successful stop.
+            throw new Error(`refusing to stop: ${state.detail}`);
     }
 }
 /**
@@ -11586,6 +11961,10 @@ async function startFlairProcess(port, dataDir) {
         cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
     });
     proc.unref();
+    // Identity sidecar immediately after spawn (flair#1454 decision 3), before
+    // waitForHealth so startTimeMs stays within the ±2s tolerance.
+    if (proc.pid)
+        writeDaemonSidecar(dataDir, proc.pid, port);
     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
@@ -13057,6 +13436,21 @@ program
         return /^y(es)?$/i.test(answer.trim());
     }
     const detectedClients = detectClients().filter((c) => c.detected);
+    // flair#1439 — install-health (MCP, FLAIR_URL, CLAUDE.md, SessionStart
+    // hook, verified-read plan, keys classification, launchd) is the same
+    // catalog upgrade asserts. Adding a check to DOCTOR_CHECK_IDS widens
+    // both. Extra doctor UX (pi, --fix, execution probe, continuity,
+    // agent registration) stays below and does not redefine those checks.
+    const doctorCtx = {
+        homeDir: homedir(),
+        cwd: process.cwd(),
+        detectedClientIds: detectedClients.map((c) => c.id),
+        launchd: observeLaunchdManagement(defaultDataDir(), effectivePort),
+        keysDir,
+        keyAgentIds,
+        agentFlag: typeof opts.agent === "string" ? opts.agent : undefined,
+    };
+    const catalogBefore = runDoctorChecks(doctorCtx);
     if (detectedClients.length === 0) {
         console.log(`  ${render.icons.info} No MCP client detected — skipping client-integration checks`);
     }
@@ -13291,7 +13685,6 @@ program
                                                 wireCursor(wireEnv);
                                 console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
                                 if (wireResult.ok) {
-                                    fixed++;
                                     if (client.id === "claude-code")
                                         claudeCodeAgentId = fixAgentId;
                                     if (client.id === "codex")
@@ -13311,7 +13704,6 @@ program
                     const agentHint = knownAgentId ? "" : fixCommandAgentHint(keyAgentIds);
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix${agentHint} ${render.wrap(render.c.dim, `(wires ${client.label} automatically)`)}`);
                 }
-                issues++;
                 continue;
             }
             console.log(`  ${render.icons.ok} ${client.label}: MCP server configured (${render.wrap(render.c.dim, block.configPath)})`);
@@ -13369,15 +13761,12 @@ program
                         else {
                             const fixRes = fixClaudeMdBootstrap(process.cwd());
                             console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
-                            if (fixRes.ok)
-                                fixed++;
                         }
                     }
                 }
                 else {
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(adds the mcp__flair__bootstrap line to ./CLAUDE.md)")}`);
                 }
-                issues++;
             }
             // flair#1007: presence was never the problem — the failing entry was
             // perfectly well-formed. inspectSessionStartHook() additionally RUNS
@@ -13446,8 +13835,6 @@ program
                                 else {
                                     const upgrade = upgradeSessionStartHookCommand(homedir());
                                     console.log(`     ${upgrade.ok ? render.icons.ok : render.icons.warn} ${upgrade.message}`);
-                                    if (upgrade.ok && upgrade.changed)
-                                        fixed++;
                                 }
                             }
                         }
@@ -13458,7 +13845,6 @@ program
                     else {
                         console.log(`     ${render.wrap(render.c.dim, "This hook was hand-edited, so Flair will not rewrite it. To adopt the current form:")} flair hook install`);
                     }
-                    issues++;
                 }
             }
             else {
@@ -13476,15 +13862,12 @@ program
                             const fixAgentId = claudeCodeAgentId || opts.agent || process.env.FLAIR_AGENT_ID;
                             const fixRes = fixSessionStartHook(homedir(), fixAgentId);
                             console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
-                            if (fixRes.ok)
-                                fixed++;
                         }
                     }
                 }
                 else {
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(adds the flair-session-start SessionStart hook)")}`);
                 }
-                issues++;
             }
             // flair#1257 slice 2 — continuity capture pair (the check-5 twin of
             // the SessionStart check above: installed / absent / stale-form).
@@ -13584,8 +13967,6 @@ program
                                 else {
                                     const upgrade = upgradeSessionStartHookCommand(homedir(), hook.path);
                                     console.log(`     ${upgrade.ok ? render.icons.ok : render.icons.warn} ${upgrade.message}`);
-                                    if (upgrade.ok && upgrade.changed)
-                                        fixed++;
                                 }
                             }
                         }
@@ -13596,7 +13977,6 @@ program
                     else {
                         console.log(`     ${render.wrap(render.c.dim, "This hook was hand-edited, so Flair will not rewrite it. To adopt the current form:")} flair hook install --harness codex`);
                     }
-                    issues++;
                 }
             }
             else {
@@ -13614,18 +13994,27 @@ program
                             const fixAgentId = resolveHookAgentId({ agent: opts.agent }, homedir(), "codex");
                             const fixRes = fixSessionStartHook(homedir(), fixAgentId, hook.path);
                             console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
-                            if (fixRes.ok)
-                                fixed++;
                         }
                     }
                 }
                 else {
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex`);
                 }
-                issues++;
             }
         }
     }
+    // Catalog is the install-health verdict — count fail/unrun here, not
+    // via a second issues++ on MCP / CLAUDE.md / SessionStart hook above.
+    // --fix that cleared a catalog member shows up in the found→fixed delta.
+    const catalogAfter = autoFix ? runDoctorChecks(doctorCtx) : catalogBefore;
+    const catalogDelta = catalogIssueDelta(catalogBefore, catalogAfter);
+    issues += catalogDelta.found;
+    if (autoFix)
+        fixed += catalogDelta.fixed;
+    console.log(`\n  ${render.wrap(render.c.bold, "Install health")}`);
+    for (const row of renderCatalogDoctorLines(catalogAfter)) {
+        console.log(`  ${render.icons[row.icon]} ${row.line}`);
+    }
     // 7a. Resolve which agent identities the two verified-read sections below
     // (Fleet presence, Migrations) iterate (flair#722). Previously both
     // sections required --agent explicitly; doctor already enumerates every
@@ -15393,6 +15782,7 @@ memory.command("search [query]")
     .option("--q <query>", "search query (alias for positional arg)")
     .option("--limit <n>", "Max results", "5")
     .option("--tag <tag>")
+    .option("--include-archived", "Include basemented (archived) memories in results (default: excluded)")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--port <port>", "Harper HTTP port")
@@ -15410,10 +15800,51 @@ memory.command("search [query]")
     const body = { agentId, q, limit: parseInt(opts.limit, 10) || 5 };
     if (opts.tag)
         body.tag = opts.tag;
+    if (opts.includeArchived)
+        body.includeArchived = true;
     const baseUrl = resolveBaseUrl(opts);
     const res = await api("POST", "/SemanticSearch", body, { baseUrl, agentId });
     console.log(JSON.stringify(res, null, 2));
 });
+// ─── flair memory basement / restore ────────────────────────────────────────
+// flair#1472 Deliverable A — the user-facing archive action. `basement` sends a
+// memory to the basement (archived=true + stamps archivedAt); `restore`
+// un-basements it (clears archived/archivedAt/archivedBy). Both are GLOBAL and
+// deliberate: restore un-retires the memory for EVERY session, not a
+// session-local view (per-session reuse is drawers, Deliverable B, which does
+// not exist yet). Scoped to the caller's own memories (own-lane write).
+memory.command("basement <id>")
+    .description("Send a memory to the basement (archive it). Removes it from bootstrap + default search; still retrievable via `memory search --include-archived`. GLOBAL and deliberate — scoped to your own memories.")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--port <port>", "Harper HTTP port")
+    .action(async (id, opts) => {
+    const agentId = resolveSigningAgentId(opts, "memory basement");
+    if (!agentId) {
+        console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+        process.exit(2);
+    }
+    const baseUrl = resolveBaseUrl(opts);
+    const res = await api("POST", "/MemoryArchive", { id, action: "basement" }, { baseUrl, agentId });
+    console.log(JSON.stringify(res, null, 2));
+});
+memory.command("restore <id>")
+    .description("Restore a basemented (archived) memory. Clears archived/archivedAt/archivedBy. GLOBAL and deliberate — this un-retires the memory for EVERY session, not a session-local view (per-session reuse is drawers, which do not exist yet). Scoped to your own memories.")
+    .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET; alias for --url)")
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--port <port>", "Harper HTTP port")
+    .action(async (id, opts) => {
+    const agentId = resolveSigningAgentId(opts, "memory restore");
+    if (!agentId) {
+        console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+        process.exit(2);
+    }
+    const baseUrl = resolveBaseUrl(opts);
+    const res = await api("POST", "/MemoryArchive", { id, action: "restore" }, { baseUrl, agentId });
+    console.log(JSON.stringify(res, null, 2));
+});
 memory.command("list")
     .description("List an agent's memories (optionally filtered by --tag or embedding-backfill triage)")
     .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")