@jhizzard/termdeck 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/cli/src/init-mnestra.js

@@ -10,7 +10,9 @@
 //      existing values. Done BEFORE any database work so a later pg connect
 //      or migration failure doesn't lose the user's typed-in keys.
 //   3. Connect via `pg` using the direct URL
-//   4. Apply the six bundled Mnestra migrations in order
+//   4. Apply all bundled Mnestra migrations in order (currently 17 — count
+//      grows over time; audit-upgrade probes for any not yet applied and
+//      runs them idempotently against existing installs)
 //   5. Update ~/.termdeck/config.yaml — set rag.enabled: false (MCP-only
 //      default; opt into TermDeck-side RAG via dashboard toggle) and point
 //      at ${VAR} refs (only after migrations apply cleanly — otherwise the
@@ -75,7 +77,7 @@ const HELP = [
   '     saved values if a complete set already exists in secrets.env.',
   '  2. Writes ~/.termdeck/secrets.env IMMEDIATELY (merge-aware) so a later',
   '     pg connect or migration failure does not lose what you typed in.',
-  '  3. Connects to Postgres and applies the six Mnestra schema + RPC migrations.',
+  '  3. Connects to Postgres and applies all bundled Mnestra schema + RPC migrations.',
   '  4. Updates ~/.termdeck/config.yaml — sets rag.enabled: false (MCP-only',
   '     default) and references ${VAR} keys for credentials.',
   '  5. Verifies the Mnestra store is reachable via memory_status_aggregation().',
@@ -182,7 +184,8 @@ This wizard configures TermDeck's Tier 2 memory layer (Mnestra) by:
   4. Asking for an Anthropic API key (optional, summaries)
   5. Writing ~/.termdeck/secrets.env (before any database work, so a
      pg failure cannot lose what you typed in)
-  6. Connecting to Postgres + applying six SQL migrations
+  6. Connecting to Postgres + applying all bundled SQL migrations
+     (audit-upgrade detects + applies any missing on existing installs)
   7. Updating ~/.termdeck/config.yaml — rag.enabled: false (MCP-only
      default; toggle in dashboard later) with \${VAR} refs (only after
      migrations apply cleanly)
@@ -567,6 +570,265 @@ function refreshBundledHookIfNewer(opts = {}) {
   return { status: 'refreshed', from: installed, to: bundled, backup };
 }
 
+// Sprint 51.7 T1 — wizard wire-up bug fix.
+//
+// Moved upstream of `pgRunner.connect` and the migration-replay loop so
+// DB-side failures (Class A schema drift, network blips, partial state)
+// cannot strand the hook upgrade. Joshua's 2026-05-03 Phase B run threw at
+// `applyMigrations()` on `001_mnestra_tables.sql` (the `match_memories`
+// CREATE OR REPLACE return-type drift on petvetbid — existing function had
+// columns in a different order, Postgres rejected with "cannot change return
+// type of existing function"). Outer catch at the old call site fired and
+// returned exit 5; the refresh at the old wire-up never ran. Brad's
+// jizzard-brain reproduced the same symptom under v1.0.2.
+//
+// Hook refresh is a LOCAL filesystem operation. It has no dependency on DB
+// success, so it should run as part of the initial local-setup phase next
+// to `writeSecretsFile`, not buried after a 17-migration replay. This also
+// means the wizard ALWAYS lands the bundled hook on disk after a successful
+// `npm install -g @jhizzard/termdeck@latest && termdeck init --mnestra`,
+// even when the DB phase fails — a meaningful upgrade-path improvement
+// because the hook fix is independently valuable.
+//
+// `--dry-run` exercises this path with `dryRun: true` so the wizard
+// truthfully reports what WOULD happen on a live run (Sprint 51.6 Phase B
+// dry-run probe couldn't catch the wire-up bug because dry-run early-
+// returned BEFORE the old refresh location at line 677).
+//
+// Stderr instrumentation is gated behind `TERMDECK_DEBUG_WIREUP=1` so
+// production users never see noise; the gate is broadly useful for future
+// wire-up bisects (any developer can re-run the wizard with the env var
+// set and get a deterministic trace).
+// Sprint 51.8 — settings.json wiring migration (Brad's v1.0.3 follow-up).
+//
+// Sprint 51.7 fixed the Class M wire-up bug — `runHookRefresh()` runs
+// upstream of the DB phase so the v2 hook FILE always lands. But the
+// settings.json wiring half of `installSessionEndHook` (in
+// `packages/stack-installer/src/index.js`) was never lifted into the
+// wizard. Result: anyone whose `~/.claude/settings.json` was wired by a
+// pre-Sprint-48 stack-installer (= `@jhizzard/termdeck-stack@<=0.5.0`,
+// matching anyone who first ran `termdeck init --mnestra` on
+// v1.0.0/v1.0.1) gets the v2 hook FILE post-1.0.3, but the file is still
+// wired under `Stop`. The v2 hook does not gate on event type, so it
+// fires every assistant turn and writes N `session_summary` rows in
+// `memory_items` per session (Brad's 2026-05-04 jizzard-brain repro).
+//
+// `_mergeSessionEndHookEntry` is a 1:1 hoist of the same-named function
+// in `packages/stack-installer/src/index.js:451`. We can't `require()`
+// across to it because the published `@jhizzard/termdeck` tarball ships
+// only `packages/stack-installer/assets/hooks/**`, not `.../src/**` —
+// the settings.json migration logic is unreachable at runtime from the
+// wizard's own tarball. Hoisting is correct here; the function is pure
+// (~50 LOC, no I/O), the upstream is exhaustively covered by
+// `tests/stack-installer-hook-merge.test.js`, and a duplicate copy
+// avoids cross-package version-coupling.
+//
+// Why we run this on every wizard pass, not just first install: the
+// whole point is to self-heal old Stop wirings on upgrade. Idempotent —
+// if SessionEnd is already correct, this no-ops and prints
+// `already wired`. Brad's framing: "settings.json invariants the wizard
+// must enforce" (INSTALLER-PITFALLS.md ledger #16). The wizard is the
+// canonical place to enforce them because it's the only path users
+// actually run after upgrading the package.
+
+const SETTINGS_JSON_PATH = path.join(require('os').homedir(), '.claude', 'settings.json');
+const HOOK_COMMAND = 'node ~/.claude/hooks/memory-session-end.js';
+const HOOK_TIMEOUT_SECONDS = 30;
+
+function _isSessionEndHookEntry(entry) {
+  return entry && typeof entry.command === 'string'
+    && entry.command.includes('memory-session-end.js');
+}
+
+// Pure: merges our SessionEnd entry into the given settings object.
+// Idempotent. Returns { settings, status } where status is one of
+// 'already-installed', 'installed', or 'migrated-from-stop'. Mutates
+// the input. Mirrors `_mergeSessionEndHookEntry` in
+// `packages/stack-installer/src/index.js:451` byte-for-byte (modulo
+// constants pulled from this file's scope).
+function _mergeSessionEndHookEntry(settings, opts = {}) {
+  const command = opts.command || HOOK_COMMAND;
+  const timeout = opts.timeout != null ? opts.timeout : HOOK_TIMEOUT_SECONDS;
+  const entry = { type: 'command', command, timeout };
+
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+
+  // Migrate any pre-Sprint-48 Stop registration of OUR hook to SessionEnd.
+  // Only entries matching `_isSessionEndHookEntry` are touched — any
+  // unrelated Stop hooks the user has are preserved verbatim.
+  let migrated = false;
+  if (Array.isArray(settings.hooks.Stop)) {
+    for (const group of settings.hooks.Stop) {
+      if (!group || !Array.isArray(group.hooks)) continue;
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter((e) => !_isSessionEndHookEntry(e));
+      if (group.hooks.length !== before) migrated = true;
+    }
+    settings.hooks.Stop = settings.hooks.Stop.filter(
+      (g) => g && Array.isArray(g.hooks) && g.hooks.length > 0
+    );
+    if (settings.hooks.Stop.length === 0) delete settings.hooks.Stop;
+  }
+
+  if (!Array.isArray(settings.hooks.SessionEnd)) settings.hooks.SessionEnd = [];
+
+  for (const group of settings.hooks.SessionEnd) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    if (group.hooks.some(_isSessionEndHookEntry)) {
+      return { settings, status: migrated ? 'migrated-from-stop' : 'already-installed' };
+    }
+  }
+
+  const emptyMatcher = settings.hooks.SessionEnd.find(
+    (g) => g && g.matcher === '' && Array.isArray(g.hooks)
+  );
+  if (emptyMatcher) {
+    emptyMatcher.hooks.push(entry);
+  } else {
+    settings.hooks.SessionEnd.push({ matcher: '', hooks: [entry] });
+  }
+  return { settings, status: migrated ? 'migrated-from-stop' : 'installed' };
+}
+
+function _readSettingsJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { settings: {}, status: 'no-file' };
+  }
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    if (raw.trim() === '') return { settings: {}, status: 'empty' };
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { settings: {}, status: 'malformed', error: 'top-level must be an object' };
+    }
+    return { settings: parsed, status: 'ok' };
+  } catch (e) {
+    return { settings: {}, status: 'malformed', error: e.message };
+  }
+}
+
+function _writeSettingsJson(filePath, settings) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}
+
+// Apply the Stop→SessionEnd migration to ~/.claude/settings.json (or the
+// path passed via opts.settingsPath, used by tests). Idempotent on
+// already-migrated installs. Best-effort backup before write —
+// timestamped `.bak.<YYYYMMDDhhmmss>` matching the convention used by
+// `refreshBundledHookIfNewer`. Returns a structured status the caller
+// can pretty-print.
+function migrateSettingsJsonHookEntry(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const settingsPath = opts.settingsPath || SETTINGS_JSON_PATH;
+
+  const read = _readSettingsJson(settingsPath);
+  if (read.status === 'malformed') {
+    return { status: 'malformed', error: read.error, settingsPath };
+  }
+
+  // Snapshot pre-merge JSON so we can detect "no actual change" even
+  // when status == 'installed' (e.g. a fresh user with no hook keys at
+  // all — we'd add one, which IS a change).
+  const before = JSON.stringify(read.settings);
+  const merge = _mergeSessionEndHookEntry(read.settings);
+  const after = JSON.stringify(merge.settings);
+  const noChange = before === after;
+
+  if (merge.status === 'already-installed' || noChange) {
+    return { status: 'already-installed', settingsPath };
+  }
+
+  if (dryRun) {
+    return { status: 'would-' + merge.status, settingsPath };
+  }
+
+  // Best-effort backup before write — only when a settings.json
+  // existed; brand-new install (no-file → write) doesn't need a backup.
+  let backup = null;
+  if (read.status === 'ok' || read.status === 'empty') {
+    const stamp = new Date().toISOString().replace(/[-:T.Z]/g, '').slice(0, 14);
+    backup = `${settingsPath}.bak.${stamp}`;
+    try { fs.copyFileSync(settingsPath, backup); }
+    catch (_) { backup = null; /* best-effort */ }
+  }
+
+  _writeSettingsJson(settingsPath, merge.settings);
+  return { status: merge.status, settingsPath, backup };
+}
+
+function runSettingsJsonMigration({ dryRun = false } = {}) {
+  const debug = !!process.env.TERMDECK_DEBUG_WIREUP;
+  step('Reconciling ~/.claude/settings.json hook event mapping (Stop → SessionEnd)...');
+  if (debug) {
+    process.stderr.write(`[wire-up-debug] runSettingsJsonMigration entry: dryRun=${dryRun} SETTINGS_JSON_PATH=${SETTINGS_JSON_PATH} exists=${fs.existsSync(SETTINGS_JSON_PATH)}\n`);
+  }
+  try {
+    const r = migrateSettingsJsonHookEntry({ dryRun });
+    if (debug) process.stderr.write(`[wire-up-debug] runSettingsJsonMigration return: ${JSON.stringify(r)}\n`);
+    if (r.status === 'already-installed') {
+      ok('already wired (SessionEnd)');
+    } else if (r.status === 'installed') {
+      ok(r.backup ? `installed (SessionEnd; backup: ${path.basename(r.backup)})` : 'installed (SessionEnd)');
+    } else if (r.status === 'migrated-from-stop') {
+      ok(r.backup ? `migrated Stop → SessionEnd (was firing on every turn; backup: ${path.basename(r.backup)})` : 'migrated Stop → SessionEnd (was firing on every turn)');
+    } else if (r.status === 'would-installed') {
+      ok('would install (SessionEnd) (dry-run)');
+    } else if (r.status === 'would-migrated-from-stop') {
+      ok('would migrate Stop → SessionEnd (dry-run)');
+    } else if (r.status === 'malformed') {
+      ok(`(skipped: settings.json malformed: ${r.error})`);
+    } else {
+      ok(`(${r.status})`);
+    }
+  } catch (err) {
+    // Don't abort init for a settings-migration failure — log + continue.
+    // Same fail-soft posture as runHookRefresh: the user's wizard goal
+    // (DB setup) is independent of settings.json wiring; if we can't
+    // write to settings.json (e.g. permission denied), the wizard
+    // should still finish the DB work.
+    process.stdout.write(`    ! settings.json migration failed: ${err.message} (continuing)\n`);
+    if (debug) process.stderr.write(`[wire-up-debug] runSettingsJsonMigration threw: ${err && err.stack || err}\n`);
+  }
+}
+
+function runHookRefresh({ dryRun = false } = {}) {
+  const debug = !!process.env.TERMDECK_DEBUG_WIREUP;
+  step('Refreshing ~/.claude/hooks/memory-session-end.js (if bundled is newer)...');
+  if (debug) {
+    const HOME = require('os').homedir();
+    const HOOK_DEST = path.join(HOME, '.claude', 'hooks', 'memory-session-end.js');
+    const HOOK_SOURCE = path.join(__dirname, '..', '..', 'stack-installer', 'assets', 'hooks', 'memory-session-end.js');
+    process.stderr.write(`[wire-up-debug] runHookRefresh entry: dryRun=${dryRun} HOOK_DEST=${HOOK_DEST} HOOK_SOURCE=${HOOK_SOURCE} HOOK_SOURCE_exists=${fs.existsSync(HOOK_SOURCE)} HOOK_DEST_exists=${fs.existsSync(HOOK_DEST)}\n`);
+  }
+  try {
+    const r = refreshBundledHookIfNewer({ dryRun });
+    if (debug) process.stderr.write(`[wire-up-debug] runHookRefresh return: ${JSON.stringify(r)}\n`);
+    if (r.status === 'refreshed') {
+      ok(`refreshed v${r.from ?? 0} → v${r.to} (backup: ${path.basename(r.backup)})`);
+    } else if (r.status === 'would-refresh') {
+      ok(`would-refresh v${r.from ?? 0} → v${r.to} (dry-run)`);
+    } else if (r.status === 'installed') {
+      ok(`installed v${r.bundled} (no prior copy)`);
+    } else if (r.status === 'would-install') {
+      ok(`would-install v${r.bundled} (dry-run, no prior copy)`);
+    } else if (r.status === 'up-to-date') {
+      ok(`up-to-date (v${r.installed})`);
+    } else {
+      ok(`(${r.status}${r.message ? ': ' + r.message : ''})`);
+    }
+  } catch (err) {
+    // Don't abort init for a hook-refresh failure — log + continue. The
+    // user's wizard goal (DB setup) is independent of hook refresh; even
+    // if refresh fails (e.g. permission denied, FS error), the wizard
+    // should continue to do the DB work.
+    process.stdout.write(`    ! hook refresh failed: ${err.message} (continuing)\n`);
+    if (debug) process.stderr.write(`[wire-up-debug] runHookRefresh threw: ${err && err.stack || err}\n`);
+  }
+}
+
 function printNextSteps() {
   process.stdout.write(`
 Mnestra is configured.
@@ -637,6 +899,29 @@ async function main(argv) {
     return 6;
   }
 
+  // Sprint 51.7 T1 — refresh ~/.claude/hooks/memory-session-end.js BEFORE the
+  // DB phase. Hook refresh is local FS work; coupling it downstream of pg
+  // connect + 17-migration replay (the old wire-up at line 677 in v1.0.2)
+  // meant ANY DB-side error (Joshua's mig-001 `match_memories` return-type
+  // drift, Brad's same on jizzard-brain) silently skipped the upgrade. With
+  // refresh here, the user always lands the bundled hook even when the DB
+  // phase later fails — decoupled concerns, idempotent re-runs, and the
+  // helper handles its own try/catch internally so a refresh failure never
+  // strands the wizard.
+  runHookRefresh({ dryRun: flags.dryRun });
+
+  // Sprint 51.8 — reconcile ~/.claude/settings.json wiring. Sprint 51.7
+  // landed the v2 hook FILE on disk but never moved the event mapping
+  // from `Stop` to `SessionEnd` for users whose settings.json was
+  // written by `@jhizzard/termdeck-stack@<=0.5.0`. The v2 hook does not
+  // gate on event type, so a Stop wiring fires on every assistant turn
+  // and writes N session_summary rows in memory_items per session. This
+  // migration is idempotent and runs alongside the file refresh so the
+  // wire-up + wiring stay in lockstep on every wizard pass. Brad's
+  // 2026-05-04 jizzard-brain repro is the canonical fixture for this
+  // class of bug (INSTALLER-PITFALLS.md ledger #16).
+  runSettingsJsonMigration({ dryRun: flags.dryRun });
+
   step('Connecting to Supabase...');
   if (flags.dryRun) {
     ok('(dry-run, skipped)');
@@ -664,27 +949,12 @@ async function main(argv) {
     await applyMigrations(client, false);
     await runMnestraAudit(client, inputs.projectUrl.projectRef, false);
     writeYamlConfig(false);
-    // Sprint 51.6 T3: refresh ~/.claude/hooks/memory-session-end.js when the
-    // bundled hook's version stamp is newer than the installed copy. Closes
-    // the upgrade gap where bundled fixes never reached users' machines via
-    // the standard `npm install -g @jhizzard/termdeck@latest && termdeck
-    // init --mnestra` path. Best-effort, timestamped backup, fail-soft.
-    step('Refreshing ~/.claude/hooks/memory-session-end.js (if bundled is newer)...');
-    try {
-      const r = refreshBundledHookIfNewer({ dryRun: false });
-      if (r.status === 'refreshed') {
-        ok(`refreshed v${r.from ?? 0} → v${r.to} (backup: ${path.basename(r.backup)})`);
-      } else if (r.status === 'installed') {
-        ok(`installed v${r.bundled} (no prior copy)`);
-      } else if (r.status === 'up-to-date') {
-        ok(`up-to-date (v${r.installed})`);
-      } else {
-        ok(`(${r.status}${r.message ? ': ' + r.message : ''})`);
-      }
-    } catch (err) {
-      // Don't abort init for a hook-refresh failure — log + continue.
-      process.stdout.write(`    ! hook refresh failed: ${err.message} (continuing)\n`);
-    }
+    // Sprint 51.7 T1: hook refresh moved upstream — see runHookRefresh()
+    // call site near writeSecretsFile. The old wire-up here was reachable
+    // only when every DB step succeeded, which Sprint 51.6 Phase B proved
+    // was the bug (mig-001 `match_memories` return-type drift threw and
+    // stranded the upgrade for both Joshua and Brad).
+
     // v0.6.9: post-write outcome verification. Confirms each migration's
     // expected schema bits actually landed — including memory_items.
     // source_session_id (the v0.6.5 column whose absence cascaded into
@@ -732,3 +1002,10 @@ if (require.main === module) {
 module.exports = main;
 // Sprint 51.6 T3 — exported for tests/init-mnestra-hook-refresh.test.js.
 module.exports.refreshBundledHookIfNewer = refreshBundledHookIfNewer;
+// Sprint 51.8 — exported for tests/init-mnestra-settings-migration.test.js.
+module.exports.migrateSettingsJsonHookEntry = migrateSettingsJsonHookEntry;
+module.exports._mergeSessionEndHookEntry = _mergeSessionEndHookEntry;
+module.exports._isSessionEndHookEntry = _isSessionEndHookEntry;
+module.exports.SETTINGS_JSON_PATH = SETTINGS_JSON_PATH;
+module.exports.HOOK_COMMAND = HOOK_COMMAND;
+module.exports.HOOK_TIMEOUT_SECONDS = HOOK_TIMEOUT_SECONDS;

package/packages/stack-installer/assets/hooks/memory-session-end.js

@@ -51,7 +51,17 @@
  *   a new transcript parser, a default PROJECT_MAP change. Comment-only
  *   tweaks do not need a bump.
  *
- * @termdeck/stack-installer-hook v1
+ *   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
@@ -440,11 +450,117 @@ function selectTranscriptParser(sessionType) {
   return { parser: parseAutoDetect, sessionType: 'auto' };
 }
 
-// Sprint 51.6 T3: returns `{ summary, messagesCount }` instead of just the
-// summary string. messagesCount feeds the new memory_sessions write path
-// (postMemorySession), which needs the parser-derived count without
-// reparsing the transcript. Returns null when the transcript is unreadable
-// or has fewer than 5 messages — same skip semantics as before.
+// ──────────────────────────────────────────────────────────────────────────
+// 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'); }
@@ -468,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: summary.slice(0, 7000), messagesCount: messages.length };
+
+  // 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) {
@@ -569,7 +696,15 @@ async function postMemorySession({
   summary, summaryEmbedding,
   project, sessionId,
   transcriptPath, messagesCount,
-  endedAt
+  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.');
@@ -595,14 +730,16 @@ async function postMemorySession({
           ? `[${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,
-        // started_at, duration_minutes, facts_extracted, files_changed, topics
-        // intentionally omitted — column defaults apply on petvetbid; nullable
-        // on canonical (post-mig-017). Future sprint may parse per-message
-        // timestamps to derive started_at + duration; v1.0.2 ships the
-        // minimum viable row.
       }),
     });
     if (!res.ok) {
@@ -668,7 +805,14 @@ async function processStdinPayload(input) {
 
   const built = buildSummary(transcriptPath, sessionType);
   if (!built) return;
-  const { summary, messagesCount } = built;
+  const {
+    summary,
+    messagesCount,
+    startedAt: parsedStartedAt,
+    endedAt: parsedEndedAt,
+    durationMinutes,
+    factsExtracted,
+  } = built;
 
   const embedding = await embedText(summary, env.openaiKey);
   if (!embedding) return;
@@ -686,6 +830,13 @@ async function processStdinPayload(input) {
   // 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,
@@ -695,11 +846,14 @@ async function processStdinPayload(input) {
     sessionId,
     transcriptPath,
     messagesCount,
-    endedAt: new Date(),
+    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)} memory_items=${itemOk ? 'ok' : 'fail'} memory_sessions=${sessionOk ? 'ok' : 'fail'}`);
+    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'}`);
   }
 }
 
@@ -736,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,
   };
 }