@pcircle/memesh 4.9.4 → 4.10.2

package/scripts/hooks/session-summary.js

@@ -6,7 +6,7 @@
 //
 import { createRequire } from 'module';
 import { basename, join } from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeSync } from 'fs';
 import { pathToFileURL } from 'url';
 import {
   AUTO_CAPTURE_TAG,
@@ -20,13 +20,17 @@ import {
   openHookDb,
   readUpdateCheckCache,
   redactSecrets,
+  hookErrorReason,
+  recordHookOutcome,
   recordHookRun,
   stampHookRunOnly,
   resolveAutoUpdatePolicy,
   resolvePluginRoot,
+  SKIP_REASONS,
   spawnAutoUpdate,
   truncateTitle,
 } from './_shared.js';
+import { runStopNotes } from './_stop-notes.js';
 
 const require = createRequire(import.meta.url);
 
@@ -211,13 +215,22 @@ function parseTranscript(transcriptPath) {
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { input += chunk; });
+// See post-commit.js for why every exit path leaves a record (#327).
+let payload = null;
+let pendingSystemMessage = null;
+/** Set by runStopNotes; called by exit0() with whether the nudge went out. */
+let settleNudge = null;
+function record(outcome, reason, entity) {
+  recordHookOutcome(process.env, { hook: 'session-summary', outcome, reason, entity, payload });
+}
+
 process.stdin.on('end', async () => {
   let sessionId = 'unknown';
   try {
-    if (!input.trim()) return exit0();
-
-    // Opt-out check (env > config > default-on)
-    if (!isAutoCaptureEnabled(process.env)) return exit0();
+    if (!input.trim()) {
+      record('skipped', SKIP_REASONS.emptyStdin);
+      return exit0();
+    }
 
     let inputData;
     try {
@@ -230,12 +243,37 @@ process.stdin.on('end', async () => {
         const preview = (input || '').slice(0, 80).replace(/\n/g, ' ');
         process.stderr.write(`[memesh session-summary] malformed stdin JSON (len=${input.length}): ${parseErr?.message || parseErr}; preview="${preview}"\n`);
       } catch {}
+      record('error', 'malformed stdin JSON');
       return exit0();
     }
 
+    payload = inputData;
     sessionId = inputData.session_id || 'unknown';
     const transcriptPath = inputData.transcript_path;
 
+    // Opt-out check (env > config > default-on). Read before the note work
+    // below because ingestion WRITES memories and must honour it; the nudge
+    // writes nothing and runs either way (#324). It used to sit above the
+    // JSON parse, which is why the payload is parsed first now.
+    const captureEnabled = isAutoCaptureEnabled(process.env);
+
+    // #324: ingest the project's note directory and decide the
+    // "decided things, stored nothing" nudge. Records its own outcomes under
+    // `note-ingest` / `remember-nudge`, never throws, and only ever yields
+    // one line for exit0() to print.
+    const stopNotes = await runStopNotes(inputData, {
+      captureEnabled,
+      project: inputData.cwd ? getProjectName(inputData.cwd) : undefined,
+      metaUrl: import.meta.url,
+    });
+    pendingSystemMessage = stopNotes.message;
+    settleNudge = stopNotes.settle;
+
+    if (!captureEnabled) {
+      record('skipped', SKIP_REASONS.autoCaptureOff);
+      return exit0();
+    }
+
     // `cwd` decides the project tag, and the project tag decides which
     // sessions `session-start` injects and which memories `pre-edit-recall`
     // surfaces. Falling back to `process.cwd()` — the hook process's launch
@@ -249,6 +287,7 @@ process.stdin.on('end', async () => {
     // capture than to file it under the wrong project. Same rule here.
     if (!inputData.cwd) {
       try { process.stderr.write(`[memesh session-summary] cwd absent in payload (keys: ${Object.keys(inputData).join(',')}); cannot resolve project, skipping capture\n`); } catch {}
+      record('skipped', SKIP_REASONS.cwdAbsent);
       return exit0();
     }
     const cwd = inputData.cwd;
@@ -279,7 +318,11 @@ process.stdin.on('end', async () => {
     // (empty stdin, malformed JSON, missing cwd) are schema-flip shapes: if
     // Claude Code's payload changed under us, capture is effectively dead,
     // and a heartbeat would mask exactly that.
-    if (!wasAgenticLoop) { stampHookRunOnly(process.env, 'session-summary'); return exit0(); }
+    if (!wasAgenticLoop) {
+      stampHookRunOnly(process.env, 'session-summary');
+      record('skipped', SKIP_REASONS.notAgenticLoop);
+      return exit0();
+    }
     // Trace why we're skipping. Two failure modes:
     //   (a) transcript_path absent — schema flip, Claude Code stopped
     //       sending the field. Same bug shape as `was_in_agentic_loop`
@@ -291,6 +334,7 @@ process.stdin.on('end', async () => {
     // breadcrumb so a schema flip doesn't ship undetected again.
     if (!transcriptPath) {
       try { process.stderr.write(`[memesh session-summary] transcript_path absent in payload (keys: ${Object.keys(inputData).join(',')}); skipping capture\n`); } catch {}
+      record('skipped', SKIP_REASONS.transcriptPathAbsent);
       return exit0();
     }
     if (!existsSync(transcriptPath)) {
@@ -299,6 +343,7 @@ process.stdin.on('end', async () => {
       // race) — the hook itself ran fine, so this stamps. A payload that
       // never carried the field at all (schema flip) bails above, unstamped.
       stampHookRunOnly(process.env, 'session-summary');
+      record('skipped', SKIP_REASONS.transcriptGone);
       return exit0();
     }
 
@@ -310,11 +355,18 @@ process.stdin.on('end', async () => {
     // LOST (permissions, I/O), and a heartbeat here would keep doctor green
     // through exactly the repeated failure it exists to expose. No stamp —
     // parseTranscript already traced the fault to stderr.
-    if (readFailed) return exit0();
+    if (readFailed) {
+      record('error', 'the transcript could not be read');
+      return exit0();
+    }
 
     // Skip sessions with too little activity — the single most common
     // healthy exit, so it MUST stamp (see stampHookRunOnly).
-    if (toolCallCount < 3) { stampHookRunOnly(process.env, 'session-summary'); return exit0(); }
+    if (toolCallCount < 3) {
+      stampHookRunOnly(process.env, 'session-summary');
+      record('skipped', SKIP_REASONS.tooLittleActivity);
+      return exit0();
+    }
 
     const projectName = getProjectName(cwd);
 
@@ -324,35 +376,23 @@ process.stdin.on('end', async () => {
     //
     const { db } = openHookDb(process.env, { fts: true });
     let writeFailed = false;
+    let firstFailedEntity = null;
+    // True once any of the three rules below actually calls storeMemory.
+    // Between the toolCallCount < 3 guard above and Rule 3's >= 20 bar, a
+    // session that ran real commands but edited no file matches none of
+    // them — storeMemory never runs, writeFailed stays false, and without
+    // this flag the outcome below fell through to record('wrote') anyway:
+    // a claimed write with zero entities actually touched.
+    let anyRuleMatched = false;
+    // True only once captureEntity actually lands a write. A matched rule
+    // whose entity is `forget`-archived sets anyRuleMatched but not this —
+    // the archived branch below returns before either flag changes, so a
+    // Stop where every matched rule's target was archived falls through to
+    // the `!anyWrote` branch instead of a false 'wrote' (same bug shape as
+    // the noRuleMatched fix above, one level deeper).
+    let anyWrote = false;
+    let lastWrittenEntity = null;
     try {
-      // Duplicate detection: if we already captured this session, bail.
-      //
-      // Use the FULL session_id rather than the first 8 chars: real
-      // Claude Code UUIDs collide on 8 chars only with cosmically small
-      // probability, but artificial test IDs (verify-fix-001 vs -002)
-      // share the prefix and silently skipped the second session
-      // entirely. The contract is one stored capture per distinct
-      // session_id, so the dedup key has to be the full id.
-      //
-      // A dedup bail is a SUCCESSFUL run — the loop executed and correctly
-      // decided there was nothing to do — so it stamps the heartbeat like
-      // the capture path below does. Only a throw leaves no stamp.
-      // Guard on ANY of this session's three entities, not only `-files`.
-      // A Bash-only session created no `-files` row, so the guard never
-      // tripped and `-summary` was re-appended on every Stop — measured: 56
-      // observations, 16 unique, three commands stored fourteen times each.
-      const alreadyCaptured = db.prepare(
-        "SELECT id FROM entities WHERE name IN (?, ?, ?) LIMIT 1",
-      ).get(`session-${sessionId}-files`, `session-${sessionId}-fixes`, `session-${sessionId}-summary`);
-      if (alreadyCaptured) {
-        recordHookRun(db, 'session-summary');
-        // A duplicate capture is still a completed Stop lifecycle. Update
-        // consent is session-scoped and must not be skipped merely because
-        // the same transcript was observed twice (a common host retry).
-        await runAutoUpdateAtStop(sessionId);
-        return exit0();
-      }
-
       // Build and store session memories
       const baseTags = [AUTO_CAPTURE_TAG, `session:${sessionId}`, `project:${projectName}`];
 
@@ -378,12 +418,51 @@ process.stdin.on('end', async () => {
       // entities_fts too. This copy used to insert entity + observations + tags
       // only, skipping the FTS reindex the sibling hooks did — which left every
       // session-insight memory unrecallable via the FTS keyword path.
+      //
+      // Known tradeoff, not a bug: the three Rule blocks below each call this
+      // function independently, and captureEntity() commits its own
+      // transaction per call. A failure partway through Rule 2 or 3 can leave
+      // an earlier entity (e.g. -files) replaced while a later one is not,
+      // even though the overall Stop is recorded as 'error'. Wrapping all
+      // three in one outer db.transaction() would close that gap (nested
+      // calls become SAVEPOINTs — see MemeshDatabase.transaction() in
+      // src/storage/sqlite.ts) but was deliberately not done here: it widens
+      // the write-lock hold on every Stop (this hook's busy_timeout is
+      // shorter than the harness timeout on purpose), to guard a failure mode
+      // that self-heals — the next Stop rebuilds each entity fresh from the
+      // transcript, since these are snapshots, not accumulations.
       function storeMemory(name, type, observations, tags, title) {
+        anyRuleMatched = true;
+        // `replace`: these three entities are a SNAPSHOT of one session, and
+        // Stop fires at the end of every turn. Appending stored the same
+        // sentences on every turn; skipping after the first froze a two-day
+        // session at its first turn (#322). A snapshot is restated, not added
+        // to.
+        const result = captureEntity(db, { name, type, observations, tags, title, replace: true });
+        if (result?.archived) {
+          // The user `forget`-archived this exact entity. Not a failure —
+          // captureEntity's contract left it untouched on purpose — so it
+          // must not set writeFailed (that would misreport an honoured
+          // `forget` as a broken hook). Traced, not silent (#3d): the next
+          // Stop will try again and say the same thing until the user either
+          // reactivates the entity or the session ends.
+          try { process.stderr.write(`MeMesh: session-summary left "${name}" alone — archived by forget.\n`); } catch {}
+          return;
+        }
         // null = the entity row could not be resolved = this write did NOT
         // happen (captureEntity's contract). A run with a failed write must
         // not stamp the heartbeat below — "alive" would be a lie about the
         // exact thing the heartbeat certifies.
-        if (!captureEntity(db, { name, type, observations, tags, title })) writeFailed = true;
+        if (!result) {
+          writeFailed = true;
+          // First failure, not last: with three independent per-entity
+          // transactions, the first is the root cause — later calls run
+          // regardless and naming one of them would point at a symptom.
+          if (firstFailedEntity === null) firstFailedEntity = name;
+          return;
+        }
+        anyWrote = true;
+        lastWrittenEntity = name;
       }
 
       // No free-form human text exists for these three entities the way a
@@ -393,7 +472,8 @@ process.stdin.on('end', async () => {
       const titleDate = new Date().toISOString().slice(0, 10);
       const titlePrefix = `${titleDate} ${projectName}`;
 
-      // Rule 1: File editing session summary
+      // Rule 1: File editing session summary — name uses the FULL
+      // session_id (tests/core/extractor.test.ts pins why).
       if (filesEdited.length > 0) {
         storeMemory(
           `session-${sessionId}-files`,
@@ -421,7 +501,15 @@ process.stdin.on('end', async () => {
         );
       }
 
-      // Rule 3: Heavy session summary (20+ tool calls = significant work)
+      // Rule 3: Heavy session summary (20+ tool calls = significant work).
+      // This literal is the one place that actually decides the bar; two
+      // doc strings describe it in prose without importing it (this file is
+      // plain JS with no shared constant module, and capture-liveness.ts is
+      // a deliberate zero-import leaf) — src/core/capture-liveness.ts's
+      // SKIP_REASONS.noRuleMatched and src/core/session-insight.ts's own
+      // (HEAVY_SESSION_TOOL_CALLS-derived) copy. A future change to this
+      // number needs both updated by hand, or doctor's text will drift from
+      // what actually happened.
       if (toolCallCount >= 20) {
         storeMemory(
           `session-${sessionId}-summary`,
@@ -548,9 +636,42 @@ process.stdin.on('end', async () => {
               // session so it survives DB restores from either era) plus
               // the compliance denominators: sessions that HAD an injection
               // vs sessions whose transcript carried any citation marker.
+              //
+              // The counters are scoped to the generation named in the stamp.
+              // When a graph that counted under an EARLIER generation meets
+              // this one, they are cleared rather than added to: the
+              // numerator changed meaning (v1 asked "did the transcript
+              // contain any marker", v2 asks "was an id we injected cited"),
+              // so a sum across both is one ratio wearing the newer label and
+              // no key separates the eras. Readers — analytics.ts and
+              // scripts/audit/measure-signals.mjs — read the bare keys and
+              // therefore keep working unchanged; what they report is now
+              // this generation only. A graph that never counted has no
+              // stamp, so nothing resets on a new install.
+              const ACCOUNTING_MODE = 'citation-v2 since 2026-09-12';
+              const priorMode = db.prepare(
+                "SELECT value FROM memesh_metadata WHERE key = 'recall_accounting_mode'"
+              ).get()?.value;
+              if (priorMode && priorMode !== ACCOUNTING_MODE) {
+                // Traced, not silently dropped: the numbers being discarded
+                // are the only record of the previous era, and a reset that
+                // leaves no result record is the silent-skip shape.
+                const prior = (key) => db.prepare('SELECT value FROM memesh_metadata WHERE key = ?').get(key)?.value ?? 'absent';
+                const priorTotal = prior('citation_sessions_total');
+                const priorCited = prior('citation_sessions_cited');
+                db.prepare(
+                  "DELETE FROM memesh_metadata WHERE key IN ('citation_sessions_total', 'citation_sessions_cited')"
+                ).run();
+                try {
+                  process.stderr.write(
+                    `[memesh session-summary] citation accounting generation changed (${priorMode} -> ${ACCOUNTING_MODE}); ` +
+                      `counters reset from total=${priorTotal} cited=${priorCited} — the two eras count different things and are not comparable.\n`,
+                  );
+                } catch {}
+              }
               db.prepare(
                 'INSERT OR REPLACE INTO memesh_metadata (key, value) VALUES (?, ?)'
-              ).run('recall_accounting_mode', 'citation-v1 since 2026-08-16');
+              ).run('recall_accounting_mode', ACCOUNTING_MODE);
               const bump = db.prepare(
                 `INSERT INTO memesh_metadata (key, value) VALUES (?, '1')
                  ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT)`
@@ -584,7 +705,39 @@ process.stdin.on('end', async () => {
       // write did not land must not read as alive. (The recall-effectiveness
       // block catches its own errors — session memories were already stored
       // by then, so the run still counts.)
-      if (!writeFailed) recordHookRun(db, 'session-summary');
+      if (writeFailed) {
+        // Name the entity whose captureEntity call actually returned null —
+        // not a fixed guess. With three independent per-entity writes, a
+        // hardcoded name here would point at the wrong one whenever the
+        // failure was in Rule 1 or 2.
+        record('error', 'captureEntity did not land the write', firstFailedEntity ?? undefined);
+      } else if (!anyRuleMatched) {
+        // Correctly deciding there was nothing to capture is still a
+        // completed run — same stance as the tooLittleActivity skip above,
+        // which stamps too. What it must NOT do is claim 'wrote': that was
+        // this hook's shape for every real-work-but-no-file-edit session
+        // until this branch existed.
+        recordHookRun(db, 'session-summary');
+        // No entity named: by definition no rule matched, so `-files`,
+        // `-fixes` and `-summary` are all equally untouched this Stop —
+        // naming one of them would misreport which entity this record is
+        // about.
+        record('skipped', SKIP_REASONS.noRuleMatched);
+      } else if (!anyWrote) {
+        // A rule DID match, but every entity it targeted was `forget`-
+        // archived — the same false-'wrote' shape as the branch above, one
+        // level deeper (a matched rule that produced no write). Its own
+        // reason, not noRuleMatched: a rule fired, saying otherwise would
+        // hide that.
+        recordHookRun(db, 'session-summary');
+        record('skipped', SKIP_REASONS.allMatchedEntitiesArchived);
+      } else {
+        recordHookRun(db, 'session-summary');
+        // Name the entity that actually landed the write (the last one, if
+        // more than one rule wrote) — not a fixed guess at which of the
+        // three this Stop touched.
+        record('wrote', undefined, lastWrittenEntity ?? undefined);
+      }
     } finally {
       db.close();
     }
@@ -596,6 +749,7 @@ process.stdin.on('end', async () => {
     // failures from this hook; with that branch gone, real capture errors stay
     // visible without crashing the host session.
     try { process.stderr.write(`[memesh session-summary] ${err?.message || err}\n`); } catch {}
+    record('error', hookErrorReason(err));
   }
 
   // Update only after all session work so installed files cannot change while
@@ -619,6 +773,28 @@ process.stdin.on('end', async () => {
 });
 
 function exit0() {
+  // The one thing this hook may print (#324): the nudge. `systemMessage` is
+  // the only Stop output Claude Code shows the user (Stop has no
+  // hookSpecificOutput variant — tests/helpers/hook-output-contract.ts).
+  // Codex's acceptance of it on Stop is NOT verified against a live Codex in
+  // this repository; tests/hooks/cross-host-output-contract.test.ts pins the
+  // exact envelope so a rejection report maps to one line. `suppressOutput`,
+  // which Codex did reject, stays gone. writeSync, not console.log: stdout is a
+  // pipe, and an async pipe write can be cut off by process.exit on macOS.
+  //
+  // The nudge's outcome is decided HERE, by whether the write succeeded —
+  // not by runStopNotes, which cannot know. A host that closed stdout gets
+  // an `error` record and keeps its transcript offset, so the next Stop
+  // judges the same window again instead of losing it to a line nobody read.
+  let delivered = true;
+  if (pendingSystemMessage) {
+    try {
+      writeSync(1, `${JSON.stringify({ systemMessage: pendingSystemMessage })}\n`);
+    } catch {
+      delivered = false; // host closed stdout; the record says so.
+    }
+  }
+  try { settleNudge?.(delivered); } catch { /* diagnostics never take the hook down */ }
   process.exit(0);
 }
 /**

package/scripts/hooks/user-prompt-intent.js

@@ -21,14 +21,23 @@
 import { pathToFileURL } from 'url';
 import {
   findAutoUpdateConsent,
+  importFromPluginRoot,
   isAutoCaptureEnabled,
+  hookErrorReason,
+  SKIP_REASONS,
+  recordHookOutcome,
+  markUpdatePromptAnswered,
+  memeshDir,
   parseAutoUpdateConsent,
   readUpdateCheckCache,
+  readUpdatePromptClaim,
   resolvePluginRoot,
+  unreadMessageLines,
   writeAutoUpdateConsent,
+  writeSnooze,
 } from './_shared.js';
 import { join } from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, realpathSync } from 'fs';
 
 let installChannelMod = null;
 try {
@@ -56,24 +65,64 @@ function currentInstalledVersion() {
   } catch { return null; }
 }
 
-function recordUpdateConsent(sessionId, prompt) {
+/**
+ * Record the owner's answer to this session's first-use update notice.
+ *
+ * Returns 'approved' | 'declined' | 'never' | null. The answer counts only
+ * when THIS session was actually shown the notice (a prompt claim exists for
+ * session/current/latest), so a stray "no" in unrelated conversation is not
+ * a decision about updates.
+ *
+ *   approved — npm-global only (the one channel with a hook-owned installer);
+ *              other channels were told their manual action and cannot be
+ *              approved into an install.
+ *   declined — "Not now": escalating snooze for this target version, on
+ *              every channel. A distinct newer target is offered again.
+ *   never    — "Never ask again": config.updateCheck = false; also snoozed so
+ *              a host that already read the old config stays quiet.
+ */
+async function recordUpdateConsent(sessionId, prompt) {
   const current = currentInstalledVersion();
   if (!current || !sessionId) return null;
-  const channel = currentInstallChannel();
-  // Only npm-global has a hook-owned installer. Other channels receive an
-  // actionable notice at SessionStart and must not turn an "Upgrade" word
-  // into a misleading approval marker for a different installation path.
-  if (channel !== 'npm-global') return null;
   const cache = readUpdateCheckCache(current);
   const latest = cache?.latestVersion;
   if (typeof latest !== 'string' || !latest) return null;
-  const pending = findAutoUpdateConsent(sessionId, current, latest, channel);
-  if (!pending || !['pending'].includes(pending.decision)) return null;
   const decision = parseAutoUpdateConsent(prompt);
   if (!decision) return null;
-  return writeAutoUpdateConsent(
-    sessionId, current, latest, pending.channel ?? 'unknown', decision,
-  ) ? decision : null;
+  const channel = currentInstallChannel();
+  const pending = channel === 'npm-global'
+    ? findAutoUpdateConsent(sessionId, current, latest, channel)
+    : null;
+  const claim = readUpdatePromptClaim(sessionId, current, latest);
+  // The notice must have been shown to THIS session and not answered yet.
+  // Once answered, later "no"/"later" in ordinary conversation is not a
+  // decision about updates (it used to escalate the snooze every time).
+  const open = (claim && claim.decision !== 'answered') || pending?.decision === 'pending';
+  if (!open) return null;
+
+  if (decision === 'approved') {
+    if (!pending || pending.decision !== 'pending') return null;
+    if (!writeAutoUpdateConsent(sessionId, current, latest, pending.channel ?? channel, 'approved')) return null;
+    markUpdatePromptAnswered(sessionId, current, latest, 'approved');
+    return 'approved';
+  }
+  // declined | never
+  try { writeSnooze(memeshDir(), latest); } catch { /* best-effort */ }
+  if (pending?.decision === 'pending') {
+    writeAutoUpdateConsent(sessionId, current, latest, pending.channel ?? channel, 'declined');
+  }
+  let recorded = decision;
+  if (decision === 'never') {
+    try {
+      const configMod = await importFromPluginRoot(resolvePluginRoot(import.meta.url), 'dist/core/config.js');
+      configMod.updateConfig({ updateCheck: false });
+    } catch (err) {
+      logError('user-prompt-intent', `could not persist updateCheck=false: ${err?.message || err}`);
+      recorded = 'declined';
+    }
+  }
+  markUpdatePromptAnswered(sessionId, current, latest, recorded);
+  return recorded;
 }
 
 // Patterns compiled at module load — invalid regex MUST fail loudly. Do
@@ -169,12 +218,44 @@ function logError(scope, msg) {
 // `file://${process.argv[1]}` produces an invalid URL because the path uses
 // backslashes; pathToFileURL() correctly normalizes to a file:// URL on
 // every platform, so the comparison is portable.
-const isMainModule = import.meta.url === pathToFileURL(process.argv[1]).href;
+//
+// `import.meta.url` is the REAL path of this file; `process.argv[1]` is the
+// path as the host typed it. Through a symlink (plugin cache, global npm
+// prefix) the two differ, so compare the typed path first — under
+// `--preserve-symlinks-main` Node leaves `import.meta.url` unresolved too, and
+// resolving the typed side unconditionally would make them diverge — and only
+// then the resolved path. A realpath failure on that fallback is left to
+// throw: a crash is visible, "not the entry point" is not.
+//
+// Also reads "not main" for `node -` (`argv[1]` is the literal `-`;
+// `realpathSync('-')` would throw) and `node -e`/`-p` (the eval flag is in
+// `process.execArgv`; `argv[1]` is just the caller's first argument). That
+// is `isMain()`'s (scripts/lib/verify-core.mjs) `-`/eval handling and its
+// typed-path-then-realpath order, without its directory case: `node <dir>`
+// reads as "not main" here, where `isMain()` throws. The hook cannot import
+// `isMain()`: it ships standalone (package.json `files`).
+const EVAL_FLAG = /^(-e|-p|-pe|--eval|--print)(=|$)/;
+const entryPath = process.argv[1];
+const isMainModule = Boolean(entryPath)
+  && entryPath !== '-'
+  && !process.execArgv.some((arg) => EVAL_FLAG.test(arg))
+  && (import.meta.url === pathToFileURL(entryPath).href
+    || import.meta.url === pathToFileURL(realpathSync(entryPath)).href);
 if (isMainModule) {
+  // See post-commit.js for why every exit path leaves a record (#327). This
+  // hook's only effect is the additionalContext it injects, so its outcome is
+  // `notified`, not `wrote`: doctor's `writes` answers "is memory capture
+  // still alive", and an injected hint is not a memory. Both branches that
+  // reach it — a remember intent and an update-consent decision — inject and
+  // store nothing, so there is no writing branch here to keep.
+  let payload = null;
+  const record = (outcome, reason, entity) =>
+    recordHookOutcome(process.env, { hook: 'user-prompt-intent', outcome, reason, entity, payload });
+
   let input = '';
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });
-  process.stdin.on('end', () => {
+  process.stdin.on('end', async () => {
     try {
       // Distinguish empty stdin (legitimate degenerate event) from malformed
       // input (protocol drift). Both stay non-blocking, but only malformed
@@ -186,6 +267,7 @@ if (isMainModule) {
           data = JSON.parse(trimmed);
         } catch (parseErr) {
           logError('user-prompt-intent', `malformed stdin JSON (len=${input.length}): ${parseErr.message}`);
+          record('error', 'malformed stdin JSON');
           return process.exit(0);
         }
       }
@@ -194,26 +276,46 @@ if (isMainModule) {
       // Claude Code's transcript format changed once before (2026-05-07), so
       // we accept either name to survive a similar rename. If both are absent
       // or non-string, detectRememberIntent's type guard returns false safely.
+      payload = data;
       const prompt = data.prompt ?? data.user_prompt ?? '';
-      const updateDecision = recordUpdateConsent(data.session_id, prompt);
+      const updateDecision = await recordUpdateConsent(data.session_id, prompt);
       const rememberIntent = detectRememberIntent(prompt);
-      if (!rememberIntent && !updateDecision) return process.exit(0);
+      // Messages waiting for the recipient this session declared in
+      // MEMESH_RECIPIENT. Read-only and not memory capture, so it is not
+      // gated by autoCapture. Empty when the variable is unset. An inbox that
+      // cannot be read is recorded as an `error` of its own (a label, never
+      // the message), next to whatever this prompt's outcome turns out to be,
+      // so a skip below cannot be read as "nothing was waiting".
+      const inboxLines = unreadMessageLines(process.env, (err) => record('error', `inbox: ${hookErrorReason(err)}`));
+      if (!rememberIntent && !updateDecision && inboxLines.length === 0) {
+        record('skipped', SKIP_REASONS.noPromptIntent);
+        return process.exit(0);
+      }
       // Update consent is a user-authorized control decision, not memory
       // capture; it must still be recorded when auto-capture is disabled.
-      if (!isAutoCaptureEnabled(process.env) && !updateDecision) return process.exit(0);
+      if (!isAutoCaptureEnabled(process.env) && !updateDecision && inboxLines.length === 0) {
+        record('skipped', SKIP_REASONS.autoCaptureOff);
+        return process.exit(0);
+      }
 
       const contexts = [];
-      if (updateDecision) {
-        contexts.push(updateDecision === 'approved'
-          ? 'The user explicitly approved the MeMesh upgrade. The Stop hook may now update the consented installation.'
-          : 'The user declined the MeMesh upgrade for this session. Do not install it or ask again in this session.');
+      if (updateDecision === 'approved') {
+        contexts.push('The user explicitly approved the MeMesh upgrade. The Stop hook may now update the consented installation.');
+      } else if (updateDecision === 'declined') {
+        contexts.push('The user declined the MeMesh upgrade. It is snoozed for this target version (24h, then 48h, then 7 days on repeated declines); do not install it or mention it again unless a newer version appears.');
+      } else if (updateDecision === 'never') {
+        contexts.push('The user asked never to be asked about MeMesh updates again. updateCheck is now off; do not mention updates. `memesh config set updateCheck true` turns checks back on.');
       }
-      if (rememberIntent) contexts.push(buildHint());
+      const hint = rememberIntent && isAutoCaptureEnabled(process.env);
+      if (hint) contexts.push(buildHint());
+      if (inboxLines.length > 0) contexts.push(inboxLines.join('\n'));
       const out = { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: contexts.join('\n\n') } };
       process.stdout.write(JSON.stringify(out));
+      record('notified', undefined, `hint:${updateDecision ?? (hint ? 'remember-intent' : 'inbox')}`);
       process.exit(0);
     } catch (err) {
       logError('user-prompt-intent', err?.message || err);
+      record('error', hookErrorReason(err));
       process.exit(0);
     }
   });

package/scripts/upgrade-plugin.sh

@@ -497,14 +497,13 @@ fi
 # that never contained them. `git archive` extracts exactly the tree at
 # $MARKETPLACE_SHA; nothing untracked or uncommitted can reach the cache.
 # node_modules and .git are never tracked, so they never appear in the
-# archive; tests/benchmarks/docs/plans are tracked (real source) and are
-# removed after extraction to keep the shipped cache the same shape as
-# before.
+# archive; tests/benchmarks are tracked (real source) and are removed after
+# extraction to keep the shipped cache the same shape as before.
 git -C "$MARKETPLACE_DIR" archive "$MARKETPLACE_SHA" | tar -x -C "$STAGE_PATH" || {
   echo "ERROR: git archive failed — the live cache at $NEW_INSTALL_PATH was not touched" >&2
   exit 1
 }
-if ! rm -rf "$STAGE_PATH/tests" "$STAGE_PATH/benchmarks" "$STAGE_PATH/docs/plans"; then
+if ! rm -rf "$STAGE_PATH/tests" "$STAGE_PATH/benchmarks"; then
   echo "ERROR: could not remove development-only files from the staging copy — the live cache was not touched." >&2
   exit 1
 fi