@dzhechkov/harness-core 0.3.43 → 0.3.45

package/src/agentdb-index.ts

@@ -0,0 +1,128 @@
+/**
+ * Generic native AgentDB indexer — the reusable primitive behind Option C's learnings-mirror
+ * AND the book-knowledge-digitizer's KB indexer (ADR-001 v2, `features/book-knowledge-digitizer`).
+ *
+ * Writes rows NATIVELY via the project's `better-sqlite3`, replicating `ReasoningBank`'s exact
+ * schema (`reasoning_patterns` + `pattern_embeddings`, embed text `${taskType}: ${text}`) so the
+ * `agentdb` MCP server's `agentdb_pattern_search` reads what we write. `agentdb` is used ONLY for
+ * its `EmbeddingService` — never its `createDatabase` (hardwired to sql.js, whose whole-file save
+ * corrupts concurrent native-WAL writers; QE P1). Best-effort: never throws, returns an honest
+ * error string when the deps are absent.
+ *
+ * @packageDocumentation
+ */
+
+import { join, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+/** One record to index. `text` is stored as `approach` AND embedded (`${taskType}: ${text}`). */
+export interface AgentdbRow {
+  readonly taskType: string;
+  readonly text: string;
+  /** Stored as `success_rate`; clamped to [0,1]. Use the REAL signal, never a fabricated 1.0. */
+  readonly score: number;
+  readonly tags?: readonly string[];
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** Outcome of {@link indexPatternsToAgentdb}. */
+export interface AgentdbIndexResult {
+  readonly indexed: number;
+  readonly error?: string | undefined;
+}
+
+interface NativeDb {
+  pragma: (s: string) => void;
+  exec: (s: string) => void;
+  prepare: (q: string) => { run: (...a: unknown[]) => { lastInsertRowid: number | bigint } };
+  transaction: <T>(fn: (...a: unknown[]) => T) => (...a: unknown[]) => T;
+  close: () => void;
+}
+
+/** Resolve the shared store path: explicit opt → AGENTDB_PATH env → `<project>/.dz/agentdb.db`. */
+export function resolveAgentdbPath(projectRoot: string, dbPath?: string): string {
+  if (dbPath !== undefined && dbPath !== '') return dbPath;
+  const env = process.env['AGENTDB_PATH'];
+  return env !== undefined && env !== '' ? env : join(projectRoot, '.dz', 'agentdb.db');
+}
+
+/** ReasoningBank's schema, verbatim — so the MCP server reads exactly what we insert. */
+const REASONING_BANK_SCHEMA = `CREATE TABLE IF NOT EXISTS reasoning_patterns (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER DEFAULT (strftime('%s', 'now')),
+  task_type TEXT NOT NULL,
+  approach TEXT NOT NULL,
+  success_rate REAL NOT NULL DEFAULT 0.0,
+  uses INTEGER DEFAULT 0,
+  avg_reward REAL DEFAULT 0.0,
+  tags TEXT,
+  metadata TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_patterns_task_type ON reasoning_patterns(task_type);
+CREATE INDEX IF NOT EXISTS idx_patterns_success_rate ON reasoning_patterns(success_rate);
+CREATE INDEX IF NOT EXISTS idx_patterns_uses ON reasoning_patterns(uses);
+CREATE TABLE IF NOT EXISTS pattern_embeddings (
+  pattern_id INTEGER PRIMARY KEY,
+  embedding BLOB NOT NULL,
+  FOREIGN KEY (pattern_id) REFERENCES reasoning_patterns(id) ON DELETE CASCADE
+);`;
+
+/**
+ * Index `rows` into the shared AgentDB vector store. Returns `{indexed:0}` for an empty input and
+ * `{indexed:0, error}` when `agentdb`/`better-sqlite3` cannot be resolved from the project.
+ */
+export async function indexPatternsToAgentdb(
+  projectRoot: string,
+  rows: readonly AgentdbRow[],
+  opts: { dbPath?: string } = {},
+): Promise<AgentdbIndexResult> {
+  if (rows.length === 0) return { indexed: 0 };
+  let sqliteUrl: string;
+  let agentdbDir: string;
+  try {
+    const req = createRequire(join(projectRoot, 'package.json'));
+    sqliteUrl = pathToFileURL(req.resolve('better-sqlite3')).href;
+    agentdbDir = dirname(req.resolve('agentdb'));
+  } catch {
+    return { indexed: 0, error: 'agentdb/better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
+  }
+  try {
+    const { default: Database } = (await import(sqliteUrl)) as { default: new (p: string) => NativeDb };
+    const { EmbeddingService } = (await import(pathToFileURL(join(agentdbDir, 'controllers', 'EmbeddingService.js')).href)) as {
+      EmbeddingService: new (o: object) => { initialize: () => Promise<void>; embed: (t: string) => Promise<Float32Array> };
+    };
+    const emb = new EmbeddingService({ model: 'Xenova/all-MiniLM-L6-v2', dimension: 384, provider: 'transformers' });
+    await emb.initialize();
+
+    const db = new Database(resolveAgentdbPath(projectRoot, opts.dbPath));
+    try {
+      db.pragma('journal_mode = WAL');
+      db.pragma('busy_timeout = 5000'); // wait out a brief MCP-server write lock instead of failing
+      db.exec(REASONING_BANK_SCHEMA);
+      const insPattern = db.prepare('INSERT INTO reasoning_patterns (task_type, approach, success_rate, uses, avg_reward, tags, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)');
+      const insEmb = db.prepare('INSERT OR REPLACE INTO pattern_embeddings (pattern_id, embedding) VALUES (?, ?)');
+      // Embeddings are async (can't run inside better-sqlite3's sync transaction) — compute them
+      // ALL first, then commit the writes atomically (QE P2: a mid-loop failure must not leave a
+      // partial batch reported as indexed:0).
+      const prepared: Array<{ row: AgentdbRow; vec: Float32Array }> = [];
+      for (const row of rows) prepared.push({ row, vec: await emb.embed(`${row.taskType}: ${row.text}`) });
+      const commit = db.transaction(() => {
+        for (const { row, vec } of prepared) {
+          const r = insPattern.run(
+            row.taskType, row.text, Math.max(0, Math.min(1, Number.isFinite(row.score) ? row.score : 0)), 0, 0.0,
+            row.tags ? JSON.stringify(row.tags) : null,
+            row.metadata ? JSON.stringify(row.metadata) : null,
+          );
+          insEmb.run(Number(r.lastInsertRowid), Buffer.from(vec.buffer));
+        }
+        return prepared.length;
+      });
+      return { indexed: commit() as number };
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    return { indexed: 0, error: `index failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}

package/src/book-kb.ts

@@ -0,0 +1,170 @@
+/**
+ * Book Knowledge Base — a lexical (FTS5) namespace for digitized-book Knowledge Units, kept
+ * **separate by construction** from the taught-pattern store (`.dz/memory/…`). Because it is its
+ * own file (`.dz/memory/books.sqlite`) with its own API, `loadPatterns`/`computePatternBoost`
+ * never see book KUs (ADR-001 v2 harness-integration P1: no boost pollution) and there is no
+ * retention expiry (books are permanent references, not decaying session patterns).
+ *
+ * The semantic (vector) layer lives in the shared agentdb store via {@link indexPatternsToAgentdb};
+ * this is the lexical layer for `dz recall --books`. Native better-sqlite3; best-effort.
+ *
+ * @packageDocumentation
+ */
+
+import { join, dirname } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+/** A digitized Knowledge Unit as stored in the book KB. */
+export interface BookKU {
+  readonly book: string;            // ISBN or book slug (the immutable upstream key)
+  readonly kuId: string;
+  readonly corpusVersion: string;   // invalidation key: a re-ingest bumps this
+  readonly type: string;
+  readonly name: string;
+  readonly problem: string;
+  readonly content: string;
+  readonly chapter?: string;
+  readonly pages?: readonly number[];
+  readonly metadata?: Record<string, unknown>;
+}
+
+/** A lexical hit from {@link queryBookKnowledge}. */
+export interface BookKUHit {
+  readonly book: string;
+  readonly kuId: string;
+  readonly type: string;
+  readonly name: string;
+  readonly problem: string;
+  readonly content: string;
+  readonly chapter?: string;
+  readonly pages?: readonly number[];
+}
+
+interface NativeDb {
+  pragma: (s: string) => void;
+  exec: (s: string) => void;
+  prepare: (q: string) => {
+    run: (...a: unknown[]) => unknown;
+    all: (...a: unknown[]) => unknown[];
+  };
+  transaction: <T>(fn: (...a: unknown[]) => T) => (...a: unknown[]) => T;
+  close: () => void;
+}
+
+/** Default lexical store path — a `memory/` sibling of the pattern store, never `agentdb.db`. */
+export function bookKbPath(projectRoot: string): string {
+  return join(projectRoot, '.dz', 'memory', 'books.sqlite');
+}
+
+const SCHEMA = `CREATE VIRTUAL TABLE IF NOT EXISTS book_knowledge USING fts5(
+  book UNINDEXED, ku_id UNINDEXED, corpus_version UNINDEXED, type UNINDEXED,
+  name, problem, content, chapter UNINDEXED, pages UNINDEXED, metadata UNINDEXED
+);`;
+
+async function openDb(projectRoot: string, dbPath?: string): Promise<NativeDb | { error: string }> {
+  let sqliteUrl: string;
+  try {
+    const req = createRequire(join(projectRoot, 'package.json'));
+    sqliteUrl = pathToFileURL(req.resolve('better-sqlite3')).href;
+  } catch {
+    return { error: 'better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
+  }
+  const path = dbPath ?? bookKbPath(projectRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const { default: Database } = (await import(sqliteUrl)) as { default: new (p: string) => NativeDb };
+  const db = new Database(path);
+  db.pragma('journal_mode = WAL');
+  db.pragma('busy_timeout = 5000');
+  db.exec(SCHEMA);
+  return db;
+}
+
+/**
+ * Upsert a batch of KUs for a book. Idempotent per (book, kuId): existing rows for the same
+ * kuId are replaced, and — since a re-ingest changes `corpusVersion` — every row for the book
+ * whose corpus_version differs from this batch's is evicted (stale-corpus cleanup), so the KB
+ * mirrors exactly the current ingest. Best-effort: returns an honest error, never throws.
+ */
+export async function putBookKnowledge(
+  projectRoot: string,
+  kus: readonly BookKU[],
+  opts: { dbPath?: string } = {},
+): Promise<{ upserted: number; evicted: number; error?: string }> {
+  if (kus.length === 0) return { upserted: 0, evicted: 0 };
+  // Precondition (QE P3): a batch must be one book at one corpus_version — the eviction below is
+  // keyed on that. Reject a mixed batch instead of silently leaving stale rows.
+  const book = kus[0]!.book;
+  const corpusVersion = kus[0]!.corpusVersion;
+  if (kus.some((k) => k.book !== book || k.corpusVersion !== corpusVersion)) {
+    return { upserted: 0, evicted: 0, error: 'putBookKnowledge: batch must share one book + corpus_version' };
+  }
+  const opened = await openDb(projectRoot, opts.dbPath);
+  if ('error' in opened) return { upserted: 0, evicted: 0, error: opened.error };
+  const db = opened;
+  try {
+    // Atomic (QE P2): eviction + all inserts in ONE transaction — a mid-batch failure rolls the
+    // eviction back too, so we never lose rows and never leave a half-written book.
+    const del = db.prepare('DELETE FROM book_knowledge WHERE book = ? AND corpus_version != ?');
+    const delKu = db.prepare('DELETE FROM book_knowledge WHERE book = ? AND ku_id = ?');
+    const ins = db.prepare(`INSERT INTO book_knowledge
+      (book, ku_id, corpus_version, type, name, problem, content, chapter, pages, metadata)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const run = db.transaction(() => {
+      const evicted = (del.run(book, corpusVersion) as { changes?: number }).changes ?? 0;
+      for (const ku of kus) {
+        delKu.run(ku.book, ku.kuId);
+        ins.run(
+          ku.book, ku.kuId, ku.corpusVersion, ku.type, ku.name, ku.problem, ku.content,
+          ku.chapter ?? null, ku.pages ? JSON.stringify(ku.pages) : null,
+          ku.metadata ? JSON.stringify(ku.metadata) : null,
+        );
+      }
+      return { upserted: kus.length, evicted };
+    });
+    return run() as { upserted: number; evicted: number };
+  } catch (err) {
+    return { upserted: 0, evicted: 0, error: `book-kb upsert failed (rolled back): ${err instanceof Error ? err.message : String(err)}` };
+  } finally {
+    db.close();
+  }
+}
+
+/** Lexical (FTS5) search over the book KB. `book` filters to one book. Never throws. */
+export async function queryBookKnowledge(
+  projectRoot: string,
+  query: string,
+  opts: { limit?: number; book?: string; dbPath?: string } = {},
+): Promise<{ hits: BookKUHit[]; error?: string }> {
+  const path = opts.dbPath ?? bookKbPath(projectRoot);
+  if (!existsSync(path)) return { hits: [] };
+  const opened = await openDb(projectRoot, opts.dbPath);
+  if ('error' in opened) return { hits: [], error: opened.error };
+  const db = opened;
+  try {
+    const limit = opts.limit ?? 10;
+    // Build the FTS5 MATCH by AND-ing individually-quoted TERMS (QE P2): quoting the whole query as
+    // one phrase forced strict adjacency (a big recall regression); per-term quoting keeps
+    // injection safety (special chars stay literal inside each phrase) while allowing any-order
+    // matches. Empty/all-punctuation query → no MATCH (return no hits) rather than an FTS5 error.
+    const terms = query.split(/\s+/).map((t) => t.replace(/[^\p{L}\p{N}]+/gu, '')).filter(Boolean);
+    if (terms.length === 0) return { hits: [] };
+    const match = terms.map((t) => `"${t}"`).join(' AND ');
+    const rows = (opts.book !== undefined
+      ? db.prepare('SELECT book, ku_id, type, name, problem, content, chapter, pages FROM book_knowledge WHERE book_knowledge MATCH ? AND book = ? ORDER BY rank LIMIT ?').all(match, opts.book, limit)
+      : db.prepare('SELECT book, ku_id, type, name, problem, content, chapter, pages FROM book_knowledge WHERE book_knowledge MATCH ? ORDER BY rank LIMIT ?').all(match, limit)
+    ) as Array<{ book: string; ku_id: string; type: string; name: string; problem: string; content: string; chapter: string | null; pages: string | null }>;
+    return {
+      hits: rows.map((r) => ({
+        book: r.book, kuId: r.ku_id, type: r.type, name: r.name, problem: r.problem, content: r.content,
+        ...(r.chapter !== null ? { chapter: r.chapter } : {}),
+        ...(r.pages !== null ? { pages: JSON.parse(r.pages) as number[] } : {}),
+      })),
+    };
+  } catch (err) {
+    return { hits: [], error: `book-kb query failed: ${err instanceof Error ? err.message : String(err)}` };
+  } finally {
+    db.close();
+  }
+}

package/src/index.ts

@@ -25,9 +25,13 @@ export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
 export { buildRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, discoverSkillPackDirs } from './registry.js';
 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 { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, BOOST_CAP, recordPattern, loadStorePatternsSync, patternToRecord, recordToPattern, consolidateSessions, recallPatterns, pruneNoisePatterns } from './patterns.js';
+export type { PatternRecord, SessionRecord, LearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, SessionsSource, PruneNoiseResult } from './patterns.js';
 export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf, AGENTDB_WRITER_VERSION } from './setup.js';
+export { indexPatternsToAgentdb, resolveAgentdbPath } from './agentdb-index.js';
+export { putBookKnowledge, queryBookKnowledge, bookKbPath } from './book-kb.js';
+export type { BookKU, BookKUHit } from './book-kb.js';
+export type { AgentdbRow, AgentdbIndexResult } from './agentdb-index.js';
 export { generatePlugin } from './plugin.js';
 export type { PluginManifest } from './plugin.js';
 export type { SetupOptions, SetupResult, SetupStep } from './setup.js';

package/src/operations.ts

@@ -526,6 +526,24 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
       detail: '.claude/mcp.json is NOT loaded by Claude Code — re-run dz setup to register agentdb in .mcp.json (project root)',
     });
   }
+  // Flat dz hook entries (dz ≤0.3.43 emitted `{type,command}` without the matcher-group wrapper)
+  // are silently IGNORED by Claude Code — the writer never fires. Detect and point at the fix.
+  try {
+    const { commandsOf } = await import('./setup.js');
+    const settings = JSON.parse(readFileSync(join(root, '.claude', 'settings.json'), 'utf-8')) as {
+      hooks?: Record<string, unknown[]>;
+    };
+    const flatDz = Object.values(settings.hooks ?? {}).flat().filter((entry) =>
+      !Array.isArray((entry as { hooks?: unknown[] })?.hooks) &&
+      commandsOf(entry).some((cmd) => cmd.includes('agentdb-writer.mjs') || cmd.includes('sessions.jsonl')));
+    if (flatDz.length > 0) {
+      checks.push({
+        name: 'agentdb hooks shape',
+        ok: false,
+        detail: `${flatDz.length} dz hook entr(ies) use the legacy flat shape Claude Code ignores (writer never fires) — re-run dz setup to migrate`,
+      });
+    }
+  } catch { /* settings absent/unreadable — covered by other checks */ }
   const writerPath = join(root, '.dz', 'agentdb-writer.mjs');
   if (existsSync(writerPath)) {
     const { writerVersionOf, AGENTDB_WRITER_VERSION } = await import('./setup.js');

package/src/publish.ts

@@ -180,6 +180,10 @@ export function orderByDependencies<T extends { name: string; dir: string }>(pkg
  * pre-setting the future version by hand). Exact-old-token matching keeps every other version
  * string (dependency pins, historical notes, examples citing other releases) untouched.
  * Returns the pre-sync README text for failure restore, or undefined when nothing was rewritten.
+ *
+ * Bootstrap invariant: exact-token matching MAINTAINS sync but cannot REPAIR pre-existing drift
+ * (a footer already one release behind contains a token != oldVersion and is skipped). Bring the
+ * footer to the current package.json version once; the mechanism owns it from then on.
  */
 export function syncReadmeVersion(dir: string, oldVersion: string, newVersion: string): string | undefined {
   const readmePath = join(dir, 'README.md');

package/src/registry.ts

@@ -8,7 +8,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 /**
@@ -31,16 +31,24 @@ export function skillPackBaseDirs(cwd: string): string[] {
     if (!bases.includes(dir)) bases.push(dir);
   };
 
-  add(join(cwd, 'packages', '@dzhechkov'));
-  add(join(cwd, 'node_modules', '@dzhechkov'));
+  // Extra @scopes and local pack roots from `.dz/config.json` (ADR-001 v2): makes packs in other
+  // npm scopes (e.g. a private @mybooks registry) OR arbitrary local dirs first-class for
+  // discovery — the path for generated book packs distributed privately, not via public @dzhechkov.
+  const { skillScopes, skillDirs } = readSkillDiscoveryConfig(cwd);
+  const scopes = ['@dzhechkov', ...skillScopes];
 
-  // Self-location: harness-core is always co-installed with the skill packs (they are
-  // siblings under the same `@dzhechkov` dir, or one `node_modules` hop away). Walk up.
+  for (const scope of scopes) add(join(cwd, 'packages', scope));
+  for (const scope of scopes) add(join(cwd, 'node_modules', scope));
+
+  // Self-location: harness-core is co-installed with the skill packs (siblings under the same
+  // scope dir, or one `node_modules` hop away). Walk up for each configured scope.
   try {
     let dir = dirname(fileURLToPath(import.meta.url)); // .../@dzhechkov/harness-core/dist
     for (let depth = 0; depth < 8; depth += 1) {
-      if (basename(dir) === '@dzhechkov') add(dir);
-      add(join(dir, 'node_modules', '@dzhechkov'));
+      for (const scope of scopes) {
+        if (basename(dir) === scope) add(dir);
+        add(join(dir, 'node_modules', scope));
+      }
       const parent = dirname(dir);
       if (parent === dir) break;
       dir = parent;
@@ -49,9 +57,25 @@ export function skillPackBaseDirs(cwd: string): string[] {
     // import.meta.url unavailable (unexpected in ESM) — cwd scans still apply.
   }
 
+  // Arbitrary local pack roots (each directly contains `skills-*` dirs). Resolved against cwd.
+  for (const d of skillDirs) add(resolve(cwd, d));
+
   return bases.filter((dir) => existsSync(dir));
 }
 
+/** Read `discovery.skillScopes[]` / `discovery.skillDirs[]` from `.dz/config.json` (empty on any error). */
+function readSkillDiscoveryConfig(cwd: string): { skillScopes: string[]; skillDirs: string[] } {
+  try {
+    const cfg = JSON.parse(readFileSync(join(cwd, '.dz', 'config.json'), 'utf-8')) as {
+      discovery?: { skillScopes?: unknown; skillDirs?: unknown };
+    };
+    const arr = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []);
+    return { skillScopes: arr(cfg.discovery?.skillScopes), skillDirs: arr(cfg.discovery?.skillDirs) };
+  } catch {
+    return { skillScopes: [], skillDirs: [] };
+  }
+}
+
 /** List `skills-*` pack directories across all base dirs, de-duplicated by pack name (first wins). */
 export function discoverSkillPackDirs(cwd: string): { pack: string; dir: string }[] {
   const seen = new Set<string>();
@@ -155,6 +179,8 @@ function categoryFromPack(pack: string): string {
     pack.includes('presentation')
   )
     return 'product';
+  // Digitized-book knowledge packs (ADR-001 book-knowledge-digitizer)
+  if (pack.includes('book')) return 'knowledge';
   return 'other';
 }
 

package/src/setup.ts

@@ -157,6 +157,17 @@ export function writerVersionOf(content: string): number {
 }
 
 /** Generate Claude Code hooks configuration for self-learning. */
+/**
+ * Commands of a Claude Code hook entry in EITHER shape: the valid matcher-group form
+ * `{matcher?, hooks:[{type,command}]}` or the legacy flat `{type,command}` that dz ≤0.3.43
+ * emitted (Claude Code silently ignores flat entries — the writer-hooks bug; migrated on setup).
+ */
+export function commandsOf(entry: unknown): string[] {
+  const e = entry as { command?: unknown; hooks?: { command?: unknown }[] };
+  if (Array.isArray(e?.hooks)) return e.hooks.map((h) => String(h?.command ?? ''));
+  return [String(e?.command ?? '')];
+}
+
 export function generateHooksConfig(projectRoot: string, backend: MemoryBackend): string {
   const dzDir = join(projectRoot, '.dz');
 
@@ -165,10 +176,13 @@ export function generateHooksConfig(projectRoot: string, backend: MemoryBackend)
     // (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');
+    // Claude Code's hooks schema requires MATCHER-GROUP entries: `[{ hooks: [{type, command}] }]`.
+    // A flat `[{type, command}]` is silently ignored by Claude Code (QE find: writer hooks never
+    // fired), so wrap every entry. Session events take no matcher.
     return JSON.stringify({
       hooks: {
-        SessionStart: [{ type: 'command', command: `node ${JSON.stringify(writer)} start` }],
-        SessionEnd: [{ type: 'command', command: `node ${JSON.stringify(writer)} end` }],
+        SessionStart: [{ hooks: [{ type: 'command', command: `node ${JSON.stringify(writer)} start` }] }],
+        SessionEnd: [{ hooks: [{ type: 'command', command: `node ${JSON.stringify(writer)} end` }] }],
       },
     }, null, 2);
   }
@@ -181,8 +195,8 @@ export function generateHooksConfig(projectRoot: string, backend: MemoryBackend)
     `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: jsonlCmd('start') }],
-      SessionEnd: [{ type: 'command', command: jsonlCmd('end') }],
+      SessionStart: [{ hooks: [{ type: 'command', command: jsonlCmd('start') }] }],
+      SessionEnd: [{ hooks: [{ type: 'command', command: jsonlCmd('end') }] }],
     },
   }, null, 2);
 }
@@ -500,7 +514,7 @@ export function runSetup(opts: SetupOptions): SetupResult {
     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 }[]>;
+      hooks: Record<string, { hooks: { type: string; command: string }[] }[]>;
     };
 
     if (!existsSync(settingsPath)) {
@@ -515,11 +529,14 @@ export function runSetup(opts: SetupOptions): SetupResult {
         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.
+          // Drop dz-generated entries (any vintage, either shape) — keep the user's own hooks
+          // untouched. Flat dz entries (≤0.3.43) are dropped too, migrating them to the valid
+          // matcher-group shape appended below.
           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;
+            const cmds = commandsOf(entry);
+            const isDz = cmds.some((cmd) => cmd.includes('agentdb add') || cmd.includes('agentdb-writer.mjs') || cmd.includes('sessions.jsonl'));
+            const isFlat = !Array.isArray((entry as { hooks?: unknown[] })?.hooks);
+            if (isDz && (isFlat || cmds.some((cmd) => cmd.includes('agentdb add')))) replacedLegacy = true;
             return !isDz;
           });
           const next = [...kept, ...generated.hooks[event]!];
@@ -605,10 +622,10 @@ export function runSetup(opts: SetupOptions): SetupResult {
     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 }[]>;
+        hooks?: Record<string, unknown[]>;
       };
       const refs = ['SessionStart', 'SessionEnd'].every((ev) =>
-        (settings.hooks?.[ev] ?? []).some((h) => String(h?.command ?? '').includes('agentdb-writer.mjs')));
+        (settings.hooks?.[ev] ?? []).some((h) => commandsOf(h).some((cmd) => cmd.includes('agentdb-writer.mjs'))));
       if (!refs) problems.push('hooks do not invoke the writer');
     } catch {
       problems.push('settings.json unreadable');