freeharness 0.4.1

package/dist/adapters/memory/doctor.js

@@ -0,0 +1,1217 @@
+// Memory doctor: tell which claude-mem is actually active on this machine (ours vs an
+// upstream install), back up its data, and switch the machine to the FreeHarness build.
+//
+// Evidence used (no guessing):
+//   - plugin cache versions under <cfg>/plugins/cache/thedotmack/claude-mem/<ver>/ — ours
+//     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
+//     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 { 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";
+/** 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. */
+export const QUOTA_EXHAUSTED_RECHECK_COOLDOWN_MS = 30 * 60_000;
+/** Ledger file names (engine shared/observer-health.ts, shared/quota-cooldown.ts), under the data dir. */
+export const OBSERVER_HEALTH_FILENAME = "observer-health.json";
+export const QUOTA_COOLDOWN_FILENAME = "quota-cooldown.json";
+/**
+ * Read the observer ledgers of the data dir.
+ *
+ * Args:
+ *   data: The claude-mem data dir.
+ *   now: Clock (ms), injectable for tests.
+ *
+ * Returns:
+ *   Health (null when no ledger), the unhealthy verdict (engine rule: >= threshold failures
+ *   and the last error newer than the last success) and every armed cooldown with its remaining time.
+ */
+export function readObserverStatus(data, now = Date.now()) {
+    let health = null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(data, OBSERVER_HEALTH_FILENAME), "utf8"));
+        if (raw && typeof raw === "object") {
+            health = {
+                consecutiveFailures: Number(raw.consecutiveFailures) || 0,
+                failingSinceAt: raw.failingSinceAt ?? null,
+                lastErrorAt: raw.lastErrorAt ?? null,
+                lastErrorMessage: raw.lastErrorMessage ?? null,
+                lastErrorProvider: raw.lastErrorProvider ?? null,
+                lastSuccessAt: raw.lastSuccessAt ?? null,
+                lastErrorKind: raw.lastErrorKind ?? null,
+                lastErrorCode: raw.lastErrorCode ?? null,
+                lastErrorAction: raw.lastErrorAction ?? null,
+            };
+        }
+    }
+    catch {
+        /* absent or unreadable */
+    }
+    const unhealthy = health !== null && health.consecutiveFailures >= OBSERVER_UNHEALTHY_FAILURE_THRESHOLD && (health.lastErrorAt ?? 0) > (health.lastSuccessAt ?? 0);
+    const cooldowns = [];
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(data, QUOTA_COOLDOWN_FILENAME), "utf8"));
+        if (Array.isArray(raw)) {
+            for (const e of raw) {
+                if (!e || typeof e.provider !== "string" || typeof e.armedAtMs !== "number")
+                    continue;
+                cooldowns.push({
+                    provider: e.provider,
+                    message: typeof e.message === "string" ? e.message : "Provider reported the inference allowance exhausted",
+                    ...(e.window ? { window: e.window } : {}),
+                    armedAtMs: e.armedAtMs,
+                    remainingMs: Math.max(0, QUOTA_EXHAUSTED_RECHECK_COOLDOWN_MS - (now - e.armedAtMs)),
+                });
+            }
+        }
+    }
+    catch {
+        /* absent or unreadable */
+    }
+    return { health, unhealthy, cooldowns };
+}
+/**
+ * How long an unresolved observer verdict stays worth a fresh warning. Independent of the
+ * engine's own `isObserverUnhealthy` (that gate does not carry an age bound yet): this reads
+ * the same ledger file directly so `memory status` can down-rank a failure with no session in
+ * between from a live WARN to a dated INFO line.
+ */
+export const OBSERVER_STALE_AFTER_MS = 12 * 60 * 60_000;
+/**
+ * True when the ledger's last failure is old enough that a fresh WARN would be noise: the
+ * same unhealthy condition (>= threshold consecutive failures, the last error newer than the
+ * last success) plus that last error being older than `OBSERVER_STALE_AFTER_MS`.
+ *
+ * Args:
+ *   ledger: The observer-health ledger (null when no ledger file exists yet).
+ *   nowMs: Clock (ms), injectable for tests.
+ *
+ * Returns:
+ *   Whether the verdict is stale.
+ */
+export function isObserverVerdictStale(ledger, nowMs = Date.now()) {
+    if (!ledger || ledger.lastErrorAt === null)
+        return false;
+    if (ledger.consecutiveFailures < OBSERVER_UNHEALTHY_FAILURE_THRESHOLD)
+        return false;
+    if (ledger.lastErrorAt <= (ledger.lastSuccessAt ?? 0))
+        return false;
+    return nowMs - ledger.lastErrorAt > OBSERVER_STALE_AFTER_MS;
+}
+/** "3 minutes" / "about 2 hours" for durations (mirrors the engine's describeDuration). */
+function describeDuration(ms) {
+    const minutes = Math.max(1, Math.round(ms / 60_000));
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 48)
+        return `about ${hours} hour${hours === 1 ? "" : "s"}`;
+    return `about ${Math.round(hours / 24)} days`;
+}
+/**
+ * Printable lines for the observer state (OK/WARN/INFO prefixed).
+ *
+ * Args:
+ *   s: The observer status.
+ *   now: Clock (ms).
+ *
+ * Returns:
+ *   Lines: one for the health ledger, one per cooldown (or "no quota cooldown").
+ */
+export function observerLines(s, now = Date.now()) {
+    const out = [];
+    const iso = (ms) => (ms ? new Date(ms).toISOString() : "never");
+    if (!s.health) {
+        out.push(`INFO observer: no ${OBSERVER_HEALTH_FILENAME} yet (written by the worker after its first observer run)`);
+    }
+    else if (s.unhealthy && isObserverVerdictStale(s.health, now)) {
+        // The verdict has expired (no session in between refreshed it): the caller's own
+        // "observer verdict stale" INFO line names the last failure, so no WARN is injected here.
+    }
+    else if (s.unhealthy) {
+        const since = s.health.failingSinceAt ?? s.health.lastErrorAt;
+        out.push(`WARN observer UNHEALTHY: ${s.health.consecutiveFailures} consecutive rejections on ${s.health.lastErrorProvider ?? "unknown provider"} for ${describeDuration(now - (since ?? now))} (since ${iso(since)}; last success ${iso(s.health.lastSuccessAt)})${s.health.lastErrorKind ? ` [${s.health.lastErrorKind}]` : ""}: ${s.health.lastErrorMessage ?? "unknown error"}${s.health.lastErrorAction ? ` — ${s.health.lastErrorAction}` : ""}`);
+    }
+    else if (s.health.consecutiveFailures > 0) {
+        out.push(`OK   observer: ${s.health.consecutiveFailures} rejection${s.health.consecutiveFailures === 1 ? "" : "s"} since the last success (${iso(s.health.lastSuccessAt)}); below the ${OBSERVER_UNHEALTHY_FAILURE_THRESHOLD}-failure warning threshold. Last error: ${s.health.lastErrorMessage ?? "unknown"}`);
+    }
+    else {
+        out.push(`OK   observer healthy: last successful store ${iso(s.health.lastSuccessAt)}, no rejections since`);
+    }
+    // A resolved local-provider failure (the claude fallback stored the observation, so the
+    // ledger is not unhealthy) still deserves a visible line: local kinds never raise the
+    // health WARN on their own (spec: "local kinds SHALL NOT mark the observer unhealthy while
+    // the claude fallback stores observations"), so without this the owner would see no signal
+    // at all that the local server dropped a batch. Gated the same way as ContextBuilder's
+    // localNoticeApplies: a success recorded after the failure means a retry already landed it,
+    // so the line would misreport a stale outage as current.
+    if (s.health &&
+        !s.unhealthy &&
+        s.health.lastErrorKind &&
+        s.health.lastErrorKind.startsWith("local_") &&
+        s.health.lastErrorAt !== null &&
+        s.health.lastErrorAt > (s.health.lastSuccessAt ?? 0)) {
+        out.push(`INFO observer last failure was local (${s.health.lastErrorKind}): failed batches were retried on the claude path or stay queued for the next observer start; freeharness doctor --scope user probes the server`);
+    }
+    if (s.cooldowns.length === 0) {
+        out.push("OK   no quota cooldown armed");
+    }
+    for (const c of s.cooldowns) {
+        const armed = new Date(c.armedAtMs).toISOString();
+        out.push(c.remainingMs > 0
+            ? `WARN quota cooldown ACTIVE for ${c.provider}${c.window ? ` (${c.window} window)` : ""}: ${c.message} — ${describeDuration(c.remainingMs)} remaining (armed ${armed}; observations are withheld until then, one re-probe after)`
+            : `OK   quota cooldown for ${c.provider} elapsed (armed ${armed}); the next observation re-probes the provider`);
+    }
+    return out;
+}
+/** 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;
+/**
+ * Read max(version) from schema_versions via the sqlite3 CLI (no node sqlite dep).
+ *
+ * Returns:
+ *   The version, or null when the db/sqlite3 is unavailable.
+ */
+function dbSchemaVersion(dbPath) {
+    if (!fs.existsSync(dbPath))
+        return null;
+    const r = spawnSync("sqlite3", ["-readonly", dbPath, "SELECT MAX(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;
+}
+/**
+ * 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
+ * owner reads off `memory status` (not "the other six days").
+ *
+ * Args:
+ *   dbPath: Path of claude-mem.db.
+ *   spawn: Injectable spawnSync, so the missing-binary path is deterministic in tests
+ *     regardless of whether sqlite3 happens to be on the test machine's PATH.
+ *
+ * Returns:
+ *   One row per (window, model) with a row, or the reason spend could not be read.
+ */
+export function observerSpend(dbPath, spawn = spawnSync) {
+    if (!fs.existsSync(dbPath))
+        return [];
+    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;",
+    ].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)
+        return { reason: (r.stderr || "").trim().split("\n")[0] || `sqlite3 exited ${r.status}`, missingBinary: false };
+    const rows = [];
+    for (const line of r.stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        const [window, model, 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 });
+    }
+    return rows;
+}
+/**
+ * Model ids that name metered Claude spend: the `claude-*` families, a bare tier alias
+ * (`haiku`, `sonnet`, `opus`, alone or with a `-` suffix) and the `$TIER:` placeholder the
+ * engine writes before a tier is resolved. `generated_by_model` stores the id as configured,
+ * and the engine's own default simple-tier model is the bare alias `haiku`, so a plain
+ * `claude` prefix test would file the whole simple tier as free local spend.
+ *
+ * The same rule, with the same expression, lives in the cost-tracker hook
+ * (`canonical/hooks/freeharness-cost-tracker.mjs`): the two split the same rows and a
+ * divergence would make `memory status` and `cost report` disagree on one machine.
+ *
+ * Args:
+ *   model: A `generated_by_model` value.
+ *
+ * Returns:
+ *   True for a Claude id, false for a local one.
+ */
+export function isClaudeModelId(model) {
+    return /^(?:claude|\$TIER:|(?:haiku|sonnet|opus)(?:-|$))/.test(model);
+}
+/**
+ * Renders `observerSpend`'s result as printable INFO lines: for each window (today, then the
+ * seven-day window) that has at least one row, the Claude model rows, then the local model
+ * rows, then a `subscription observer tokens` subtotal summing the Claude rows of that window
+ * only — the subscription is the metered resource, so a local row never inflates it and a
+ * local-only window still gets a printed (zero) subtotal, since the window itself had
+ * activity. A window with no rows at all (a fresh install, or a provider not yet run today)
+ * prints nothing, matching the pre-split behavior for an empty result. A single line instead
+ * when spend could not be read at all (the fixed sqlite3-missing wording, or the
+ * query/database error's own reason).
+ *
+ * Args:
+ *   spend: `observerSpend`'s return value.
+ *
+ * Returns:
+ *   Lines in today-rows/today-subtotal/seven-day-rows/seven-day-subtotal order; `[]` when
+ *   `spend` is an empty array (no observations in either window).
+ */
+export function spendLines(spend) {
+    if (!Array.isArray(spend)) {
+        return [spend.missingBinary ? "INFO observer spend unavailable without sqlite3" : `INFO observer spend unavailable: ${spend.reason}`];
+    }
+    const line = (r) => `INFO observer spend ${r.window === "today" ? "today" : "last 7 days"}: ${r.model} ${r.observations} observations, ${r.tokens} tokens`;
+    const windowLines = (window, label) => {
+        const rows = spend.filter((r) => r.window === window);
+        if (rows.length === 0)
+            return [];
+        const claude = rows.filter((r) => isClaudeModelId(r.model));
+        const local = rows.filter((r) => !isClaudeModelId(r.model));
+        const subtotal = claude.reduce((sum, r) => sum + r.tokens, 0);
+        return [...claude.map(line), ...local.map(line), `INFO subscription observer tokens ${label}: ${subtotal}`];
+    };
+    return [...windowLines("today", "today"), ...windowLines("seven_day", "last 7 days")];
+}
+/** Start of the UTC calendar day containing `nowMs` (matches `observerSpend`'s `date('now')`, which sqlite evaluates in UTC). */
+function startOfUtcDayMs(nowMs) {
+    const d = new Date(nowMs);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+/** Default cap for `readLocalProviderLog`'s read: an unbounded read of an append-only, never-rotated log is unbounded work per `memory status` run. */
+const DEFAULT_LOCAL_PROVIDER_LOG_CAP_BYTES = 4 * 1024 * 1024;
+/**
+ * Reads the last `maxBytes` of a file, dropping the leading partial line when the read did not
+ * start at byte 0 (the day boundary and the log's true start are both inside the discarded
+ * head, so nothing counted from a truncated read double-counts or half-counts a batch).
+ *
+ * Args:
+ *   filePath: File to read.
+ *   maxBytes: Cap.
+ *
+ * Returns:
+ *   The tail text (whole file when it fits) and whether it was truncated.
+ */
+function readTail(filePath, maxBytes) {
+    const size = fs.statSync(filePath).size;
+    if (size <= maxBytes)
+        return { text: fs.readFileSync(filePath, "utf8"), truncated: false };
+    const start = size - maxBytes;
+    const fd = fs.openSync(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(maxBytes);
+        // readSync may return fewer bytes than asked; converting the whole buffer would turn the
+        // untouched zero padding into a garbage trailing line the caller counts as unparseable.
+        const read = fs.readSync(fd, buffer, 0, maxBytes, start);
+        const chunk = buffer.subarray(0, read).toString("utf8");
+        const firstNewline = chunk.indexOf("\n");
+        return { text: firstNewline === -1 ? "" : chunk.slice(firstNewline + 1), truncated: true };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Reads today's local-provider activity from the append-only batch log, at most its last
+ * `maxBytes` (default 4 MB) so an unrotated, ever-growing log never makes `memory status`
+ * read the whole file.
+ *
+ * Args:
+ *   logPath: `<data-dir>/local-provider.jsonl`.
+ *   dayStartMs: Start of the UTC day being summarized. The engine writes `ts` as an ISO
+ *     instant and the only caller passes `startOfUtcDayMs`, so the window matches the UTC
+ *     boundary `observerSpend`'s `date('now')` already uses and the two lines describe one day.
+ *   nowMs: End of the window (the day so far).
+ *   maxBytes: Read cap, injectable so a test can exercise truncation without writing a
+ *     multi-megabyte fixture.
+ *
+ * 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);
+ *   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.
+ */
+export function readLocalProviderLog(logPath, dayStartMs, nowMs, maxBytes = DEFAULT_LOCAL_PROVIDER_LOG_CAP_BYTES) {
+    let tail;
+    try {
+        tail = readTail(logPath, maxBytes);
+    }
+    catch (e) {
+        const err = e;
+        if (err && err.code === "ENOENT")
+            return null;
+        return { reason: err && err.message ? err.message : String(e) };
+    }
+    const summary = { batches: 0, local: 0, fallbacks: {}, skippedLines: 0, truncated: tail.truncated };
+    for (const rawLine of tail.text.split("\n")) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            summary.skippedLines++;
+            continue;
+        }
+        if (!entry || typeof entry !== "object") {
+            summary.skippedLines++;
+            continue;
+        }
+        const e = entry;
+        const tsMs = typeof e.ts === "string" ? Date.parse(e.ts) : NaN;
+        const attempted = e.attempted;
+        if (!Number.isFinite(tsMs) || (attempted !== "local" && attempted !== "claude")) {
+            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
+        summary.batches++;
+        if (e.answered === "local") {
+            summary.local++;
+        }
+        else {
+            const kind = typeof e.kind === "string" && e.kind.length > 0 ? e.kind : "unknown";
+            summary.fallbacks[kind] = (summary.fallbacks[kind] ?? 0) + 1;
+        }
+    }
+    return summary;
+}
+/**
+ * Reads the near-duplicate rate of the locally answered observations, for the UTC day so far
+ * and for the one before it: rows are grouped by `(generated_by_model, memory_session_id,
+ * title)` and every row past the first of a group counts as a near-duplicate. Only rows whose
+ * `generated_by_model` fails `isClaudeModelId` are counted — a stateless local batch has no
+ * prior context to avoid repeating itself, which is the cost the figure exists to measure, and
+ * a Claude row would dilute it. The previous day is read in the same pass so the rate has a
+ * local-to-local baseline: the day so far compared against the day before it, both counting
+ * only locally answered rows.
+ *
+ * Same unavailability shape as `observerSpend`.
+ *
+ * Args:
+ *   dbPath: Path of claude-mem.db.
+ *   spawn: Injectable spawnSync (see `observerSpend`).
+ *
+ * Returns:
+ *   Both days' observation and duplicate counts, or the reason the rate could not be read.
+ */
+export function observerDuplicateRate(dbPath, spawn = spawnSync) {
+    const empty = { today: { observations: 0, duplicates: 0 }, yesterday: { observations: 0, duplicates: 0 } };
+    if (!fs.existsSync(dbPath))
+        return empty;
+    const query = [
+        "SELECT day, model, COUNT(*) FROM (",
+        "SELECT CASE WHEN date(created_at) = date('now') THEN 'today' ELSE 'yesterday' END AS day,",
+        "COALESCE(generated_by_model,'') AS model, memory_session_id, title FROM observations",
+        "WHERE date(created_at) IN (date('now'), date('now','-1 day'))",
+        ") GROUP BY day, model, memory_session_id, title;",
+    ].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)
+        return { reason: (r.stderr || "").trim().split("\n")[0] || `sqlite3 exited ${r.status}`, missingBinary: false };
+    const stats = { today: { observations: 0, duplicates: 0 }, yesterday: { observations: 0, duplicates: 0 } };
+    for (const line of r.stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        const parts = line.split("|");
+        if (parts.length < 3)
+            continue;
+        const day = parts[0];
+        const model = parts.slice(1, -1).join("|");
+        const count = parseInt(parts[parts.length - 1], 10) || 0;
+        if (day !== "today" && day !== "yesterday")
+            continue;
+        if (isClaudeModelId(model))
+            continue;
+        stats[day].observations += count;
+        stats[day].duplicates += count - 1;
+    }
+    return stats;
+}
+/**
+ * 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.
+ *
+ * Args:
+ *   summary: `readLocalProviderLog`'s return value.
+ *   duplicates: `observerDuplicateRate`'s return value.
+ *
+ * Returns:
+ *   Zero, one or two lines.
+ */
+export function localProviderLines(summary, duplicates) {
+    if (!summary)
+        return [];
+    if ("reason" in summary)
+        return [`WARN local observer log unreadable: ${summary.reason}`];
+    const fallbackTotal = summary.batches - summary.local;
+    const kindText = Object.keys(summary.fallbacks)
+        .sort()
+        .map((kind) => `${kind} ${summary.fallbacks[kind]}`)
+        .join(", ");
+    const out = [
+        `INFO local observer today: ${summary.batches} batches, ${summary.local} local, ${fallbackTotal} fallback${fallbackTotal === 1 ? "" : "s"}${kindText ? ` (${kindText})` : ""}${summary.truncated ? " (log truncated)" : ""}`,
+    ];
+    if (!("reason" in duplicates)) {
+        const share = (d) => {
+            const pct = d.observations > 0 ? ((d.duplicates / d.observations) * 100).toFixed(1) : "0.0";
+            return `${d.duplicates}/${d.observations} (${pct}%)`;
+        };
+        out.push(`INFO local observer near-duplicates today: ${share(duplicates.today)}, yesterday ${share(duplicates.yesterday)}`);
+    }
+    return out;
+}
+/** A `haiku` alias (bare or `claude-haiku-*`), the FreeHarness-recommended observer model kind. */
+export function isHaikuAlias(model) {
+    return model === "haiku" || model.startsWith("claude-haiku");
+}
+/**
+ * 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
+ * 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.
+ */
+const FALLBACK_ENGINE_OBSERVER_DEFAULTS = { base: "claude-haiku-4-5-20251001", simple: "haiku", summary: "" };
+/**
+ * Reads the engine's own default observer models straight from
+ * packages/memory/vendor/claude-mem/engine/shared/SettingsDefaultsManager.ts, so a change to
+ * that file's DEFAULTS reaches `memory status` without a hand-maintained copy going stale.
+ *
+ * Returns:
+ *   Base, simple and (raw, possibly empty) summary defaults.
+ */
+function engineDefaultObserverModels() {
+    try {
+        const repo = sourceRepoRoot(resolveCanonicalDir());
+        if (!repo)
+            return FALLBACK_ENGINE_OBSERVER_DEFAULTS;
+        const managerPath = path.join(repo, "packages", "memory", "vendor", UPSTREAM_PLUGIN_NAME, "engine", "shared", "SettingsDefaultsManager.ts");
+        const src = fs.readFileSync(managerPath, "utf8");
+        const pick = (key) => src.match(new RegExp(`${key}:\\s*'([^']*)'`))?.[1];
+        return {
+            base: pick("CLAUDE_MEM_MODEL") ?? FALLBACK_ENGINE_OBSERVER_DEFAULTS.base,
+            simple: pick("CLAUDE_MEM_TIER_SIMPLE_MODEL") ?? FALLBACK_ENGINE_OBSERVER_DEFAULTS.simple,
+            summary: pick("CLAUDE_MEM_TIER_SUMMARY_MODEL") ?? FALLBACK_ENGINE_OBSERVER_DEFAULTS.summary,
+        };
+    }
+    catch {
+        return FALLBACK_ENGINE_OBSERVER_DEFAULTS;
+    }
+}
+/** Parses a settings.json (flat schema) into a string map; `{}` when absent or malformed. */
+function readFlatSettings(settingsPath) {
+    try {
+        return JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Effective observer model per tier: the engine defaults with the owner's settings.json layered
+ * on top, and the summary tier's empty-default resolved to the base model (the engine's own
+ * "empty = use default model for summaries" rule) so the printed value is what actually runs.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json (absent or malformed = engine defaults).
+ *
+ * Returns:
+ *   Base, simple and summary model ids.
+ */
+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 summary = rawSummary.length > 0 ? rawSummary : base;
+    return { base, simple, summary };
+}
+/** Engine fallbacks for an absent local key (LocalProvider.ts's own FALLBACK_BASE_URL / FALLBACK_MODEL). */
+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
+ * 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`
+ * or the engine's `local-model` default.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json (absent or malformed = claude).
+ *
+ * Returns:
+ *   The effective provider and, for local, its model id.
+ */
+export function effectiveObserverProvider(settingsPath) {
+    const values = readFlatSettings(settingsPath);
+    if (values.CLAUDE_MEM_PROVIDER !== "local")
+        return { provider: "claude", model: null };
+    const raw = values.CLAUDE_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.
+ */
+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",
+};
+/** `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",
+};
+/** 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
+ * 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.
+ * Deriving from the default at call time, rather than a second hand-maintained literal, means a
+ * later change to the default carries over here without an edit.
+ *
+ * Returns:
+ *   The recommended default's tool list minus the three served tools, comma-joined.
+ */
+function localProviderSkipTools() {
+    return RECOMMENDED_OBSERVER_SETTINGS.CLAUDE_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
+ * 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,
+};
+/**
+ * Builds the six `CLAUDE_MEM_LOCAL_*` / `CLAUDE_MEM_PROVIDER` / `CLAUDE_MEM_SKIP_TOOLS` keys for
+ * `memory settings --local`.
+ *
+ * Args:
+ *   baseUrl: Candidate `CLAUDE_MEM_LOCAL_BASE_URL` value.
+ *   model: Candidate `CLAUDE_MEM_LOCAL_MODEL` value.
+ *
+ * Returns:
+ *   The six local-provider keys.
+ *
+ * Raises:
+ *   Error: The base URL does not parse as an `http:`/`https:` URL, or the model id is empty or
+ *   matches `isClaudeModelId` (a likely misconfiguration, not a local model).
+ */
+function localObserverSettings(baseUrl, model) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`FAIL invalid --local base URL: ${baseUrl}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`FAIL invalid --local base URL: ${baseUrl}`);
+    }
+    if (!model || isClaudeModelId(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,
+        ...LOCAL_OBSERVER_SETTINGS_DEFAULTS,
+        CLAUDE_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
+ * keys, or the five recommended keys when neither `--local` nor `--no-local` is given.
+ *
+ * Args:
+ *   opts: The command's `--local`/`--no-local` request, if any.
+ *
+ * Returns:
+ *   The key set to preview or write.
+ *
+ * Raises:
+ *   Error: `--local` and `--no-local` given together, or `--local`'s values fail validation.
+ */
+function resolveObserverKeySet(opts) {
+    if (opts?.local && opts.noLocal) {
+        throw new Error("FAIL --local and --no-local cannot be combined");
+    }
+    if (opts?.local)
+        return localObserverSettings(opts.local.baseUrl, opts.local.model);
+    if (opts?.noLocal)
+        return NO_LOCAL_OBSERVER_SETTINGS;
+    return RECOMMENDED_OBSERVER_SETTINGS;
+}
+/**
+ * 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`
+ * restored to the recommended default.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json.
+ *   opts: The command's `--local`/`--no-local` request, if any.
+ *
+ * Returns:
+ *   One row per key in the selected set, and the parse error when the file is present but
+ *   invalid.
+ *
+ * Raises:
+ *   Error: `opts` fails validation (see `resolveObserverKeySet`); nothing is read or written.
+ */
+export function previewObserverSettings(settingsPath, opts) {
+    const keySet = resolveObserverKeySet(opts);
+    let values = {};
+    let parseError;
+    if (fs.existsSync(settingsPath)) {
+        try {
+            values = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        }
+        catch (e) {
+            parseError = e instanceof Error ? e.message : String(e);
+        }
+    }
+    const rows = Object.entries(keySet).map(([key, recommended]) => {
+        const raw = values[key];
+        const current = raw === undefined ? undefined : typeof raw === "string" ? raw : JSON.stringify(raw);
+        return { key, current, recommended, changed: current !== recommended };
+    });
+    return { rows, parseError };
+}
+/**
+ * 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
+ * (throws) without writing anything when `opts` fails validation or the existing file is not
+ * valid JSON.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json.
+ *   opts: The command's `--local`/`--no-local` request, if any.
+ *
+ * Returns:
+ *   Whether the file was created, and the backup path when one was made.
+ *
+ * Raises:
+ *   Error: `opts` fails validation, or the existing file is not valid JSON (its message names
+ *   the parse error).
+ */
+export function applyObserverSettings(settingsPath, opts) {
+    const keySet = resolveObserverKeySet(opts);
+    let values = {};
+    let created = false;
+    let backupPath;
+    if (fs.existsSync(settingsPath)) {
+        const raw = fs.readFileSync(settingsPath, "utf8");
+        try {
+            values = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new Error(`refusing to write ${settingsPath}: not valid JSON (${e instanceof Error ? e.message : String(e)})`);
+        }
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        backupPath = `${settingsPath}.${stamp}.bak`;
+        fs.copyFileSync(settingsPath, backupPath);
+    }
+    else {
+        created = true;
+    }
+    for (const [key, value] of Object.entries(keySet)) {
+        values[key] = value;
+    }
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(values, null, 2) + "\n");
+    return { created, backupPath };
+}
+/**
+ * Short text for a probe request's failure (the cause's code when present, e.g. ECONNREFUSED).
+ *
+ * Args:
+ *   e: Thrown value.
+ *   timeoutMs: Timeout used, for the abort message.
+ *
+ * Returns:
+ *   Text.
+ */
+function describeProbeError(e, timeoutMs) {
+    if (e instanceof Error) {
+        if (e.name === "AbortError")
+            return `timeout after ${timeoutMs} ms`;
+        const cause = e.cause;
+        return cause?.code ?? cause?.message ?? e.message;
+    }
+    return String(e);
+}
+/**
+ * GETs a URL under a caller-owned `AbortSignal`, parsing a JSON body when present.
+ *
+ * Args:
+ *   url: URL.
+ *   signal: Abort signal shared across every request of one probe call, so the probe's total
+ *     time is bounded by one deadline rather than one timeout per request.
+ *   timeoutMs: The probe's configured timeout, quoted in the abort message only.
+ *
+ * Returns:
+ *   The status and parsed body, or a connection-error reason.
+ */
+async function getWithSignal(url, signal, timeoutMs) {
+    try {
+        const r = await fetch(url, { signal, redirect: "error" });
+        let body;
+        try {
+            body = await r.json();
+        }
+        catch {
+            body = undefined;
+        }
+        return { status: r.status, body };
+    }
+    catch (e) {
+        return { error: describeProbeError(e, timeoutMs) };
+    }
+}
+/**
+ * Splits a `CLAUDE_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:
+ *   baseUrl: The configured base URL.
+ *
+ * Returns:
+ *   The health root and the models base.
+ */
+function providerUrls(baseUrl) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    return trimmed.endsWith("/v1") ? { root: trimmed.slice(0, -"/v1".length), base: trimmed } : { root: trimmed, base: `${trimmed}/v1` };
+}
+/**
+ * Probes a local memory-provider server: `<root>/health` (200 expected), then `<base>/models`
+ * (the configured model id expected in `data[].id`), both requests bound by one
+ * `AbortController` armed once for `timeoutMs` — so a slow-but-live server cannot push the
+ * total probe time past the configured deadline by stacking a full timeout on each request.
+ * Down is a one-line reason, never a throw.
+ *
+ * Args:
+ *   baseUrl: `CLAUDE_MEM_LOCAL_BASE_URL`.
+ *   model: `CLAUDE_MEM_LOCAL_MODEL`.
+ *   timeoutMs: The whole probe's deadline (both requests together).
+ *
+ * Returns:
+ *   ok, or ok:false with a one-line reason.
+ */
+export async function probeMemoryProvider(baseUrl, model, timeoutMs = 3000) {
+    const { root, base } = providerUrls(baseUrl);
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+        const health = await getWithSignal(`${root}/health`, ctl.signal, timeoutMs);
+        if ("error" in health)
+            return { ok: false, reason: health.error };
+        if (health.status !== 200)
+            return { ok: false, reason: `health ${health.status}` };
+        const models = await getWithSignal(`${base}/models`, ctl.signal, timeoutMs);
+        if ("error" in models)
+            return { ok: false, reason: models.error };
+        const data = models.body?.data;
+        const ids = Array.isArray(data) ? data.map((d) => (typeof d.id === "string" ? d.id : undefined)).filter((id) => id !== undefined) : [];
+        if (!ids.includes(model))
+            return { ok: false, reason: `model ${model} not listed` };
+        return { ok: true };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 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
+ * the reason; absent or `claude` prints nothing.
+ *
+ * Args:
+ *   settingsPath: Path of the data dir's settings.json.
+ *   probe: Injectable probe function.
+ *
+ * Returns:
+ *   Zero or one printable line.
+ */
+export async function memoryProviderLines(settingsPath, probe = probeMemoryProvider) {
+    const values = readFlatSettings(settingsPath);
+    if (values.CLAUDE_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 r = await probe(baseUrl, model);
+    return [`${r.ok ? "OK  " : "WARN"} memory provider: ${baseUrl} ${model} ${r.ok ? "OK" : r.reason}`];
+}
+/** Resolve $CLAUDE_CONFIG_DIR or ~/.claude. */
+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). */
+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");
+    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);
+    }
+    catch {
+        /* default */
+    }
+    return def;
+}
+/** Mirror engine SettingsDefaultsManager: CLAUDE_MEM_WORKER_PORT or 37700 + uid % 100. */
+function workerPort(dir) {
+    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)
+            return p;
+    }
+    catch {
+        /* default */
+    }
+    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;
+        }
+    };
+    const health = await get("/api/health");
+    if (!health)
+        return { port, reachable: false };
+    let version;
+    try {
+        version = String((await health.json()).version ?? "");
+    }
+    catch {
+        /* non-JSON */
+    }
+    const root = await get("/");
+    let body = "";
+    try {
+        body = root ? await root.text() : "";
+    }
+    catch {
+        /* ignore */
+    }
+    const viewer = root?.status === 200;
+    const ours = root ? root.status === 404 || body.includes(VIEWER_MARKER) : undefined;
+    return { port, reachable: true, version, viewer, ours };
+}
+/**
+ * Lists cache versions under one plugin-cache root.
+ * @param root The `<cfg>/plugins/cache/<owner>/<name>` directory.
+ * @param legacy Whether `root` is the upstream (thedotmack/claude-mem) path.
+ * @returns One entry per version directory; empty when `root` is absent.
+ */
+function listCacheRoot(root, legacy) {
+    if (!fs.existsSync(root))
+        return [];
+    return fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && /^\d/.test(e.name))
+        .map((e) => {
+        const dir = path.join(root, e.name);
+        const skillsDir = path.join(dir, "skills");
+        const skills = fs.existsSync(skillsDir) ? fs.readdirSync(skillsDir).filter((s) => !s.startsWith(".")) : [];
+        return { version: e.name, dir, ours: fs.existsSync(path.join(dir, ".install-version")), skills, legacy };
+    });
+}
+/**
+ * Lists every plugin-cache version doctor knows to look for: our native cache
+ * (`<cfg>/plugins/cache/freeharness/free-mem`) and the upstream cache
+ * (`<cfg>/plugins/cache/thedotmack/claude-mem`), which after a migration holds either a
+ * previous FreeHarness build (pre-rename) or a genuine upstream install.
+ * @param cfg Claude config dir.
+ * @returns Native entries first, then legacy entries.
+ */
+function listCache(cfg) {
+    const nativeRoot = path.join(cfg, "plugins", "cache", MARKETPLACE_OWNER, PLUGIN_NAME);
+    const legacyRoot = path.join(cfg, "plugins", "cache", UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_NAME);
+    return [...listCacheRoot(nativeRoot, false), ...listCacheRoot(legacyRoot, true)];
+}
+/**
+ * Human-readable tag for one plugin-cache entry in the `doctor` cache table.
+ * @param c The cache entry.
+ * @returns One of: a native FreeHarness build, a legacy (pre-rename) FreeHarness build or
+ *   upstream install, or a foreign entry with no `.install-version` marker.
+ */
+function cacheTag(c) {
+    if (!c.ours)
+        return "UPSTREAM/foreign (no .install-version)";
+    if (c.legacy)
+        return "previous FreeHarness build or upstream (legacy thedotmack/claude-mem cache)";
+    return "FreeHarness build";
+}
+/**
+ * Diagnose which claude-mem is active.
+ *
+ * Returns:
+ *   A MemoryDiagnosis with a verdict and printable lines (OK/WARN prefixed).
+ */
+export async function diagnoseMemory() {
+    const cfg = configDir();
+    const data = dataDir();
+    const dbPath = path.join(data, "claude-mem.db");
+    const dbBytes = fs.existsSync(dbPath) ? fs.statSync(dbPath).size : 0;
+    const chromaPresent = fs.existsSync(path.join(data, "chroma"));
+    const cache = listCache(cfg);
+    const lines = [];
+    let activeInstallPath;
+    let activeVersion;
+    try {
+        const ip = JSON.parse(fs.readFileSync(path.join(cfg, "plugins", "installed_plugins.json"), "utf8"));
+        const entry = ip.plugins?.[PLUGIN_KEY]?.[0];
+        activeInstallPath = entry?.installPath;
+        activeVersion = entry?.version;
+    }
+    catch {
+        /* not registered */
+    }
+    const activeIsOurs = activeInstallPath ? fs.existsSync(path.join(activeInstallPath, ".install-version")) : undefined;
+    const worker = await probeWorker(workerPort(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)"}`);
+    }
+    if (cache.length === 0)
+        lines.push(`WARN no ${PLUGIN_NAME} plugin in the cache (run install.sh --with-memory)`);
+    if (activeInstallPath) {
+        lines.push(`${activeIsOurs ? "OK  " : "WARN"} ${PLUGIN_KEY} registered -> v${activeVersion} at ${activeInstallPath} (${activeIsOurs ? "ours" : "NOT ours"})`);
+    }
+    else {
+        lines.push(`WARN ${PLUGIN_KEY} not registered in installed_plugins.json`);
+    }
+    if (!worker.reachable) {
+        lines.push(`OK   no worker listening on :${worker.port} (next SessionStart starts the registered plugin's worker)`);
+    }
+    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"}`);
+        // 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) {
+            lines.push(`WARN worker on :${worker.port} runs ${worker.version} but the registered plugin is ${activeVersion} — run \`freeharness memory restart\``);
+        }
+    }
+    lines.push(...observerLines(observer));
+    const now = Date.now();
+    if (isObserverVerdictStale(observer.health, now)) {
+        const at = new Date(observer.health.lastErrorAt).toISOString();
+        lines.push(`INFO observer verdict stale: last failure ${at} (${describeDuration(now - observer.health.lastErrorAt)} ago), no warning injected`);
+    }
+    const models = effectiveObserverModels(path.join(data, "settings.json"));
+    const baseIsHaiku = isHaikuAlias(models.base);
+    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`"}`);
+    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);
+    // Only a machine with a batch log has locally answered rows to count; a Claude-only
+    // install would pay one sqlite3 spawn per status run for a guaranteed pair of zeros.
+    const duplicateStats = localLogSummary && !("reason" in localLogSummary)
+        ? 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`);
+    }
+    const foreign = cache.some((c) => !c.ours);
+    const upstreamWorker = worker.reachable && worker.ours !== true;
+    let verdict = "none";
+    if (cache.length > 0) {
+        if (activeIsOurs && !foreign && !upstreamWorker)
+            verdict = "ours";
+        else if (activeIsOurs === false && !cache.some((c) => c.ours))
+            verdict = "upstream";
+        else
+            verdict = "mixed";
+    }
+    lines.push(verdict === "ours"
+        ? "OK   VERDICT: the FreeHarness build is the only active memory plugin"
+        : verdict === "none"
+            ? "WARN VERDICT: memory plugin not installed"
+            : `WARN VERDICT: ${verdict === "upstream" ? "the UPSTREAM install is active" : "MIXED — upstream pieces still active beside ours"} (run: freeharness memory backup && freeharness memory activate)`);
+    return { configDir: cfg, dataDir: data, dbPath, dbBytes, chromaPresent, cache, activeInstallPath, activeVersion, activeIsOurs, worker, observer, verdict, lines };
+}
+/**
+ * Copy the claude-mem data dir to a timestamped sibling (never moves the original).
+ *
+ * Returns:
+ *   The backup directory path.
+ */
+export function backupMemoryData() {
+    const src = dataDir();
+    if (!fs.existsSync(src))
+        throw new Error(`data dir not found: ${src}`);
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const dest = `${src}-backup-${stamp}`;
+    fs.cpSync(src, dest, { recursive: true, filter: (p) => !/\/(logs|\.pid|.*\.lock)$/.test(p) });
+    return dest;
+}
+/**
+ * Restart the claude-mem worker of the registered FreeHarness build.
+ *
+ * Prefers the plugin's own launcher (`node <install>/scripts/bun-runner.js
+ * <install>/scripts/worker-service.cjs restart`, detached) so the new worker is the
+ * registered version; without a registered FreeHarness install it only asks a running
+ * worker to shut down (the next SessionStart hook respawns it). The observer ledgers are
+ * left alone: a restart does not clear an armed quota cooldown (that is by design in the
+ * engine; the breaker is persisted so restarts cannot reopen a request storm).
+ *
+ * Args:
+ *   dryRun: Report only.
+ *   diagnosis: A diagnosis already computed by the caller (a fresh one otherwise).
+ *
+ * Returns:
+ *   What was (or would be) done.
+ */
+export async function restartWorker(dryRun, diagnosis) {
+    const d = diagnosis ?? (await diagnoseMemory());
+    const install = d.activeIsOurs && d.activeInstallPath ? d.activeInstallPath : undefined;
+    const runner = install ? path.join(install, "scripts", "bun-runner.js") : undefined;
+    const service = install ? path.join(install, "scripts", "worker-service.cjs") : undefined;
+    if (runner && service && fs.existsSync(runner) && fs.existsSync(service)) {
+        const detail = `node ${runner} ${service} restart`;
+        if (!dryRun) {
+            const child = spawn(process.execPath, [runner, service, "restart"], { detached: true, stdio: "ignore", env: { ...process.env } });
+            child.unref();
+        }
+        return { method: "worker-service restart", detail };
+    }
+    if (d.worker.reachable) {
+        const url = `http://127.0.0.1:${d.worker.port}/api/admin/shutdown`;
+        if (!dryRun) {
+            try {
+                await fetch(url, { method: "POST", signal: AbortSignal.timeout(5000) });
+            }
+            catch {
+                /* it may exit before answering */
+            }
+        }
+        return { method: "shutdown-only", detail: `POST ${url}; the next Claude Code SessionStart respawns the registered plugin's worker` };
+    }
+    return { method: "nothing", detail: `no worker on :${d.worker.port} and no registered FreeHarness build to launch (run install.sh --with-memory)` };
+}
+/**
+ * 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.
+ *
+ * Args:
+ *   dryRun: Report only.
+ *
+ * Returns:
+ *   What was (or would be) done.
+ */
+export async function activateOurs(dryRun) {
+    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.
+    const ours = d.cache
+        .filter((c) => c.ours)
+        .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 };
+    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) });
+            res.stoppedWorker = true;
+        }
+        catch {
+            /* it may have exited before answering */
+            res.stoppedWorker = true;
+        }
+    }
+    else if (d.worker.reachable)
+        res.stoppedWorker = true;
+    // Foreign cache versions are always found under the upstream root (see `listCache`): a
+    // genuine upstream install registers itself there, and so does a pre-rename FreeHarness
+    // build. Parking keeps that same root, only appending `.disabled`.
+    const disabledRoot = path.join(d.configDir, "plugins", "cache", UPSTREAM_MARKETPLACE_OWNER, `${UPSTREAM_PLUGIN_NAME}.disabled`);
+    for (const c of d.cache.filter((x) => !x.ours)) {
+        const dest = path.join(disabledRoot, c.version);
+        if (!dryRun) {
+            fs.mkdirSync(disabledRoot, { recursive: true });
+            if (fs.existsSync(dest))
+                fs.rmSync(dest, { recursive: true, force: true });
+            fs.renameSync(c.dir, dest);
+        }
+        res.disabled.push(`${c.dir} -> ${dest}`);
+    }
+    const ipPath = path.join(d.configDir, "plugins", "installed_plugins.json");
+    if (!dryRun && fs.existsSync(ipPath)) {
+        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 }];
+        fs.writeFileSync(ipPath, JSON.stringify(ip, null, 2) + "\n");
+    }
+    res.registered = true;
+    return res;
+}