@jhizzard/termdeck 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.0.1",
+  "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"
@@ -11,6 +11,7 @@
     "packages/cli/templates/**",
     "packages/server/src/**",
     "packages/client/public/**",
+    "packages/stack-installer/assets/hooks/**",
     "config/config.example.yaml",
     "config/secrets.env.example",
     "config/transcript-migration.sql",

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)
@@ -481,6 +484,156 @@ function writeYamlConfig(dryRun) {
   else ok();
 }
 
+// Sprint 51.6 T3 — hook upgrade gap fix.
+//
+// Codex's Sprint 51.6 GAP at 20:11 ET surfaced this: the bundled session-end
+// hook ships in `packages/stack-installer/assets/hooks/memory-session-end.js`,
+// and `npm install -g @jhizzard/termdeck@latest` lands the new bundled file
+// in node_modules — but `termdeck init --mnestra` never touched
+// ~/.claude/hooks/memory-session-end.js. The user's daily-driver kept
+// running the OLD installed copy forever. v1.0.2 closes that gap by adding
+// this refresh step to init --mnestra. The version stamp in the bundled
+// hook (// @termdeck/stack-installer-hook v<N>) gates the overwrite — only
+// strictly-newer bundled stamps trigger a refresh, so a hand-edited
+// installed file with v=current stays put.
+//
+// Backup is best-effort timestamped: `<dest>.bak.<YYYYMMDDhhmmss>`. Matches
+// the pattern Joshua already had on disk from earlier stack-installer runs.
+function refreshBundledHookIfNewer(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const HOME = require('os').homedir();
+  const HOOK_DEST = opts.destPath || path.join(HOME, '.claude', 'hooks', 'memory-session-end.js');
+  // Sprint 51.6 T4-CODEX audit 20:28 ET fix: bundled hook source must be on
+  // a path that ships in @jhizzard/termdeck's npm tarball. Root package.json
+  // includes `packages/stack-installer/assets/hooks/**` (added 51.6 T3) so
+  // this path resolves both in the monorepo and in the published tarball.
+  const HOOK_SOURCE = opts.sourcePath
+    || path.join(__dirname, '..', '..', 'stack-installer', 'assets', 'hooks', 'memory-session-end.js');
+  const SIG_RE = /@termdeck\/stack-installer-hook\s+v(\d+)/;
+  const TERMDECK_MARKERS = [
+    /TermDeck session-end memory hook/,
+    /@jhizzard\/termdeck-stack/,
+    /Vendored into ~\/\.claude\/hooks\/memory-session-end\.js by @jhizzard/i,
+  ];
+
+  function readHead(p) {
+    try { return fs.readFileSync(p, 'utf8').slice(0, 4096); }
+    catch (_) { return null; }
+  }
+  function readVersion(p) {
+    const head = readHead(p);
+    if (!head) return null;
+    const m = head.match(SIG_RE);
+    return m ? parseInt(m[1], 10) : null;
+  }
+  function looksTermdeckManaged(p) {
+    const head = readHead(p);
+    if (!head) return false;
+    return TERMDECK_MARKERS.some((m) => m.test(head));
+  }
+
+  if (!fs.existsSync(HOOK_SOURCE)) {
+    return { status: 'no-bundled', message: 'bundled hook source not found' };
+  }
+  const bundled = readVersion(HOOK_SOURCE);
+  if (bundled === null) {
+    return { status: 'bundled-unsigned', message: 'bundled hook missing version stamp; skipping refresh' };
+  }
+  if (!fs.existsSync(HOOK_DEST)) {
+    if (dryRun) return { status: 'would-install', bundled };
+    fs.mkdirSync(path.dirname(HOOK_DEST), { recursive: true });
+    fs.copyFileSync(HOOK_SOURCE, HOOK_DEST);
+    fs.chmodSync(HOOK_DEST, 0o644);
+    return { status: 'installed', bundled };
+  }
+  const installed = readVersion(HOOK_DEST);
+  if (installed !== null && installed >= bundled) {
+    return { status: 'up-to-date', installed, bundled };
+  }
+  // Sprint 51.6 T4-CODEX audit 20:23 ET safety gate: an unsigned installed
+  // hook gets refreshed ONLY if it looks TermDeck-managed (carries one of
+  // the docstring markers from a prior bundled cut). A genuinely custom
+  // user hook with no TermDeck fingerprint stays put.
+  if (installed === null && !looksTermdeckManaged(HOOK_DEST)) {
+    return {
+      status: 'custom-hook-preserved',
+      message: 'installed hook lacks TermDeck-managed markers; keeping as-is. Re-run with --force-overwrite to bypass.',
+      bundled,
+    };
+  }
+  if (dryRun) return { status: 'would-refresh', from: installed, to: bundled };
+  const stamp = new Date().toISOString().replace(/[-:T.Z]/g, '').slice(0, 14);
+  const backup = `${HOOK_DEST}.bak.${stamp}`;
+  try { fs.copyFileSync(HOOK_DEST, backup); } catch (_) { /* best-effort */ }
+  fs.copyFileSync(HOOK_SOURCE, HOOK_DEST);
+  fs.chmodSync(HOOK_DEST, 0o644);
+  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.
@@ -551,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)');
@@ -578,6 +742,12 @@ async function main(argv) {
     await applyMigrations(client, false);
     await runMnestraAudit(client, inputs.projectUrl.projectRef, false);
     writeYamlConfig(false);
+    // 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
@@ -623,3 +793,5 @@ if (require.main === module) {
 }
 
 module.exports = main;
+// Sprint 51.6 T3 — exported for tests/init-mnestra-hook-refresh.test.js.
+module.exports.refreshBundledHookIfNewer = refreshBundledHookIfNewer;

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

@@ -337,14 +337,21 @@ async function runRumenAudit(projectRef, secrets, dryRun) {
       pgClient: client,
       projectRef
     });
-    if (result.applied.length === 0 && result.errors.length === 0) {
+    if (result.applied.length === 0 && result.errors.length === 0 && result.skipped.length === 0) {
       ok(`(install up to date — ${result.probed.length} probes all present)`);
       return true;
     }
-    ok(`(probed ${result.probed.length}, applied ${result.applied.length})`);
+    ok(`(probed ${result.probed.length}, applied ${result.applied.length}, skipped ${result.skipped.length})`);
     for (const name of result.applied) {
       process.stdout.write(`    ✓ applied ${name}\n`);
     }
+    // Sprint 51.6 T3 — Bug D: surface skipped[] entries (functionSource
+    // probes that detected drift but can't auto-redeploy from audit). The
+    // wizard will redeploy below in the deployFunctions step, which fixes
+    // the drift; this print just makes the diagnosis visible.
+    for (const s of result.skipped) {
+      process.stdout.write(`    ⊘ skipped ${s.name}: ${s.reason}\n`);
+    }
     for (const e of result.errors) {
       process.stdout.write(`    ! ${e.name}: ${e.error}\n`);
     }
@@ -363,7 +370,20 @@ async function runRumenAudit(projectRef, secrets, dryRun) {
 // copied verbatim. If a future function adds a placeholder, list it here.
 const FUNCTIONS_WITH_VERSION_PLACEHOLDER = new Set(['rumen-tick']);
 
-function deployFunctions(rumenVersion, dryRun) {
+// Sprint 51.6 T3 — `projectRef` is required and passed explicitly to every
+// `supabase functions deploy` invocation as `--project-ref <ref>`. Brad's
+// 2026-05-03 jizzard-brain install hit Bug C: `supabase link --project-ref`
+// runs successfully (audit-upgrade probes confirm the link is live), but a
+// few subprocess calls later `supabase functions deploy` errors with
+// `Cannot find project ref. Have you run supabase link?` because the link
+// state persists per-cwd in supabase/config.toml and the staged-functions
+// directory has none. Threading --project-ref through dodges link-state
+// coupling entirely. The flag is supported by supabase CLI v1.x and v2.x.
+function deployFunctions(rumenVersion, projectRef, dryRun) {
+  if (!projectRef || typeof projectRef !== 'string') {
+    fail('deployFunctions: projectRef is required (Sprint 51.6 T3 — explicit --project-ref to dodge subprocess link-state isolation)');
+    return false;
+  }
   const fnNames = migrations.listRumenFunctions();
   if (fnNames.length === 0) {
     fail('no Rumen Edge Function source found in bundled setup or @jhizzard/rumen package');
@@ -390,10 +410,14 @@ function deployFunctions(rumenVersion, dryRun) {
   ok();
 
   for (const name of fnNames) {
-    step(`Running: supabase functions deploy ${name} --no-verify-jwt...`);
-    const r = runShell('supabase', ['functions', 'deploy', name, '--no-verify-jwt'], {
-      cwd: stage
-    });
+    // Sprint 51.6 T3 — `--project-ref <ref>` explicit, dodging supabase
+    // link-state subprocess isolation (Bug C, Brad's 2026-05-03 install).
+    step(`Running: supabase functions deploy ${name} --project-ref ${projectRef} --no-verify-jwt...`);
+    const r = runShell('supabase', [
+      'functions', 'deploy', name,
+      '--project-ref', projectRef,
+      '--no-verify-jwt',
+    ], { cwd: stage });
     if (!r.ok) {
       fail(`deploy of ${name} failed (exit ${r.code})`);
       return false;
@@ -997,7 +1021,7 @@ async function main(argv) {
     process.stderr.write(`  ! falling back to pinned FALLBACK_RUMEN_VERSION=${FALLBACK_RUMEN_VERSION}\n`);
   }
 
-  if (!deployFunctions(resolved.version, flags.dryRun)) return 6;
+  if (!deployFunctions(resolved.version, projectRef, flags.dryRun)) return 6;
 
   // Sprint 51.5 T3: install-time prompt for AI edge classification. Sets
   // secrets.GRAPH_LLM_CLASSIFY in-memory; the per-secret loop below picks
@@ -1042,6 +1066,9 @@ module.exports._wireAccessTokenInMcpJson = wireAccessTokenInMcpJson;
 // Sprint 43 T3: stage helper exposed so init-rumen-deploy.test.js can pin
 // the multi-function staging contract without shelling out to `supabase`.
 module.exports._stageRumenFunctions = stageRumenFunctions;
+// Sprint 51.6 T3 — exported for tests/init-rumen-project-ref.test.js so the
+// --project-ref invariant can be asserted without spawning a real shell.
+module.exports._deployFunctions = deployFunctions;
 // Sprint 51.5 T3: per-secret CLI loop, Vault SQL-Editor URL builder, and
 // Vault-secret ensure helper exposed for tests/init-rumen-secrets-per-call,
 // init-rumen-graph-llm, and init-rumen-vault-deeplinks.

package/packages/server/src/setup/audit-upgrade.js

@@ -117,6 +117,23 @@ const PROBES = Object.freeze([
       "  and column_name = 'source_agent' limit 1",
     presentWhen: 'rowReturned'
   },
+  {
+    // Sprint 51.6 T3 — bundled session-end hook (TermDeck v1.0.2+) writes
+    // the rich rag-system column set to memory_sessions; canonical engram
+    // mig 001 only ships (id, project, summary, metadata, created_at).
+    // Probe for memory_sessions.session_id (the most distinctive of the
+    // mig-017 columns) and apply mig 017 if absent. Idempotent on petvetbid
+    // where the columns are already present from hand-applied DDL.
+    name: 'memory_sessions.session_id',
+    kind: 'mnestra',
+    migrationFile: '017_memory_sessions_session_metadata.sql',
+    probeSql:
+      "select 1 as present from information_schema.columns " +
+      "where table_schema = 'public' " +
+      "  and table_name = 'memory_sessions' " +
+      "  and column_name = 'session_id' limit 1",
+    presentWhen: 'rowReturned'
+  },
   {
     name: 'rumen-tick cron schedule',
     kind: 'rumen',
@@ -134,6 +151,38 @@ const PROBES = Object.freeze([
     probeSql:
       "select 1 as present from cron.job where jobname = 'graph-inference-tick' limit 1",
     presentWhen: 'rowReturned'
+  },
+  // Sprint 51.6 T3 — Brad's Bug D: function-existence probes (cron schedule
+  // checks for jobname presence) are not enough. The deployed Edge Function
+  // SOURCE may be stale even when the cron job and function both exist.
+  // jizzard-brain on 2026-05-03: deployed rumen-tick was missing the
+  // SUPABASE_DB_URL fallback that Sprint 51.5 T1 added; cron probe said
+  // "present", source was old. The marker check below detects that drift.
+  //
+  // probeKind 'functionSource' triggers a Management API fetch instead of a
+  // pgClient.query. Bumps to skipped[] (not missing[]) when drift is
+  // detected — the corresponding "apply" is a redeploy via init-rumen's
+  // deployFunctions, not an SQL migration. The wizard shows skipped[]
+  // entries with their probeError, prompting the user to re-run init.
+  //
+  // Maintenance: bump `requiredMarker` whenever a new feature is added to
+  // the bundled function source that is meaningful enough to gate redeploys
+  // on. The marker should be a string unique to the post-change version.
+  {
+    name: 'rumen-tick deployed source has SUPABASE_DB_URL fallback',
+    kind: 'rumen',
+    probeKind: 'functionSource',
+    functionSlug: 'rumen-tick',
+    requiredMarker: "Deno.env.get('SUPABASE_DB_URL')",
+    presentWhen: 'sourceMatch'
+  },
+  {
+    name: 'graph-inference deployed source has SUPABASE_DB_URL fallback',
+    kind: 'rumen',
+    probeKind: 'functionSource',
+    functionSlug: 'graph-inference',
+    requiredMarker: "Deno.env.get('SUPABASE_DB_URL')",
+    presentWhen: 'sourceMatch'
   }
 ]);
 
@@ -147,8 +196,68 @@ function resolveMigrationFile(target, files) {
   return files.find((f) => path.basename(f) === wanted) || null;
 }
 
+// Sprint 51.6 T3 — Bug D: Edge Function source-drift detection.
+//
+// Fetches the deployed Edge Function body from Supabase Management API and
+// looks for a marker string the bundled source contains. Returns absent
+// (with probeError) when the marker is missing — meaning the deployed
+// function is older than the bundle and should be redeployed.
+//
+// Requires:
+//   - projectRef passed through from auditUpgrade()
+//   - SUPABASE_ACCESS_TOKEN in env (a personal access token, format `sbp_*`)
+// Fail-soft when either is missing — recorded as probeError, treated as
+// absent. The audit caller decides whether to surface to the user.
+async function probeFunctionSource(target, { projectRef, fetchImpl }) {
+  const fn = fetchImpl || (typeof globalThis !== 'undefined' ? globalThis.fetch : undefined);
+  if (typeof fn !== 'function') {
+    return { present: false, probeError: 'no fetch implementation available' };
+  }
+  if (!projectRef) {
+    return { present: false, probeError: 'projectRef required for functionSource probe' };
+  }
+  const accessToken = process.env.SUPABASE_ACCESS_TOKEN;
+  if (!accessToken) {
+    return {
+      present: false,
+      probeError: 'SUPABASE_ACCESS_TOKEN not set; cannot fetch deployed function body. Set the personal access token (`supabase login` writes it to ~/.supabase/access-token) to enable function-source drift detection.',
+    };
+  }
+  let res;
+  try {
+    res = await fn(
+      `https://api.supabase.com/v1/projects/${projectRef}/functions/${target.functionSlug}/body`,
+      { headers: { 'Authorization': `Bearer ${accessToken}` } }
+    );
+  } catch (err) {
+    return { present: false, probeError: `Management API fetch failed: ${err.message}` };
+  }
+  if (!res.ok) {
+    return {
+      present: false,
+      probeError: `Management API returned HTTP ${res.status} for ${target.functionSlug}/body — function may not be deployed yet, or access token lacks permission.`
+    };
+  }
+  let body;
+  try { body = await res.text(); }
+  catch (err) { return { present: false, probeError: `body decode failed: ${err.message}` }; }
+
+  if (target.requiredMarker && body.includes(target.requiredMarker)) {
+    return { present: true };
+  }
+  return {
+    present: false,
+    probeError: `deployed ${target.functionSlug} source missing marker (${JSON.stringify(target.requiredMarker)}) — re-run \`termdeck init --rumen\` to redeploy from bundled source.`,
+  };
+}
+
 // Run a probe and decide present/absent based on the probe's contract.
-async function probeOne(pgClient, target) {
+// Sprint 51.6 T3: dispatches by target.probeKind. Default is the legacy
+// pgClient.query path; 'functionSource' calls probeFunctionSource (HTTP).
+async function probeOne(pgClient, target, ctx = {}) {
+  if (target.probeKind === 'functionSource') {
+    return probeFunctionSource(target, ctx);
+  }
   let result;
   try {
     result = await pgClient.query(target.probeSql);
@@ -233,7 +342,8 @@ async function auditUpgrade({
   projectRef,
   dryRun = false,
   probes,
-  _migrations
+  _migrations,
+  _fetch
 } = {}) {
   if (!pgClient || typeof pgClient.query !== 'function') {
     throw new Error('auditUpgrade: pgClient with .query() is required');
@@ -255,11 +365,23 @@ async function auditUpgrade({
 
   for (const target of targets) {
     probed.push(target.name);
-    const probeResult = await probeOne(pgClient, target);
+    const probeResult = await probeOne(pgClient, target, { projectRef, fetchImpl: _fetch });
     if (probeResult.present) {
       present.push(target.name);
       continue;
     }
+
+    // Sprint 51.6 T3 — Bug D: functionSource probes go to skipped[] (not
+    // missing[]). The corresponding fix is a re-run of `init --rumen` which
+    // calls deployFunctions; audit-upgrade does not auto-redeploy.
+    if (target.probeKind === 'functionSource') {
+      skipped.push({
+        name: target.name,
+        reason: probeResult.probeError || 'function source drift — redeploy via init --rumen',
+      });
+      continue;
+    }
+
     missing.push(target.name);
 
     if (dryRun) continue;
@@ -297,6 +419,7 @@ module.exports = {
   // Test surface — kept exported so audit-upgrade.test.js can pin probe
   // selection / apply pathway behavior without needing a live pg client.
   _probeOne: probeOne,
+  _probeFunctionSource: probeFunctionSource,
   _applyOne: applyOne,
   _resolveMigrationFile: resolveMigrationFile
 };

package/packages/server/src/setup/mnestra-migrations/017_memory_sessions_session_metadata.sql

@@ -0,0 +1,94 @@
+-- Migration 017 — memory_sessions session metadata columns.
+--
+-- Sprint 51.6 T3 (TermDeck v1.0.2 hotfix wave). Brings the canonical engram
+-- memory_sessions schema in line with the rag-system writer's column set so
+-- TermDeck's bundled session-end hook can write a uniform shape on both
+-- fresh-canonical installs and Joshua's daily-driver petvetbid (where the
+-- columns were already added by hand when rag-system bootstrap ran).
+--
+-- Why: until v1.0.2 the bundled hook only wrote memory_items. The actual
+-- memory_sessions writer was Joshua's PRIOR personal hook at
+-- ~/Documents/Graciella/rag-system/hooks/memory-session-end.js, which spawned
+-- ~/Documents/Graciella/rag-system/src/scripts/process-session.ts; that script
+-- INSERTed memory_sessions rows with this richer column set. When the
+-- TermDeck stack-installer overwrote the personal hook on 2026-05-02, the
+-- writer disappeared and memory_sessions stopped accumulating. v1.0.2's
+-- bundled hook gains a memory_sessions write path; this migration ensures
+-- the schema it expects exists everywhere.
+--
+-- Idempotent — safe on:
+--   1. petvetbid (where these columns are already present from hand-applied
+--      DDL Joshua ran when setting up rag-system; the IF NOT EXISTS guards
+--      no-op on every column).
+--   2. Fresh canonical installs that ran migrations 001-016 only (the canonical
+--      engram set, which left memory_sessions at the minimal mig-001 shape).
+--   3. Re-runs of this migration — every operation is guarded.
+--
+-- The unique constraint on session_id is wrapped in a do-block because
+-- ADD CONSTRAINT does not support IF NOT EXISTS in PostgreSQL. Joshua's
+-- petvetbid already has the constraint as memory_sessions_session_id_key
+-- (auto-named by the rag-system bootstrap); this block detects that name
+-- and skips re-adding.
+--
+-- session_id is added NULLABLE on canonical installs even though petvetbid's
+-- existing constraint is NOT NULL. Adding NOT NULL via ALTER TABLE on a
+-- table with existing rows would fail; the bundled hook always supplies
+-- session_id at write time, so nullability is non-blocking. A future sprint
+-- may tighten to NOT NULL with a DEFAULT after a backfill pass.
+
+-- Defensive: vector extension must already be installed (migration 001
+-- requires it for memory_items.embedding). If it's somehow missing this
+-- ADD COLUMN errors, surfacing the real environment issue rather than
+-- silently skipping the embedding column.
+
+alter table public.memory_sessions
+  add column if not exists session_id text,
+  add column if not exists summary_embedding vector(1536),
+  add column if not exists started_at timestamptz,
+  add column if not exists ended_at timestamptz,
+  add column if not exists duration_minutes integer,
+  add column if not exists messages_count integer default 0,
+  add column if not exists facts_extracted integer default 0,
+  add column if not exists files_changed jsonb default '[]'::jsonb,
+  add column if not exists topics jsonb default '[]'::jsonb,
+  add column if not exists transcript_path text;
+
+-- Unique constraint on session_id. Skip if any unique constraint on
+-- (session_id) is already in place — covers both the canonical name
+-- memory_sessions_session_id_key and any alternate name from a manual
+-- ALTER TABLE Joshua may have run on petvetbid.
+do $$
+declare
+  has_unique boolean;
+begin
+  select exists (
+    select 1
+    from pg_constraint c
+    join pg_class t on t.oid = c.conrelid
+    join pg_namespace n on n.oid = t.relnamespace
+    where n.nspname = 'public'
+      and t.relname = 'memory_sessions'
+      and c.contype = 'u'
+      and (
+        select array_agg(att.attname order by att.attnum)
+        from unnest(c.conkey) as colnum
+        join pg_attribute att on att.attrelid = c.conrelid and att.attnum = colnum
+      ) = ARRAY['session_id']::name[]
+  ) into has_unique;
+
+  if not has_unique then
+    alter table public.memory_sessions
+      add constraint memory_sessions_session_id_key unique (session_id);
+  end if;
+end $$;
+
+-- HNSW index on summary_embedding for future similarity search. Idempotent.
+-- Cost on insert is negligible; cost on backfill is one-time.
+create index if not exists memory_sessions_summary_embedding_hnsw_idx
+  on public.memory_sessions using hnsw (summary_embedding vector_cosine_ops)
+  with (m = 16, ef_construction = 64);
+
+-- Helpful covering index for time-range scans (used by Flashback / rumen
+-- queries that filter by ended_at). Idempotent.
+create index if not exists memory_sessions_ended_at_idx
+  on public.memory_sessions(ended_at desc nulls last);

package/packages/stack-installer/README.md

@@ -0,0 +1,73 @@
+# @jhizzard/termdeck-stack
+
+One-command installer for the TermDeck developer memory stack.
+
+```
+npx @jhizzard/termdeck-stack
+```
+
+## What gets installed
+
+| Layer | Package | What it does |
+|-------|---------|--------------|
+| 1 | `@jhizzard/termdeck` | Browser terminal multiplexer with metadata overlays and Flashback recall toasts |
+| 2 | `@jhizzard/mnestra` | pgvector memory store + MCP server. Lights up Flashback. Provides `memory_*` tools to Claude Code, Cursor, Windsurf |
+| 3 | `@jhizzard/rumen` | Async learning loop on a Supabase Edge Function cron. Synthesizes cross-project insights |
+| 4 | `@supabase/mcp-server-supabase` | MCP that lets the TermDeck setup wizard provision your Supabase project automatically |
+
+The wizard:
+
+1. Prints the four-layer overview so you see what you're agreeing to.
+2. Detects which pieces are already on your machine.
+3. Asks which tier you want (default: 4 — full stack).
+4. Runs `npm install -g` for the missing pieces.
+5. Merges Mnestra and Supabase MCP entries into `~/.claude/mcp.json` — preserving any existing MCP servers.
+6. Prints the next steps (Supabase PAT, credentials, `termdeck` to start).
+
+## Modes
+
+```
+npx @jhizzard/termdeck-stack             # interactive
+npx @jhizzard/termdeck-stack --tier 4    # unattended
+npx @jhizzard/termdeck-stack --dry-run   # print plan, don't install
+npx @jhizzard/termdeck-stack --yes       # accept defaults (combine with --tier)
+```
+
+## Known limitations
+
+Tier 3 (Rumen) currently still requires one manual command after the
+installer finishes:
+
+```
+termdeck init --rumen
+```
+
+That command deploys the Rumen Supabase Edge Function, applies the
+migration, and installs the `pg_cron` schedule. Auto-running it from
+the meta-installer is queued — until then the wizard prints it as an
+explicit next step.
+
+## Version vs. the rest of the stack
+
+This package's version tracks the meta-installer surface, not the
+underlying packages. Each layer ships on its own release cadence:
+
+| Package | Where to look |
+|---------|---------------|
+| `@jhizzard/termdeck` | https://www.npmjs.com/package/@jhizzard/termdeck |
+| `@jhizzard/mnestra` | https://www.npmjs.com/package/@jhizzard/mnestra |
+| `@jhizzard/rumen` | https://www.npmjs.com/package/@jhizzard/rumen |
+
+The installer always pulls each layer's `latest` dist-tag, so a fresh
+`npx @jhizzard/termdeck-stack` run picks up the most recent published
+version of every layer regardless of this package's own version.
+
+## Why this exists
+
+The TermDeck stack used to be a 15-step install: provision Supabase, run six SQL migrations, mint API keys, paste them into `secrets.env`, edit `config.yaml`, install Mnestra globally, deploy Rumen, install the Supabase MCP, wire `~/.claude/mcp.json`. Most testers bounced before step 5.
+
+This installer collapses every step that's a `npm install -g` into one command, then drops the user at the doorstep of the in-browser setup wizard (which handles credentials).
+
+## License
+
+MIT