@pcircle/memesh 4.9.3 → 4.10.1

package/scripts/hooks/_shared.js

@@ -1,5 +1,5 @@
-import { appendFileSync, chmodSync, closeSync, constants as fsConstants, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'fs';
-import { createHash } from 'crypto';
+import { appendFileSync, chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'fs';
+import { createHash, randomBytes } from 'crypto';
 import { spawn } from 'child_process';
 import { MemeshDatabase } from './_generated/sqlite.js';
 import { dirname, join } from 'path';
@@ -39,6 +39,39 @@ export { assembleTopologyBlock, buildReferenceContext, extractCitedMemoryIds, DE
 export { readRepoState, repoStateLines } from './_generated/repo-state.js';
 export { matchingGuards, guardFromMetadata } from './_generated/guards.js';
 export { writeCitationRule, citationRulePath, CITATION_RULE_BODY } from './_generated/citation-rule.js';
+// Imported locally (recordHookOutcome below uses them) AND re-exported, so
+// every hook reaches the same definition through one module.
+import {
+  detectHookHost,
+  serializeHookOutcome,
+  trimHookOutcomeLines,
+  HOOK_OUTCOMES_FILENAME,
+  HOOK_OUTCOMES_ROTATE_BYTES,
+} from './_generated/capture-liveness.js';
+export {
+  advanceGraceState,
+  captureLivenessNotice,
+  captureLivenessVerdict,
+  graceInEffect,
+  parseGraceState,
+  parseHookOutcomes,
+  summarizeHookOutcomes,
+  HOOK_OUTCOMES_FILENAME,
+  SKIP_REASONS,
+  isGitCommitCommand,
+} from './_generated/capture-liveness.js';
+export {
+  resolveUpdateNotice,
+  shouldRefreshUpdateCache,
+  readSnooze,
+  writeSnooze,
+  clearSnooze,
+  readJustUpgradedMarker,
+  writeJustUpgradedMarker,
+  clearJustUpgradedMarker,
+  claimJustUpgradedMarker,
+  isStrictlyOlder,
+} from './_generated/update-notice.js';
 import { guardFromMetadata as guardFromMetadataLocal } from './_generated/guards.js';
 
 /**
@@ -454,8 +487,10 @@ function migrateHookDbToCurrent(db, opts) {
  * 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.
+ * crying-wolf this table exists to end. Stop fires at the end of EVERY turn
+ * (#322), so this extra open+close happens once per bailed turn, not once
+ * per session — still cheap enough next to the transcript read the bail
+ * already did to skip.
  *
  * Never throws: the heartbeat is diagnostics, and the bail it decorates was
  * already a successful exit.
@@ -476,6 +511,154 @@ export function stampHookRunOnly(env, hook) {
   }
 }
 
+const NOFOLLOW = typeof fsConstants.O_NOFOLLOW === 'number' ? fsConstants.O_NOFOLLOW : 0;
+const APPEND_NOFOLLOW_FLAGS = fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | NOFOLLOW;
+const READ_NOFOLLOW_FLAGS = fsConstants.O_RDONLY | NOFOLLOW;
+
+/**
+ * Record what `hook` DID, on every exit path (issue #327).
+ *
+ * `recordHookRun` answers "did the hook execute"; this answers "and did it
+ * write anything, and if not, why not". The gap between those two questions
+ * is where two days of an empty graph hid: post-commit was executing on every
+ * Bash call and skipping every one of them, because the commits were made
+ * with `-q` and printed no line to match. From the outside that is
+ * indistinguishable from a hook broken by an upgrade.
+ *
+ * Contract, in the same spirit as `stampHookRunOnly`:
+ *   - NEVER throws. Diagnostics must not take capture down with them.
+ *   - NEVER writes to stdout. The hook output contract is a single JSON
+ *     document or nothing at all; one stray line breaks both hosts.
+ *   - APPENDS one line (O_APPEND), never read-modify-write. SessionStart,
+ *     UserPromptSubmit and a PreToolUse hook fire inside the same second on
+ *     a busy turn: three processes reading the same JSON document and
+ *     writing back what each of them read means the last one wins and the
+ *     other two records are gone — the concurrency that proves a session is
+ *     busy would be the concurrency that erases the proof. An append has no
+ *     read step to lose, and the OS orders the writes.
+ *   - Rotation (keep each hook's last 20 records) is the only rewrite, and it goes
+ *     through temp + rename so a reader sees the old complete file or the
+ *     new one.
+ *
+ * @param {Record<string,string|undefined>} env
+ * `outcome` has four kinds, and the line between the first two is the whole
+ * point of the record: `wrote` means a MEMORY was stored, and nothing else —
+ * it is the numerator of the signal `memesh doctor` uses to answer "is memory
+ * capture still alive". `notified` is for a hook whose effect is text the user
+ * or the model sees: an injected context, a printed warning, a nudge. Six
+ * hooks recorded those as `wrote`, each with its own comment saying it was not
+ * a memory, and the answer to that question was inflated by all six.
+ *
+ * @param {{hook: string, outcome: 'wrote'|'notified'|'skipped'|'error', reason?: string, entity?: string, payload?: object}} info
+ */
+export function recordHookOutcome(env, { hook, outcome, reason, entity, payload }) {
+  try {
+    // getMemeshDirFromDbPath(), not memeshDir(): the record must sit beside
+    // the database it describes. A test (or a user) that points
+    // MEMESH_DB_PATH somewhere else would otherwise split the evidence — a
+    // graph in one directory, the liveness history of the hooks that filled
+    // it in another.
+    const dir = getMemeshDirFromDbPath();
+    ensurePrivateDir(dir);
+    const filePath = join(dir, HOOK_OUTCOMES_FILENAME);
+    const record = {
+      hook,
+      at: new Date().toISOString(),
+      host: detectHookHost(payload ?? null, env),
+      outcome,
+    };
+    // A hook's `reason` is, on the error path, the exception message — which
+    // may echo a credential a failed request or git command surfaced. Skip
+    // reasons are hard-coded literals and pass through unchanged, but the
+    // error ones are redacted before they persist: stderr is transient, this
+    // JSONL file is a permanent, exportable copy.
+    if (reason) record.reason = redactSecrets(String(reason)).slice(0, 200);
+    if (entity) record.entity = redactSecrets(String(entity)).slice(0, 200);
+    // One O_APPEND write of one line. `mode` applies only when the file is
+    // being created, which is the only moment the permission can be set
+    // without a second syscall on the hot path. O_NOFOLLOW: the directory
+    // can be a shared or repository path (MEMESH_DB_PATH), and a planted
+    // symlink named hook-outcomes.jsonl would otherwise turn every hook run
+    // into an append to a file of the planter's choosing. Windows has no
+    // O_NOFOLLOW (the constant is undefined there), so it contributes 0.
+    const fd = openSync(filePath, APPEND_NOFOLLOW_FLAGS, 0o600);
+    try {
+      writeSync(fd, serializeHookOutcome(record));
+    } finally {
+      closeSync(fd);
+    }
+    try { chmodSync(filePath, 0o600); } catch { /* best-effort hardening */ }
+    rotateHookOutcomes(filePath);
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `MeMesh: could not record the ${hook} hook outcome (${err?.message ?? err}). ` +
+          `Capture itself is unaffected, but 'memesh doctor' will under-report capture liveness.\n`,
+      );
+    } catch { /* stderr gone */ }
+  }
+}
+
+/**
+ * The `reason` an outer catch may persist for an exception: its `code` or
+ * class name, never its message.
+ *
+ * A message is not a label, it is a copy of whatever the failure echoed: a
+ * V8 JSON parse error quotes the payload it choked on, an execFileSync error
+ * carries git's stderr and absolute paths. stderr is transient; the outcome
+ * file is permanent, exportable, and rendered into doctor and a pasted issue.
+ * So the file gets `uncaught SyntaxError` / `uncaught ENOENT`, and the full
+ * text goes to stderr where the hook already writes it.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+export function hookErrorReason(err) {
+  const label = (value) => (typeof value === 'string' && /^[A-Za-z][\w-]{0,39}$/.test(value) ? value : null);
+  const e = err && typeof err === 'object' ? err : null;
+  return `uncaught ${label(e?.code) ?? label(e?.name) ?? 'error'}`;
+}
+
+/**
+ * Keep the history bounded, without paying a read on every append.
+ *
+ * A line count would mean reading the file back on the hot path — the read
+ * step O_APPEND exists to remove. A `stat` is cheap, so size is the trigger
+ * and the trim is exact. The rewrite goes through temp + rename: a
+ * concurrent appender may lose ONE line to the swap, which is why the byte
+ * budget is far larger than the window any summary reads.
+ */
+function rotateHookOutcomes(filePath) {
+  let tmpPath = null;
+  try {
+    // One descriptor for both the size check and the read, so the file that
+    // was measured is the file that is read (a stat-then-open pair can be
+    // swapped in between). The size check is the hot path on every append
+    // and needs no random name.
+    let raw;
+    const fd = openSync(filePath, READ_NOFOLLOW_FLAGS);
+    try {
+      if (fstatSync(fd).size <= HOOK_OUTCOMES_ROTATE_BYTES) return;
+      raw = readFileSync(fd, 'utf8');
+    } finally {
+      closeSync(fd);
+    }
+    // An unpredictable name, created exclusively ('wx' = O_CREAT|O_EXCL,
+    // which refuses an existing path — a planted symlink included).
+    // `${pid}.tmp` was guessable, and the plain write followed whatever sat
+    // at that name.
+    tmpPath = `${filePath}.${randomBytes(8).toString('hex')}.tmp`;
+    const trimmed = trimHookOutcomeLines(raw);
+    writeFileSync(tmpPath, trimmed, { encoding: 'utf8', mode: PRIVATE_FILE_MODE, flag: 'wx' });
+    renameSync(tmpPath, filePath);
+  } catch (err) {
+    try { if (tmpPath && existsSync(tmpPath)) unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
+    try {
+      process.stderr.write(`[memesh hook-outcomes] rotation failed for ${filePath}: ${err?.message ?? err}\n`);
+    } catch { /* stderr gone */ }
+  }
+}
+
 /**
  * Record that `hook` ran, right now.
  *
@@ -560,14 +743,20 @@ export { truncateTitle } from './_generated/title.js';
  * hooks stay a cheap always-on capture path and core owns later enrichment.
  *
  * @param {import('./_generated/sqlite.js').MemeshDatabase} db - an open hook DB handle
- * @param {{name: string, type: string, observations?: string[], tags?: string[], title?: string | null, metadata?: Record<string, unknown>}} entity
+ * @param {{name: string, type: string, observations?: string[], tags?: string[], title?: string | null, metadata?: Record<string, unknown>, replace?: boolean}} entity
  *   `metadata` is extra INSERT-only metadata (e.g. post-commit's session_id +
  *   files). It cannot override the provenance/title_source stamps below, and
  *   an OR IGNORE re-capture of an existing entity leaves it untouched — same
- *   first-writer-wins rule provenance already follows.
- * @returns {{ id: number, isNew: boolean } | null} null if the row could not be resolved
+ *   first-writer-wins rule provenance already follows. `replace` (#322)
+ *   restates the entity's observations and tags instead of adding to them —
+ *   for a caller whose entity is a per-turn SNAPSHOT, not an accumulating log.
+ *   Unlike `remember({ replace: true })` in core, this is a HARD delete: no
+ *   `replaced_history` is kept (see the comment at the DELETE below for why).
+ * @returns {{ id: number, isNew: boolean, archived?: true } | null} null if the row
+ *   could not be resolved; `archived: true` if `replace` was requested on an
+ *   entity `forget` archived — nothing was written, by design
  */
-export function captureEntity(db, { name, type, observations = [], tags = [], title, metadata }) {
+export function captureEntity(db, { name, type, observations = [], tags = [], title, metadata, replace = false }) {
   // One transaction, because this function performs six writes that only
   // mean anything together: the entity row, its observations, its tags, and
   // the contentless-FTS delete + insert that make them findable.
@@ -586,10 +775,10 @@ export function captureEntity(db, { name, type, observations = [], tags = [], ti
   // could not be resolved. `observationsWritten` may be lower than
   // `observations.length`: an observation whose exact content is already on
   // the entity is not stored again (see the dedupe in captureEntityInner).
-  return db.transaction(() => captureEntityInner(db, { name, type, observations, tags, title, metadata }))();
+  return db.transaction(() => captureEntityInner(db, { name, type, observations, tags, title, metadata, replace }))();
 }
 
-function captureEntityInner(db, { name, type, observations, tags, title, metadata }) {
+function captureEntityInner(db, { name, type, observations, tags, title, metadata, replace }) {
   // 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
@@ -606,10 +795,36 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
     .prepare('INSERT OR IGNORE INTO entities (name, type, metadata, title) VALUES (?, ?, ?, ?)')
     .run(name, type, JSON.stringify(insertMetadata), title ?? null);
   const isNew = insertResult.changes > 0;
-  const row = db.prepare('SELECT id, title FROM entities WHERE name = ?').get(name);
+  const row = db.prepare('SELECT id, title, status, metadata FROM entities WHERE name = ?').get(name);
   if (!row) return null;
   const id = row.id;
 
+  // `replace` never touches an archived entity. src/core/operations.ts's
+  // `remember({ replace: true })` REFUSES this case with a thrown error —
+  // right for a rare, interactive call the user reads the response of, but
+  // a hook must never throw (it would abort the OTHER two entities' writes
+  // this Stop, and crash risk is exactly what this file exists to avoid).
+  // So the hook path degrades to a silent no-op instead: the archived row,
+  // its observations and its FTS absence are all left exactly as `forget`
+  // left them.
+  //
+  // Without this, a whole-entity `forget` (archiveEntity: status flipped to
+  // 'archived', its row removed from entities_fts) would come undone on the
+  // next Stop — `replace` would overwrite the preserved observations with a
+  // fresh derivation from the transcript and reinsert the entity into
+  // entities_fts, un-hiding it from FTS keyword search even though its
+  // status stays 'archived' (recall's default query filters status='active',
+  // which caps but does not close that exposure). `removeFromFts` guards its
+  // own delete on a rowid COUNT, so calling it on an already-removed row is
+  // a safe no-op either way — this check is about not losing the user's
+  // forgotten content, not about a contentless-FTS5 delete failure.
+  //
+  // Observation-level corrections remain active and are filtered below;
+  // this branch preserves the separate whole-entity archive contract.
+  if (replace && !isNew && row.status === 'archived') {
+    return { id, isNew: false, archived: true };
+  }
+
   // Title update on an EXISTING entity — INSERT OR IGNORE never touches
   // `title` when the row already exists, so mirror knowledge-graph.ts's
   // createEntity(): only an explicit, actually-different value writes
@@ -655,6 +870,38 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
   // BY + the one join rule), via the generated fts-index copy.
   const prevObsText = isNew ? undefined : indexedObservationText(db, id);
 
+  // `replace`: the caller is restating the whole entity, not adding to it.
+  //
+  // Appending is right for a `commit-<sha>` or a `pre-compact-<id>`, where
+  // each capture is a new fact about the same subject. It is wrong for a
+  // session insight, whose three entities are a SNAPSHOT of one session: Stop
+  // fires at the end of every turn, so appending stored the same sentences
+  // over and over (measured: 56 observations, 16 unique) and the workaround —
+  // capture once, then skip — froze a two-day session's memory at its first
+  // turn (#322). Replacing is the third answer: the snapshot is rewritten, so
+  // it is neither duplicated nor stale.
+  //
+  // The old rows go AFTER `prevObsText` was read above, so the contentless-FTS
+  // delete still matches exactly what was indexed. The re-insert below must
+  // then leave that text out.
+  //
+  // This is a HARD delete — no history kept. That is a deliberate difference
+  // from `remember({ replace: true })` in src/core/operations.ts, which files
+  // the old text into `metadata.replaced_history` before overwriting: that
+  // path is a rare, user-invoked correction, where an audit trail is worth
+  // the bytes. This path fires on every Stop, every turn, for a session that
+  // can run for hours — keeping history here would mean growing metadata on
+  // every single turn for content nobody asks to undo.
+  if (replace && !isNew) {
+    db.prepare('DELETE FROM observations WHERE entity_id = ?').run(id);
+    // Tags get the same treatment, for the same reason: "restating the whole
+    // entity" was true for observations and FTS but not for tags until this
+    // line — a session-<id>-files entity that stopped mentioning file A kept
+    // answering `file:a.ts` lookups (pre-edit-recall's Strategy 1) for a
+    // snapshot that no longer said anything about that file.
+    db.prepare('DELETE FROM tags WHERE entity_id = ?').run(id);
+  }
+
   // Never store the same sentence twice on one entity (#240, widened).
   //
   // #240 was fixed in session-summary.js alone, with an EXISTENCE guard: "if
@@ -683,12 +930,18 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
   // the "database disk image is malformed" failure this file warns about
   // above. The `seen` set also collapses repeats WITHIN one call.
   const seen = new Set(
-    isNew
+    // `|| replace`: the rows a plain SELECT would find here were just
+    // DELETEd above (same transaction), so this skips a query that would
+    // only ever come back empty — not a second dedup path.
+    isNew || replace
       ? []
       : db.prepare('SELECT content FROM observations WHERE entity_id = ?').all(id).map((r) => r.content),
   );
   const freshObservations = [];
+  const forgotten = parseEntityMetadata(row.metadata)?.forgotten_observation_hashes;
+  const excluded = new Set(replace && Array.isArray(forgotten) ? forgotten : []);
   for (const obs of observations) {
+    if (excluded.has(createHash('sha256').update(obs).digest('hex'))) continue;
     if (seen.has(obs)) continue;
     seen.add(obs);
     freshObservations.push(obs);
@@ -711,7 +964,9 @@ function captureEntityInner(db, { name, type, observations, tags, title, metadat
   // Stop/PreCompact/PostToolUse capture, and the re-read grew with an
   // upserted entity's accumulated observation count.
   const obsParts = [];
-  if (prevObsText) obsParts.push(prevObsText);
+  // Not after a `replace`: those rows were deleted above, and carrying their
+  // text forward would index words the entity no longer holds.
+  if (prevObsText && !replace) obsParts.push(prevObsText);
   if (freshObservations.length) obsParts.push(joinIndexedObservations(freshObservations));
   const allObsText = joinIndexedObservations(obsParts);
   // Current title is fully determined by the branches above — no re-read.
@@ -903,6 +1158,23 @@ export function finalizeUpdatePromptClaim(sessionId, currentVersion, latestVersi
   }
 }
 
+/**
+ * The owner answered this session's notice. After this, further words in the
+ * same session ("no" to an unrelated question, a stray "never") are not
+ * decisions about updates. Returns false when there was no claim to mark.
+ */
+export function markUpdatePromptAnswered(sessionId, currentVersion, latestVersion, decision) {
+  const path = updatePromptClaimPath(sessionId, currentVersion, latestVersion);
+  if (!path || !existsSync(path)) return false;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    writePrivateJson(path, { ...value, decision: 'answered', answer: decision, answeredAt: new Date().toISOString() });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function readUpdatePromptClaim(sessionId, currentVersion, latestVersion) {
   const path = updatePromptClaimPath(sessionId, currentVersion, latestVersion);
   if (!path || !existsSync(path)) return null;
@@ -968,14 +1240,30 @@ export function writeAutoUpdateConsent(sessionId, currentVersion, latestVersion,
   }
 }
 
+/**
+ * Owner's answer to the first-use update notice.
+ *   'approved' — install (npm-global only; other channels have no in-session installer)
+ *   'declined' — "Not now": snooze this target (24h, then 48h, then 7d)
+ *   'never'    — "Never ask again": config.updateCheck = false
+ */
 export function parseAutoUpdateConsent(prompt) {
   if (typeof prompt !== 'string') return null;
   const value = prompt.trim().toLowerCase().replace(/[.!?。！？]+$/u, '');
+  // "never" alone is NOT enough: it is an ordinary English word, and this
+  // hook sees every prompt in a session that was shown the notice. The
+  // phrases below are the ones the Settings hint tells users to type, in
+  // each of the 11 dashboard locales.
+  if (/^(?:never ask(?: me)?(?: again)?|don'?t ask(?: me)?(?: again)?|stop asking|不要再問|別再問|不再提醒|不要再问|今後は確認しない|다시 묻지 않기|não voltar a perguntar|ne plus demander|nicht mehr fragen|không hỏi lại|no volver a preguntar|ไม่ต้องถามอีก)$/.test(value)) return 'never';
   if (/^(?:yes|y|upgrade|update|install(?: it)?|go ahead|是|好|升級|更新|安裝)$/.test(value)) return 'approved';
-  if (/^(?:no|n|not now|later|不要|不用|稍後|暫時不要)$/.test(value)) return 'declined';
+  if (/^(?:no|n|not now|later|不要|不用|稍後|暫時不要|稍后|後で|나중에|agora não|pas maintenant|jetzt nicht|để sau|ahora no|ไว้ก่อน)$/.test(value)) return 'declined';
   return null;
 }
 
+/** `config.updateCheck` — false means the owner said never ask again. */
+export function isUpdateCheckEnabled(env = process.env) {
+  return readHookConfig(env).updateCheck !== false;
+}
+
 export function decideAutoUpdateHook(currentVersion, cache, policy) {
   if (!cache || cache.currentVersion !== currentVersion) return { run: false };
   const latest = cache.latestVersion;