freeharness 0.4.1 → 0.4.2

package/dist/adapters/memory/doctor.js

@@ -6,20 +6,36 @@
 //     carries the `.install-version` marker written by VendoredMemory and ships exactly
 //     one skill (mem-search); an upstream install ships many (cloud-sync, babysit, ...).
 //   - installed_plugins.json — the installPath Claude Code loads hooks/skills from.
-//   - the running worker — /api/health reports its version; GET / answers 200 with the
-//     React viewer on upstream and, on our build, 200 with the FreeHarness viewer page
-//     (marker "FreeHarness memory", FIXUP section 8) or 404 on a pre-viewer build.
-//   - the data dir (~/.claude-mem or CLAUDE_MEM_DATA_DIR): claude-mem.db + chroma, plus the
+//   - the running worker — /api/health reports its version and, on our build, the product
+//     marker "free-mem"; an unmarked answer is an older build of ours only when the free-mem
+//     PID file names its pid and port. GET / proves nothing: upstream also answers 404 there.
+//   - the data dir (resolveMemoryPaths in ./paths.ts): the database (a leftover chroma/
+//     directory is only sized and reported, never touched), plus the
 //     observer ledgers written by the ported 13.24 engine (observer-health.json,
 //     quota-cooldown.json) that `memory status` renders as rejections / cooldowns.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
-import { MARKETPLACE_OWNER, PLUGIN_KEY, PLUGIN_NAME, UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_NAME } from "./vendored.js";
+import { MARKETPLACE_OWNER, PLUGIN_KEY, PLUGIN_NAME, UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_KEY, UPSTREAM_PLUGIN_NAME, claudePluginPaths, isUpstreamRegistered, declaresPluginDeps, installPluginDeps, missingPluginBundles, missingPluginDeps, pluginVersion, probeBun, stagePluginCache, writeInstallMarker, } from "./vendored.js";
+import { FREE_DIR_NAME, LEGACY_DB_FILENAME, LEGACY_DIR_NAME, readMemorySettings, resolveMemoryPaths } from "./paths.js";
+import { pidFileLive } from "./migrate.js";
 import { resolveCanonicalDir, sourceRepoRoot } from "../../infra/paths.js";
-/** Marker in the FreeHarness viewer page served on GET / (plugin/ui/viewer.html). */
-export const VIEWER_MARKER = "FreeHarness memory";
+const OLD_PREFIX = "CLAUDE_MEM_";
+const NEW_PREFIX = "FREE_MEM_";
+function legacyName(key) {
+    return OLD_PREFIX + key.slice(NEW_PREFIX.length);
+}
+/** A FREE_MEM_ setting, else its CLAUDE_MEM_ twin: the engine reads an unrenamed file the same way. */
+function setting(values, key) {
+    return values[key] ?? values[legacyName(key)];
+}
+/** Like `setting`, but an empty value counts as unset, as the engine's envGet reads the environment. */
+function envSetting(env, key) {
+    return env[key] || env[legacyName(key)] || undefined;
+}
+/** The /api/health product marker of our worker; a test pins it to the engine's and the hooks' copies. */
+export const FREE_MEM_PRODUCT = "free-mem";
 /** Mirror of engine shared/observer-health.ts: warn only after this many consecutive failures. */
 export const OBSERVER_UNHEALTHY_FAILURE_THRESHOLD = 3;
 /** Mirror of engine shared/quota-cooldown.ts: how long requests are withheld after a quota refusal. */
@@ -178,25 +194,64 @@ export function observerLines(s, now = Date.now()) {
 }
 /** Highest schema_versions row our vendored SessionStore applies (13.24.0 port; the upstream v50 observed_model/observed_billing migration is telemetry-only and not ported). */
 export const OUR_SCHEMA_VERSION = 49;
+/** Versions at or above this belong to FreeHarness migrations, so they must not be compared with upstream's counter. */
+const FREEHARNESS_SCHEMA_BASE = 9000;
+/** Every FreeHarness migration the vendored SessionStore records; a store holding some but not all of them did not finish migrating. */
+const FREEHARNESS_SCHEMA_VERSIONS = [9001, 9002, 9003, 9004, 9005, 9006, 9007];
 /**
- * Read max(version) from schema_versions via the sqlite3 CLI (no node sqlite dep).
+ * Read the applied schema_versions via the sqlite3 CLI (no node sqlite dep), read-only.
  *
  * Returns:
- *   The version, or null when the db/sqlite3 is unavailable.
+ *   The versions, or null when the db/sqlite3 is unavailable.
  */
-function dbSchemaVersion(dbPath) {
+function dbSchemaVersions(dbPath) {
     if (!fs.existsSync(dbPath))
         return null;
-    const r = spawnSync("sqlite3", ["-readonly", dbPath, "SELECT MAX(version) FROM schema_versions;"], { encoding: "utf8" });
+    const r = spawnSync("sqlite3", ["-readonly", dbPath, "SELECT version FROM schema_versions;"], { encoding: "utf8" });
     if (r.status !== 0)
         return null;
-    const n = parseInt(r.stdout.trim(), 10);
-    return Number.isFinite(n) ? n : null;
+    const versions = r.stdout.split("\n").map((l) => parseInt(l.trim(), 10)).filter((n) => Number.isFinite(n));
+    return versions.length > 0 ? versions : null;
+}
+/**
+ * Build the schema status line. Upstream and FreeHarness versions are split at 9000 so a
+ * FreeHarness migration is never reported as a newer upstream engine. A store that records
+ * some FreeHarness versions but not all of them has not finished migrating (a migration
+ * rolled back, or the worker predates the update), so the line warns and names each missing
+ * version; a store with none has never been opened
+ * by a FreeHarness worker and keeps the upstream verdict.
+ *
+ * Returns:
+ *   The line, or null when the db/sqlite3 is unavailable.
+ */
+export function schemaVersionLine(dbPath, dbName) {
+    const versions = dbSchemaVersions(dbPath);
+    if (versions === null)
+        return null;
+    const upstream = versions.filter((v) => v < FREEHARNESS_SCHEMA_BASE);
+    const own = [...new Set(versions.filter((v) => v >= FREEHARNESS_SCHEMA_BASE))].sort((a, b) => a - b);
+    const schema = upstream.length > 0 ? Math.max(...upstream) : 0;
+    const label = `schema v${schema}${own.length > 0 ? ` + FreeHarness ${own.join(", ")}` : ""}`;
+    const newer = `schema v${schema} is NEWER than our engine (v${OUR_SCHEMA_VERSION})`;
+    const missing = own.length > 0 ? FREEHARNESS_SCHEMA_VERSIONS.filter((v) => !own.includes(v)) : [];
+    if (missing.length > 0) {
+        const upstreamNote = schema > OUR_SCHEMA_VERSION && schema !== 50 ? `; upstream ${newer}` : "";
+        return `WARN ${dbName} ${label}: FreeHarness migration ${missing.join(", ")} missing — a failed or partial migration, or a worker not restarted since the update; restart the worker so it retries, and read the worker log if this line stays${upstreamNote}`;
+    }
+    if (schema <= OUR_SCHEMA_VERSION)
+        return `OK   ${dbName} ${label} (our engine knows up to v${OUR_SCHEMA_VERSION})`;
+    if (schema === 50)
+        return `OK   ${dbName} ${label} (upstream 13.2x; v50 only adds nullable sdk_sessions columns our engine v${OUR_SCHEMA_VERSION} ignores)`;
+    return `WARN ${dbName} ${newer} — migrated by an upstream build; migrations are additive so it usually works, but keep the backup and watch the first worker start`;
 }
+/** Not yet migrated: the cost-tracker hook's `observerSink` tolerates the same error. */
+const MISSING_CONSOLIDATION_TABLE = /no such table: (?:main\.)?consolidation_(?:calls|jobs)\b/;
 /**
  * Reads observer spend (observation count and summed `discovery_tokens`) grouped by day
  * window and `generated_by_model`, through `sqlite3 -readonly` (same invocation shape as
- * `dbSchemaVersion`). The seven-day window includes today, matching the running total an
+ * `dbSchemaVersions`), plus each model's `consolidation_calls` tokens: consolidation
+ * observations carry `discovery_tokens` 0, and the cost-tracker hook's `observerSink` counts
+ * the same rows. The seven-day window includes today, matching the running total an
  * owner reads off `memory status` (not "the other six days").
  *
  * Args:
@@ -210,28 +265,220 @@ function dbSchemaVersion(dbPath) {
 export function observerSpend(dbPath, spawn = spawnSync) {
     if (!fs.existsSync(dbPath))
         return [];
+    // sqlite3 prints a statement's rows before preparing the next, so a missing table in the
+    // last statement keeps the observation rows.
     const query = [
         "SELECT 'today', generated_by_model, COUNT(*), COALESCE(SUM(discovery_tokens),0)",
         "FROM observations WHERE date(created_at) = date('now') GROUP BY generated_by_model",
         "UNION ALL",
         "SELECT 'seven_day', generated_by_model, COUNT(*), COALESCE(SUM(discovery_tokens),0)",
         "FROM observations WHERE created_at >= datetime('now', '-7 days') GROUP BY generated_by_model;",
+        "SELECT 'today', model, 0, COALESCE(SUM(tokens),0)",
+        "FROM consolidation_calls WHERE date(settled_at_epoch / 1000, 'unixepoch') = date('now') GROUP BY model",
+        "UNION ALL",
+        "SELECT 'seven_day', model, 0, COALESCE(SUM(tokens),0)",
+        "FROM consolidation_calls WHERE settled_at_epoch >= CAST(strftime('%s', 'now', '-7 days') AS INTEGER) * 1000 GROUP BY model;",
     ].join(" ");
     const r = spawn("sqlite3", ["-readonly", dbPath, query], { encoding: "utf8" });
     if (r.error)
         return { reason: r.error.message || "sqlite3 not found on PATH", missingBinary: true };
-    if (r.status !== 0)
+    if (r.status !== 0 && !MISSING_CONSOLIDATION_TABLE.test(r.stderr || "")) {
         return { reason: (r.stderr || "").trim().split("\n")[0] || `sqlite3 exited ${r.status}`, missingBinary: false };
-    const rows = [];
-    for (const line of r.stdout.split("\n")) {
+    }
+    const rows = new Map();
+    for (const line of (r.stdout || "").split("\n")) {
         if (!line.trim())
             continue;
-        const [window, model, observations, tokens] = line.split("|");
+        const [window, rawModel, observations, tokens] = line.split("|");
         if (window !== "today" && window !== "seven_day")
             continue;
-        rows.push({ window, model: model || "(unknown)", observations: parseInt(observations, 10) || 0, tokens: parseInt(tokens, 10) || 0 });
+        const model = rawModel || "(unknown)";
+        const row = rows.get(`${window}|${model}`) ?? { window, model, observations: 0, tokens: 0 };
+        row.observations += parseInt(observations, 10) || 0;
+        row.tokens += parseInt(tokens, 10) || 0;
+        rows.set(`${window}|${model}`, row);
+    }
+    return [...rows.values()];
+}
+/** The engine's spool file name; temp files, `bad/` and the counters do not match. */
+const SPOOL_FILE = /^\d{1,16}-[0-9a-f]{64}\.json$/;
+function spoolCounts(dataDir) {
+    const dir = path.join(dataDir, "spool");
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    let dropped = 0;
+    try {
+        const value = parseInt(fs.readFileSync(path.join(dir, ".dropped"), "utf8").trim(), 10);
+        if (Number.isFinite(value) && value >= 0)
+            dropped = value;
+    }
+    catch {
+        // No drops recorded yet.
+    }
+    return { queued: names.filter((n) => SPOOL_FILE.test(n)).length, dropped };
+}
+function readOnlyRows(dbPath, sql, spawn) {
+    if (!fs.existsSync(dbPath))
+        return null;
+    const r = spawn("sqlite3", ["-readonly", dbPath, sql], { encoding: "utf8" });
+    if (r.error || r.status !== 0)
+        return null;
+    return String(r.stdout || "").split("\n").filter((l) => l.trim()).map((l) => l.split("|"));
+}
+/** The lexical fused search streams, in the order explain lists them. */
+const LEXICAL_STREAMS = "phrase, terms, session, files, tag";
+/** The default FREE_MEM_EMBED_MAX_DISTANCE, measured on all-minilm only. */
+const DEFAULT_EMBED_MAX_DISTANCE = 1;
+const CALIBRATED_EMBED_MODEL = "all-minilm";
+const grouped = (n) => n.toLocaleString("en-US");
+/**
+ * The streams line with the vector state. The vector stream is listed among the fused
+ * streams only in the states where a query can still vote with it (ready, backfilling,
+ * degraded); off and unreachable fuse the lexical streams alone.
+ */
+function searchLine(e) {
+    const line = (vector, state) => `INFO search: fused (${LEXICAL_STREAMS}${vector ? ", vector" : ""}); vector ${state}`;
+    if (!e)
+        return line(false, "n/a (worker not answering)");
+    const floor = e.model === null ? "" : `, model ${e.model}, floor ${e.maxDistance.toFixed(2)}`;
+    switch (e.state) {
+        case "ready":
+            return line(true, `ready ${grouped(e.embedded)}/${grouped(e.total)}${floor}`);
+        case "backfilling":
+            return line(true, `backfilling ${grouped(e.embedded)}/${grouped(e.total)}${floor}`);
+        case "degraded":
+            return line(true, `degraded, ${grouped(e.failed)} failed of ${grouped(e.total)}${floor}`);
+        case "unreachable":
+            return line(false, `unreachable (${e.lastErrorClass ?? "unknown"})${e.model === null ? "" : `, model ${e.model}`}`);
+        default:
+            return line(false, `off (${e.reason ?? "unset"})`);
+    }
+}
+/** A refused base URL, a model on a floor measured for another model, and unused model lineages. */
+function embeddingsLines(e) {
+    if (!e)
+        return [];
+    const out = [];
+    if (e.reason === "refused") {
+        out.push("WARN memory embeddings: base URL refused (non-loopback, userinfo, the worker port or an uncovered proxy variable); vectors off");
+    }
+    if (e.model !== null && e.model !== CALIBRATED_EMBED_MODEL && e.maxDistance === DEFAULT_EMBED_MAX_DISTANCE) {
+        out.push(`WARN memory embeddings: model ${e.model} uses the default floor 1.00, which is calibrated for ${CALIBRATED_EMBED_MODEL}; set FREE_MEM_EMBED_MAX_DISTANCE from a sweep`);
+    }
+    for (const other of e.otherModels) {
+        out.push(`INFO memory embeddings: ${grouped(other.count)} vectors of model ${other.model} are kept and unused`);
+    }
+    return out;
+}
+/**
+ * Validates the /api/health `embeddings` field; anything malformed counts as absent. The answer
+ * may come from another program on the port, so its strings are filtered before they print.
+ */
+function parseEmbeddingsHealth(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const r = raw;
+    const states = ["off", "ready", "backfilling", "degraded", "unreachable"];
+    if (typeof r.state !== "string" || !states.includes(r.state) || (typeof r.model !== "string" && r.model !== null))
+        return undefined;
+    const num = (v, fallback) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : fallback);
+    const otherModels = Array.isArray(r.otherModels)
+        ? r.otherModels.flatMap((o) => {
+            const m = o;
+            return m && typeof m.model === "string" && typeof m.count === "number" ? [{ model: filterForeignText(m.model), count: m.count }] : [];
+        })
+        : [];
+    return {
+        state: r.state,
+        reason: r.reason === "unset" || r.reason === "refused" ? r.reason : null,
+        model: typeof r.model === "string" ? filterForeignText(r.model) : null,
+        maxDistance: num(r.maxDistance, DEFAULT_EMBED_MAX_DISTANCE),
+        embedded: num(r.embedded, 0),
+        failed: num(r.failed, 0),
+        total: num(r.total, 0),
+        lastErrorClass: typeof r.lastErrorClass === "string" ? filterForeignText(r.lastErrorClass) : null,
+        otherModels,
+    };
+}
+const MISSING_SIGNAL_TABLE = /no such table: (?:main\.)?(?:gc_runs|observation_feedback|observation_supersedes)\b/;
+/** "2h", "15m", "3d": the parked age on one status line. */
+function shortAge(ms) {
+    const minutes = Math.max(0, Math.round(ms / 60_000));
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.round(minutes / 60);
+    return hours < 48 ? `${hours}h` : `${Math.round(hours / 24)}d`;
+}
+/**
+ * The gc and feedback lines from the 9006 tables. A verdict counts only when it is the newest
+ * for its observation, as search reads it, so a corrected `wrong` stops counting as wrong.
+ */
+function signalLines(dbPath, spawn) {
+    if (!fs.existsSync(dbPath))
+        return ["INFO gc: n/a", "INFO feedback: n/a"];
+    const sql = [
+        "SELECT 'gc', outcome, COALESCE(finished_at_epoch, started_at_epoch), superseded FROM gc_runs ORDER BY id DESC LIMIT 1;",
+        "SELECT 'verdict', verdict, COUNT(*) FROM observation_feedback f",
+        "WHERE id = (SELECT MAX(id) FROM observation_feedback g WHERE g.observation_id = f.observation_id) GROUP BY verdict;",
+        "SELECT 'superseded', COUNT(*) FROM observation_supersedes;",
+    ].join(" ");
+    const r = spawn("sqlite3", ["-readonly", dbPath, sql], { encoding: "utf8" });
+    if (!r.error && r.status !== 0 && MISSING_SIGNAL_TABLE.test(String(r.stderr || ""))) {
+        return ["INFO gc: tables missing (schema 9006)", "INFO feedback: tables missing (schema 9006)"];
     }
-    return rows;
+    if (r.error || r.status !== 0)
+        return ["INFO gc: n/a", "INFO feedback: n/a"];
+    const rows = String(r.stdout || "").split("\n").filter((l) => l.trim()).map((l) => l.split("|"));
+    const gc = rows.find((row) => row[0] === "gc");
+    const at = gc ? parseInt(gc[2], 10) : NaN;
+    const gcLine = gc
+        ? `INFO gc: last run ${Number.isFinite(at) ? new Date(at).toISOString() : "?"} ${gc[1]}, superseded ${parseInt(gc[3], 10) || 0}`
+        : "INFO gc: no run yet";
+    const verdicts = (v) => parseInt(rows.find((row) => row[0] === "verdict" && row[1] === v)?.[2] ?? "0", 10) || 0;
+    const superseded = parseInt(rows.find((row) => row[0] === "superseded")?.[1] ?? "0", 10) || 0;
+    return [gcLine, `INFO feedback: ${verdicts("wrong")} wrong, ${verdicts("stale")} stale, ${superseded} superseded`];
+}
+function parkedLine(worker) {
+    if (!worker.reachable)
+        return "INFO parked: worker not answering";
+    if (!worker.parked)
+        return "INFO parked: n/a (the worker reports no parked count)";
+    const { count, oldestAgeMs } = worker.parked;
+    const batches = `${count} batch${count === 1 ? "" : "es"}`;
+    return count > 0 && oldestAgeMs !== null ? `INFO parked: ${batches}, oldest ${shortAge(oldestAgeMs)}` : `INFO parked: ${batches}`;
+}
+/**
+ * The capture pipeline and retrieval health as INFO lines: spool backlog and drops,
+ * consolidation jobs by status, the rules tier's share of the last 7 days' observations, the
+ * search streams, the last gc run, the feedback counts and the parked batches the worker
+ * reports. Anything unreadable prints `n/a` rather than failing the report.
+ *
+ * Args:
+ *   worker: The /api/health probe; omitted, the worker counts as not answering.
+ */
+export function pipelineLines(dataDir, dbPath, spawn = spawnSync, worker = { reachable: false }) {
+    const spool = spoolCounts(dataDir);
+    const lines = [spool ? `INFO spool: ${spool.queued} queued, ${spool.dropped} dropped` : "INFO spool: n/a"];
+    const jobs = readOnlyRows(dbPath, "SELECT status, COUNT(*) FROM consolidation_jobs GROUP BY status;", spawn);
+    if (jobs === null) {
+        lines.push("INFO consolidation: n/a");
+    }
+    else {
+        const count = (status) => parseInt(jobs.find((row) => row[0] === status)?.[1] ?? "0", 10) || 0;
+        lines.push(`INFO consolidation: done ${count("done")}, failed ${count("failed")}, pending ${count("pending")}`);
+    }
+    const share = readOnlyRows(dbPath, "SELECT COUNT(*), COALESCE(SUM(generated_by_model = 'rules'),0) FROM observations WHERE created_at >= datetime('now', '-7 days');", spawn);
+    const total = share ? parseInt(share[0]?.[0] ?? "0", 10) || 0 : 0;
+    const rules = share ? parseInt(share[0]?.[1] ?? "0", 10) || 0 : 0;
+    lines.push(total > 0 ? `INFO rules share (7d): ${Math.round((rules * 100) / total)}%` : "INFO rules share (7d): n/a");
+    const embeddings = worker.reachable ? worker.embeddings : undefined;
+    lines.push(searchLine(embeddings), ...embeddingsLines(embeddings), ...signalLines(dbPath, spawn), parkedLine(worker));
+    return lines;
 }
 /**
  * Model ids that name metered Claude spend: the `claude-*` families, a bare tier alias
@@ -341,7 +588,7 @@ function readTail(filePath, maxBytes) {
  *
  * Returns:
  *   The day's batch/fallback counts and whether the read was truncated; null when the log file
- *   does not exist yet (a fresh `CLAUDE_MEM_PROVIDER=claude` machine has never written one);
+ *   does not exist yet (a fresh `FREE_MEM_PROVIDER=claude` machine has never written one);
  *   the reason when the file is there but could not be read, which is a different state from
  *   an absent log and gets its own printed line.
  */
@@ -356,7 +603,7 @@ export function readLocalProviderLog(logPath, dayStartMs, nowMs, maxBytes = DEFA
             return null;
         return { reason: err && err.message ? err.message : String(e) };
     }
-    const summary = { batches: 0, local: 0, fallbacks: {}, skippedLines: 0, truncated: tail.truncated };
+    const summary = { batches: 0, local: 0, fallbacks: {}, skippedLines: 0, truncated: tail.truncated, degraded: {}, pausedWindows: {} };
     for (const rawLine of tail.text.split("\n")) {
         const line = rawLine.trim();
         if (!line)
@@ -380,10 +627,20 @@ export function readLocalProviderLog(logPath, dayStartMs, nowMs, maxBytes = DEFA
             summary.skippedLines++;
             continue;
         }
-        if (attempted !== "local")
-            continue; // a claude-attempted line: well-formed, not counted here
         if (tsMs < dayStartMs || tsMs > nowMs)
             continue; // outside the day: well-formed, not today
+        // A degraded batch is tallied by outcome, not by which provider was attempted first: a
+        // paused run can hand a batch to either provider and still owe it a terminal line.
+        const outcome = e.outcome;
+        const isTerminal = outcome === "stored" || outcome === "skipped" || outcome === "dropped";
+        if (e.degraded === true && isTerminal) {
+            const tier = typeof e.tier === "string" && e.tier.length > 0 ? e.tier : "unknown";
+            summary.degraded[tier] = (summary.degraded[tier] ?? 0) + 1;
+            const window = typeof e.paused_window === "string" && e.paused_window.length > 0 ? e.paused_window : "unknown";
+            summary.pausedWindows[window] = (summary.pausedWindows[window] ?? 0) + 1;
+        }
+        if (attempted !== "local")
+            continue; // a claude-attempted line: well-formed, not counted here
         summary.batches++;
         if (e.answered === "local") {
             summary.local++;
@@ -451,10 +708,12 @@ export function observerDuplicateRate(dbPath, spawn = spawnSync) {
 }
 /**
  * Renders the local-provider log summary and near-duplicate rate as printable INFO lines: the
- * batch/fallback line, then the near-duplicate-rate line (omitted when the rate could not be
- * read). Nothing at all when `summary` is null (no `local-provider.jsonl` yet); a single WARN
- * naming the reason when the log is present but unreadable, so a permission or I/O failure
- * never reads like a machine that has not run the local provider.
+ * batch/fallback line, the degraded-day line (present only when today has at least one
+ * `degraded: true` batch, naming the tier breakdown and the most frequent `paused_window`),
+ * then the near-duplicate-rate line (omitted when the rate could not be read). Nothing at all
+ * when `summary` is null (no `local-provider.jsonl` yet); a single WARN naming the reason when
+ * the log is present but unreadable, so a permission or I/O failure never reads like a machine
+ * that has not run the local provider.
  *
  * Args:
  *   summary: `readLocalProviderLog`'s return value.
@@ -476,6 +735,22 @@ export function localProviderLines(summary, duplicates) {
     const out = [
         `INFO local observer today: ${summary.batches} batches, ${summary.local} local, ${fallbackTotal} fallback${fallbackTotal === 1 ? "" : "s"}${kindText ? ` (${kindText})` : ""}${summary.truncated ? " (log truncated)" : ""}`,
     ];
+    const degradedTotal = Object.values(summary.degraded).reduce((sum, n) => sum + n, 0);
+    if (degradedTotal > 0) {
+        const tierText = Object.keys(summary.degraded)
+            .sort()
+            .map((tier) => `${tier} ${summary.degraded[tier]}`)
+            .join(", ");
+        let window = "unknown";
+        let windowCount = -1;
+        for (const w of Object.keys(summary.pausedWindows).sort()) {
+            if (summary.pausedWindows[w] > windowCount) {
+                window = w;
+                windowCount = summary.pausedWindows[w];
+            }
+        }
+        out.push(`INFO observer degraded today: ${degradedTotal} batches (${tierText}) while claude paused on ${window}`);
+    }
     if (!("reason" in duplicates)) {
         const share = (d) => {
             const pct = d.observations > 0 ? ((d.duplicates / d.observations) * 100).toFixed(1) : "0.0";
@@ -491,7 +766,7 @@ export function isHaikuAlias(model) {
 }
 /**
  * Defensive fallback for `engineDefaultObserverModels` when the vendored engine tree is not a
- * sibling on disk (an npx-bridge install with no vendored source next to it). Mirrors
+ * sibling on disk (a tree-absent install, such as the npm tarball). Mirrors
  * SettingsDefaultsManager.ts's current defaults; the parser above is the source of truth when
  * the tree is present, so a future default change there needs no edit here to take effect on a
  * checkout — this fallback only covers the tree-absent case.
@@ -547,9 +822,10 @@ export function effectiveObserverModels(settingsPath) {
     const defaults = engineDefaultObserverModels();
     const file = readFlatSettings(settingsPath);
     const str = (v, fallback) => (typeof v === "string" && v.length > 0 ? v : fallback);
-    const base = str(file.CLAUDE_MEM_MODEL, defaults.base);
-    const simple = str(file.CLAUDE_MEM_TIER_SIMPLE_MODEL, defaults.simple);
-    const rawSummary = typeof file.CLAUDE_MEM_TIER_SUMMARY_MODEL === "string" ? file.CLAUDE_MEM_TIER_SUMMARY_MODEL : defaults.summary;
+    const base = str(setting(file, "FREE_MEM_MODEL"), defaults.base);
+    const simple = str(setting(file, "FREE_MEM_TIER_SIMPLE_MODEL"), defaults.simple);
+    const summaryValue = setting(file, "FREE_MEM_TIER_SUMMARY_MODEL");
+    const rawSummary = typeof summaryValue === "string" ? summaryValue : defaults.summary;
     const summary = rawSummary.length > 0 ? rawSummary : base;
     return { base, simple, summary };
 }
@@ -557,9 +833,9 @@ export function effectiveObserverModels(settingsPath) {
 const ENGINE_LOCAL_BASE_URL_DEFAULT = "http://127.0.0.1:8080/v1";
 const ENGINE_LOCAL_MODEL_DEFAULT = "local-model";
 /**
- * Effective observer provider: `CLAUDE_MEM_PROVIDER` from settings.json (default `claude`; any
+ * Effective observer provider: `FREE_MEM_PROVIDER` from settings.json (default `claude`; any
  * value other than the literal `local` is treated as `claude`, mirroring the engine's own
- * `SettingsDefaultsManager` fallback), and when local, the configured `CLAUDE_MEM_LOCAL_MODEL`
+ * `SettingsDefaultsManager` fallback), and when local, the configured `FREE_MEM_LOCAL_MODEL`
  * or the engine's `local-model` default.
  *
  * Args:
@@ -570,34 +846,36 @@ const ENGINE_LOCAL_MODEL_DEFAULT = "local-model";
  */
 export function effectiveObserverProvider(settingsPath) {
     const values = readFlatSettings(settingsPath);
-    if (values.CLAUDE_MEM_PROVIDER !== "local")
+    if (setting(values, "FREE_MEM_PROVIDER") !== "local")
         return { provider: "claude", model: null };
-    const raw = values.CLAUDE_MEM_LOCAL_MODEL;
+    const raw = setting(values, "FREE_MEM_LOCAL_MODEL");
     return { provider: "local", model: typeof raw === "string" && raw.length > 0 ? raw : ENGINE_LOCAL_MODEL_DEFAULT };
 }
 /**
- * The FreeHarness-recommended observer settings: a haiku base and simple tier (the daily-spend
- * gate), a sonnet summary tier (session summaries read by every future session, worth the
- * larger model), the upstream skip list extended with the tools whose decisions matter for
- * recall (Read, Glob, Grep and the multi-agent tools), and a concurrency cap of 2. Shared by
- * `memory status`'s WARN check and the `memory settings` command.
+ * The FreeHarness-recommended observer settings: Haiku on every tier, because the summary tier
+ * alone spent 25.4M Sonnet tokens in a week, and the claude provider, because a local provider
+ * running beside it doubled the observer work. The skip list extends the upstream one with
+ * the read-only and multi-agent tools, which carry no decision worth recording, and
+ * concurrency is capped at 2. Shared by `memory status`'s WARN checks and the `memory
+ * settings` command.
  */
 export const RECOMMENDED_OBSERVER_SETTINGS = {
-    CLAUDE_MEM_MODEL: "haiku",
-    CLAUDE_MEM_TIER_SIMPLE_MODEL: "haiku",
-    CLAUDE_MEM_TIER_SUMMARY_MODEL: "sonnet",
-    CLAUDE_MEM_SKIP_TOOLS: "ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion,Read,Glob,Grep,ListAgents,SendMessage,Monitor,TaskOutput,ToolSearch,TaskStop",
-    CLAUDE_MEM_MAX_CONCURRENT_AGENTS: "2",
+    FREE_MEM_MODEL: "haiku",
+    FREE_MEM_TIER_SIMPLE_MODEL: "haiku",
+    FREE_MEM_TIER_SUMMARY_MODEL: "haiku",
+    FREE_MEM_PROVIDER: "claude",
+    FREE_MEM_SKIP_TOOLS: "ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion,Read,Glob,Grep,ListAgents,SendMessage,Monitor,TaskOutput,ToolSearch,TaskStop",
+    FREE_MEM_MAX_CONCURRENT_AGENTS: "2",
 };
 /** `memory settings --local`'s fixed defaults for the two tuning keys. */
 const LOCAL_OBSERVER_SETTINGS_DEFAULTS = {
-    CLAUDE_MEM_LOCAL_MAX_PROMPT_TOKENS: "4000",
-    CLAUDE_MEM_LOCAL_TIMEOUT_MS: "90000",
+    FREE_MEM_LOCAL_MAX_PROMPT_TOKENS: "4000",
+    FREE_MEM_LOCAL_TIMEOUT_MS: "90000",
 };
 /** The read-only tools the local provider itself observes once it is on. */
 const LOCAL_PROVIDER_SERVED_TOOLS = ["Read", "Glob", "Grep"];
 /**
- * Derives `memory settings --local`'s `CLAUDE_MEM_SKIP_TOOLS` value from the recommended
+ * Derives `memory settings --local`'s `FREE_MEM_SKIP_TOOLS` value from the recommended
  * default with `Read`, `Glob` and `Grep` removed, order kept: those three cost subscription
  * tokens for little signal at ingest, which is why the recommended default skips them, but the
  * local provider observes them at zero subscription cost, so the skip list follows the provider.
@@ -608,26 +886,26 @@ const LOCAL_PROVIDER_SERVED_TOOLS = ["Read", "Glob", "Grep"];
  *   The recommended default's tool list minus the three served tools, comma-joined.
  */
 function localProviderSkipTools() {
-    return RECOMMENDED_OBSERVER_SETTINGS.CLAUDE_MEM_SKIP_TOOLS.split(",")
+    return RECOMMENDED_OBSERVER_SETTINGS.FREE_MEM_SKIP_TOOLS.split(",")
         .filter((tool) => !LOCAL_PROVIDER_SERVED_TOOLS.includes(tool))
         .join(",");
 }
 /**
  * `memory settings --no-local`: the two keys that return the observer to the Claude provider —
- * `CLAUDE_MEM_PROVIDER` and `CLAUDE_MEM_SKIP_TOOLS` restored to the recommended default, so the
+ * `FREE_MEM_PROVIDER` and `FREE_MEM_SKIP_TOOLS` restored to the recommended default, so the
  * skip list follows the provider back.
  */
 export const NO_LOCAL_OBSERVER_SETTINGS = {
-    CLAUDE_MEM_PROVIDER: "claude",
-    CLAUDE_MEM_SKIP_TOOLS: RECOMMENDED_OBSERVER_SETTINGS.CLAUDE_MEM_SKIP_TOOLS,
+    FREE_MEM_PROVIDER: "claude",
+    FREE_MEM_SKIP_TOOLS: RECOMMENDED_OBSERVER_SETTINGS.FREE_MEM_SKIP_TOOLS,
 };
 /**
- * Builds the six `CLAUDE_MEM_LOCAL_*` / `CLAUDE_MEM_PROVIDER` / `CLAUDE_MEM_SKIP_TOOLS` keys for
+ * Builds the six `FREE_MEM_LOCAL_*` / `FREE_MEM_PROVIDER` / `FREE_MEM_SKIP_TOOLS` keys for
  * `memory settings --local`.
  *
  * Args:
- *   baseUrl: Candidate `CLAUDE_MEM_LOCAL_BASE_URL` value.
- *   model: Candidate `CLAUDE_MEM_LOCAL_MODEL` value.
+ *   baseUrl: Candidate `FREE_MEM_LOCAL_BASE_URL` value.
+ *   model: Candidate `FREE_MEM_LOCAL_MODEL` value.
  *
  * Returns:
  *   The six local-provider keys.
@@ -651,16 +929,16 @@ function localObserverSettings(baseUrl, model) {
         throw new Error(`FAIL invalid --local model id: ${model}`);
     }
     return {
-        CLAUDE_MEM_PROVIDER: "local",
-        CLAUDE_MEM_LOCAL_BASE_URL: baseUrl,
-        CLAUDE_MEM_LOCAL_MODEL: model,
+        FREE_MEM_PROVIDER: "local",
+        FREE_MEM_LOCAL_BASE_URL: baseUrl,
+        FREE_MEM_LOCAL_MODEL: model,
         ...LOCAL_OBSERVER_SETTINGS_DEFAULTS,
-        CLAUDE_MEM_SKIP_TOOLS: localProviderSkipTools(),
+        FREE_MEM_SKIP_TOOLS: localProviderSkipTools(),
     };
 }
 /**
- * Resolves the key set `memory settings` previews or writes: the local set (`CLAUDE_MEM_PROVIDER`
- * plus four `CLAUDE_MEM_LOCAL_*` keys plus the narrowed `CLAUDE_MEM_SKIP_TOOLS`), the two no-local
+ * Resolves the key set `memory settings` previews or writes: the local set (`FREE_MEM_PROVIDER`
+ * plus four `FREE_MEM_LOCAL_*` keys plus the narrowed `FREE_MEM_SKIP_TOOLS`), the two no-local
  * keys, or the five recommended keys when neither `--local` nor `--no-local` is given.
  *
  * Args:
@@ -685,8 +963,8 @@ function resolveObserverKeySet(opts) {
 /**
  * Previews `memory settings`: the selected key set against the current file, same or
  * would-change, writing nothing. Plain (no options): the five recommended keys. `--local`:
- * `CLAUDE_MEM_PROVIDER` plus the four `CLAUDE_MEM_LOCAL_*` keys plus the narrowed
- * `CLAUDE_MEM_SKIP_TOOLS`. `--no-local`: `CLAUDE_MEM_PROVIDER` and `CLAUDE_MEM_SKIP_TOOLS`
+ * `FREE_MEM_PROVIDER` plus the four `FREE_MEM_LOCAL_*` keys plus the narrowed
+ * `FREE_MEM_SKIP_TOOLS`. `--no-local`: `FREE_MEM_PROVIDER` and `FREE_MEM_SKIP_TOOLS`
  * restored to the recommended default.
  *
  * Args:
@@ -713,7 +991,7 @@ export function previewObserverSettings(settingsPath, opts) {
         }
     }
     const rows = Object.entries(keySet).map(([key, recommended]) => {
-        const raw = values[key];
+        const raw = setting(values, key);
         const current = raw === undefined ? undefined : typeof raw === "string" ? raw : JSON.stringify(raw);
         return { key, current, recommended, changed: current !== recommended };
     });
@@ -721,7 +999,8 @@ export function previewObserverSettings(settingsPath, opts) {
 }
 /**
  * Applies `memory settings`: adds or updates the selected key set (see `previewObserverSettings`
- * for which set), preserving every other key, after backing up an existing file first. Refuses
+ * for which set) and drops each written key's `CLAUDE_MEM_` twin, preserving every other key,
+ * after backing up an existing file first. Refuses
  * (throws) without writing anything when `opts` fails validation or the existing file is not
  * valid JSON.
  *
@@ -758,6 +1037,7 @@ export function applyObserverSettings(settingsPath, opts) {
     }
     for (const [key, value] of Object.entries(keySet)) {
         values[key] = value;
+        delete values[legacyName(key)];
     }
     fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
     fs.writeFileSync(settingsPath, JSON.stringify(values, null, 2) + "\n");
@@ -811,7 +1091,7 @@ async function getWithSignal(url, signal, timeoutMs) {
     }
 }
 /**
- * Splits a `CLAUDE_MEM_LOCAL_BASE_URL` into its health root (no `/v1`) and models base (with
+ * Splits a `FREE_MEM_LOCAL_BASE_URL` into its health root (no `/v1`) and models base (with
  * `/v1`), accepting the configured value with or without the `/v1` suffix.
  *
  * Args:
@@ -832,8 +1112,8 @@ function providerUrls(baseUrl) {
  * Down is a one-line reason, never a throw.
  *
  * Args:
- *   baseUrl: `CLAUDE_MEM_LOCAL_BASE_URL`.
- *   model: `CLAUDE_MEM_LOCAL_MODEL`.
+ *   baseUrl: `FREE_MEM_LOCAL_BASE_URL`.
+ *   model: `FREE_MEM_LOCAL_MODEL`.
  *   timeoutMs: The whole probe's deadline (both requests together).
  *
  * Returns:
@@ -864,7 +1144,7 @@ export async function probeMemoryProvider(baseUrl, model, timeoutMs = 3000) {
 }
 /**
  * The `memory provider` doctor line: only when the data dir's settings.json sets
- * `CLAUDE_MEM_PROVIDER=local`, a probe of the configured base URL and model, OK or WARN with
+ * `FREE_MEM_PROVIDER=local`, a probe of the configured base URL and model, OK or WARN with
  * the reason; absent or `claude` prints nothing.
  *
  * Args:
@@ -876,16 +1156,16 @@ export async function probeMemoryProvider(baseUrl, model, timeoutMs = 3000) {
  */
 export async function memoryProviderLines(settingsPath, probe = probeMemoryProvider) {
     const values = readFlatSettings(settingsPath);
-    if (values.CLAUDE_MEM_PROVIDER !== "local")
+    if (setting(values, "FREE_MEM_PROVIDER") !== "local")
         return [];
     // The worker applies these same defaults for an absent key, so probing "" would report a
     // URL-parse failure for a server the observer is in fact reaching.
-    const baseUrl = typeof values.CLAUDE_MEM_LOCAL_BASE_URL === "string" && values.CLAUDE_MEM_LOCAL_BASE_URL.trim() !== ""
-        ? values.CLAUDE_MEM_LOCAL_BASE_URL
-        : ENGINE_LOCAL_BASE_URL_DEFAULT;
-    const model = typeof values.CLAUDE_MEM_LOCAL_MODEL === "string" && values.CLAUDE_MEM_LOCAL_MODEL.trim() !== ""
-        ? values.CLAUDE_MEM_LOCAL_MODEL
-        : ENGINE_LOCAL_MODEL_DEFAULT;
+    const configured = (key, fallback) => {
+        const v = setting(values, key);
+        return typeof v === "string" && v.trim() !== "" ? v : fallback;
+    };
+    const baseUrl = configured("FREE_MEM_LOCAL_BASE_URL", ENGINE_LOCAL_BASE_URL_DEFAULT);
+    const model = configured("FREE_MEM_LOCAL_MODEL", ENGINE_LOCAL_MODEL_DEFAULT);
     const r = await probe(baseUrl, model);
     return [`${r.ok ? "OK  " : "WARN"} memory provider: ${baseUrl} ${model} ${r.ok ? "OK" : r.reason}`];
 }
@@ -893,30 +1173,75 @@ export async function memoryProviderLines(settingsPath, probe = probeMemoryProvi
 export function configDir() {
     return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
 }
-/** Mirror engine shared/paths.ts resolveDataDir (env, then settings.json, then default). */
+/** The engine's data directory and database for this process. */
+export function memoryPaths() {
+    return resolveMemoryPaths(process.env, os.homedir());
+}
 export function dataDir() {
-    const expand = (p) => (p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
-    if (process.env.CLAUDE_MEM_DATA_DIR)
-        return expand(process.env.CLAUDE_MEM_DATA_DIR);
-    const def = path.join(os.homedir(), ".claude-mem");
+    return memoryPaths().dataDir;
+}
+/**
+ * One WARN per `CLAUDE_MEM_*` variable in `env`, naming its `FREE_MEM_*` replacement, and one
+ * WARN for all `CLAUDE_MEM_*` keys in the active settings file: a seeded legacy file holds dozens,
+ * and a line per key would bury the rest of the report.
+ */
+export function deprecatedNameLines(env, settingsPath) {
+    const lines = Object.keys(env)
+        .filter((k) => k.startsWith(OLD_PREFIX) && env[k] !== undefined)
+        .sort()
+        .map((k) => `WARN deprecated environment variable ${k} is set; use FREE_MEM_${k.slice(OLD_PREFIX.length)}`);
+    const keys = Object.keys(readMemorySettings(settingsPath) ?? {}).filter((k) => k.startsWith(OLD_PREFIX)).sort();
+    if (keys.length > 0) {
+        lines.push(`WARN deprecated settings keys (${keys.length}) in ${settingsPath}: ${keys.join(", ")}; copying the settings to the free-mem directory renames them to FREE_MEM_*`);
+    }
+    return lines;
+}
+/**
+ * A WARN when the legacy database (or its WAL) changed after the migration marker's `at`:
+ * a build still on the old name keeps writing memories the new directory never sees.
+ */
+export function legacyWriteLines(home) {
+    const freeDir = path.join(home, FREE_DIR_NAME);
+    let marker;
     try {
-        const raw = JSON.parse(fs.readFileSync(path.join(def, "settings.json"), "utf8"));
-        const s = raw.env ?? raw;
-        if (typeof s.CLAUDE_MEM_DATA_DIR === "string")
-            return expand(s.CLAUDE_MEM_DATA_DIR);
+        marker = JSON.parse(fs.readFileSync(path.join(freeDir, ".migrated-from.json"), "utf8"));
     }
     catch {
-        /* default */
+        return [];
     }
-    return def;
+    const at = typeof marker.at === "string" ? Date.parse(marker.at) : NaN;
+    if (Number.isNaN(at))
+        return [];
+    const source = typeof marker.source === "string" && marker.source ? marker.source : path.join(home, LEGACY_DIR_NAME);
+    const db = path.join(source, LEGACY_DB_FILENAME);
+    let changed = 0;
+    for (const file of [db, `${db}-wal`]) {
+        try {
+            changed = Math.max(changed, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            /* absent */
+        }
+    }
+    if (changed <= at)
+        return [];
+    return [`WARN legacy database ${db} changed at ${new Date(changed).toISOString()}, after the migration at ${new Date(at).toISOString()}; a build still on the old name may be writing there, and those memories are not in ${freeDir}`];
 }
-/** Mirror engine SettingsDefaultsManager: CLAUDE_MEM_WORKER_PORT or 37700 + uid % 100. */
-function workerPort(dir) {
+/** Leading decimal integer, as the engine's parseInt reads it, when in 1..65535. */
+function validPort(value) {
+    const p = parseInt(String(value ?? ""), 10);
+    return p >= 1 && p <= 65535 ? p : null;
+}
+/** Engine worker port: env, then settings.json, then 37700 + uid % 100. */
+export function workerPort(dir) {
+    const env = validPort(envSetting(process.env, "FREE_MEM_WORKER_PORT"));
+    if (env !== null)
+        return env;
     try {
         const raw = JSON.parse(fs.readFileSync(path.join(dir, "settings.json"), "utf8"));
         const s = raw.env ?? raw;
-        const p = parseInt(String(s.CLAUDE_MEM_WORKER_PORT ?? ""), 10);
-        if (Number.isFinite(p) && p > 0)
+        const p = validPort(setting(s, "FREE_MEM_WORKER_PORT"));
+        if (p !== null)
             return p;
     }
     catch {
@@ -924,37 +1249,111 @@ function workerPort(dir) {
     }
     return 37700 + ((process.getuid?.() ?? 77) % 100);
 }
-async function probeWorker(port) {
-    const base = `http://127.0.0.1:${port}`;
-    const get = async (p) => {
-        try {
-            return await fetch(base + p, { signal: AbortSignal.timeout(1500) });
-        }
-        catch {
-            return null;
-        }
+function readJsonOr(file, fallback) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return fallback;
+    }
+}
+/** One WARN while the upstream plugin is still registered: both workers bind the same port. */
+export function upstreamLines(cfg, port) {
+    const installed = readJsonOr(path.join(cfg, "plugins", "installed_plugins.json"), {});
+    const settings = readJsonOr(path.join(cfg, "settings.json"), {});
+    if (!isUpstreamRegistered(installed, settings))
+        return [];
+    return [`WARN ${UPSTREAM_PLUGIN_KEY} is still registered; it shares worker port ${port} with ${PLUGIN_NAME}; disable it with \`claude plugin disable ${UPSTREAM_PLUGIN_KEY}\``];
+}
+const FOREIGN_TEXT_MAX = 200;
+const ANSI_SEQUENCE = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+// Copy of the engine's filterForeignText (the CLI may not import engine source). Built from code
+// points so this source holds no raw line separator or bidi control; under the u flag the
+// surrogate class matches only an unpaired half.
+const UNPRINTABLE_RANGES = [
+    [0x00, 0x1f], [0x7f, 0x9f], [0x200e, 0x200f], [0x2028, 0x2029], [0x202a, 0x202e], [0x2066, 0x2069],
+];
+const hex = (cp) => "\\u" + cp.toString(16).padStart(4, "0");
+const UNPRINTABLE = new RegExp("[" + UNPRINTABLE_RANGES.map(([from, to]) => hex(from) + "-" + hex(to)).join("") + "]|[" + hex(0xd800) + "-" + hex(0xdfff) + "]", "gu");
+/** A foreign worker writes these strings, and doctor prints them to the user's terminal. */
+function filterForeignText(value) {
+    if (typeof value !== "string")
+        return "";
+    const clean = value.replace(ANSI_SEQUENCE, "").replace(UNPRINTABLE, "");
+    return Array.from(clean).slice(0, FOREIGN_TEXT_MAX).join("");
+}
+function trustedPid(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+/** The pid and port in the data dir's worker.pid, the file the engine writes and stopWorker reads. */
+function ownedWorker(dir) {
+    const raw = readJsonOr(path.join(dir, "worker.pid"), null);
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const { pid, port } = raw;
+    const owned = trustedPid(pid);
+    return owned !== undefined && typeof port === "number" ? { pid: owned, port } : null;
+}
+/**
+ * The engine's classifyWorker: an unmarked answer is an older build of ours only when the
+ * free-mem PID file names both its pid and the probed port, since a foreign worker can report
+ * any pid it likes.
+ */
+function classifyHealth(health, owned, port) {
+    if (health === null || typeof health !== "object" || Array.isArray(health)) {
+        return { identity: "foreign", facts: { workerPath: "", version: "" } };
+    }
+    const answer = health;
+    if (answer.product === FREE_MEM_PRODUCT)
+        return { identity: "ours" };
+    const pid = trustedPid(answer.pid);
+    if (owned !== null && owned.port === port && pid !== undefined && owned.pid === pid)
+        return { identity: "ours-stale" };
+    return {
+        identity: "foreign",
+        facts: { ...(pid !== undefined ? { pid } : {}), workerPath: filterForeignText(answer.workerPath), version: filterForeignText(answer.version) },
     };
-    const health = await get("/api/health");
-    if (!health)
-        return { port, reachable: false };
-    let version;
+}
+function foreignWorkerLine(port, facts) {
+    const where = facts.workerPath || "unknown path";
+    const version = facts.version || "unknown";
+    const cleanup = "run `freeharness cleanup --scope user` to remove its launchers";
+    if (facts.pid !== undefined) {
+        return `FAIL worker on :${port} is another program (pid ${facts.pid}, ${where}, version ${version}); memory is off — stop it with \`kill ${facts.pid}\` and ${cleanup}`;
+    }
+    return `FAIL worker on :${port} is another program (${where}, version ${version}); memory is off — stop the program listening on port ${port} and ${cleanup}`;
+}
+async function probeWorker(port, dir) {
+    let res;
     try {
-        version = String((await health.json()).version ?? "");
+        // Unfollowed, so the port's holder cannot redirect the probe to a server that vouches for it.
+        res = await fetch(`http://127.0.0.1:${port}/api/health`, { redirect: "manual", signal: AbortSignal.timeout(1500) });
     }
     catch {
-        /* non-JSON */
+        return { port, reachable: false };
     }
-    const root = await get("/");
-    let body = "";
+    let health;
     try {
-        body = root ? await root.text() : "";
+        const text = await res.text();
+        // Our worker always answers health with 200, so any other answer comes from another program.
+        health = res.status === 200 ? JSON.parse(text) : undefined;
     }
     catch {
-        /* ignore */
+        /* non-JSON or cut off: classified as foreign below */
+    }
+    const verdict = classifyHealth(health, ownedWorker(dir), port);
+    const fields = (health !== null && typeof health === "object" ? health : {});
+    let parked;
+    const count = fields.parked?.count;
+    if (typeof count === "number" && Number.isInteger(count) && count >= 0) {
+        const age = fields.parked?.oldestAgeMs;
+        parked = { count, oldestAgeMs: typeof age === "number" && Number.isFinite(age) && age >= 0 ? age : null };
+    }
+    const embeddings = parseEmbeddingsHealth(fields.embeddings);
+    if (verdict.identity === "foreign") {
+        return { port, reachable: true, version: verdict.facts.version || undefined, identity: "foreign", ours: false, foreign: verdict.facts, parked, embeddings };
     }
-    const viewer = root?.status === 200;
-    const ours = root ? root.status === 404 || body.includes(VIEWER_MARKER) : undefined;
-    return { port, reachable: true, version, viewer, ours };
+    return { port, reachable: true, version: String(fields.version ?? ""), identity: verdict.identity, ours: true, parked, embeddings };
 }
 /**
  * Lists cache versions under one plugin-cache root.
@@ -1001,16 +1400,50 @@ function cacheTag(c) {
         return "previous FreeHarness build or upstream (legacy thedotmack/claude-mem cache)";
     return "FreeHarness build";
 }
+const TREE_BYTES_MAX_ENTRIES = 100_000;
+/** Bytes of regular files under `dir`; symlinks are never followed and the walk is capped, so a huge tree yields a lower bound. */
+function treeBytes(dir) {
+    let bytes = 0;
+    let seen = 0;
+    const stack = [dir];
+    while (stack.length > 0 && seen < TREE_BYTES_MAX_ENTRIES) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (++seen > TREE_BYTES_MAX_ENTRIES)
+                break;
+            const p = path.join(cur, e.name);
+            if (e.isDirectory())
+                stack.push(p);
+            else if (e.isFile()) {
+                try {
+                    bytes += fs.lstatSync(p).size;
+                }
+                catch {
+                    // vanished between readdir and lstat
+                }
+            }
+        }
+    }
+    return bytes;
+}
 /**
  * Diagnose which claude-mem is active.
  *
  * Returns:
- *   A MemoryDiagnosis with a verdict and printable lines (OK/WARN prefixed).
+ *   A MemoryDiagnosis with a verdict and printable lines (OK/WARN/INFO prefixed; FAIL for a
+ *   foreign worker on the memory port).
  */
 export async function diagnoseMemory() {
     const cfg = configDir();
-    const data = dataDir();
-    const dbPath = path.join(data, "claude-mem.db");
+    const { dataDir: data, dbFile: dbPath } = memoryPaths();
+    const dbName = path.basename(dbPath);
     const dbBytes = fs.existsSync(dbPath) ? fs.statSync(dbPath).size : 0;
     const chromaPresent = fs.existsSync(path.join(data, "chroma"));
     const cache = listCache(cfg);
@@ -1027,7 +1460,7 @@ export async function diagnoseMemory() {
         /* not registered */
     }
     const activeIsOurs = activeInstallPath ? fs.existsSync(path.join(activeInstallPath, ".install-version")) : undefined;
-    const worker = await probeWorker(workerPort(data));
+    const worker = await probeWorker(workerPort(data), data);
     const observer = readObserverStatus(data);
     for (const c of cache) {
         lines.push(`${c.ours && !c.legacy ? "OK  " : "WARN"} plugin cache ${c.version}: ${cacheTag(c)}; skills: ${c.skills.join(", ") || "(none)"}`);
@@ -1040,12 +1473,15 @@ export async function diagnoseMemory() {
     else {
         lines.push(`WARN ${PLUGIN_KEY} not registered in installed_plugins.json`);
     }
+    lines.push(...upstreamLines(cfg, worker.port));
     if (!worker.reachable) {
         lines.push(`OK   no worker listening on :${worker.port} (next SessionStart starts the registered plugin's worker)`);
     }
+    else if (worker.identity === "foreign") {
+        lines.push(foreignWorkerLine(worker.port, worker.foreign ?? { workerPath: "", version: "" }));
+    }
     else {
-        const isOurs = worker.ours === true;
-        lines.push(`${isOurs ? "OK  " : "WARN"} worker on :${worker.port} version ${worker.version ?? "?"} — ${isOurs ? `FreeHarness build (viewer: http://localhost:${worker.port}/)` : "serves the React viewer at / => UPSTREAM daemon still running"}`);
+        lines.push(`OK   worker on :${worker.port} version ${worker.version ?? "?"} — FreeHarness build (viewer: http://localhost:${worker.port}/)`);
         // A worker outlives the plugin upgrade that replaced its files: it keeps serving the old
         // version until restarted. The verdict is unaffected (both are ours when both are ours).
         if (worker.version && activeVersion && worker.version !== activeVersion) {
@@ -1063,6 +1499,20 @@ export async function diagnoseMemory() {
     const provider = effectiveObserverProvider(path.join(data, "settings.json"));
     const providerSuffix = provider.provider === "local" ? ` provider=local ${provider.model}` : " provider=claude";
     lines.push(`${baseIsHaiku ? "OK  " : "WARN"} observer model base=${models.base} simple=${models.simple} summary=${models.summary}${providerSuffix}${baseIsHaiku ? "" : " — not a haiku alias; run `freeharness memory settings`"}`);
+    if (!isHaikuAlias(models.summary)) {
+        lines.push(`WARN observer summary tier FREE_MEM_TIER_SUMMARY_MODEL=${models.summary} is not a haiku alias; run \`freeharness memory settings\``);
+    }
+    if (provider.provider === "local") {
+        lines.push("WARN observer FREE_MEM_PROVIDER=local runs beside the claude observer; run `freeharness memory settings`");
+    }
+    const skipRaw = setting(readFlatSettings(path.join(data, "settings.json")), "FREE_MEM_SKIP_TOOLS");
+    if (typeof skipRaw === "string") {
+        const skipped = skipRaw.split(",").map((t) => t.trim());
+        const missing = LOCAL_PROVIDER_SERVED_TOOLS.filter((t) => !skipped.includes(t));
+        if (missing.length > 0) {
+            lines.push(`WARN observer FREE_MEM_SKIP_TOOLS lacks ${missing.join(", ")}, so the observer pays for them; run \`freeharness memory settings\``);
+        }
+    }
     lines.push(...(await memoryProviderLines(path.join(data, "settings.json"))));
     lines.push(...spendLines(observerSpend(dbPath)));
     const localLogSummary = readLocalProviderLog(path.join(data, "local-provider.jsonl"), startOfUtcDayMs(now), now);
@@ -1072,17 +1522,19 @@ export async function diagnoseMemory() {
         ? observerDuplicateRate(dbPath)
         : { today: { observations: 0, duplicates: 0 }, yesterday: { observations: 0, duplicates: 0 } };
     lines.push(...localProviderLines(localLogSummary, duplicateStats));
-    lines.push(`INFO data dir ${data}: claude-mem.db ${(dbBytes / 1048576).toFixed(1)} MB${chromaPresent ? " + chroma/" : ""} (shared by both builds; back up before switching)`);
-    const schema = dbSchemaVersion(dbPath);
-    if (schema !== null) {
-        lines.push(schema <= OUR_SCHEMA_VERSION
-            ? `OK   claude-mem.db schema v${schema} (our engine knows up to v${OUR_SCHEMA_VERSION})`
-            : schema === 50
-                ? `OK   claude-mem.db schema v50 (upstream 13.2x; v50 only adds nullable sdk_sessions columns our engine v${OUR_SCHEMA_VERSION} ignores)`
-                : `WARN claude-mem.db schema v${schema} is NEWER than our engine (v${OUR_SCHEMA_VERSION}) — migrated by an upstream build; migrations are additive so it usually works, but keep the backup and watch the first worker start`);
+    lines.push(...pipelineLines(data, dbPath, spawnSync, worker));
+    lines.push(`INFO memory data dir ${data}: ${dbName} ${(dbBytes / 1048576).toFixed(1)} MB (shared by both builds; back up before switching)`);
+    if (chromaPresent) {
+        const mb = (treeBytes(path.join(data, "chroma")) / 1048576).toFixed(1);
+        lines.push(`INFO memory data dir ${data}: chroma/ (${mb} MB) is no longer used by free-mem and is kept; move it aside by hand to reclaim the space`);
     }
+    lines.push(...deprecatedNameLines(process.env, path.join(data, "settings.json")));
+    lines.push(...legacyWriteLines(os.homedir()));
+    const schemaLine = schemaVersionLine(dbPath, dbName);
+    if (schemaLine !== null)
+        lines.push(schemaLine);
     const foreign = cache.some((c) => !c.ours);
-    const upstreamWorker = worker.reachable && worker.ours !== true;
+    const upstreamWorker = worker.reachable && worker.identity === "foreign";
     let verdict = "none";
     if (cache.length > 0) {
         if (activeIsOurs && !foreign && !upstreamWorker)
@@ -1158,17 +1610,159 @@ export async function restartWorker(dryRun, diagnosis) {
     }
     return { method: "nothing", detail: `no worker on :${d.worker.port} and no registered FreeHarness build to launch (run install.sh --with-memory)` };
 }
+// Set when a stop-only call stopped a running worker, so the next restart decision owes it back.
+let stopOwed = false;
+async function answers(port) {
+    try {
+        await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(1000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * Make the FreeHarness build the only active claude-mem: stop a running worker, move
- * foreign cache versions aside (never deleted), point installed_plugins at ours.
+ * Stops the worker without starting another, then waits until its pid file names no live process
+ * and its port is closed.
+ * @param mode Only `shutdown`.
+ * @param opts Data dir and port (the resolved ones by default) and the wait bound in ms.
+ * @returns Whether it stopped, whether one was running, and the reason on timeout.
+ */
+export async function stopWorker(mode, opts = {}) {
+    const dir = opts.dir ?? dataDir();
+    const port = opts.port ?? workerPort(dir);
+    const pidFile = path.join(dir, "worker.pid");
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    const up = await answers(port);
+    const wasRunning = up || pidFileLive(pidFile);
+    if (up && mode === "shutdown") {
+        try {
+            await fetch(`http://127.0.0.1:${port}/api/admin/shutdown`, { method: "POST", signal: AbortSignal.timeout(5000) });
+        }
+        catch {
+            /* it may exit before answering */
+        }
+    }
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const answering = await answers(port);
+        const live = pidFileLive(pidFile);
+        if (!answering && !live)
+            break;
+        if (Date.now() >= deadline) {
+            return { stopped: false, wasRunning, reason: answering ? `worker on :${port} still answers after ${timeoutMs} ms` : `${pidFile} still names a live process after ${timeoutMs} ms` };
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    if (wasRunning)
+        stopOwed = true;
+    return { stopped: true, wasRunning };
+}
+/** Whether a worker answers on the data dir's worker port right now. */
+export async function workerRunning() {
+    const dir = dataDir();
+    return (await probeWorker(workerPort(dir), dir)).reachable;
+}
+/** The engine's log file for a day, where a failed worker start leaves its reason. */
+export function workerLogPath(now = new Date()) {
+    return path.join(dataDir(), "logs", `free-mem-${now.toISOString().split("T")[0]}.log`);
+}
+/** `<pid>:<version>` from `/api/health` on the data dir's worker port; null when nothing answers. */
+async function workerIdentity() {
+    try {
+        const res = await fetch(`http://127.0.0.1:${workerPort(dataDir())}/api/health`, { signal: AbortSignal.timeout(1500) });
+        const body = (await res.json().catch(() => ({})));
+        return `${String(body.pid ?? "")}:${String(body.version ?? "")}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Polls health until a worker other than `previous` answers: one seen after the port went down,
+ * or one whose pid or version differs. Without this, the old worker still answering right
+ * after the launcher spawn passes as the restarted one.
+ *
+ * Args:
+ *   ms: Poll budget.
+ *   previous: The identity read before the restart (null when nothing answered).
+ *
+ * Returns:
+ *   `up` for a new worker; `old` when the previous one still answered at the deadline; `down` otherwise.
+ */
+async function workerAnswers(ms, previous) {
+    const deadline = Date.now() + ms;
+    let previousGone = previous === null;
+    do {
+        const current = await workerIdentity();
+        if (current === null)
+            previousGone = true;
+        else if (previousGone || current !== previous)
+            return "up";
+        await new Promise((r) => setTimeout(r, 250));
+    } while (Date.now() < deadline);
+    return previousGone ? "down" : "old";
+}
+/**
+ * Restart a worker that was running before the command when the command staged a different build
+ * or stopped that worker itself; a worker that was not running stays stopped. A failed
+ * restart, including a launched worker that never answers health or an old worker that never
+ * gives way to a new one, is reported, never thrown.
  *
  * Args:
+ *   wasRunning: Whether a worker answered before the command changed anything.
+ *   cause: Whether the command staged a build or stopped the worker.
  *   dryRun: Report only.
+ *   healthMs: How long a launched worker has to answer `/api/health`.
+ *
+ * Returns:
+ *   The decision and, on apply, its outcome.
+ */
+export async function restartAfterStage(wasRunning, cause, dryRun, healthMs = 15_000) {
+    if (!wasRunning)
+        return { planned: false, reason: "not running; it stays stopped" };
+    if (!cause.staged && !cause.stopped && !stopOwed)
+        return { planned: false, reason: "build unchanged" };
+    const out = { planned: true, reason: cause.staged ? "a different build was staged" : "the command stopped it" };
+    if (dryRun)
+        return out;
+    stopOwed = false;
+    try {
+        const previous = await workerIdentity();
+        out.result = await restartWorker(false);
+        const outcome = out.result.method === "worker-service restart" ? await workerAnswers(healthMs, previous) : undefined;
+        if (outcome === undefined)
+            out.error = `${out.result.method}: ${out.result.detail}`;
+        else if (outcome === "old")
+            out.error = `no new worker answered /api/health within ${healthMs} ms after ${out.result.detail}; the previous worker (pid:version ${previous}) still answers`;
+        else if (outcome === "down")
+            out.error = `worker did not answer /api/health within ${healthMs} ms after ${out.result.detail}`;
+    }
+    catch (e) {
+        out.error = e instanceof Error ? e.message : String(e);
+    }
+    if (out.error)
+        out.log = workerLogPath();
+    return out;
+}
+/**
+ * Make the FreeHarness build the only active claude-mem: stage the vendored build when it is
+ * built and differs from the cache, stop a running worker, move foreign cache versions aside
+ * (never deleted), point installed_plugins at ours, and restart the worker it stopped.
+ * Staging runs first, so a staging failure leaves a running worker up.
+ *
+ * Args:
+ *   dryRun: Report only.
+ *   opts: The vendored plugin dir; without it the newest cached build is registered as is.
  *
  * Returns:
  *   What was (or would be) done.
+ *
+ * Raises:
+ *   Error: When the cache holds no FreeHarness build, the plugin version is not semver, staging
+ *     fails, or deps need a missing Bun (refused before any cache write).
  */
-export async function activateOurs(dryRun) {
+export async function activateOurs(dryRun, opts = {}) {
     const d = await diagnoseMemory();
     // A native-cache build always wins over a legacy (pre-rename) one, even at a lower version:
     // the native path is what the current vendored engine's constants resolve to.
@@ -1177,7 +1771,36 @@ export async function activateOurs(dryRun) {
         .sort((a, b) => Number(a.legacy) - Number(b.legacy) || b.version.localeCompare(a.version, undefined, { numeric: true }))[0];
     if (!ours)
         throw new Error("no FreeHarness build in the plugin cache — run install.sh --with-memory first");
-    const res = { stoppedWorker: false, disabled: [], registered: false };
+    const res = { stoppedWorker: false, disabled: [], registered: false, stageNotes: [], restart: { planned: false, reason: "" } };
+    let active = { dir: ours.dir, version: ours.version };
+    const unbuilt = opts.pluginDir ? missingPluginBundles(opts.pluginDir) : [];
+    if (!opts.pluginDir)
+        res.stageNotes.push("no vendored build in this checkout; the cached build is registered as is");
+    else if (unbuilt.length > 0) {
+        // plugin/scripts is untracked build output: an unbuilt checkout must never wipe a working cache.
+        res.stageNotes.push(`${opts.pluginDir} is not built (missing ${unbuilt.map((f) => `scripts/${f}`).join(", ")}); the cached build is kept`);
+    }
+    else {
+        const version = pluginVersion(opts.pluginDir);
+        const cacheDir = claudePluginPaths(version).cacheDir;
+        const bun = probeBun();
+        // A re-stage empties node_modules, and a registered cache without its deps fails every hook.
+        if (!bun.path && declaresPluginDeps(opts.pluginDir) && stagePluginCache(opts.pluginDir, cacheDir, { dryRun: true }).staged) {
+            throw new Error(`Bun is required to install the plugin runtime deps in ${cacheDir} (https://bun.sh); the plugin cache is unchanged`);
+        }
+        const stage = stagePluginCache(opts.pluginDir, cacheDir, { dryRun });
+        if (!dryRun && (stage.staged || !fs.existsSync(path.join(cacheDir, ".install-version")))) {
+            if (missingPluginDeps(cacheDir).length > 0) {
+                if (!bun.path)
+                    throw new Error(`Bun is required to install the plugin runtime deps in ${cacheDir} (https://bun.sh)`);
+                installPluginDeps(cacheDir, bun.path);
+            }
+            writeInstallMarker(cacheDir, version, bun.version ?? "unknown");
+        }
+        res.stage = { ...stage, cacheDir, version };
+        res.stageNotes.push(...stage.notes);
+        active = { dir: cacheDir, version };
+    }
     if (d.worker.reachable && !dryRun) {
         try {
             await fetch(`http://127.0.0.1:${d.worker.port}/api/admin/shutdown`, { method: "POST", signal: AbortSignal.timeout(5000) });
@@ -1209,9 +1832,10 @@ export async function activateOurs(dryRun) {
         const ip = JSON.parse(fs.readFileSync(ipPath, "utf8"));
         const now = new Date().toISOString();
         ip.plugins = ip.plugins ?? {};
-        ip.plugins[PLUGIN_KEY] = [{ scope: "user", installPath: ours.dir, version: ours.version, installedAt: now, lastUpdated: now }];
+        ip.plugins[PLUGIN_KEY] = [{ scope: "user", installPath: active.dir, version: active.version, installedAt: now, lastUpdated: now }];
         fs.writeFileSync(ipPath, JSON.stringify(ip, null, 2) + "\n");
     }
     res.registered = true;
+    res.restart = await restartAfterStage(d.worker.reachable, { staged: res.stage?.staged === true, stopped: res.stoppedWorker }, dryRun);
     return res;
 }