freeharness 0.4.2 → 0.4.3

package/dist/adapters/harness/claude-code.d.ts

@@ -38,6 +38,8 @@ export declare const QUOTA_TAP_SCRIPT = "freeharness-quota-tap.mjs";
 export declare const HOOK_SCRIPTS: readonly string[];
 export declare class ClaudeCodeAdapter implements HarnessPort {
     readonly target: "claude-code";
+    private readonly autoMemoryMerged;
+    private turnOffAutoMemoryOnce;
     apply(cap: Capability, ctx: InstallContext): Promise<AdapterResult>;
 }
 /**
@@ -46,6 +48,11 @@ export declare class ClaudeCodeAdapter implements HarnessPort {
  * test can hold both copies to the same answers.
  */
 export declare function freeMemEnabled(claudeDir: string): boolean;
+/**
+ * free-mem is the only memory owner; Claude Code auto memory (and agent memory with it) would
+ * keep a second store nothing recalls. Added only when absent, so an owner's explicit value wins.
+ */
+export declare function turnOffAutoMemory(settingsPath: string, dry: boolean, res: AdapterResult): void;
 /**
  * Reports and, only once confirmed, strips a trailing `[1m]` suffix from the scope's own
  * `model` value. The emitted defaults never force or replace a model family: a value with no

package/dist/adapters/harness/claude-code.js

@@ -83,6 +83,15 @@ export const HOOK_SCRIPTS = [
 ];
 export class ClaudeCodeAdapter {
     target = "claude-code";
+    // The runner keeps one adapter per pass, so a later capability case sees the key this pass
+    // already merged and would report it as the owner's value.
+    autoMemoryMerged = new Set();
+    turnOffAutoMemoryOnce(settingsPath, dry, res) {
+        if (this.autoMemoryMerged.has(settingsPath))
+            return;
+        this.autoMemoryMerged.add(settingsPath);
+        turnOffAutoMemory(settingsPath, dry, res);
+    }
     async apply(cap, ctx) {
         const res = { capabilityId: cap.id, target: this.target, written: [], actions: [], notes: [] };
         const C = ctx.canonicalDir;
@@ -104,9 +113,6 @@ export class ClaudeCodeAdapter {
         const hooksDir = user
             ? path.join(home, ".claude", "freeharness", "hooks")
             : path.join(ctx.projectRoot, ".freeharness", "hooks");
-        const safetyFile = user
-            ? path.join(home, ".claude", "freeharness", "safety.md")
-            : path.join(ctx.projectRoot, ".freeharness", "safety.md");
         const ssScript = path.join(hooksDir, "freeharness-session-start");
         const mgScript = path.join(hooksDir, "freeharness-memory-guard.mjs");
         // user scope bakes an absolute path; project scope uses ${CLAUDE_PROJECT_DIR}.
@@ -125,7 +131,7 @@ export class ClaudeCodeAdapter {
             : 'node "${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-cost-tracker.mjs"';
         const hookCmd = (script, flags) => `${user ? `node "${path.join(hooksDir, script)}"` : `node "\${CLAUDE_PROJECT_DIR}/.freeharness/hooks/${script}"`}${flags ? ` ${flags}` : ""}`;
         const mergeOwned = (event, entry, ownerKey) => ({ event, r: mergeClaudeHook(settingsPath, event, entry, dry, ownerKey) });
-        const mainNote = (script, cmd, merged, addedNote, presentNote, failClosed) => {
+        const mainNote = (script, cmd, merged, addedNote, presentNote, guard) => {
             const replaced = merged.flatMap((m) => (m.r.outcome === "replaced" ? [m.r] : []));
             const hasAdded = merged.some((m) => m.r.outcome === "added");
             if (replaced.length > 0) {
@@ -134,7 +140,7 @@ export class ClaudeCodeAdapter {
                     ? `Updated ${script} hook (flags changed: ${stale} -> ${cmd}). Update resets FreeHarness hook flags to the shipped values.`
                     : replaced.some((r) => r.onFailureChanged)
                         ? `Updated ${script} hook (onFailure reset to the shipped value).`
-                        : `Updated ${script} hook (collapsed duplicate ${failClosed ? "guard" : "hook"} entries).`;
+                        : `Updated ${script} hook (collapsed duplicate ${guard ? "guard" : "hook"} entries).`;
                 if (hasAdded)
                     return [updatedNote, addedNote];
                 return [updatedNote];
@@ -143,20 +149,19 @@ export class ClaudeCodeAdapter {
                 return [addedNote];
             return [presentNote];
         };
-        // A shared entry is never rewritten, so a guard copy there cannot gain onFailure block.
-        const hookNotes = (script, cmd, merged, addedNote, presentNote, failClosed = false) => {
-            const why = failClosed ? " That copy runs without fail-closed (no onFailure block): if it cannot run, the tool call proceeds unjudged." : "";
-            const shared = merged.filter((m) => m.r.hasSharedCopy).map((m) => `${script} also runs inside a hook entry shared with other commands in ${m.event}; remove it there by hand.${why}`);
-            return [...mainNote(script, cmd, merged, addedNote, presentNote, failClosed), ...shared];
+        // A shared entry is never rewritten, so the owner removes that copy by hand.
+        const hookNotes = (script, cmd, merged, addedNote, presentNote, guard = false) => {
+            const shared = merged.filter((m) => m.r.hasSharedCopy).map((m) => `${script} also runs inside a hook entry shared with other commands in ${m.event}; remove it there by hand.`);
+            return [...mainNote(script, cmd, merged, addedNote, presentNote, guard), ...shared];
         };
-        const emitHook = (script, flags, events, note, failClosed = false) => {
+        const emitHook = (script, flags, events, note, guard = false) => {
             res.written.push(writeText(path.join(hooksDir, script), readText(path.join(C, "hooks", script)), dry));
             const cmd = hookCmd(script, flags);
             const merged = events.map((e) => {
-                const hook = { type: "command", command: cmd, ...(e.event === "SessionEnd" || e.event === "SubagentStop" ? { timeout: SESSION_END_TIMEOUT_S } : {}), ...(failClosed ? { onFailure: "block" } : {}) };
+                const hook = { type: "command", command: cmd, ...(e.event === "SessionEnd" || e.event === "SubagentStop" ? { timeout: SESSION_END_TIMEOUT_S } : {}) };
                 return mergeOwned(e.event, { ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [hook] }, hookCmd(script, ""));
             });
-            res.notes.push(...hookNotes(script, cmd, merged, `Added ${note}.`, `${script} hook already present.`, failClosed));
+            res.notes.push(...hookNotes(script, cmd, merged, `Added ${note}.`, `${script} hook already present.`, guard));
         };
         switch (cap.id) {
             case "rules": {
@@ -192,8 +197,8 @@ export class ClaudeCodeAdapter {
                 // Routing table beside the script the hook reads it from.
                 res.written.push(writeText(path.join(hooksDir, ROUTING_FILE), readText(routingSourcePath(C)), dry));
                 res.written.push(writeText(mgScript, readText(path.join(C, "hooks", "freeharness-memory-guard.mjs")), dry));
-                // The guards fail closed: a guard that cannot run blocks the call instead of passing it.
-                const mgEntry = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: mgCmd, onFailure: "block" }] };
+                // The guards sit under the permission layer, so a guard that cannot run allows the call.
+                const mgEntry = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: mgCmd }] };
                 const mg = mergeOwned("PreToolUse", mgEntry, mgCmd);
                 res.notes.push(...hookNotes("freeharness-memory-guard.mjs", mgCmd, [mg], "Added memory-guard hook (PreToolUse denies memory .md writes; saves tokens).", "Memory-guard hook already present.", true));
                 emitHook("freeharness-config-guard.mjs", CONFIG_GUARD_FLAGS, [{ event: "PreToolUse", matcher: "Edit|Write|MultiEdit|Bash" }], `config-guard hook (PreToolUse denies edits to live configuration by location: settings in a .claude directory, .mcp.json, the user .claude.json and CLAUDE.md, hook directories and the plugin tree, unless an allow marker from the last ${CONFIG_GUARD_TTL_MIN} minutes is present)`, true);
@@ -202,7 +207,7 @@ export class ClaudeCodeAdapter {
                 emitHook("freeharness-precompact.mjs", "", [{ event: "PreCompact" }], "precompact hook (PreCompact writes the checkpoint skeleton + file-op list for SessionStart and asks a running memory worker for a summary; worker down = skipped)");
                 emitHook("freeharness-reload-context.mjs", "", [{ event: "UserPromptSubmit" }], "reload-context hook (UserPromptSubmit answers the exact prompt `reload context` with the newest saved handoff or PreCompact skeleton; other prompts untouched)");
                 if (user && freeMemEnabled(claudeDir))
-                    turnOffAutoMemory(settingsPath, dry, res);
+                    this.turnOffAutoMemoryOnce(settingsPath, dry, res);
                 break;
             }
             case "skills": {
@@ -233,7 +238,6 @@ export class ClaudeCodeAdapter {
                 }));
                 break;
             case "safety": {
-                res.written.push(writeText(safetyFile, readText(path.join(C, "rules", "safety.md")), dry));
                 // Advisory PreToolUse hook: warns on vulnerability sinks in Edit/Write content,
                 // never blocks. Same additive merge as the memory guard.
                 res.written.push(writeText(sgScript, readText(path.join(C, "hooks", "freeharness-security-guidance.mjs")), dry));
@@ -315,7 +319,7 @@ export class ClaudeCodeAdapter {
                 merge(await mem.registerHooks(ctx.scope, ctx));
                 // Registering enables free-mem, so the key follows in the same run; pass 1 previews it.
                 if (user)
-                    turnOffAutoMemory(settingsPath, dry, res);
+                    this.turnOffAutoMemoryOnce(settingsPath, dry, res);
                 res.notes.push("Worker start + recall are verified on the machine (needs the Claude Agent SDK key / network); not exercised by the installer.");
                 break;
             }
@@ -327,7 +331,8 @@ export class ClaudeCodeAdapter {
                         continue;
                     res.actions.push({
                         description: `Register MCP server ${s.name}${s.optional ? " (optional)" : ""}`,
-                        command: `claude mcp add ${s.name} -s ${sc} -- ${s.command} ${s.args.join(" ")}`,
+                        // `claude mcp add` exits 1 for a registered name; the get guard keeps a re-run quiet.
+                        command: `claude mcp get ${s.name} >/dev/null 2>&1 || claude mcp add ${s.name} -s ${sc} -- ${s.command} ${s.args.join(" ")}`,
                         optional: true, // a failing/missing `claude` must not abort the whole install
                     });
                 }
@@ -384,13 +389,14 @@ export function freeMemEnabled(claudeDir) {
  * free-mem is the only memory owner; Claude Code auto memory (and agent memory with it) would
  * keep a second store nothing recalls. Added only when absent, so an owner's explicit value wins.
  */
-function turnOffAutoMemory(settingsPath, dry, res) {
+export function turnOffAutoMemory(settingsPath, dry, res) {
     let merged;
     try {
         merged = mergeSettingsKeys(settingsPath, { autoMemoryEnabled: false }, dry);
     }
     catch (e) {
-        res.notes.push(`autoMemoryEnabled not set: ${settingsPath} not parsed (${e instanceof Error ? e.message : String(e)}).`);
+        const reason = e instanceof SyntaxError ? "not parsed" : "not updated";
+        res.notes.push(`autoMemoryEnabled not set: ${settingsPath} ${reason} (${e instanceof Error ? e.message : String(e)}).`);
         return;
     }
     if (merged.added.length > 0) {

package/dist/adapters/harness/opencode.js

@@ -108,7 +108,7 @@ export class OpenCodeAdapter {
                 break;
             }
             case "safety":
-                res.written.push(writeText(path.join(P, ".freeharness", "safety.md"), readText(path.join(C, "rules", "safety.md")), dry));
+                res.notes.push("safety: OpenCode has no hook contract FreeHarness emits to; nothing emitted.");
                 break;
             case "sdd": {
                 const src = path.join(C, "openspec");

package/dist/adapters/harness/plugin.js

@@ -17,7 +17,7 @@ export const MARKETPLACE_NAME = "freeharness-local";
 /**
  * Additively merges a hook entry into the plugin's hooks.json (dedupe by command; the file is
  * created with the official `description` + `hooks` shape). Entries running only this command
- * fold into the first one, rewritten to the current entry, so a re-emit gains the fail-closed
+ * fold into the first one, rewritten to the current entry, so a re-emit drops a stale `onFailure`
  * field and a stale copy never keeps running beside a current one; an entry mixing it with other
  * commands is left as is.
  * @param file Absolute path of hooks/hooks.json.
@@ -68,10 +68,10 @@ export class PluginAdapter {
         const hooksFile = path.join(hooksDir, "hooks.json");
         const hookCmd = (script, runner = "node", flags = "") => `${runner} "\${CLAUDE_PLUGIN_ROOT}/hooks/${script}"${flags ? ` ${flags}` : ""}`;
         /** Copies a canonical hook script and registers it under each event (dedupe by command). */
-        const emitHook = (script, flags, events, failClosed = false) => {
+        const emitHook = (script, flags, events) => {
             res.written.push(writeText(path.join(hooksDir, script), readText(path.join(C, "hooks", script)), dry));
             for (const e of events) {
-                const hook = { type: "command", command: hookCmd(script, "node", flags), ...(e.event === "SessionEnd" || e.event === "SubagentStop" ? { timeout: SESSION_END_TIMEOUT_S } : {}), ...(failClosed ? { onFailure: "block" } : {}) };
+                const hook = { type: "command", command: hookCmd(script, "node", flags), ...(e.event === "SessionEnd" || e.event === "SubagentStop" ? { timeout: SESSION_END_TIMEOUT_S } : {}) };
                 const entry = { ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [hook] };
                 mergePluginHook(hooksFile, e.event, entry, dry);
             }
@@ -91,10 +91,10 @@ export class PluginAdapter {
                 // it from its own directory regardless of which target installed it.
                 res.written.push(writeText(path.join(hooksDir, ROUTING_FILE), readText(routingSourcePath(C)), dry));
                 res.written.push(writeText(path.join(hooksDir, "freeharness-memory-guard.mjs"), readText(path.join(C, "hooks", "freeharness-memory-guard.mjs")), dry));
-                // The guards fail closed: a guard that cannot run blocks the call instead of passing it.
-                const mg = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: hookCmd("freeharness-memory-guard.mjs"), onFailure: "block" }] };
+                // The guards sit under the permission layer, so a guard that cannot run allows the call.
+                const mg = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: hookCmd("freeharness-memory-guard.mjs") }] };
                 mergePluginHook(hooksFile, "PreToolUse", mg, dry);
-                emitHook("freeharness-config-guard.mjs", CONFIG_GUARD_FLAGS, [{ event: "PreToolUse", matcher: "Edit|Write|MultiEdit|Bash" }], true);
+                emitHook("freeharness-config-guard.mjs", CONFIG_GUARD_FLAGS, [{ event: "PreToolUse", matcher: "Edit|Write|MultiEdit|Bash" }]);
                 emitHook("freeharness-repeat-tool.mjs", REPEAT_TOOL_FLAGS, [{ event: "PreToolUse" }, { event: "UserPromptSubmit" }]);
                 emitHook("freeharness-precompact.mjs", "", [{ event: "PreCompact" }]);
                 emitHook("freeharness-reload-context.mjs", "", [{ event: "UserPromptSubmit" }]);
@@ -116,7 +116,7 @@ export class PluginAdapter {
                 }));
                 break;
             case "safety": {
-                res.notes.push("safety: rules/safety.md is a rules file (not a plugin component); only the advisory security-guidance hook ships in the plugin.");
+                res.notes.push("safety: the advisory security-guidance hook ships in the plugin.");
                 res.written.push(writeText(path.join(hooksDir, "freeharness-security-guidance.mjs"), readText(path.join(C, "hooks", "freeharness-security-guidance.mjs")), dry));
                 const sg = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: hookCmd("freeharness-security-guidance.mjs") }] };
                 mergePluginHook(hooksFile, "PreToolUse", sg, dry);
@@ -256,8 +256,8 @@ its agents, skills, and hooks.
 
 ## What is not in the plugin
 
-- Behavior rules (\`CLAUDE.md\`) and \`safety.md\`: not plugin components. Install them per user with
-  \`freeharness init --scope user --only rules,safety\`.
+- Behavior rules (\`CLAUDE.md\`): not a plugin component. Install them per user with
+  \`freeharness init --scope user --only rules\`. The security-guidance hook ships in the plugin.
 - SDD (OpenSpec \`/opsx\`): per-project init, \`freeharness bootstrap\` inside the project.
 - Memory (free-mem): its own plugin, \`freeharness init --scope user --only memory\`.
 - Report-formatting runtime deps: after install run \`npm install\` in

package/dist/adapters/memory/doctor.d.ts

@@ -1,14 +1,14 @@
 import { spawnSync } from "node:child_process";
 import { type StageResult } from "./vendored.js";
 import { type MemoryPaths } from "./paths.js";
-import { type StopResult } from "./migrate.js";
+import { type StopResult } from "./worker-control.js";
 export interface CacheVersion {
     version: string;
     dir: string;
     ours: boolean;
     skills: string[];
-    /** Found under the upstream (thedotmack/claude-mem) cache root: a previous FreeHarness
-     * build (pre-rename) or a genuine upstream install, never our current native path. */
+    /** Found under the upstream (thedotmack/claude-mem) cache root: a pre-rename FreeHarness
+     * build or an upstream install, never our native path. */
     legacy: boolean;
 }
 /** What the foreign responder said about itself, already filtered for printing. */
@@ -153,8 +153,7 @@ export declare const OUR_SCHEMA_VERSION = 49;
  * 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.
+ * version; a store with none was never opened by a FreeHarness worker and keeps the upstream verdict.
  *
  * Returns:
  *   The line, or null when the db/sqlite3 is unavailable.
@@ -189,8 +188,7 @@ export interface SpendUnavailable {
  *
  * 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.
+ *   spawn: Injectable spawnSync, so a test of the missing-binary path does not depend on sqlite3 being on PATH.
  *
  * Returns:
  *   One row per (window, model) with a row, or the reason spend could not be read.
@@ -494,21 +492,17 @@ export declare function configDir(): string;
 /** The engine's data directory and database for this process. */
 export declare function memoryPaths(): MemoryPaths;
 export declare function dataDir(): string;
-/**
- * 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.
- */
+/** One WARN per ignored `CLAUDE_MEM_*` variable in `env` and key in the settings file, naming its replacement. */
 export declare function deprecatedNameLines(env: Record<string, string | undefined>, settingsPath: string): string[];
-/**
- * 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 declare function legacyWriteLines(home: string): string[];
+/** A WARN while a legacy database sits beside a free-mem store with no observation: the worker creates
+ *  an empty store at its first start, so existence cannot silence it; an unreadable store stays silent. */
+export declare function legacyHomeLines(env: Record<string, string | undefined>, home: string, spawn?: SpawnSyncFn): string[];
 /** Engine worker port: env, then settings.json, then 37700 + uid % 100. */
 export declare function workerPort(dir: string): number;
 /** One WARN while the upstream plugin is still registered: both workers bind the same port. */
 export declare function upstreamLines(cfg: string, port: number): string[];
+/** Steps that clear a reachable foreign worker, else null; no-pid fallback as in foreignWorkerLine. */
+export declare function foreignWorkerStep(worker: WorkerProbe): string | null;
 /**
  * Diagnose which claude-mem is active.
  *

package/dist/adapters/memory/doctor.js

@@ -1,7 +1,7 @@
 // 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):
+// Evidence used:
 //   - 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, ...).
@@ -9,30 +9,26 @@
 //   - 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.
+//   - the data dir (resolveMemoryPaths in ./paths.ts): the database (a leftover
+//     chroma/ is only sized and
+//     reported, never touched) and the engine's observer ledgers, which `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_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 { LEGACY_DIR_NAME, readMemorySettings, resolveMemoryPaths } from "./paths.js";
+import { pidFileLive } from "./worker-control.js";
 import { resolveCanonicalDir, sourceRepoRoot } from "../../infra/paths.js";
 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. */
+/** FREE_MEM_ names only, as the engine reads them (CLAUDE_MEM_ twins are ignored); an empty value is unset. */
 function envSetting(env, key) {
-    return env[key] || env[legacyName(key)] || undefined;
+    return env[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";
@@ -218,8 +214,7 @@ function dbSchemaVersions(dbPath) {
  * 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.
+ * version; a store with none was never opened by a FreeHarness worker and keeps the upstream verdict.
  *
  * Returns:
  *   The line, or null when the db/sqlite3 is unavailable.
@@ -256,8 +251,7 @@ const MISSING_CONSOLIDATION_TABLE = /no such table: (?:main\.)?consolidation_(?:
  *
  * 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.
+ *   spawn: Injectable spawnSync, so a test of the missing-binary path does not depend on sqlite3 being on PATH.
  *
  * Returns:
  *   One row per (window, model) with a row, or the reason spend could not be read.
@@ -822,9 +816,9 @@ 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(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 base = str(file.FREE_MEM_MODEL, defaults.base);
+    const simple = str(file.FREE_MEM_TIER_SIMPLE_MODEL, defaults.simple);
+    const summaryValue = 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 };
@@ -846,9 +840,9 @@ const ENGINE_LOCAL_MODEL_DEFAULT = "local-model";
  */
 export function effectiveObserverProvider(settingsPath) {
     const values = readFlatSettings(settingsPath);
-    if (setting(values, "FREE_MEM_PROVIDER") !== "local")
+    if (values.FREE_MEM_PROVIDER !== "local")
         return { provider: "claude", model: null };
-    const raw = setting(values, "FREE_MEM_LOCAL_MODEL");
+    const raw = values.FREE_MEM_LOCAL_MODEL;
     return { provider: "local", model: typeof raw === "string" && raw.length > 0 ? raw : ENGINE_LOCAL_MODEL_DEFAULT };
 }
 /**
@@ -991,7 +985,7 @@ export function previewObserverSettings(settingsPath, opts) {
         }
     }
     const rows = Object.entries(keySet).map(([key, recommended]) => {
-        const raw = setting(values, key);
+        const raw = values[key];
         const current = raw === undefined ? undefined : typeof raw === "string" ? raw : JSON.stringify(raw);
         return { key, current, recommended, changed: current !== recommended };
     });
@@ -1156,12 +1150,12 @@ export async function probeMemoryProvider(baseUrl, model, timeoutMs = 3000) {
  */
 export async function memoryProviderLines(settingsPath, probe = probeMemoryProvider) {
     const values = readFlatSettings(settingsPath);
-    if (setting(values, "FREE_MEM_PROVIDER") !== "local")
+    if (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 configured = (key, fallback) => {
-        const v = setting(values, key);
+        const v = values[key];
         return typeof v === "string" && v.trim() !== "" ? v : fallback;
     };
     const baseUrl = configured("FREE_MEM_LOCAL_BASE_URL", ENGINE_LOCAL_BASE_URL_DEFAULT);
@@ -1180,52 +1174,33 @@ export function memoryPaths() {
 export function dataDir() {
     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.
- */
+/** One WARN per ignored `CLAUDE_MEM_*` variable in `env` and key in the settings file, naming its replacement. */
 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 replacement = (k) => NEW_PREFIX + k.slice(OLD_PREFIX.length);
+    const vars = Object.keys(env).filter((k) => k.startsWith(OLD_PREFIX) && env[k] !== undefined).sort();
     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;
+    return [
+        ...vars.map((k) => `WARN environment variable ${k} is ignored; set ${replacement(k)} instead`),
+        ...keys.map((k) => `WARN settings key ${k} in ${settingsPath} is ignored; rename it to ${replacement(k)}`),
+    ];
 }
-/**
- * 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;
+/** A WARN while a legacy database sits beside a free-mem store with no observation: the worker creates
+ *  an empty store at its first start, so existence cannot silence it; an unreadable store stays silent. */
+export function legacyHomeLines(env, home, spawn = spawnSync) {
+    const legacyDir = path.join(home, LEGACY_DIR_NAME);
+    if (env.FREE_MEM_DATA_DIR || fs.statSync(path.join(legacyDir, "claude-mem.db"), { throwIfNoEntry: false })?.isFile() !== true)
+        return [];
+    const { dataDir: freeDir, dbFile } = resolveMemoryPaths(env, home);
+    const warn = [`WARN legacy memory directory ${legacyDir} is not read; free-mem uses ${freeDir}, which holds no observation yet: copy the data by hand to keep the old memories`];
+    if (!fs.existsSync(dbFile))
+        return warn;
     try {
-        marker = JSON.parse(fs.readFileSync(path.join(freeDir, ".migrated-from.json"), "utf8"));
+        const r = spawn("sqlite3", ["-readonly", dbFile, "SELECT COUNT(*) FROM observations;"], { encoding: "utf8", timeout: 2000 });
+        return !r.error && r.status === 0 && String(r.stdout).trim() === "0" ? warn : [];
     }
     catch {
         return [];
     }
-    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}`];
 }
 /** Leading decimal integer, as the engine's parseInt reads it, when in 1..65535. */
 function validPort(value) {
@@ -1240,7 +1215,7 @@ export function workerPort(dir) {
     try {
         const raw = JSON.parse(fs.readFileSync(path.join(dir, "settings.json"), "utf8"));
         const s = raw.env ?? raw;
-        const p = validPort(setting(s, "FREE_MEM_WORKER_PORT"));
+        const p = validPort(s.FREE_MEM_WORKER_PORT);
         if (p !== null)
             return p;
     }
@@ -1323,6 +1298,14 @@ function foreignWorkerLine(port, facts) {
     }
     return `FAIL worker on :${port} is another program (${where}, version ${version}); memory is off — stop the program listening on port ${port} and ${cleanup}`;
 }
+/** Steps that clear a reachable foreign worker, else null; no-pid fallback as in foreignWorkerLine. */
+export function foreignWorkerStep(worker) {
+    if (!worker.reachable || worker.identity !== "foreign")
+        return null;
+    const pid = worker.foreign?.pid;
+    const stop = pid !== undefined ? `kill ${pid}` : `stop the program listening on port ${worker.port}`;
+    return `${stop}, then freeharness cleanup --scope user`;
+}
 async function probeWorker(port, dir) {
     let res;
     try {
@@ -1401,7 +1384,7 @@ function cacheTag(c) {
     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. */
+/** A size for the report only: symlinks are not followed and the walk is capped, so a huge tree yields a lower bound. */
 function treeBytes(dir) {
     let bytes = 0;
     let seen = 0;
@@ -1505,7 +1488,7 @@ export async function diagnoseMemory() {
     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");
+    const skipRaw = 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));
@@ -1529,7 +1512,7 @@ export async function diagnoseMemory() {
         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()));
+    lines.push(...legacyHomeLines(process.env, os.homedir()));
     const schemaLine = schemaVersionLine(dbPath, dbName);
     if (schemaLine !== null)
         lines.push(schemaLine);
@@ -1544,11 +1527,15 @@ export async function diagnoseMemory() {
         else
             verdict = "mixed";
     }
+    // `memory activate` cannot clear a foreign worker beside our build; the upstream verdict keeps the backup-and-activate advice.
+    const foreignStep = verdict === "mixed" ? foreignWorkerStep(worker) : null;
     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)`);
+            : foreignStep !== null
+                ? `WARN VERDICT: MIXED — a foreign worker holds the memory port (see the FAIL line: ${foreignStep})`
+                : `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 };
 }
 /**

package/dist/adapters/memory/paths.d.ts

@@ -1,22 +1,15 @@
-export type MemoryPathSource = "FREE_MEM_DATA_DIR" | "CLAUDE_MEM_DATA_DIR" | "settings" | "default" | "fallback";
+export type MemoryPathSource = "FREE_MEM_DATA_DIR" | "settings" | "default";
 export interface MemoryPaths {
     dataDir: string;
     /** Absolute path of the database the engine opens in `dataDir`. */
     dbFile: string;
-    /** True when `dataDir` is `<home>/.claude-mem`. */
-    legacy: boolean;
     source: MemoryPathSource;
 }
 export declare const FREE_DIR_NAME = ".free-mem";
+/** The pre-rename data directory: never read, only kept protected and named by doctor. */
 export declare const LEGACY_DIR_NAME = ".claude-mem";
 export declare const DB_FILENAME = "free-mem.db";
-export declare const LEGACY_DB_FILENAME = "claude-mem.db";
 /** A settings file's keys as the engine reads them (BOM dropped, `env` first); null when unreadable. */
 export declare function readMemorySettings(settingsPath: string): Record<string, unknown> | null;
-/**
- * Resolves the memory data directory and database from `env` and `home` alone, never from
- * process globals, so callers and tests can pass fake values.
- * @param env Environment to read `FREE_MEM_DATA_DIR` and `CLAUDE_MEM_DATA_DIR` from.
- * @param home Home directory that holds `.free-mem` and `.claude-mem` and expands `~`.
- */
+/** The data directory and database from `env` and `home` alone, never process globals, so tests pass fakes. */
 export declare function resolveMemoryPaths(env: Record<string, string | undefined>, home: string): MemoryPaths;