memoir-cli 3.9.0 → 3.10.0

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;

package/src/session/state.js

@@ -9,13 +9,25 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
+import { withSessionLock } from './lock.js';
+import { SCHEMA_VERSION, migrateSessionData, emptySession } from './migrations.js';
+// NOTE: events/log.js imports getMachineId FROM this module — this is a
+// circular import, safe here because both appendEvent (used below) and
+// getMachineId (used by events/log.js) are hoisted function declarations
+// used only inside other functions' bodies, never at module-evaluation
+// time. Verified working; see test-event-log.mjs.
+import { appendEvent } from '../events/log.js';
 
 const home = os.homedir();
 const CONFIG_DIR = path.join(home, '.config', 'memoir');
 const SESSION_PATH = path.join(CONFIG_DIR, 'session.json');
 const MACHINE_ID_PATH = path.join(CONFIG_DIR, 'machine.id');
+const SESSION_LOCK_PATH = path.join(CONFIG_DIR, 'session.json.lock');
 
-export const SCHEMA_VERSION = 1;
+// Re-exported for external consumers (e.g. test-session.mjs asserts against
+// state.SCHEMA_VERSION) — the canonical constant now lives in migrations.js
+// alongside the migration ladder it governs.
+export { SCHEMA_VERSION, emptySession };
 
 // Maximum items kept in each list before oldest entries rotate into history.
 // Prevents unbounded growth of the live pinned block.
@@ -44,66 +56,107 @@ export async function getMachineId() {
   return { id, label: os.hostname() };
 }
 
-// ── Schema ───────────────────────────────────────────────────────
-
-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?, machine_id, date }
-    },
-    history: [],         // { date, machine_id, summary, files_touched, duration_min? }
-  };
-}
-
 // ── Read / write ─────────────────────────────────────────────────
+//
+// Forward-version guard: if session.json's version is NEWER than this
+// build's SCHEMA_VERSION (the file came from a newer memoir install — e.g.
+// another machine upgraded first and this one hasn't yet), readSession()
+// backs up the original file (mirroring the corrupted-JSON quarantine
+// pattern below) and returns a safe, empty-but-valid session instead of
+// misinterpreting an unknown shape. This is centralized HERE, not in
+// individual callers, so all ~20 call sites across mcp.js (8 MCP tool
+// handlers), commands/session.js, commands/why.js, commands/auto-refresh.js,
+// commands/push.js, commands/restore.js automatically get safe behavior
+// with zero changes required at each call site — and critically, no MCP
+// tool call is ever allowed to throw/crash because of a schema mismatch.
+let warnedForwardVersion = false; // print the upgrade warning once per process, not once per call
+
+// Opportunistic cleanup so the .corrupted-<ts> / .pre-migration-<ts> backup
+// patterns don't accumulate forever on a machine that repeatedly hits
+// either quarantine path. Keeps the N most recent of EACH pattern, deletes
+// older ones. Best-effort — a cleanup failure never blocks the caller.
+const MAX_BACKUPS_PER_PATTERN = 3;
+function cleanupOldBackups(suffixPrefix) {
+  try {
+    const dir = path.dirname(SESSION_PATH);
+    const base = path.basename(SESSION_PATH); // "session.json"
+    const marker = `${base}.${suffixPrefix}-`;
+    const matches = fs.readdirSync(dir)
+      .filter((f) => f.startsWith(marker))
+      .map((f) => {
+        let mtime = 0;
+        try { mtime = fs.statSync(path.join(dir, f)).mtimeMs; } catch {}
+        return { name: f, mtime };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+    for (const f of matches.slice(MAX_BACKUPS_PER_PATTERN)) {
+      try { fs.unlinkSync(path.join(dir, f.name)); } catch {}
+    }
+  } catch {
+    // Best-effort — never block the caller.
+  }
+}
 
-// Atomic read with graceful recovery from corrupted JSON.
+// Atomic read with graceful recovery from corrupted JSON AND from a
+// too-new schema version.
 export async function readSession() {
   if (!await fs.pathExists(SESSION_PATH)) return emptySession();
 
+  let raw;
   try {
-    const raw = await fs.readFile(SESSION_PATH, 'utf8');
-    const parsed = JSON.parse(raw);
-    return migrateIfNeeded(parsed);
-  } catch (err) {
+    raw = await fs.readFile(SESSION_PATH, 'utf8');
+  } catch {
+    // Unreadable (permissions, race with a concurrent delete, etc.) —
+    // degrade to a safe empty session rather than throwing.
+    return emptySession();
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
     // Corrupted — preserve it for inspection, start fresh.
     const backup = `${SESSION_PATH}.corrupted-${Date.now()}`;
     try { await fs.copy(SESSION_PATH, backup); } catch {}
+    cleanupOldBackups('corrupted');
     return emptySession();
   }
+
+  const { future, state } = migrateSessionData(parsed);
+
+  if (future) {
+    const backup = `${SESSION_PATH}.pre-migration-${Date.now()}`;
+    try { await fs.copy(SESSION_PATH, backup); } catch {}
+    cleanupOldBackups('pre-migration');
+    if (!warnedForwardVersion) {
+      warnedForwardVersion = true;
+      try {
+        process.stderr.write(
+          `memoir: session.json is from a newer version of memoir than this install understands ` +
+          `(schema v${parsed?.version} > v${SCHEMA_VERSION}). It has been backed up to ${backup}. ` +
+          `Run: npm i -g memoir-cli@latest\n`
+        );
+      } catch {}
+    }
+  }
+
+  return state;
 }
 
 // Atomic write: write to tmp, rename. Prevents torn writes on crash.
+// Unconditionally stamps version — every write lands at the CURRENT
+// SCHEMA_VERSION, since it always passed through readSession/migrateSessionData
+// (or emptySession()) to get here. Always called from within a locked
+// critical section (see the mutators below and lock.js).
 export async function writeSession(state) {
   await fs.ensureDir(CONFIG_DIR);
+  state.version = SCHEMA_VERSION;
   state.updated_at = new Date().toISOString();
   const tmp = `${SESSION_PATH}.tmp-${process.pid}`;
   await fs.writeFile(tmp, JSON.stringify(state, null, 2));
   await fs.move(tmp, SESSION_PATH, { overwrite: true });
 }
 
-function migrateIfNeeded(state) {
-  if (state && state.version === SCHEMA_VERSION) return state;
-  // Future versions: add migration steps here.
-  // For now, if version mismatch, merge defaults to fill gaps.
-  const fresh = emptySession();
-  return {
-    ...fresh,
-    ...state,
-    version: SCHEMA_VERSION,
-    current: { ...fresh.current, ...(state?.current || {}) },
-    machines: { ...fresh.machines, ...(state?.machines || {}) },
-    history: Array.isArray(state?.history) ? state.history : [],
-  };
-}
-
 // ── Machine registration ────────────────────────────────────────
 
 async function touchMachine(state) {
@@ -117,98 +170,123 @@ async function touchMachine(state) {
 
 // ── Mutators ────────────────────────────────────────────────────
 
+// Every mutator below wraps its ENTIRE read -> mutate -> write cycle in
+// withSessionLock — not just the write. Locking only the write would still
+// allow two processes to both read the same stale snapshot before either
+// writes; the read must be inside the lock too so the second process reads
+// the FIRST process's already-written change rather than a stale copy.
+
 export async function addGoal(text) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  state.current.goals.unshift({
-    text,
-    machine_id: machineId,
-    set_on: new Date().toISOString(),
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    state.current.goals.unshift({
+      text,
+      machine_id: machineId,
+      set_on: new Date().toISOString(),
+    });
+    state.current.goals = state.current.goals.slice(0, MAX_GOALS);
+    await writeSession(state);
+    await appendEvent('goal_set', {}); // no PII/content — count-and-type only
+    return state;
   });
-  state.current.goals = state.current.goals.slice(0, MAX_GOALS);
-  await writeSession(state);
-  return state;
 }
 
 export async function addNext(text) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  // Dedupe by text (case-insensitive)
-  const normalized = text.trim().toLowerCase();
-  const exists = state.current.next_actions.some(a => a.text.trim().toLowerCase() === normalized);
-  if (!exists) {
-    state.current.next_actions.push({
-      text,
-      machine_id: machineId,
-      added: new Date().toISOString(),
-    });
-    state.current.next_actions = state.current.next_actions.slice(-MAX_NEXT);
-  }
-  await writeSession(state);
-  return state;
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    // Dedupe by text (case-insensitive)
+    const normalized = text.trim().toLowerCase();
+    const exists = state.current.next_actions.some(a => a.text.trim().toLowerCase() === normalized);
+    if (!exists) {
+      state.current.next_actions.push({
+        text,
+        machine_id: machineId,
+        added: new Date().toISOString(),
+      });
+      state.current.next_actions = state.current.next_actions.slice(-MAX_NEXT);
+    }
+    await writeSession(state);
+    return state;
+  });
 }
 
 export async function completeNext(textOrIndex) {
-  const state = await readSession();
-  await touchMachine(state);
-  let idx = -1;
-  if (typeof textOrIndex === 'number') {
-    idx = textOrIndex;
-  } else {
-    const normalized = String(textOrIndex).trim().toLowerCase();
-    idx = state.current.next_actions.findIndex(a => a.text.trim().toLowerCase().includes(normalized));
-  }
-  if (idx >= 0) {
-    state.current.next_actions.splice(idx, 1);
-  }
-  await writeSession(state);
-  return state;
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    await touchMachine(state);
+    let idx = -1;
+    if (typeof textOrIndex === 'number') {
+      idx = textOrIndex;
+    } else {
+      const normalized = String(textOrIndex).trim().toLowerCase();
+      idx = state.current.next_actions.findIndex(a => a.text.trim().toLowerCase().includes(normalized));
+    }
+    const completed = idx >= 0;
+    if (completed) {
+      state.current.next_actions.splice(idx, 1);
+    }
+    await writeSession(state);
+    // Only when something was actually completed — the event should mean
+    // "something happened," not "this function was called with no match."
+    if (completed) await appendEvent('next_completed', {});
+    return state;
+  });
 }
 
 export async function addNote(text, opts = {}) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  const decision = {
-    text,
-    machine_id: machineId,
-    date: new Date().toISOString(),
-  };
-  if (opts.why) decision.why = opts.why;
-  if (opts.rejected) decision.rejected = opts.rejected;
-  state.current.decisions.unshift(decision);
-  state.current.decisions = state.current.decisions.slice(0, MAX_DECISIONS_RECENT);
-  await writeSession(state);
-  return state;
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    const decision = {
+      text,
+      machine_id: machineId,
+      date: new Date().toISOString(),
+    };
+    if (opts.why) decision.why = opts.why;
+    if (opts.rejected) decision.rejected = opts.rejected;
+    state.current.decisions.unshift(decision);
+    state.current.decisions = state.current.decisions.slice(0, MAX_DECISIONS_RECENT);
+    await writeSession(state);
+    // Count/booleans only — never the decision text itself.
+    await appendEvent('decision_captured', { has_why: !!opts.why, has_rejected: !!opts.rejected });
+    return state;
+  });
 }
 
 export async function addQuestion(text) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  state.current.open_questions.push({
-    text,
-    machine_id: machineId,
-    asked: new Date().toISOString(),
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    state.current.open_questions.push({
+      text,
+      machine_id: machineId,
+      asked: new Date().toISOString(),
+    });
+    state.current.open_questions = state.current.open_questions.slice(-MAX_QUESTIONS);
+    await writeSession(state);
+    return state;
   });
-  state.current.open_questions = state.current.open_questions.slice(-MAX_QUESTIONS);
-  await writeSession(state);
-  return state;
 }
 
 // Roll up the current state into a history entry. Use at session end / push.
 // Does not clear `current` — these are "the working set," not per-session scratch.
 export async function recordSessionEnd({ summary, filesTouched = [], durationMin = null } = {}) {
-  const state = await readSession();
-  const machineId = await touchMachine(state);
-  state.history.unshift({
-    date: new Date().toISOString(),
-    machine_id: machineId,
-    summary: summary || '',
-    files_touched: filesTouched.slice(0, 20),
-    duration_min: durationMin,
+  return withSessionLock(SESSION_LOCK_PATH, async () => {
+    const state = await readSession();
+    const machineId = await touchMachine(state);
+    state.history.unshift({
+      date: new Date().toISOString(),
+      machine_id: machineId,
+      summary: summary || '',
+      files_touched: filesTouched.slice(0, 20),
+      duration_min: durationMin,
+    });
+    state.history = state.history.slice(0, MAX_HISTORY);
+    await writeSession(state);
+    return state;
   });
-  state.history = state.history.slice(0, MAX_HISTORY);
-  await writeSession(state);
-  return state;
 }
 
 // ── Cross-machine merge ─────────────────────────────────────────
@@ -293,4 +371,5 @@ export const paths = {
   config: CONFIG_DIR,
   session: SESSION_PATH,
   machineId: MACHINE_ID_PATH,
+  sessionLock: SESSION_LOCK_PATH,
 };