@gamaze/hicortex 0.20.3 → 0.20.5

package/dist/claude-desktop.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Claude Desktop auto-configuration (#381) — the init-side writer for the
+ * `claude_desktop_config.json` MCP entry.
+ *
+ * Claude Desktop's ONLY stdio MCP route is this hand-edited file (no CLI, no
+ * plugin discovery), which is why Desktop never had an init step while CC
+ * (`claude mcp add`), Pi, and opencode (dropped extension files) did. The
+ * 0.20.4 `hicortex mcp` stdio bridge makes such an entry meaningful, so init
+ * now offers to write it — the same auto-detect pattern as the other
+ * harnesses, gated on the Claude Desktop config DIRECTORY existing (the
+ * config FILE may not exist yet; creating it fresh is in scope).
+ *
+ * Two properties dominate the design:
+ *
+ *   1. IT IS ANOTHER APP'S FILE. `claude_desktop_config.json` is owned by
+ *      Claude Desktop and carries the user's other servers and app settings.
+ *      The write is therefore merge-safe (preserve EVERY top-level key and
+ *      every other server; touch only `mcpServers.hicortex`), takes a
+ *      timestamped `.bak` copy of the existing file first, lands via
+ *      tmp-write + JSON-validate + rename in the same directory (atomic),
+ *      and REFUSES — touching nothing, not even a backup — when the existing
+ *      file is not valid JSON. Unlike our own config.json there is no repair
+ *      flow here (quarantening another app's config would break IT); the
+ *      user fixes the file by hand with the snippet init prints.
+ *
+ *   2. THE COMMAND MUST BE AN ABSOLUTE NPX PATH. Desktop is a GUI app and
+ *      does not inherit the shell PATH — a bare "npx" command is the #1
+ *      Desktop MCP failure mode. Resolution walks PATH plus the common
+ *      install locations and rejects npm's ephemeral `/_npx/` cache (#176: a
+ *      path that dies on the next cache GC — the entry would break silently
+ *      weeks later). Unresolvable → manual instructions, nothing written.
+ *      Windows .cmd shims cannot be spawned by Electron without a shell, so
+ *      they are wrapped in `cmd /c`.
+ *
+ * Every helper is pure/parametrised (platform/env/home/exists injected) so
+ * the suite covers darwin/win32/linux without touching a real machine. This
+ * module deliberately imports NOTHING from init.ts (init imports this — no
+ * cycle); the package spec is passed in from init's getPackageSpec().
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.desktopConfigDir = desktopConfigDir;
+exports.resolveDesktopNpxPath = resolveDesktopNpxPath;
+exports.buildDesktopServerEntry = buildDesktopServerEntry;
+exports.isLocalServerUrl = isLocalServerUrl;
+exports.mergeDesktopServerConfig = mergeDesktopServerConfig;
+exports.writeDesktopServerConfig = writeDesktopServerConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const node_crypto_1 = require("node:crypto");
+// ---------------------------------------------------------------------------
+// Config-dir detection
+// ---------------------------------------------------------------------------
+/**
+ * The Claude Desktop config directory for this platform, or null where no
+ * Desktop build exists (Linux → silent skip). Parametrised so tests cover
+ * the platform matrix without a real machine. Detection in init is
+ * `desktopConfigDir() !== null && existsSync(dir)` — the config FILE itself
+ * may legitimately not exist yet.
+ */
+function desktopConfigDir(platform = (0, node_os_1.platform)(), env = process.env, home = (0, node_os_1.homedir)()) {
+    if (platform === "darwin") {
+        return (0, node_path_1.join)(home, "Library", "Application Support", "Claude");
+    }
+    if (platform === "win32") {
+        // %APPDATA% is the documented location; the AppData\Roaming fallback
+        // covers shells/services where the env var is not exported.
+        return (0, node_path_1.join)(env.APPDATA ?? (0, node_path_1.join)(home, "AppData", "Roaming"), "Claude");
+    }
+    return null;
+}
+/**
+ * Candidate npx paths in resolution order: every PATH dir first, then the
+ * common install locations. On win32 each dir contributes `npx.cmd` before
+ * `npx.exe` (the cmd shim is what npm actually installs there).
+ */
+function candidateNpxPaths(platform, pathEnv, home, env) {
+    const names = platform === "win32" ? ["npx.cmd", "npx.exe"] : ["npx"];
+    const delimiter = platform === "win32" ? ";" : ":";
+    const pathDirs = pathEnv.split(delimiter).filter(Boolean);
+    const commonDirs = platform === "win32"
+        ? [
+            // The npm global bin dir (%APPDATA%\npm) and the Node installer's
+            // dir — where a GUI-launched Desktop is most likely to find npx
+            // even when PATH (a shell concept) carries nothing useful.
+            (0, node_path_1.join)(env.APPDATA ?? (0, node_path_1.join)(home, "AppData", "Roaming"), "npm"),
+            "C:\\Program Files\\nodejs",
+        ]
+        : [
+            "/opt/homebrew/bin",
+            "/usr/local/bin",
+            (0, node_path_1.join)(home, ".npm-global", "bin"),
+            (0, node_path_1.join)(home, ".volta", "bin"),
+        ];
+    return [...pathDirs, ...commonDirs].flatMap((dir) => names.map((name) => (0, node_path_1.join)(dir, name)));
+}
+/**
+ * Resolve an ABSOLUTE npx path for the Desktop entry, or null when nothing
+ * durable exists (init then prints manual instructions and writes nothing).
+ * Rejects npm's ephemeral npx cache in BOTH separator spellings — unix
+ * `/_npx/` and Windows `\_npx\` — a bare includes("/_npx/") would let the
+ * win32 form through (#176: the path dies on the next cache GC).
+ */
+function resolveDesktopNpxPath(options = {}) {
+    const platform = options.platform ?? (0, node_os_1.platform)();
+    const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
+    const home = options.home ?? (0, node_os_1.homedir)();
+    const env = options.env ?? process.env;
+    const exists = options.exists ?? node_fs_1.existsSync;
+    for (const candidate of candidateNpxPaths(platform, pathEnv, home, env)) {
+        if (candidate.includes("/_npx/") || candidate.includes("\\_npx\\"))
+            continue;
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Build the stdio entry for the `hicortex mcp` bridge. NO "type" field —
+ * stdio is implied for Desktop entries (the CC `.claude.json` writer needs
+ * `"type":"sse"`; this is the other shape). A `.cmd`/`.bat` shim is wrapped
+ * in `cmd /c` because Electron spawns without a shell and cannot exec a cmd
+ * script directly. An empty/absent env omits the key entirely — a local
+ * entry must carry no env (the bridge autostarts the daemon; loopback
+ * bypasses auth).
+ */
+function buildDesktopServerEntry(npxPath, packageSpec, env) {
+    const entry = /\.(cmd|bat)$/i.test(npxPath)
+        ? { command: "cmd", args: ["/c", npxPath, "-y", packageSpec, "mcp"] }
+        : { command: npxPath, args: ["-y", packageSpec, "mcp"] };
+    if (env && Object.keys(env).length > 0)
+        entry.env = { ...env };
+    return entry;
+}
+/**
+ * Loopback check for a server URL — decides whether the Desktop entry needs
+ * an env block at all (local: none, the bridge resolves + autostarts the
+ * daemon; remote: URL + token). Mirrors mcp-stdio's isLoopbackHost (kept
+ * local rather than imported to avoid dragging the SDK into init's graph).
+ * An unparseable URL is NOT local — fail toward carrying the env, which
+ * still works everywhere the URL is real.
+ */
+function isLocalServerUrl(url) {
+    try {
+        const hostname = new URL(url).hostname.toLowerCase();
+        return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse the existing config text and merge our entry in, preserving every
+ * top-level key and every other server. `rawText === null` means "no file"
+ * (fresh install — a config containing only our entry is created). Malformed
+ * JSON, a non-object document, or a non-object `mcpServers` value returns
+ * `{ ok: false }` — the caller refuses to write, so the ORIGINAL file and
+ * its bytes are what the user keeps.
+ */
+function mergeDesktopServerConfig(rawText, entry) {
+    if (rawText === null) {
+        return { ok: true, config: { mcpServers: { hicortex: entry } } };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: `the file is not valid JSON (${e instanceof Error ? e.message : String(e)}) — ` +
+                `fix it by hand and re-run init`,
+        };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        const kind = parsed === null ? "null" : Array.isArray(parsed) ? "an array" : typeof parsed;
+        return { ok: false, reason: `the file parses to ${kind}, not a JSON object — fix it by hand and re-run init` };
+    }
+    const config = { ...parsed };
+    const existing = config.mcpServers;
+    if (existing !== undefined && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+        const kind = Array.isArray(existing) ? "an array" : typeof existing;
+        return { ok: false, reason: `"mcpServers" is ${kind}, not an object — fix it by hand and re-run init` };
+    }
+    config.mcpServers = { ...existing, hicortex: entry };
+    return { ok: true, config };
+}
+/**
+ * Orchestrate the merge-safe, atomic write of our entry into
+ * `claude_desktop_config.json`:
+ *
+ *   1. Read the existing file (ENOENT → fresh-install path).
+ *   2. Merge; a malformed/shape-refused file → `{ status: "refused" }` with
+ *      NOTHING touched — no backup, no tmp, no bytes changed.
+ *   3. Copy the existing file to `<path>.bak-<ISO-colons-stripped>` BEFORE
+ *      writing (the quarantineMalformedConfig naming convention).
+ *   4. Write the serialized payload to a tmp file in the SAME directory
+ *      (same filesystem → the rename is atomic), JSON-parse the exact bytes
+ *      that landed on disk, then renameSync over the target.
+ *
+ * Any unexpected I/O error returns `{ status: "failed" }` after removing the
+ * tmp file — a half-written tmp must never masquerade as a config. Never
+ * throws; the init wiring turns every non-"written" result into a printed
+ * warning and init continues.
+ */
+function writeDesktopServerConfig(configPath, entry) {
+    // 1. Read — only a genuinely-absent file (ENOENT) is a fresh install.
+    let raw = null;
+    try {
+        raw = (0, node_fs_1.readFileSync)(configPath, "utf-8");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT") {
+            return { status: "failed", reason: `could not read ${configPath}: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    // 2. Merge — refusal happens BEFORE any disk mutation (step 3+).
+    const merged = mergeDesktopServerConfig(raw, entry);
+    if (!merged.ok) {
+        return { status: "refused", reason: `Refusing to write ${configPath}: ${merged.reason}` };
+    }
+    const payload = JSON.stringify(merged.config, null, 2);
+    let tmpPath;
+    try {
+        const dir = (0, node_path_1.dirname)(configPath);
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        // 3. Backup the existing file BEFORE any write of ours.
+        let backupPath;
+        if (raw !== null) {
+            backupPath = `${configPath}.bak-${new Date().toISOString().replace(/:/g, "-")}`;
+            (0, node_fs_1.copyFileSync)(configPath, backupPath);
+        }
+        // 4. tmp write → validate the exact on-disk bytes → atomic rename.
+        tmpPath = (0, node_path_1.join)(dir, `${(0, node_path_1.basename)(configPath)}.tmp-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`);
+        (0, node_fs_1.writeFileSync)(tmpPath, payload);
+        JSON.parse((0, node_fs_1.readFileSync)(tmpPath, "utf-8"));
+        (0, node_fs_1.renameSync)(tmpPath, configPath);
+        tmpPath = undefined; // committed — nothing left to clean up
+        return backupPath === undefined ? { status: "written" } : { status: "written", backupPath };
+    }
+    catch (e) {
+        if (tmpPath !== undefined) {
+            try {
+                (0, node_fs_1.rmSync)(tmpPath, { force: true });
+            }
+            catch { /* best-effort cleanup — the failure below is the real news */ }
+        }
+        return { status: "failed", reason: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/cli.d.ts

@@ -4,6 +4,7 @@
  *
  * Commands:
  *   server     Start the MCP HTTP/SSE server (persistent daemon)
+ *   mcp        Speak MCP over stdio (bridge to the local daemon or HICORTEX_SERVER_URL)
  *   init       Detect existing setup and configure for CC/OC
  *   nightly    Run capture + consolidate (manual trigger)
  *              nightly --capture-only     Capture only, skip consolidation
@@ -11,8 +12,12 @@
  *              nightly --evict-only       Memory-cap eviction only — pure DB, no LLM (#317)
  *              nightly --status           Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
- *   dedup      Cluster + merge near-duplicate memories (issue #100)
- *              dedup --apply           Execute the merge (default: dry run)
+ *   dedup      Cluster + merge near-duplicate memories (issues #100, #392)
+ *              dedup --apply           Execute the merge (default: dry run);
+ *                                      losers are absorbed (kept as evidence,
+ *                                      hidden from recall), not deleted
+ *   history    Show a memory's rewrite history, or roll one back (issue #384)
+ *              history --rollback <row>  Undo one rewrite + un-absorb triggers
  *   status     Show config, DB stats, adapter status
  *   uninstall  Clean removal of CC integration
  */

package/dist/cli.js

@@ -5,6 +5,7 @@
  *
  * Commands:
  *   server     Start the MCP HTTP/SSE server (persistent daemon)
+ *   mcp        Speak MCP over stdio (bridge to the local daemon or HICORTEX_SERVER_URL)
  *   init       Detect existing setup and configure for CC/OC
  *   nightly    Run capture + consolidate (manual trigger)
  *              nightly --capture-only     Capture only, skip consolidation
@@ -12,8 +13,12 @@
  *              nightly --evict-only       Memory-cap eviction only — pure DB, no LLM (#317)
  *              nightly --status           Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
- *   dedup      Cluster + merge near-duplicate memories (issue #100)
- *              dedup --apply           Execute the merge (default: dry run)
+ *   dedup      Cluster + merge near-duplicate memories (issues #100, #392)
+ *              dedup --apply           Execute the merge (default: dry run);
+ *                                      losers are absorbed (kept as evidence,
+ *                                      hidden from recall), not deleted
+ *   history    Show a memory's rewrite history, or roll one back (issue #384)
+ *              history --rollback <row>  Undo one rewrite + un-absorb triggers
  *   status     Show config, DB stats, adapter status
  *   uninstall  Clean removal of CC integration
  */
@@ -34,6 +39,26 @@ switch (command) {
         });
         break;
     }
+    case "mcp": {
+        // Stdio MCP bridge (#375): speak MCP on stdin/stdout, backed by the
+        // daemon's SSE endpoint (or a remote server via HICORTEX_SERVER_URL).
+        // Registry clients (Claude Desktop, Cursor, the MCP Registry's install
+        // flow) launch stdio commands — this is the command the registry's
+        // server.json declares (`npx -y @gamaze/hicortex mcp`). Starts a local
+        // daemon when the target is loopback and none is running; never spawns
+        // for remote targets. stdout carries ONLY the MCP protocol — all
+        // diagnostics go to stderr (the bridge owns that discipline internally).
+        import("./mcp-stdio.js").then(({ runMcpStdio }) => {
+            runMcpStdio().catch((err) => {
+                console.error(err instanceof Error ? err.message : `[hicortex] mcp bridge failed: ${err}`);
+                process.exit(1);
+            });
+        }).catch((err) => {
+            console.error("[hicortex] Failed to load the mcp bridge:", err);
+            process.exit(1);
+        });
+        break;
+    }
     case "init": {
         const serverArg = process.argv.indexOf("--server");
         const serverUrl = serverArg !== -1 ? process.argv[serverArg + 1] : undefined;
@@ -251,6 +276,52 @@ switch (command) {
         });
         break;
     }
+    case "history": {
+        // Rewrite history: audit + one-command rollback (#384). Listing is
+        // read-only; --rollback mutates (restores prior content/status and
+        // un-absorbs triggers). Mirrors `dedup`: flags parsed here, the runner
+        // (config load + DB open + print/rollback + close) lives in
+        // reconsolidation.ts so this switch stays thin.
+        const args = process.argv.slice(3);
+        let rollbackId;
+        try {
+            const raw = (0, cli_args_js_1.readValueFlag)(args, "--rollback");
+            if (raw !== undefined) {
+                rollbackId = parseInt(raw, 10);
+                if (isNaN(rollbackId)) {
+                    console.error("[hicortex] history: --rollback requires a numeric history row id");
+                    process.exit(1);
+                }
+            }
+        }
+        catch {
+            console.error("[hicortex] history: --rollback requires a history row id (see `hicortex history <memory-id>`)");
+            process.exit(1);
+        }
+        let dbPath;
+        try {
+            dbPath = (0, cli_args_js_1.readValueFlag)(args, "--db");
+        }
+        catch {
+            console.error("[hicortex] history: --db requires a path value");
+            process.exit(1);
+        }
+        const positional = args.filter((a) => !a.startsWith("-") && a !== dbPath);
+        const memoryId = positional[0];
+        const historyOptions = { dbPath, memoryId, rollbackId };
+        import("./reconsolidation.js").then(({ runHistoryCommand }) => {
+            runHistoryCommand(historyOptions)
+                .then((code) => process.exit(code))
+                .catch((err) => {
+                console.error(err instanceof Error ? err.message : `[hicortex] history failed: ${err}`);
+                process.exit(1);
+            });
+        }).catch((err) => {
+            console.error("[hicortex] history failed:", err);
+            process.exit(1);
+        });
+        break;
+    }
     case "identity": {
         // Standing identity layer edit surface (spec §6; renamed from context in
         // 0.18 #264): show|edit against the configured server. Secondary to the
@@ -331,6 +402,7 @@ Usage: hicortex <command> [options]
 
 Commands:
   server          Start the MCP HTTP/SSE server (server mode)
+  mcp             Speak MCP over stdio (bridge to the local daemon or HICORTEX_SERVER_URL)
   init            Set up Hicortex (server mode, local DB + daemon)
                   Scaffolds 5 editable default memory domains (Work, Personal,
                   People, Health, Finance) in ~/.hicortex/config.json
@@ -343,6 +415,9 @@ Commands:
   nightly         Run nightly denoise + capture + consolidate
   relink          Resumable link-discovery pass over the ENTIRE corpus (server mode)
   dedup           Cluster + merge near-duplicate memories (server mode; dry run by default)
+  history         Show a memory's rewrite history, or roll one back (server mode)
+                  history <id>                List rewrite events (read-only)
+                  history --rollback <row>    Undo one rewrite + un-absorb its triggers
   backup          Snapshot the DB + identity + state to a tar.gz (online, WAL-safe)
   classify-domains  Backfill content-based domain tags over the corpus (server mode, needs config.domains)
   classify-types    Backfill episode→fact/decision type tags over the corpus (server mode)
@@ -368,8 +443,14 @@ Options:
   relink --batch <n>        Memories per batch (default: 200)
   relink --reset            Restart from the beginning (ignore saved cursor)
   dedup --apply             Execute the merge (default: dry run, report only)
-  dedup --threshold <t>     Override config dedupMergeThreshold for one run
+                            Losers are absorbed — hidden from recall, kept as
+                            evidence (fetchable by id; dedup_log audit) — not deleted
+  dedup --threshold <t>     Override the threshold for one run (default: config
+                            dedupAutoMergeThreshold, legacy dedupMergeThreshold
+                            still honored; else 0.92)
   dedup --db <path>         DB path override (defaults to the configured DB)
+  history --rollback <row>  Roll back history row <row>: restores prior content/status, un-absorbs triggers
+  history --db <path>       DB path override (defaults to the configured DB)
   backup --out <dir>        Write the artifact into <dir> as hicortex-<ISO>.tar.gz (default: <home>/backups)
   backup --stdout           Stream the tar.gz to stdout (offsite pipe: hicortex backup --stdout | rclone rcat …)
   classify-domains --all    Reclassify every memory (default: only NULL/stale-domain rows)

package/dist/consolidate.d.ts

@@ -8,6 +8,7 @@ import type { Memory, ConsolidationReport } from "./types.js";
 import type { LlmClient } from "./llm.js";
 import type { EmbedFn } from "./retrieval.js";
 import { type DomainDef } from "./domain-classify.js";
+import { type ReconsolidationOptions } from "./reconsolidation.js";
 /**
  * Default ceiling on total LLM calls across all classify-tier consolidation
  * stages (content-domain, link discovery, supersession) per run. This is a
@@ -343,7 +344,13 @@ budgetMaxCalls?: number,
 /** Soft cap on the corpus (#245). Nightly.ts reads `memorySoftCap` from
  *  config and passes it; unset → `DEFAULT_MEMORY_SOFT_CAP` (10000). `0`
  *  disables eviction (indefinite growth). */
-memorySoftCap?: number): Promise<ConsolidationReport>;
+memorySoftCap?: number, 
+/** Reconsolidation-stage knobs (#384), threaded from config by nightly.ts
+ *  (correctionMinSimilarity / correctionRewriteMinConfidence) exactly like
+ *  supersessionOptions above; unset fields → the stage's defaults.
+ *  Appended AFTER the pre-#384 params so every existing positional caller
+ *  (tests, hosted nightly) keeps its argument meaning. */
+reconsolidationOptions?: ReconsolidationOptions): Promise<ConsolidationReport>;
 /**
  * Calculate milliseconds until the next occurrence of a given hour (local time).
  */

package/dist/consolidate.js

@@ -66,6 +66,8 @@ const state_js_1 = require("./state.js");
 const domain_classify_js_1 = require("./domain-classify.js");
 const schema_prototypes_js_1 = require("./schema-prototypes.js");
 const nofit_js_1 = require("./nofit.js");
+const reconsolidation_js_1 = require("./reconsolidation.js");
+const dedup_js_1 = require("./dedup.js");
 // Default config constants (matching Python config.py)
 /**
  * Default ceiling on total LLM calls across all classify-tier consolidation
@@ -1065,7 +1067,7 @@ function parseSupersessionReply(reply) {
  */
 async function classifySupersession(llm, oldContent, newContent) {
     try {
-        const r = await llm.completeClassify(buildSupersessionPrompt(oldContent, newContent), 32);
+        const r = await llm.completeClassify(buildSupersessionPrompt(oldContent, newContent));
         return { verdict: parseSupersessionReply(r.text), usage: r.usage };
     }
     catch {
@@ -1360,6 +1362,66 @@ function stageMemoryCapEviction(db, dryRun, cap) {
         `memories (corpus was ${count}, cap ${cap}).`);
     return { cap, evicted: victims.length };
 }
+/**
+ * Minimal resolution-stage report for a SKIPPED (quiet-night) consolidation
+ * run (#392): every stage field zero except `merges` — the deterministic
+ * zone's own report — and its derived deterministic band snapshot. Keeps the
+ * one-report surface intact (the zone is the only resolution work a quiet
+ * night does) while telemetry's "skipped = zero LLM work" stays true. Knob
+ * validation mirrors the stage's own (invalid → defaults).
+ */
+async function skippedRunResolutionReport(db, dryRun, stateDir, options = {}) {
+    const validNumber = (v, fallback, ok) => {
+        const n = Number(v);
+        return Number.isFinite(n) && ok(n) ? n : fallback;
+    };
+    const autoMergeThreshold = validNumber(options.autoMergeThreshold, dedup_js_1.DEFAULT_DEDUP_MERGE_THRESHOLD, (n) => n > 0 && n <= 1);
+    const maxMerges = validNumber(options.maxMerges, dedup_js_1.DEFAULT_DEDUP_NIGHTLY_MAX_MERGES, (n) => n >= 0);
+    const merges = await (0, dedup_js_1.runDeterministicMergeZone)(db, {
+        stateDir,
+        threshold: autoMergeThreshold,
+        maxMerges,
+        dryRun,
+        acquireLock: options.acquireLock,
+    });
+    const bandStats = {};
+    if (merges.max_merges > 0) {
+        bandStats[`>=${autoMergeThreshold}`] = {
+            pairs: merges.losers_merged,
+            merge: merges.losers_merged,
+            corrects: 0,
+            supersedes: 0,
+            none: 0,
+            merge_below_gate: 0,
+            conf_sum: merges.losers_merged,
+            ...(merges.skipped_metadata_mismatch > 0
+                ? { metadata_skipped: merges.skipped_metadata_mismatch }
+                : {}),
+        };
+    }
+    return {
+        scanned: 0,
+        pairs_evaluated: 0,
+        rewritten: 0,
+        absorbed: 0,
+        kept_linked: 0,
+        marked_superseded: 0,
+        marked_retracted: 0,
+        below_gate: 0,
+        contract_failed: 0,
+        skipped_infra: 0,
+        skipped_idempotent: 0,
+        explicit_verified: 0,
+        explicit_divergent: 0,
+        cursor: (0, state_js_1.loadState)(stateDir).reconsolidationCursor ?? 0,
+        merges,
+        merge_pairs_applied: 0,
+        merge_below_gate: 0,
+        skipped_above_ceiling: 0,
+        skipped_metadata_mismatch: 0,
+        band_stats: bandStats,
+    };
+}
 async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection = false, stateDir, domainOptions, supersessionOptions, 
 /** Total LLM-call ceiling across classify-tier stages (#241). The caller
  *  reads `consolidateMaxLlmCalls` from config and passes it; unset → the
@@ -1368,7 +1430,13 @@ budgetMaxCalls,
 /** Soft cap on the corpus (#245). Nightly.ts reads `memorySoftCap` from
  *  config and passes it; unset → `DEFAULT_MEMORY_SOFT_CAP` (10000). `0`
  *  disables eviction (indefinite growth). */
-memorySoftCap) {
+memorySoftCap, 
+/** Reconsolidation-stage knobs (#384), threaded from config by nightly.ts
+ *  (correctionMinSimilarity / correctionRewriteMinConfidence) exactly like
+ *  supersessionOptions above; unset fields → the stage's defaults.
+ *  Appended AFTER the pre-#384 params so every existing positional caller
+ *  (tests, hosted nightly) keeps its argument meaning. */
+reconsolidationOptions) {
     const start = new Date();
     const report = {
         started_at: start.toISOString(),
@@ -1407,6 +1475,13 @@ memorySoftCap) {
     // but the cap stage is pure DB: cheap, idempotent when under cap).
     report.stages.memory_cap = stageMemoryCapEviction(db, dryRun, memorySoftCap ?? exports.DEFAULT_MEMORY_SOFT_CAP);
     if (skip) {
+        // #392: the deterministic merge zone is LLM-free, so a quiet night (zero
+        // new memories → this skip) still drains a pre-existing duplicate
+        // backlog — the memory_cap precedent. Results ride the ONE resolution
+        // stage report (telemetry's "skipped = zero LLM work" stays true), and
+        // the zone never runs twice: the main path runs it INSIDE the stage, this
+        // skip path returns before that.
+        report.stages.reconsolidation = await skippedRunResolutionReport(db, dryRun, stateDir, reconsolidationOptions);
         report.status = "skipped";
         report.completed_at = new Date().toISOString();
         return report;
@@ -1455,6 +1530,11 @@ memorySoftCap) {
         report.stages.hub_boost = stageHubBoost(db, dryRun);
         // Stage 3.7: Supersession Detection (#191 Phase B)
         report.stages.supersession = await stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, supersessionOptions);
+        // Stage 3.8: Reconsolidation (#384) — resolve corrections: rewrite
+        // fact-shaped targets in place (absorbing transition-only triggers),
+        // mark everything else. Rides the same shared budget under its own stage
+        // label + cursor (supersession-stage pattern).
+        report.stages.reconsolidation = await (0, reconsolidation_js_1.stageReconsolidation)(db, llm, budget, embedFn, dryRun, stateDir, reconsolidationOptions);
         // Stage 4: Decay & Prune
         report.stages.decay_prune = stageDecayPrune(db, dryRun);
         // (Memory cap eviction moved before the precheck skip — see above.)

package/dist/dashboard.d.ts

@@ -351,3 +351,20 @@ export declare function dashboardDataHandler(getDb: () => Database.Database, get
  * 500 with the usual {error} shape (same as dashboardDataHandler).
  */
 export declare function accountHandler(getConfig: () => Record<string, unknown> | null | undefined): express.RequestHandler;
+/**
+ * Express adapter for GET /account/token — the install's connection token for
+ * the console account menu (#365). SECURITY: echo-only — the caller must
+ * ALREADY present the token (bearer, or the localhost bypass) to receive it,
+ * so this endpoint grants no privilege. It exists so the menu shows the
+ * AUTHORITATIVE server-side token instead of trusting localStorage, which can
+ * be stale after token rotation and is absent entirely for browser sessions
+ * the hosted router authenticates via its session→bearer injection.
+ *
+ * `getToken` receives the boot-resolved PRIMARY token (config authToken ??
+ * HICORTEX_AUTH_TOKEN env) — the value the auth middleware itself accepts as
+ * current, so the menu survives rotation and never echoes the rotation-grace
+ * token. When no token is configured the handler answers 503 (mirrors how the
+ * /auth/* endpoints answer "not configured"); other failures surface as a 500
+ * {error} exactly like accountHandler.
+ */
+export declare function accountTokenHandler(getToken: () => string | undefined): express.RequestHandler;

package/dist/dashboard.js

@@ -26,6 +26,7 @@ exports.backfillSnapshots = backfillSnapshots;
 exports.handleDashboardData = handleDashboardData;
 exports.dashboardDataHandler = dashboardDataHandler;
 exports.accountHandler = accountHandler;
+exports.accountTokenHandler = accountTokenHandler;
 const recall_index_js_1 = require("./recall-index.js");
 const config_read_js_1 = require("./config-read.js");
 const consolidate_js_1 = require("./consolidate.js");
@@ -526,3 +527,34 @@ function accountHandler(getConfig) {
         }
     };
 }
+/**
+ * Express adapter for GET /account/token — the install's connection token for
+ * the console account menu (#365). SECURITY: echo-only — the caller must
+ * ALREADY present the token (bearer, or the localhost bypass) to receive it,
+ * so this endpoint grants no privilege. It exists so the menu shows the
+ * AUTHORITATIVE server-side token instead of trusting localStorage, which can
+ * be stale after token rotation and is absent entirely for browser sessions
+ * the hosted router authenticates via its session→bearer injection.
+ *
+ * `getToken` receives the boot-resolved PRIMARY token (config authToken ??
+ * HICORTEX_AUTH_TOKEN env) — the value the auth middleware itself accepts as
+ * current, so the menu survives rotation and never echoes the rotation-grace
+ * token. When no token is configured the handler answers 503 (mirrors how the
+ * /auth/* endpoints answer "not configured"); other failures surface as a 500
+ * {error} exactly like accountHandler.
+ */
+function accountTokenHandler(getToken) {
+    return (_req, res) => {
+        try {
+            const token = getToken();
+            if (!token) {
+                res.status(503).json({ error: "no auth token configured on this install" });
+                return;
+            }
+            res.status(200).json({ token });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+}

package/dist/db.js

@@ -511,6 +511,42 @@ const MIGRATIONS = [
             db.exec("UPDATE memories SET memory_type = 'learnings'  WHERE memory_type = 'lesson'");
         },
     },
+    {
+        version: 14,
+        name: "reconsolidation_status_history",
+        up: (db) => {
+            // #384 reconsolidation. `memories.status` is the code-defined state
+            // vocabulary (NULL/active default; 'superseded'/'retracted' demote in
+            // ranking; 'corrected' = rewritten, never demotes; 'absorbed' =
+            // invisible to recall — no vector, no FTS row). NULL default with NO
+            // backfill: legacy supersessions stay link-driven (findSupersededIds
+            // already demotes them); a status is only ever written by the
+            // reconsolidation stage, an explicit ingest mark, or a rollback.
+            // `memory_history` records CONTENT REWRITES ONLY (before/after content,
+            // prior status, trigger dispositions) — one structure serving audit AND
+            // `hicortex history --rollback`. Marks need no history row: they are
+            // auditable via links + status. Idempotent: hasColumn + IF NOT EXISTS.
+            if (!hasColumn(db, "memories", "status")) {
+                db.exec("ALTER TABLE memories ADD COLUMN status TEXT");
+            }
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS memory_history (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          memory_id TEXT NOT NULL,
+          old_content TEXT NOT NULL,
+          new_content TEXT NOT NULL,
+          prev_status TEXT,
+          new_status TEXT,
+          triggers_json TEXT,
+          evidence_id TEXT,
+          confidence REAL,
+          cause TEXT NOT NULL,
+          created_at TEXT NOT NULL
+        )
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_history_memory ON memory_history(memory_id)");
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.