@dzhechkov/harness-core 0.3.40 → 0.3.42

package/src/index.ts

@@ -27,7 +27,7 @@ export { recommend } from './recommend.js';
 export { pretrain } from './pretrain.js';
 export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, BOOST_CAP, recordPattern, loadStorePatternsSync, patternToRecord, recordToPattern, consolidateSessions, recallPatterns } from './patterns.js';
 export type { PatternRecord, SessionRecord, LearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, SessionsSource } from './patterns.js';
-export { runSetup } from './setup.js';
+export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf, AGENTDB_WRITER_VERSION } from './setup.js';
 export { generatePlugin } from './plugin.js';
 export type { PluginManifest } from './plugin.js';
 export type { SetupOptions, SetupResult, SetupStep } from './setup.js';

package/src/operations.ts

@@ -500,5 +500,57 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
     });
   }
 
+  // 8. agentdb brownfield health (gap G2) — only when agentdb artifacts are present, to keep
+  // non-agentdb projects noise-free. Detects installs from BEFORE the real-write fix.
+  const settingsPath = join(root, '.claude', 'settings.json');
+  const settingsRaw = existsSync(settingsPath) ? readFileSync(settingsPath, 'utf-8') : '';
+  if (settingsRaw.includes('agentdb add')) {
+    checks.push({
+      name: 'agentdb hooks',
+      ok: false,
+      detail: 'LEGACY broken hooks call non-existent `agentdb add` (they never wrote anything) — re-run: dz setup --target <t> --memory agentdb',
+    });
+  }
+  if (existsSync(join(root, '.dz', 'memory.rvf'))) {
+    checks.push({
+      name: 'agentdb store',
+      ok: false,
+      detail: 'orphan .dz/memory.rvf placeholder from an old setup (nothing reads it) — delete it; the real store is .dz/agentdb.db',
+    });
+  }
+  const legacyMcp = join(root, '.claude', 'mcp.json');
+  if (existsSync(legacyMcp) && readFileSync(legacyMcp, 'utf-8').includes('agentdb')) {
+    checks.push({
+      name: 'agentdb mcp location',
+      ok: false,
+      detail: '.claude/mcp.json is NOT loaded by Claude Code — re-run dz setup to register agentdb in .mcp.json (project root)',
+    });
+  }
+  const writerPath = join(root, '.dz', 'agentdb-writer.mjs');
+  if (existsSync(writerPath)) {
+    const { writerVersionOf, AGENTDB_WRITER_VERSION } = await import('./setup.js');
+    const deployed = writerVersionOf(readFileSync(writerPath, 'utf-8'));
+    if (deployed < AGENTDB_WRITER_VERSION) {
+      checks.push({
+        name: 'agentdb writer version',
+        ok: false,
+        detail: `deployed writer v${deployed} < current v${AGENTDB_WRITER_VERSION} — re-run dz setup to upgrade (no --force needed)`,
+      });
+    }
+    // Version drift between the local agentdb copy and the .mcp.json pin (gap G7)
+    try {
+      const localVer = (JSON.parse(readFileSync(join(root, 'node_modules', 'agentdb', 'package.json'), 'utf-8')) as { version?: string }).version;
+      const mcp = JSON.parse(readFileSync(join(root, '.mcp.json'), 'utf-8')) as { mcpServers?: Record<string, { args?: string[] }> };
+      const pinned = mcp.mcpServers?.['agentdb']?.args?.[0];
+      if (localVer && pinned && pinned !== `agentdb@${localVer}`) {
+        checks.push({
+          name: 'agentdb version drift',
+          ok: false,
+          detail: `local agentdb@${localVer} != MCP pin ${pinned} (alpha schema drift risk on the shared DB) — re-run dz setup`,
+        });
+      }
+    } catch { /* either side absent — covered by other checks */ }
+  }
+
   return { node: process.version, checks, ok: checks.every((check) => check.ok) };
 }

package/src/setup.ts

@@ -4,8 +4,10 @@
  * Unlike `dz init` (skills only), `dz setup` configures the complete
  * self-learning environment:
  * 1. Skills installation (via init)
- * 2. Claude Code hooks (session-start/end for memory)
- * 3. Memory database initialization (.dz/memory.db)
+ * 2. Claude Code session hooks (start/end) — with `--memory agentdb`, a real vector-store
+ *    write via `.dz/agentdb-writer.mjs`; otherwise a `.dz/sessions.jsonl` marker
+ * 3. Memory store: `.dz/agentdb.db` (agentdb, shared with the MCP server via AGENTDB_PATH)
+ *    or `.dz/sessions.jsonl` + `.dz/patterns.jsonl` (jsonl default)
  * 4. Pretrain (project analysis → auto-recommend)
  *
  * All operations are additive — never overwrites existing files.
@@ -13,8 +15,9 @@
  * @packageDocumentation
  */
 
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { execSync } from 'node:child_process';
 
 /** Memory backend type. */
 export type MemoryBackend = 'jsonl' | 'agentdb';
@@ -48,38 +51,138 @@ export interface SetupStep {
   readonly detail: string;
 }
 
+/** Absolute path to the agentdb store shared by the hook writer and the MCP server. */
+function agentdbStorePath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'agentdb.db');
+}
+
+/**
+ * Version of the generated `.dz/agentdb-writer.mjs`. Bump on ANY change to
+ * {@link generateAgentdbWriter}'s output — setup regenerates deployed writers whose
+ * `dz-writer-version` stamp is older, WITHOUT requiring `--force` (audit gap G4: generated code
+ * must not fossilize outside the package lifecycle).
+ */
+export const AGENTDB_WRITER_VERSION = 3;
+
+/**
+ * Generate the `.dz/agentdb-writer.mjs` helper invoked by the session hooks.
+ *
+ * v2 (ADR-002, audit gaps G3 + code#1 + code#4): session markers are **metadata-only telemetry** —
+ * a plain row in the `dz_session_events` table inside the SAME shared `.dz/agentdb.db` the MCP
+ * server is pinned to (`AGENTDB_PATH`). No embedding, no model load, no `successRate`:
+ * - ~ms latency (v1 loaded a ~90 MB transformers model → 12 s cold-timeout losing the marker);
+ * - zero pollution of the HNSW index real learnings live in (those enter via `agentdb_*` MCP tools);
+ * - uses better-sqlite3 DIRECTLY (WAL + busy_timeout) — if it is unavailable the writer falls back
+ *   to the jsonl marker instead of ever touching the sql.js in-memory backend, whose
+ *   last-write-wins semantics were the design's one real corruption vector.
+ *
+ * Best-effort and never throws: any failure degrades to a `.dz/sessions.jsonl` line labelled
+ * `jsonl-fallback` (with the error), so the hook always exits 0 and never blocks a session.
+ */
+export function generateAgentdbWriter(projectRoot: string): string {
+  const dbPath = agentdbStorePath(projectRoot);
+  const sessionsPath = join(projectRoot, '.dz', 'sessions.jsonl');
+  return `#!/usr/bin/env node
+// dz-writer-version: ${AGENTDB_WRITER_VERSION}
+// Auto-generated by \`dz setup --memory agentdb\`. Do not edit — re-run \`dz setup\` to upgrade
+// (setup regenerates automatically when this version stamp is outdated; --force not required).
+// Writes a metadata-only session-event row into the shared AgentDB store (.dz/agentdb.db — the
+// same file the agentdb MCP server is pinned to via AGENTDB_PATH). Real learnings go into the
+// vector index via the agentdb_* MCP tools; this is deliberately non-semantic telemetry.
+// On SessionEnd it ALSO fires a detached \`dz consolidate\` (Option C, ADR-003): harvest this
+// session's learnings into the lexical store and mirror them — with real embeddings — into the
+// shared AgentDB vector index. Detached + unref'd: the hook returns immediately; the model-load
+// cost happens off the session's critical path.
+// Best-effort: on ANY error it appends a .dz/sessions.jsonl marker and exits 0 — never throws,
+// never blocks the session.
+import { appendFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const event = process.argv[2] === 'end' ? 'end' : 'start';
+const ts = new Date().toISOString();
+const DB = process.env.AGENTDB_PATH || ${JSON.stringify(dbPath)};
+const SESSIONS = ${JSON.stringify(sessionsPath)};
+const ROOT = ${JSON.stringify(projectRoot)};
+
+function note(extra) {
+  try {
+    appendFileSync(SESSIONS, JSON.stringify({ event, ts, ...extra }) + '\\n');
+  } catch { /* last resort: swallow */ }
+}
+function fallback(err) {
+  note({ backend: 'jsonl-fallback', error: String((err && err.message) || err) });
+}
+
+try {
+  // Native better-sqlite3 ONLY (prebuilt; synchronous; WAL). Never the sql.js fallback — its
+  // whole-file-in-memory persistence is unsafe against a concurrently-writing MCP server.
+  const { default: Database } = await import('better-sqlite3');
+  const db = new Database(DB);
+  db.pragma('journal_mode = WAL');
+  db.pragma('busy_timeout = 5000'); // wait out a brief MCP-server write lock instead of failing
+  db.exec('CREATE TABLE IF NOT EXISTS dz_session_events (id INTEGER PRIMARY KEY AUTOINCREMENT, event TEXT NOT NULL, ts TEXT NOT NULL, source TEXT NOT NULL DEFAULT \\'dz-session-hook\\')');
+  db.prepare('INSERT INTO dz_session_events (event, ts) VALUES (?, ?)').run(event, ts);
+  db.close();
+} catch (err) {
+  fallback(err);
+}
+
+if (event === 'end') {
+  // Option C: harvest learnings + mirror to the vector index, DETACHED (fire-and-forget) so the
+  // hook never waits on transcript parsing or the embedding model. Uses the globally-installed
+  // \`dz\` from PATH. NO shell on posix: spawn's args-array + shell:true silently word-splits a
+  // ROOT containing spaces AND is Node's documented command-injection hazard (QE P1+P2); a plain
+  // spawn searches PATH itself and quotes nothing. Windows needs a shell for the .cmd shim, so
+  // there we pass ONE pre-quoted string (") — quotes are illegal in Windows paths, so wrapping
+  // is sufficient. Failure is detected via BOTH the error event (posix ENOENT) and a non-zero
+  // exit code (shell-mediated "not found"), each leaving an honest note.
+  try {
+    const child = process.platform === 'win32'
+      ? spawn('dz consolidate --project "' + ROOT + '"', { detached: true, stdio: 'ignore', shell: true, cwd: ROOT })
+      : spawn('dz', ['consolidate', '--project', ROOT], { detached: true, stdio: 'ignore', cwd: ROOT });
+    child.on('error', (err) => note({ consolidate: 'skipped', error: String((err && err.message) || err) }));
+    child.on('exit', (code) => { if (code !== null && code !== 0) note({ consolidate: 'skipped', error: 'dz exited ' + code + ' (not on PATH?)' }); });
+    child.unref();
+  } catch (err) {
+    note({ consolidate: 'skipped', error: String((err && err.message) || err) });
+  }
+}
+`;
+}
+
+/** Parse the `dz-writer-version` stamp from a deployed writer file ('' or absent → 0). */
+export function writerVersionOf(content: string): number {
+  const m = /^\/\/ dz-writer-version:\s*(\d+)/m.exec(content);
+  return m ? parseInt(m[1] ?? '0', 10) : 0;
+}
+
 /** Generate Claude Code hooks configuration for self-learning. */
-function generateHooksConfig(projectRoot: string, backend: MemoryBackend): string {
+export function generateHooksConfig(projectRoot: string, backend: MemoryBackend): string {
   const dzDir = join(projectRoot, '.dz');
 
   if (backend === 'agentdb') {
-    // agentdb backend: hooks use agentdb CLI to store patterns
-    const rvfPath = join(dzDir, 'memory.rvf');
+    // agentdb backend: hooks invoke the generated writer, which does a REAL vector-store write
+    // (ReasoningBank.storePattern) into the AGENTDB_PATH store the MCP server shares. The writer
+    // self-degrades to a sessions.jsonl marker on any failure, so no hook ever throws.
+    const writer = join(dzDir, 'agentdb-writer.mjs');
     return JSON.stringify({
       hooks: {
-        SessionStart: [{
-          type: 'command',
-          command: `node -e "const fs=require('fs');const d=new Date().toISOString();try{require('child_process').execSync('npx agentdb add \\'${rvfPath}\\' \\'session-start: '+d+'\\'',{stdio:'pipe'})}catch{fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'start',ts:d,backend:'agentdb'})+'\\n')}"`,
-        }],
-        SessionEnd: [{
-          type: 'command',
-          command: `node -e "const fs=require('fs');const d=new Date().toISOString();try{require('child_process').execSync('npx agentdb add \\'${rvfPath}\\' \\'session-end: '+d+'\\'',{stdio:'pipe'})}catch{fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'end',ts:d,backend:'agentdb'})+'\\n')}"`,
-        }],
+        SessionStart: [{ type: 'command', command: `node ${JSON.stringify(writer)} start` }],
+        SessionEnd: [{ type: 'command', command: `node ${JSON.stringify(writer)} end` }],
       },
     }, null, 2);
   }
 
-  // JSONL backend (default)
+  // JSONL backend (default) — honest session bookkeeping, no vector store involved.
+  // Use a RELATIVE path (Claude Code runs hooks from the project root): interpolating the absolute
+  // ${dzDir} into a single-quoted JS literal inside shell double-quotes breaks on Windows backslash
+  // paths (\U, \b…) and on any path containing a quote. `.dz/sessions.jsonl` sidesteps all of it.
+  const jsonlCmd = (event: 'start' | 'end'): string =>
+    `node -e "const fs=require('fs');const d=new Date().toISOString();fs.appendFileSync('.dz/sessions.jsonl',JSON.stringify({event:'${event}',ts:d,backend:'jsonl'})+'\\n')"`;
   return JSON.stringify({
     hooks: {
-      SessionStart: [{
-        type: 'command',
-        command: `node -e "const fs=require('fs');const d=new Date().toISOString();fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'start',ts:d})+'\\n')"`,
-      }],
-      SessionEnd: [{
-        type: 'command',
-        command: `node -e "const fs=require('fs');const d=new Date().toISOString();fs.appendFileSync('${dzDir}/sessions.jsonl',JSON.stringify({event:'end',ts:d})+'\\n')"`,
-      }],
+      SessionStart: [{ type: 'command', command: jsonlCmd('start') }],
+      SessionEnd: [{ type: 'command', command: jsonlCmd('end') }],
     },
   }, null, 2);
 }
@@ -96,9 +199,10 @@ function generateDzConfig(target: string, preset: string | undefined, backend: M
       // recommend() reads .dz/patterns.jsonl back as a ranking boost (audit #2).
       // Set false to disable the boost (recommend() reverts to pure keyword scoring).
       recommendBoost: true,
-      // No background consolidator ships in Tier 1 — flag must not advertise an
-      // unimplemented capability (the harvestDreamPatterns worker is Tier 2).
-      patternConsolidation: false,
+      // agentdb backend: the SessionEnd hook fires a detached `dz consolidate` that harvests
+      // learnings and mirrors them into the vector index (Option C, ADR-003). jsonl backend has
+      // no background consolidator — the flag must not advertise an unimplemented capability.
+      patternConsolidation: backend === 'agentdb',
       // Store backend: 'auto' = SQLite (FTS5, scale) when better-sqlite3 is
       // available, else the JSON fallback. 'json'/'sqlite' force a backend (Tier-3).
       sqliteBackend: 'auto',
@@ -107,12 +211,18 @@ function generateDzConfig(target: string, preset: string | undefined, backend: M
     },
     memory: {
       backend,
-      path: backend === 'agentdb' ? '.dz/memory.rvf' : '.dz/sessions.jsonl',
+      // agentdb: the native SQLite vector store shared by the session-hook writer and the
+      // agentdb MCP server (both pinned via AGENTDB_PATH). Real ReasoningBank patterns land here.
+      path: backend === 'agentdb' ? '.dz/agentdb.db' : '.dz/sessions.jsonl',
       maxSizeMb: backend === 'agentdb' ? 100 : 10,
       agentdb: backend === 'agentdb' ? {
         learning: true,
         vectorDim: 384,
         mcpServer: 'agentdb',
+        // Both the hook writer and the MCP server read/write THIS path (env AGENTDB_PATH).
+        storePath: '.dz/agentdb.db',
+        embeddingModel: 'Xenova/all-MiniLM-L6-v2',
+        sessionHookWrites: true,
       } : undefined,
     },
     hooks: {
@@ -122,11 +232,52 @@ function generateDzConfig(target: string, preset: string | undefined, backend: M
   }, null, 2);
 }
 
-/** Check if agentdb is available. */
-function isAgentdbAvailable(): boolean {
+/** True if `agentdb` resolves from the project's node_modules (the hook writer needs it there). */
+function isAgentdbInstalledLocally(projectRoot: string): boolean {
+  return existsSync(join(projectRoot, 'node_modules', 'agentdb', 'package.json'));
+}
+
+/**
+ * The exact agentdb version installed in the project, or `'latest'` as a fallback. Used to pin the
+ * MCP server spec (`agentdb@<version>`) so the long-running MCP server and the hook writer — which
+ * imports the on-disk local copy — run the SAME schema against the shared DB (agentdb is alpha;
+ * `@latest` could drift the MCP server's schema away from what the hook wrote).
+ */
+function installedAgentdbSpec(projectRoot: string): string {
   try {
-    require('child_process').execSync('npx agentdb --version', { stdio: 'pipe', timeout: 10000 });
-    return true;
+    const pkg = JSON.parse(readFileSync(join(projectRoot, 'node_modules', 'agentdb', 'package.json'), 'utf-8')) as { version?: string };
+    return pkg.version ? `agentdb@${pkg.version}` : 'agentdb@latest';
+  } catch {
+    return 'agentdb@latest';
+  }
+}
+
+/**
+ * Install `agentdb` + `better-sqlite3` as LOCAL project deps so the session-hook writer can
+ * `import('agentdb')` and get a native SQLite store (better-sqlite3 ships prebuilt binaries — no
+ * build tools — and gives true cross-process WAL concurrency so the hook and the MCP server share
+ * one live store). Best-effort: returns false (caller degrades to jsonl) if install fails.
+ */
+function installAgentdbLocally(projectRoot: string): boolean {
+  if (isAgentdbInstalledLocally(projectRoot)) return true;
+  try {
+    // Anchor npm to THIS project: without a package.json here, npm's prefix walk-up would
+    // install into (and mutate the lockfile of) the nearest ANCESTOR project (audit code#2).
+    const pkgJsonPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgJsonPath)) {
+      writeFileSync(pkgJsonPath, JSON.stringify({ name: 'dz-harness-project', private: true, version: '0.0.0' }, null, 2) + '\n');
+    }
+    // NB: use the ESM-imported execSync — `require()` is undefined in this ESM module (the
+    // original agentdb hooks failed silently for exactly this reason). stdio:'ignore' (not
+    // 'pipe') avoids execSync's 1 MB maxBuffer aborting the child on npm's verbose output.
+    // --save-exact: agentdb is alpha; a semver range would let a later `npm update` drift the
+    // local copy away from the version the MCP registration pins (audit gap G7).
+    execSync('npm install agentdb better-sqlite3 --save-exact --no-audit --no-fund --loglevel=error', {
+      cwd: projectRoot,
+      stdio: 'ignore',
+      timeout: 300000,
+    });
+    return isAgentdbInstalledLocally(projectRoot);
   } catch {
     return false;
   }
@@ -257,14 +408,19 @@ export function runSetup(opts: SetupOptions): SetupResult {
   const dzDir = join(opts.projectRoot, '.dz');
   const backend: MemoryBackend = opts.memory ?? 'jsonl';
 
-  // Step 0: Check agentdb availability if requested
+  // Step 0: Install agentdb + better-sqlite3 locally so the session-hook writer can import them
+  // and share a native store with the MCP server. Best-effort — the writer self-degrades to a
+  // jsonl marker (and self-heals once the deps exist) if this fails.
   if (backend === 'agentdb') {
-    const available = isAgentdbAvailable();
-    if (available) {
-      steps.push({ name: 'AgentDB check', status: 'done', detail: 'agentdb available' });
+    const ready = installAgentdbLocally(opts.projectRoot);
+    if (ready) {
+      steps.push({ name: 'Install agentdb + better-sqlite3', status: 'done', detail: 'local deps for real vector writes' });
     } else {
-      steps.push({ name: 'AgentDB check', status: 'error', detail: 'not found — install: npm i -g agentdb' });
-      // Fall through — will still create config, hooks will fallback to JSONL
+      steps.push({
+        name: 'Install agentdb + better-sqlite3',
+        status: 'error',
+        detail: 'install failed — hooks log to sessions.jsonl until you run: npm i agentdb better-sqlite3',
+      });
     }
   }
 
@@ -296,22 +452,26 @@ export function runSetup(opts: SetupOptions): SetupResult {
 
   // Step 4: Initialize memory store
   if (backend === 'agentdb') {
-    // Initialize .rvf via agentdb CLI
-    const rvfPath = join(dzDir, 'memory.rvf');
-    if (!existsSync(rvfPath)) {
-      try {
-        const { execSync } = require('child_process') as typeof import('child_process');
-        execSync(`npx agentdb init "${rvfPath}"`, { stdio: 'pipe', timeout: 30000 });
-        steps.push({ name: 'Initialize memory.rvf', status: 'done', detail: 'agentdb vector memory' });
-      } catch {
-        // Fallback: create empty file, agentdb will init on first use
-        writeFileSync(rvfPath, '');
-        steps.push({ name: 'Initialize memory.rvf', status: 'done', detail: 'placeholder (agentdb will init on first use)' });
-      }
+    // Write the session-hook writer. The agentdb.db store itself is auto-created on first write
+    // by createDatabase() (both the writer and the MCP server init the schema), so there is no
+    // orphan placeholder file — the writer targets the real, shared native store.
+    const writerPath = join(dzDir, 'agentdb-writer.mjs');
+    // Regenerate when missing, forced, OR the deployed stamp is older than the current
+    // generator — deployed writers must not fossilize outside the package lifecycle (gap G4).
+    const deployedVersion = existsSync(writerPath) ? writerVersionOf(readFileSync(writerPath, 'utf-8')) : -1;
+    if (deployedVersion === -1 || opts.force || deployedVersion < AGENTDB_WRITER_VERSION) {
+      writeFileSync(writerPath, generateAgentdbWriter(opts.projectRoot));
+      steps.push({
+        name: 'Write agentdb-writer.mjs',
+        status: 'done',
+        detail: deployedVersion > -1 && deployedVersion < AGENTDB_WRITER_VERSION
+          ? `upgraded v${deployedVersion} → v${AGENTDB_WRITER_VERSION}`
+          : `session telemetry writer v${AGENTDB_WRITER_VERSION}`,
+      });
     } else {
-      steps.push({ name: 'Initialize memory.rvf', status: 'skipped', detail: 'already exists' });
+      steps.push({ name: 'Write agentdb-writer.mjs', status: 'skipped', detail: `current (v${deployedVersion})` });
     }
-    // Also create JSONL fallback
+    // Keep the jsonl fallback log available for the writer's degraded path.
     const sessionsPath = join(dzDir, 'sessions.jsonl');
     if (!existsSync(sessionsPath)) writeFileSync(sessionsPath, '');
   } else {
@@ -332,70 +492,162 @@ export function runSetup(opts: SetupOptions): SetupResult {
     }
   }
 
-  // Step 5: Configure hooks (write to .claude/settings.json)
+  // Step 5: Configure hooks (write to .claude/settings.json) — EVENT-LEVEL merge (gap G2):
+  // dz-generated entries (recognized by signature, incl. the broken legacy `agentdb add` hooks
+  // this feature fixes) are replaced in place WITHOUT --force; the user's own hooks and every
+  // other settings key are preserved. Full-file overwrite happens only when the file is absent.
   if (!opts.noHooks) {
     const settingsDir = join(opts.projectRoot, '.claude');
     const settingsPath = join(settingsDir, 'settings.json');
+    const generated = JSON.parse(generateHooksConfig(opts.projectRoot, backend)) as {
+      hooks: Record<string, { type: string; command: string }[]>;
+    };
 
-    if (!existsSync(settingsPath) || opts.force) {
+    if (!existsSync(settingsPath)) {
       mkdirSync(settingsDir, { recursive: true });
-      writeFileSync(settingsPath, generateHooksConfig(opts.projectRoot, backend));
+      writeFileSync(settingsPath, JSON.stringify({ hooks: generated.hooks }, null, 2));
       steps.push({ name: 'Configure hooks', status: 'done', detail: `${backend} session hooks` });
     } else {
       try {
         const existing = JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
-        if (!existing['hooks']) {
-          const hooks = JSON.parse(generateHooksConfig(opts.projectRoot, backend));
-          existing['hooks'] = hooks.hooks;
+        const hooks = (existing['hooks'] ?? {}) as Record<string, unknown[]>;
+        let changed = false;
+        let replacedLegacy = false;
+        for (const event of Object.keys(generated.hooks)) {
+          const current = Array.isArray(hooks[event]) ? hooks[event] : [];
+          // Drop dz-generated entries (any vintage) — keep the user's own hooks untouched.
+          const kept = current.filter((entry) => {
+            const cmd = String((entry as { command?: unknown })?.command ?? '');
+            const isDz = cmd.includes('agentdb add') || cmd.includes('agentdb-writer.mjs') || cmd.includes('sessions.jsonl');
+            if (isDz && !cmd.includes('agentdb-writer.mjs')) replacedLegacy = true;
+            return !isDz;
+          });
+          const next = [...kept, ...generated.hooks[event]!];
+          if (JSON.stringify(next) !== JSON.stringify(current)) changed = true;
+          hooks[event] = next;
+        }
+        if (changed) {
+          existing['hooks'] = hooks;
           writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
-          steps.push({ name: 'Configure hooks', status: 'done', detail: `merged ${backend} hooks` });
+          steps.push({
+            name: 'Configure hooks',
+            status: 'done',
+            detail: replacedLegacy ? `replaced legacy dz hooks with ${backend} hooks` : `merged ${backend} hooks (user hooks preserved)`,
+          });
         } else {
-          steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'hooks already configured' });
+          steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'hooks already current' });
         }
       } catch {
-        steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'could not parse existing settings' });
+        steps.push({ name: 'Configure hooks', status: 'error', detail: 'could not parse existing settings.json — fix it and re-run' });
       }
     }
   } else {
     steps.push({ name: 'Configure hooks', status: 'skipped', detail: '--no-hooks' });
   }
 
-  // Step 5.5: Register agentdb MCP server (if agentdb backend)
+  // Step 5.5: Register agentdb MCP server (if agentdb backend) in **`.mcp.json` at the project
+  // root** — the project-scope location Claude Code actually loads (gap G5: the previously used
+  // `.claude/mcp.json` is NOT read by Claude Code, so the server never got AGENTDB_PATH and the
+  // shared-store invariant silently failed). READ-MERGE-WRITE: only the `agentdb` entry is
+  // managed; every other registered server is preserved (audit code#5 — never clobber).
   if (backend === 'agentdb') {
-    const mcpConfigPath = join(opts.projectRoot, '.claude', 'mcp.json');
-    if (!existsSync(mcpConfigPath) || opts.force) {
-      const mcpConfig = {
-        mcpServers: {
-          agentdb: {
-            command: 'npx',
-            args: ['agentdb@latest', 'mcp', 'start'],
-          },
-        },
+    const agentdbEntry = {
+      command: 'npx',
+      // Pin to the INSTALLED agentdb version (not @latest) so the MCP server and the hook
+      // writer run the same alpha schema against one DB.
+      args: [installedAgentdbSpec(opts.projectRoot), 'mcp', 'start'],
+      // Pin the store to the SAME native DB the session-hook writer targets, so hook telemetry
+      // and agentdb_* pattern/reflexion data live in one shared store.
+      env: { AGENTDB_PATH: agentdbStorePath(opts.projectRoot) },
+    };
+    const mcpConfigPath = join(opts.projectRoot, '.mcp.json');
+    try {
+      const mcpConfig = (existsSync(mcpConfigPath)
+        ? JSON.parse(readFileSync(mcpConfigPath, 'utf-8'))
+        : {}) as { mcpServers?: Record<string, unknown> };
+      const servers = mcpConfig.mcpServers ?? {};
+      const before = JSON.stringify(servers['agentdb']);
+      servers['agentdb'] = agentdbEntry;
+      mcpConfig.mcpServers = servers;
+      if (before !== JSON.stringify(agentdbEntry)) {
+        writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+        steps.push({ name: 'Register agentdb MCP', status: 'done', detail: '.mcp.json: 41 tools, store pinned to .dz/agentdb.db' });
+      } else {
+        steps.push({ name: 'Register agentdb MCP', status: 'skipped', detail: 'already registered and current' });
+      }
+    } catch {
+      steps.push({ name: 'Register agentdb MCP', status: 'error', detail: '.mcp.json unparseable — fix it and re-run' });
+    }
+    // Migrate off the legacy location: `.claude/mcp.json` is not loaded by Claude Code. If it
+    // holds ONLY our old agentdb registration, remove the file; otherwise leave it and warn.
+    const legacyPath = join(opts.projectRoot, '.claude', 'mcp.json');
+    if (existsSync(legacyPath)) {
+      try {
+        const legacy = JSON.parse(readFileSync(legacyPath, 'utf-8')) as { mcpServers?: Record<string, unknown> };
+        const keys = Object.keys(legacy.mcpServers ?? {});
+        if (keys.length === 1 && keys[0] === 'agentdb') {
+          rmSync(legacyPath);
+          steps.push({ name: 'Migrate legacy .claude/mcp.json', status: 'done', detail: 'removed (not loaded by Claude Code); registration now in .mcp.json' });
+        } else {
+          steps.push({ name: 'Migrate legacy .claude/mcp.json', status: 'error', detail: 'contains other servers — Claude Code does NOT load this file; move them to .mcp.json' });
+        }
+      } catch {
+        steps.push({ name: 'Migrate legacy .claude/mcp.json', status: 'error', detail: 'unparseable legacy file — Claude Code does not load it; review manually' });
+      }
+    }
+  }
+
+  // Step 5.9: agentdb wiring invariant check (audit code#3). Skip-branches across repeated runs
+  // can leave inconsistent combinations (e.g. writer+MCP present but hooks still jsonl). Verify
+  // the three-way invariant explicitly and surface a loud error step instead of silent "skipped"s.
+  if (backend === 'agentdb' && !opts.noHooks) {
+    const problems: string[] = [];
+    if (!isAgentdbInstalledLocally(opts.projectRoot)) problems.push('deps missing (npm i agentdb better-sqlite3)');
+    try {
+      const settings = JSON.parse(readFileSync(join(opts.projectRoot, '.claude', 'settings.json'), 'utf-8')) as {
+        hooks?: Record<string, { command?: string }[]>;
       };
-      mkdirSync(join(opts.projectRoot, '.claude'), { recursive: true });
-      writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
-      steps.push({ name: 'Register agentdb MCP', status: 'done', detail: '41 tools available' });
-    } else {
-      steps.push({ name: 'Register agentdb MCP', status: 'skipped', detail: 'mcp.json already exists' });
+      const refs = ['SessionStart', 'SessionEnd'].every((ev) =>
+        (settings.hooks?.[ev] ?? []).some((h) => String(h?.command ?? '').includes('agentdb-writer.mjs')));
+      if (!refs) problems.push('hooks do not invoke the writer');
+    } catch {
+      problems.push('settings.json unreadable');
+    }
+    try {
+      const mcp = JSON.parse(readFileSync(join(opts.projectRoot, '.mcp.json'), 'utf-8')) as {
+        mcpServers?: Record<string, { env?: Record<string, string> }>;
+      };
+      if (mcp.mcpServers?.['agentdb']?.env?.['AGENTDB_PATH'] !== agentdbStorePath(opts.projectRoot)) {
+        problems.push('.mcp.json agentdb missing or not pinned to .dz/agentdb.db');
+      }
+    } catch {
+      problems.push('.mcp.json unreadable');
     }
+    steps.push(problems.length === 0
+      ? { name: 'agentdb wiring', status: 'done', detail: 'hooks → writer → .dz/agentdb.db ← MCP (one shared store)' }
+      : { name: 'agentdb wiring', status: 'error', detail: `INCOMPLETE: ${problems.join('; ')}` });
   }
 
-  // Step 6: Update .gitignore
+  // Step 6: Update .gitignore. Append only the ENTRIES that are actually missing — a single
+  // sentinel check (e.g. sessions.jsonl, present in both backends) would skip agentdb.db/-wal/-shm
+  // on the documented jsonl→agentdb `--force` switch, leaking the binary store into git.
   const gitignorePath = join(opts.projectRoot, '.gitignore');
-  const dzIgnoreEntry = backend === 'agentdb'
-    ? '\n# DZ Harness learning data\n.dz/memory.rvf\n.dz/sessions.jsonl\n'
-    : '\n# DZ Harness learning data\n.dz/sessions.jsonl\n.dz/patterns.jsonl\n';
-  if (existsSync(gitignorePath)) {
-    const content = readFileSync(gitignorePath, 'utf-8');
-    if (!content.includes('.dz/sessions.jsonl')) {
-      writeFileSync(gitignorePath, content + dzIgnoreEntry);
-      steps.push({ name: 'Update .gitignore', status: 'done', detail: 'added .dz/sessions.jsonl + patterns.jsonl' });
-    } else {
-      steps.push({ name: 'Update .gitignore', status: 'skipped', detail: 'already ignoring .dz data' });
-    }
+  const dzIgnoreLines = backend === 'agentdb'
+    ? ['.dz/agentdb.db', '.dz/agentdb.db-wal', '.dz/agentdb.db-shm', '.dz/sessions.jsonl']
+    : ['.dz/sessions.jsonl', '.dz/patterns.jsonl'];
+  const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+  const missing = dzIgnoreLines.filter((line) => !existing.split(/\r?\n/).includes(line));
+  if (missing.length > 0) {
+    const prefix = existing === '' ? '' : (existing.endsWith('\n') ? '' : '\n');
+    const block = `${prefix}\n# DZ Harness learning data\n${missing.join('\n')}\n`;
+    writeFileSync(gitignorePath, existing + block);
+    steps.push({
+      name: existsSync(gitignorePath) && existing !== '' ? 'Update .gitignore' : 'Create .gitignore',
+      status: 'done',
+      detail: `added ${missing.join(', ')}`,
+    });
   } else {
-    writeFileSync(gitignorePath, dzIgnoreEntry);
-    steps.push({ name: 'Create .gitignore', status: 'done', detail: 'with .dz entries' });
+    steps.push({ name: 'Update .gitignore', status: 'skipped', detail: 'already ignoring .dz data' });
   }
 
   // Step 7: Install the CLI-driver skill + agent docs (--install-driver)