@pcircle/memesh 4.4.0 → 4.5.1

package/scripts/hooks/_shared.js

@@ -1,7 +1,7 @@
 import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'fs';
 import { spawn } from 'child_process';
 import { createRequire } from 'module';
-import { homedir } from 'os';
+import { MemeshDatabase } from './_generated/sqlite.js';
 import { dirname, join } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 
@@ -23,7 +23,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 // did, but the copy is byte-locked to core and CI-gated (`git diff` on rebuild +
 // `tests/hooks/mirror-parity.test.ts`), making drift structurally impossible.
 //
-// Re-exported here so all 7 hooks keep importing these names from `_shared.js`
+// Re-exported here so all 6 hooks keep importing these names from `_shared.js`
 // unchanged.
 import {
   memeshDir,
@@ -126,28 +126,17 @@ export function readHookConfig(_env = process.env) {
   }
 }
 
-/**
- * Resolve the agentic-orchestration opt-in flag.
- * Precedence: env > config > default(false).
- * Env semantics preserved: only `=== '1'` enables (avoids accidental
- * truthy unlock from a stray env value).
- *
- * @param {NodeJS.ProcessEnv} [env=process.env]
- * @returns {boolean}
- */
-export function isAgenticOrchestrationEnabled(env = process.env) {
-  const envVal = env.MEMESH_ENABLE_AGENTIC_ORCHESTRATION;
-  if (envVal !== undefined) return envVal === '1';
-  const cfg = readHookConfig(env);
-  return cfg.enableAgenticOrchestration === true;
-}
-
 /**
  * Resolve the auto-capture flag.
  * Precedence: env > config > default(true).
  * Env semantics preserved: explicit `=== 'false'` disables; any other
  * value (including undefined) leaves it on or defers to config.
  *
+ * src/core/doctor.ts duplicates this precedence (isAutoCaptureOff — the
+ * TS/hook-JS bundle boundary forbids sharing code). A semantic change here
+ * MUST be mirrored there, or doctor starts reasoning about a disabled state
+ * the hooks don't agree on.
+ *
  * @param {NodeJS.ProcessEnv} [env=process.env]
  * @returns {boolean}
  */
@@ -180,6 +169,19 @@ export function resolveSessionLimit(env = process.env) {
   return 10;
 }
 
+/**
+ * The tag every capture hook attaches to what it writes.
+ *
+ * `memesh doctor`'s hook-activity row counts THIS to answer "is the
+ * auto-capture loop alive" — it used to answer from entity type, and one of
+ * those types is what `memesh learn` writes by hand. The constant lives in
+ * `src/core/types.ts` for the TypeScript side; the hooks are plain .js loaded
+ * by Claude Code and cannot import it, so this is the one mirror.
+ * `tests/auto-capture-provenance.test.ts` fails if the two ever disagree, or
+ * if a capture hook stops writing it.
+ */
+export const AUTO_CAPTURE_TAG = 'source:auto-capture';
+
 const VALID_AUTO_UPDATE_POLICIES = new Set(['off', 'patch', 'minor', 'major']);
 
 /**
@@ -251,13 +253,11 @@ CREATE TABLE IF NOT EXISTS tags (
 
 CREATE INDEX IF NOT EXISTS idx_tags_entity ON tags(entity_id);
 CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag);
-DELETE FROM tags
-WHERE id NOT IN (
-  SELECT MIN(id)
-  FROM tags
-  GROUP BY entity_id, tag
-);
-CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_entity_tag_unique ON tags(entity_id, tag);
+-- The tags dedup DELETE + idx_tags_entity_tag_unique creation live in
+-- ensureTagsUniqueIndex(), AFTER this exec — the DELETE is a one-time
+-- migration, and a DML statement in this string made every open start a
+-- write transaction even when it deleted nothing (same reader-breaking
+-- pattern as the hook_runs_since note below).
 CREATE INDEX IF NOT EXISTS idx_observations_entity ON observations(entity_id);
 CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity_id);
 CREATE INDEX IF NOT EXISTS idx_relations_to ON relations(to_entity_id);
@@ -276,6 +276,44 @@ CREATE TABLE IF NOT EXISTS memesh_metadata (
   key   TEXT PRIMARY KEY,
   value TEXT NOT NULL
 );
+
+-- Proof that a capture hook actually RAN. Nothing else in this schema can
+-- give it: every other signal is "a row was written", and "the hook ran and
+-- found nothing worth saving" is the healthy case that produces no row at
+-- all. So a quiet day and a dead capture loop were byte-identical in the
+-- database, and the one doctor message that had to cover both cried wolf on
+-- the first and stayed silent on the second.
+--
+-- Written by the three hooks that hold a read-write handle (Stop, PreCompact,
+-- PostToolUse), each calling recordHookRun() at its own SUCCESSFUL exit —
+-- after capture, not at open. Stamping at open certified the wrong thing: a
+-- hook that opened the database and then died mid-capture looked alive for a
+-- day. "Successful" is precise: a completed capture, or a well-formed
+-- payload the hook correctly decided not to capture (dedup, low-signal
+-- session). A malformed payload (schema-flip shapes) and a write that did
+-- not land both leave no stamp — either would make the heartbeat mask the
+-- exact dropout it exists to expose. The recall-side hooks open read-only
+-- and deliberately do not appear here: their liveness answers a different
+-- question, and giving them a write handle would put a lock acquisition on
+-- the SessionStart hot path.
+--
+-- One row per hook, upserted. It does not grow.
+CREATE TABLE IF NOT EXISTS hook_runs (
+  hook        TEXT PRIMARY KEY,
+  last_run_at TIMESTAMP NOT NULL,
+  run_count   INTEGER NOT NULL DEFAULT 0
+);
+
+-- The 'hook_runs_since' metadata key (when this database first became able
+-- to record hook runs) is stamped by ensureHookRunsSince() AFTER this exec,
+-- NOT here. It used to be an INSERT OR IGNORE in this string, and that made
+-- every open — including opens that only ever read — start a write
+-- transaction: an INSERT statement takes the WAL writer lock even when
+-- OR IGNORE ends up changing nothing. Two states regressed from "reads work"
+-- to "open throws": a peer holding the writer lock past busy_timeout, and a
+-- read-only database FILE (measured: "attempt to write a readonly database"
+-- killed recall along with capture). The helper SELECTs first and writes
+-- only when the key is genuinely absent — once per database lifetime.
 `;
 
 // FTS5 virtual table — separate so hooks that don't need it stay lean.
@@ -304,171 +342,19 @@ CREATE VIRTUAL TABLE IF NOT EXISTS fts_vocab USING fts5vocab(entities_fts, 'row'
  * @param {boolean} [opts.fts=false] - Also create the FTS5 virtual table.
  * @returns {{ db: any, dbPath: string }}
  */
-// Cached lookup for the better-sqlite3 native module. Plugin-marketplace
-// installs ship the tarball without node_modules OR with a node_modules
-// tree that lacks the compiled .node binding. tryRequireBetterSqlite()
-// returns null in either scenario and lets each caller silent-skip —
-// callers paired with a working dev/npm-global registration still produce
-// output. The require() call alone is NOT sufficient: better-sqlite3's
-// `lib/index.js` defers the bindings() call until the first
-// `new Database()`, so a successful require() can still hand back a
-// constructor that throws "Could not locate the bindings file" on use.
-// We probe with an in-memory DB to force the binding load up-front.
-function _inTestEnv() {
-  return process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
-}
-
-let _cachedDatabaseCtor;
-export function tryRequireBetterSqlite() {
-  // Test-only seam: force the "native module unavailable" branch so
-  // tests can exercise the silent-skip path that plugin-marketplace
-  // cache installs hit. Gated to test environments so an accidental
-  // shell export cannot disable memesh on a real user's machine.
-  if (_inTestEnv() && process.env.MEMESH_TEST_FORCE_MISSING_NATIVE === '1') return null;
-  if (_cachedDatabaseCtor !== undefined) return _cachedDatabaseCtor;
-  try {
-    const Database = require('better-sqlite3');
-    // Second test-only seam: simulate the exact plugin-marketplace cache
-    // failure mode where require() succeeds (JS wrapper present) but the
-    // native .node is missing, so the first construction throws. Same
-    // test-env gate as the seam above.
-    if (_inTestEnv() && process.env.MEMESH_TEST_FORCE_BINDING_LOAD_FAIL === '1') {
-      throw new Error('Could not locate the bindings file. (test forced)');
-    }
-    const probe = new Database(':memory:');
-    probe.close();
-    _cachedDatabaseCtor = Database;
-  } catch (err) {
-    // Stderr-trace-then-silent: an empty catch would collapse plugin-
-    // marketplace's "no .node binding" case together with ABI mismatches,
-    // disk full, fd exhaustion, OOM, and tampered native modules — all
-    // distinct causes with distinct fixes. Following the project's hook
-    // pattern (e.g. session-summary.js, post-commit.js), we surface a
-    // single line on stderr (NOT stdout — Claude Code's hook contract
-    // requires stdout stays a single JSON document or empty) and let
-    // each caller continue its silent-skip behavior. The stderr trace
-    // is visible to anyone running `memesh doctor` or inspecting hook
-    // exit logs; it does NOT reach the Claude Code conversation.
-    try {
-      const code = err && typeof err === 'object' && 'code' in err ? err.code : '';
-      const msg = (err && typeof err === 'object' && 'message' in err ? err.message : String(err)) || 'unknown';
-      process.stderr.write(`[memesh hook] better-sqlite3 probe failed: ${code} ${msg}\n`);
-    } catch {
-      // stderr write itself failed (closed pipe, etc.) — give up silently.
-    }
-    // Self-heal for the plugin-marketplace silent-dropout class of bug.
-    // When Claude Code's `/plugin install` runs `npm install --ignore-scripts`
-    // (security default), better-sqlite3's `install` script never fetches
-    // / builds the native binding. Result: `require()` returns a JS
-    // wrapper but `new Database()` throws "Could not locate the bindings
-    // file" — and every hook silently exits without writing entities.
-    // Without this self-heal, the user has no signal that auto-capture
-    // is broken; the DB just stays empty forever.
-    //
-    // Strategy: spawn a detached `npm rebuild better-sqlite3` in the
-    // package root so the *next* hook invocation succeeds. Cap to one
-    // attempt per hour per package root via an exclusive-create marker
-    // so a crash-loop can't drive a rebuild storm. Skipped under test
-    // env (tests deliberately exercise the failure path).
-    if (!_inTestEnv()) {
-      _attemptBetterSqliteRebuild();
-    }
-    _cachedDatabaseCtor = null;
-  }
-  return _cachedDatabaseCtor;
-}
-
-function _attemptBetterSqliteRebuild() {
-  try {
-    // Package root = parent of the scripts/hooks/ directory that contains
-    // this file. That's where memesh's own `package.json` lives.
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkgRoot = dirname(dirname(here));
-    if (!existsSync(join(pkgRoot, 'package.json'))) return;
-    // Resolve better-sqlite3's actual install location via Node's normal
-    // resolution algorithm, which follows hoisting (the consumer's
-    // top-level node_modules holds the package when memesh is installed
-    // as a dependency). Looking at `<pkgRoot>/node_modules/better-sqlite3`
-    // directly would false-negative on every hoisted install.
-    let bsqliteDir;
-    try {
-      // `require.resolve` returns the path to `lib/index.js` inside the
-      // package. Walk up to the package directory.
-      const entry = require.resolve('better-sqlite3', { paths: [pkgRoot] });
-      // `<bsqliteDir>/lib/index.js` → walk back twice to the package root.
-      bsqliteDir = dirname(dirname(entry));
-    } catch {
-      // Genuinely not installed anywhere on the resolution path. `npm
-      // rebuild` cannot help; the user needs a full install.
-      try {
-        process.stderr.write(
-          `[memesh hook] better-sqlite3 is not installed (Node could not resolve from ${pkgRoot}). `
-          + `Run: cd to the project that depends on @pcircle/memesh and run \`npm install\`.\n`,
-        );
-      } catch {}
-      return;
-    }
-    // The hoisted install location's package root — npm rebuild needs to
-    // be run from a project that owns this node_modules tree. Walking
-    // up to the nearest directory that has its own package.json gives
-    // us the right cwd.
-    let rebuildCwd = dirname(bsqliteDir);
-    while (rebuildCwd !== dirname(rebuildCwd)) {
-      if (existsSync(join(rebuildCwd, 'package.json')) && !rebuildCwd.endsWith('node_modules')) break;
-      rebuildCwd = dirname(rebuildCwd);
-    }
-    const memesh = join(homedir(), '.memesh');
-    try { mkdirSync(memesh, { recursive: true, mode: 0o700 }); } catch {}
-    const markerPath = join(memesh, 'last-rebuild-attempt.lock');
-    // Atomic one-shot claim via O_EXCL. Once the marker exists, every
-    // future hook bails — no stale-cleanup-then-recreate dance, which
-    // would open a TOCTOU window (stat → unlink → open is racy: a peer
-    // can insert between any two steps and the result is either a
-    // double-spawn of `npm rebuild` or one peer's fresh marker being
-    // stomped by another peer's stale-cleanup).
-    //
-    // Trade-off: if the rebuild fails, the marker blocks retries until
-    // the user removes it manually. That's acceptable because the
-    // stderr breadcrumb below tells the user the exact manual command,
-    // and `memesh doctor` will also surface the failure. A retry-loop
-    // here would either re-introduce the race or burn CPU on a broken
-    // npm config.
-    try {
-      const fd = openSync(markerPath, 'wx', 0o600);
-      try { writeFileSync(fd, String(Date.now())); } finally { closeSync(fd); }
-    } catch (err) {
-      if (err && err.code === 'EEXIST') return; // peer / prior attempt owns it
-      return; // any other write failure — bail silently
-    }
-    process.stderr.write(
-      `[memesh hook] Attempting to rebuild better-sqlite3 in background — `
-      + `next session should capture normally. (rebuildCwd: ${rebuildCwd})\n`
-      + `[memesh hook] To retry later, manually: rm "${markerPath}" && `
-      + `cd "${rebuildCwd}" && npm rebuild better-sqlite3\n`,
-    );
-    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const child = spawn(npm, ['rebuild', 'better-sqlite3'], {
-      cwd: rebuildCwd,
-      detached: true,
-      stdio: 'ignore',
-      windowsHide: true,
-    });
-    // 'error' is emitted asynchronously (e.g. npm not on PATH). Without a
-    // listener it becomes an uncaught exception that the outer sync
-    // try/catch cannot catch — and a hook crash here would turn a silent
-    // dropout into a louder broken-hook story. Swallow it: self-heal is
-    // best-effort by design, and the binding probe already left a stderr
-    // breadcrumb explaining the manual fix.
-    child.on('error', () => {});
-    child.unref();
-  } catch {
-    // Best-effort — never let self-heal failures crash the hook.
-  }
-}
+// No native-binding probe, and nothing to self-heal.
+//
+// This is where ~160 lines used to live: a cached require() of
+// better-sqlite3, an in-memory construction to force the deferred bindings
+// load, two test seams to simulate the failure, and a detached
+// `npm rebuild` with an O_EXCL marker so a crash-loop could not storm it.
+// All of it existed because better-sqlite3 ships a compiled binary that
+// `npm install --ignore-scripts` never builds — and Claude Code's
+// `/plugin install` uses exactly that flag, so every hook silently did
+// nothing. node:sqlite is part of the runtime: there is no binary to
+// miss, so the failure mode and its whole recovery apparatus are gone.
 
 export function openHookDb(env = process.env, opts = {}) {
-  const Database = tryRequireBetterSqlite();
-  if (!Database) return null;
 
   // Path helpers read process.env directly (no-arg). The `env` parameter
   // is kept on this signature for backward compatibility with callers
@@ -479,10 +365,58 @@ export function openHookDb(env = process.env, opts = {}) {
   const dbDir = env.MEMESH_DB_PATH ? dirname(env.MEMESH_DB_PATH) : memeshDir();
   if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
 
-  const db = new Database(dbPath);
+  // `allowExtension` matches src/db.ts: it only permits a later
+  // `enableLoadExtension(true)`, and session-summary.js needs one to load
+  // sqlite-vec through this handle. The switch itself stays off.
+  const db = new MemeshDatabase(dbPath, { allowExtension: true });
   db.pragma('journal_mode = WAL');
   db.pragma('foreign_keys = ON');
+  // Bringing the schema current is a WRITE, and "cannot migrate" must not
+  // mean "cannot open": a database file that is read-only but behind on
+  // schema (a pre-upgrade backup, a permissions accident) dies on the
+  // CREATE TABLE any release adds. If the FILE refuses writes, open it for
+  // what it can still do — reads; capture writes fail individually at
+  // their own guarded call sites. Any other error still throws. Mirrors
+  // initialiseDatabase() in src/db.ts — keep the two in lockstep.
+  try {
+    migrateHookDbToCurrent(db, opts);
+  } catch (err) {
+    if (!/readonly database|SQLITE_READONLY/i.test(err?.message || '')) throw err;
+    try {
+      process.stderr.write(
+        'MeMesh: the database file is read-only, so schema migration was skipped — ' +
+          'opened for reads only. Capture and migrations resume when the file is writable.\n',
+      );
+    } catch { /* stderr gone */ }
+  }
+
+
+  // No heartbeat here. This helper used to stamp `hook_runs` as soon as the
+  // handle was usable, and that stamped-then-crashed hooks into looking
+  // alive: a hook that opened the database and then died in its own capture
+  // logic — the failure class this table exists to expose — read as PASS in
+  // `memesh doctor` for the next 24 hours. Each capture hook now calls
+  // recordHookRun() itself at every SUCCESSFUL exit (including "ran, nothing
+  // worth saving"), so a mid-capture throw leaves no stamp.
+
+  return { db, dbPath };
+}
+
+/**
+ * Everything that makes a hook-opened handle CURRENT: schema, FTS,
+ * one-time migrations and the segmentation rebuild. Split from
+ * openHookDb() so the read-only-file tolerance there has a single
+ * boundary to wrap — every statement in here may write, and none of
+ * them is load-bearing for reading what the database already holds.
+ * Mirrors migrateToCurrentSchema() in src/db.ts — keep in lockstep.
+ *
+ * @param {import('./_generated/sqlite.js').MemeshDatabase} db
+ * @param {{fts?: boolean}} opts
+ */
+function migrateHookDbToCurrent(db, opts) {
   db.exec(SCHEMA_SQL);
+  ensureTagsUniqueIndex(db);
+  ensureHookRunsSince(db);
   if (opts.fts) db.exec(FTS_SQL);
 
   // Apply the full migration chain — keep in lockstep with src/db.ts.
@@ -554,8 +488,160 @@ export function openHookDb(env = process.env, opts = {}) {
   // delete failed, the stale row survived alongside the new one, and the user
   // saw "database disk image is malformed" on hook stderr.
   if (opts.fts) ensureHookFtsSegmentation(db);
+}
 
-  return { db, dbPath };
+/**
+ * One-time tags dedup + unique-index creation, guarded so it never writes
+ * once the index exists. Mirror of ensureTagsUniqueIndex() in src/db.ts —
+ * hooks cannot import from dist/. Keep the two in lockstep.
+ *
+ * @param {import('./_generated/sqlite.js').MemeshDatabase} db
+ */
+export function ensureTagsUniqueIndex(db) {
+  try {
+    const present = db
+      .prepare("SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = 'idx_tags_entity_tag_unique'")
+      .get();
+    if (present) return;
+    // One IMMEDIATE transaction, not two autocommit statements: exec runs
+    // each statement in its own transaction, so a crash or a busy peer
+    // between them could commit the DELETE with the index never created —
+    // and a concurrent pre-index writer could re-insert a duplicate pair in
+    // that window, failing the CREATE with a constraint error. BEGIN
+    // IMMEDIATE holds the write lock across both, so the dedup and the
+    // index land together or not at all (CREATE INDEX is transactional in
+    // SQLite).
+    db.exec(
+      'BEGIN IMMEDIATE; ' +
+        'DELETE FROM tags WHERE id NOT IN (SELECT MIN(id) FROM tags GROUP BY entity_id, tag); ' +
+        'CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_entity_tag_unique ON tags(entity_id, tag); ' +
+        'COMMIT;',
+    );
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch { /* no transaction open */ }
+    try {
+      process.stderr.write(
+        `MeMesh: could not create the tags unique index (${err?.message ?? err}). ` +
+          `Reads are unaffected; the next open retries the dedup and index together.\n`,
+      );
+    } catch { /* stderr gone; nothing left to say */ }
+  }
+}
+
+/**
+ * Stamp 'hook_runs_since' once per database lifetime — read-first, so an
+ * open that only ever reads stays a reader.
+ *
+ * Mirror of ensureHookRunsSince() in src/db.ts — hooks cannot import from
+ * dist/. Keep the two in lockstep; the full rationale (the INSERT used to
+ * live inside SCHEMA_SQL and made read-only database files unopenable)
+ * lives on the src copy.
+ *
+ * @param {import('./_generated/sqlite.js').MemeshDatabase} db
+ */
+export function ensureHookRunsSince(db) {
+  try {
+    const row = db
+      .prepare("SELECT value FROM memesh_metadata WHERE key = 'hook_runs_since'")
+      .get();
+    if (row) {
+      // A marker that exists but cannot be read as a past UTC timestamp
+      // (corrupt text, a rolled-over pseudo-date, a wrong clock stamping the
+      // future) would grant doctor's "tracking just started" grace FOREVER —
+      // a fail-open. Heal it HERE, because this is a write path that runs on
+      // every real open; doctor is a reader (reachable via GET /v1/doctor)
+      // and must not repair the database it inspects. Same parse rules as
+      // doctor's hoursSince: anchored, UTC, round-tripped.
+      const m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/.exec(row.value ?? '');
+      if (m) {
+        const then = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]);
+        const d = new Date(then);
+        const intact = Number.isFinite(then)
+          && d.getUTCFullYear() === +m[1] && d.getUTCMonth() === +m[2] - 1 && d.getUTCDate() === +m[3]
+          && d.getUTCHours() === +m[4] && d.getUTCMinutes() === +m[5] && d.getUTCSeconds() === +m[6];
+        if (intact && then <= Date.now() + 5 * 60 * 1000) return;
+      }
+      db
+        .prepare("UPDATE memesh_metadata SET value = datetime('now') WHERE key = 'hook_runs_since'")
+        .run();
+      return;
+    }
+    db
+      .prepare("INSERT OR IGNORE INTO memesh_metadata (key, value) VALUES ('hook_runs_since', datetime('now'))")
+      .run();
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `MeMesh: could not stamp hook_runs_since (${err?.message ?? err}). ` +
+          `Reads are unaffected; doctor's hook-activity tracking starts once the database is writable.\n`,
+      );
+    } catch { /* stderr gone; nothing left to say */ }
+  }
+}
+
+/**
+ * Stamp a hook's heartbeat from a path that has no database handle open.
+ *
+ * session-summary's low-signal bails (non-agentic session, vanished
+ * transcript, fewer than three tool calls) decide "nothing worth saving"
+ * BEFORE opening the database — and a correct nothing-to-do decision is a
+ * successful run that must stamp, or a user whose sessions are consistently
+ * short reads as "capture has stopped" in doctor within a day: the exact
+ * crying-wolf this table exists to end. Stop fires once per session, so one
+ * extra open+close here is noise.
+ *
+ * Never throws: the heartbeat is diagnostics, and the bail it decorates was
+ * already a successful exit.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} hook
+ */
+export function stampHookRunOnly(env, hook) {
+  try {
+    const { db } = openHookDb(env);
+    try { recordHookRun(db, hook); } finally { db.close(); }
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `MeMesh: could not stamp the ${hook} heartbeat on a no-capture exit (${err?.message ?? err}).\n`,
+      );
+    } catch { /* stderr gone */ }
+  }
+}
+
+/**
+ * Record that `hook` ran, right now.
+ *
+ * This is the only evidence in the system that a hook EXECUTED, as opposed to
+ * a hook having captured something. Doctor could previously only count
+ * auto-captured entities, which conflates the healthy "ran, nothing worth
+ * saving" with the fatal "never ran" — see the `hook_runs` comment in
+ * SCHEMA_SQL.
+ *
+ * A failure here must never take the hook down with it: the heartbeat is
+ * diagnostics, and a session that captured its work but could not stamp the
+ * row is far better than one that threw. But it is not swallowed either — it
+ * writes to stderr, because a heartbeat that silently stops recording would
+ * recreate the exact blind spot it exists to close.
+ */
+export function recordHookRun(db, hook) {
+  try {
+    db.prepare(
+      `INSERT INTO hook_runs (hook, last_run_at, run_count)
+       VALUES (?, datetime('now'), 1)
+       ON CONFLICT(hook) DO UPDATE SET
+         last_run_at = datetime('now'),
+         run_count   = run_count + 1`,
+    ).run(hook);
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `MeMesh: could not record that the ${hook} hook ran (${err?.message ?? err}). ` +
+          `Capture itself is unaffected, but 'memesh doctor' will under-report ` +
+          `hook liveness until this succeeds.\n`,
+      );
+    } catch { /* stderr itself is gone; there is nowhere left to report */ }
+  }
 }
 
 /**
@@ -625,8 +711,8 @@ function ensureHookFtsSegmentation(db) {
 
       db.exec("INSERT INTO entities_fts (entities_fts) VALUES('delete-all')");
 
-      // Paged, not `.iterate()`: better-sqlite3 refuses to run a write while
-      // an iterator is open on the same connection, and writing as we read is
+      // Paged, not `.iterate()`: writing while an iterator is open on the
+      // same connection is not something to rely on, and writing as we read is
       // the point. Keyset pagination on e.id bounds memory to one page.
       const page = db.prepare(
         `SELECT e.id, e.name, COALESCE(group_concat(o.content, ' '), '') AS obs
@@ -711,14 +797,19 @@ function ensureHookFtsSegmentation(db) {
  * deliberately NOT done here: hooks are cheap always-on capture, and those are
  * the heavier, user-initiated `remember` concerns (core owns them).
  *
- * @param {import('better-sqlite3').Database} db - an open hook DB handle
+ * @param {import('./_generated/sqlite.js').MemeshDatabase} db - an open hook DB handle
  * @param {{name: string, type: string, observations?: string[], tags?: string[]}} entity
  * @returns {{ id: number, isNew: boolean } | null} null if the row could not be resolved
  */
 export function captureEntity(db, { name, type, observations = [], tags = [] }) {
+  // source_host provenance: these hooks only ever run under Claude Code (they
+  // are wired into ~/.claude/settings.json), so a hook-captured entity is by
+  // definition a claude-code capture. Stamped only on the INSERT — an OR
+  // IGNORE re-capture of an existing entity must not overwrite provenance an
+  // earlier writer (possibly another host, via MCP) already recorded.
   const insertResult = db
-    .prepare('INSERT OR IGNORE INTO entities (name, type) VALUES (?, ?)')
-    .run(name, type);
+    .prepare('INSERT OR IGNORE INTO entities (name, type, metadata) VALUES (?, ?, ?)')
+    .run(name, type, JSON.stringify({ provenance: { source_host: 'claude-code' } }));
   const isNew = insertResult.changes > 0;
   const row = db.prepare('SELECT id FROM entities WHERE name = ?').get(name);
   if (!row) return null;