@gamaze/hicortex 0.16.1 → 0.16.3

package/dist/init.js

@@ -21,9 +21,16 @@ exports.GENERIC_DEFAULT_DOMAINS = void 0;
 exports.parseMcpListStatus = parseMcpListStatus;
 exports.parseEnvFile = parseEnvFile;
 exports.isLlmConfigured = isLlmConfigured;
+exports.persistLlmConfig = persistLlmConfig;
+exports.loadConfigStrict = loadConfigStrict;
+exports.quarantineMalformedConfig = quarantineMalformedConfig;
 exports.generateAuthToken = generateAuthToken;
 exports.persistAuthToken = persistAuthToken;
+exports.ensureAgentId = ensureAgentId;
+exports.ensureAndPersistAgentId = ensureAndPersistAgentId;
 exports.decideAgentName = decideAgentName;
+exports.writeAgentNameConfig = writeAgentNameConfig;
+exports.writeClientConfig = writeClientConfig;
 exports.scaffoldDefaultDomains = scaffoldDefaultDomains;
 exports.isEphemeralNpxPath = isEphemeralNpxPath;
 exports.installSessionStartHook = installSessionStartHook;
@@ -485,14 +492,10 @@ function isLlmConfigured(config) {
  * as a numbered list; the user picks one. Nothing is auto-applied.
  * If the user cancels, the server runs recall-only (no LLM).
  */
-async function persistLlmConfig() {
-    const configPath = (0, node_path_1.join)(HICORTEX_HOME, "config.json");
-    // Read existing config (may have licenseKey)
-    let config = {};
-    try {
-        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
-    }
-    catch { /* new file */ }
+async function persistLlmConfig(configPath = (0, node_path_1.join)(HICORTEX_HOME, "config.json")) {
+    // Strict load: a malformed existing config throws here — NEVER wiped to a
+    // stub (the 0.16.x BLOCKER). ENOENT seeds {} (fresh install).
+    const { config } = loadConfigStrict(configPath);
     // Don't overwrite if LLM config already persisted (incl. a nested-only config).
     if (isLlmConfigured(config)) {
         console.log(`  ✓ LLM config already configured`);
@@ -709,6 +712,128 @@ function saveConfig(configPath, config) {
     (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
     (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
 }
+/**
+ * Strict config loader — the SINGLE source of truth for "read config.json or
+ * fail loudly". Every config writer in init (persistLlmConfig, persistAuthToken,
+ * ensureAndPersistAgentId, scaffoldDefaultDomains) loads through this, and the
+ * runtime readers (nightly, server boot) route through it too (catching the
+ * throw to fail-soft with a visible WARN).
+ *
+ * The 0.16.x BLOCKER this closes: the bare `try { JSON.parse(readFileSync) }
+ * catch { /* new file *\/ }` pattern, on a config.json that EXISTS but won't
+ * parse (a hand-edit syntax slip, truncation, corruption), silently seeded `{}`
+ * and the writer then OVERWROTE the file — `persistAuthToken` minted a fresh
+ * token (fleet-wide 401), `scaffoldDefaultDomains` re-seeded the generic
+ * vocabulary over the owner list, etc. `authToken` / `licenseKey` /
+ * `distillApiKey` / `domains` / `weakPrimaryFloor` / `contextClients` all gone.
+ * The early-return guards (existing-key checks) did NOT save them: those only
+ * fire on a VALID parse that reads the key, not on a corrupted file.
+ *
+ * Contract:
+ *   - ENOENT (genuinely no file) → `{ config: {}, hadFile: false }` (a new
+ *     install; the caller decides whether to persist).
+ *   - Any OTHER read failure on an existing file (EACCES, etc.) → THROW.
+ *   - A parse failure (bad JSON) on an existing file → THROW.
+ *   - A non-object JSON value (null / array / true / 5 / "x") → THROW. Such a
+ *     value is not a valid config and must not be silently replaced with {}.
+ *
+ * Refusing is the right DEFAULT, but it dead-ends the operator: `init` is
+ * exactly what you would run to repair a broken install, and it now won't run.
+ * `init --repair-config` is the explicit escape hatch — see
+ * quarantineMalformedConfig below. Never quarantine implicitly: that path mints
+ * a fresh authToken (fleet-wide 401), so it must be a deliberate choice.
+ *
+ * Exported so nightly.ts / mcp-server.ts readers can route through it.
+ */
+function loadConfigStrict(configPath) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(configPath, "utf-8");
+    }
+    catch (e) {
+        // Only a genuinely-absent file (ENOENT) may safely seed {}.
+        if (e.code === "ENOENT") {
+            return { config: {}, hadFile: false };
+        }
+        // EACCES / EIO / … — the file is there but unreadable. Do not swallow.
+        throw new Error(`Refusing to read ${configPath}: the file exists but is not readable ` +
+            `(fix the permissions and re-run). Cause: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Refusing to write ${configPath}: the file exists but could not be parsed ` +
+            `(swallowing this would overwrite it with a stub and lose authToken / licenseKey / ` +
+            `domains). Fix the JSON and re-run, or run \`hicortex init --repair-config\` to move ` +
+            `the broken file aside and rebuild. ` +
+            `Cause: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // Non-object JSON (null / array / boolean / number / string) is not a valid
+    // config object and must never be silently replaced with {}.
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        const kind = parsed === null ? "null" : Array.isArray(parsed) ? "an array" : typeof parsed;
+        throw new Error(`Refusing to write ${configPath}: the file parses to ${kind}, not a JSON object ` +
+            `(swallowing this would overwrite it with a stub). Fix the JSON and re-run, or run ` +
+            `\`hicortex init --repair-config\` to move the broken file aside and rebuild.`);
+    }
+    return { config: parsed, hadFile: true };
+}
+/**
+ * `init --repair-config` escape hatch: move a malformed config.json aside so
+ * init can rebuild, instead of dead-ending on loadConfigStrict's throw.
+ *
+ * Why this exists: refusing to overwrite a corrupt config is right (it closed
+ * the 0.16.x wipe BLOCKER), but it leaves the operator stuck — `init` is the
+ * natural repair action and it now refuses to run. Deleting the file by hand
+ * works but silently loses `licenseKey` / `authToken` / `distillApiKey`.
+ *
+ * Why it is OPT-IN and never automatic: rebuilding mints a fresh `authToken`,
+ * which 401s every thin client on the fleet until they are re-pointed. That is
+ * a deliberate operator decision, not a fallback.
+ *
+ * Behaviour:
+ *   - Config absent or valid → no-op (`{ quarantined: false }`).
+ *   - Malformed → rename to `config.json.corrupt-<ISO>` (colons stripped for
+ *     Windows), and report the TOP-LEVEL KEY NAMES recovered from the raw text
+ *     so the operator knows what to restore.
+ *
+ * SECURITY: key NAMES only, never values. `authToken`, `licenseKey`,
+ * `distillApiKey` and `reflectApiKey` are secrets — printing them would leak
+ * into terminal scrollback, CI logs, and screen shares. The operator reads the
+ * values out of the backup file themselves.
+ *
+ * Exported for testability.
+ */
+function quarantineMalformedConfig(configPath) {
+    try {
+        loadConfigStrict(configPath);
+        return { quarantined: false }; // absent (ENOENT) or valid — nothing to do.
+    }
+    catch { /* malformed — fall through and quarantine */ }
+    // Best-effort key-name recovery from the RAW text. The file does not parse,
+    // so this is a regex over top-level-looking `"key":` occurrences — advisory
+    // only (it may over- or under-report on deeply nested or truncated files).
+    let keys = [];
+    try {
+        const raw = (0, node_fs_1.readFileSync)(configPath, "utf-8");
+        keys = [...new Set([...raw.matchAll(/"([A-Za-z_][A-Za-z0-9_]*)"\s*:/g)].map((m) => m[1]))];
+    }
+    catch { /* unreadable — report no keys rather than fail the repair */ }
+    const backupPath = `${configPath}.corrupt-${new Date().toISOString().replace(/:/g, "-")}`;
+    (0, node_fs_1.renameSync)(configPath, backupPath);
+    console.log(`  ⚠ ${configPath} was malformed — moved to ${backupPath}`);
+    console.log(`    init will rebuild a fresh config. NOTHING was deleted.`);
+    if (keys.length > 0) {
+        console.log(`    Keys found in the old file: ${keys.join(", ")}`);
+    }
+    console.log(`    ACTION REQUIRED: copy any of licenseKey / distillApiKey / reflectApiKey /`);
+    console.log(`    domains / weakPrimaryFloor back from the backup by hand.`);
+    console.log(`    A NEW authToken will be generated — every thin client pointing at this`);
+    console.log(`    server must be updated, or their recall will 401 (silently, fail-soft).`);
+    return { quarantined: true, backupPath, keys };
+}
 /**
  * Generate a random auth token in the format hctx-<32 hex chars>.
  * Exported for testability.
@@ -723,11 +848,10 @@ function generateAuthToken() {
  * Exported for testability.
  */
 function persistAuthToken(configPath) {
-    let config = {};
-    try {
-        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
-    }
-    catch { /* new file */ }
+    // Strict load: a malformed existing config throws here — NEVER mint a fresh
+    // token over a wiped stub (the 0.16.x BLOCKER: this writer was the worst — a
+    // fleet-wide 401 on a hand-edit slip). ENOENT seeds {} (fresh install).
+    const { config } = loadConfigStrict(configPath);
     if (config.authToken && typeof config.authToken === "string") {
         return { token: config.authToken, generated: false };
     }
@@ -737,6 +861,66 @@ function persistAuthToken(configPath) {
     (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
     return { token, generated: true };
 }
+/**
+ * Ensure a stable per-install `agentId` UUID is set on a config object.
+ *
+ * The id is the client's attribution identity (stored on each captured
+ * memory as `source_agent_id`) — it survives agent/machine renames, unlike
+ * the readable `source_agent` name. Generated once, never rotated (idempotent:
+ * an existing valid `agentId` is always kept). Pure: mutates `config` in place
+ * and does NO file IO — BOTH server and client init call this on their
+ * in-memory config object before saving (the server path loads/saves
+ * config.json around it; the client builds in-memory and saves once).
+ * Exported for testability.
+ */
+function ensureAgentId(config) {
+    if (typeof config.agentId === "string" && config.agentId) {
+        return { agentId: config.agentId, generated: false };
+    }
+    const agentId = (0, node_crypto_1.randomUUID)();
+    config.agentId = agentId;
+    return { agentId, generated: true };
+}
+/**
+ * Load → ensure → persist wrapper for the `agentId` provenance field. This is
+ * the runtime activation path: `ensureAgentId` was historically called ONLY
+ * inside `init`, so pre-0.16.2 installs that already ran init never get an
+ * `agentId` written → nightly + server boot capture sent `source_agent_id:
+ * null` forever (the feature was inert for the entire existing fleet). Both
+ * nightly and server boot call THIS on startup so the field self-heals on the
+ * first run after upgrade — one read, one conditional write, idempotent.
+ *
+ * Built on the pure `ensureAgentId` (which init's client path and the unit
+ * test still call directly); this wrapper adds the disk IO.
+ *
+ * Hardening (0.16.x CR BLOCKER): the naive "try { read } catch { seed {} }"
+ * + unconditional save WIPES config.json when the file exists but is
+ * unparseable (a hand-edit syntax slip) — the catch swallows the parse error,
+ * {} is seeded, and the save overwrites the file with just {"agentId": ...},
+ * destroying authToken / licenseKey / domains / weakPrimaryFloor, then
+ * cascades into scaffoldDefaultDomains re-seeding the generic vocabulary.
+ * This wrapper refuses that path:
+ *   - ENOENT (file genuinely absent) → seed {} is correct (new install).
+ *   - Any OTHER read/parse failure on a file that EXISTS (corruption,
+ *     truncation, bad JSON) → THROW. Swallowing would overwrite the file; the
+ *     operator must fix the JSON instead of silently losing it.
+ * Save happens ONLY when a new id was generated AND the file already existed
+ * — a missing config.json means init was never run (a separate problem), so we
+ * do not create a stub file just to hold an agentId. The returned id is still
+ * usable in-memory for the run either way.
+ *
+ * Exported for use by init's server path, nightly.ts, and mcp-server.ts boot.
+ */
+function ensureAndPersistAgentId(configPath) {
+    // One source of truth: loadConfigStrict throws on a malformed existing file
+    // (never wipe) and returns hadFile=false on ENOENT (do not create a stub).
+    const { config, hadFile } = loadConfigStrict(configPath);
+    const result = ensureAgentId(config);
+    if (result.generated && hadFile) {
+        saveConfig(configPath, config);
+    }
+    return result;
+}
 /**
  * Decide the per-agent context id to persist at init (#179; CC default = global,
  * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
@@ -773,32 +957,70 @@ function decideAgentName(existing, flag) {
         return { write: false, value: existing };
     return { write: false, value: null };
 }
-/** Read config.json, set agentName, write it back. Used by the server path. */
+/** Read config.json, set agentName, write it back. Used by the server path.
+ *  Routes through loadConfigStrict — a malformed existing config throws rather
+ *  than being wiped to a `{agentName: …}` stub (0.16.x BLOCKER; same pattern as
+ *  the other four writers). Exported for wipe-protection coverage. */
 function writeAgentNameConfig(configPath, value) {
-    let config = {};
-    try {
-        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
-    }
-    catch { /* new / unreadable → start fresh */ }
+    const { config } = loadConfigStrict(configPath);
     config.agentName = value;
     (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
     (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
 }
-/** Read config.json, delete any `agentName` key, write it back (server path). */
+/** Read config.json, delete any `agentName` key, write it back (server path).
+ *  Routes through loadConfigStrict — a malformed existing config throws (never
+ *  silently no-op). ENOENT is still a silent no-op (hadFile=false → empty
+ *  config has no `agentName` key → return without writing). */
 function clearAgentNameConfig(configPath) {
-    let config = {};
-    try {
-        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
-    }
-    catch {
-        return; /* new / unreadable → nothing to clear */
-    }
+    const { config } = loadConfigStrict(configPath);
     if (!("agentName" in config))
         return;
     delete config.agentName;
     (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
     (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
 }
+/**
+ * Client-init config write: strict-load → apply the client overrides → save.
+ * This is the testable seam for the client path's config build (the rest of
+ * runClientInit is interactive / mutates ~/.claude / installs the daemon, so it
+ * is not unit-testable; this helper is).
+ *
+ * Strict load closes the 0.16.x BLOCKER for the client path: the old bare
+ * `try { parse } catch { warn }` seeded `{}` on a malformed existing config,
+ * then proceeded to set mode/serverUrl/authToken/agentId and `saveConfig` —
+ * OVERWRITING the file and losing the client's existing `authToken` (→ 401 on
+ * the next /search) and `licenseKey`, the same class as the server-side wipe.
+ * Now a malformed existing config THROWS (the user is interactive at `init`;
+ * they can fix the JSON and re-run, same as the server path). ENOENT → `{}`
+ * → a genuinely new client config is built fresh and saved.
+ *
+ * `agentNameDecision` is resolved by the caller via decideAgentName (which owns
+ * the process.exit on an invalid --agent-name flag). A no-flag run passes a
+ * {write:false} decision → this helper does not touch `agentName`, preserving
+ * whatever the loaded config already carries. Exported for wipe-protection
+ * coverage.
+ */
+function writeClientConfig(configPath, overrides, agentNameDecision) {
+    const { config } = loadConfigStrict(configPath);
+    config.mode = "client";
+    config.serverUrl = overrides.serverUrl;
+    if (overrides.authToken)
+        config.authToken = overrides.authToken;
+    if (agentNameDecision) {
+        if (agentNameDecision.clear) {
+            delete config.agentName;
+        }
+        else if (agentNameDecision.write && agentNameDecision.value) {
+            config.agentName = agentNameDecision.value;
+        }
+        // write:false (no --agent-name flag) → leave the existing agentName as-is.
+    }
+    // Stable per-install agent id (attribution). Generated once, kept across
+    // re-runs (never rotated). An existing id from a prior init is preserved.
+    ensureAgentId(config);
+    saveConfig(configPath, config);
+    return { config };
+}
 /**
  * Generic default memory domains scaffolded by server-mode init (issue #150).
  * Deliberately broad, high-level spheres — an editable STARTING POINT, not a
@@ -827,11 +1049,10 @@ exports.GENERIC_DEFAULT_DOMAINS = [
  * Exported for testability.
  */
 function scaffoldDefaultDomains(configPath) {
-    let config = {};
-    try {
-        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
-    }
-    catch { /* new file */ }
+    // Strict load: a malformed existing config throws here — NEVER re-seed the
+    // generic defaults over the owner vocabulary (the 0.16.x BLOCKER). ENOENT
+    // seeds {} (fresh install → scaffold is the point).
+    const { config } = loadConfigStrict(configPath);
     if ("domains" in config) {
         console.log("  ✓ Memory domains already configured — leaving your list as-is");
         return { scaffolded: false };
@@ -1114,6 +1335,12 @@ async function ask(question) {
 // Main
 // ---------------------------------------------------------------------------
 async function runInit(options = {}) {
+    // --repair-config: quarantine a malformed config.json BEFORE any writer runs,
+    // so the strict loaders see ENOENT and rebuild instead of throwing. Must come
+    // first — every writer downstream loads through loadConfigStrict.
+    if (options.repairConfig) {
+        quarantineMalformedConfig((0, node_path_1.join)(HICORTEX_HOME, "config.json"));
+    }
     if (options.serverUrl) {
         await runClientInit(options.serverUrl, options.agentName);
         return;
@@ -1190,6 +1417,19 @@ async function runInit(options = {}) {
     else {
         console.log(`  ✓ Auth token already configured`);
     }
+    // Stable per-install agent id (attribution on captured memories; survives
+    // renames). Generated once, never rotated — same non-clobber philosophy as
+    // the auth token. Goes through ensureAndPersistAgentId (hardened wrapper:
+    // throws on a malformed existing config instead of swallowing + wiping, and
+    // saves ONLY when a new id was generated). persistAuthToken above already
+    // ensured config.json exists by this point. The client path shares the SAME
+    // loadConfigStrict discipline via writeClientConfig — it throws on a malformed
+    // existing config too (ENOENT builds a fresh client config), so no path in
+    // init silently wipes config.json anymore.
+    const agentIdResult = ensureAndPersistAgentId(configPath);
+    if (agentIdResult.generated) {
+        console.log(`  ✓ Agent id: ${agentIdResult.agentId}`);
+    }
     // Scaffold the generic default memory domains (server mode only — domains
     // live in the server's config; a client's memories are classified by the
     // server). Non-clobber: an existing `domains` key is never touched.
@@ -1355,39 +1595,25 @@ async function runClientInit(serverUrl, agentName) {
     // Step 3: Save client config
     (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
     const configPath = (0, node_path_1.join)(HICORTEX_HOME, "config.json");
-    let config = {};
-    if ((0, node_fs_1.existsSync)(configPath)) {
-        try {
-            config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
-        }
-        catch {
-            console.log(`  ⚠ ${configPath} exists but is not valid JSON — starting with empty config (licenseKey and LLM settings may need to be re-entered).`);
-        }
-    }
-    config.mode = "client";
-    config.serverUrl = serverUrl;
-    if (authToken)
-        config.authToken = authToken;
-    // Per-agent context id (#179): explicit opt-in only. Written ONLY when
-    // --agent-name is passed; otherwise no agentName is set and the client shares
-    // the global context (global by default). Re-init keeps an existing value
-    // unless --agent-name is explicit; `--agent-name ""` clears it back to global.
-    const nameDecision = decideAgentName(config.agentName, agentName);
+    // Per-agent context id (#179): explicit opt-in only. resolve the flag via
+    // decideAgentName (it owns the process.exit on an invalid --agent-name). A
+    // no-flag run yields a {write:false} decision → writeClientConfig leaves any
+    // existing agentName untouched (preserving what the loaded config carries).
+    const nameDecision = decideAgentName(undefined, agentName);
     if (nameDecision.error) {
         console.error(`  ✗ ${nameDecision.error}`);
         process.exit(1);
     }
     if (nameDecision.clear) {
-        delete config.agentName;
         console.log("  ✓ Agent name cleared — global context");
     }
-    else if (nameDecision.write && nameDecision.value) {
-        config.agentName = nameDecision.value;
-        if (agentName && nameDecision.value !== agentName) {
-            console.log(`  ℹ Agent name sanitized to '${nameDecision.value}'`);
-        }
+    else if (nameDecision.write && nameDecision.value && agentName && nameDecision.value !== agentName) {
+        console.log(`  ℹ Agent name sanitized to '${nameDecision.value}'`);
     }
-    saveConfig(configPath, config);
+    // writeClientConfig: strict-load → apply overrides → save. Throws on a
+    // malformed existing config (0.16.x BLOCKER — never wipe the client's
+    // authToken/licenseKey). ENOENT → fresh client config.
+    const { config } = writeClientConfig(configPath, { serverUrl, authToken }, nameDecision);
     console.log(`  ✓ Client config saved to ${configPath}`);
     if (typeof config.agentName === "string") {
         console.log(`  ✓ Agent name: ${config.agentName}`);

package/dist/mcp-server.js

@@ -70,6 +70,7 @@ const recall_index_js_1 = require("./recall-index.js");
 const seed_lesson_js_1 = require("./seed-lesson.js");
 const distiller_js_1 = require("./distiller.js");
 const dedup_js_1 = require("./dedup.js");
+const init_js_1 = require("./init.js");
 // ---------------------------------------------------------------------------
 // Server state
 // ---------------------------------------------------------------------------
@@ -78,6 +79,21 @@ let llm = null;
 // llmConfig is module-level so the /distill handler can call resolveDistillFallback
 // without having to read config on every request. null when no LLM is configured.
 let llmConfig = null;
+// One-time-per-process deprecation warning for the `?privacy=` query param
+// (0.16.x: the column is vestigial, never filtered). Old clients/plugins still
+// send it; we accept it (backward compat) but warn ONCE so an operator relying
+// on privacy filtering discovers from the logs that it is now a no-op.
+let privacyDeprecationWarned = false;
+function warnDeprecatedPrivacyParamIfPresent(query, route) {
+    if (privacyDeprecationWarned)
+        return;
+    if (query.privacy === undefined || query.privacy === null || query.privacy === "")
+        return;
+    privacyDeprecationWarned = true;
+    console.warn(`[hicortex] client sent ?privacy= on /${route}, which is ignored since 0.16.2 — ` +
+        `privacy is no longer filtered server-side (the column is vestigial). ` +
+        `Use a separate Hicortex server for isolation. (This warning fires once per process.)`);
+}
 // distillFallbackMode controls whether a failed remote distill endpoint causes an
 // immediate abort ("strict", default) or a fallback to the base model ("local").
 let distillFallbackMode = "strict";
@@ -174,7 +190,6 @@ function createMcpServer() {
                 sourceAgent: "claude-code/manual",
                 project,
                 memoryType: memory_type ?? "episode",
-                privacy: "WORK",
             });
             return { content: [{ type: "text", text: `Memory stored (id: ${id.slice(0, 8)})` }] };
         }
@@ -360,6 +375,17 @@ async function startServer(options = {}) {
     // goes through resolveExplicitLlmConfig which requires a user-chosen provider.
     // If nothing is configured: start recall-only with an unmissable warning.
     const savedConfig = (0, llm_js_1.applyModelsBlock)(readConfigFile(stateDir));
+    // 0.16.2 activation gap: self-heal the agentId provenance field for
+    // pre-0.16.2 server installs on first boot after upgrade. The server's own
+    // nightly captures its sessions to localhost:8787/distill and needs this id;
+    // without it every self-captured memory landed with source_agent_id NULL.
+    // Hardened wrapper: throws on a malformed config instead of wiping, saves
+    // only when a new id was generated. Mutate savedConfig so any downstream
+    // read picks up the id even before the file is re-read.
+    if (savedConfig) {
+        const { agentId } = (0, init_js_1.ensureAndPersistAgentId)((0, node_path_1.join)(stateDir, "config.json"));
+        savedConfig.agentId = agentId;
+    }
     if (savedConfig?.llmBackend === "claude-cli") {
         const claudePath = (0, llm_js_1.findClaudeBinary)();
         if (claudePath) {
@@ -597,7 +623,7 @@ async function startServer(options = {}) {
             res.status(503).json({ error: "Server not initialized" });
             return;
         }
-        const { content, source_agent, project, memory_type, privacy, source_session, session_date } = req.body ?? {};
+        const { content, source_agent, source_agent_id, source_domain, project, memory_type, privacy, source_session, session_date } = req.body ?? {};
         if (!content || typeof content !== "string") {
             res.status(400).json({ error: "Missing or invalid 'content' field" });
             return;
@@ -619,10 +645,15 @@ async function startServer(options = {}) {
             const embedding = await (0, embedder_js_1.embed)(content);
             const id = storage.insertMemory(db, content, embedding, {
                 sourceAgent: source_agent ?? "remote-client",
+                // Attribution + provenance passthrough (0.16.x); null when absent.
+                sourceAgentId: typeof source_agent_id === "string" ? source_agent_id : null,
+                sourceDomain: typeof source_domain === "string" ? source_domain : null,
                 sourceSession: source_session ?? undefined,
                 project: project ?? undefined,
                 memoryType: memory_type ?? "episode",
-                privacy: privacy ?? "WORK",
+                // 0.16.x: privacy defaults to null (vestigial column). A legacy client
+                // that sends an explicit value is honored; absent → null.
+                privacy: typeof privacy === "string" ? privacy : null,
                 createdAt: session_date ? new Date(session_date).toISOString() : undefined,
             });
             res.status(201).json({ id, message: "Memory ingested" });
@@ -646,11 +677,12 @@ async function startServer(options = {}) {
         // No hardcoded default: absent limit → config-driven (searchLimit).
         const limit = req.query.limit ? Number(req.query.limit) : undefined;
         const project = typeof req.query.project === "string" && req.query.project ? req.query.project : undefined;
-        const privacy = typeof req.query.privacy === "string" && req.query.privacy
-            ? req.query.privacy.split(",").map((s) => s.trim()).filter(Boolean)
-            : undefined;
+        // 0.16.x: `privacy` query param is ACCEPTED for backward compat (old
+        // clients/plugins still send it) but no longer read — retrieval ignores
+        // privacy entirely (the column is vestigial, never filtered).
+        warnDeprecatedPrivacyParamIfPresent(req.query, "search");
         try {
-            const results = await retrieval.retrieve(db, embedder_js_1.embed, query, { limit, project, privacy });
+            const results = await retrieval.retrieve(db, embedder_js_1.embed, query, { limit, project });
             res.json({ results });
         }
         catch (err) {
@@ -692,9 +724,9 @@ async function startServer(options = {}) {
                     limit,
                     noStrengthen: true,
                     // #203: project + mission_domains are SOFT affinity (zero-boost
-                    // neutral), threaded into computeScore. privacy stays a hard filter.
+                    // neutral), threaded into computeScore. 0.16.x: privacy is no
+                    // longer threaded (vestigial column, never filtered).
                     project: filters?.project,
-                    privacy: filters?.privacy,
                     missionDomains: filters?.mission_domains,
                     queryEmbedding: queryVec,
                 });
@@ -703,17 +735,18 @@ async function startServer(options = {}) {
         }, req.body);
         res.status(r.status).json(r.body);
     });
-    // REST /memory?id=[&privacy=] — fetch one memory's full content (lazy-load
-    // counterpart of /recall-index for REST clients: Hermes/OC plugins). Marks
-    // it as used. Prefix ids resolve; a privacy filter miss reads as 404 (no
-    // existence leak). Logic in handleMemoryGet (recall-index.ts).
+    // REST /memory?id= — fetch one memory's full content (lazy-load counterpart
+    // of /recall-index for REST clients: Hermes/OC plugins). Marks it as used.
+    // Prefix ids resolve. 0.16.x: the `privacy` query param is accepted but
+    // ignored (column is vestigial, never filtered). Logic in handleMemoryGet.
     app.get("/memory", (req, res) => {
         if (!db) {
             res.status(503).json({ error: "Server not initialized" });
             return;
         }
+        warnDeprecatedPrivacyParamIfPresent(req.query, "memory");
         try {
-            const r = (0, recall_index_js_1.handleMemoryGet)(db, { id: req.query.id, privacy: req.query.privacy });
+            const r = (0, recall_index_js_1.handleMemoryGet)(db, { id: req.query.id });
             res.status(r.status).json(r.body);
         }
         catch (err) {
@@ -728,12 +761,11 @@ async function startServer(options = {}) {
         }
         const project = typeof req.query.project === "string" && req.query.project ? req.query.project : undefined;
         // No hardcoded default: absent limit → config-driven (recentLimit).
+        // 0.16.x: `privacy` query param accepted but ignored (vestigial column).
         const limit = req.query.limit ? Number(req.query.limit) : undefined;
-        const privacy = typeof req.query.privacy === "string" && req.query.privacy
-            ? req.query.privacy.split(",").map((s) => s.trim()).filter(Boolean)
-            : undefined;
+        warnDeprecatedPrivacyParamIfPresent(req.query, "recent");
         try {
-            const results = retrieval.searchRecent(db, { project, limit, privacy });
+            const results = retrieval.searchRecent(db, { project, limit });
             res.json({ results });
         }
         catch (err) {
@@ -807,7 +839,7 @@ async function startServer(options = {}) {
             res.status(503).json({ error: "No LLM configured — run npx @gamaze/hicortex init. Session will be retried." });
             return;
         }
-        const { text, messages, source_agent, project, session_id, segment_id, session_date, privacy } = req.body ?? {};
+        const { text, messages, source_agent, source_agent_id, source_domain, project, session_id, segment_id, session_date, privacy } = req.body ?? {};
         // Resolve the conversation text from either the pre-denoised string or raw messages array.
         let conversationText;
         if (typeof text === "string" && text.length > 0) {
@@ -898,12 +930,18 @@ async function startServer(options = {}) {
                 for (const { entry, embedding, i } of toStore) {
                     out.push(storage.insertMemory(db, entry, embedding, {
                         sourceAgent: source_agent ?? "unknown",
+                        // Attribution + provenance only (0.16.x): client-declared, never
+                        // filtered. Default null for older clients that don't send them.
+                        sourceAgentId: typeof source_agent_id === "string" ? source_agent_id : null,
+                        sourceDomain: typeof source_domain === "string" ? source_domain : null,
                         // Per-chunk key: "<session_id>[#<segment_id>]#<i>". The prefix
                         // matches the dedup checks above, so a re-run is idempotent.
                         sourceSession: sourcePrefix ? `${sourcePrefix}#${i}` : undefined,
                         project: project ?? undefined,
                         memoryType: "episode",
-                        privacy: privacy ?? "WORK",
+                        // 0.16.x: privacy defaults to null (vestigial column). A legacy
+                        // client that sends an explicit value is honored; absent → null.
+                        privacy: typeof privacy === "string" ? privacy : null,
                         createdAt,
                     }));
                 }
@@ -1250,17 +1288,25 @@ async function startServer(options = {}) {
 const resolveMemoryId = storage.resolveMemoryId;
 /**
  * Read ~/.hicortex/config.json (persisted by init with LLM and license config).
+ * Routes through loadConfigStrict: a malformed existing file (bad JSON /
+ * non-object / unreadable) emits a visible WARN then fails-soft to null; an
+ * absent file (ENOENT) silently returns null. Without this routing the
+ * agentId self-heal's throw would be unreachable from boot (the old swallow
+ * → null → `if (savedConfig)` guard skipped it).
  */
 function readConfigFile(stateDir) {
+    const configPath = (0, node_path_1.join)(stateDir, "config.json");
+    let loaded;
     try {
-        const { readFileSync } = require("node:fs");
-        const { join } = require("node:path");
-        const configPath = join(stateDir, "config.json");
-        return JSON.parse(readFileSync(configPath, "utf-8"));
+        loaded = (0, init_js_1.loadConfigStrict)(configPath);
     }
-    catch {
+    catch (e) {
+        console.warn(`[hicortex] ${configPath} exists but could not be parsed — server booting degraded ` +
+            `(config-driven LLM/decay/recall knobs and agentId self-heal will not apply). ` +
+            `Fix the JSON and restart. Cause: ${e instanceof Error ? e.message : String(e)}`);
         return null;
     }
+    return loaded.hadFile ? loaded.config : null;
 }
 /**
  * Self-heal: if the daemon plist/systemd unit has a pinned version