@gamaze/hicortex 0.16.1 → 0.16.3

package/README.md

@@ -164,6 +164,7 @@ npx @gamaze/hicortex context edit <name>       # Edit a context section in $EDIT
 npx @gamaze/hicortex context show --agent <id> # Show a specific agent's resolved context (0.13)
 npx @gamaze/hicortex init --agent-name <name>  # Opt in to a per-agent context id (default: unset — shared global context)
 npx @gamaze/hicortex init --agent-name ""      # Clear it back to global context
+npx @gamaze/hicortex init --repair-config      # Recover from a malformed config.json (see below)
 npx @gamaze/hicortex telemetry                 # Show exactly what anonymous telemetry sends
 npx @gamaze/hicortex status                    # Show config, DB stats
 npx @gamaze/hicortex uninstall                 # Remove CC integration (keeps DB)
@@ -211,6 +212,9 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `contextAgents` | Per-agent context modes (0.13): `{ "<id>": "override" \| "global" \| "off" }`. Absent + no `agents/<id>/` dir → every agent gets the global set. Boot-time (restart to apply) — see [Per-agent context](#per-agent-context-013) |
 | `agentName` | This install's per-agent context id sent as `?agent=`. **Unset by default** (CC shares the global context — no `?agent=` sent). Explicit opt-in via `init --agent-name <name>`; `init --agent-name ""` clears it. An empty/whitespace value equals unset |
 | `nightlyHour` | Local hour (0–23) for the nightly job installed by `init` (defaults: client 2, server 3). Applied on fresh installs; existing schedules are never overwritten |
+| `preflightTimeoutMs` | **Client mode only.** Per-attempt timeout for the nightly's server-reachability check before it starts capturing (default: 15000 ms) |
+| `preflightAttempts` | **Client mode only.** Reachability-check retries before the nightly aborts (default: 3; floored at 1). `1` = single try, no retry |
+| `preflightRetryGapMs` | **Client mode only.** Delay between reachability retries (default: 60000 ms). Note: timers don't advance while the machine is asleep, so on a sleeping laptop this gap counts awake-time, not wall-clock |
 | `scoreSimilarityWeight` | Weight of semantic similarity in the ranking score (default: 0.50) |
 | `scoreStrengthWeight` | Weight of effective strength — importance/use/recency of access (default: 0.20) |
 | `scoreConnectionsWeight` | Weight of graph centrality (default: 0.15) |
@@ -330,6 +334,13 @@ npm test
 
 ## Troubleshooting
 
+**`init` fails with "Refusing to write ~/.hicortex/config.json":** the file exists but is not valid JSON — usually a hand-edit slip (a trailing comma, a truncated write). `init` refuses rather than overwriting it, because overwriting would lose `authToken`, `licenseKey`, `distillApiKey`, and your `domains` list. Two ways out:
+
+1. **Preferred — fix the JSON.** The error names the parse failure and its position. Correct it and re-run `init`. Nothing is lost.
+2. **`npx @gamaze/hicortex init --repair-config`.** Moves the broken file to `config.json.corrupt-<timestamp>` and rebuilds from scratch. Nothing is deleted, and it prints the top-level key names it found (names only — never secret values) so you know what to copy back. **This mints a new `authToken`**, so every thin client pointing at this server must be updated or its recall will silently 401 (recall is fail-soft — you will see no error, just no memories).
+
+The nightly and the server behave differently on purpose: a malformed config makes them log a warning and run degraded rather than refuse to start, so a broken config never takes recall offline.
+
 **Tools not visible to agent (OC):** The plugin auto-adds tools to `tools.allow` on startup. Restart the gateway after install.
 
 **OC plugin: "Server unreachable":** The plugin requires a running Hicortex server. Run `npx @gamaze/hicortex init` on the same machine, or set `serverUrl` in the plugin config to point at a remote server.

package/dist/capture.d.ts

@@ -52,11 +52,17 @@ export interface Segment {
 export interface DistillBody {
     text: string;
     source_agent: string;
+    /** Stable client UUID (config.json `agentId`). Attribution only. */
+    source_agent_id?: string | null;
+    /** Client-declared topic/domain of the capturing agent. Provenance only. */
+    source_domain?: string | null;
     project: string;
     session_id: string;
     segment_id: string;
     session_date: string;
-    privacy: string;
+    /** 0.16.x: optional/vestigial. The distiller no longer sets it; a legacy
+     *  client may. Honored if present, else the memory stores NULL. */
+    privacy?: string;
 }
 /** Normalized POST result the caller's transport returns. */
 export interface PostResult {
@@ -73,6 +79,17 @@ export interface CaptureOptions {
     dryRun?: boolean;
     /** Segment size cap; defaults to SEGMENT_MAX_CHARS. Lowered in tests. */
     segmentMaxChars?: number;
+    /**
+     * Per-client attribution UUID (config.json `agentId`). Sent on every
+     * segment as `source_agent_id`. Null when the client has no `agentId`
+     * (e.g. a pre-0.16.x config that has not re-run init).
+     */
+    sourceAgentId?: string | null;
+    /**
+     * Per-client declared topic/domain (config.json `sourceDomain`). Sent as
+     * `source_domain` provenance. Null when undeclared.
+     */
+    sourceDomain?: string | null;
 }
 export interface CaptureResult {
     memoriesIngested: number;

package/dist/capture.js

@@ -134,7 +134,7 @@ function packSegments(entries, startCursor, entryCursors, maxChars = exports.SEG
  * boundary) while other sessions continue. A 429/401 stops the whole loop.
  */
 async function captureBatches(batches, opts) {
-    const { post, cursorStore, dryRun = false, segmentMaxChars = exports.SEGMENT_MAX_CHARS } = opts;
+    const { post, cursorStore, dryRun = false, segmentMaxChars = exports.SEGMENT_MAX_CHARS, sourceAgentId, sourceDomain } = opts;
     let memoriesIngested = 0;
     let sessionsSent = 0;
     let hadTransientFailure = false;
@@ -186,11 +186,12 @@ async function captureBatches(batches, opts) {
             const body = {
                 text: seg.text,
                 source_agent: batch.sourceAgent ?? `claude-code/${batch.projectName}`,
+                source_agent_id: sourceAgentId ?? null,
+                source_domain: sourceDomain ?? null,
                 project: batch.projectName,
                 session_id: batch.sessionId,
                 segment_id: `${genPrefix}${seg.segStart}-${seg.segEnd}${seg.idSuffix}`,
                 session_date: batch.date,
-                privacy: "WORK",
             };
             let result;
             try {

package/dist/classify-domains.d.ts

@@ -16,7 +16,7 @@
  *     reflect tier), same as the nightly. The LLM emits ONLY the ordered tag
  *     set; per-tag weights come from the domain prototypes (computed once at
  *     run start) and the PRIMARY (memories.domain) is derived (argmax weight,
- *     compartment override, LLM order breaking ties) inside
+ *     LLM order breaking ties) inside
  *     storage.setMemoryTags. After a completed (non-aborted) run the
  *     prototypes, all weights, and all primaries are recomputed from the
  *     final tag sets — same reconsolidation pass as the nightly.

package/dist/classify-domains.js

@@ -17,7 +17,7 @@
  *     reflect tier), same as the nightly. The LLM emits ONLY the ordered tag
  *     set; per-tag weights come from the domain prototypes (computed once at
  *     run start) and the PRIMARY (memories.domain) is derived (argmax weight,
- *     compartment override, LLM order breaking ties) inside
+ *     LLM order breaking ties) inside
  *     storage.setMemoryTags. After a completed (non-aborted) run the
  *     prototypes, all weights, and all primaries are recomputed from the
  *     final tag sets — same reconsolidation pass as the nightly.
@@ -195,7 +195,6 @@ async function runClassifyDomains(options = {}) {
         // Prototypes once at run start — newly classified memories get their
         // weights from these; the post-run reconsolidation pass refreshes
         // everything from the final tag sets.
-        const compartments = (0, schema_prototypes_js_1.compartmentSet)(domains);
         const { prototypes } = await (0, schema_prototypes_js_1.computeDomainPrototypes)(db, domains, getEmbedFn);
         // Scope filter: default = NULL / not-in-set / no tags yet; --all = everything.
         const placeholders = domains.map(() => "?").join(", ");
@@ -255,10 +254,9 @@ async function runClassifyDomains(options = {}) {
                     continue;
                 }
                 // Derived primary (argmax weight from the run-start prototypes,
-                // compartment override, LLM order breaking ties) — the same value
-                // setMemoryTags will write below.
+                // LLM order breaking ties) — the same value setMemoryTags writes below.
                 const weights = (0, schema_prototypes_js_1.computeTagWeights)(db, row.id, result.tags, prototypes);
-                const derived = (0, schema_prototypes_js_1.derivePrimary)(result.tags.map((tag) => ({ tag, weight: weights[tag] ?? null })), compartments);
+                const derived = (0, schema_prototypes_js_1.derivePrimary)(result.tags.map((tag) => ({ tag, weight: weights[tag] ?? null })));
                 if (derived === row.domain) {
                     batchUnchanged++;
                 }
@@ -273,10 +271,10 @@ async function runClassifyDomains(options = {}) {
             const tx = db.transaction(() => {
                 for (const w of writes) {
                     if (w.kind === "tags") {
-                        storage.setMemoryTags(db, w.id, w.tags, { weights: w.weights, compartments });
+                        storage.setMemoryTags(db, w.id, w.tags, { weights: w.weights });
                     }
                     else if (w.resolution.kind === "weak_primary") {
-                        (0, nofit_js_1.applyWeakPrimary)(db, w.id, w.resolution.domain, w.resolution.weight, compartments);
+                        (0, nofit_js_1.applyWeakPrimary)(db, w.id, w.resolution.domain, w.resolution.weight);
                     }
                     else {
                         (0, nofit_js_1.applyNoAssociationDecay)(db, w.id);

package/dist/cli.js

@@ -40,12 +40,17 @@ switch (command) {
             agentName = (0, cli_args_js_1.readValueFlag)(process.argv, "--agent-name");
         }
         catch {
-            console.error("[hicortex] init: --agent-name requires a value, e.g. --agent-name lenovo");
+            console.error("[hicortex] init: --agent-name requires a value, e.g. --agent-name my-agent");
             process.exit(1);
         }
+        const repairConfig = process.argv.includes("--repair-config");
         import("./init.js").then(({ runInit }) => {
-            runInit({ serverUrl, agentName }).catch((err) => {
-                console.error("[hicortex] Init failed:", err);
+            runInit({ serverUrl, agentName, repairConfig }).catch((err) => {
+                // Operator-fixable failures (a malformed config.json) carry a complete,
+                // actionable message — print that alone. A stack trace would bury it.
+                // Anything else is a real bug and gets the full error object.
+                const operatorFixable = err instanceof Error && /^Refusing to (read|write) /.test(err.message);
+                console.error("[hicortex] Init failed:", operatorFixable ? err.message : err);
                 process.exit(1);
             });
         });
@@ -250,6 +255,9 @@ Commands:
   init --server <url>  Set up as client (remote server)
   init --agent-name <name>  Opt in to a per-agent context id (default: unset — shared global context)
                             Pass --agent-name "" to clear it back to global
+  init --repair-config  Recover from a malformed ~/.hicortex/config.json: move it to
+                        config.json.corrupt-<timestamp> and rebuild. Nothing is deleted.
+                        Mints a NEW authToken — every thin client must be updated.
   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)

package/dist/cluster.d.ts

@@ -25,18 +25,19 @@ export declare class UnionFind {
 export declare function clusterEdges(edges: Edge[], threshold: number): string[][];
 /** Excess = sum(cluster size − 1) — rows that would disappear if every cluster merged to one. */
 export declare function clusterExcess(clusters: string[][]): number;
-/** The three metadata fields a merge candidate cluster must agree on. */
+/** Metadata fields a merge candidate cluster must agree on. `privacy` is on the row (the
+ *  column still exists) but is NOT a merge-safety field — vestigial since 0.16.2. */
 export interface ClusterMetaRow {
     project: string | null;
-    privacy: string;
+    privacy: string | null;
     source_agent: string;
 }
 export interface ClusterMetadataMismatch {
     projectMismatch: boolean;
-    privacyMismatch: boolean;
     sourceAgentMismatch: boolean;
 }
-/** Do cluster members disagree on project/privacy/source_agent? (merge-safety input for #100). */
+/** Do cluster members disagree on project / source_agent? (merge-safety input for #100).
+ *  Privacy is intentionally NOT checked — it is vestigial since 0.16.2. */
 export declare function clusterMetadataMismatch(members: ClusterMetaRow[]): ClusterMetadataMismatch;
 /**
  * Build the max-cosine edge set via top-K KNN on `memory_vectors`, keeping

package/dist/cluster.js

@@ -69,14 +69,13 @@ function clusterEdges(edges, threshold) {
 function clusterExcess(clusters) {
     return clusters.reduce((sum, c) => sum + (c.length - 1), 0);
 }
-/** Do cluster members disagree on project/privacy/source_agent? (merge-safety input for #100). */
+/** Do cluster members disagree on project / source_agent? (merge-safety input for #100).
+ *  Privacy is intentionally NOT checked — it is vestigial since 0.16.2. */
 function clusterMetadataMismatch(members) {
     const projects = new Set(members.map((m) => m.project ?? "\u0000null"));
-    const privacies = new Set(members.map((m) => m.privacy));
     const agents = new Set(members.map((m) => m.source_agent));
     return {
         projectMismatch: projects.size > 1,
-        privacyMismatch: privacies.size > 1,
         sourceAgentMismatch: agents.size > 1,
     };
 }

package/dist/consolidate.js

@@ -356,7 +356,6 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                         project,
                         memoryType: "lesson",
                         baseStrength: baseStrength[severity] ?? 0.8,
-                        privacy: "WORK",
                     });
                     generated++;
                 }
@@ -436,7 +435,6 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
         return { curated: false, domains: domains.length, classified: 0, reason: `dry_run (${rows.length} would classify)` };
     }
     const getEmbedFn = async () => embedFn;
-    const compartments = (0, schema_prototypes_js_1.compartmentSet)(domains);
     let classified = 0;
     let weakPrimary = 0;
     let noAssociationDecayed = 0;
@@ -465,7 +463,7 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
                 // double-halves.
                 const resolution = (0, nofit_js_1.resolveNoFit)(db, row.id, domains, startPrototypes, weakPrimaryFloor);
                 if (resolution.kind === "weak_primary") {
-                    (0, nofit_js_1.applyWeakPrimary)(db, row.id, resolution.domain, resolution.weight, compartments);
+                    (0, nofit_js_1.applyWeakPrimary)(db, row.id, resolution.domain, resolution.weight);
                     weakPrimary++;
                 }
                 else {
@@ -475,7 +473,7 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
                 continue;
             }
             const weights = (0, schema_prototypes_js_1.computeTagWeights)(db, row.id, result.tags, startPrototypes);
-            storage.setMemoryTags(db, row.id, result.tags, { weights, compartments });
+            storage.setMemoryTags(db, row.id, result.tags, { weights });
             classified++;
         }
     }
@@ -834,7 +832,7 @@ function stageHubBoost(db, dryRun) {
 //
 // A later decision/correction can reverse, replace, or invalidate an earlier
 // one — e.g. "chose Ollama for distillation" superseded a month later by
-// "switched distillation to the MBP's 35B model over Tailscale". Left
+// "switched distillation to a local 35B model over a mesh VPN". Left
 // unlinked, retrieval and lesson selection can surface the stale one. This
 // stage links OLD → NEW with relationship `superseded_by` and accelerates the
 // old memory's decay, WITHOUT deleting it (unlike `hicortex dedup`'s merge —

package/dist/db.js

@@ -441,6 +441,29 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 11,
+        name: "add_source_attribution",
+        up: (db) => {
+            // 0.16.x attribution + provenance. Two nullable columns on `memories`,
+            // both populated ONLY by capture (/distill) from client-declared values;
+            // nothing filters, scopes, or scores on either (attribution + echo).
+            //
+            // `source_agent_id`: the capturing client's stable UUID (config.json
+            //   `agentId`, generated once by init). Survives agent/machine renames
+            //   — unlike `source_agent`, a readable name. NULL on legacy rows.
+            // `source_domain`: the client-declared topic/domain of the capturing
+            //   agent (config.json `domain`). Distinct from the content-classified
+            //   `domain` column (which stays the LLM/prototype-derived primary).
+            // Guarded with hasColumn for idempotency across partially-migrated DBs.
+            if (!hasColumn(db, "memories", "source_agent_id")) {
+                db.exec("ALTER TABLE memories ADD COLUMN source_agent_id TEXT");
+            }
+            if (!hasColumn(db, "memories", "source_domain")) {
+                db.exec("ALTER TABLE memories ADD COLUMN source_domain TEXT");
+            }
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/dedup.js

@@ -287,7 +287,7 @@ async function runDedup(options = {}) {
             if (members.length < 2)
                 continue; // defensive — a member vanished between KNN and load
             const mismatch = (0, cluster_js_1.clusterMetadataMismatch)(members);
-            if (mismatch.projectMismatch || mismatch.privacyMismatch || mismatch.sourceAgentMismatch) {
+            if (mismatch.projectMismatch || mismatch.sourceAgentMismatch) {
                 mismatchSkipped.push({ size: members.length, memberIds: members.map((m) => m.id), mismatch });
                 continue;
             }

package/dist/distiller.js

@@ -419,8 +419,8 @@ function parseDistilledEntries(markdown) {
     const lines = markdown.split("\n");
     for (const line of lines) {
         const trimmed = line.trim();
-        // Skip all markdown headers (session title, classification, section
-        // headings). Sections are NOT prefixed onto entries: each bullet already
+        // Skip all markdown headers (session title, section headings). Sections
+        // are NOT prefixed onto entries: each bullet already
         // starts with its [SUBJECT] (topic-first, enforced by prompts.ts), and
         // prepending "[Section]" re-introduced the category-first prefix the
         // 2026-08-02 corpus rewrite removed. The section label is unused

package/dist/domain-classify.d.ts

@@ -18,7 +18,7 @@
  *     (the order is used solely as an exact-weight tiebreak downstream).
  * The PRIMARY (memories.domain) is NO LONGER requested from the LLM — audits
  * proved LLM primaries a coin-flip on overlapping spheres. It is DERIVED
- * deterministically (argmax association weight + compartment override) in
+ * deterministically (argmax association weight, LLM tag order breaking ties) in
  * schema-prototypes.ts / storage.setMemoryTags.
  *
  * NO-FIT = EMPTY TAG SET (owner amendment 07.07): "Unsorted" is a non-tag —

package/dist/domain-classify.js

@@ -19,7 +19,7 @@
  *     (the order is used solely as an exact-weight tiebreak downstream).
  * The PRIMARY (memories.domain) is NO LONGER requested from the LLM — audits
  * proved LLM primaries a coin-flip on overlapping spheres. It is DERIVED
- * deterministically (argmax association weight + compartment override) in
+ * deterministically (argmax association weight, LLM tag order breaking ties) in
  * schema-prototypes.ts / storage.setMemoryTags.
  *
  * NO-FIT = EMPTY TAG SET (owner amendment 07.07): "Unsorted" is a non-tag —
@@ -84,10 +84,6 @@ function parseConfigDomains(config) {
         if (!name)
             continue;
         const def = { name, description };
-        // Compartment policy passthrough (graded-schema spec): a domain flagged
-        // `compartment: true` becomes the primary whenever tagged.
-        if (d.compartment === true)
-            def.compartment = true;
         out.push(def);
     }
     return out.length > 0 ? out : null;

package/dist/eval/run-eval.js

@@ -65,7 +65,6 @@ function renderDups(d) {
         const mismatch = cluster.metadataMismatch;
         const mismatchFlags = [
             mismatch.projectMismatch ? "project" : null,
-            mismatch.privacyMismatch ? "privacy" : null,
             mismatch.sourceAgentMismatch ? "source_agent" : null,
         ].filter(Boolean);
         lines.push(`**Cluster ${i + 1}** — size ${cluster.size}, attribution: ${cluster.attribution.recoveryReingest} recovery-pair(s) / ${cluster.attribution.organic} organic-pair(s)` +

package/dist/index.js

@@ -470,7 +470,6 @@ exports.default = {
                         source_agent: `openclaw/${context?.agentId ?? "manual"}`,
                         project: args.project,
                         memory_type: args.memory_type ?? "episode",
-                        privacy: "WORK",
                     }, 15000);
                     if (!result.ok) {
                         return { error: `Ingest failed: ${result.data?.error ?? `HTTP ${result.status}`}` };

package/dist/init.d.ts

@@ -37,6 +37,84 @@ export declare function parseEnvFile(content: string): Record<string, string>;
  * a `models.score` would then silently shadow (nested > flat).
  */
 export declare function isLlmConfigured(config: Record<string, unknown>): boolean;
+/**
+ * Detect or ask for LLM config and persist to ~/.hicortex/config.json.
+ * The daemon can't inherit shell env vars, so we persist here.
+ * LLM choice is always user-controlled: candidates are detected and presented
+ * as a numbered list; the user picks one. Nothing is auto-applied.
+ * If the user cancels, the server runs recall-only (no LLM).
+ */
+export declare function persistLlmConfig(configPath?: string): Promise<void>;
+/**
+ * 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.
+ */
+export declare function loadConfigStrict(configPath: string): {
+    config: Record<string, unknown>;
+    hadFile: boolean;
+};
+/**
+ * `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.
+ */
+export declare function quarantineMalformedConfig(configPath: string): {
+    quarantined: false;
+} | {
+    quarantined: true;
+    backupPath: string;
+    keys: string[];
+};
 /**
  * Generate a random auth token in the format hctx-<32 hex chars>.
  * Exported for testability.
@@ -52,6 +130,56 @@ export declare function persistAuthToken(configPath: string): {
     token: string;
     generated: boolean;
 };
+/**
+ * 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.
+ */
+export declare function ensureAgentId(config: Record<string, unknown>): {
+    agentId: string;
+    generated: boolean;
+};
+/**
+ * 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.
+ */
+export declare function ensureAndPersistAgentId(configPath: string): {
+    agentId: string;
+    generated: boolean;
+};
 /**
  * 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
@@ -75,6 +203,42 @@ export declare function decideAgentName(existing: unknown, flag: string | undefi
     clear?: boolean;
     error?: string;
 };
+/** 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. */
+export declare function writeAgentNameConfig(configPath: string, value: string): void;
+/**
+ * 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.
+ */
+export declare function writeClientConfig(configPath: string, overrides: {
+    serverUrl: string;
+    authToken?: string;
+}, agentNameDecision?: {
+    write: boolean;
+    value: string | null;
+    clear?: boolean;
+}): {
+    config: Record<string, unknown>;
+};
 /**
  * Generic default memory domains scaffolded by server-mode init (issue #150).
  * Deliberately broad, high-level spheres — an editable STARTING POINT, not a
@@ -129,6 +293,7 @@ export declare function installRecallHooks(settingsPath?: string): void;
 export declare function runInit(options?: {
     serverUrl?: string;
     agentName?: string;
+    repairConfig?: boolean;
 }): Promise<void>;
 /**
  * Resolve the nightly hour (0–23, local time) for the generated schedule.