@tpsdev-ai/flair 0.32.0 → 0.34.0

package/dist/cli.js

@@ -6,11 +6,12 @@ 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 { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache } from "./version-handshake.js";
@@ -21,11 +22,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 +1429,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 +1441,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 +1461,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 +1474,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 +1500,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 +1554,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 +1605,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 +1620,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 +1787,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 +1829,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 +1882,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 +4037,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 +4244,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 ───────────────────────────────────────────────────────────────
@@ -9611,8 +9701,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 +9739,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 +9764,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}`);
@@ -9684,17 +9818,38 @@ program
     // 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) {
-            for (const pid of pids) {
-                try {
-                    process.kill(pid, "SIGTERM");
+            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);
+            }
+            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);
+            }
+            else {
+                for (const pid of pids) {
+                    try {
+                        process.kill(pid, "SIGTERM");
+                    }
+                    catch { /* already gone */ }
                 }
-                catch { /* already gone */ }
+                console.log(`✅ Flair stopped (killed PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")})`);
             }
-            console.log(`✅ Flair stopped (killed PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")})`);
         }
         else {
             console.log("Flair is not running.");
@@ -9734,6 +9889,13 @@ 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)
@@ -9859,17 +10021,94 @@ export function assertLaunchdServiceOwnedBy(dataDir, label, plistPath, action) {
  * wrong today whenever the port does not match.
  */
 function assertPortInstanceOwnedBy(port, dataDir, listeningPids) {
-    if (resolve(dataDir) === defaultDataDir())
-        return;
+    // (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);
-    if (expected !== null && listeningPids.includes(expected))
+    // 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;
-    const why = expected === null
-        ? `no hdb.pid under that directory, so it does not look like a running instance`
-        : `its recorded PID ${expected} is not the process listening on ${port}`;
-    throw new Error(`refusing to stop the process listening on port ${port}: it cannot be attributed to ${resolve(dataDir)} (${why}). ` +
-        `Stopping by port alone would signal a different Flair instance. ` +
-        `Pass --port with the port ${resolve(dataDir)} actually serves, or omit --data-dir to operate on the default install.`);
+    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
+// 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
@@ -9914,12 +10153,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;
@@ -9981,6 +10256,21 @@ 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);
@@ -10157,6 +10447,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) {
@@ -10171,7 +10473,11 @@ program
     .option("--purge", "Also remove data and keys (destructive)")
     .action(async (opts) => {
     const platform = process.platform;
-    const port = readPortFromConfig() ?? DEFAULT_PORT;
+    // Use the unified resolver: Harper's config > per-user config > default.
+    // A default of 19926 that is "present but wrong" beats the actual port
+    // Harper is serving on (flair#819). resolveHttpPort reads Harper's own
+    // config in the data directory, which is authoritative.
+    const port = resolveHttpPort({}, "address");
     // Stop first: remove launchd service(s) on macOS, then kill by port on
     // all platforms. Removes BOTH the new instance-scoped plist and a
     // pre-flair#693 legacy plist if present — uninstall's job is to purge
@@ -10198,51 +10504,88 @@ program
     // Kill any process still on the port (covers direct-start, no-service, or
     // failed unload). Listening sockets only, never our own PID — see
     // parseListeningPids (flair#800/flair#905).
+    //
+    // Guard (flair#917): refuse to SIGTERM a PID that cannot be attributed to
+    // this Flair instance. A port is not an identity — something else can hold
+    // it. Killing the wrong PID and then purging data is the whole bug.
+    let refusedKill = false;
     try {
         const { execSync } = await import("node:child_process");
         const pids = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
         if (pids.length > 0) {
-            for (const pid of pids) {
-                try {
-                    process.kill(pid, "SIGTERM");
+            // Verify ownership before killing: the PID must match this instance's
+            // recorded PID (hdb.pid). If no PID file exists, Harper is already
+            // stopped and the port is stale — safe to skip.
+            const dataDir = defaultDataDir();
+            const harperPid = readHarperPid(dataDir);
+            if (harperPid !== null) {
+                // PID file exists — the PID on the port must be Harper or we refuse.
+                if (!pids.includes(harperPid)) {
+                    console.log(`⚠️  Process(es) on port ${port} (PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")}) `
+                        + `do not match this Flair instance (PID ${harperPid}). `
+                        + `Not killing — cannot attribute the process to this instance. `
+                        + `Stop the process manually if it is not Flair.`);
+                    refusedKill = true;
                 }
-                catch { }
+                else {
+                    for (const pid of pids) {
+                        try {
+                            process.kill(pid, "SIGTERM");
+                        }
+                        catch { }
+                    }
+                    await new Promise(r => setTimeout(r, 2000));
+                    console.log("✅ Flair process stopped");
+                }
+            }
+            else {
+                // No PID file — Harper is not (or was not) running here.
+                // The port may be stale or held by something else; don't risk killing it.
+                console.log(`⚠️  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 killing — stop the process manually if it is not Flair.`);
+                refusedKill = true;
             }
-            // Wait for process to release file handles (RocksDB)
-            await new Promise(r => setTimeout(r, 2000));
-            console.log("✅ Flair process stopped");
         }
     }
     catch { /* not running */ }
-    // Remove config
-    const cfgPath = configPath();
-    if (existsSync(cfgPath)) {
-        const { unlinkSync } = await import("node:fs");
-        unlinkSync(cfgPath);
-        console.log("✅ Config removed");
+    // Always remove per-user config on uninstall.
+    {
+        const cfgPath = configPath();
+        if (existsSync(cfgPath)) {
+            const { unlinkSync } = await import("node:fs");
+            unlinkSync(cfgPath);
+            console.log("✅ Config removed");
+        }
     }
     if (opts.purge) {
-        const { rmSync } = await import("node:fs");
-        const dataDir = defaultDataDir();
-        const keysDir = defaultKeysDir();
-        const flairDir = join(homedir(), ".flair");
-        if (existsSync(dataDir)) {
-            rmSync(dataDir, { recursive: true, force: true });
-            console.log("✅ Data removed: " + dataDir);
-        }
-        if (existsSync(keysDir)) {
-            rmSync(keysDir, { recursive: true, force: true });
-            console.log("✅ Keys removed: " + keysDir);
+        if (refusedKill) {
+            console.log("\n⚠️  Skipping purge: could not attribute the process on port — data preserved.");
+            console.log("Stop the process manually, then re-run: flair uninstall --purge");
         }
-        // Remove .flair dir if empty
-        try {
-            const { readdirSync, rmdirSync } = await import("node:fs");
-            if (existsSync(flairDir) && readdirSync(flairDir).length === 0) {
-                rmdirSync(flairDir);
+        else {
+            const { rmSync } = await import("node:fs");
+            const dataDir = defaultDataDir();
+            const keysDir = defaultKeysDir();
+            const flairDir = join(homedir(), ".flair");
+            if (existsSync(dataDir)) {
+                rmSync(dataDir, { recursive: true, force: true });
+                console.log("✅ Data removed: " + dataDir);
+            }
+            if (existsSync(keysDir)) {
+                rmSync(keysDir, { recursive: true, force: true });
+                console.log("✅ Keys removed: " + keysDir);
             }
+            // Remove .flair dir if empty
+            try {
+                const { readdirSync, rmdirSync } = await import("node:fs");
+                if (existsSync(flairDir) && readdirSync(flairDir).length === 0) {
+                    rmdirSync(flairDir);
+                }
+            }
+            catch { /* non-empty, that's fine */ }
+            console.log("\n🗑️  Flair fully purged");
         }
-        catch { /* non-empty, that's fine */ }
-        console.log("\n🗑️  Flair fully purged");
     }
     else {
         console.log("\nData and keys preserved at ~/.flair/");
@@ -10892,17 +11235,24 @@ program
     else if (versionCheckResult.latest) {
         console.log(`  ${render.icons.ok} flair ${__pkgVersion} is current`);
     }
-    // Helper: try to reach Harper on a given port
+    // Helper: try to reach Harper on a given port.
+    // Must return true ONLY when Harper's /Health endpoint returns 200 OK.
+    // A generic HTTP status > 0 (flair#862) would accept 404 from a Node
+    // inspector on 9229 or any other service — "present but wrong" beats
+    // "absent but correct".
     async function probePort(p) {
         try {
             const res = await fetch(`http://127.0.0.1:${p}/Health`, { signal: AbortSignal.timeout(3000) });
-            return res.status > 0;
+            return res.ok; // 200-299 only — /Health returns { ok: true } on 200
         }
         catch {
             return false;
         }
     }
-    // Helper: discover what port a Harper PID is listening on
+    // Helper: discover what port a Harper PID is listening on.
+    // Scans ALL listening ports for this PID and returns the first one that
+    // responds to /Health with 200 OK. This avoids picking a debug port (9229)
+    // or any non-Flair listener that happens to share the process (flair#862).
     async function discoverPortFromPid(pid) {
         // Defense-in-depth: caller already validates, but re-check here
         if (!/^\d+$/.test(pid))
@@ -10910,9 +11260,16 @@ program
         try {
             const { execSync } = await import("node:child_process");
             const out = execSync(`lsof -aPi -p ${pid} -sTCP:LISTEN -Fn 2>/dev/null || true`, { encoding: "utf-8" });
-            const match = out.match(/:(\d+)$/m);
-            if (match)
-                return Number(match[1]);
+            // Extract all ports from lsof -Fn output (lines like "n127.0.0.1:PORT")
+            const ports = [...out.matchAll(/n(?:\S+):(\d+)/g)].map(m => Number(m[1]));
+            if (ports.length === 0)
+                return null;
+            // Try each port until one responds to /Health with 200 OK
+            for (const port of ports) {
+                if (await probePort(port))
+                    return port;
+            }
+            return null; // No port responded to /Health
         }
         catch { /* ignore */ }
         return null;
@@ -11141,6 +11498,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
@@ -11165,13 +11570,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)
@@ -11330,7 +11743,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
@@ -11364,9 +11781,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)}`);
@@ -11423,7 +11906,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++;
     }
@@ -11434,7 +11920,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;
@@ -11622,7 +12108,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`);
@@ -12698,7 +13184,7 @@ memory.command("add [content]")
     .description("Write a new memory row for an agent (content via positional arg or --content)")
     .requiredOption("--agent <id>")
     .option("--content <text>", "memory content (alias for positional arg)")
-    .option("--durability <d>", "standard").option("--tags <csv>")
+    .option("--durability <d>", "permanent|persistent|standard|ephemeral (default standard). Also decides the default visibility when --visibility is omitted: permanent/persistent -> shared, standard/ephemeral -> private").option("--tags <csv>")
     .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content)")
     .option("--subject <text>", "one-line title / entity this memory is about")
     .option("--derived-from <csv>", "Comma-separated source Memory IDs this memory was distilled/reflected from (sets Memory.derivedFrom; used by the `rem rapid` reflection loop)")
@@ -12719,8 +13205,21 @@ memory.command("add [content]")
         body.summary = opts.summary;
     if (opts.subject)
         body.subject = opts.subject;
-    if (opts.visibility)
-        body.visibility = String(opts.visibility).trim();
+    // flair#991: reject an unrecognized --visibility instead of writing it.
+    // `visibility` is a free-form String server-side and the read scope asks
+    // isPrivateVisibility() — an exact match on the literal "private" — so
+    // ANY other string, `--visibility prvate` included, persists a row the
+    // user believes is owner-only and that every agent on the instance can
+    // in fact read. A typo must never widen who can read a memory.
+    if (opts.visibility) {
+        const visibility = String(opts.visibility).trim();
+        if (visibility !== "private" && visibility !== "shared") {
+            console.error(`error: --visibility must be 'private' or 'shared' (got: ${visibility})`);
+            console.error("  omit it to use the durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private");
+            process.exit(1);
+        }
+        body.visibility = visibility;
+    }
     if (opts.derivedFrom) {
         body.derivedFrom = String(opts.derivedFrom).split(",").map((x) => x.trim()).filter(Boolean);
     }
@@ -13098,6 +13597,59 @@ function parseRelativeOrIso(input) {
     const multMs = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
     return new Date(Date.now() - n * (multMs[unit] ?? 0)).toISOString();
 }
+export function searchScoringFormula(scoring) {
+    return scoring === "composite"
+        ? "semantic × durability-weight × recency-decay × usage-boost"
+        : "cosine similarity only";
+}
+export function buildSearchExplain(record, scoring, now = Date.now()) {
+    const score = typeof record?._score === "number" ? record._score : undefined;
+    const rawScore = typeof record?._rawScore === "number" ? record._rawScore : undefined;
+    // composite mode: server sends both (_rawScore = pre-composite semantic).
+    // raw mode: server sends only _score, and that IS the raw score.
+    const raw = scoring === "composite" ? rawScore : score;
+    const composite = scoring === "composite" ? score : undefined;
+    let ageDays;
+    if (record?.createdAt) {
+        const created = new Date(String(record.createdAt)).getTime();
+        if (Number.isFinite(created))
+            ageDays = Math.max(0, Math.floor((now - created) / 86_400_000));
+    }
+    const explain = {
+        scoring,
+        formula: searchScoringFormula(scoring),
+        durability: record?.durability ?? "standard",
+        usageCount: typeof record?.usageCount === "number" ? record.usageCount : 0,
+    };
+    if (typeof raw === "number")
+        explain.raw = raw;
+    if (typeof composite === "number")
+        explain.composite = composite;
+    if (typeof ageDays === "number")
+        explain.ageDays = ageDays;
+    return explain;
+}
+// Human one-liner for a hit's breakdown. Scoring terms come from the shared
+// builder; the trailing tags/subject/supersedes are record context that json
+// mode already carries at top level, so they're appended here only.
+export function formatSearchExplain(explain, record) {
+    const parts = [];
+    if (typeof explain.raw === "number")
+        parts.push(`raw=${explain.raw.toFixed(3)}`);
+    if (typeof explain.composite === "number")
+        parts.push(`composite=${explain.composite.toFixed(3)}`);
+    parts.push(`durability=${explain.durability}`);
+    if (typeof explain.ageDays === "number")
+        parts.push(`age=${explain.ageDays}d`);
+    parts.push(`usage=${explain.usageCount}`);
+    if (Array.isArray(record?.tags) && record.tags.length > 0)
+        parts.push(`tags=[${record.tags.join(",")}]`);
+    if (record?.subject)
+        parts.push(`subject=${record.subject}`);
+    if (record?.supersedes)
+        parts.push(`supersedes=${record.supersedes}`);
+    return parts.join(" · ");
+}
 program
     .command("search <query>")
     .description("Search memories by meaning (shortcut for memory search) — filterable, with --explain ranking")
@@ -13120,7 +13672,7 @@ program
     .option("--durability <level>", "Filter to permanent|persistent|standard|ephemeral (client-side)")
     .option("--source <name>", "Filter by source/agentId (client-side)")
     // Output modes
-    .option("--explain", "Show score breakdown (composite, raw, durability, age, retrieval) per hit")
+    .option("--explain", "Show score breakdown (raw, composite, durability, age, usage) per hit — also added to --json output as _explain")
     .option("--json", "Output raw JSON array")
     .action(async (query, opts) => {
     try {
@@ -13180,8 +13732,17 @@ program
             results = results.filter((r) => allowed.has(r._source ?? r.agentId ?? ""));
         }
         const mode = render.resolveOutputMode(opts);
+        const scoringMode = payload.scoring === "composite" ? "composite" : "raw";
         if (mode === "json") {
-            console.log(render.asJSON(results));
+            // flair#992: --explain must be honoured here, not silently dropped.
+            // This branch is what every non-TTY caller lands in. The breakdown
+            // rides ALONG the json contract as an opt-in `_explain` key — present
+            // only when the caller typed --explain, so default output is unchanged
+            // — rather than switching output mode behind the caller's back.
+            const out = opts.explain
+                ? results.map((r) => ({ ...r, _explain: buildSearchExplain(r, scoringMode) }))
+                : results;
+            console.log(render.asJSON(out));
             return;
         }
         if (results.length === 0) {
@@ -13233,30 +13794,15 @@ program
             if (meta)
                 console.log(`  ${render.wrap(render.c.dim, "(")} ${meta} ${render.wrap(render.c.dim, ")")}`);
             if (opts.explain) {
-                const parts = [];
-                if (typeof r._rawScore === "number")
-                    parts.push(`raw=${r._rawScore.toFixed(3)}`);
-                if (typeof r._score === "number")
-                    parts.push(`composite=${r._score.toFixed(3)}`);
-                if (typeof r.retrievalCount === "number" && r.retrievalCount > 0)
-                    parts.push(`retrievals=${r.retrievalCount}`);
-                if (r.tags && Array.isArray(r.tags) && r.tags.length > 0)
-                    parts.push(`tags=[${r.tags.join(",")}]`);
-                if (r.subject)
-                    parts.push(`subject=${r.subject}`);
-                if (r.supersedes)
-                    parts.push(`supersedes=${r.supersedes}`);
-                if (parts.length > 0) {
-                    console.log(`    ${render.wrap(render.c.gray, "└─")} ${render.wrap(render.c.dim, parts.join(" · "))}`);
+                const line = formatSearchExplain(buildSearchExplain(r, scoringMode), r);
+                if (line) {
+                    console.log(`    ${render.wrap(render.c.gray, "└─")} ${render.wrap(render.c.dim, line)}`);
                 }
             }
             console.log();
         }
         if (opts.explain) {
-            const formula = payload.scoring === "composite"
-                ? "semantic × durability-weight × recency-decay × retrieval-boost"
-                : "cosine similarity only";
-            console.log(`${render.wrap(render.c.dim, "Scoring:")} ${render.wrap(render.c.bold, payload.scoring)}  ${render.wrap(render.c.dim, `(${formula})`)}`);
+            console.log(`${render.wrap(render.c.dim, "Scoring:")} ${render.wrap(render.c.bold, scoringMode)}  ${render.wrap(render.c.dim, `(${searchScoringFormula(scoringMode)})`)}`);
         }
     }
     catch (err) {
@@ -13404,7 +13950,7 @@ soul.command("set")
     .requiredOption("--agent <id>")
     .requiredOption("--key <key>")
     .requiredOption("--value <value>")
-    .option("--durability <d>", "permanent")
+    .option("--durability <d>", "permanent|persistent|standard|ephemeral (default permanent — soul entries are identity, not working memory)")
     .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
     // PUT /Soul/{agentId:key} (upsert by id), matching flair-client's soul.set().
@@ -15221,4 +15767,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, };