@jhizzard/termdeck-stack 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ underlying packages (`@jhizzard/termdeck`, `@jhizzard/mnestra`,
 `@jhizzard/rumen`) ship on their own cadences and have their own
 changelogs — see the root `CHANGELOG.md` for `@jhizzard/termdeck`.
 
+## [1.3.0] — 2026-05-14
+
+### Added
+
+- **`installPreCompactHook`** at `src/index.js` — bundles `assets/hooks/memory-pre-compact.js` (235 LOC, NEW) and wires it into `~/.claude/settings.json` under `hooks.PreCompact` with `matcher: "*"`. Closes Investigation 2 of `docs/CRITICAL-READ-FIRST-2026-05-07.md` (auto-commit on context-compaction-near). Hook is fail-soft (exit 0 on error; never blocks compaction); writes `source_type='pre_compact_snapshot'` rows to Mnestra. Two firing modes: Claude Code `PreCompact` lifecycle event AND TermDeck server-side periodic-capture timer (for Codex/Gemini/Grok panels). Discriminated via `resolveFiringContext`. Refresh path at `packages/cli/src/init-mnestra.js::runHookRefresh` extended with the same version-stamp regex.
+- **Uninstall path** at `src/uninstall.js` — `_isPreCompactHookEntry` + `'PreCompact'` added to the settings.json event-name loop in `_stepSpliceSettingsJson`; new `_stepBackupPreCompactHookFile` step in the orchestrator chain. Round-trips cleanly with install.
+
+### Documentation
+
+- Audit-trail update: validated against `@jhizzard/termdeck@1.3.0`, the Sprint 64 close-out ship. Wave bundles (a) install-polish wizard with `--auto` MCP-mediated Supabase provisioning + 10-phase pipeline + OS-detection (macOS / Ubuntu / Docker fedora / Docker debian / Alpine / Arch / SUSE) + unified `init` orchestrator collapsing the new-user path from 15+ manual steps to "paste 2 credentials, click 3 buttons"; (b) Sprint 63 four carve-outs — codex `resolveTranscriptPath` strict birthtime epsilon + `adapter.spawn` honored by `spawnTerminalSession` + codex auto-update persisted-last-seen-version probe + `MIN_TRANSCRIPT_MESSAGES` env-configurable threshold; (c) Investigation 2 closure — `PreCompact` harness hook for Claude Code panels + server-side `onPanelPeriodicCapture` timer (10 min default, 1 KB throttle) for non-Claude panels; (d) security regression caught pre-merge by T4-CODEX adversarial audit — Supabase PAT was about to broadcast to every spawned PTY env via `secrets.env` merge; fixed with PAT non-persistence + PTY env exclusion list + dual-layer credential redaction (source-side regex + caller-side explicit). 295/295 root `npm test` green; T4-CODEX FINAL-VERDICT GREEN with file:line evidence; ~42 min wall-clock from inject to verdict (fastest 3+1+1 close to date).
+
 ## [1.2.0] — 2026-05-11
 
 ### Documentation

package/assets/hooks/memory-pre-compact.js

@@ -0,0 +1,277 @@
+/**
+ * TermDeck pre-compact memory hook (Mnestra-direct, no rag-system dependency).
+ *
+ * Vendored into ~/.claude/hooks/memory-pre-compact.js by @jhizzard/termdeck-stack.
+ * Wired into ~/.claude/settings.json under hooks.PreCompact — fires BEFORE
+ * Claude Code compacts conversation context, capturing the in-flight session
+ * state into Mnestra before the harness vaporizes it.
+ *
+ * Why this hook exists (Sprint 64 Investigation 2 of
+ * docs/CRITICAL-READ-FIRST-2026-05-07.md): every long Claude Code session that
+ * crosses the auto-compaction boundary loses in-context state. The global
+ * CLAUDE.md "Before Context Gets Long" rule was advisory and unreliably
+ * followed under sprint pressure. PreCompact is the deterministic signal —
+ * see the canonical hooks docs at https://code.claude.com/docs/en/hooks for
+ * the event contract — and this hook captures a session_summary-shaped row
+ * with `source_type='pre_compact_snapshot'` so post-compaction `memory_recall`
+ * can resurface what was about to be lost.
+ *
+ * Two firing modes:
+ *
+ *   1. Claude Code PreCompact (primary). STDIN shape per the docs:
+ *      { session_id, transcript_path, cwd, hook_event_name: "PreCompact",
+ *        trigger: "auto"|"manual" }.
+ *
+ *   2. TermDeck server periodic-capture timer (Sprint 64 T3.4). Non-Claude
+ *      panels (Codex/Gemini/Grok) have no PreCompact-equivalent. The TermDeck
+ *      server spawns this hook every N minutes for each active non-Claude
+ *      panel, draining the rolling transcript to Mnestra. STDIN shape adds:
+ *      { sessionType, source_agent, mode: "periodic_checkpoint" }.
+ *
+ * Both modes share the rest of the pipeline:
+ *   - Load ~/.termdeck/secrets.env on env-var gaps (Sprint 47.5 discipline).
+ *   - Parse transcript via the adapter parser exported by
+ *     memory-session-end.js (Sprint 38 module-export contract; no duplication).
+ *   - Embed via OpenAI text-embedding-3-small.
+ *   - POST ONE row to /rest/v1/memory_items with
+ *     source_type='pre_compact_snapshot', category='workflow'.
+ *
+ * Fail-soft contract: any error (network, parse, env-var-missing, malformed
+ * transcript) logs and exits 0. NEVER blocks compaction — PreCompact CAN block
+ * via exit-2/decision:block, but losing the checkpoint is bad while blocking
+ * compaction would be worse (the user gets stuck). Match memory-session-end.js
+ * fail-soft.
+ *
+ * Version stamp (Sprint 64 T3.2 — initial cut):
+ *   The marker `@termdeck/stack-installer-hook v<N>` below is read by both
+ *   stack-installer's installPreCompactHook (version-aware overwrite under
+ *   --yes) and `termdeck init --mnestra` (refreshBundledPreCompactHookIfNewer
+ *   step). Bump the integer whenever a change here should overwrite an
+ *   already-installed copy. Comment-only tweaks do not need a bump.
+ *
+ * @termdeck/stack-installer-hook v1
+ *
+ * Required env vars (validated at entry, after the secrets.env fallback):
+ *   - SUPABASE_URL              e.g. https://<project-ref>.supabase.co
+ *   - SUPABASE_SERVICE_ROLE_KEY      service-role key (needs INSERT on memory_items)
+ *   - OPENAI_API_KEY            sk-... for text-embedding-3-small
+ *
+ * Optional:
+ *   - TERMDECK_HOOK_DEBUG=1               verbose logging
+ *   - TERMDECK_PRECOMPACT_MIN_BYTES=5000  transcript size threshold (same default as
+ *                                         memory-session-end.js — sub-5KB transcripts
+ *                                         don't compact anyway, but the guard keeps
+ *                                         synthetic test fixtures honest)
+ *   - TERMDECK_HOOK_HELPERS_PATH=...      override the memory-session-end.js path the
+ *                                         hook require()s helpers from (tests use this)
+ *
+ * Co-existence with memory-session-end.js:
+ *   - memory-session-end.js writes source_type='session_summary' (one per SessionEnd).
+ *   - this hook writes source_type='pre_compact_snapshot' (one per PreCompact OR
+ *     per periodic-capture tick).
+ *   - Same source_session_id ties them together; future `memory_recall` filters
+ *     can include or exclude pre-compact rows independently.
+ */
+
+'use strict';
+
+const { existsSync, readFileSync, appendFileSync, statSync } = require('fs');
+const path = require('path');
+const os = require('os');
+
+const LOG_FILE = path.join(os.homedir(), '.claude', 'hooks', 'memory-hook.log');
+
+function log(msg) {
+  try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [pre-compact] ${msg}\n`); }
+  catch (_) { /* fail-soft */ }
+}
+const DEBUG = process.env.TERMDECK_HOOK_DEBUG === '1';
+function debug(msg) { if (DEBUG) log(`[debug] ${msg}`); }
+
+// Load the SessionEnd hook's helpers via the Sprint 38 module-export contract
+// (`require.main === module` ⇒ CLI; else exports object). Resolved in priority:
+//   1. TERMDECK_HOOK_HELPERS_PATH env var (tests).
+//   2. The installed SessionEnd hook at ~/.claude/hooks/memory-session-end.js —
+//      production path; vendored by installSessionEndHook from the same
+//      stack-installer assets dir this file lives in.
+//   3. The bundled SessionEnd source sibling — used when this hook is exercised
+//      directly from the source tree (fence tests, dev repro).
+function loadHelpers() {
+  const override = process.env.TERMDECK_HOOK_HELPERS_PATH;
+  const candidates = [
+    override,
+    path.join(os.homedir(), '.claude', 'hooks', 'memory-session-end.js'),
+    path.join(__dirname, 'memory-session-end.js'),
+  ].filter(Boolean);
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try { return require(p); }
+    catch (err) {
+      log(`helper-load-failed: ${p} — ${err && err.message ? err.message : String(err)}`);
+    }
+  }
+  log('helpers-not-found: pre-compact hook needs memory-session-end.js bundled at ~/.claude/hooks/. Install via `npx @jhizzard/termdeck-stack`.');
+  return null;
+}
+
+const MIN_TRANSCRIPT_BYTES_PRE_COMPACT =
+  parseInt(process.env.TERMDECK_PRECOMPACT_MIN_BYTES || '5000', 10);
+
+// Inline POST to /rest/v1/memory_items so we can set source_type='pre_compact_snapshot'
+// without touching memory-session-end.js's postMemoryItem (which hardcodes
+// source_type='session_summary'). Inlining keeps the Sprint 62 close-out path
+// untouched — zero regression risk for SessionEnd flow.
+async function postPreCompactSnapshot({
+  supabaseUrl, supabaseKey,
+  content, embedding,
+  project, sessionId,
+  sourceAgent,
+}) {
+  try {
+    const res = await fetch(`${supabaseUrl}/rest/v1/memory_items`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'apikey': supabaseKey,
+        'Authorization': `Bearer ${supabaseKey}`,
+        'Prefer': 'return=minimal',
+      },
+      body: JSON.stringify({
+        content,
+        embedding: `[${embedding.join(',')}]`,
+        source_type: 'pre_compact_snapshot',
+        category: 'workflow',
+        project,
+        source_session_id: sessionId || null,
+        source_agent: sourceAgent,
+      }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      log(`supabase-insert-failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+      return false;
+    }
+    return true;
+  } catch (e) {
+    log(`supabase-insert-exception: ${e.message}`);
+    return false;
+  }
+}
+
+// Distinguishes the two firing modes from the STDIN payload shape:
+//   - { hook_event_name: "PreCompact", trigger }      → Claude Code harness
+//   - { mode: "periodic_checkpoint", sessionType }    → TermDeck server timer
+// Returns { mode, trigger, sessionType, sourceAgent } resolved per mode.
+function resolveFiringContext(data, helpers) {
+  const isClaudePreCompact = data && data.hook_event_name === 'PreCompact';
+  if (isClaudePreCompact) {
+    return {
+      mode: 'pre_compact',
+      trigger: data.trigger === 'manual' ? 'manual' : 'auto',
+      // Claude Code's PreCompact payload doesn't carry sessionType; default
+      // to the canonical adapter name so buildSummary's parser dispatch picks
+      // parseClaudeJsonl. Codex/Gemini/Grok never reach this branch — they
+      // route through the server-side periodic-capture branch below.
+      sessionType: 'claude-code',
+      sourceAgent: helpers.normalizeSourceAgent(data.source_agent || 'claude'),
+    };
+  }
+  return {
+    mode: 'periodic_checkpoint',
+    trigger: 'periodic',
+    sessionType: data.sessionType || data.session_type || 'claude-code',
+    sourceAgent: helpers.normalizeSourceAgent(data.source_agent || 'claude'),
+  };
+}
+
+async function processPreCompactPayload(input, helpers) {
+  let data;
+  try { data = JSON.parse(input); }
+  catch (e) { log(`parse-stdin-failed: ${e.message}`); return { status: 'parse-failed' }; }
+
+  const transcriptPath = data.transcript_path;
+  const cwd = data.cwd || '';
+  const sessionId = data.session_id || null;
+  if (!transcriptPath) { log('no-transcript-path: skipping'); return { status: 'no-transcript-path' }; }
+  if (!sessionId) { log('no-session-id: skipping'); return { status: 'no-session-id' }; }
+
+  const { mode, trigger, sessionType, sourceAgent } = resolveFiringContext(data, helpers);
+
+  let stat;
+  try { stat = statSync(transcriptPath); }
+  catch (e) {
+    log(`cannot-stat-transcript: ${transcriptPath} — ${e.message}`);
+    return { status: 'cannot-stat-transcript' };
+  }
+
+  if (stat.size < MIN_TRANSCRIPT_BYTES_PRE_COMPACT) {
+    debug(`small-transcript: ${stat.size} bytes — skipping ${mode} checkpoint`);
+    return { status: 'small-transcript' };
+  }
+
+  const env = helpers.readEnv();
+  if (!env) return { status: 'env-missing' };
+
+  const project = helpers.detectProject(cwd);
+  const built = helpers.buildSummary(transcriptPath, sessionType);
+  if (!built) {
+    debug(`buildSummary-skipped: <5 messages (parser=${sessionType}) — ${mode} hook bailing gracefully`);
+    return { status: 'too-few-messages' };
+  }
+  const { summary: baseSummary, messagesCount, durationMinutes, factsExtracted } = built;
+
+  // Prepend a checkpoint header so memory_recall results read clearly. Plain
+  // text (not JSON) so the line survives the embed roundtrip intact and is
+  // operator-readable in recall output. Fields chosen for at-a-glance
+  // recovery semantics: mode tells you what fired, trigger distinguishes
+  // auto-vs-manual-vs-periodic, agent says whose context this slice is from.
+  const header =
+    `[CHECKPOINT mode=${mode} trigger=${trigger} ` +
+    `agent=${sourceAgent} ` +
+    `messages=${messagesCount} ` +
+    `duration=${durationMinutes === null ? 'unknown' : `${durationMinutes}m`} ` +
+    `facts_remembered=${factsExtracted}]`;
+  const content = `${header}\n\n${baseSummary}`.slice(0, 7000);
+
+  const embedding = await helpers.embedText(content, env.openaiKey);
+  if (!embedding) return { status: 'embed-failed' };
+
+  const ok = await postPreCompactSnapshot({
+    supabaseUrl: env.supabaseUrl,
+    supabaseKey: env.supabaseKey,
+    content, embedding, project, sessionId, sourceAgent,
+  });
+
+  if (ok) {
+    log(`ingested-${mode}: project="${project}" session=${sessionId} trigger=${trigger} agent=${sourceAgent} bytes=${content.length} messages=${messagesCount} factsExtracted=${factsExtracted}`);
+    return { status: 'ingested', project, sessionId, sourceAgent, mode, trigger, messagesCount };
+  }
+  return { status: 'insert-failed' };
+}
+
+// Module-export contract — when run as a script, read stdin and process; when
+// require()'d (tests + the TermDeck server's periodic-capture spawn helper),
+// expose the inner functions.
+if (require.main === module) {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    const helpers = loadHelpers();
+    if (!helpers) { process.exit(0); return; }
+    processPreCompactPayload(input, helpers)
+      .catch((e) => log(`hook-error: ${e && e.message ? e.message : String(e)}`))
+      // Fail-soft: ALWAYS exit 0. Blocking compaction (exit 2 per Claude Code's
+      // hook contract) costs more than skipping a checkpoint.
+      .finally(() => process.exit(0));
+  });
+} else {
+  module.exports = {
+    loadHelpers,
+    postPreCompactSnapshot,
+    processPreCompactPayload,
+    resolveFiringContext,
+    LOG_FILE,
+    MIN_TRANSCRIPT_BYTES_PRE_COMPACT,
+  };
+}

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

@@ -138,6 +138,16 @@ const PROJECT_MAP = [
 ];
 
 const MIN_TRANSCRIPT_BYTES = parseInt(process.env.TERMDECK_HOOK_MIN_BYTES || '5000', 10);
+// Sprint 64 T2 (carve-out 2.2) — Sprint 63 EXIT-CAPTURE-VERIFICATION.md
+// Finding #3 documented Brad's grok-canary panel silent-skipped at 4 msgs /
+// 6,713 bytes of canary content because the legacy hard-coded `< 5 messages`
+// gate fired before the MIN_TRANSCRIPT_BYTES floor could even matter. Codex
+// audit posts are similarly content-rich-but-message-count-poor (one canonical
+// turn). Default lowered to 1 — the 5 KB byte gate at `:140 + :795 + the
+// `MIN_TRANSCRIPT_BYTES`-based skip at line 795` is now the sole primary noise
+// filter; sub-5KB drips still get dropped. Env-configurable for operators who
+// want the legacy permissive-to-zero floor or a higher cutoff than 1.
+const MIN_TRANSCRIPT_MESSAGES = parseInt(process.env.TERMDECK_HOOK_MIN_MESSAGES || '1', 10);
 const DEBUG = process.env.TERMDECK_HOOK_DEBUG === '1';
 
 function log(msg) {
@@ -573,8 +583,10 @@ function buildSummary(transcriptPath, sessionType) {
 
   const messages = parser(raw);
 
-  if (messages.length < 5) {
-    debug(`session-too-short: ${messages.length} messages (parser=${resolvedType}), skipping`);
+  // Sprint 64 T2 (carve-out 2.2) — env-configurable floor, default 1. See
+  // `MIN_TRANSCRIPT_MESSAGES` declaration for the Brad grok-canary rationale.
+  if (messages.length < MIN_TRANSCRIPT_MESSAGES) {
+    debug(`session-too-short: ${messages.length} messages (parser=${resolvedType}), skipping (TERMDECK_HOOK_MIN_MESSAGES=${MIN_TRANSCRIPT_MESSAGES})`);
     return null;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck-stack",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "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

@@ -53,6 +53,17 @@ const HOOK_DEST = path.join(HOOK_DEST_DIR, 'memory-session-end.js');
 const HOOK_SOURCE = path.join(__dirname, '..', 'assets', 'hooks', 'memory-session-end.js');
 const HOOK_COMMAND = 'node ~/.claude/hooks/memory-session-end.js';
 const HOOK_TIMEOUT_SECONDS = 30;
+
+// Sprint 64 T3 — PreCompact hook (Investigation 2 of
+// docs/CRITICAL-READ-FIRST-2026-05-07.md). Fires BEFORE Claude Code compacts
+// context, capturing session state into Mnestra under
+// source_type='pre_compact_snapshot'. Lives alongside the SessionEnd hook in
+// ~/.claude/hooks/ and re-uses memory-session-end.js helpers via the Sprint 38
+// module-export contract.
+const PRECOMPACT_HOOK_DEST = path.join(HOOK_DEST_DIR, 'memory-pre-compact.js');
+const PRECOMPACT_HOOK_SOURCE = path.join(__dirname, '..', 'assets', 'hooks', 'memory-pre-compact.js');
+const PRECOMPACT_HOOK_COMMAND = 'node ~/.claude/hooks/memory-pre-compact.js';
+const PRECOMPACT_HOOK_TIMEOUT_SECONDS = 30;
 const SECRETS_PATH = path.join(HOME, '.termdeck', 'secrets.env');
 
 // Read ~/.termdeck/secrets.env into a plain object. Returns {} if the file
@@ -493,6 +504,48 @@ function _mergeSessionEndHookEntry(settings, opts = {}) {
   return { settings, status: migrated ? 'migrated-from-stop' : 'installed' };
 }
 
+// Sprint 64 T3 — PreCompact entry detection + merge. Parallel to the SessionEnd
+// helpers above, with the key difference that PreCompact didn't exist before
+// this sprint so there's no Stop-style migration branch. Idempotent.
+function _isPreCompactHookEntry(entry) {
+  return entry && typeof entry.command === 'string'
+    && entry.command.includes('memory-pre-compact.js');
+}
+
+// Pure: merges our PreCompact entry into the given settings object. Returns
+// { settings, status } where status is 'already-installed' or 'installed'.
+// Mutates the input. matcher='*' is the documented wildcard for PreCompact —
+// fires on both auto-compact (token-limit-driven) AND manual /compact triggers.
+function _mergePreCompactHookEntry(settings, opts = {}) {
+  const command = opts.command || PRECOMPACT_HOOK_COMMAND;
+  const timeout = opts.timeout != null ? opts.timeout : PRECOMPACT_HOOK_TIMEOUT_SECONDS;
+  const entry = { type: 'command', command, timeout };
+
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PreCompact)) settings.hooks.PreCompact = [];
+
+  for (const group of settings.hooks.PreCompact) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    if (group.hooks.some(_isPreCompactHookEntry)) {
+      return { settings, status: 'already-installed' };
+    }
+  }
+
+  // Append to a `*`-matcher group if present (covers both auto + manual); else
+  // create one. Hand-edited groups with specific matchers (e.g. matcher: 'auto')
+  // are left intact — a future user-installed hook gating on a specific trigger
+  // coexists with our wildcard group rather than getting overwritten.
+  const wildcardGroup = settings.hooks.PreCompact.find(
+    (g) => g && g.matcher === '*' && Array.isArray(g.hooks)
+  );
+  if (wildcardGroup) {
+    wildcardGroup.hooks.push(entry);
+  } else {
+    settings.hooks.PreCompact.push({ matcher: '*', hooks: [entry] });
+  }
+  return { settings, status: 'installed' };
+}
+
 function _readSettingsJson(filePath) {
   if (!fs.existsSync(filePath)) {
     return { settings: {}, status: 'no-file' };
@@ -707,6 +760,113 @@ async function installSessionEndHook(opts = {}) {
   return { fileStatus, settingsStatus };
 }
 
+// Sprint 64 T3 — install the PreCompact hook. Closes Investigation 2 of
+// docs/CRITICAL-READ-FIRST-2026-05-07.md ("auto-commit on context compaction-
+// near"). Mirrors installSessionEndHook closely but simpler: PreCompact is
+// new in Sprint 64 so there's no Stop→SessionEnd-style legacy migration.
+//
+// File copy and settings.json merge are independent — a file-copy failure
+// doesn't suppress the settings merge, and vice versa. Both errors fail-soft.
+async function installPreCompactHook(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const sourcePath = opts.sourcePath || PRECOMPACT_HOOK_SOURCE;
+  const destPath = opts.destPath || PRECOMPACT_HOOK_DEST;
+  const settingsPath = opts.settingsPath || SETTINGS_JSON;
+  const promptInstall = opts.promptInstall
+    || (() => promptYesNo({ question: "Install TermDeck's PreCompact memory hook? (captures session state before Claude compacts)", defaultYes: true }));
+  const promptOverwrite = opts.promptOverwrite
+    || (() => promptYesNo({
+      question: `Existing pre-compact hook found at ${destPath}. Overwrite?`,
+      defaultYes: false,
+    }));
+
+  rule();
+  process.stdout.write(`${ANSI.bold}PreCompact memory hook${ANSI.reset}\n`);
+  process.stdout.write(`${ANSI.dim}  Fires before Claude Code compacts conversation context, capturing the in-flight session state into Mnestra so long sessions don't leak findings on auto-compact.${ANSI.reset}\n\n`);
+
+  const userWantsInstall = opts.assumeYes ? true
+    : opts.assumeNo ? false
+    : await promptInstall();
+
+  if (!userWantsInstall) {
+    statusLine(`${ANSI.dim}─${ANSI.reset}`, 'pre-compact hook', 'skipped (user declined)');
+    process.stdout.write('\n');
+    return { fileStatus: 'declined', settingsStatus: 'declined' };
+  }
+
+  // 1. File copy. Reuses the version-stamp gate so future bumps of
+  // `@termdeck/stack-installer-hook v<N>` in the bundled file trigger an
+  // overwrite on `--yes` without prompting. A genuinely custom user file
+  // (unsigned, no TermDeck markers) is preserved — but in practice nobody
+  // has one of these on disk pre-Sprint-64 because PreCompact is new.
+  let fileStatus;
+  const cmp = _compareHookFiles(sourcePath, destPath);
+  if (cmp === 'missing-dest') {
+    if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would copy pre-compact hook to ${destPath}`);
+      fileStatus = 'would-copy';
+    } else {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(sourcePath, destPath);
+      fs.chmodSync(destPath, 0o644);
+      statusLine(`${ANSI.green}+${ANSI.reset}`, 'pre-compact hook file', `copied to ${destPath}`);
+      fileStatus = 'copied';
+    }
+  } else if (cmp === 'identical') {
+    statusLine(`${ANSI.dim}=${ANSI.reset}`, 'pre-compact hook file', 'already present, identical contents');
+    fileStatus = 'already-current';
+  } else {
+    const overwrite = opts.assumeYes
+      ? _hookSignatureUpgradeAvailable(sourcePath, destPath)
+      : opts.forceOverwrite ? true
+      : await promptOverwrite();
+    if (!overwrite) {
+      statusLine(`${ANSI.dim}=${ANSI.reset}`, 'pre-compact hook file', `existing kept (differs from vendored copy)`);
+      fileStatus = 'kept-existing';
+    } else if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would overwrite ${destPath}`);
+      fileStatus = 'would-overwrite';
+    } else {
+      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}`, 'pre-compact hook file', `overwrote ${destPath}`);
+      fileStatus = 'overwritten';
+    }
+  }
+
+  // 2. Settings.json merge.
+  const read = _readSettingsJson(settingsPath);
+  let settingsStatus;
+  if (read.status === 'malformed') {
+    statusLine(`${ANSI.red}✗${ANSI.reset}`, 'settings.json', `malformed (${read.error}); not modified`);
+    settingsStatus = 'malformed';
+  } else {
+    const merged = _mergePreCompactHookEntry(read.settings);
+    if (merged.status === 'already-installed') {
+      statusLine(`${ANSI.dim}=${ANSI.reset}`, 'settings.json PreCompact hook', 'already installed');
+      settingsStatus = 'already-installed';
+    } else if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would merge PreCompact hook into ${settingsPath}`);
+      settingsStatus = 'would-install';
+    } else {
+      _writeSettingsJson(settingsPath, merged.settings);
+      statusLine(`${ANSI.green}+${ANSI.reset}`, 'settings.json PreCompact hook', 'merged');
+      settingsStatus = 'installed';
+    }
+  }
+
+  process.stdout.write('\n');
+  if (!dryRun && (fileStatus === 'copied' || settingsStatus === 'installed')) {
+    process.stdout.write(`  ${ANSI.dim}PreCompact hook installed at ${destPath}.${ANSI.reset}\n`);
+    process.stdout.write(`  ${ANSI.dim}It runs before Claude Code compacts context, writing a pre_compact_snapshot row to Mnestra.${ANSI.reset}\n`);
+    process.stdout.write(`  ${ANSI.dim}Sprint 64 / Investigation 2 / docs/CRITICAL-READ-FIRST-2026-05-07.md.${ANSI.reset}\n\n`);
+  }
+
+  return { fileStatus, settingsStatus };
+}
+
 // ── Next steps ──────────────────────────────────────────────────────
 
 function printNextSteps(plan, opts) {
@@ -838,6 +998,15 @@ async function main(argv) {
     assumeYes: args.yes,
   });
 
+  // Sprint 64 T3 — bundle the PreCompact memory hook (Investigation 2 closure).
+  // Same prompt UX as SessionEnd: default-on, opt-out via prompt; --yes
+  // accepts the install. The two hooks coexist — SessionEnd captures on
+  // /exit, PreCompact captures before context compaction.
+  await installPreCompactHook({
+    dryRun: args.dryRun,
+    assumeYes: args.yes,
+  });
+
   printNextSteps(wantedLayers, { dryRun: args.dryRun });
 
   if (failures > 0) {
@@ -872,6 +1041,14 @@ 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;
+// Sprint 64 T3 — PreCompact hook (Investigation 2 closure) exports.
+module.exports.installPreCompactHook = installPreCompactHook;
+module.exports._isPreCompactHookEntry = _isPreCompactHookEntry;
+module.exports._mergePreCompactHookEntry = _mergePreCompactHookEntry;
+module.exports.PRECOMPACT_HOOK_COMMAND = PRECOMPACT_HOOK_COMMAND;
+module.exports.PRECOMPACT_HOOK_SOURCE = PRECOMPACT_HOOK_SOURCE;
+module.exports.PRECOMPACT_HOOK_DEST = PRECOMPACT_HOOK_DEST;
+module.exports.PRECOMPACT_HOOK_TIMEOUT_SECONDS = PRECOMPACT_HOOK_TIMEOUT_SECONDS;
 module.exports._mcpInternals = _mcpInternals;
 module.exports.MCP_CONFIG_PATH = MCP_CONFIG;
 module.exports.CLAUDE_MCP_PATH_CANONICAL = CLAUDE_MCP_PATH_CANONICAL;

package/src/uninstall.js

@@ -60,6 +60,17 @@ function _isSessionEndHookEntry(entry) {
     && entry.command.includes('memory-session-end.js');
 }
 
+// Sprint 64 T3 — PreCompact entry predicate (Investigation 2 closure). Used
+// alongside _isSessionEndHookEntry to splice both hook kinds during uninstall.
+function _isPreCompactHookEntry(entry) {
+  return entry && typeof entry.command === 'string'
+    && entry.command.includes('memory-pre-compact.js');
+}
+
+function _isAnyTermdeckHookEntry(entry) {
+  return _isSessionEndHookEntry(entry) || _isPreCompactHookEntry(entry);
+}
+
 // ── Args ────────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
@@ -217,6 +228,8 @@ function _resolvePaths(home, platform) {
     claudeJson: path.join(home, '.claude.json'),
     settingsJson: path.join(home, '.claude', 'settings.json'),
     hookFile: path.join(home, '.claude', 'hooks', 'memory-session-end.js'),
+    // Sprint 64 T3 — PreCompact hook destination (Investigation 2 closure).
+    preCompactHookFile: path.join(home, '.claude', 'hooks', 'memory-pre-compact.js'),
     launchAgentsDir: path.join(home, 'Library', 'LaunchAgents'),
     launchAgentGlob: 'com.jhizzard.termdeck.', // prefix match against .plist files
     systemdUnit: path.join(home, '.config', 'systemd', 'user', 'termdeck.service'),
@@ -237,17 +250,18 @@ function _settingsJsonHasOurHook(_fs, settingsJson) {
   try { parsed = JSON.parse(_fs.readFileSync(settingsJson, 'utf8') || '{}'); }
   catch (_) { return false; }
   if (!parsed || !parsed.hooks) return false;
-  for (const event of ['Stop', 'SessionEnd']) {
+  // Sprint 64 T3 — also probe PreCompact wiring (Investigation 2 closure).
+  for (const event of ['Stop', 'SessionEnd', 'PreCompact']) {
     const arr = parsed.hooks[event];
     if (!Array.isArray(arr)) continue;
     for (const elem of arr) {
       if (!elem) continue;
       // Canonical Claude-Code group shape: { matcher, hooks: [{ type, command }] }
-      if (Array.isArray(elem.hooks) && elem.hooks.some(_isSessionEndHookEntry)) return true;
+      if (Array.isArray(elem.hooks) && elem.hooks.some(_isAnyTermdeckHookEntry)) return true;
       // Legacy / hand-edited flat shape: { type, command } directly in array.
       // T3 (Sprint 61 18:50 ET) found that real-world fixtures use this
       // alternative shape, and our uninstall must handle both.
-      if (_isSessionEndHookEntry(elem)) return true;
+      if (_isAnyTermdeckHookEntry(elem)) return true;
     }
   }
   return false;
@@ -288,6 +302,9 @@ function _detectInstallState(_fs, paths) {
     hasOurHookInSettings: _settingsJsonHasOurHook(_fs, paths.settingsJson),
     hasHookFile: _fs.existsSync(paths.hookFile),
     hookBakFiles: _findHookBakFiles(_fs, paths.hookFile),
+    // Sprint 64 T3 — PreCompact hook file detection (Investigation 2 closure).
+    hasPreCompactHookFile: _fs.existsSync(paths.preCompactHookFile),
+    preCompactHookBakFiles: _findHookBakFiles(_fs, paths.preCompactHookFile),
     launchAgents,
     systemdActive,
   };
@@ -336,6 +353,8 @@ function _isFullyClean(state) {
     && !state.hasMnestraMcpEntry
     && !state.hasOurHookInSettings
     && !state.hasHookFile
+    // Sprint 64 T3 — fully-clean predicate now also covers the PreCompact hook.
+    && !state.hasPreCompactHookFile
     && state.launchAgents.length === 0
     && !state.systemdActive;
 }
@@ -468,7 +487,10 @@ function _stepSpliceSettingsJson(_fs, paths, opts) {
     return out;
   }
   let removedCount = 0;
-  for (const event of ['Stop', 'SessionEnd']) {
+  // Sprint 64 T3 — added 'PreCompact' to the event-name list and switched the
+  // predicate to `_isAnyTermdeckHookEntry` so a single splice pass also strips
+  // PreCompact wirings (Investigation 2 closure).
+  for (const event of ['Stop', 'SessionEnd', 'PreCompact']) {
     const arr = parsed.hooks[event];
     if (!Array.isArray(arr)) continue;
     // Two shapes coexist in the wild (T3 finding 2026-05-07 18:50 ET):
@@ -480,7 +502,7 @@ function _stepSpliceSettingsJson(_fs, paths, opts) {
     for (const elem of arr) {
       if (elem && Array.isArray(elem.hooks)) {
         const before = elem.hooks.length;
-        elem.hooks = elem.hooks.filter((e) => !_isSessionEndHookEntry(e));
+        elem.hooks = elem.hooks.filter((e) => !_isAnyTermdeckHookEntry(e));
         removedCount += before - elem.hooks.length;
       }
     }
@@ -488,7 +510,7 @@ function _stepSpliceSettingsJson(_fs, paths, opts) {
     for (const elem of arr) {
       if (!elem) continue;
       // Drop flat entries that match our hook.
-      if (_isSessionEndHookEntry(elem) && !Array.isArray(elem.hooks)) {
+      if (_isAnyTermdeckHookEntry(elem) && !Array.isArray(elem.hooks)) {
         removedCount += 1;
         continue;
       }
@@ -544,6 +566,33 @@ function _stepBackupHookFile(_fs, paths, opts) {
   return out;
 }
 
+// Sprint 64 T3 — same shape as _stepBackupHookFile but targets the PreCompact
+// hook file (Investigation 2 closure). Independent of the SessionEnd backup —
+// either file's absence/presence is OK; both are renamed-not-deleted so user
+// customizations are recoverable.
+function _stepBackupPreCompactHookFile(_fs, paths, opts) {
+  const out = { name: 'pre-compact-hook-file-backup', status: 'pending', detail: '' };
+  if (!_fs.existsSync(paths.preCompactHookFile)) {
+    out.status = 'skipped'; out.detail = 'not present';
+    return out;
+  }
+  const stamp = _isoStamp(opts._now);
+  const bakPath = `${paths.preCompactHookFile}.bak.${stamp}`;
+  if (opts.dryRun) {
+    out.status = 'would-rename';
+    out.detail = `would rename ${paths.preCompactHookFile} → ${bakPath}`;
+    return out;
+  }
+  try {
+    _fs.renameSync(paths.preCompactHookFile, bakPath);
+    out.status = 'renamed';
+    out.detail = `${paths.preCompactHookFile} → ${bakPath}`;
+  } catch (e) {
+    out.status = 'error'; out.detail = `rename failed: ${e.message}`;
+  }
+  return out;
+}
+
 // Step 6 (darwin only): LaunchAgents — `launchctl unload` BEFORE `rm`. The
 // unload call's exit code is non-fatal: the agent may not be loaded in the
 // current session, especially in tests.
@@ -759,6 +808,7 @@ function _printPreflight(out, state, paths, opts) {
   if (state.hasMnestraMcpEntry) lines.push(`  ${ANSI.cyan}•${ANSI.reset} mcpServers.mnestra in ${paths.claudeJson} ${ANSI.dim}(surgical splice — other entries preserved)${ANSI.reset}`);
   if (state.hasOurHookInSettings) lines.push(`  ${ANSI.cyan}•${ANSI.reset} hooks.{Stop,SessionEnd} entries in ${paths.settingsJson} ${ANSI.dim}(surgical splice — other entries preserved)${ANSI.reset}`);
   if (state.hasHookFile) lines.push(`  ${ANSI.cyan}•${ANSI.reset} ${paths.hookFile} ${ANSI.dim}(renamed to .bak.<timestamp>, not deleted)${ANSI.reset}`);
+  if (state.hasPreCompactHookFile) lines.push(`  ${ANSI.cyan}•${ANSI.reset} ${paths.preCompactHookFile} ${ANSI.dim}(renamed to .bak.<timestamp>, not deleted)${ANSI.reset}`);
   for (const p of state.launchAgents) lines.push(`  ${ANSI.cyan}•${ANSI.reset} ${p} ${ANSI.dim}(launchctl unload + rm)${ANSI.reset}`);
   if (state.systemdActive) lines.push(`  ${ANSI.cyan}•${ANSI.reset} ${paths.systemdUnit} ${ANSI.dim}(systemctl --user disable --now + rm)${ANSI.reset}`);
   if (opts.purgeSupabase) lines.push(`  ${ANSI.red}•${ANSI.reset} ${ANSI.bold}--purge-supabase: will DROP Mnestra/Rumen tables in your Supabase project${ANSI.reset}`);
@@ -869,6 +919,10 @@ async function uninstall(opts = {}) {
     (o) => _stepSpliceClaudeJson(_fs, paths, o),
     (o) => _stepSpliceSettingsJson(_fs, paths, o),
     (o) => _stepBackupHookFile(_fs, paths, o),
+    // Sprint 64 T3 — PreCompact hook backup step (Investigation 2 closure).
+    // Runs after the SessionEnd backup so a clean install with both hooks
+    // present produces .bak siblings for both files with a consistent stamp.
+    (o) => _stepBackupPreCompactHookFile(_fs, paths, o),
     (o) => _stepRemoveLaunchAgents(_fs, _spawnSync, paths, o),
     (o) => _stepRemoveSystemdUnit(_fs, _spawnSync, paths, o),
   ]) {
@@ -921,6 +975,10 @@ module.exports = {
   parseArgs,
   // Test hooks — exposed so unit tests can drive primitives without a full run.
   _isSessionEndHookEntry,
+  // Sprint 64 T3 — PreCompact uninstall surface (Investigation 2 closure).
+  _isPreCompactHookEntry,
+  _isAnyTermdeckHookEntry,
+  _stepBackupPreCompactHookFile,
   _resolvePaths,
   _detectInstallState,
   _isFullyClean,