@pcircle/memesh 4.9.3 → 4.10.1

package/scripts/hooks/session-start.js

@@ -23,7 +23,18 @@ import {
   // Aliased: this file already has a local `const memeshDir` (a resolved
   // db-path-derived directory string) — the helper here is the MEMESH_DIR/
   // home resolver the update-check cache itself uses.
+  advanceGraceState,
+  captureLivenessNotice,
+  captureLivenessVerdict,
+  graceInEffect,
+  parseGraceState,
+  ensurePrivateDir as ensurePrivateDirShared,
   memeshDir as memeshHomeDir,
+  parseHookOutcomes,
+  hookErrorReason,
+  recordHookOutcome,
+  summarizeHookOutcomes,
+  HOOK_OUTCOMES_FILENAME,
   parseTaskState,
   readRepoState,
   readAutoUpdateConsent,
@@ -31,6 +42,11 @@ import {
   finalizeUpdatePromptClaim,
   readUpdatePromptClaim,
   readUpdateCheckCache,
+  resolveUpdateNotice,
+  shouldRefreshUpdateCache,
+  claimJustUpgradedMarker,
+  isStrictlyOlder,
+  isUpdateCheckEnabled,
   repoStateLines,
   resolvePluginRoot,
   resolveSessionLimit,
@@ -43,6 +59,12 @@ import {
 } from './_shared.js';
 import { MemeshDatabase } from './_generated/sqlite.js';
 import { unreadDeliveryCount, unreadInboxLines } from './_generated/agent-message-inbox.js';
+import {
+  buildBriefingIndex,
+  INDEX_CANDIDATE_CAP,
+  INDEX_EXCLUDED_TYPES,
+  INDEX_SNIPPET_FETCH_CHARS,
+} from './_generated/briefing-index.js';
 
 const require = createRequire(import.meta.url);
 
@@ -191,33 +213,59 @@ function buildDeprecationBanner(currentVersion, cache) {
  */
 const UPDATE_BANNER_THROTTLE_MS = 24 * 60 * 60 * 1000;
 
+// `isStrictlyOlder` now comes from the shared update-notice leaf (one
+// semver rule for hooks, CLI and the resolver).
+
+const CHECK_FAILED_BANNER_THROTTLE_MS = 24 * 60 * 60 * 1000;
+
 /**
- * Return true iff `a` is strictly older than `b` under semver-ish
- * ordering. Compares the dot-separated numeric portion of each version
- * componentwise (so 4.2.10 > 4.2.9, unlike string compare). Anything
- * after the first non-numeric char falls back to lex compare on the
- * trailing fragment — fine for the prerelease / 4-segment build tags
- * memesh uses (e.g. 4.2.5-rc.1).
+ * Banner lines for the two update states that are NOT a consent prompt:
+ * JUST_UPGRADED (said once, then the receipt is consumed) and CHECK_FAILED
+ * (unknown is not "up to date"; throttled to once a day). Everything else
+ * returns [] so the caller falls through to its consent/banner logic.
  */
-function isStrictlyOlder(a, b) {
-  const parse = (v) => {
-    const [main, ...rest] = String(v).split(/[-+]/);
-    const nums = main.split('.').map((s) => Number.parseInt(s, 10));
-    return { nums, tail: rest.join('-') };
-  };
-  const pa = parse(a);
-  const pb = parse(b);
-  const len = Math.max(pa.nums.length, pb.nums.length);
-  for (let i = 0; i < len; i++) {
-    const ai = Number.isFinite(pa.nums[i]) ? pa.nums[i] : 0;
-    const bi = Number.isFinite(pb.nums[i]) ? pb.nums[i] : 0;
-    if (ai !== bi) return ai < bi;
+function updateNoticeBanner(installedVersion, cache) {
+  if (!installedVersion) return { kind: 'UNKNOWN_VERSION', lines: [] };
+  const notice = resolveUpdateNotice({
+    dir: memeshHomeDir(), currentVersion: installedVersion, cache, updateCheckEnabled: isUpdateCheckEnabled(),
+  });
+  if (notice.kind === 'JUST_UPGRADED') {
+    // Take the receipt atomically: two host hooks starting together must not
+    // both announce. The loser sees null and says nothing about it.
+    const claimed = claimJustUpgradedMarker(memeshHomeDir());
+    if (!claimed) return { kind: 'UP_TO_DATE', lines: [] };
+    return {
+      kind: notice.kind,
+      lines: [`✅ MeMesh upgraded ${claimed.from} → ${claimed.to}. Hosts already running keep the old version until they restart; this session's hooks and MCP server pick up ${claimed.to} on the next start.`],
+    };
   }
-  // Numeric prefix tied. A prerelease tail counts as OLDER than no
-  // tail (semver: 1.0.0-rc.1 < 1.0.0); otherwise lex on tail.
-  if (pa.tail && !pb.tail) return true;
-  if (!pa.tail && pb.tail) return false;
-  return pa.tail < pb.tail;
+  if (notice.kind === 'CHECK_FAILED') return { kind: notice.kind, lines: buildCheckFailedBanner(installedVersion, notice.reason) };
+  return { kind: notice.kind, lines: [] };
+}
+
+/**
+ * The update status is UNKNOWN (no completed check, or the registry lookup
+ * failed and the last good answer is older than a day). Silence here would
+ * read as "up to date", so say it — once a day per installed version.
+ */
+function buildCheckFailedBanner(currentVersion, reason) {
+  try {
+    const fs = require('fs');
+    const dir = memeshHomeDir();
+    try { ensurePrivateDir(dir); } catch { /* best-effort */ }
+    const versionTag = /^[0-9A-Za-z.+-]+$/.test(currentVersion) ? currentVersion : 'unknown';
+    const markerPath = join(dir, `last-check-failed-banner.${versionTag}.lock`);
+    let stat;
+    try { stat = fs.statSync(markerPath); } catch { stat = null; }
+    if (stat && Date.now() - stat.mtimeMs < CHECK_FAILED_BANNER_THROTTLE_MS) return [];
+    try {
+      fs.writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });
+      try { fs.chmodSync(markerPath, 0o600); } catch { /* non-POSIX */ }
+    } catch { /* best-effort */ }
+  } catch {
+    return [];
+  }
+  return [`ℹ️  MeMesh could not confirm whether an update exists (${reason}). Update status is unknown, not current — run \`memesh status\` to retry.`];
 }
 
 function buildUpdateAvailableBanner(currentVersion, cache, getChannel) {
@@ -333,7 +381,13 @@ function detectInstallChannelHook(pluginRoot) {
 
 function buildUpdateConsentPrompt(sessionId, currentVersion, cache, channel) {
   if (!sessionId || sessionId === 'unknown' || !cache || cache.currentVersion !== currentVersion) return null;
-  if (!cache.latestVersion || !isStrictlyOlder(currentVersion, cache.latestVersion)) return null;
+  // One resolver decides. Snoozed ("Not now" within its window), disabled
+  // ("Never ask again"), a just-landed upgrade, or a failed check all mean:
+  // no consent prompt this session. Those states get their own banner line.
+  const notice = resolveUpdateNotice({
+    dir: memeshHomeDir(), currentVersion, cache, updateCheckEnabled: isUpdateCheckEnabled(),
+  });
+  if (notice.kind !== 'UPGRADE_AVAILABLE') return null;
   const existing = readAutoUpdateConsent(sessionId, currentVersion, cache.latestVersion, channel);
   if (existing?.decision) return null;
   // Claim the session-level notice before emitting it. A resumed hook or a
@@ -354,7 +408,7 @@ function buildUpdateConsentPrompt(sessionId, currentVersion, cache, channel) {
           ? '    Project-local install: run `npm install @pcircle/memesh@latest` in the project that installed it.'
           : '    Update it through the tool or package manager that installed MeMesh.';
     return {
-      system: `\nℹ️  MeMesh ${cache.latestVersion} is available (you're on ${currentVersion}) for ${target}. This installation cannot be upgraded automatically from this session.\n${action}`,
+      system: `\nℹ️  MeMesh ${cache.latestVersion} is available (you're on ${currentVersion}) for ${target}. This installation cannot be upgraded automatically from this session.\n${action}\n    Reply “Not now” to snooze this version (24h, then longer), or “Never ask again” to stop these checks.`,
       context: `MeMesh ${cache.latestVersion} is available for ${target}, but this channel has no safe in-session installer. Show the user the channel-specific update action and do not claim that an Upgrade reply will install it.`,
     };
   }
@@ -363,8 +417,8 @@ function buildUpdateConsentPrompt(sessionId, currentVersion, cache, channel) {
   // session notice has been claimed.
   if (!writeAutoUpdateConsent(sessionId, currentVersion, cache.latestVersion, channel, 'pending')) return null;
   return {
-    system: `\nℹ️  MeMesh ${cache.latestVersion} is available (you're on ${currentVersion}) for ${target}. Reply “Upgrade” to install it, or “Not now” to skip for this session.`,
-    context: `MeMesh update consent is pending for this session. Ask the user whether to upgrade from ${currentVersion} to ${cache.latestVersion} for the ${target}. Wait for an explicit Upgrade or Not now response; do not install without affirmative consent.`,
+    system: `\nℹ️  MeMesh ${cache.latestVersion} is available (you're on ${currentVersion}) for ${target}. Reply “Upgrade” to install it, “Not now” to snooze this version (24h, then longer), or “Never ask again” to stop these checks.`,
+    context: `MeMesh update consent is pending for this session. Ask the user whether to upgrade from ${currentVersion} to ${cache.latestVersion} for the ${target}. Wait for an explicit Upgrade, Not now, or Never ask again response; do not install without affirmative consent.`,
   };
 }
 
@@ -563,6 +617,11 @@ function runPostBannerUpdateTasks() {
     if (!installedVersion) return;
     // Auto-update spawn moved to Stop hook (v4.1.4) to avoid TOCTOU race
     // where npm install -g overwrites dist/ while peer hooks are still reading it.
+    // Two TTLs (update-notice.ts): a current answer is re-verified hourly, a
+    // known upgrade is not re-fetched for 12h; a failed or missing check is
+    // always retried. "Never ask again" also stops the background refresh.
+    if (!isUpdateCheckEnabled()) return;
+    if (!shouldRefreshUpdateCache(installedVersion, readUpdateCheckCache(installedVersion))) return;
     spawnFreshUpdateCheck(installedVersion);
   } catch {
     // Best-effort — never crash the hook on a network or fs hiccup.
@@ -611,27 +670,120 @@ function captureTargetUnwritable() {
   return null;
 }
 
+/**
+ * Once per 24h, one line when automatic capture has gone quiet (#327).
+ *
+ * The verdict is computed in the HOOK layer because a hook cannot import
+ * `src/` — but from the SAME leaf `memesh doctor` uses, so the banner and
+ * the report can never disagree about whether capture is alive. The hook
+ * sees only `hook-outcomes.jsonl`: doctor additionally reads the database for
+ * per-type trends and the `hook_runs` heartbeats, so doctor can reach a FAIL
+ * this line never will. That is the right asymmetry — a SessionStart line is
+ * a nudge towards `memesh doctor`, not a replacement for it.
+ *
+ * Suppression after the next successful write needs no marker of its own: a
+ * `wrote` record makes the hook non-silent and the verdict returns to PASS,
+ * so this returns null on its own. Only the throttle needs a file.
+ *
+ * It reads the JSONL and nothing else — never the database. SessionStart is
+ * on the critical path of every session start with a 10s budget, and a
+ * banner line is not worth a query against a graph that may be mid-write.
+ */
+const CAPTURE_LIVENESS_THROTTLE_MS = 24 * 60 * 60 * 1000;
+const CAPTURE_GRACE_FILE = 'capture-liveness-grace.json';
+
+/**
+ * Count this session against the post-install / post-upgrade grace, and say
+ * whether the grace is still on.
+ *
+ * The counter is keyed to the installed version, so an upgrade resets it —
+ * an upgrade replaces the hooks, which is exactly when a legitimate run of
+ * skips is expected and a warning would be noise.
+ */
+function captureGraceInEffect(dir, installedVersion) {
+  try {
+    let raw = null;
+    try { raw = readFileSync(join(dir, CAPTURE_GRACE_FILE), 'utf8'); } catch { /* first session */ }
+    const next = advanceGraceState(parseGraceState(raw), installedVersion, Date.now());
+    try {
+      ensurePrivateDirShared(dir);
+      const gracePath = join(dir, CAPTURE_GRACE_FILE);
+      require('fs').writeFileSync(gracePath, JSON.stringify(next), { mode: 0o600 });
+      try { require('fs').chmodSync(gracePath, 0o600); } catch { /* best-effort hardening */ }
+    } catch { /* best-effort — a lost count only shortens the grace */ }
+    return graceInEffect(next, Date.now());
+  } catch {
+    // Cannot tell how new this install is → assume it is new. Silence is
+    // the safe default for a nudge; doctor still reports the truth.
+    return true;
+  }
+}
+
+function captureLivenessBannerLine(installedVersion) {
+  try {
+    // The banner must read the outcome file from the SAME place the hooks
+    // write it. recordHookOutcome writes beside the database
+    // (getMemeshDirFromDbPath = dirname(MEMESH_DB_PATH)); reading via
+    // memeshHomeDir (= MEMESH_DIR) instead split the two whenever a DB path
+    // override pointed elsewhere, and the banner silently read nothing —
+    // the exact "banner and report can never disagree" failure this exists
+    // to prevent. The grace counter and throttle lock move with it so the
+    // three pieces of this mechanism stay beside the same file.
+    const dir = getMemeshDirFromDbPath();
+    if (captureGraceInEffect(dir, installedVersion ?? 'unknown')) return null;
+    let raw = null;
+    try { raw = readFileSync(join(dir, HOOK_OUTCOMES_FILENAME), 'utf8'); } catch { return null; }
+    const verdict = captureLivenessVerdict({ hooks: summarizeHookOutcomes(parseHookOutcomes(raw)), types: [] });
+    const line = captureLivenessNotice(verdict);
+    if (!line) return null;
+
+    // Same throttle primitive as the update banner: file mtime, touched
+    // BEFORE the line is emitted so two sessions starting at once cannot
+    // both print it.
+    const markerPath = join(dir, 'last-capture-liveness-notice.lock');
+    let stat;
+    try { stat = require('fs').statSync(markerPath); } catch { stat = null; }
+    if (stat && Date.now() - stat.mtimeMs < CAPTURE_LIVENESS_THROTTLE_MS) return null;
+    try {
+      ensurePrivateDirShared(dir);
+      require('fs').writeFileSync(markerPath, String(Date.now()), { mode: 0o600 });
+      try { require('fs').chmodSync(markerPath, 0o600); } catch { /* best-effort hardening */ }
+    } catch { /* best-effort — worst case the line shows twice */ }
+    return line;
+  } catch {
+    // Diagnostics must never cost a session its banner.
+    return null;
+  }
+}
+
 /**
  * Build a "base message + optional deprecation banner" combined
  * single-line systemMessage payload. Keeps stdout a single JSON
  * object on every empty/no-DB exit path so Claude Code's hook
  * contract holds.
  */
-function combineWithBanner(baseMessage) {
+function combineWithBanner(baseMessage, { skipUpdateBanner = false } = {}) {
   let lines = [];
+  // Hoisted out of the try: the capture-liveness grace is keyed to the
+  // installed version, and it must still be counted when the update-banner
+  // block below throws (a missing package.json must not silently disable the
+  // grace and start warning on a fresh install).
+  let livenessVersion = null;
   try {
     const pluginRoot = resolvePluginRoot(import.meta.url);
     const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
     const installedVersion = typeof pkg.version === 'string' ? pkg.version : null;
+    livenessVersion = installedVersion;
     const cache = readUpdateCheckCache(installedVersion);
     if (installedVersion) {
       const deprecation = buildDeprecationBanner(installedVersion, cache);
-      // Deprecation owns the spot when present; the update-available
-      // banner is the fallback for the much more common "not flagged,
-      // just out of date" case.
+      const notice = updateNoticeBanner(installedVersion, cache);
       if (deprecation.length > 0) {
         lines = deprecation;
-      } else {
+      } else if (notice.lines.length > 0) {
+        lines = notice.lines;
+      } else if (notice.kind === 'UPGRADE_AVAILABLE' && !skipUpdateBanner) {
+        // Snoozed, disabled, failed or current: the resolver already said no.
         lines = buildUpdateAvailableBanner(
           installedVersion, cache, () => detectInstallChannelHook(pluginRoot));
       }
@@ -639,6 +791,10 @@ function combineWithBanner(baseMessage) {
   } catch {
     // Best-effort — fall through to base message only.
   }
+  // The capture-liveness line rides the same single systemMessage as every
+  // other banner — stdout must stay one JSON document.
+  const liveness = captureLivenessBannerLine(livenessVersion);
+  if (liveness) lines = [...lines, liveness];
   if (lines.length === 0) return baseMessage;
   return [...lines.filter((l) => l.length > 0), '', baseMessage].join('\n');
 }
@@ -730,7 +886,6 @@ process.stdin.on('end', async () => {
       // With no database there is nothing to recall either — the warning IS
       // the whole truth, and "memories will be created as you work" would
       // contradict it one line later.
-      const emptySummary = combineWithBanner(captureWarning ?? '◉ MeMesh ready · no database yet, memories will be created as you work');
       let consent = null;
       let consentVersion = null;
       let consentCache = null;
@@ -742,6 +897,20 @@ process.stdin.on('end', async () => {
         const channel = detectInstallChannelHook(pluginRoot);
         consent = buildUpdateConsentPrompt(data.session_id, consentVersion, consentCache, channel);
       } catch { /* best-effort */ }
+      // The consent prompt IS the update message for this session; the
+      // routine "update available" banner must not repeat it one line later
+      // (the database path has had this rule since the notice was added; the
+      // no-database path printed both). Deprecation, a just-landed upgrade
+      // and a failed check still render through combineWithBanner.
+      // A session that was already shown the notice (claim exists, answered
+      // or not) must not get the routine banner either — same rule as the
+      // database path.
+      const alreadyNoticed = consent !== null || (consentVersion !== null
+        && readUpdatePromptClaim(data.session_id, consentVersion, consentCache?.latestVersion) !== null);
+      const emptySummary = combineWithBanner(
+        captureWarning ?? '◉ MeMesh ready · no database yet, memories will be created as you work',
+        { skipUpdateBanner: alreadyNoticed },
+      );
       output(consent ? `${consent.system}\n${emptySummary}` : emptySummary,
         consent ? `${consent.context}\n\n${workPackageGuidance}` : workPackageGuidance);
       if (consent) finalizeUpdatePromptClaim(data.session_id, consentVersion, consentCache?.latestVersion);
@@ -1101,45 +1270,122 @@ process.stdin.on('end', async () => {
         try { process.stderr.write(`[memesh session-start] memory-context: ${err?.message || err}\n`); } catch {}
       }
 
+      // --- The durable-memory index (#323) -----------------------------
+      // One line per decision / lesson / pattern / reference for this
+      // project, newest first, hard-capped — what is known, visible without
+      // a query. Same read as core's `readBriefingIndex` (this hook owns its
+      // own SQL, with the legacy-schema guards the queries above use); every
+      // decision about what to show lives in the generated leaf. A read that
+      // fails renders as "could not be read", never as the empty-state line:
+      // an empty index is a claim about the user's data.
+      let indexLines;
+      // id → name for the rows the index rendered, so the injected-set
+      // record below can credit a citation of an index line the same way it
+      // credits a ranked one — the line carries a `[mem:id]` handle, it was
+      // shown, and a cite of it must not earn nothing.
+      const indexEntities = [];
+      try {
+        const excluded = INDEX_EXCLUDED_TYPES.map(() => '?').join(',');
+        const indexRows = db.prepare(
+          `SELECT e.id, e.name, e.type,${hasTitle ? ' e.title,' : ''} e.metadata,
+             (SELECT substr(o.content, 1, ${INDEX_SNIPPET_FETCH_CHARS}) FROM observations o
+               WHERE o.entity_id = e.id ORDER BY o.id ASC LIMIT 1) AS snippet,
+             max(e.created_at, COALESCE((SELECT MAX(o2.created_at) FROM observations o2
+               WHERE o2.entity_id = e.id), e.created_at)) AS last_activity
+           FROM entities e
+           WHERE e.id IN (SELECT entity_id FROM tags WHERE tag = ?)
+             ${statusFilter} ${notGlobal}
+             AND e.type NOT IN (${excluded})
+           ORDER BY last_activity DESC, e.id DESC
+           LIMIT ?`,
+        ).all(projectTag, ...INDEX_EXCLUDED_TYPES, INDEX_CANDIDATE_CAP);
+        const index = buildBriefingIndex(
+          indexRows.map((row) => ({
+            id: row.id,
+            type: row.type,
+            title: row.title ?? null,
+            snippet: row.snippet,
+            lastActivity: row.last_activity,
+            // The RAW column: the index's gate must tell an absent metadata
+            // column (allowed) from unparseable JSON (refused), exactly as
+            // `isTrustedForAutoContext` does on the ranked path. Parsing here
+            // would collapse both to null and fail OPEN.
+            metadata: row.metadata,
+          })),
+          projectName,
+          Date.now(),
+          { truncated: indexRows.length >= INDEX_CANDIDATE_CAP },
+        );
+        indexLines = index.lines;
+        const rendered = new Set(index.ids);
+        for (const row of indexRows) if (rendered.has(row.id)) indexEntities.push(row);
+      } catch (err) {
+        const reason = String(err?.message || err);
+        try { process.stderr.write(`[memesh session-start] briefing-index: ${reason}\n`); } catch {}
+        recordHookOutcome(process.env, {
+          hook: 'session-start',
+          outcome: 'error',
+          // The locus, plus a LABEL for the exception — never its message.
+          // `hook-outcomes.jsonl` is permanent, exportable and meant to be
+          // pasteable into an issue, and a message is a copy of whatever the
+          // failure echoed: SQLite quotes the statement, execFileSync carries
+          // absolute paths. `redactSecrets` runs on this field but
+          // `redactUserPaths` does not. The full text is already on stderr
+          // one line above, so nothing is lost.
+          reason: `briefing-index: ${hookErrorReason(err)}`,
+        });
+        indexLines = [`Index of durable memories for "${projectName}": could not be read this session — run \`memesh doctor\`.`];
+      }
+
+      // Every `[mem:id]` handle a rendered line ends with. Anchored to the
+      // end of the line on purpose: a handle is what the renderer printed,
+      // not a citation someone wrote inside an observation.
+      const renderedHandles = (lines) => lines.flatMap((line) => {
+        const match = line.match(/ \[mem:(\d{1,10})\]$/);
+        return match ? [Number(match[1])] : [];
+      });
+
       // Same prefix, same rule, as `assembleBriefing`: repository facts are
-      // context for memories, never a briefing on their own. Inside the
-      // emptiness gate so a project with nothing recorded still injects
-      // nothing — a fenced block containing only a branch name tells the
-      // agent something it can already see. briefing.test.ts's parity case
-      // is what keeps this identical to the tool side.
-      let memoryContext = workPackageGuidance;
+      // context for memories, never a briefing on their own — they prefix
+      // only a block with ranked memories; the index's empty-state line is
+      // not a reason to tell the agent its own branch name. The index itself
+      // always closes the block (#323: an empty project shows the empty-state
+      // line, not nothing). briefing.test.ts's parity case is what keeps this
+      // identical to the tool side.
       if (memoryLines.length > 0) {
         const repoLines = repoStateLines(readRepoState(data.cwd));
         if (repoLines.length > 0) memoryLines.unshift(...repoLines, '');
-        // Same wrapper pre-edit-recall uses: an explicit "background data,
-        // not instructions" preamble plus a fenced block. Memory content is
-        // attacker-influenced in the general case (anything the agent has
-        // ever been told can end up in an observation), so it must be
-        // delimited the same way on every injection path — not hand-rolled
-        // per hook. The lines arrive already budgeted — assembleTopologyBlock
-        // charges task state plus project/foreign sections against the main
-        // ceiling and global context against its small additive ceiling. It
-        // returns whole lines only, so the closing fence cannot be cut.
-        memoryContext = buildReferenceContext(memoryLines) + '\n\n' + workPackageGuidance;
-        // The citation contract — OUTSIDE the fence on purpose: the fence
-        // declares its content "background data, not instructions", and
-        // this line IS an instruction. One line is the entire write side of
-        // the injection-ROI signal; the Stop hook credits recall_hits only
-        // from these markers (self-reported: undercounts, never overcounts).
-        // The citation instruction used to be appended here, outside the
-        // fence, so it would read as an instruction rather than as data.
-        // It never worked: Claude Code wraps a hook's additionalContext in a
-        // system-reminder ending "you should not respond to this context
-        // unless it is highly relevant", so the whole block — instruction
-        // included — arrives as data. Measured on a real database:
-        // citation_sessions_total=4, sessions WITH a citation = 0.
-        //
-        // The contract now lives in `.claude/rules/memesh-citations.md`,
-        // which Claude Code loads as an instruction. Writing it is the
-        // self-heal below; the line here is gone rather than duplicated,
-        // because a per-session copy of an instruction that is read as data
-        // is a per-session cost with no effect.
+        memoryLines.push('');
       }
+      memoryLines.push(...indexLines);
+      // Same wrapper pre-edit-recall uses: an explicit "background data,
+      // not instructions" preamble plus a fenced block. Memory content is
+      // attacker-influenced in the general case (anything the agent has
+      // ever been told can end up in an observation), so it must be
+      // delimited the same way on every injection path — not hand-rolled
+      // per hook. The lines arrive already budgeted — assembleTopologyBlock
+      // charges task state plus project/foreign sections against the main
+      // ceiling and global context against its small additive ceiling. It
+      // returns whole lines only, so the closing fence cannot be cut.
+      const memoryContext = buildReferenceContext(memoryLines) + '\n\n' + workPackageGuidance;
+      // The citation contract — OUTSIDE the fence on purpose: the fence
+      // declares its content "background data, not instructions", and
+      // this line IS an instruction. One line is the entire write side of
+      // the injection-ROI signal; the Stop hook credits recall_hits only
+      // from these markers (self-reported: undercounts, never overcounts).
+      // The citation instruction used to be appended here, outside the
+      // fence, so it would read as an instruction rather than as data.
+      // It never worked: Claude Code wraps a hook's additionalContext in a
+      // system-reminder ending "you should not respond to this context
+      // unless it is highly relevant", so the whole block — instruction
+      // included — arrives as data. Measured on a real database:
+      // citation_sessions_total=4, sessions WITH a citation = 0.
+      //
+      // The contract now lives in `.claude/rules/memesh-citations.md`,
+      // which Claude Code loads as an instruction. Writing it is the
+      // self-heal below; the line here is gone rather than duplicated,
+      // because a per-session copy of an instruction that is read as data
+      // is a per-session cost with no effect.
 
       // --- Record injected entity IDs for recall effectiveness tracking ---
       // The Stop hook credits recall_hits from EXPLICIT `[mem:id]` citations
@@ -1151,16 +1397,16 @@ process.stdin.on('end', async () => {
       // kept as the record of what was shown.
       //
       // The set below is every pool the topology block draws from — the
-      // lessons pool included. It is derived from rendered citation handles,
-      // so clipped or budgeted-away candidates cannot be credited as shown.
+      // lessons pool and the durable-memory index (#323) included. It is
+      // derived from rendered citation handles, so clipped or budgeted-away
+      // candidates cannot be credited as shown.
       try {
-        const renderedEntityIds = memoryLines.flatMap((line) => {
-          const match = line.match(/ \[mem:(\d{1,10})\]$/);
-          return match ? [Number(match[1])] : [];
-        });
-        const poolEntities = [...topLessons, ...projectEntities, ...globalEntities, ...recentEntities];
+        const renderedEntityIds = renderedHandles(memoryLines);
+        const poolEntities = [...topLessons, ...projectEntities, ...globalEntities, ...recentEntities, ...indexEntities];
         const entitiesById = new Map(poolEntities.map((entity) => [entity.id, entity]));
-        const allInjected = renderedEntityIds
+        // A memory can appear in the ranked block AND the index; it was
+        // injected once.
+        const allInjected = [...new Set(renderedEntityIds)]
           .map((id) => entitiesById.get(id))
           .filter(Boolean);
 
@@ -1218,8 +1464,16 @@ process.stdin.on('end', async () => {
       let updateConsentContext = null;
       if (installedVersion) {
         const deprecation = buildDeprecationBanner(installedVersion, updateCache);
+        const notice = updateNoticeBanner(installedVersion, updateCache);
         if (deprecation.length > 0) {
           bannerLines = deprecation;
+        } else if (notice.lines.length > 0) {
+          bannerLines = notice.lines;
+        } else if (notice.kind !== 'UPGRADE_AVAILABLE') {
+          // Snoozed ("Not now"), disabled ("Never ask again"), current, or
+          // unknown-but-throttled: the resolver decided, so the routine
+          // banner below must not undo it.
+          bannerLines = [];
         } else {
           const channel = detectInstallChannelHook(resolvePluginRoot(import.meta.url));
           const consent = buildUpdateConsentPrompt(data.session_id, installedVersion, updateCache, channel);
@@ -1240,6 +1494,13 @@ process.stdin.on('end', async () => {
           }
         }
       }
+      // The populated-database path builds its banner locally rather than
+      // going through combineWithBanner() (the no-database path does). Keep
+      // the capture-liveness notice in this path too: otherwise the warning
+      // works only for a fresh graph and disappears precisely for users whose
+      // existing memories make capture failure most costly.
+      const captureLiveness = captureLivenessBannerLine(installedVersion);
+      if (captureLiveness) bannerLines.push(captureLiveness);
       const finalMessage = bannerLines.length > 0
         ? [...bannerLines.filter(l => l.length > 0), '', summary].join('\n')
         : summary;
@@ -1317,7 +1578,14 @@ process.stdin.on('end', async () => {
       // Hooks must never crash Claude Code — but report honestly.
       // Inner catch so the outer finally can still run the post-
       // banner update tasks even when the recall flow blew up.
-      console.log(JSON.stringify({ systemMessage: withCaptureWarning(`MeMesh: memories not loaded this session (${err?.message || 'unknown error'}) — everything else works; run \`memesh doctor\` if this repeats.`) }));
+      // Through output(), like every other emit: the gate proves "every
+      // stdout write lies inside output()", and output() records exactly one
+      // outcome — here an error, not the default `wrote`.
+      output(
+        withCaptureWarning(`MeMesh: memories not loaded this session (${err?.message || 'unknown error'}) — everything else works; run \`memesh doctor\` if this repeats.`),
+        null,
+        { outcome: 'error', reason: hookErrorReason(err) },
+      );
     }
   } finally {
     // ── Auto-update + cache refresh ──────────────────────────────
@@ -1355,7 +1623,15 @@ process.stdin.on('end', async () => {
  */
 const workPackageGuidance = 'Work packages: check work_package prepare for this project (digest or transcript). When available, offer a concise host-native interactive choice in the user’s conversation language: dispatch an agent task, later (defer not_now), or stop suggesting for this session. Never dispatch without the user choosing it. The Dashboard cannot dispatch agents, and no durable opt-out is implied.';
 
-function output(text, memoryContext = workPackageGuidance) {
+function output(text, memoryContext = workPackageGuidance, recorded = null) {
+  // session-start's only effect is the context it injects, so it records
+  // `notified`, not `wrote`: doctor's `writes` answers "is memory capture
+  // still alive", and injected context is something this hook READ, not
+  // something it stored. Recorded here rather than at each of the handler's many
+  // returns because output() is the single emit point they all funnel
+  // through, so no path can add itself later and stay invisible (#327).
+  // `recorded` overrides the outcome for the one path that is not a write
+  // (the recall flow threw): still one emit, still exactly one record.
   const payload = { systemMessage: text };
   if (memoryContext) {
     payload.hookSpecificOutput = {
@@ -1364,4 +1640,11 @@ function output(text, memoryContext = workPackageGuidance) {
     };
   }
   console.log(JSON.stringify(payload));
+  recordHookOutcome(process.env, recorded
+    ? { hook: 'session-start', outcome: recorded.outcome, reason: recorded.reason }
+    : {
+      hook: 'session-start',
+      outcome: 'notified',
+      entity: memoryContext ? 'session-start-context' : 'session-start-banner',
+    });
 }