@tpsdev-ai/flair 0.31.1 → 0.33.0

package/dist/cli.js

@@ -269,7 +269,19 @@ function migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir = defa
     }
     catch { /* best effort */ }
     const legacyContent = readFileSync(resolved.plistPath, "utf-8");
-    const newContent = legacyContent.replace(`<key>Label</key><string>${LEGACY_LAUNCHD_LABEL}</string>`, `<key>Label</key><string>${newLabel}</string>`);
+    // Use a function replacer to avoid $-sensitivity in the replacement
+    // string (flair#919). String.prototype.replace interprets $&, $', $`
+    // etc. in the replacement even when the search value is a plain string.
+    const labelSearch = `<key>Label</key><string>${LEGACY_LAUNCHD_LABEL}</string>`;
+    const labelReplacement = `<key>Label</key><string>${newLabel}</string>`;
+    const newContent = legacyContent.replace(labelSearch, () => labelReplacement);
+    // Refuse to propagate a malformed plist: if the Label wasn't found,
+    // the plist is not what we expect and migration must not write it.
+    if (newContent === legacyContent) {
+        throw new Error(`Legacy plist at ${resolved.plistPath} does not contain the expected ` +
+            `Label key — it may be malformed or from an unknown Flair version. ` +
+            `Remove it manually and re-run 'flair init'.`);
+    }
     writeFileSync(newPlistPath, newContent);
     try {
         unlinkSync(resolved.plistPath);
@@ -277,6 +289,58 @@ function migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir = defa
     catch { /* best effort */ }
     return { migrated: true, label: newLabel, plistPath: newPlistPath };
 }
+/**
+ * Clean up a pre-flair#693 legacy launchd plist (ai.tpsdev.flair) during
+ * init, but ONLY when it belongs to the data dir being initialised.
+ *
+ * flair#966: the legacy plist is a single global label — init must not
+ * unload/delete it unless ROOTPATH proves it serves this data dir.
+ *
+ * `runLaunchctl` is injected so tests can record/mock without touching
+ * real launchd. The caller (init) passes a real execSync wrapper; tests
+ * pass a recording stub.
+ */
+function cleanupLegacyLaunchdPlist(dataDir, plistDir, runLaunchctl) {
+    const legacyPlistPath = launchdPlistPath(LEGACY_LAUNCHD_LABEL, plistDir);
+    if (!existsSync(legacyPlistPath))
+        return { action: "none" };
+    const legacyRootPath = readPlistRootPath(legacyPlistPath);
+    const legacyOwnedByUs = legacyRootPath !== null && resolve(legacyRootPath) === resolve(dataDir);
+    if (legacyOwnedByUs) {
+        let unloadFailed;
+        let deleteFailed;
+        try {
+            runLaunchctl(`launchctl unload "${legacyPlistPath}"`);
+        }
+        catch (err) {
+            unloadFailed = err?.message ?? String(err);
+            console.error(`Failed to unload legacy launchd service (${LEGACY_LAUNCHD_LABEL}): ` +
+                `${unloadFailed}. ` +
+                `The plist at ${legacyPlistPath} may still be loaded — ` +
+                `unload it manually with: launchctl unload "${legacyPlistPath}"`);
+        }
+        try {
+            unlinkSync(legacyPlistPath);
+            console.log(`Migrated off legacy launchd label (${LEGACY_LAUNCHD_LABEL}) ✓`);
+        }
+        catch (err) {
+            deleteFailed = err?.message ?? String(err);
+            console.error(`Failed to remove legacy launchd plist at ${legacyPlistPath}: ` +
+                `${deleteFailed}. Remove it manually.`);
+        }
+        return { action: "unloaded", unloadFailed, deleteFailed };
+    }
+    if (legacyRootPath !== null) {
+        console.log(`Skipped legacy launchd cleanup: the plist at ${legacyPlistPath} ` +
+            `belongs to data dir ${resolve(legacyRootPath)}, not ${resolve(dataDir)} — ` +
+            `that is a different Flair instance.`);
+        return { action: "skipped-foreign", foreignDataDir: resolve(legacyRootPath) };
+    }
+    console.log(`Skipped legacy launchd cleanup: could not determine which data dir ` +
+        `the plist at ${legacyPlistPath} serves. ` +
+        `If it is yours, remove it manually with: rm "${legacyPlistPath}"`);
+    return { action: "skipped-unknown" };
+}
 /**
  * Load + start `dataDir`'s launchd service, migrating off a pre-flair#693
  * legacy registration FIRST if one is found (migrateLegacyLaunchdLabel
@@ -290,6 +354,13 @@ function migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir = defa
  */
 function ensureLaunchdServiceLoaded(dataDir, runLaunchctl, launchAgentsDir = defaultLaunchAgentsDir()) {
     const migration = migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir);
+    // Unload first so a rewritten plist is re-read (flair#872).
+    // launchd caches the environment of an already-loaded job; load
+    // alone does not pick up changes to the plist on disk.
+    try {
+        runLaunchctl(`launchctl unload "${migration.plistPath}"`);
+    }
+    catch { /* not loaded, etc. — best effort */ }
     try {
         runLaunchctl(`launchctl load "${migration.plistPath}"`);
     }
@@ -2933,25 +3004,20 @@ program
                 const plistDir = defaultLaunchAgentsDir();
                 mkdirSync(plistDir, { recursive: true });
                 const plistPath = launchdPlistPath(label, plistDir);
-                // flair#693 migration: a pre-flair#693 install registered under
+                // flair#693 + flair#966: a pre-flair#693 install registered under
                 // the bare LEGACY_LAUNCHD_LABEL. init always writes fresh plist
                 // content below (it has the current ports/creds in hand), so
                 // migration here is just "clean up the old registration" —
                 // unload + remove it BEFORE writing the new one, so re-running
                 // init never leaves two services behind for this data dir.
-                const legacyPlistPath = launchdPlistPath(LEGACY_LAUNCHD_LABEL, plistDir);
-                if (existsSync(legacyPlistPath)) {
-                    try {
-                        const { execSync } = await import("node:child_process");
-                        execSync(`launchctl unload "${legacyPlistPath}"`, { stdio: "pipe" });
-                    }
-                    catch { /* best effort */ }
-                    try {
-                        unlinkSync(legacyPlistPath);
-                    }
-                    catch { /* best effort */ }
-                    console.log(`Migrated off legacy launchd label (${LEGACY_LAUNCHD_LABEL}) ✓`);
-                }
+                //
+                // flair#966: the legacy plist is NOT scoped to this data dir —
+                // it is a single global label. cleanupLegacyLaunchdPlist reads
+                // ROOTPATH to establish ownership before touching it.
+                cleanupLegacyLaunchdPlist(dataDir, plistDir, (cmd) => {
+                    const { execSync } = require("node:child_process");
+                    execSync(cmd, { stdio: "pipe" });
+                });
                 const opsSocket = join(dataDir, "operations-server");
                 // authorizeLocal: false (flair#654) — same posture as the initial spawn
                 // above; the launchd-managed process must not diverge from it.
@@ -9618,17 +9684,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.");
@@ -9741,20 +9828,28 @@ program
  * Never logs plist contents — the plist embeds HDB_ADMIN_PASSWORD. Only the
  * extracted ROOTPATH path ever reaches a message.
  */
-export function assertLaunchdServiceOwnedBy(dataDir, label, plistPath, action) {
-    let declared = null;
+/**
+ * Read the ROOTPATH declared in a launchd plist, or null if it cannot be
+ * determined (file missing, unreadable, or no ROOTPATH key).
+ *
+ * The plist stores this XML-escaped (buildLaunchdPlist), so the returned
+ * value is decoded through unescapeXml before being returned — a data dir
+ * containing `&` is on disk as `&amp;` and this returns the literal `&`.
+ *
+ * Never logs plist contents — the plist embeds HDB_ADMIN_PASSWORD.
+ */
+export function readPlistRootPath(plistPath) {
     try {
         const raw = readFileSync(plistPath, "utf-8");
         const m = raw.match(/<key>ROOTPATH<\/key>\s*<string>([^<]*)<\/string>/);
-        // The plist stores this XML-escaped (buildLaunchdPlist), so a data dir
-        // containing `&` is on disk as `&amp;`. Decode before comparing, or the
-        // path would never equal itself and this guard would refuse a legitimate
-        // stop/start on any instance whose path contains an escaped character.
-        declared = m ? unescapeXml(m[1]) : null;
+        return m ? unescapeXml(m[1]) : null;
     }
     catch {
-        return; // unreadable — no evidence, don't block
+        return null;
     }
+}
+export function assertLaunchdServiceOwnedBy(dataDir, label, plistPath, action) {
+    const declared = readPlistRootPath(plistPath);
     if (declared === null)
         return;
     if (resolve(declared) === resolve(dataDir))
@@ -9785,17 +9880,29 @@ 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.`);
 }
 /**
  * Stop the local Flair (Harper) process — launchd `stop` on darwin when a
@@ -9835,18 +9942,15 @@ async function stopFlairProcess(port, dataDir) {
             assertLaunchdServiceOwnedBy(dataDir, label, plistPath, "stop");
             try {
                 const { execSync } = await import("node:child_process");
-                // Ensure the service is loaded (init writes the plist but doesn't load it)
-                try {
-                    execSync(`launchctl load "${plistPath}"`, { stdio: "pipe" });
-                }
-                catch { }
-                // Capture the current PID *before* stopping so callers that
+                // Capture the current PID *before* unloading so callers that
                 // immediately restart can verify exit. Without this, waitForHealth
                 // can race against the still-shutting-down old process and return
-                // success before KeepAlive brings the new one up.
+                // success before the new one comes up.
                 const oldPid = readHarperPid(dataDir);
+                // unload stops the job AND prevents KeepAlive from respawning it.
+                // launchctl stop alone is insufficient for a KeepAlive job (flair#874).
                 try {
-                    execSync(`launchctl stop ${label}`, { stdio: "pipe" });
+                    execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
                 }
                 catch { }
                 if (oldPid)
@@ -10100,7 +10204,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
@@ -10127,51 +10235,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;
+                }
+                else {
+                    for (const pid of pids) {
+                        try {
+                            process.kill(pid, "SIGTERM");
+                        }
+                        catch { }
+                    }
+                    await new Promise(r => setTimeout(r, 2000));
+                    console.log("✅ Flair process stopped");
                 }
-                catch { }
             }
-            // Wait for process to release file handles (RocksDB)
-            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;
+            }
         }
     }
     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 (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");
         }
-        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);
+        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/");
@@ -10821,17 +10966,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))
@@ -10839,9 +10991,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;
@@ -12627,7 +12786,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)")
@@ -12648,8 +12807,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);
     }
@@ -13027,6 +13199,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")
@@ -13049,7 +13274,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 {
@@ -13109,8 +13334,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) {
@@ -13162,30 +13396,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) {
@@ -13333,7 +13552,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().
@@ -14068,6 +14287,19 @@ program
         console.error("Error: --admin-pass, --admin-pass-file, or FLAIR_ADMIN_PASS required for backup");
         process.exit(1);
     }
+    // flair#968: `flair backup > file.json` captures the progress report, not
+    // the archive (which goes to --output, defaulting to ~/.flair/backups/...).
+    // The result was exit 0 and a plausible-looking file of a few hundred bytes —
+    // a false success immediately before a destructive upgrade.
+    //
+    // When stdout is not a TTY, route progress output to stderr. The archive
+    // still goes to --output / the default path. This makes `flair backup >
+    // file.json` produce an EMPTY file — unmistakably not a valid archive —
+    // while leaving default-path callers (schedulers, cron) completely
+    // unaffected.
+    const log = process.stdout.isTTY
+        ? console.log.bind(console)
+        : console.error.bind(console);
     const auth = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
     async function adminGet(path) {
         const res = await fetch(`${baseUrl}${path}`, {
@@ -14080,11 +14312,11 @@ program
         }
         return res.json();
     }
-    console.log("Fetching agents...");
+    log("Fetching agents...");
     const allAgents = await adminGet("/Agent/");
     const filterIds = opts.agents ? opts.agents.split(",").map((s) => s.trim()) : null;
     const agents = filterIds ? allAgents.filter((a) => filterIds.includes(a.id)) : allAgents;
-    console.log(`Fetching memories for ${agents.length} agent(s)...`);
+    log(`Fetching memories for ${agents.length} agent(s)...`);
     const memories = [];
     for (const agent of agents) {
         try {
@@ -14096,7 +14328,7 @@ program
             console.warn(`  Warning: could not fetch memories for ${agent.id}: ${err.message}`);
         }
     }
-    console.log("Fetching souls...");
+    log("Fetching souls...");
     const souls = [];
     for (const agent of agents) {
         try {
@@ -14124,11 +14356,11 @@ program
     const tmp = outputPath + ".tmp";
     writeFileSync(tmp, JSON.stringify(backup, null, 2) + "\n", "utf-8");
     renameSync(tmp, outputPath);
-    console.log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Backup complete")}`);
-    console.log(render.kv("Agents", render.wrap(render.c.bold, String(agents.length))));
-    console.log(render.kv("Memories", render.wrap(render.c.bold, String(memories.length))));
-    console.log(render.kv("Souls", render.wrap(render.c.bold, String(souls.length))));
-    console.log(render.kv("Output", render.wrap(render.c.dim, outputPath)));
+    log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Backup complete")}`);
+    log(render.kv("Agents", render.wrap(render.c.bold, String(agents.length))));
+    log(render.kv("Memories", render.wrap(render.c.bold, String(memories.length))));
+    log(render.kv("Souls", render.wrap(render.c.bold, String(souls.length))));
+    log(render.kv("Output", render.wrap(render.c.dim, outputPath)));
 });
 // ─── flair restore ────────────────────────────────────────────────────────────
 program
@@ -15137,4 +15369,4 @@ 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, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, };
+LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, cleanupLegacyLaunchdPlist, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, };