@jhizzard/termdeck 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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,70 @@ 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).
+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 +704,17 @@ 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 });
+
   step('Connecting to Supabase...');
   if (flags.dryRun) {
     ok('(dry-run, skipped)');
@@ -664,27 +742,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

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,
   };
 }