@pcircle/memesh 4.5.1 → 4.6.1

package/scripts/hooks/session-start.js

@@ -2,7 +2,6 @@
 
 import { createRequire } from 'module';
 import { spawn } from 'child_process';
-import { homedir } from 'os';
 import { join } from 'path';
 import { pathToFileURL } from 'url';
 import { existsSync, readFileSync, unlinkSync, mkdirSync, accessSync, constants as fsConstants } from 'fs';
@@ -13,10 +12,22 @@ import {
   getMemeshDirFromDbPath,
   getProjectName,
   importFromPluginRoot,
+  assembleTopologyBlock,
+  DEFAULT_TOPOLOGY_BUDGET,
+  SNIPPET_FETCH_CHARS,
+  TOPOLOGY_CANDIDATE_CAP,
   isTrustedForAutoContext,
+  parseEntityMetadata,
+  // Aliased: this file already has a local `const memeshDir` (a resolved
+  // db-path-derived directory string) — the helper here is the MEMESH_DIR/
+  // home resolver the update-check cache itself uses.
+  memeshDir as memeshHomeDir,
+  parseTaskState,
   readUpdateCheckCache,
   resolvePluginRoot,
   resolveSessionLimit,
+  taskStateLines,
+  taskStateName,
   writePrivateJson,
 } from './_shared.js';
 import { MemeshDatabase } from './_generated/sqlite.js';
@@ -192,7 +203,7 @@ function isStrictlyOlder(a, b) {
   return pa.tail < pb.tail;
 }
 
-function buildUpdateAvailableBanner(currentVersion, cache, channel) {
+function buildUpdateAvailableBanner(currentVersion, cache, getChannel) {
   if (!cache || cache.currentVersion !== currentVersion) return [];
   // Deprecation banner takes precedence — when set, it owns the
   // session-start real estate. Skip the soft banner so the user sees
@@ -215,7 +226,10 @@ function buildUpdateAvailableBanner(currentVersion, cache, channel) {
   // this user a banner today?"
   try {
     const fs = require('fs');
-    const dir = join(homedir(), '.memesh');
+    // memeshHomeDir(), not join(homedir(), '.memesh'): the throttle marker
+    // must sit next to the update-check cache it throttles when MEMESH_DIR
+    // is set (readUpdateCheckCache resolves its path with this same helper).
+    const dir = memeshHomeDir();
     try { ensurePrivateDir(dir); } catch { /* best-effort */ }
     const versionTag = /^[0-9A-Za-z.+-]+$/.test(currentVersion) ? currentVersion : 'unknown';
     const markerPath = join(dir, `last-update-banner.${versionTag}.lock`);
@@ -234,6 +248,13 @@ function buildUpdateAvailableBanner(currentVersion, cache, channel) {
     } catch { /* best-effort */ }
   } catch { /* best-effort */ }
 
+  // Channel detection spawns `npm root -g` (50-200ms) — resolve it only
+  // here, after every early return above has had its chance to suppress
+  // the banner. The guards fire on ~every session; the banner at most
+  // once per 24h.
+  let channel = 'unknown';
+  try { channel = getChannel(); } catch { /* best-effort */ }
+
   const lines = [
     '',
     `ℹ️  MeMesh update available: ${cache.latestVersion} (you're on ${currentVersion}).`,
@@ -241,7 +262,7 @@ function buildUpdateAvailableBanner(currentVersion, cache, channel) {
   if (channel === 'npm-global') {
     lines.push(`    Run: memesh update`);
   } else if (channel === 'plugin-marketplace') {
-    lines.push(`    Run: bash <plugin-root>/scripts/upgrade-plugin.sh   (or reinstall from /plugin UI)`);
+    lines.push(`    Run: memesh upgrade-plugin   (no CLI? npx @pcircle/memesh upgrade-plugin — or reinstall from /plugin UI)`);
   } else if (channel === 'source-checkout') {
     lines.push(`    Source checkout: \`git pull && npm install && npm run build\`.`);
   } else if (channel === 'npm-local') {
@@ -309,7 +330,9 @@ function spawnFreshUpdateCheck(installedVersion) {
     const cliPath = join(pluginRoot, 'dist/transports/cli/cli.js');
     if (!existsSync(cliPath)) return false;
     const fs = require('fs');
-    const dir = join(homedir(), '.memesh');
+    // memeshHomeDir(), not join(homedir(), '.memesh') — same reasoning as
+    // the banner marker above: marker and cache must share a directory.
+    const dir = memeshHomeDir();
     try { ensurePrivateDir(dir); } catch { /* best-effort */ }
     // Codex round 37: scope the throttle marker to the installed
     // version. The marker was machine-global, so a refresh started
@@ -491,8 +514,8 @@ function combineWithBanner(baseMessage) {
       if (deprecation.length > 0) {
         lines = deprecation;
       } else {
-        const channel = detectInstallChannelHook(pluginRoot);
-        lines = buildUpdateAvailableBanner(installedVersion, cache, channel);
+        lines = buildUpdateAvailableBanner(
+          installedVersion, cache, () => detectInstallChannelHook(pluginRoot));
       }
     }
   } catch {
@@ -571,6 +594,10 @@ process.stdin.on('end', async () => {
     // property of the database file that the writing side already set, and a
     // reader opens a WAL database perfectly well without asking for it.
     const db = new MemeshDatabase(dbPath, { readOnly: true });
+    // Whether the noise-compression epilogue below should run at all —
+    // pre-read from this readonly handle before it closes. Defaults to
+    // true so any early exit still lets the epilogue's own throttle decide.
+    let noiseCompressDue = true;
     try {
       // Check if tables exist (db may exist but be empty)
       const tableCheck = db.prepare(
@@ -633,7 +660,12 @@ process.stdin.on('end', async () => {
       // doesn't have confidence/access_count/last_accessed_at, so the
       // SELECT can't reference them. Build the column list to match
       // what the schema actually supports.
-      const baseCols = 'e.id, e.name, e.type, e.created_at, e.metadata';
+      // `title` is an ALTER-added column (UX-1) and gets the same
+      // legacy-schema guard as the scoring columns: a database that predates
+      // it must still produce an injection, falling back to the observation
+      // snippet for its display text.
+      const hasTitle = colNames.has('title');
+      const baseCols = `e.id, e.name, e.type,${hasTitle ? ' e.title,' : ''} e.created_at, e.metadata`;
       const scoringCols = hasScoringCols
         ? `, e.confidence, e.access_count, e.last_accessed_at`
         : '';
@@ -650,7 +682,7 @@ process.stdin.on('end', async () => {
             pool_stats AS (
               SELECT COALESCE(MAX(access_count), 0) AS max_access FROM pool
             )
-            SELECT p.id, p.name, p.type, p.created_at, p.metadata
+            SELECT p.id, p.name, p.type,${hasTitle ? ' p.title,' : ''} p.created_at, p.metadata
             FROM pool p, pool_stats s
             ORDER BY
               COALESCE(p.confidence, 1.0) * 0.2833
@@ -679,7 +711,19 @@ process.stdin.on('end', async () => {
         `JOIN tags t ON t.entity_id = e.id`,
         `WHERE t.tag = ? ${statusFilter}`,
       );
-      const projectEntities = db.prepare(projectQuery).all(projectTag, sessionLimit * 3)
+      // Over-fetch WIDE, then filter. The window used to be `sessionLimit * 3`
+      // and the trust filter ran after it — so a class of entity that ranks
+      // high can consume the entire window and leave nothing. That was not
+      // hypothetical: measured on a real graph, all 30 top-ranked rows were
+      // filtered out and the "project memory" section rendered empty while 92
+      // eligible entities sat below the cut. The filter is a JS predicate with
+      // one owner (`isTrustedForAutoContext`); rather than restate it as SQL
+      // and own it twice, the window is made wide enough that the filtered
+      // class cannot fill it. CANDIDATE_CAP bounds the work for a large graph.
+      // Shared with the briefing surface via the leaf, so the two sides'
+      // candidate windows cannot drift apart.
+      const CANDIDATE_CAP = TOPOLOGY_CANDIDATE_CAP;
+      const projectEntities = db.prepare(projectQuery).all(projectTag, CANDIDATE_CAP)
         .filter(entity => isTrustedForAutoContext(entity.metadata))
         .slice(0, sessionLimit);
 
@@ -688,7 +732,7 @@ process.stdin.on('end', async () => {
       // so rewrite to e.status for consistency.
       const recentWhere = hasStatus ? "WHERE e.status = 'active'" : '';
       const recentQuery = buildScoringQuery('', recentWhere);
-      const recentEntities = db.prepare(recentQuery).all(15)
+      const recentEntities = db.prepare(recentQuery).all(CANDIDATE_CAP)
         .filter(entity => isTrustedForAutoContext(entity.metadata))
         .slice(0, 5);
 
@@ -701,7 +745,7 @@ process.stdin.on('end', async () => {
       let lessonEntities = [];
       try {
         const lessonRows = db.prepare(`
-          SELECT DISTINCT e.id, e.name, e.type, e.metadata
+          SELECT DISTINCT e.id, e.name, e.type,${hasTitle ? ' e.title,' : ''} e.metadata
           FROM entities e
           JOIN tags t ON t.entity_id = e.id
           WHERE e.type = 'lesson_learned'
@@ -754,17 +798,20 @@ process.stdin.on('end', async () => {
       // stay far under that on purpose — session start should prime the
       // model, not consume its working context. Snippets are truncated per
       // observation and the whole block is hard-capped.
-      const MAX_SNIPPET = 160;
-      const MAX_CONTEXT_CHARS = 4000;
+      // The budget itself comes from the leaf (DEFAULT_TOPOLOGY_BUDGET) at
+      // the assembleTopologyBlock call — "the same block" depends on the two
+      // surfaces agreeing, so neither side restates the numbers.
+
+      // Only the entities we will actually render — the lesson query pulls
+      // up to 50 rows for the banner count, but at most 5 are injected, and
+      // this runs before the user's first turn. Bounded well under SQLite's
+      // 999-variable limit by construction (5 lessons + sessionLimit
+      // project + 5 recent). Declared out here because the injected-set
+      // record below must list the SAME lessons the block renders.
+      const topLessons = lessonEntities.slice(0, 5);
 
       const memoryLines = [];
       try {
-        // Only the entities we will actually render — the lesson query pulls
-        // up to 50 rows for the banner count, but at most 5 are injected, and
-        // this runs before the user's first turn. Bounded well under SQLite's
-        // 999-variable limit by construction (5 lessons + sessionLimit
-        // project + 5 recent).
-        const topLessons = lessonEntities.slice(0, 5);
         const rankedIds = [
           ...topLessons.map(e => e.id),
           ...projectEntities.map(e => e.id),
@@ -788,33 +835,63 @@ process.stdin.on('end', async () => {
             // later ones are refinements.
             if (snippets.has(row.entity_id)) continue;
             const text = String(row.content ?? '').replace(/\s+/g, ' ').trim();
-            if (text) snippets.set(row.entity_id, text.slice(0, MAX_SNIPPET));
+            // A few line-widths, not the exact line cap: the final cut is
+            // clip()'s, on a word boundary — a hard slice at the line cap
+            // would hand it a string with nothing left to trim and ship
+            // mid-word fragments again.
+            if (text) snippets.set(row.entity_id, text.slice(0, SNIPPET_FETCH_CHARS));
           }
         }
 
-        // Groups overlap by construction: a lesson tagged to this project
-        // is in lessonEntities AND projectEntities. Render each entity once,
-        // in the highest-priority group it belongs to, so the injected block
-        // doesn't spend the model's context repeating itself.
-        const rendered = new Set();
-        const renderGroup = (label, entities) => {
-          const fresh = entities.filter(e => !rendered.has(e.id));
-          if (fresh.length === 0) return;
-          memoryLines.push(label);
-          for (const e of fresh) {
-            rendered.add(e.id);
-            const snippet = snippets.get(e.id);
-            const type = e.type || 'memory';
-            memoryLines.push(
-              snippet ? `- ${e.name} (${type}): ${snippet}` : `- ${e.name} (${type})`
-            );
-          }
-          memoryLines.push('');
-        };
+        // "Where we left off" leads the block. It is the one memory a new
+        // session needs before any other: everything below is context for
+        // work, this IS the work. It is also the only line here a human
+        // (or an agent acting for one) stated on purpose — the rest is
+        // ranked, and ranking cannot know what you meant to do next.
+        //
+        // Read from metadata, not from the observation trail: observations
+        // are the CHANGE history, and picking "the current goal" out of them
+        // means guessing which line is newest. Metadata holds one answer.
+        const taskRow = db
+          .prepare('SELECT metadata FROM entities WHERE name = ?')
+          .get(taskStateName(projectName));
+        const stateLines = taskStateLines(
+          parseTaskState(parseEntityMetadata(taskRow?.metadata)),
+          projectName,
+        );
 
-        renderGroup('Lessons learned (avoid repeating these):', topLessons);
-        renderGroup(`Project memory for "${projectName}":`, projectEntities);
-        renderGroup('Recently active across projects:', recentEntities);
+        // The pools overlap by construction (a lesson tagged to this project
+        // is in lessonEntities AND projectEntities); the shared assembler
+        // dedupes across them in claim order, so a project-scoped row is
+        // never marked foreign by the cross-project recent pool, and the
+        // topology grouping decides where each one belongs. This mapping —
+        // raw row → TopologyEntity — is the only part this hook owns; the
+        // assembly order, the spacer discipline, the budget and the
+        // task-state exclusion live in the leaf, shared with `briefing`.
+        const toEntity = (e) => {
+          const meta = parseEntityMetadata(e.metadata);
+          return {
+            name: e.name,
+            type: e.type || 'memory',
+            // The citation handle: topologyLine prints `[mem:<id>]` so the
+            // agent can credit the exact memory it used (the Stop hook's
+            // accounting reads those markers back).
+            id: e.id,
+            title: e.title ?? null,
+            snippet: snippets.get(e.id) ?? null,
+            signalScore: meta && typeof meta.signal_score === 'number' ? meta.signal_score : null,
+          };
+        };
+        memoryLines.push(...assembleTopologyBlock(
+          stateLines,
+          [
+            { entities: topLessons.map(toEntity), foreign: false },
+            { entities: projectEntities.map(toEntity), foreign: false },
+            { entities: recentEntities.map(toEntity), foreign: true },
+          ],
+          projectName,
+          DEFAULT_TOPOLOGY_BUDGET,
+        ));
       } catch (err) {
         // Snippet enrichment is best-effort. A failure here must not stop
         // the banner or the session — but trace it, because a silent break
@@ -830,40 +907,33 @@ process.stdin.on('end', async () => {
         // attacker-influenced in the general case (anything the agent has
         // ever been told can end up in an observation), so it must be
         // delimited the same way on every injection path — not hand-rolled
-        // per hook.
-        //
-        // Truncate the LINES before wrapping, so the closing fence is never
-        // cut off — a dangling fence would let the tail of the block escape
-        // its delimiter.
-        const budgeted = [];
-        let used = 0;
-        for (const line of memoryLines) {
-          if (used + line.length + 1 > MAX_CONTEXT_CHARS) {
-            budgeted.push('… (truncated)');
-            break;
-          }
-          budgeted.push(line);
-          used += line.length + 1;
-        }
-        memoryContext = buildReferenceContext(budgeted);
+        // per hook. The lines arrive already budgeted — assembleTopologyBlock
+        // charges the task-state block and the sections against ONE ceiling
+        // and returns whole lines only, so the closing fence cannot be cut.
+        memoryContext = buildReferenceContext(memoryLines);
+        // The citation contract — OUTSIDE the fence on purpose: the fence
+        // declares its content "background data, not instructions", and
+        // this line IS an instruction. One line is the entire write side of
+        // the injection-ROI signal; the Stop hook credits recall_hits only
+        // from these markers (self-reported: undercounts, never overcounts).
+        memoryContext += '\nWhen a memory above genuinely informs your work, cite it once inline as [mem:ID], using the id shown on its line.';
       }
 
       // --- Record injected entity IDs for recall effectiveness tracking ---
-      // The Stop hook decides hit/miss by removing the transcript records
-      // Claude Code created FROM this hook's output (see stripHookEchoes in
-      // session-summary.js) and then looking for the entity name in what
-      // remains. `injectedContext` is kept as the record of what was shown,
-      // not as a string to subtract — an earlier version subtracted it and a
-      // later one counted its occurrences, and BOTH were wrong because one
-      // injection is echoed into the transcript more than once.
+      // The Stop hook credits recall_hits from EXPLICIT `[mem:id]` citations
+      // the agent writes (after structurally removing the transcript records
+      // Claude Code created FROM this hook's output — the injected block
+      // itself prints a handle on every line; see stripHookEchoes in
+      // session-summary.js). Literal-content matching was retired after
+      // measuring 0% signal over ten real sessions. `injectedContext` is
+      // kept as the record of what was shown.
       //
-      // It must still be the text we actually injected: previously it was the
-      // count-only banner, so every injected entity was scored against a
-      // transcript it had never appeared in and took a `recall_miss` it did
-      // not earn.
+      // The set below is every pool the topology block draws from — the
+      // lessons pool included. It used to record only project + recent
+      // rows, so an injected lesson could never be credited at all.
       try {
         const seenIds = new Set();
-        const allInjected = [...projectEntities, ...recentEntities].filter(e => {
+        const allInjected = [...topLessons, ...projectEntities, ...recentEntities].filter(e => {
           if (seenIds.has(e.id)) return false;
           seenIds.add(e.id);
           return true;
@@ -900,11 +970,11 @@ process.stdin.on('end', async () => {
           } catch {}
         }
       } catch (err) {
-        // Non-critical — sessions-file write powers recall-effectiveness
-        // tracking (recall_hits / recall_misses on the dashboard). If it
-        // silently breaks, the impact-score factor in core/scoring.ts
-        // converges on 0.5 (neutral) for everything. Stderr trace so a
-        // permission/serialisation regression is visible.
+        // Non-critical — sessions-file write powers citation accounting
+        // (recall_hits credited from `[mem:id]` markers). If it silently
+        // breaks, no hit can ever be credited and the impact-score factor
+        // in core/scoring.ts converges on 0.5 (neutral) for everything.
+        // Stderr trace so a permission/serialisation regression is visible.
         try { process.stderr.write(`[memesh session-start] sessions-write: ${err?.message || err}\n`); } catch {}
       }
 
@@ -925,12 +995,8 @@ process.stdin.on('end', async () => {
         if (deprecation.length > 0) {
           bannerLines = deprecation;
         } else {
-          let channel = 'unknown';
-          try {
-            const pluginRoot = resolvePluginRoot(import.meta.url);
-            channel = detectInstallChannelHook(pluginRoot);
-          } catch { /* best-effort */ }
-          bannerLines = buildUpdateAvailableBanner(installedVersion, updateCache, channel);
+          bannerLines = buildUpdateAvailableBanner(installedVersion, updateCache,
+            () => detectInstallChannelHook(resolvePluginRoot(import.meta.url)));
         }
       }
       const finalMessage = bannerLines.length > 0
@@ -938,6 +1004,25 @@ process.stdin.on('end', async () => {
         : summary;
 
       output(withCaptureWarning(finalMessage), memoryContext);
+
+      // Pre-read the noise-compression throttle on the handle we already
+      // hold. compressWeeklyNoise() re-checks under its own connection, but
+      // ~364/365 sessions are inside the 24h window — and the full path
+      // costs two dist module-graph imports plus a write-capable
+      // migration-chain open (WAL writer lock) that must stay off the
+      // SessionStart hot path. Missing table / any error ⇒ due (the full
+      // path owns schema creation).
+      noiseCompressDue = (() => {
+        try {
+          const row = db.prepare(
+            "SELECT value FROM memesh_metadata WHERE key = 'last_noise_compress_at'"
+          ).get();
+          if (!row) return true;
+          return Date.now() - new Date(row.value).getTime() >= 24 * 60 * 60 * 1000;
+        } catch {
+          return true;
+        }
+      })();
     } finally {
       db.close();
     }
@@ -945,6 +1030,7 @@ process.stdin.on('end', async () => {
     // Opens a separate read-write connection via the core module.
     // Throttled to once per 24h inside compressWeeklyNoise().
     try {
+      if (noiseCompressDue) {
       // F5: derive pluginRoot strictly from this file's location.
       // See `resolvePluginRoot` for the full reasoning.
       const pluginRoot = resolvePluginRoot(import.meta.url);
@@ -956,6 +1042,7 @@ process.stdin.on('end', async () => {
       } finally {
         dbMod.closeDatabase();
       }
+      }
     } catch (err) {
       // Non-critical — noise compression failed, will retry next session.
       // Trace because this catch previously hid an off-by-one regression