memoir-cli 3.9.0 → 3.10.1

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;