memoir-cli 3.8.1 → 3.10.0

package/src/context/capture.js

@@ -151,6 +151,58 @@ function parseLines(lines) {
   return result;
 }
 
+// Reject conversational fragments that loose regexes sometimes capture as
+// "decisions" — questions, and clauses starting with a pronoun/filler word
+// ("we pick this back up Monday", "it up at...", "some lenders may...").
+function looksLikeFragment(v) {
+  if (!v) return true;
+  if (/\?/.test(v)) return true;
+  if (/^(it|this|that|these|those|we|i|they|you|he|she|some|there|here|just|back|now|also)\b/i.test(v)) return true;
+  return false;
+}
+
+// Quality gate for auto-extracted decisions before they're written to EITHER
+// persistence sink (session-decisions.md via persistDecisions, or session.json
+// via addNote — see push.js, which now runs this once over parsed.decisions
+// before both call sites). Auto-extraction is regex-based and occasionally
+// produces prose fragments, markdown-table cells, or truncated pasted-spec
+// snippets — this rejects the shapes that look like junk rather than a real
+// decision.
+//
+// 2026-07: two real junk decisions made it into a live session.json because
+// the user-note regex (see extractDecisions below) matched mid-paragraph
+// inside long pasted spec/prompt text, and one of them was a hard 150-char
+// truncation with an unbalanced closing paren. The regex is now anchored to
+// message/line start (see below), which independently prevents both from
+// matching at all — these two extra checks are defense-in-depth for the
+// other, unanchored pattern branches (rename/tech/design/stack) that can
+// still match mid-message.
+export function isQuality(text) {
+  if (!text) return false;
+  if (text.length < 15) return false;                // too short to be a real decision
+  if (text.length > 200) return false;                // probably a snippet, not a decision
+  if (/\|/.test(text)) return false;                  // markdown table fragment
+  if (/[_*`]{3,}/.test(text)) return false;           // markdown formatting leaked in
+  if (!/[a-zA-Z]/.test(text)) return false;           // no actual words
+  if (looksLikeFragment(text)) return false;          // question, or pronoun/filler-start fragment
+  const words = text.split(/\s+/).length;
+  if (words < 3) return false;                        // less than 3 words isn't a decision
+
+  // Unbalanced parens/brackets — a hallmark of a regex capture that got cut
+  // off mid-parenthetical (real junk: "...only gain is Y)" with no opener,
+  // because the opening "(" was in the text BEFORE the capture started).
+  const opens = (text.match(/[(\[]/g) || []).length;
+  const closes = (text.match(/[)\]]/g) || []).length;
+  if (opens !== closes) return false;
+
+  // Suspiciously long AND doesn't end in sentence-ending punctuation or a
+  // closing quote — another truncation signature (a capture cut off mid-word
+  // or mid-sentence by a regex length cap rather than ending naturally).
+  if (text.length >= 140 && !/[.!?"')\]]$/.test(text)) return false;
+
+  return true;
+}
+
 /**
  * Extract durable decisions from session conversation.
  * These are things like renames, tech choices, preferences — stuff that should persist.
@@ -168,16 +220,19 @@ function extractDecisions(userMessages, assistantTexts) {
     // Tech choices
     { regex: /(?:let'?s|we(?:'ll| will| should)?|going to|decided to)\s+use\s+([A-Z][a-zA-Z0-9_./-]+)\s+(?:for|instead|as|to)/gi, type: 'tech' },
     { regex: /(?:switch|migrate|move)\s+(?:from\s+\S+\s+)?to\s+([A-Z][a-zA-Z0-9_./-]+)/gi, type: 'tech' },
-    // Architecture / design
-    { regex: /(?:let'?s|we(?:'ll| will| should)?)\s+(?:go with|pick|choose)\s+(.{5,60}?)(?:\.|$|,|\n)/gi, type: 'design' },
-    // Stack choices
-    { regex: /(?:stack|framework|database|backend|frontend)\s+(?:is|will be|should be)\s+(.{5,60}?)(?:\.|$|,|\n)/gi, type: 'stack' },
+    // Architecture / design — require an explicit decision verb and a capitalized
+    // target. Bare "pick/choose" caught conversational fragments as decisions.
+    { regex: /(?:decided|settled|going|chose|chosen)\s+(?:to\s+(?:go\s+with|use)|with|on)\s+([A-Z][\w .\/+-]{3,50}?)(?:\.|$|,|\n)/g, type: 'design' },
+    // Stack choices — require a capitalized, tech-looking value, not a prose
+    // fragment ("backend is just throwing it away" used to leak through).
+    { regex: /(?:stack|framework|database|backend|frontend|hosting|infra)\s+(?:is|will be|should be)\s+([A-Z][\w .\/+-]{2,40}?)(?:\.|$|,|\n)/g, type: 'stack' },
   ];
 
   for (const { regex, type } of patterns) {
     let match;
     while ((match = regex.exec(allText)) !== null) {
       const value = match[1].trim().replace(/["']+$/, '');
+      if (looksLikeFragment(value)) continue;
       if (value.length > 2 && value.length < 80) {
         // Avoid duplicates
         const existing = decisions.find(d => d.value.toLowerCase() === value.toLowerCase());
@@ -188,12 +243,37 @@ function extractDecisions(userMessages, assistantTexts) {
     }
   }
 
-  // Look for explicit "remember this" instructions from the user
+  // Look for explicit "remember this" instructions from the user.
+  //
+  // Anchored to message/line start ((?:^|\n) immediately before optional
+  // indentation and an optional "please") — unlike the pattern branches
+  // above, this used to match ANYWHERE in the message, which meant a phrase
+  // like "note that" or "keep in mind that" appearing mid-sentence inside a
+  // long pasted spec/prompt got misread as an explicit remember-instruction.
+  // Requiring it to start the message (or a line within it) means only a
+  // genuine top-of-message instruction matches, not incidental prose deep in
+  // pasted content.
+  //
+  // Only scanned within the first ~500 chars of the message: a short
+  // "Remember that X." followed by a long paste in the SAME turn must still
+  // be captured (the instruction is still at message start), but a trigger
+  // phrase that only occurs later/mid-document in a long paste is excluded
+  // — it was never an instruction to begin with.
+  const USER_NOTE_RE = /(?:^|\n)[ \t]*(?:please\s+)?(?:remember (?:that|this)|note that|keep in mind that|from now on)[:\s]+(.{10,150})/i;
   for (const msg of userMessages) {
-    // Only match when user is clearly asking to remember something
-    const rememberMatch = msg.match(/(?:remember (?:that|this)|note that|keep in mind that|from now on)[:\s]+(.{10,150})/i);
+    const scope = msg.slice(0, 500);
+    const rememberMatch = scope.match(USER_NOTE_RE);
     if (rememberMatch) {
-      decisions.push({ type: 'user-note', value: rememberMatch[1].trim(), context: msg.slice(0, 120) });
+      const capturedRaw = rememberMatch[1];
+      // The capture group is capped at 150 chars. Hitting that cap exactly is
+      // a truncation signature — real junk in the wild was a parenthetical
+      // cut off mid-thought with an unbalanced closing paren. Reject rather
+      // than keep a truncated tail.
+      const hitCap = capturedRaw.length === 150;
+      const value = capturedRaw.trim();
+      if (!hitCap && !looksLikeFragment(value)) {
+        decisions.push({ type: 'user-note', value, context: msg.slice(0, 120) });
+      }
     }
   }
 
@@ -201,37 +281,44 @@ function extractDecisions(userMessages, assistantTexts) {
 }
 
 /**
- * Write extracted decisions to Claude's persistent memory.
- * This ensures decisions survive across sessions and machines.
+ * Resolve the HOME-level memory dir (~/.claude/projects/<home-key>/memory) —
+ * the one that matches the user's home path encoding, not a sub-project.
+ * Returns null if none exists. Shared by persistDecisions + lean-memory tidy.
  */
-export function persistDecisions(decisions, claudeSource) {
-  if (!decisions || decisions.length === 0) return 0;
-
+export function resolveHomeMemoryDir(claudeSource) {
   const claudeDir = claudeSource || path.join(home, '.claude');
   const projectsDir = path.join(claudeDir, 'projects');
-  if (!fs.existsSync(projectsDir)) return 0;
+  // Canonical home-key path ONLY. We deliberately do NOT fall back to "shortest
+  // dir that has a memory/ subfolder" — on a shared machine that could silently
+  // target a different project's (or teammate's) memory. Callers create the dir
+  // if needed; tidy safely no-ops when MEMORY.md is absent.
+  const homeKey = process.platform === 'win32'
+    ? home.replace(/\\/g, '-').replace(/:/g, '-')
+    : '-' + home.replace(/^\//, '').replace(/\//g, '-');
+  return path.join(projectsDir, homeKey, 'memory');
+}
 
-  // Find the HOME-level memory dir (not project-specific)
-  // This is the dir that matches the user's home path encoding
-  let homeKey;
-  if (process.platform === 'win32') {
-    homeKey = home.replace(/\\/g, '-').replace(/:/g, '-');
-  } else {
-    homeKey = '-' + home.replace(/^\//, '').replace(/\//g, '-');
-  }
+// Atomic write (sync): write to a pid-scoped tmp file, then rename over the
+// target. Matches the tmp-then-rename idiom used elsewhere in this codebase
+// (state.js's writeSession, inject.js's injectInto) — prevents a torn/partial
+// file if the process crashes mid-write. persistDecisions stays synchronous
+// (its one caller in push.js doesn't await it), so this uses the sync
+// fs-extra APIs rather than switching the whole call chain to async.
+function writeFileAtomicSync(targetPath, content) {
+  const tmp = `${targetPath}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, content);
+  fs.moveSync(tmp, targetPath, { overwrite: true });
+}
 
-  // Try exact match first, then detect from existing dirs
-  let memDir = path.join(projectsDir, homeKey, 'memory');
-  if (!fs.existsSync(memDir)) {
-    // Fallback: find dirs with memory/ subfolder, pick shortest name (likely home-level)
-    const entries = fs.readdirSync(projectsDir, { withFileTypes: true })
-      .filter(e => e.isDirectory() && fs.existsSync(path.join(projectsDir, e.name, 'memory')));
-    if (entries.length === 0) return 0;
-    // Shortest dir name is most likely the home key (not a sub-project)
-    const homeEntry = entries.sort((a, b) => a.name.length - b.name.length)[0];
-    memDir = path.join(projectsDir, homeEntry.name, 'memory');
-  }
+/**
+ * Write extracted decisions to Claude's persistent memory.
+ * This ensures decisions survive across sessions and machines.
+ */
+export function persistDecisions(decisions, claudeSource) {
+  if (!decisions || decisions.length === 0) return 0;
 
+  const memDir = resolveHomeMemoryDir(claudeSource);
+  if (!memDir) return 0;
   fs.mkdirSync(memDir, { recursive: true });
   const decisionsFile = path.join(memDir, 'session-decisions.md');
   const memoryMdPath = path.join(memDir, 'MEMORY.md');
@@ -269,10 +356,10 @@ type: project
 
 # Decisions from coding sessions
 ${section}`;
-    fs.writeFileSync(decisionsFile, content);
+    writeFileAtomicSync(decisionsFile, content);
   } else {
     // Append to existing
-    fs.writeFileSync(decisionsFile, existing.trimEnd() + '\n' + section);
+    writeFileAtomicSync(decisionsFile, existing.trimEnd() + '\n' + section);
   }
 
   // Ensure MEMORY.md references the decisions file
@@ -280,7 +367,7 @@ ${section}`;
     const memoryMd = fs.readFileSync(memoryMdPath, 'utf8');
     if (!memoryMd.includes('session-decisions.md')) {
       const addition = `\n- [Session Decisions](session-decisions.md) — project renames, tech choices, architecture decisions from coding sessions\n`;
-      fs.writeFileSync(memoryMdPath, memoryMd.trimEnd() + addition);
+      writeFileAtomicSync(memoryMdPath, memoryMd.trimEnd() + addition);
     }
   }
 

package/src/events/log.js

@@ -0,0 +1,113 @@
+// Additive, size-bounded, crash-safe JSONL event log.
+//
+// Target: ~/.config/memoir/events.jsonl — one JSON object per line:
+//   { ts, type, machine_id, ...minimal metadata }
+//
+// PRIVACY: this must never become a second, unfiltered copy of sensitive
+// user data. NEVER log raw decision/note/goal TEXT content — only counts,
+// ids, booleans, and short enum-like type strings. Every call site in this
+// codebase that calls appendEvent() is expected to honor that; review any
+// new call site against it.
+//
+// CRASH-SAFE: pure fs.appendFileSync (O_APPEND) for the actual write —
+// never a read-modify-write on this file, so a crash mid-write can at worst
+// leave a truncated LAST line, never corrupt earlier ones.
+//
+// SIZE-BOUNDED: rotates at MAX_BYTES — events.jsonl -> .1 -> .2, oldest
+// generation beyond MAX_ROTATIONS is deleted.
+//
+// LOCKED ROTATE-THEN-APPEND: the size-check-and-maybe-rotate is itself a
+// check-then-act sequence that would race under concurrent processes
+// exactly like the session.json bug Commit 4 fixed (two processes both see
+// "under the cap," both append, one rotates mid-write, etc.). Rather than
+// threading through whichever *other* lock happens to be held at each of
+// the 6+ call sites (some of which, like sync_pushed/sync_failed, have no
+// adjacent lock at all), this uses ONE small dedicated lock
+// (events.jsonl.lock) around every rotate-then-append, uniformly. Simpler
+// and always-safe, at the cost of a little lock contention on an
+// infrequent, cheap operation — a deliberate simplification over coupling
+// to each caller's own lock.
+//
+// NEVER BREAKS THE CALLER: appendEvent() catches everything internally and
+// never throws. The primary operation it's logging (writeSession,
+// injectInto, push, etc.) must always succeed or fail on its own merits,
+// never because event logging failed.
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { getMachineId } from '../session/state.js';
+import { withSessionLock } from '../session/lock.js';
+
+const CONFIG_DIR = process.platform === 'win32'
+  ? path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'memoir')
+  : path.join(os.homedir(), '.config', 'memoir');
+const EVENTS_PATH = path.join(CONFIG_DIR, 'events.jsonl');
+const EVENTS_LOCK_PATH = path.join(CONFIG_DIR, 'events.jsonl.lock');
+
+const MAX_BYTES = 5 * 1024 * 1024; // 5MB
+const MAX_ROTATIONS = 2; // keep events.jsonl.1 and .2; older generations are dropped
+
+let cachedMachineId = null;
+async function machineId() {
+  if (cachedMachineId) return cachedMachineId;
+  try {
+    const { id } = await getMachineId();
+    cachedMachineId = id;
+  } catch {
+    cachedMachineId = 'unknown';
+  }
+  return cachedMachineId;
+}
+
+// Rotate events.jsonl -> .1 -> .2, drop anything beyond MAX_ROTATIONS. Must
+// only be called from within the events lock (see appendEvent) — this
+// function itself does no locking.
+function rotateIfNeeded() {
+  try {
+    if (!fs.existsSync(EVENTS_PATH)) return;
+    const stat = fs.statSync(EVENTS_PATH);
+    if (stat.size < MAX_BYTES) return;
+
+    // Shift existing generations up (.1 -> .2 -> dropped), oldest first.
+    for (let i = MAX_ROTATIONS; i >= 1; i--) {
+      const src = `${EVENTS_PATH}.${i}`;
+      if (!fs.existsSync(src)) continue;
+      if (i === MAX_ROTATIONS) {
+        fs.removeSync(src); // oldest generation, drop it
+      } else {
+        fs.moveSync(src, `${EVENTS_PATH}.${i + 1}`, { overwrite: true });
+      }
+    }
+    fs.moveSync(EVENTS_PATH, `${EVENTS_PATH}.1`, { overwrite: true });
+  } catch {
+    // Rotation failure must never block an append.
+  }
+}
+
+/**
+ * Append one JSON event line. See file header for the privacy contract
+ * (counts/ids/booleans/enum-strings only, never raw content) and the
+ * crash-safety / size-bound / locking guarantees.
+ *
+ * Always safe to call and await — never throws, never rejects.
+ */
+export async function appendEvent(type, payload = {}) {
+  try {
+    await fs.ensureDir(CONFIG_DIR);
+    const id = await machineId();
+    const line = JSON.stringify({ ts: new Date().toISOString(), type, machine_id: id, ...payload }) + '\n';
+
+    await withSessionLock(EVENTS_LOCK_PATH, async () => {
+      rotateIfNeeded();
+      fs.appendFileSync(EVENTS_PATH, line);
+    });
+  } catch {
+    // Never break the caller.
+  }
+}
+
+export const paths = {
+  events: EVENTS_PATH,
+  eventsLock: EVENTS_LOCK_PATH,
+};

package/src/mcp.js

@@ -697,7 +697,13 @@ server.tool(
   { query: z.string().describe('Keyword or phrase to search in decision text, rationale, or rejected alternative') },
   async ({ query }) => {
     const state = await readSession();
-    const matches = findDecisions(state, query);
+    // findDecisions() already filters hidden:true (tombstoned) decisions —
+    // this second filter is deliberate belt-and-suspenders so this tool
+    // handler stays correct even if findDecisions' internals change without
+    // that coupling being obvious. Same tombstone semantics as render.js's
+    // pinned block and why.js's CLI display: distinct from the live
+    // `rejected` field.
+    const matches = findDecisions(state, query).filter(d => !d?.hidden);
     if (matches.length === 0) {
       return { content: [{ type: 'text', text: `No decisions match "${query}".` }] };
     }

package/src/providers/index.js

@@ -3,6 +3,7 @@ import path from 'path';
 import os from 'os';
 import chalk from 'chalk';
 import { execFileSync } from 'child_process';
+import { appendEvent } from '../events/log.js';
 
 function sanitizeUrl(url) {
   // Reject URLs with shell metacharacters
@@ -23,6 +24,7 @@ export async function syncToLocal(config, stagingDir, spinner) {
 
   await fs.copy(stagingDir, resolvedDest);
   spinner.succeed(chalk.green('Sync complete! ') + chalk.gray(`(Saved to ${resolvedDest})`));
+  await appendEvent('sync_pushed', { provider: 'local' });
 }
 
 export async function syncToGit(config, stagingDir, spinner) {
@@ -64,7 +66,15 @@ export async function syncToGit(config, stagingDir, spinner) {
     execFileSync('git', ['push', repoUrl, 'main'], { cwd: gitDir, stdio: 'ignore', timeout: 120000 });
 
     spinner.succeed(chalk.green('Sync complete! ') + chalk.gray('(Uploaded securely to GitHub)'));
+    await appendEvent('sync_pushed', { provider: 'git' });
   } catch (err) {
+    // Makes a silently-swallowed push failure (a non-fast-forward rejection
+    // from two racing pushes, a network error, bad credentials, etc.)
+    // visible in the event log instead of vanishing into the detached
+    // autopush child's ignored stdio. Deliberately no raw error text/repo
+    // URL in the payload — those can contain usernames/paths; type+provider
+    // is enough to know "pushes are failing" without leaking anything.
+    await appendEvent('sync_failed', { provider: 'git' });
     if (err.message.includes('invalid characters')) throw err;
     throw new Error('Failed to push to git repository. Ensure your credentials are configured and the repository exists.');
   } finally {

package/src/session/inject.js

@@ -14,6 +14,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import { BLOCK_START, BLOCK_END } from './render.js';
+import { appendEvent } from '../events/log.js';
 
 const home = os.homedir();
 const isWin = process.platform === 'win32';
@@ -79,6 +80,17 @@ export async function injectInto(targetPath, renderedBlock) {
   await fs.writeFile(tmp, updated);
   await fs.move(tmp, targetPath, { overwrite: true });
 
+  // One event per target (this function is called once per detected tool —
+  // up to ~4x for a single session update). Deliberate: each call here IS a
+  // successful write to one specific target file, and the payload is tiny
+  // (just the filename, no content), so per-tool visibility is worth the 4x
+  // over collapsing to one event per "session update." injectInto() only
+  // receives a raw path (callers loop over detectAvailableTargets() by
+  // value, discarding the tool-name key), so the filename itself
+  // (CLAUDE.md / memoir-session.mdc / memoir-session.md / GEMINI.md) is
+  // what's actually available here without a larger refactor.
+  await appendEvent('memory_written', { target: path.basename(targetPath) });
+
   return { path: targetPath, created: !existed, replaced: existed && BLOCK_RE.test(content) };
 }
 

package/src/session/lock.js

@@ -0,0 +1,102 @@
+// Lightweight file lock for a read-modify-write critical section, with NO
+// new npm dependency.
+//
+// WHY: two independent Claude Code sessions (or two racing Stop hooks) can
+// run against the same $HOME at once — each runs its own memoir-mcp stdio
+// server / autopush invocation. Every session.json mutator in state.js does
+// readSession() -> mutate in memory -> writeSession(). writeSession's
+// tmp-then-rename only prevents a TORN write; it does not stop two
+// concurrent processes from both reading the same on-disk snapshot,
+// mutating independently, and having the second writeSession() silently and
+// completely overwrite the first process's change. autopush.js's debounce
+// check ("read timestamp, compare elapsed, write new timestamp") is the same
+// class of unlocked check-then-act. This is a real, easily-triggered
+// data-loss bug, not a theoretical one.
+//
+// MECHANISM: fs.openSync(lockPath, 'wx') is an atomic create-exclusive at
+// the OS level — it throws EEXIST if the file already exists, so exactly one
+// process can "win" the create at a time. Acquire retries on EEXIST with a
+// short delay, up to a bounded total wait. Release deletes the lock file,
+// wrapped in try/finally so a thrown error inside the critical section still
+// releases the lock.
+//
+// STALE-LOCK RECOVERY: if the lock file is older than STALE_MS, we assume
+// the process that created it crashed (or was killed) while holding it, and
+// we remove it and proceed. This trades a small window of imperfect mutual
+// exclusion for availability — appropriate for a local, single-user tool,
+// where a permanently stuck lock from a crashed process is a worse failure
+// mode than the rare double-write it might allow.
+
+import fs from 'fs-extra';
+import path from 'path';
+
+const RETRY_DELAY_MS = 50;
+const MAX_WAIT_MS = 5000;
+const STALE_MS = 30_000; // treat a lock older than this as abandoned
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Acquire the exclusive lock at `lockPath`, run `fn`, then always release —
+ * even if `fn` throws. Returns whatever `fn` returns/resolves to.
+ *
+ * If the lock can't be acquired within MAX_WAIT_MS (and stale-lock recovery
+ * didn't free it up), proceeds WITHOUT the lock rather than hanging forever,
+ * printing one loud stderr warning — never blocks the caller indefinitely,
+ * and never throws just because the lock was contended.
+ */
+export async function withSessionLock(lockPath, fn) {
+  await fs.ensureDir(path.dirname(lockPath));
+  const start = Date.now();
+  let fd = null;
+  let warned = false;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      fd = fs.openSync(lockPath, 'wx');
+      try { fs.writeSync(fd, String(process.pid)); } catch {}
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+
+      // Stale-lock recovery: the holder may have crashed. If the lock file
+      // is older than STALE_MS, remove it and retry the acquire immediately
+      // (no delay) rather than waiting out the full bounded window.
+      try {
+        const stat = fs.statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > STALE_MS) {
+          try { fs.unlinkSync(lockPath); } catch {}
+          continue;
+        }
+      } catch {
+        // Lock file vanished between the failed open and this stat (the
+        // holder released it) — just retry the acquire.
+        continue;
+      }
+
+      if (Date.now() - start > MAX_WAIT_MS) {
+        if (!warned) {
+          warned = true;
+          process.stderr.write(
+            `memoir: could not acquire lock at ${lockPath} after ${MAX_WAIT_MS}ms — proceeding without it (another memoir process may be mid-write).\n`
+          );
+        }
+        fd = null;
+        break; // proceed without the lock rather than hang forever
+      }
+      await sleep(RETRY_DELAY_MS);
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); } catch {}
+      try { fs.unlinkSync(lockPath); } catch {}
+    }
+  }
+}

package/src/session/migrations.js

@@ -0,0 +1,98 @@
+// Pure, no-I/O session-schema migration ladder for session.json.
+//
+// This module has NO file access and NO side effects — it's a plain data
+// transform: migrateSessionData(parsedObject) -> { future, state }. That
+// makes it safe to reuse everywhere a session object needs normalizing,
+// not just when reading the local file:
+//   - state.js's readSession() calls it after JSON.parse-ing the local
+//     ~/.config/memoir/session.json.
+//   - push.js and restore.js call it on an already-parsed REMOTE session.json
+//     (fetched from another machine's backup) before merging it with the
+//     local session via mergeSessions — so a lagging machine's old-schema
+//     file, or a machine ahead on a newer schema, gets migrated/degraded
+//     consistently regardless of which code path touched it first.
+//
+// File-specific concerns — backing up the ORIGINAL on-disk file before a
+// migration changes its data, and printing a one-time user-facing warning —
+// belong to the caller that actually owns a real file (readSession()), not
+// here. Remote data has no local file to back up; mergeSessions' own
+// never-clobber semantics are the safety net there (a degraded remote read
+// at worst contributes nothing to the merge, never destroys local data).
+
+export const SCHEMA_VERSION = 1;
+
+// Per-version migration steps, keyed by the version being migrated FROM.
+// Each step takes a state object at version N and returns one at N+1.
+// Currently empty (identity ladder) since SCHEMA_VERSION is still 1 — this
+// exists so a REAL future schema bump has a tested seam to hang a step off,
+// rather than growing an ad hoc branch inside migrateSessionData itself.
+//
+//   const MIGRATIONS = {
+//     1: (state) => ({ ...state, version: 2, /* ...transform... */ }),
+//   };
+const MIGRATIONS = {};
+
+export function emptySession() {
+  return {
+    version: SCHEMA_VERSION,
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    machines: {}, // { [machineId]: { label, last_seen } }
+    current: {
+      goals: [],         // { text, machine_id, set_on }
+      next_actions: [],  // { text, machine_id, added, completed? }
+      open_questions: [],// { text, machine_id, asked }
+      decisions: [],     // { text, why?, rejected?, hidden?, hidden_at?, machine_id, date }
+    },
+    history: [],          // { date, machine_id, summary, files_touched, duration_min? }
+  };
+}
+
+/**
+ * Normalize an already-JSON.parsed session object to SCHEMA_VERSION.
+ *
+ * Returns { future, state }:
+ *   - future: false, state: normalized object at SCHEMA_VERSION — either
+ *     walked forward through the migration ladder from an older/missing
+ *     version, or passed through unchanged (with defaults filled in for any
+ *     missing fields) if already current.
+ *   - future: true, state: a fresh, empty, valid session — returned when the
+ *     input's version is NEWER than this build's SCHEMA_VERSION (the file
+ *     came from a newer memoir install). We deliberately do not attempt to
+ *     interpret an unknown future shape; the caller decides what to do with
+ *     `future: true` (readSession() backs up the original + warns once).
+ *
+ * Never throws on malformed input — worst case, returns a fresh empty
+ * session (future: false), matching the existing "corrupted JSON" recovery
+ * behavior elsewhere in this codebase.
+ */
+export function migrateSessionData(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { future: false, state: emptySession() };
+  }
+
+  let version = typeof raw.version === 'number' && Number.isFinite(raw.version) ? raw.version : 0;
+
+  if (version > SCHEMA_VERSION) {
+    return { future: true, state: emptySession() };
+  }
+
+  let state = raw;
+  while (version < SCHEMA_VERSION) {
+    const step = MIGRATIONS[version];
+    state = step ? step(state) : { ...state, version: version + 1 };
+    version += 1;
+  }
+
+  const fresh = emptySession();
+  const normalized = {
+    ...fresh,
+    ...state,
+    version: SCHEMA_VERSION,
+    current: { ...fresh.current, ...(state?.current || {}) },
+    machines: { ...fresh.machines, ...(state?.machines || {}) },
+    history: Array.isArray(state?.history) ? state.history : [],
+  };
+
+  return { future: false, state: normalized };
+}

package/src/session/render.js

@@ -19,7 +19,13 @@ export function renderSession(state) {
   const goals = (state.current?.goals || []).slice(0, MAX_RENDERED_GOALS);
   const nexts = (state.current?.next_actions || []).slice(-MAX_RENDERED_NEXT).reverse();
   const questions = (state.current?.open_questions || []).slice(-MAX_RENDERED_QUESTIONS).reverse();
-  const decisions = (state.current?.decisions || []).slice(0, MAX_RENDERED_DECISIONS);
+  // hidden:true is a tombstone (see scripts/cleanup-junk-decisions-2026-07.mjs)
+  // — distinct from the `rejected` field (which is a live, user-facing "the
+  // alternative we considered and rejected" string). Filtered here, and in
+  // why.js's CLI search+display and its MCP memoir_why handler, so a
+  // tombstoned decision is fully suppressed rather than just hidden from one
+  // of the three places decisions are read/displayed/searched.
+  const decisions = (state.current?.decisions || []).filter(d => !d?.hidden).slice(0, MAX_RENDERED_DECISIONS);
   const history = (state.history || []).slice(0, MAX_RENDERED_HISTORY);
 
   const everythingEmpty = !goals.length && !nexts.length && !questions.length && !decisions.length && !history.length;