@jhizzard/termdeck-stack 0.6.1 → 0.6.3

package/assets/hooks/memory-session-end.js

@@ -36,7 +36,32 @@
  *      (last ~30 message excerpts).
  *   7. Embeds the summary via OpenAI text-embedding-3-small.
  *   8. POSTs ONE row to Supabase /rest/v1/memory_items with source_type='session_summary'.
- *   9. Logs every step to ~/.claude/hooks/memory-hook.log.
+ *   9. (Sprint 51.6 T3) POSTs ONE row to Supabase /rest/v1/memory_sessions with
+ *      Prefer: resolution=merge-duplicates so SessionEnd-fires-twice resolves
+ *      to a single row. Requires Mnestra migration 017 on canonical installs;
+ *      petvetbid already has the rich schema from rag-system bootstrap.
+ *  10. Logs every step to ~/.claude/hooks/memory-hook.log.
+ *
+ * Version stamp (Sprint 51.6 T3 — hook upgrade gap fix):
+ *   The marker `@termdeck/stack-installer-hook v<N>` below is read by both
+ *   stack-installer's installSessionEndHook (version-aware overwrite under
+ *   --yes) and `termdeck init --mnestra` (refreshBundledHookIfNewer step).
+ *   Bump the integer whenever a change to this file should overwrite an
+ *   already-installed copy on the user's machine — e.g. a new write path,
+ *   a new transcript parser, a default PROJECT_MAP change. Comment-only
+ *   tweaks do not need a bump.
+ *
+ *   v2 (Sprint 51.7 T2 — metadata completeness + wire-up insurance):
+ *     - parseTranscriptMetadata() now populates memory_sessions.started_at /
+ *       duration_minutes / facts_extracted from per-message timestamps and
+ *       memory_remember tool_use counts, closing the v1 "minimum viable row"
+ *       gap Codex flagged at Sprint 51.6 Phase B.
+ *     - Stamp bump load-bearing as INSURANCE for the Sprint 51.6 wire-up bug
+ *       (T1 fix landing in same v1.0.3 wave): an installed-v1 user upgrading
+ *       to bundled-v2 always passes the `installed >= bundled` short-circuit
+ *       at init-mnestra.js:550 and reaches the refresh path.
+ *
+ * @termdeck/stack-installer-hook v2
  *
  * Required env vars (validated at entry, after the secrets.env fallback):
  *   - SUPABASE_URL              e.g. https://<project-ref>.supabase.co
@@ -73,13 +98,43 @@ function resolveSecretsPath() {
     || join(os.homedir(), '.termdeck', 'secrets.env');
 }
 
-// PROJECT_MAP — minimal default. Users extend by adding entries to this array.
-// Patterns match against the cwd reported by Claude Code at Stop time.
+// PROJECT_MAP — most-specific-first ordering (Sprint 41 design).
+// Patterns match against the cwd reported by Claude Code at SessionEnd.
 // First match wins; falls through to "global".
+//
+// Sprint 51.6 (T1 side finding b): a previous version shipped this array
+// empty, which caused every session to tag as "global" — orphaning rows
+// from project-scoped memory_recall queries. The default below restores
+// the most-specific-first taxonomy from Sprint 41 T1, generalized for
+// universal shipping. Users still extend in place by editing this array.
+//
+// Patterns NOT specific to Joshua's filesystem (e.g. /\/PVB\//i, /\/DOR\//i)
+// are kept because they're benign on other machines — the regex simply
+// doesn't fire on cwds that don't contain those segments. The chopin-
+// nashville catch-all stays LAST (structural invariant) so a TermDeck cwd
+// inside ChopinNashville/SideHustles/ resolves to "termdeck", not the
+// catch-all.
 const PROJECT_MAP = [
-  // Example entries — uncomment + edit, or add your own:
-  // { pattern: /\/myproject\//i,        project: 'my-project' },
-  // { pattern: /work-stuff/i,           project: 'work' },
+  // ── Active code projects (most-specific FIRST) ──
+  { pattern: /\/SideHustles\/TermDeck\/termdeck/i,           project: 'termdeck' },
+  { pattern: /\/Graciella\/engram(\/|$)/i,                    project: 'mnestra' },
+  { pattern: /\/Graciella\/rumen(\/|$)/i,                     project: 'rumen' },
+  { pattern: /\/Graciella\/rag-system(\/|$)/i,                project: 'rag-system' },
+  { pattern: /\/ChopinInBohemia\/podium(\/|$)/i,              project: 'podium' },
+  { pattern: /\/ChopinInBohemia(\/|$)/i,                      project: 'chopin-in-bohemia' },
+  { pattern: /\/SideHustles\/SchedulingApp(\/|$)/i,           project: 'chopin-scheduler' },
+  { pattern: /\/ChopinNashville\/SchedulingApp(\/|$)/i,       project: 'chopin-scheduler' },
+  { pattern: /\/Graciella\/PVB(\/|$)|\/PVB\/pvb(\/|$)/i,      project: 'pvb' },
+  { pattern: /\/Unagi\/gorgias-ticket-monitor(\/|$)/i,        project: 'claimguard' },
+  { pattern: /\/ChopinNashville\/SideHustles\/ClaimGuard(\/|$)/i, project: 'claimguard' },
+  { pattern: /\/Documents\/DOR(\/|$)/i,                       project: 'dor' },
+  { pattern: /\/Graciella\/joshuaizzard-dev(\/|$)/i,          project: 'portfolio' },
+  { pattern: /\/Graciella\/imessage-reader(\/|$)/i,           project: 'imessage-reader' },
+
+  // ── chopin-nashville catch-all (MUST be LAST among /ChopinNashville/ matchers).
+  // Sprint 35 + 41 lesson: any /ChopinNashville/-matching pattern placed below
+  // this entry gets shadowed and the row mis-tags as 'chopin-nashville'.
+  { pattern: /\/ChopinNashville(\/|$)/i,                      project: 'chopin-nashville' },
 ];
 
 const MIN_TRANSCRIPT_BYTES = parseInt(process.env.TERMDECK_HOOK_MIN_BYTES || '5000', 10);
@@ -395,6 +450,117 @@ function selectTranscriptParser(sessionType) {
   return { parser: parseAutoDetect, sessionType: 'auto' };
 }
 
+// ──────────────────────────────────────────────────────────────────────────
+// Sprint 51.7 T2 — transcript metadata extractor for memory_sessions.
+//
+// The v1 bundled hook (Sprint 51.6 T3) intentionally shipped the "minimum
+// viable row" — postMemorySession set started_at, duration_minutes, and
+// facts_extracted to NULL/0 because v1 omitted transcript parsing for
+// per-message timestamps. The legacy rag-system writer
+// (~/Documents/Graciella/rag-system/src/scripts/process-session.ts) populated
+// those fields by parsing the transcript JSONL passed to it on stdin, and
+// petvetbid's 289 baseline rows carried the rich shape from that writer.
+// v2 closes the gap in pure Node so the bundled hook reaches parity without
+// the rag-system dependency (Class E hidden-dependency rule).
+//
+// Heuristic for facts_extracted: count distinct `tool_use` blocks whose
+// `name` matches a memory_remember MCP tool. Conservative by design — a
+// regex like /Remember:/ inside summary text would over-match quoted user
+// content (e.g., "the user typed 'Remember:' in their prompt"). Counting
+// tool_use blocks instead measures what was actually written into the store
+// during the session, which is the semantic the rag-system writer used.
+//
+// Tool name variants observed in real transcripts (T4-CODEX 11:09 ET pre-
+// audit confirmed both prefixes are live in `~/.claude/projects/`):
+//   - `memory_remember`               (bare; CC native + future-proofing)
+//   - `mcp__mnestra__memory_remember` (current Mnestra MCP, post-rename)
+//   - `mcp__memory__memory_remember`  (legacy MCP server name from when
+//                                       the project was called "memory")
+// Counting all three avoids undercounting on existing user transcripts.
+// ──────────────────────────────────────────────────────────────────────────
+
+const FACT_TOOL_NAMES = new Set([
+  'memory_remember',
+  'mcp__mnestra__memory_remember',
+  'mcp__memory__memory_remember',
+]);
+
+// Sprint 51.7 T2 / T4-CODEX 11:13 ET catch: each adapter shipped by this
+// hook stores message content under a different key shape, and we have to
+// match all of them or facts_extracted under-counts whenever a non-Claude
+// session writes to memory_sessions. Mirror the shapes already documented
+// at the top of TRANSCRIPT_PARSERS:
+//
+//   - Claude Code (current):  msg.message.content[]
+//   - Grok (Sprint 50 T1):    msg.content[] (flat, AI SDK provider shape)
+//   - Codex (response_item):  msg.payload.content[] when msg.type === 'response_item'
+//
+// Gemini's single-JSON envelope doesn't apply per-line — its content lives
+// inside a top-level messages array, and each entry's content is a flat
+// array OR a string. extractContentBlocks() handles flat arrays; strings
+// are skipped (no tool_use can hide inside a string).
+function extractContentBlocks(msg) {
+  if (!msg || typeof msg !== 'object') return null;
+  if (msg.message && Array.isArray(msg.message.content)) return msg.message.content;
+  if (Array.isArray(msg.content)) return msg.content;
+  if (msg.type === 'response_item' && msg.payload && Array.isArray(msg.payload.content)) {
+    return msg.payload.content;
+  }
+  return null;
+}
+
+function parseTranscriptMetadata(rawJsonl) {
+  if (typeof rawJsonl !== 'string' || rawJsonl.length === 0) {
+    return { startedAt: null, endedAt: null, durationMinutes: null, factsExtracted: 0 };
+  }
+  const lines = rawJsonl.split('\n').filter(Boolean);
+  let earliestTs = null;
+  let latestTs = null;
+  let factsExtracted = 0;
+
+  for (const line of lines) {
+    let msg;
+    try { msg = JSON.parse(line); } catch (_) { continue; }
+    if (!msg || typeof msg !== 'object') continue;
+
+    // Timestamp: top-level `timestamp` is the canonical Claude Code shape.
+    // Fall back to `msg.message.timestamp` for any future / alt-shape that
+    // nests it (Codex/Gemini/Grok adapters preserve the top-level form, so
+    // this is mostly forward-compat).
+    const ts = msg.timestamp || (msg.message && msg.message.timestamp);
+    if (typeof ts === 'string' || typeof ts === 'number') {
+      const t = Date.parse(ts);
+      if (!Number.isNaN(t)) {
+        if (earliestTs === null || t < earliestTs) earliestTs = t;
+        if (latestTs === null || t > latestTs) latestTs = t;
+      }
+    }
+
+    // facts_extracted: count tool_use blocks matching a memory_remember
+    // MCP tool name. See FACT_TOOL_NAMES + extractContentBlocks above.
+    const blocks = extractContentBlocks(msg);
+    if (blocks) {
+      for (const b of blocks) {
+        if (b && b.type === 'tool_use' && typeof b.name === 'string' && FACT_TOOL_NAMES.has(b.name)) {
+          factsExtracted += 1;
+        }
+      }
+    }
+  }
+
+  const startedAt = earliestTs !== null ? new Date(earliestTs).toISOString() : null;
+  const endedAt = latestTs !== null ? new Date(latestTs).toISOString() : null;
+  const durationMinutes = (earliestTs !== null && latestTs !== null)
+    ? Math.max(0, Math.round((latestTs - earliestTs) / 60000))
+    : null;
+  return { startedAt, endedAt, durationMinutes, factsExtracted };
+}
+
+// Sprint 51.6 T3 → 51.7 T2: `buildSummary` now also returns parser-derived
+// metadata (startedAt, endedAt, durationMinutes, factsExtracted) merged into
+// the result object. parseTranscriptMetadata reuses the same raw string —
+// no second readFileSync. Returns null when the transcript is unreadable or
+// has fewer than 5 messages (skip semantics unchanged from v1).
 function buildSummary(transcriptPath, sessionType) {
   let raw;
   try { raw = readFileSync(transcriptPath, 'utf8'); }
@@ -418,7 +584,18 @@ function buildSummary(transcriptPath, sessionType) {
     tail.map((m) => `[${m.role}] ${m.content}`).join('\n');
   // OpenAI text-embedding-3-small accepts up to 8192 tokens (~32K chars).
   // 7000 chars is a safe headroom that survives multibyte expansion.
-  return summary.slice(0, 7000);
+
+  // Sprint 51.7 T2: merge transcript-derived metadata so the caller (
+  // processStdinPayload → postMemorySession) can populate the
+  // memory_sessions.started_at/duration_minutes/facts_extracted fields the
+  // v1 hook left NULL/0.
+  const metadata = parseTranscriptMetadata(raw);
+
+  return {
+    summary: summary.slice(0, 7000),
+    messagesCount: messages.length,
+    ...metadata,
+  };
 }
 
 async function embedText(text, openaiKey) {
@@ -494,6 +671,89 @@ async function postMemoryItem({ supabaseUrl, supabaseKey, content, embedding, pr
   }
 }
 
+// Sprint 51.6 T3 — companion write to memory_sessions.
+//
+// History: the bundled hook never wrote memory_sessions until v1.0.2. Joshua's
+// PRIOR personal rag-system hook spawned process-session.ts which inserted
+// memory_sessions rows; the Sprint 38 P0 rewrite replaced that hook with a
+// Mnestra-direct hook that only wrote memory_items. Result: from 2026-05-02
+// 13:24 ET (when bundled overwrote personal) until v1.0.2, no memory_sessions
+// rows accumulated. Sprint 51.6 T1+T2+T3 documented the gap; this function
+// closes it.
+//
+// Schema target: Mnestra migration 017 brings canonical engram in line with
+// petvetbid's rag-system flavor (session_id, summary_embedding, started_at,
+// ended_at, duration_minutes, messages_count, transcript_path, etc). The
+// bundled hook writes the rich shape on every install — fresh-canonical
+// (post-mig-017) and petvetbid alike.
+//
+// Idempotency: Prefer: resolution=merge-duplicates relies on the
+// memory_sessions_session_id_key unique constraint. Mig 017 adds it where
+// absent. SessionEnd-fires-twice (e.g. /exit then PTY close) resolves to a
+// single row.
+async function postMemorySession({
+  supabaseUrl, supabaseKey,
+  summary, summaryEmbedding,
+  project, sessionId,
+  transcriptPath, messagesCount,
+  endedAt,
+  // Sprint 51.7 T2 — transcript-derived metadata (closes Sprint 51.6's
+  // started_at/duration_minutes/facts_extracted=NULL gap). All optional;
+  // null/null/0 fallback preserves the v1 minimum-viable-row shape when the
+  // transcript carries no timestamps (e.g. legacy fixtures, pre-CC-2.x
+  // payloads, or hand-fed test inputs).
+  startedAt = null,
+  durationMinutes = null,
+  factsExtracted = 0,
+}) {
+  if (!sessionId) {
+    log('memory-sessions-skip: sessionId missing — cannot satisfy session_id NOT NULL/UNIQUE.');
+    return false;
+  }
+  try {
+    // Sprint 51.6 T3 / T4-CODEX audit 20:23 ET: PostgREST requires both
+    // `Prefer: resolution=merge-duplicates` AND `?on_conflict=<column>`
+    // on the URL to trigger an UPSERT. Without `on_conflict=session_id`
+    // a duplicate fire would error against memory_sessions_session_id_key.
+    const res = await fetch(`${supabaseUrl}/rest/v1/memory_sessions?on_conflict=session_id`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'apikey': supabaseKey,
+        'Authorization': `Bearer ${supabaseKey}`,
+        'Prefer': 'resolution=merge-duplicates,return=minimal',
+      },
+      body: JSON.stringify({
+        session_id: sessionId,
+        summary,
+        summary_embedding: Array.isArray(summaryEmbedding)
+          ? `[${summaryEmbedding.join(',')}]`
+          : null,
+        project,
+        // Sprint 51.7 T2: started_at + duration_minutes + facts_extracted now
+        // populated from parseTranscriptMetadata when transcript timestamps
+        // are present. files_changed and topics remain unpopulated (would
+        // require diff parsing the bundled hook doesn't have; deferred).
+        started_at: typeof startedAt === 'string' ? startedAt : null,
+        ended_at: (endedAt instanceof Date ? endedAt : new Date()).toISOString(),
+        duration_minutes: typeof durationMinutes === 'number' ? durationMinutes : null,
+        messages_count: typeof messagesCount === 'number' ? messagesCount : 0,
+        facts_extracted: typeof factsExtracted === 'number' ? factsExtracted : 0,
+        transcript_path: transcriptPath || null,
+      }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      log(`memory-sessions-insert-failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+      return false;
+    }
+    return true;
+  } catch (e) {
+    log(`memory-sessions-insert-exception: ${e.message}`);
+    return false;
+  }
+}
+
 async function processStdinPayload(input) {
   let data;
   try { data = JSON.parse(input); }
@@ -543,13 +803,21 @@ async function processStdinPayload(input) {
   const project = detectProject(cwd);
   debug(`project="${project}", session=${sessionId}, sessionType=${sessionType}`);
 
-  const summary = buildSummary(transcriptPath, sessionType);
-  if (!summary) return;
+  const built = buildSummary(transcriptPath, sessionType);
+  if (!built) return;
+  const {
+    summary,
+    messagesCount,
+    startedAt: parsedStartedAt,
+    endedAt: parsedEndedAt,
+    durationMinutes,
+    factsExtracted,
+  } = built;
 
   const embedding = await embedText(summary, env.openaiKey);
   if (!embedding) return;
 
-  const ok = await postMemoryItem({
+  const itemOk = await postMemoryItem({
     supabaseUrl: env.supabaseUrl,
     supabaseKey: env.supabaseKey,
     content: summary,
@@ -559,7 +827,34 @@ async function processStdinPayload(input) {
     sourceAgent,
   });
 
-  if (ok) log(`ingested: project="${project}" session=${sessionId} bytes=${summary.length} sessionType=${sessionType} sourceAgent=${normalizeSourceAgent(sourceAgent)}`);
+  // Sprint 51.6 T3: companion memory_sessions write. Independent of the
+  // memory_items write — a memory_items failure shouldn't suppress the
+  // memory_sessions row, and vice versa. Both errors fail-soft.
+  //
+  // Sprint 51.7 T2: prefer parser-derived `endedAt` (last-message
+  // timestamp) over hook-fire-time when the transcript carried timestamps.
+  // Matches the rag-system writer's semantics — `ended_at` is "when the
+  // conversation last had activity," not "when the SessionEnd hook
+  // happened to fire." Falls back to `new Date()` when the parser found
+  // no timestamps, preserving v1 behavior.
+  const sessionOk = await postMemorySession({
+    supabaseUrl: env.supabaseUrl,
+    supabaseKey: env.supabaseKey,
+    summary,
+    summaryEmbedding: embedding,
+    project,
+    sessionId,
+    transcriptPath,
+    messagesCount,
+    endedAt: parsedEndedAt ? new Date(parsedEndedAt) : new Date(),
+    startedAt: parsedStartedAt,
+    durationMinutes,
+    factsExtracted,
+  });
+
+  if (itemOk || sessionOk) {
+    log(`ingested: project="${project}" session=${sessionId} bytes=${summary.length} messages=${messagesCount} sessionType=${sessionType} sourceAgent=${normalizeSourceAgent(sourceAgent)} startedAt=${parsedStartedAt || 'null'} durationMin=${durationMinutes === null ? 'null' : durationMinutes} factsExtracted=${factsExtracted} memory_items=${itemOk ? 'ok' : 'fail'} memory_sessions=${sessionOk ? 'ok' : 'fail'}`);
+  }
 }
 
 // Module-export contract for testability. When run as a script (require.main === module),
@@ -579,6 +874,8 @@ if (require.main === module) {
     buildSummary,
     embedText,
     postMemoryItem,
+    // Sprint 51.6 T3 — memory_sessions write companion.
+    postMemorySession,
     processStdinPayload,
     LOG_FILE,
     // Sprint 45 T4 — adapter-pluggable transcript-parser surface.
@@ -593,5 +890,9 @@ if (require.main === module) {
     // Sprint 50 T2 — source_agent provenance plumbing.
     normalizeSourceAgent,
     ALLOWED_SOURCE_AGENTS,
+    // Sprint 51.7 T2 — transcript-metadata extractor for memory_sessions.
+    parseTranscriptMetadata,
+    FACT_TOOL_NAMES,
+    extractContentBlocks,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck-stack",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "One-command installer for the TermDeck developer memory stack: TermDeck + Mnestra + Rumen + Supabase MCP",
   "bin": {
     "termdeck-stack": "./src/index.js"

package/src/index.js

@@ -525,6 +525,61 @@ function _compareHookFiles(srcPath, destPath) {
   return a.equals(b) ? 'identical' : 'different';
 }
 
+// Sprint 51.6 T3 — version-aware overwrite gate. The bundled hook carries a
+// `// @termdeck/stack-installer-hook v<N>` marker; bumping <N> means "the
+// next install should overwrite a stale copy on the user's machine even
+// under --yes." Without this, --yes preserved the existing hook (the safe
+// default for hand-edited files) and never landed bundled fixes — the gap
+// Codex surfaced in Sprint 51.6 (item #2 of the 5-part fix).
+const HOOK_SIGNATURE_REGEX = /@termdeck\/stack-installer-hook\s+v(\d+)/;
+
+function _readHookSignatureVersion(filepath) {
+  try {
+    const head = fs.readFileSync(filepath, 'utf8').slice(0, 4096);
+    const m = head.match(HOOK_SIGNATURE_REGEX);
+    return m ? parseInt(m[1], 10) : null;
+  } catch (_) { return null; }
+}
+
+// Sprint 51.6 T4-CODEX audit 20:23 ET — safety gate: only auto-overwrite an
+// unsigned installed hook when it was clearly TermDeck-managed (carries one
+// of the docstring markers from a prior bundled cut). A genuinely custom
+// user hook with no TermDeck fingerprint stays put under --yes; the user
+// gets prompted (interactive) or must `--force-overwrite`. Markers are
+// matched in the first 4KB so a long custom file with TermDeck mentions
+// in the body doesn't false-positive.
+const TERMDECK_MANAGED_MARKERS = [
+  /TermDeck session-end memory hook/,
+  /@jhizzard\/termdeck-stack/,
+  /Vendored into ~\/\.claude\/hooks\/memory-session-end\.js by @jhizzard/i,
+];
+
+function _looksTermdeckManaged(filepath) {
+  try {
+    const head = fs.readFileSync(filepath, 'utf8').slice(0, 4096);
+    return TERMDECK_MANAGED_MARKERS.some((m) => m.test(head));
+  } catch (_) { return false; }
+}
+
+// Returns true when the bundled hook's version stamp is strictly newer than
+// the installed one (or the installed file is unsigned BUT visibly TermDeck-
+// managed — older installs pre-Sprint-51.6 had no marker, treat them as v0).
+// Returns false when the bundled hook itself is unsigned (safety: a missing
+// source marker means "don't auto-overwrite") OR the installed file is
+// unsigned and looks like a custom user hook (no TermDeck fingerprint).
+// Used to gate --yes overwrite under installSessionEndHook.
+function _hookSignatureUpgradeAvailable(sourcePath, destPath) {
+  const bundled = _readHookSignatureVersion(sourcePath);
+  if (bundled === null) return false; // bundled unsigned — never auto-overwrite
+  const installed = _readHookSignatureVersion(destPath);
+  if (installed === null) {
+    // Installed has no version stamp. Only auto-overwrite if it looks
+    // TermDeck-managed; otherwise preserve as a possible user-custom hook.
+    return _looksTermdeckManaged(destPath);
+  }
+  return bundled > installed;
+}
+
 async function promptYesNo({ question, defaultYes = true }) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   const suffix = defaultYes ? '(Y/n)' : '(y/N)';
@@ -583,8 +638,12 @@ async function installSessionEndHook(opts = {}) {
     statusLine(`${ANSI.dim}=${ANSI.reset}`, 'hook file', 'already present, identical contents');
     fileStatus = 'already-current';
   } else {
-    // different
-    const overwrite = opts.assumeYes ? false // --yes preserves existing on overwrite
+    // different. Sprint 51.6 T3: under --yes, consult the version stamp —
+    // a strictly newer bundled stamp (or an unsigned existing file) means
+    // we should refresh; same-or-older stamp keeps existing. This closes
+    // the upgrade gap where bundled fixes never reached users' machines.
+    const overwrite = opts.assumeYes
+      ? _hookSignatureUpgradeAvailable(sourcePath, destPath)
       : opts.forceOverwrite ? true
       : await promptOverwrite();
     if (!overwrite) {
@@ -594,6 +653,12 @@ async function installSessionEndHook(opts = {}) {
       statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would overwrite ${destPath}`);
       fileStatus = 'would-overwrite';
     } else {
+      // Sprint 51.6 T3: timestamped backup before overwrite so a hand-
+      // edited PROJECT_MAP or comment is recoverable. Matches the pattern
+      // ~/.claude/hooks/memory-session-end.js.bak.<YYYYMMDDhhmmss> Joshua
+      // already had on disk from prior installs.
+      const stamp = new Date().toISOString().replace(/[-:T.Z]/g, '').slice(0, 14);
+      try { fs.copyFileSync(destPath, `${destPath}.bak.${stamp}`); } catch (_) { /* best-effort */ }
       fs.copyFileSync(sourcePath, destPath);
       fs.chmodSync(destPath, 0o644);
       statusLine(`${ANSI.green}↻${ANSI.reset}`, 'hook file', `overwrote ${destPath}`);
@@ -788,8 +853,15 @@ module.exports._readSettingsJson = _readSettingsJson;
 module.exports._writeSettingsJson = _writeSettingsJson;
 module.exports._isSessionEndHookEntry = _isSessionEndHookEntry;
 module.exports._compareHookFiles = _compareHookFiles;
+// Sprint 51.6 T3 — version-aware hook refresh helpers. Exported so init-mnestra
+// (and tests) can gate refresh decisions on the same logic the installer uses.
+module.exports._readHookSignatureVersion = _readHookSignatureVersion;
+module.exports._hookSignatureUpgradeAvailable = _hookSignatureUpgradeAvailable;
+module.exports.HOOK_SIGNATURE_REGEX = HOOK_SIGNATURE_REGEX;
 module.exports.installSessionEndHook = installSessionEndHook;
 module.exports.HOOK_COMMAND = HOOK_COMMAND;
+module.exports.HOOK_SOURCE = HOOK_SOURCE;
+module.exports.HOOK_DEST = HOOK_DEST;
 module.exports.HOOK_TIMEOUT_SECONDS = HOOK_TIMEOUT_SECONDS;
 module.exports.HOOK_SOURCE = HOOK_SOURCE;
 module.exports._mcpInternals = _mcpInternals;