@tpsdev-ai/flair 0.33.0 → 0.35.0

package/dist/cli.js

@@ -6,13 +6,15 @@ 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 { homedir, tmpdir } from "node:os";
 import { join, resolve, sep, dirname } from "node:path";
-import { spawn, execFileSync } from "node:child_process";
+import { spawn, execFileSync, spawnSync, execSync } from "node:child_process";
 import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
 import { keystore } from "./keystore.js";
-import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl } from "./deploy.js";
+import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl, resolveDeployPublicUrl } from "./deploy.js";
+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";
@@ -21,11 +23,12 @@ import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemi
 import { flairCliVersion, mcpServerSpec, unpinnedSpecWarning } from "./lib/mcp-spec.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
-import { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, inferSoleAgentId, fixCommandAgentHint, describeAgentGateFinding, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
+import { readClientMcpBlock, checkClaudeMdBootstrap, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, inferSoleAgentId, fixCommandAgentHint, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
 import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
-import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
+import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snapshot-extract.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";
 // 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
@@ -1427,7 +1430,7 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
         catch { /* keysDir missing */ }
     }
     if (!agentId) {
-        return { state: "skipped", detail: "no agent id or key found" };
+        return { state: "skipped", reason: "no-agent", detail: "no agent id or key found" };
     }
     // Find the signing key. Prefer the standard locations (resolveKeyPath), but
     // fall back to the keysDir we were handed — `flair init` keys live there and
@@ -1439,7 +1442,7 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
             keyPath = candidate;
     }
     if (!keyPath) {
-        return { state: "skipped", detail: `no private key for agent '${agentId}'` };
+        return { state: "skipped", reason: "no-key", detail: `no private key for agent '${agentId}'` };
     }
     // Distinctive content vs. a PARAPHRASE query with deliberately ZERO shared
     // content words. If the search recovers the memory it can ONLY be by meaning.
@@ -1459,7 +1462,7 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
         });
         if (!writeRes.ok && writeRes.status !== 204) {
             const text = await writeRes.text().catch(() => "");
-            return { state: "skipped", detail: `could not write probe memory: HTTP ${writeRes.status} ${text.slice(0, 80)}` };
+            return { state: "skipped", reason: "probe-failed", detail: `could not write probe memory: HTTP ${writeRes.status} ${text.slice(0, 80)}` };
         }
         stored = true;
         // Allow the HNSW index to catch up before searching.
@@ -1472,7 +1475,7 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
         });
         if (!searchRes.ok) {
             const text = await searchRes.text().catch(() => "");
-            return { state: "skipped", detail: `SemanticSearch failed: HTTP ${searchRes.status} ${text.slice(0, 80)}` };
+            return { state: "skipped", reason: "probe-failed", detail: `SemanticSearch failed: HTTP ${searchRes.status} ${text.slice(0, 80)}` };
         }
         const data = await searchRes.json();
         // The server sets _warning ONLY when getMode() === "none" — i.e. the
@@ -1498,8 +1501,15 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
         return { state: "ok", score };
     }
     catch (err) {
+        // flair#1023: distinguish "your key will not load" from "the probe
+        // request failed". The former is raised before any request leaves the
+        // process, so it is never evidence about the instance — and "pass
+        // --agent" cannot fix it.
+        if (err instanceof KeyLoadError) {
+            return { state: "skipped", reason: "key-load", detail: err.message };
+        }
         const message = err instanceof Error ? err.message : String(err);
-        return { state: "skipped", detail: `probe error: ${message.slice(0, 100)}` };
+        return { state: "skipped", reason: "probe-failed", detail: `probe error: ${message.slice(0, 100)}` };
     }
     finally {
         // Best-effort cleanup of the ephemeral probe memory.
@@ -1545,6 +1555,11 @@ export async function probeFlairReachable(url, timeoutMs = 2000) {
  *   any other status, or a network error/timeout -> "unreachable" (could not
  *     verify one way or the other — e.g. a bare 401/403/500 doesn't tell us
  *     whether the agent exists, so we don't claim NOT registered on those)
+ *   the key file exists but will not load -> "key-unreadable" (flair#1023 —
+ *     signing happens strictly before the request, so authFetch can only
+ *     raise KeyLoadError while the instance is still untouched. This USED to
+ *     land in the catch below and be reported as "instance unreachable",
+ *     which doctor printed directly beneath its own "Harper responding" tick)
  *   no local key found for agentId (checked resolveKeyPath, then keysDir) -> "no-key"
  *     (can't sign the request at all — distinct from "unreachable" so the
  *     caller can print an accurate reason)
@@ -1591,6 +1606,13 @@ export async function checkAgentRegistered(baseUrl, agentId, keysDir) {
         return { state: "unreachable", detail: `HTTP ${res.status} ${text.slice(0, 80)}` };
     }
     catch (err) {
+        // flair#1023: a key that will not load is NOT a reachability fact. It is
+        // raised before the request is sent, so reporting it as "unreachable"
+        // sends the operator to firewalls and ports for a problem that is on
+        // their own disk.
+        if (err instanceof KeyLoadError) {
+            return { state: "key-unreadable", detail: err.message };
+        }
         const message = err instanceof Error ? err.message : String(err);
         return { state: "unreachable", detail: `instance unreachable: ${message.slice(0, 100)}` };
     }
@@ -1599,6 +1621,21 @@ export async function checkAgentRegistered(baseUrl, agentId, keysDir) {
 // Used during restart to confirm the old Harper process actually exited before
 // we start polling /Health — otherwise the still-shutting-down old process can
 // answer and we'd declare restart success while a gap is still ahead.
+/**
+ * Is `pid` a process that exists right now? Signal 0 performs the permission
+ * and existence checks without delivering anything (flair#1022) — a `hdb.pid`
+ * left behind by a process that is gone is not evidence about a running
+ * instance, and treating it as such produces confident wrong answers.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function waitForProcessExit(pid, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
@@ -1751,7 +1788,35 @@ export async function callOpsApi(opsUrl, body, user, pass) {
     }
     return res.json();
 }
-export async function buildDeployTarball(projectRoot, flairAdminPass) {
+/**
+ * Build the component tarball `flair init --remote` uploads via the ops API.
+ *
+ * ── What was wrong here (flair#1005 item 2) ─────────────────────────────────
+ * This function wrote a `.env` into its temp directory and then packed an
+ * EXPLICIT entries list that did not contain it, so the file was discarded with
+ * the temp directory on every call. It had been that way since the writer landed:
+ * a writer whose output nothing consumed. `.env` is now in the list, which is the
+ * whole of the fix — and `init-remote-ops.test.ts` asserts the entry is present
+ * in a real tarball, because "the file was written" was never evidence of
+ * anything.
+ *
+ * ── Why `publicUrl` replaced the password parameter (flair#1011) ────────────
+ * The discarded file assigned `HDB_ADMIN_PASSWORD` and `FLAIR_ADMIN_PASSWORD`.
+ * Shipping it as-is would have made a latent hazard live, for two independent
+ * reasons: Harper composes its own configuration before a component's `.env`
+ * loads, so `HDB_ADMIN_PASSWORD` set this way is a credential Harper is
+ * structurally unable to honour while flair reads it — two sources, one name,
+ * nothing comparing them; and the payload is ingested into Harper's
+ * `hdb_deployment` record, which is replicated to every node and retained for
+ * rollback, so anything in it is persisted cluster-wide.
+ *
+ * The parameter is REMOVED rather than validated. A caller cannot pass a password
+ * to a function that has nowhere to put one, and no future edit can reintroduce
+ * one without also reintroducing the parameter. The admin credential still
+ * reaches the instance the way it always actually did — `add_user`/`alter_user`
+ * over the ops API in `provisionFabric`.
+ */
+export async function buildDeployTarball(projectRoot, publicUrl) {
     const tmpDir = mkdtempSync(join(tmpdir(), "flair-deploy-"));
     try {
         // Copy deployment files into temp directory
@@ -1765,13 +1830,22 @@ export async function buildDeployTarball(projectRoot, flairAdminPass) {
                 cpSync(src, dst, { recursive: true });
             }
         }
-        // Write .env with 600 permissions
-        const envContent = [
-            `HDB_ADMIN_PASSWORD=${flairAdminPass}`,
-            `FLAIR_ADMIN_PASSWORD=${flairAdminPass}`,
-            "",
-        ].join("\n");
-        writeFileSync(join(tmpDir, ".env"), envContent, { mode: 0o600 });
+        // The component's environment. Harper reads this file only because
+        // config.yaml declares its `loadEnv` plugin (flair#1010) — without that
+        // declaration the file is present and inert, which is what made flair#1000
+        // hard to see. An existing `.env` in the project root is merged, never
+        // replaced; planComponentEnv keeps an operator's own value for the key.
+        const existingEnvPath = join(projectRoot, COMPONENT_ENV_FILENAME);
+        const existingEnv = existsSync(existingEnvPath) ? readFileSync(existingEnvPath, "utf8") : null;
+        const plan = planComponentEnv(existingEnv, publicUrl);
+        for (const notice of plan.notices)
+            console.warn(`⚠ flair init --remote: ${notice}`);
+        const envText = plan.text ?? existingEnv;
+        if (envText !== null) {
+            assertNoSecretKeysAdded(existingEnv, envText);
+            writeFileSync(join(tmpDir, COMPONENT_ENV_FILENAME), envText, { mode: 0o600 });
+            entries.push(COMPONENT_ENV_FILENAME);
+        }
         // Build compressed tarball
         const tarballPath = join(tmpDir, "deploy.tar.gz");
         await tarCreate({ gzip: true, cwd: tmpDir, file: tarballPath, portable: true }, entries);
@@ -1809,9 +1883,12 @@ export async function waitForFlairRestart(targetUrl, maxWaitMs = 30_000) {
 }
 export async function provisionFabric(target, opsTarget, clusterAdminUser, clusterAdminPass, flairAdminPass) {
     const projectRoot = process.cwd();
-    // 1. Build and deploy component tarball
+    // 1. Build and deploy component tarball. `target` is the served URL this
+    // function verifies against in step 2 — the same value the component must
+    // advertise in OAuth/A2A discovery, so it is what FLAIR_PUBLIC_URL is set from
+    // (flair#1005). A loopback target supplies nothing: see resolveDeployPublicUrl.
     console.log("Building deploy tarball...");
-    const { tarballB64 } = await buildDeployTarball(projectRoot, flairAdminPass);
+    const { tarballB64 } = await buildDeployTarball(projectRoot, resolveDeployPublicUrl(target));
     console.log("Deploying via ops API...");
     await callOpsApi(opsTarget, {
         operation: "deploy_component",
@@ -3961,7 +4038,13 @@ export async function classifyKeysDir(keysDir, baseUrl) {
                 entries: [],
             };
         }
-        const decision = classifyKeyFile(c.agentId, true, { state: reg.state, detail: reg.detail }, baseUrl);
+        // flair#1023 added "key-unreadable". It cannot occur here — this key's
+        // seed already parsed via isValidPrivateKeySeedFile above — but is
+        // handled explicitly rather than folded into the else: a key that will
+        // not load means exactly what prune already calls "invalid".
+        const decision = reg.state === "key-unreadable"
+            ? classifyKeyFile(c.agentId, false, null, baseUrl)
+            : classifyKeyFile(c.agentId, true, { state: reg.state, detail: reg.detail }, baseUrl);
         entries.push({ name: c.name, class: decision.class, reason: decision.reason, agentId: c.agentId });
     }
     return { aborted: false, entries };
@@ -4162,6 +4245,14 @@ hook
     console.log(`  ${status.correctShape ? render.icons.ok : render.icons.warn} wired${status.correctShape ? "" : " (unexpected shape — was it hand-edited?)"}`);
     console.log(`     ${render.wrap(render.c.dim, "Agent:")}     ${status.agentId ?? render.wrap(render.c.dim, "(unknown — could not parse command)")}`);
     console.log(`     ${render.wrap(render.c.dim, "Flair URL:")} ${status.flairUrl ?? render.wrap(render.c.dim, "(unknown — could not parse command)")}`);
+    // flair#1007 — whether a command that stopped resolving would fail quietly
+    // or print an error on every session start.
+    if (status.silenced) {
+        console.log(`     ${render.wrap(render.c.dim, "On failure:")} silent (exit 0, no output)`);
+    }
+    else {
+        console.log(`     ${render.icons.warn} ${render.wrap(render.c.dim, "On failure:")} prints an error on every session — run \`flair hook install\` to adopt the silent form`);
+    }
     console.log("");
 });
 // ─── flair mcp ───────────────────────────────────────────────────────────────
@@ -8733,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, "-");
@@ -8857,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";
@@ -8877,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).
@@ -9114,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
@@ -9367,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
@@ -9383,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.
@@ -9481,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
@@ -9611,8 +9774,28 @@ program
     // The delegated `flair restart` printed its own success line; don't say it twice.
     if (!restartWasDelegated)
         console.log("✅ Flair restarted");
+    // flair#1022 — the headline defect. The restart above is allowed to fall
+    // back off launchd to a plain detached spawn, and SHOULD be: a running
+    // instance beats a down one. What was missing is that the fallback changes
+    // whether anything brings this instance back after a reboot, and the
+    // verification below made no claim about it. `healthy, authenticated,
+    // running <new version>` was every word true of an instance that had just
+    // been orphaned.
+    //
+    // Observed here rather than reported by the restart, because
+    // `restartAfterUpgrade` may have delegated to the newly installed CLI in a
+    // CHILD PROCESS (flair#905) — no in-process flag crosses that boundary.
+    // Asking launchd is the one form of this check that is correct on both
+    // paths.
+    const management = observeLaunchdManagement(upgradeDataDir, port);
+    const detached = isDetached(management);
     if (!shouldVerify) {
         console.log("  (--no-verify: skipping post-restart verification)");
+        if (detached) {
+            for (const line of renderDetachedWarning(management, "Flair is running, but NOT under launchd.")) {
+                console.error(line);
+            }
+        }
         return;
     }
     console.log("\nVerifying...");
@@ -9629,7 +9812,20 @@ program
     });
     const verdict = decideAfterVerify(verify, previousFlairVersion);
     if (verdict.kind === "ok") {
-        console.log(`✅ verified: healthy, authenticated${verify.version ? `, running ${verify.version}` : ""}`);
+        // 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);
+        }
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -9641,10 +9837,21 @@ 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") {
-        console.log(`✅ upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}.`);
+        // 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}` : ""}.`);
         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}`);
@@ -9746,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
@@ -9755,12 +9972,20 @@ program
         const { plistPath } = resolveLaunchdLabel(dataDir);
         if (existsSync(plistPath)) {
             try {
+                // flair#1022, same pre-flight as startFlairProcess: launchctl exits 0
+                // for a job it cannot exec, so a stale plist is only ever observable
+                // as a startup timeout unless the paths are checked first.
+                const stalePlist = diagnoseLaunchdPlistPaths(plistPath);
+                if (stalePlist) {
+                    throw new Error(`${stalePlist.message} Fix it with: ${stalePlist.remedy.join(" && ")}`);
+                }
                 const { execSync } = await import("node:child_process");
                 const { label, migrated } = ensureLaunchdServiceLoaded(dataDir, (cmd) => execSync(cmd, { stdio: "pipe" }));
                 if (migrated)
                     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;
             }
@@ -9801,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 {
@@ -9904,6 +10130,71 @@ function assertPortInstanceOwnedBy(port, dataDir, listeningPids) {
         + `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
+// are the only places that talk to real launchd or the real filesystem, so a
+// test can exercise every branch above without either.
+/** `launchctl list <label>`, capped so an unreachable launchd cannot hang the CLI. */
+const realLaunchctlLister = (label) => {
+    const res = spawnSync("launchctl", ["list", label], {
+        encoding: "utf-8",
+        timeout: LAUNCHCTL_QUERY_TIMEOUT_MS,
+    });
+    return { code: res.status, stdout: res.stdout ?? "" };
+};
+/**
+ * Which process is actually serving `dataDir` — Harper's own `hdb.pid` first,
+ * then the listener on `port`.
+ *
+ * `hdb.pid` is written by the Harper process itself on every boot regardless
+ * of who spawned it, which is exactly the property this needs: it is the same
+ * number on the launchd path and on the direct-spawn fallback, so comparing it
+ * against launchd's reported PID is a real comparison rather than a proxy.
+ * The port listener is the backstop for an install whose PID file is missing;
+ * `null` (neither available) is handled by the caller as "no evidence", never
+ * as "detached".
+ */
+function resolveInstanceServingPid(dataDir, port) {
+    let listeningPids = [];
+    try {
+        listeningPids = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
+    }
+    catch { /* lsof unavailable — the PID file may still answer */ }
+    return pickInstancePid({
+        pidFilePid: readHarperPid(dataDir),
+        isAlive: isProcessAlive,
+        listeningPids,
+    });
+}
+/**
+ * Observe whether `dataDir`'s instance is running under launchd right now.
+ *
+ * Called AFTER a restart completes, by both `flair restart` and `flair
+ * upgrade` — see the module header for why this is an observation rather than
+ * a flag carried out of `startFlairProcess` (the upgrade's restart may happen
+ * in a child process, so no in-process flag survives).
+ */
+function observeLaunchdManagement(dataDir, port) {
+    // Answered without touching the filesystem or lsof off darwin — this runs on
+    // the success path of every restart and upgrade, including Linux's, where
+    // there is no launchd to have fallen back from.
+    if (process.platform !== "darwin") {
+        return { state: "not-applicable", detail: `${process.platform} does not use launchd` };
+    }
+    const { label, plistPath } = resolveLaunchdLabel(dataDir);
+    if (!existsSync(plistPath)) {
+        return { state: "no-service", detail: `no launchd service is registered for this instance (${plistPath})` };
+    }
+    return assessLaunchdManagement({
+        platform: process.platform,
+        label,
+        plistPath,
+        instancePid: resolveInstanceServingPid(dataDir, port),
+        plistExists: existsSync,
+        list: realLaunchctlLister,
+    });
+}
 /**
  * Stop the local Flair (Harper) process — launchd `stop` on darwin when a
  * plist is present (falling back on failure), otherwise a manual SIGTERM by
@@ -9947,12 +10238,48 @@ async function stopFlairProcess(port, dataDir) {
                 // can race against the still-shutting-down old process and return
                 // success before the new one comes up.
                 const oldPid = readHarperPid(dataDir);
+                // flair#1022: ask launchd whether the process we are about to wait on
+                // is even its job's, BEFORE unloading. When the instance is already
+                // running outside launchd — the state a previous fallback leaves
+                // behind, and the state a stale plist guarantees — the unload has
+                // nothing to signal, so waiting on `oldPid` burns the FULL startup
+                // budget and then reports the meaningless
+                // "Process <pid> did not exit within 60000ms". That was the first of
+                // the reported incident's two 60-second hangs. The unload still runs
+                // (a loaded-but-broken job must not be left able to respawn); only the
+                // wait is skipped, and the fallback is entered immediately with a
+                // reason that names the real condition.
+                //
+                // Gated on a LIVE recorded PID, and that gate is load-bearing: with no
+                // running process there is nothing to wait for and nothing to
+                // reattribute, and `stopFlairProcess` is documented as a harmless
+                // no-op when the instance is already stopped. Without the gate, an
+                // already-stopped instance takes the port fallback, which refuses when
+                // it cannot attribute a listener (flair#915) — turning an idempotent
+                // stop into a failed restart. Caught by the flair#902/#914 suites.
+                //
+                // Asked BEFORE the unload, because after it launchd no longer knows
+                // the label at all and every answer would be "detached".
+                const managed = oldPid !== null && isProcessAlive(oldPid)
+                    ? assessLaunchdManagement({
+                        platform: process.platform,
+                        label,
+                        plistPath,
+                        instancePid: oldPid,
+                        plistExists: existsSync,
+                        list: realLaunchctlLister,
+                    })
+                    : null;
                 // unload stops the job AND prevents KeepAlive from respawning it.
                 // launchctl stop alone is insufficient for a KeepAlive job (flair#874).
                 try {
                     execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
                 }
                 catch { }
+                if (managed && isDetached(managed)) {
+                    throw new Error(`launchd is not running this instance — ${managed.detail}`
+                        + `${managed.remedy?.length ? ` Fix it with: ${managed.remedy.join(" && ")}` : ""}`);
+                }
                 if (oldPid)
                     await waitForProcessExit(oldPid, STARTUP_TIMEOUT_MS);
                 return;
@@ -10014,10 +10341,26 @@ async function startFlairProcess(port, dataDir) {
             // success.
             assertLaunchdServiceOwnedBy(dataDir, label, plistPath, "start");
             try {
+                // flair#1022: launchd will not tell us it cannot exec the job.
+                // `launchctl load` and `launchctl start` BOTH exit 0 for a plist whose
+                // ProgramArguments[0] does not exist (measured, see the module header),
+                // so the only way this loop learns anything is by waiting the full
+                // startup budget for a port that will never open — the reported
+                // incident's second 60-second hang, ending in "did not respond within
+                // 60000ms (120 attempts)", an error about a port that says nothing
+                // about the cause. The paths in the plist are absolute and checkable
+                // with an existsSync, so check them first and turn a two-minute silence
+                // into an immediate, named diagnosis. Still falls back — a running
+                // instance beats a down one — just without the wait or the mystery.
+                const stalePlist = diagnoseLaunchdPlistPaths(plistPath);
+                if (stalePlist) {
+                    throw new Error(`${stalePlist.message} Fix it with: ${stalePlist.remedy.join(" && ")}`);
+                }
                 const { execSync } = await import("node:child_process");
                 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) {
@@ -10065,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
@@ -10190,6 +10534,18 @@ program
     // and saying so here is what keeps that true when someone adds one.
     try {
         await restartFlair(port, defaultDataDir());
+        // flair#1022: a restart that fell back off launchd left the instance
+        // running but unmanaged, and "✅ Flair restarted" was true of both
+        // outcomes. Ask launchd what it is actually running now — an
+        // observation, not a flag out of the restart, so it is right even when
+        // the detachment predates this command.
+        const managed = observeLaunchdManagement(defaultDataDir(), port);
+        if (isDetached(managed)) {
+            for (const line of renderDetachedWarning(managed, "Flair restarted, but it is NOT running under launchd.")) {
+                console.error(line);
+            }
+            return;
+        }
         console.log("✅ Flair restarted");
     }
     catch (err) {
@@ -11229,6 +11585,54 @@ program
         }
     }
     catch { /* best-effort — a stat failure shouldn't fail doctor */ }
+    // 3d. The URL this instance tells the world to use (flair#1005, flair#1000).
+    //
+    // Asks the instance for its OWN discovery document rather than inferring
+    // anything from config: /OAuthMetadata's `issuer` is the exact field that was
+    // wrong in flair#1000, and it is the only thing that proves what a client
+    // will actually be handed. describePublicUrlFinding (src/component-env.ts) is
+    // pure decision logic, unit-tested, and documents in its own header why the
+    // detectable condition is DRIFT rather than "unset on a public instance" —
+    // doctor reaches this instance over loopback and cannot observe whether it is
+    // also reachable at a public address.
+    if (harperResponding) {
+        let advertisedIssuer = null;
+        try {
+            const res = await fetch(`${baseUrl}/OAuthMetadata`, { signal: AbortSignal.timeout(5000) });
+            if (res.ok) {
+                const doc = (await res.json());
+                if (typeof doc?.issuer === "string" && doc.issuer !== "")
+                    advertisedIssuer = doc.issuer;
+            }
+        }
+        catch { /* unreachable/unparseable → null → the finding is skipped, not passed */ }
+        // The component directory for a local install is the flair package itself:
+        // `flair start` spawns `harper run .` with cwd = flairPackageDir().
+        const componentEnvPath = join(flairPackageDir(), COMPONENT_ENV_FILENAME);
+        let componentEnvValue = null;
+        try {
+            if (existsSync(componentEnvPath)) {
+                componentEnvValue = readEnvValue(readFileSync(componentEnvPath, "utf-8"), PUBLIC_URL_KEY);
+            }
+        }
+        catch { /* unreadable → treat as absent */ }
+        const finding = describePublicUrlFinding({
+            advertisedIssuer,
+            componentEnvValue,
+            processEnvValue: process.env.FLAIR_PUBLIC_URL ?? null,
+            componentEnvPath,
+        });
+        if (finding) {
+            const icon = finding.icon === "ok" ? render.icons.ok
+                : finding.icon === "warn" ? render.icons.warn
+                    : render.icons.error;
+            console.log(`  ${icon} ${finding.message}`);
+            if (finding.fixHint)
+                console.log(`     ${render.wrap(render.c.dim, "Fix:")} ${finding.fixHint}`);
+            if (finding.isIssue)
+                issues++;
+        }
+    }
     // 4. Embeddings check — REAL semantic round-trip (only if Harper is responding).
     //
     // The dead-simple `{ q: "test" }` probe used to pass even when embeddings were
@@ -11253,13 +11657,21 @@ program
                 console.log(`     ${render.wrap(render.c.dim, "See:")} docs/troubleshooting.md ${render.wrap(render.c.dim, "→ \"Semantic search DEGRADED\"")}`);
                 issues++;
                 break;
-            case "skipped":
-                // Could not run the round-trip (no agent / no key). Don't claim
-                // all-clear — surface that the check was skipped, but don't count it
-                // as a hard issue since the user may simply not have an agent yet.
+            case "skipped": {
+                // Could not run the round-trip. Don't claim all-clear — surface that
+                // the check was skipped, but don't count it as a hard issue since
+                // the user may simply not have an agent yet.
+                //
+                // flair#1023: the remedy is chosen from the classified reason
+                // (embeddingsSkipRemedy, src/doctor-client.ts) instead of being
+                // printed unconditionally. A key that will not decode gets no
+                // "pass --agent" advice, because following it changes nothing.
                 console.log(`  ${render.icons.warn} Embeddings: not verified ${render.wrap(render.c.dim, `(${semanticStatus.detail})`)}`);
-                console.log(`     ${render.wrap(render.c.dim, "Pass --agent <id> (or set FLAIR_AGENT_ID) so doctor can run a real semantic round-trip.")}`);
+                const remedy = embeddingsSkipRemedy(semanticStatus.reason);
+                if (remedy)
+                    console.log(`     ${render.wrap(render.c.dim, remedy)}`);
                 break;
+            }
         }
     }
     // 5. Stale PID file (skip if already reported in port check)
@@ -11418,7 +11830,11 @@ program
                 issues++;
             }
             else {
-                console.log(`     ${render.icons.warn} could not verify agent registration ${render.wrap(render.c.dim, `(${reg.detail})`)}`);
+                // flair#1023: `reachable` was just established two lines above, so
+                // reuse the same self-inconsistency guard the agent gates use
+                // rather than echoing a detail that may claim the opposite.
+                const finding = describeAgentGateFinding(block.agentId, reg.state, reg.detail, { instanceReachable: reachable });
+                console.log(`     ${render.icons.warn} ${finding?.message ?? `could not verify agent registration (${reg.detail})`}`);
             }
         }
         // Claude-Code-specific: CLAUDE.md + SessionStart hook. Only Claude Code
@@ -11452,9 +11868,75 @@ program
                 }
                 issues++;
             }
-            const hook = checkSessionStartHook(homedir());
+            // flair#1007: presence was never the problem — the failing entry was
+            // perfectly well-formed. inspectSessionStartHook() additionally RUNS
+            // the registered command (bounded, side-effect-free via
+            // FLAIR_HOOK_PROBE) so doctor can tell "wired" from "wired and still
+            // works", and reports the shell-level silencing separately so an
+            // already-installed loud hook can be upgraded rather than only
+            // diagnosed.
+            const hook = inspectSessionStartHook(homedir());
             if (hook.present) {
-                console.log(`  ${render.icons.ok} SessionStart hook: flair-session-start wired in ${render.wrap(render.c.dim, hook.path)}`);
+                if (hook.execution === "broken") {
+                    // Reported in full, with the remedy — but NOT counted as an issue,
+                    // so it never flips doctor's exit code on its own. This is a
+                    // verification of the environment at the moment doctor runs (a
+                    // cold `npx` cache, an offline machine, a slow registry), exactly
+                    // like the FLAIR_URL reachability and agent-registration
+                    // verifications above, which are warnings for the same reason. A
+                    // fresh, correct install on a machine that simply has not fetched
+                    // the adapter yet must not be told it is broken in the exit code.
+                    // The unsilenced finding below IS counted: that one is a fact
+                    // about the file, true regardless of the environment.
+                    console.log(`  ${render.icons.warn} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)}, but its command did not run just now`);
+                    console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                    console.log(`     ${render.wrap(render.c.dim, "If this persists, the Node runtime probably changed and the globally")}`);
+                    console.log(`     ${render.wrap(render.c.dim, "installed @tpsdev-ai/flair-mcp no longer resolves for it.")}`);
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} npm install -g @tpsdev-ai/flair-mcp ${render.wrap(render.c.dim, "(reinstall for the runtime you use now)")}`);
+                    console.log(`     ${render.wrap(render.c.dim, "Or, if you no longer want ambient memory:")} flair hook uninstall`);
+                }
+                else if (hook.execution === "unknown") {
+                    console.log(`  ${render.icons.warn} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)}, but could not be verified ${render.wrap(render.c.dim, `(${hook.detail ?? "no detail"})`)}`);
+                }
+                else if (!hook.ours) {
+                    console.log(`  ${render.icons.ok} SessionStart hook: wired in ${render.wrap(render.c.dim, hook.path)} ${render.wrap(render.c.dim, "(custom command — not verified, not modified)")}`);
+                }
+                else {
+                    console.log(`  ${render.icons.ok} SessionStart hook: flair-session-start wired in ${render.wrap(render.c.dim, hook.path)} ${render.wrap(render.c.dim, "and still runs")}`);
+                }
+                // Independent of whether it runs today: would it stay quiet if it
+                // stopped? Only offered as a repair when the command is the exact
+                // string Flair itself wrote — a hand-edited or pinned hook is the
+                // user's, and doctor reports on it rather than rewriting it.
+                if (!hook.silenced && hook.ours) {
+                    console.log(`  ${render.icons.warn} SessionStart hook: a failure would print an error on every session (this command predates the silent-failure fix)`);
+                    if (hook.upgradable) {
+                        if (autoFix) {
+                            if (dryRun) {
+                                console.log(`     ${render.wrap(render.c.dim, "Would rewrite the hook command in")} ${hook.path}`);
+                            }
+                            else {
+                                const proceed = await confirmFix(`  Rewrite the Flair SessionStart hook in ${hook.path} so failures stay silent? [y/N] `);
+                                if (!proceed) {
+                                    console.log(`     Skipped.`);
+                                }
+                                else {
+                                    const upgrade = upgradeSessionStartHookCommand(homedir());
+                                    console.log(`     ${upgrade.ok ? render.icons.ok : render.icons.warn} ${upgrade.message}`);
+                                    if (upgrade.ok && upgrade.changed)
+                                        fixed++;
+                                }
+                            }
+                        }
+                        else {
+                            console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(rewrites the hook command in place — same agent, same instance)")}`);
+                        }
+                    }
+                    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 {
                 console.log(`  ${render.icons.error} SessionStart hook: not found in ${render.wrap(render.c.dim, hook.path)}`);
@@ -11511,7 +11993,10 @@ program
     for (const id of verifiedReadAgentIds) {
         const reg = await checkAgentRegistered(baseUrl, id, defaultKeysDir());
         agentGates.push({ id, state: reg.state, detail: reg.detail });
-        const finding = describeAgentGateFinding(id, reg.state, reg.detail);
+        // harperResponding is necessarily true here (verifiedReadAgentIds is
+        // empty otherwise), so an "unreachable" verdict from this loop is
+        // always a self-contradiction — flair#1023. Hand the guard the fact.
+        const finding = describeAgentGateFinding(id, reg.state, reg.detail, { instanceReachable: harperResponding });
         if (finding?.isIssue)
             issues++;
     }
@@ -11522,7 +12007,7 @@ program
     // agent and moves on to the next (failure isolation).
     function renderAgentGateHeader(gate) {
         console.log(`    ${render.wrap(render.c.dim, `Agent: ${gate.id}`)}`);
-        const finding = describeAgentGateFinding(gate.id, gate.state, gate.detail);
+        const finding = describeAgentGateFinding(gate.id, gate.state, gate.detail, { instanceReachable: harperResponding });
         if (!finding)
             return true;
         const icon = finding.icon === "error" ? render.icons.error : render.icons.warn;
@@ -11710,7 +12195,7 @@ program
             console.log(`  ${render.icons.info} Pass --agent <id> (with a matching key in ~/.flair/keys) to see migration state — requires a verified read, same as Fleet presence above.`);
         }
         else {
-            const passedGates = agentGates.filter((g) => describeAgentGateFinding(g.id, g.state, g.detail) === null);
+            const passedGates = agentGates.filter((g) => describeAgentGateFinding(g.id, g.state, g.detail, { instanceReachable: harperResponding }) === null);
             for (const gate of passedGates) {
                 renderAgentGateHeader(gate);
                 const keyPath = resolveKeyPath(gate.id) ?? join(defaultKeysDir(), `${gate.id}.key`);
@@ -15369,4 +15854,6 @@ export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBi
 // Harper's own config — the per-instance port record (flair#914)
 harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
 // launchd label (flair#693)
-LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, cleanupLegacyLaunchdPlist, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, };
+LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, cleanupLegacyLaunchdPlist, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, 
+// launchd management observation (flair#1022)
+observeLaunchdManagement, resolveInstanceServingPid, };