@pcircle/memesh 4.9.4 → 4.10.2

package/scripts/hooks/session-start.js

@@ -7,6 +7,7 @@ import { pathToFileURL } from 'url';
 import { existsSync, readFileSync, unlinkSync, mkdirSync, accessSync, constants as fsConstants } from 'fs';
 import {
   buildReferenceContext,
+  hasBriefingContent,
   ensurePrivateDir,
   getDbPath,
   getMemeshDirFromDbPath,
@@ -23,7 +24,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,10 +43,23 @@ import {
   finalizeUpdatePromptClaim,
   readUpdatePromptClaim,
   readUpdateCheckCache,
+  resolveUpdateNotice,
+  shouldRefreshUpdateCache,
+  claimJustUpgradedMarker,
+  isStrictlyOlder,
+  isUpdateCheckEnabled,
   repoStateLines,
   resolvePluginRoot,
   resolveSessionLimit,
-  taskStateLines,
+  briefingTaskStateLines,
+  resolveBriefingLevel,
+  resolveMessageRecipient,
+  waitingMessageLines,
+  briefingLevelPolicy,
+  sessionStartAppendsWorkPackageNotice,
+  WORK_PACKAGE_NOTICE,
+  readHookConfigResult,
+  HOOK_CONFIG_UNREADABLE_REASON,
   homeDir,
   taskStateName,
   writeCitationRule,
@@ -42,17 +67,21 @@ import {
   writePrivateJson,
 } 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);
 
-// Codex round 37: dist/core/install-channel.js is emitted as ESM
-// (the project's tsconfig produces NodeNext modules). On Node 20.x
-// `require()` against an ESM file throws ERR_REQUIRE_ESM, which
-// silently downgraded all install-channel detection to 'unknown' on
-// the supported floor. Pre-load the module via dynamic `import()`
-// at hook startup using a top-level await — once at process init,
-// not on every call. Falls back to null if the dist file is
+// dist/core/install-channel.js is emitted as ESM (the project's tsconfig
+// produces NodeNext modules). On Node 20.x `require()` against an ESM file
+// throws ERR_REQUIRE_ESM, which would silently downgrade all install-channel
+// detection to 'unknown' on the supported floor. So the module is pre-loaded
+// via dynamic `import()` at hook startup using a top-level await — once at
+// process init, not on every call. Falls back to null if the dist file is
 // missing (source checkout pre-build) or fails to load.
 let _installChannelMod = null;
 try {
@@ -102,32 +131,26 @@ function buildDeprecationBanner(currentVersion, cache) {
     `⚠️  MeMesh ${currentVersion} is DEPRECATED by maintainers.`,
     `    ${msg}`,
   ];
-  // Codex round 36: emit a remediation line for EVERY deprecation
-  // banner — including the cases where the cached `latestVersion`
-  // is null, equal to current, or stale. The previous gate omitted
-  // the action line whenever the cache didn't yet show a strictly-
-  // newer version, leaving users with a security warning and no
-  // follow-up step. doctor / CLI status / dashboard already point
-  // at `memesh update` (or channel equivalents) in those uncertain
-  // cases, and the session-start banner should match — `npm`
-  // resolves @latest at install time, so the command works even
-  // when our local cache is uncertain.
+  // A remediation line is emitted for EVERY deprecation banner — including
+  // when the cached `latestVersion` is null, equal to current, or stale — so
+  // a security warning always carries a follow-up step. doctor / CLI status /
+  // dashboard point at `memesh update` (or channel equivalents) in those
+  // uncertain cases too, and the session-start banner matches: `npm`
+  // resolves @latest at install time, so the command works even when our
+  // local cache is uncertain.
   const knownUpgradeTarget = Boolean(
     cache.latestVersion && cache.latestVersion !== currentVersion,
   );
-  // Codex round 39: the SessionStart hook reads ONLY cached cache
-  // data — there's no fresh lookup happening on this code path.
-  // That means `freshness === 'fresh'` (the strict rule the
-  // dashboard / `memesh status` use to authoritatively say
-  // "no upgrade target yet") can never apply here. Round 38 used a
-  // 24h-window heuristic to fire the no-target message anyway, but
-  // codex correctly flagged that as suppressing the upgrade hint
-  // exactly when a security-advisory fix could ship within the
-  // window. Conservative remediation: always recommend
-  // `memesh update` (which is a harmless no-op when there's truly
-  // no target, and immediately applies a freshly-published fix
-  // when there is one). The "no target yet" message remains
-  // available in `memesh status` (fresh lookup) and the dashboard
+  // The SessionStart hook reads ONLY cached update data — no fresh lookup
+  // happens on this code path. That means `freshness === 'fresh'` (the strict
+  // rule the dashboard / `memesh status` use to authoritatively say "no
+  // upgrade target yet") can never apply here. A 24h-window heuristic that
+  // fired the no-target message anyway would suppress the upgrade hint
+  // exactly when a security-advisory fix could ship within the window, so
+  // the remediation is conservative: always recommend `memesh update` (a
+  // harmless no-op when there's truly no target, and it immediately applies
+  // a freshly-published fix when there is one). The "no target yet" message
+  // remains available in `memesh status` (fresh lookup) and the dashboard
   // (after a Check now click).
   // Tailor the remediation hint to the install channel. `memesh
   // update` and `autoUpdate` only work for npm-global installs;
@@ -155,9 +178,8 @@ function buildDeprecationBanner(currentVersion, cache) {
   } else if (channel === 'source-checkout') {
     lines.push(`    Source checkout: pull and rebuild (\`git pull && npm install && npm run build\`).`);
   } else if (channel === 'npm-local') {
-    // Codex round 30: the cached `latestVersion` may itself be
-    // stale (cache TTL is 24h and we're already showing a stale
-    // banner). Pinning a specific version risks installing an
+    // The cached `latestVersion` may itself be stale (cache TTL is 24h
+    // and we're already showing a stale banner). Pinning a specific version risks installing an
     // already-superseded build that's part of the same security
     // advisory. `@latest` always resolves to the registry's
     // current dist-tag at install time, which is the right
@@ -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.`],
+    };
+  }
+  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 [];
   }
-  // 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;
+  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.`,
   };
 }
 
@@ -443,14 +497,13 @@ function spawnFreshUpdateCheck(installedVersion) {
     // the banner marker above: marker and cache must share a directory.
     const dir = memeshHomeDir();
     try { ensurePrivateDir(dir); } catch { /* best-effort */ }
-    // Codex round 37: scope the throttle marker to the installed
-    // version. The marker was machine-global, so a refresh started
-    // by a global 4.1.3 install would suppress refreshes for a
-    // sibling project-local 4.1.1 for the next 5 minutes — and the
-    // shared cache it wrote would carry version 4.1.3, so the
-    // 4.1.1 session would skip its banner because
-    // `cache.currentVersion !== currentVersion`. Per-version
-    // markers ensure each install gets its own refresh window.
+    // The throttle marker is scoped to the installed version. A
+    // machine-global marker would let a refresh started by a global 4.1.3
+    // install suppress refreshes for a sibling project-local 4.1.1 for the
+    // next 5 minutes — and the shared cache it wrote would carry version
+    // 4.1.3, so the 4.1.1 session would skip its banner because
+    // `cache.currentVersion !== currentVersion`. Per-version markers give
+    // each install its own refresh window.
     // Sanitize version for filesystem (semver chars only, no path
     // separators); fall back to 'unknown' if missing.
     const versionTag = typeof installedVersion === 'string'
@@ -458,13 +511,12 @@ function spawnFreshUpdateCheck(installedVersion) {
       ? installedVersion
       : 'unknown';
     const markerPath = join(dir, `last-fresh-refresh.${versionTag}.lock`);
-    // Single-owner claim: O_EXCL atomic create. Codex round 27
-    // caught that the previous temp+rename+readback pattern was
-    // racy — both peers' renames are destructive, so each could
-    // read its own token back and both would spawn a refresh.
-    // O_EXCL is the standard POSIX/libuv primitive that lets at
-    // most one process succeed. The updater runner uses the same O_EXCL
-    // ownership primitive for its separate update lock.
+    // Single-owner claim: O_EXCL atomic create. A temp+rename+readback
+    // pattern is racy — both peers' renames are destructive, so each could
+    // read its own token back and both would spawn a refresh. O_EXCL is the
+    // standard POSIX/libuv primitive that lets at most one process succeed.
+    // The updater runner uses the same O_EXCL ownership primitive for its
+    // separate update lock.
     const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
     const claim = () => {
       try {
@@ -563,6 +615,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 +668,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,10 +789,26 @@ 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');
 }
 
+// #360: the ONE reason string for "this session's memory injection resolved
+// to nothing" — every exit path that ends up with a falsy `memoryContext`
+// passes this through `output()`'s `recorded` argument, so a genuinely silent
+// session (`minimal` on an empty project, the no-database and
+// no-entities-table early exits) always leaves a trace of WHY nothing was
+// injected, instead of the generic `session-start-banner` outcome marker that
+// carries no `reason`. One helper, not three copies of the template string,
+// so the wording cannot drift between call sites.
+function nothingToInjectReason(level, detail) {
+  return `briefing-level: nothing to inject at "${level}" — ${detail}`;
+}
+
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => { input += chunk; });
@@ -653,13 +819,70 @@ process.stdin.on('end', async () => {
   let captureWarning = null;
   const withCaptureWarning = (msg) => {
     if (!captureWarning) return msg;
-    return `${captureWarning}\n${msg.replace(/^◉ MeMesh ready · /, '◉ MeMesh · ')}`;
+    // The populated-database path prepends an update banner ahead of the
+    // "◉ MeMesh ready · ..." summary line (`finalMessage = [...bannerLines,
+    // '', summary].join('\n')`), so that line is not at the START of `msg`
+    // whenever a banner is present — an un-flagged `^` only anchors to the
+    // whole string's start, so the demotion below would silently do nothing
+    // and "MeMesh ready" would leak through even while a write failure was
+    // being reported in the very same message. `m` anchors `^` to the start
+    // of ANY line instead.
+    return `${captureWarning}\n${msg.replace(/^◉ MeMesh ready · /m, '◉ MeMesh · ')}`;
   };
   try {
     try {
     const data = JSON.parse(input);
     const projectName = getProjectName(data.cwd);
 
+    // #360 — resolve the briefing level ONCE, before any exit path, so every
+    // emit below (including the no-database and empty-database early
+    // returns) agrees on what to include. env > config > default; an
+    // unknown value on either source is not a silent fallback — it is
+    // traced AND recorded on the hook's outcome channel, the same
+    // discipline every other silent-skip path in this file follows.
+    const configRead = readHookConfigResult(process.env);
+    const briefingResolution = resolveBriefingLevel(process.env, configRead.config);
+    const briefingLevel = briefingResolution.level;
+    const briefingPolicy = briefingLevelPolicy(briefingLevel);
+    if (briefingResolution.invalid) {
+      const { source, value } = briefingResolution.invalid;
+      try {
+        process.stderr.write(
+          `[memesh session-start] invalid ${source} briefing level ${value} — using "${briefingLevel}"\n`,
+        );
+      } catch { /* stderr gone */ }
+      recordHookOutcome(process.env, {
+        hook: 'session-start',
+        outcome: 'notified',
+        reason: `briefing-level: invalid ${source} value ${value}, using ${briefingLevel}`,
+      });
+    }
+    // The check above only catches an unusable VALUE for one known key
+    // (`briefing`) inside an otherwise-parseable config object. A config.json
+    // that is not even that — truncated JSON, a bare array/string/number/null
+    // at the top level — is swallowed by `readHookConfig()` into an empty
+    // `{}`, so every setting in it (not just `briefing`) reads as "not set"
+    // with no trace anywhere, while the CLI/MCP side (`core/config.ts`'s
+    // `warnUnreadable()`) reports this exact state. `readHookConfigResult()`'s
+    // `state` is what makes it visible here too — recorded once, regardless
+    // of which settings would have been affected, since the whole document
+    // was unusable, not one field.
+    if (configRead.state === 'unreadable') {
+      recordHookOutcome(process.env, {
+        hook: 'session-start',
+        outcome: 'notified',
+        reason: HOOK_CONFIG_UNREADABLE_REASON,
+      });
+    }
+    // The work-package notice is identical boilerplate every session (#360)
+    // — only `full` still carries it. `undefined`, not a conditional string
+    // literal at each call site: output()'s memoryContext parameter treats
+    // undefined as "nothing to add" the same way it always has.
+    // Read through the named predicate, not `.workPackageNotice` off the
+    // policy object directly — this file is the ONLY caller that should ever
+    // decide this (see the field comment in briefing-level.ts).
+    const workPackageNotice = sessionStartAppendsWorkPackageNotice(briefingLevel) ? WORK_PACKAGE_NOTICE : undefined;
+
     // Self-heal the citation contract.
     //
     // `install-hooks` writes it too, but a PLUGIN install never runs that
@@ -730,7 +953,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,8 +964,36 @@ process.stdin.on('end', async () => {
         const channel = detectInstallChannelHook(pluginRoot);
         consent = buildUpdateConsentPrompt(data.session_id, consentVersion, consentCache, channel);
       } catch { /* best-effort */ }
-      output(consent ? `${consent.system}\n${emptySummary}` : emptySummary,
-        consent ? `${consent.context}\n\n${workPackageGuidance}` : workPackageGuidance);
+      // 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 },
+      );
+      const noDbContext = consent
+        ? [consent.context, workPackageNotice].filter(Boolean).join('\n\n')
+        : workPackageNotice;
+      output(
+        consent ? `${consent.system}\n${emptySummary}` : emptySummary,
+        noDbContext,
+        // Nothing was injected (no notice at this level, no database to read
+        // from) — record why, the same as the schema-present empty path
+        // further down. `standard`/`full` reach this exact same branch: at
+        // `full` `noDbContext` is always truthy (the notice), so this never
+        // overrides anything for that level; at `standard` it can also be
+        // falsy here, which correctly gets the same reason (the record is
+        // level-agnostic, matching the schema-present path's own
+        // `!memoryContext` predicate, not a `minimal`-only check).
+        !noDbContext ? { outcome: 'notified', reason: nothingToInjectReason(briefingLevel, 'no database yet') } : null,
+      );
       if (consent) finalizeUpdatePromptClaim(data.session_id, consentVersion, consentCache?.latestVersion);
       return;
     }
@@ -770,7 +1020,14 @@ process.stdin.on('end', async () => {
         "SELECT name FROM sqlite_master WHERE type='table' AND name='entities'"
       ).get();
       if (!tableCheck) {
-        output(combineWithBanner(captureWarning ?? '◉ MeMesh ready · database initialised but no memories stored yet'));
+        output(
+          combineWithBanner(captureWarning ?? '◉ MeMesh ready · database initialised but no memories stored yet'),
+          workPackageNotice,
+          // Same reason mechanism as the no-database exit above and the
+          // schema-present exit below — see `nothingToInjectReason`'s own
+          // comment for why this is not `minimal`-gated explicitly.
+          !workPackageNotice ? { outcome: 'notified', reason: nothingToInjectReason(briefingLevel, 'database has no entities table yet') } : null,
+        );
         return;
       }
 
@@ -905,8 +1162,11 @@ process.stdin.on('end', async () => {
       // gives them a separate render budget. The project keeps `sessionLimit`
       // slots and its full character budget. The column is absent on
       // pre-namespace schemas; then this branch is simply empty.
+      // #360: minimal/standard skip these two queries outright rather than
+      // fetch-then-not-render — the whole point of the level is to stop
+      // paying for what is not the current project.
       let globalEntities = [];
-      if (colNames.has('namespace')) {
+      if (briefingPolicy.global && colNames.has('namespace')) {
         const globalQuery = buildScoringQuery('', `WHERE e.namespace = 'global' ${statusFilter}`);
         globalEntities = db.prepare(globalQuery).all(CANDIDATE_CAP)
           .filter(entity => isTrustedForAutoContext(entity.metadata))
@@ -917,15 +1177,18 @@ process.stdin.on('end', async () => {
       // recentStatusFilter is "WHERE status = 'active'" or "" — the bare-column
       // form is fine when there's no JOIN, but we now alias the table as `e`,
       // so rewrite to e.status for consistency.
-      const recentConditions = [
-        hasStatus ? "e.status = 'active'" : '',
-        colNames.has('namespace') ? "(e.namespace IS NULL OR e.namespace <> 'global')" : '',
-      ].filter(Boolean);
-      const recentWhere = recentConditions.length > 0 ? `WHERE ${recentConditions.join(' AND ')}` : '';
-      const recentQuery = buildScoringQuery('', recentWhere);
-      const recentEntities = db.prepare(recentQuery).all(CANDIDATE_CAP)
-        .filter(entity => isTrustedForAutoContext(entity.metadata))
-        .slice(0, 5);
+      let recentEntities = [];
+      if (briefingPolicy.foreign) {
+        const recentConditions = [
+          hasStatus ? "e.status = 'active'" : '',
+          colNames.has('namespace') ? "(e.namespace IS NULL OR e.namespace <> 'global')" : '',
+        ].filter(Boolean);
+        const recentWhere = recentConditions.length > 0 ? `WHERE ${recentConditions.join(' AND ')}` : '';
+        const recentQuery = buildScoringQuery('', recentWhere);
+        recentEntities = db.prepare(recentQuery).all(CANDIDATE_CAP)
+          .filter(entity => isTrustedForAutoContext(entity.metadata))
+          .slice(0, 5);
+      }
 
       // Lesson count (queried for summary, not listed individually).
       // Status-column gate matches the project/recent queries above —
@@ -1005,6 +1268,7 @@ process.stdin.on('end', async () => {
       const topLessons = lessonEntities.slice(0, 5);
 
       const memoryLines = [];
+      let memoryAssemblyFailed = false;
       try {
         const rankedIds = [
           ...topLessons.map(e => e.id),
@@ -1050,14 +1314,31 @@ process.stdin.on('end', async () => {
         const taskRow = db
           .prepare('SELECT metadata FROM entities WHERE name = ?')
           .get(taskStateName(projectName));
-        // SessionStart has no exact recipient identity. The shared leaf fails
-        // closed before querying, so hook and briefing cannot diverge here.
+        // Who this session is comes from `MEMESH_RECIPIENT` (see
+        // resolveMessageRecipient). Without it there is no exact recipient
+        // and the shared leaf returns no lines, so a session never sees a
+        // message addressed to anyone else.
+        // #360: briefingTaskStateLines downgrades a stale record to one line
+        // at EVERY level, and only consults `briefingPolicy.taskState` for a
+        // fresh one — `minimal` omits a fresh state entirely, never a stale
+        // flag. The unread-inbox line below is unconditional at every level:
+        // a message waiting for this agent is not "another project's
+        // memory", it is addressed to it. An inbox that cannot be read is
+        // recorded as its own `error` (a label, like the two below), and is
+        // not a failed memory assembly: the rest of the context still ships.
         const stateLines = [
-          ...taskStateLines(
+          ...briefingTaskStateLines(
             parseTaskState(parseEntityMetadata(taskRow?.metadata)),
             projectName,
+            new Date(),
+            { includeFresh: briefingPolicy.taskState },
           ),
-          ...unreadInboxLines(unreadDeliveryCount(db, projectName), projectName),
+          ...waitingMessageLines(db, resolveMessageRecipient(process.env), (err) =>
+            recordHookOutcome(process.env, {
+              hook: 'session-start',
+              outcome: 'error',
+              reason: `inbox: ${hookErrorReason(err)}`,
+            })),
         ];
 
         // The pools overlap by construction (a lesson tagged to this project
@@ -1099,47 +1380,170 @@ process.stdin.on('end', async () => {
         // means memories stop reaching the model again (the exact v4.2.7
         // regression this block was written to fix).
         try { process.stderr.write(`[memesh session-start] memory-context: ${err?.message || err}\n`); } catch {}
+        // Recorded like the index read's failure below (a label, never the
+        // message), so a failed assembly is not later reported as an empty
+        // project: at `minimal` the index read is skipped, and this is the
+        // only place the fault can surface.
+        memoryAssemblyFailed = true;
+        recordHookOutcome(process.env, {
+          hook: 'session-start',
+          outcome: 'error',
+          reason: `memory-context: ${hookErrorReason(err)}`,
+        });
+      }
+
+      // --- 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 = [];
+      // #360: `minimal` skips the index query outright — unlike the durable
+      // index EXPOSED by the `briefing` tool/CLI (a separately-requestable
+      // fact about the project), nothing else in this hook reads it, so
+      // there is no reason to pay for a read whose only consumer is a
+      // section this level does not render.
+      if (!briefingPolicy.index) {
+        indexLines = [];
+      } else 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.
+        // #360: only spacer-then-index when the index actually has lines to
+        // show (`minimal` sets indexLines = [] above) — otherwise this would
+        // leave a dangling blank line with nothing after it.
+        if (indexLines.length > 0) 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.
+      // #360: the work-package notice is `full`-only boilerplate; at every
+      // other level workPackageNotice is undefined and this is just the
+      // fenced block.
+      //
+      // When `memoryLines` is genuinely empty (no project content —
+      // `minimal` with nothing durable yet, and no repository-state prefix
+      // because that only prepends onto EXISTING topology lines) and there is
+      // no work-package notice either, wrapping nothing in the preamble + an
+      // empty ```text``` fence would spend 166+ characters informing the
+      // agent of literally nothing. Inject NOTHING instead.
+      // This can only happen at `minimal`: at `standard`/`full`,
+      // `indexLines` always carries at least its own empty-state line
+      // (#323 — "an index is a claim about the user's data", pinned by
+      // tests/core/briefing.test.ts and unchanged here on purpose), so
+      // `memoryLines` there is never actually empty.
+      //
+      // `hasBriefingContent` (work-topology.ts), not `memoryLines.length
+      // === 0` inline: `assembleBriefing` (src/core/briefing.ts) makes the
+      // IDENTICAL decision for the SAME reason on its own `block` array —
+      // the hook cannot call that function directly (A1a: a hook cannot
+      // import `../db.js`-dependent core modules), so this is the one place
+      // the two sides CAN share the rule.
+      const memoryContext = !hasBriefingContent(memoryLines) && !workPackageNotice
+        ? undefined
+        : workPackageNotice
+          ? buildReferenceContext(memoryLines) + '\n\n' + workPackageNotice
+          : buildReferenceContext(memoryLines);
+      // 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 +1555,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 +1622,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,13 +1652,37 @@ 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;
 
-      output(withCaptureWarning(finalMessage), updateConsentContext
-        ? `${updateConsentContext}\n\n${memoryContext}`
-        : memoryContext);
+      // memoryContext can now be undefined (nothing to inject at this level)
+      // — guard the concat so an empty injection does not become the LITERAL
+      // string "undefined" glued onto a real consent prompt.
+      output(
+        withCaptureWarning(finalMessage),
+        updateConsentContext
+          ? (memoryContext ? `${updateConsentContext}\n\n${memoryContext}` : updateConsentContext)
+          : memoryContext,
+        // A specific, greppable reason for the "genuinely nothing to inject"
+        // case, distinct from the generic 'session-start-banner' entity
+        // marker output() would otherwise record for ANY falsy
+        // memoryContext. The no-database and no-entities-table early exits
+        // above record through the SAME `nothingToInjectReason` helper with
+        // their own `detail`. Not recorded when the memory assembly threw:
+        // that failure has its own error record, and an empty result it
+        // caused must not also be reported as an empty project.
+        !memoryContext && !memoryAssemblyFailed
+          ? { outcome: 'notified', reason: nothingToInjectReason(briefingLevel, 'no project content, no repository state, index excluded') }
+          : null,
+      );
       if (updateConsentContext) {
         finalizeUpdatePromptClaim(data.session_id, installedVersion, updateCache?.latestVersion);
       }
@@ -1317,7 +1753,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 ──────────────────────────────
@@ -1353,9 +1796,26 @@ process.stdin.on('end', async () => {
  *
  * The shape is asserted by tests/helpers/hook-output-contract.ts.
  */
-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.';
+// The notice's literal text is `_shared.js`'s exported `WORK_PACKAGE_NOTICE`
+// — single owner, shared with the test suite instead of a second hardcoded
+// copy there.
 
-function output(text, memoryContext = workPackageGuidance) {
+// #360: `memoryContext` deliberately has no default. A default of
+// `WORK_PACKAGE_NOTICE` would give any call site that passed only `text` the
+// notice regardless of level — exactly the kind of default that silently
+// reintroduces what a level was supposed to drop. Every call site passes its
+// memoryContext (or `workPackageNotice`, already gated) explicitly;
+// `undefined` here means "this exit has nothing to add", not "fall back to
+// the notice".
+function output(text, memoryContext = undefined, 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 +1824,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',
+    });
 }