@pcircle/memesh 4.9.3 → 4.10.1

package/scripts/hooks/guard-check.js

@@ -28,20 +28,42 @@ import {
   matchingGuards,
   guardWarningLines,
   recordGuardFires,
+  hookErrorReason,
+  SKIP_REASONS,
+  recordHookOutcome,
 } from './_shared.js';
 import { MemeshDatabase } from './_generated/sqlite.js';
 
 const dbPath = getDbPath();
 
+// See post-commit.js for why every exit path leaves a record (#327). This
+// hook never writes a MEMORY. It bumps the guard-fire counter and injects a
+// warning, so its outcome is `notified`, not `wrote`: doctor's `writes`
+// answers "is memory capture still alive", and counting a printed warning
+// there inflated the numerator of the one signal that question has. A run of
+// skips here is normal, and the record exists to distinguish "no guard
+// matched" from "never ran".
+let payload = null;
+function record(outcome, reason, entity) {
+  recordHookOutcome(process.env, { hook: 'guard-check', outcome, reason, entity, payload });
+}
+
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { input += chunk; });
 process.stdin.on('end', () => {
   try {
     const data = JSON.parse(input);
+    payload = data;
     const command = data?.tool_input?.command;
-    if (!command || typeof command !== 'string') return pass();
-    if (!existsSync(dbPath)) return pass();
+    if (!command || typeof command !== 'string') {
+      record('skipped', SKIP_REASONS.noBashCommand);
+      return pass();
+    }
+    if (!existsSync(dbPath)) {
+      record('skipped', SKIP_REASONS.noDatabaseForGuards);
+      return pass();
+    }
 
     // `readOnly`, not `readonly`: node:sqlite ignores the lowercase
     // spelling and hands back a WRITABLE handle. This hook only reads;
@@ -57,9 +79,13 @@ process.stdin.on('end', () => {
     } finally {
       db.close();
     }
-    if (!matches || matches.length === 0) return pass();
+    if (!matches || matches.length === 0) {
+      record('skipped', SKIP_REASONS.noGuardMatched);
+      return pass();
+    }
 
     recordGuardFires(dbPath, matches.map((g) => g.lessonId));
+    record('notified', undefined, `guard-fires:${matches.length}`);
 
     console.log(JSON.stringify({
       hookSpecificOutput: {
@@ -72,6 +98,7 @@ process.stdin.on('end', () => {
     // Never crash Claude Code, but trace — a silent break here means
     // every accepted guard stops firing and nothing reports it.
     try { process.stderr.write(`[memesh guard-check] ${err?.message || err}\n`); } catch {}
+    record('error', hookErrorReason(err));
     pass();
   }
 });

package/scripts/hooks/post-commit.js

@@ -1,7 +1,203 @@
 #!/usr/bin/env node
 
 import { execFileSync } from 'child_process';
-import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, recordHookRun, truncateTitle } from './_shared.js';
+import { createHash, randomBytes } from 'crypto';
+import { chmodSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { MemeshDatabase } from './_generated/sqlite.js';
+import { isAbsolute, join, resolve } from 'path';
+import { AUTO_CAPTURE_TAG, SKIP_REASONS, captureEntity, ensurePrivateDir, getMemeshDirFromDbPath, getProjectName, isAutoCaptureEnabled, isGitCommitCommand, openHookDb, hookErrorReason, recordHookOutcome, recordHookRun, truncateTitle } from './_shared.js';
+
+const HEAD_MARKER_DIR = 'post-commit-heads';
+const FULL_SHA = /^[a-f0-9]{40,64}$/;
+const MAX_COMMITS_PER_RUN = 20;
+// Leave time to record an error before the host's five-second hook deadline.
+const MARKER_LOCK_TIMEOUT_MS = 1000;
+
+function gitText(cwd, args) {
+  return execFileSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    timeout: 5000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+function validStoredHeads(parsed) {
+  const heads = {};
+  if (parsed?.heads && typeof parsed.heads === 'object') {
+    for (const [key, head] of Object.entries(parsed.heads)) {
+      if (/^[a-f0-9]{64}$/.test(key) && typeof head === 'string' && FULL_SHA.test(head)) heads[key] = head;
+    }
+  }
+  return heads;
+}
+
+function closestKnownAncestor(cwd, head, candidates) {
+  let closest = null;
+  let distance = Number.POSITIVE_INFINITY;
+  for (const candidate of new Set(candidates)) {
+    if (!FULL_SHA.test(candidate)) continue;
+    try {
+      execFileSync('git', ['-C', cwd, 'merge-base', '--is-ancestor', candidate, head], {
+        timeout: 5000,
+        stdio: ['ignore', 'ignore', 'ignore'],
+      });
+      const count = Number.parseInt(gitText(cwd, ['rev-list', '--count', `${candidate}..${head}`]), 10);
+      if (Number.isFinite(count) && count < distance) {
+        closest = candidate;
+        distance = count;
+      }
+    } catch {}
+  }
+  return closest;
+}
+
+/** Resolve one repository's current HEAD and its privacy-preserving per-worktree state. */
+function resolveHeadLocation(cwd) {
+  const rawCommonDir = gitText(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  const commonDir = realpathSync(isAbsolute(rawCommonDir) ? rawCommonDir : resolve(cwd, rawCommonDir));
+  const rawGitDir = gitText(cwd, ['rev-parse', '--path-format=absolute', '--git-dir']);
+  const gitDir = realpathSync(isAbsolute(rawGitDir) ? rawGitDir : resolve(cwd, rawGitDir));
+  const key = createHash('sha256').update(commonDir).digest('hex');
+  const worktreeKey = createHash('sha256').update(gitDir).digest('hex');
+  const markerDir = join(getMemeshDirFromDbPath(), HEAD_MARKER_DIR);
+  const markerPath = join(markerDir, `${key}.json`);
+  return { markerDir, markerPath, worktreeKey };
+}
+
+function resolveHeadState(cwd, location) {
+  const head = gitText(cwd, ['rev-parse', '--verify', 'HEAD']);
+  if (!FULL_SHA.test(head)) throw new Error('git returned an invalid HEAD');
+  let parsed = null;
+  try {
+    parsed = JSON.parse(readFileSync(location.markerPath, 'utf8'));
+  } catch {
+    // Missing or malformed state is the same safe boundary: establish a
+    // baseline and never guess which existing commits belonged to this run.
+  }
+  const heads = validStoredHeads(parsed);
+  const legacyHead = typeof parsed?.head === 'string' && FULL_SHA.test(parsed.head) ? parsed.head : null;
+  // A stored worktree position can stop being an ancestor after reset or
+  // rebase. Re-prove ancestry every time, then fall back only to another
+  // known position Git proves is on the current history.
+  const previous = closestKnownAncestor(cwd, head, [
+    ...(heads[location.worktreeKey] ? [heads[location.worktreeKey]] : []),
+    ...Object.values(heads),
+    ...(legacyHead ? [legacyHead] : []),
+  ]);
+  const short = gitText(cwd, ['rev-parse', '--short', head]);
+  const subject = gitText(cwd, ['show', '-s', '--format=%s', head]);
+  let branch = 'unknown';
+  try { branch = gitText(cwd, ['branch', '--show-current']) || 'detached'; } catch {}
+  return { head, previous, short, subject, branch, ...location };
+}
+
+function acquireMarkerLock(markerPath) {
+  // Keep one stable file: SQLite releases its OS lock on close or process death.
+  // Never unlink/rename it; pathname-based stale recovery can steal a new owner.
+  // This is separate from the graph so a baseline need not create user memories.
+  const db = new MemeshDatabase(`${markerPath}.lock.sqlite`);
+  try {
+    db.pragma(`busy_timeout = ${MARKER_LOCK_TIMEOUT_MS}`);
+    db.exec('BEGIN IMMEDIATE');
+  } catch (err) {
+    db.close();
+    if (err?.errcode === 5 || err?.code === 'SQLITE_BUSY') {
+      throw new Error('timed out waiting for post-commit state lock', { cause: err });
+    }
+    throw err;
+  }
+  return () => db.close();
+}
+
+/** Advance only this worktree's position. The caller holds the repository marker lock. */
+function writeHeadState(state) {
+  ensurePrivateDir(state.markerDir);
+  const tmp = `${state.markerPath}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    let heads = {};
+    try { heads = validStoredHeads(JSON.parse(readFileSync(state.markerPath, 'utf8'))); } catch {}
+    heads[state.worktreeKey] = state.head;
+    writeFileSync(tmp, JSON.stringify({ version: 2, heads }), { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    renameSync(tmp, state.markerPath);
+    try { chmodSync(state.markerPath, 0o600); } catch {}
+  } catch (err) {
+    try { unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+function commitsFromState(cwd, state) {
+  const raw = gitText(cwd, [
+    'rev-list', '--reverse', `--max-count=${MAX_COMMITS_PER_RUN}`, `${state.previous}..${state.head}`,
+  ]);
+  const hashes = raw.split('\n').map((line) => line.trim()).filter((line) => FULL_SHA.test(line));
+  const total = Number.parseInt(gitText(cwd, ['rev-list', '--count', `${state.previous}..${state.head}`]), 10);
+  return {
+    commits: hashes.map((hash) => ({
+      hash: gitText(cwd, ['rev-parse', '--short', hash]),
+      message: gitText(cwd, ['show', '-s', '--format=%s', hash]),
+      branch: state.branch,
+      batch: hashes.length > 1 || total > 1,
+    })),
+    skipped: Number.isFinite(total) ? Math.max(0, total - hashes.length) : 0,
+  };
+}
+
+function captureCommit(db, data, projectName, commit) {
+  const entityName = `commit-${commit.hash}`;
+  const observations = [commit.message, `Branch: ${commit.branch}`];
+  try {
+    const stat = gitText(data.cwd, ['show', '--stat', '--format=', commit.hash]);
+    if (stat) {
+      const statLines = stat.split('\n').filter((line) => line.trim());
+      const summary = statLines[statLines.length - 1]?.trim() || '';
+      if (summary) observations.push(`Diff stats: ${summary}`);
+    }
+  } catch {
+    // Diff stats are best-effort and never decide whether the commit exists.
+  }
+
+  const whyMetadata = {};
+  if (typeof data.session_id === 'string' && data.session_id) whyMetadata.session_id = data.session_id;
+  try {
+    const nameOnly = gitText(data.cwd, ['show', '--name-only', '--format=', commit.hash]);
+    if (nameOnly) {
+      const files = nameOnly.split('\n').map((line) => line.trim()).filter(Boolean);
+      if (files.length > 0) whyMetadata.files = files.slice(0, 50);
+    }
+  } catch {
+    // File names are best-effort metadata, like diff stats.
+  }
+
+  const written = captureEntity(db, {
+    name: entityName,
+    type: 'commit',
+    observations,
+    tags: [AUTO_CAPTURE_TAG, `project:${projectName}`, ...(commit.batch ? ['origin:batch'] : [])],
+    title: truncateTitle(commit.message),
+    metadata: whyMetadata,
+  });
+  return { entityName, written };
+}
+
+// The parsed payload, hoisted so the outcome recorder below can read
+// session_id and the host signal from ANY exit path — including the ones
+// that fire before or instead of a capture.
+let payload = null;
+let releaseStateLock = null;
+
+/**
+ * Leave a record on this exit path (issue #327).
+ *
+ * Every `return exit0()` below is a decision this hook made about a real
+ * event, and until now every one of them was indistinguishable from the hook
+ * not running at all. That is exactly how #321 hid: `git commit -q` prints no
+ * line, so `no commit line in output` fired on every commit for two days and
+ * the graph looked identical to a hook broken by an upgrade.
+ */
+function record(outcome, reason, entity) {
+  recordHookOutcome(process.env, { hook: 'post-commit', outcome, reason, entity, payload });
+}
 
 let input = '';
 process.stdin.setEncoding('utf8');
@@ -12,9 +208,13 @@ process.stdin.on('end', () => {
     // years while its two siblings honoured it — with capture disabled it
     // kept writing commit entities AND stamping the heartbeat, which made
     // doctor's "capture is off, hook silence is expected" message false.
-    if (!isAutoCaptureEnabled(process.env)) return exit0();
+    if (!isAutoCaptureEnabled(process.env)) {
+      record('skipped', SKIP_REASONS.autoCaptureOff);
+      return exit0();
+    }
 
     const data = JSON.parse(input);
+    payload = data;
 
     // tool_name absent is a schema-flip signal (Claude Code has done
     // tool_name renames historically — e.g. tool_use/tool_result
@@ -23,67 +223,117 @@ process.stdin.on('end', () => {
     // `was_in_agentic_loop`).
     if (data.tool_name === undefined) {
       try { process.stderr.write(`[memesh post-commit] tool_name absent in payload (keys: ${Object.keys(data).join(',')}); skipping\n`); } catch {}
+      record('skipped', SKIP_REASONS.toolNameAbsent);
       return exit0();
     }
-    if (data.tool_name !== 'Bash') return exit0();
-
-    // Claude Code's PostToolUse hook payload has had two field-name shapes:
-    // legacy `tool_output: <string>` and current
-    // `tool_response: { stdout, stderr, interrupted, isError }`. Prefer the
-    // current shape; fall back to legacy so unit-test fixtures (which use
-    // tool_output) keep working. This block existed only as the legacy
-    // branch — once Claude Code unified on tool_response the hook silently
-    // stopped seeing any output and never wrote commit entities again.
-    const tr = data.tool_response;
-    let toolOutput = '';
-    if (typeof tr === 'string') {
-      toolOutput = tr;
-    } else if (tr && typeof tr === 'object') {
-      const stdout = typeof tr.stdout === 'string' ? tr.stdout : '';
-      const stderr = typeof tr.stderr === 'string' ? tr.stderr : '';
-      toolOutput = stdout + (stderr ? '\n' + stderr : '');
-    } else if (typeof data.tool_output === 'string') {
-      toolOutput = data.tool_output;
-    } else if (data.tool_output != null) {
-      toolOutput = JSON.stringify(data.tool_output);
+    if (data.tool_name !== 'Bash') {
+      record('skipped', SKIP_REASONS.notBash);
+      return exit0();
     }
 
-    // Detect git commit in output
-    // Pattern: [branch hash] commit message — with an optional parenthesised
-    // note between branch and hash: git prints `[master (root-commit) 32e98b8]`
-    // for a repo's FIRST commit, and the old pattern silently skipped exactly
-    // that one, so no repository's first commit was ever remembered.
-    const commitMatch = toolOutput.match(/\[[\w/.-]+(?: \([\w -]+\))? ([a-f0-9]{7,})\] (.+)/);
-    if (!commitMatch) return exit0();
-
-    // The OUTPUT looking like a commit is not evidence that a commit happened.
-    // This hook stopped at the regex above, so any Bash output containing a
-    // commit-shaped line produced a permanent memory. Measured: a payload whose
-    // command was `cat docs/release-notes.md` wrote entity `commit-9f3c2a1`
-    // for a hash `git cat-file -t` rejects as "Not a valid object name".
-    // Reading a changelog, tailing a build log, or quoting a commit line was
-    // enough — and the fake then surfaced through session-start and
-    // pre-edit-recall as if it had happened.
+    // The COMMAND decides whether this run is about a commit at all, and it
+    // is checked BEFORE the output for two reasons.
+    //
+    // First, the output looking like a commit is not evidence that a commit
+    // happened. This hook once stopped at the output regex below, so any Bash
+    // output containing a commit-shaped line produced a permanent memory.
+    // Measured: a payload whose command was `cat docs/release-notes.md` wrote
+    // entity `commit-9f3c2a1` for a hash `git cat-file -t` rejects as "Not a
+    // valid object name".
+    //
+    // Second, the two skips mean opposite things to `memesh doctor` (#327):
+    // "not a git commit command" is this hook correctly ignoring `ls`, on
+    // almost every Bash call, and must not count as silence; "a git commit
+    // ran but printed no commit line" is the #321 shape — a commit happened
+    // and nothing was saved — and is exactly the silence worth a sentence.
     const issuedCommand = typeof data.tool_input?.command === 'string' ? data.tool_input.command : '';
-    if (!/\bgit\b[^|;&]*\bcommit\b/.test(issuedCommand)) {
-      try { process.stderr.write(`[memesh post-commit] output looks like a commit but the command was not a git commit; skipping ${commitMatch[1]}\n`); } catch {}
+    if (!isGitCommitCommand(issuedCommand)) {
+      record('skipped', SKIP_REASONS.notGitCommit);
       return exit0();
     }
 
-    const branchMatch = commitMatch[0].match(/^\[([^\s]+)\s/);
-    const branch = branchMatch ? branchMatch[1] : 'unknown';
+    if (!data.cwd) {
+      try { process.stderr.write('[memesh post-commit] data.cwd absent — cannot resolve project / repo; skipping\n'); } catch {}
+      record('skipped', SKIP_REASONS.commitCwdAbsent);
+      return exit0();
+    }
 
-    const commitHash = commitMatch[1];
-    const commitMsg = commitMatch[2];
+    // Current PostToolUse payloads explicitly say whether the command failed.
+    // Legacy payloads expose only terminal text. That text may corroborate a
+    // successfully resolved HEAD, but it is never commit authority by itself:
+    // wrappers can replay buffered output, while `-q` can hide a real commit.
+    const tr = data.tool_response;
+    let toolOutput = '';
+    if (typeof tr === 'string') toolOutput = tr;
+    else if (tr && typeof tr === 'object') {
+      const stdout = typeof tr.stdout === 'string' ? tr.stdout : '';
+      const stderr = typeof tr.stderr === 'string' ? tr.stderr : '';
+      toolOutput = stdout + (stderr ? `\n${stderr}` : '');
+    } else if (typeof data.tool_output === 'string') toolOutput = data.tool_output;
+    else if (data.tool_output != null) toolOutput = JSON.stringify(data.tool_output);
+    const commitMatch = toolOutput.match(/\[[\w/.-]+(?: \([\w -]+\))? ([a-f0-9]{7,})\] (.+)/);
+    let state = null;
+    let location = null;
+    try { location = resolveHeadLocation(data.cwd); } catch {}
+    if (location) {
+      ensurePrivateDir(location.markerDir);
+      releaseStateLock = acquireMarkerLock(location.markerPath);
+      try { state = resolveHeadState(data.cwd, location); } catch {}
+    }
 
-    // `data.cwd` MUST be present for project-tag and `git show` below
-    // to be correct. If absent, falling through to process.cwd() (the
-    // hook process's launch dir, unspecified for PostToolUse Bash)
-    // would either run git show against a different repo (silent
-    // corruption) or write the wrong project tag. Skip + trace
-    // instead — better to miss one commit than to tag it wrong.
-    if (!data.cwd) {
-      try { process.stderr.write(`[memesh post-commit] data.cwd absent — cannot resolve project / repo; skipping commit ${commitHash}\n`); } catch {}
+    let branch;
+    let commitHash;
+    let commitMsg;
+    let stateBatch = [];
+    let batchSkipped = 0;
+    if (state?.previous && state.previous !== state.head) {
+      const resolved = commitsFromState(data.cwd, state);
+      stateBatch = resolved.commits;
+      batchSkipped = resolved.skipped;
+      const newest = stateBatch.at(-1);
+      if (!newest) {
+        try { process.stderr.write('[memesh post-commit] repository HEAD changed, but no reachable commit could be enumerated\n'); } catch {}
+        record('skipped', SKIP_REASONS.commitHeadUnresolvable);
+        return exit0();
+      }
+      branch = newest.branch;
+      commitHash = newest.hash;
+      commitMsg = newest.message;
+    } else if (state && state.previous === state.head) {
+      // When Git state is available it is stronger evidence than terminal
+      // text. A failed command can return buffered or wrapper-produced text
+      // that looks like an earlier commit; unchanged HEAD must never turn
+      // that stale text into a write or a false liveness heartbeat.
+      try { process.stderr.write('[memesh post-commit] commit-like command completed, but repository HEAD did not change\n'); } catch {}
+      record('skipped', SKIP_REASONS.commitHeadUnchanged);
+      return exit0();
+    } else if (!state) {
+      try { process.stderr.write('[memesh post-commit] commit-like command ran, but repository HEAD could not be resolved\n'); } catch {}
+      record('skipped', SKIP_REASONS.commitHeadUnresolvable);
+      return exit0();
+    } else if (state.previous === null
+      && tr?.isError !== true && tr?.interrupted !== true
+      && commitMatch
+      && state.head.startsWith(commitMatch[1])) {
+      // Success flags are optional across hosts. Accept the commit line only
+      // after Git independently proves that exact hash is HEAD, and never
+      // when the host explicitly reports failure or interruption.
+      branch = state.branch;
+      commitHash = state.short;
+      commitMsg = state.subject;
+    } else if (state.previous === null && tr && typeof tr === 'object' && tr.isError === false && tr.interrupted !== true) {
+      // A current Claude Code PostToolUse payload tells us the command
+      // completed successfully.  In that one case HEAD itself is the newly
+      // created commit, even when `-q` or redirection removed every output
+      // line.  Capture only HEAD: older repository history remains outside
+      // this event and is never backfilled.
+      branch = state.branch;
+      commitHash = state.short;
+      commitMsg = state.subject;
+    } else if (state.previous === null) {
+      writeHeadState(state);
+      try { process.stderr.write('[memesh post-commit] recorded repository HEAD baseline; existing history was not backfilled\n'); } catch {}
+      record('skipped', SKIP_REASONS.commitHeadBaseline);
       return exit0();
     }
     // And the commit has to actually be in THIS repository.
@@ -100,6 +350,7 @@ process.stdin.on('end', () => {
       });
     } catch {
       try { process.stderr.write(`[memesh post-commit] ${commitHash} is not a commit in ${data.cwd}; nothing written\n`); } catch {}
+      record('skipped', SKIP_REASONS.hashNotACommit);
       return exit0();
     }
 
@@ -109,95 +360,35 @@ process.stdin.on('end', () => {
     // Pass fts:true so the FTS5 entity-search index is also available.
     const { db } = openHookDb(process.env, { fts: true });
     try {
-      const entityName = `commit-${commitHash}`;
-
-      // Build the observation set: commit message, branch, and — best-effort —
-      // richer diff stats (git failures are silently ignored, unchanged behavior).
-      const observations = [commitMsg, `Branch: ${branch}`];
-      try {
-        const stat = execFileSync('git', ['show', '--stat', '--format=', commitHash], {
-          cwd: data.cwd || process.cwd(),
-          encoding: 'utf8',
-          timeout: 5000,
-          // stderr captured, not inherited: outside a repo this used to leak
-          // a raw `fatal: not a git repository` into the hook's own stderr.
-          stdio: ['ignore', 'pipe', 'pipe'],
-        }).trim();
-        if (stat) {
-          // Last non-empty line is the summary, e.g. "3 files changed, 45 insertions(+), 12 deletions(-)"
-          const statLines = stat.split('\n').filter(l => l.trim());
-          const summary = statLines[statLines.length - 1]?.trim() || '';
-          if (summary) observations.push(`Diff stats: ${summary}`);
+      const commits = stateBatch.length > 0
+        ? stateBatch
+        : [{ hash: commitHash, message: commitMsg, branch, batch: false }];
+      const captured = [];
+      for (const commit of commits) {
+        const result = captureCommit(db, data, projectName, commit);
+        if (!result.written) {
+          record('error', 'captureEntity did not land the write', result.entityName);
+          return exit0();
         }
-      } catch {
-        // git show failed — no diff stats recorded, existing behavior unchanged
+        captured.push(result.entityName);
       }
 
-      // Commit → session linkage, the hop `memesh why` walks. The payload has
-      // carried session_id all along; this hook just never recorded it, so
-      // every commit entity was an island (no file list, no session, no
-      // relations). Recorded as METADATA, not tags, on purpose: a `file:*`
-      // tag here would make pre-edit-recall inject commit noise into every
-      // edit of a touched file (Strategy 1 joins on exactly that tag).
-      const whyMetadata = {};
-      if (typeof data.session_id === 'string' && data.session_id) {
-        whyMetadata.session_id = data.session_id;
-      }
-      try {
-        const nameOnly = execFileSync('git', ['-C', data.cwd, 'show', '--name-only', '--format=', commitHash], {
-          encoding: 'utf8',
-          timeout: 5000,
-          stdio: ['ignore', 'pipe', 'pipe'],
-        }).trim();
-        if (nameOnly) {
-          // Repo-relative paths, capped: a lockfile-churn commit can touch
-          // thousands of files and metadata rides every entity read.
-          const files = nameOnly.split('\n').map(l => l.trim()).filter(Boolean);
-          if (files.length > 0) whyMetadata.files = files.slice(0, 50);
-        }
-      } catch {
-        // Best-effort like the diff stats above — no file list recorded.
-      }
-
-      // Shared write dance — upsert entity + observations + tags AND reindex FTS.
-      //
-      // `source:auto-capture` is the provenance marker every capture hook
-      // writes (session-summary, pre-compact and the extractor already did;
-      // this one did not). `memesh doctor` counts it to answer "is the
-      // auto-capture loop alive" — a question it used to answer from entity
-      // TYPE, which a hand-typed `memesh learn` satisfied all by itself.
-      // The commit subject IS the title — git authors already wrote a
-      // one-line human summary; nothing to synthesize.
-      //
-      // Re-capture of an already-stored commit is expected and harmless: this
-      // hook runs on PostToolUse, so any later Bash call while HEAD is
-      // unchanged rebuilds the same `commit-<sha>` payload. It used to APPEND
-      // it — three commit entities on the maintainer's graph reached 6
-      // observations / 3 distinct, one triple re-written 107 seconds after the
-      // first. captureEntity now refuses to store an observation whose exact
-      // content is already on the entity (#240, widened), which is the right
-      // guard here rather than "skip if the entity exists": a sha is immutable,
-      // so any line that DOES differ on a later run (diff stats that failed the
-      // first time and succeeded now) is new information and must still land.
-      const written = captureEntity(db, {
-        name: entityName,
-        type: 'commit',
-        observations,
-        tags: [AUTO_CAPTURE_TAG, `project:${projectName}`],
-        title: truncateTitle(commitMsg),
-        metadata: whyMetadata,
-      });
-
-      // Heartbeat AFTER capture, so the stamp certifies "the capture loop
-      // completed", not "a database handle existed". A throw above skips it,
-      // and so does a null return (the write did not land).
-      if (written) recordHookRun(db, 'post-commit');
+      // One hook invocation is one heartbeat even when a merge exposes a
+      // bounded batch. Advance the state only after every selected commit
+      // landed, so a partial database failure is retried instead of forgotten.
+      recordHookRun(db, 'post-commit');
+      if (state) writeHeadState(state);
+      const reason = captured.length > 1 || batchSkipped > 0
+        ? `captured ${captured.length} commits as a batch; skipped ${batchSkipped} older commits`
+        : undefined;
+      record('wrote', reason, captured.at(-1));
     } finally {
       db.close();
     }
   } catch (err) {
     // Never crash Claude Code — but leave a trace for debugging
     try { process.stderr.write(`[memesh post-commit] ${err?.message || err}\n`); } catch {}
+    record('error', hookErrorReason(err));
   }
   // Emit NOTHING on success — not `{"suppressOutput": true}`.
   //
@@ -216,5 +407,10 @@ process.stdin.on('end', () => {
 });
 
 function exit0() {
+  if (releaseStateLock) {
+    const release = releaseStateLock;
+    releaseStateLock = null;
+    try { release(); } catch {}
+  }
   process.exit(0);
 }

package/scripts/hooks/pre-compact.js

@@ -2,7 +2,7 @@
 
 import { basename } from 'path';
 import { existsSync, readFileSync } from 'fs';
-import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, recordHookRun, truncateTitle } from './_shared.js';
+import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, hookErrorReason, SKIP_REASONS, recordHookOutcome, recordHookRun, truncateTitle } from './_shared.js';
 
 // There is no in-process timeout guard, and its absence is deliberate.
 //
@@ -19,6 +19,12 @@ import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled,
 // process. `openHookDb` additionally caps the SQLite lock wait at 2s so
 // contention ends in a skipped capture rather than in that kill.
 
+// See post-commit.js for why every exit path leaves a record (#327).
+let payload = null;
+function record(outcome, reason, entity) {
+  recordHookOutcome(process.env, { hook: 'pre-compact', outcome, reason, entity, payload });
+}
+
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { input += chunk; });
@@ -26,10 +32,12 @@ process.stdin.on('end', () => {
   try {
     // Opt-out check (env > config > default-on)
     if (!isAutoCaptureEnabled(process.env)) {
+      record('skipped', SKIP_REASONS.autoCaptureOff);
       return exit0();
     }
 
     const data = JSON.parse(input);
+    payload = data;
     const sessionId = data.session_id || 'unknown';
     const transcriptPath = data.transcript_path || '';
     // A payload with NEITHER a session id NOR a transcript is not a
@@ -39,6 +47,7 @@ process.stdin.on('end', () => {
     // context as a recent memory. A real session_id without a transcript
     // still records (that contract is pinned by the basic-scenario test).
     if (!data.session_id && !transcriptPath) {
+      record('skipped', SKIP_REASONS.noSessionOrTranscript);
       process.exit(0);
     }
     const cwd = data.cwd || process.cwd();
@@ -137,7 +146,12 @@ process.stdin.on('end', () => {
       // and so does a null return — captureEntity's null means the write did
       // not land, and this very hook tells the user "could not save" below;
       // stamping would say "alive" to doctor about the same failed run.
-      if (written) recordHookRun(db, 'pre-compact');
+      if (written) {
+        recordHookRun(db, 'pre-compact');
+        record('wrote', undefined, entityName);
+      } else {
+        record('error', 'captureEntity did not land the write', entityName);
+      }
     } finally {
       db.close();
     }
@@ -179,6 +193,7 @@ process.stdin.on('end', () => {
   } catch (err) {
     // Hooks must never crash Claude Code — exit cleanly
     try { process.stderr.write(`[memesh pre-compact] ${err?.message || err}\n`); } catch {}
+    record('error', hookErrorReason(err));
   }
   exit0();
 });