memoir-cli 3.10.1 → 3.11.0

package/bin/memoir.js

@@ -34,6 +34,7 @@ import {
 import { autopushCommand } from '../src/commands/autopush.js';
 import { whyCommand } from '../src/commands/why.js';
 import { autoRefreshCommand } from '../src/commands/auto-refresh.js';
+import { validateCommand } from '../src/commands/validate.js';
 import { hooksInstallCommand, hooksUninstallCommand, hooksStatusCommand } from '../src/commands/hooks.js';
 import { capture as track, telemetryCommand } from '../src/telemetry.js';
 import { createRequire } from 'module';
@@ -268,6 +269,19 @@ program
     } catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
   });
 
+program
+  .command('validate [paths...]')
+  .description('Check session state and memory entry files against the memoir format spec (docs/SPEC.md)')
+  .option('--strict', 'Treat warnings as failures')
+  .action(async (paths, options) => {
+    try {
+      await validateCommand(paths || [], options);
+    } catch (err) {
+      console.error(chalk.red('\n✖ Error:'), err.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('doctor')
   .alias('diagnose')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoir-cli",
-  "version": "3.10.1",
+  "version": "3.11.0",
   "mcpName": "io.github.camgitt/memoir",
   "description": "Private, portable AI memory: synced across every coding tool and machine, end-to-end encrypted, free. One memory for Claude Code, Cursor, Copilot, Gemini + more — MCP-native, zero-knowledge, open source.",
   "main": "src/index.js",

package/src/adapters/index.js

@@ -4,12 +4,21 @@ import path from 'path';
 import os from 'os';
 import chalk from 'chalk';
 import { shouldIgnoreProject } from '../context/capture.js';
+import { vscodeUserDir, vscodeGlobalStorage, xdgConfigDir } from '../utils/platform.js';
 
 const home = os.homedir();
 
 const isWin = process.platform === 'win32';
 const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
 
+// VS Code-family config dirs — resolved per-OS (incl. Linux) via platform.js.
+const cursorUserDir = vscodeUserDir('Cursor');
+const windsurfUserDir = vscodeUserDir('Windsurf');
+const clineStorageDir = vscodeGlobalStorage('saoudrizwan.claude-dev');
+// Non-VSCode tools that store under AppData on Windows and XDG config on POSIX.
+const copilotDir = isWin ? path.join(appData, 'GitHub Copilot') : path.join(xdgConfigDir(), 'github-copilot');
+const zedDir = isWin ? path.join(appData, 'Zed') : path.join(xdgConfigDir(), 'zed');
+
 export const adapters = [
   {
     name: 'Gemini CLI',
@@ -78,13 +87,9 @@ export const adapters = [
   {
     name: 'Cursor',
     icon: '⚡',
-    source: isWin
-      ? path.join(appData, 'Cursor', 'User')
-      : path.join(home, 'Library', 'Application Support', 'Cursor', 'User'),
+    source: cursorUserDir,
     filter: (src) => {
-      const cursorDir = isWin
-        ? path.join(appData, 'Cursor', 'User')
-        : path.join(home, 'Library', 'Application Support', 'Cursor', 'User');
+      const cursorDir = cursorUserDir;
       const rel = path.relative(cursorDir, src);
       if (src === cursorDir) return true;
       const basename = path.basename(src);
@@ -100,13 +105,8 @@ export const adapters = [
   {
     name: 'GitHub Copilot',
     icon: '🐙',
-    source: isWin
-      ? path.join(appData, 'GitHub Copilot')
-      : path.join(home, '.config', 'github-copilot'),
+    source: copilotDir,
     filter: (src) => {
-      const copilotDir = isWin
-        ? path.join(appData, 'GitHub Copilot')
-        : path.join(home, '.config', 'github-copilot');
       if (src === copilotDir) return true;
       const basename = path.basename(src);
       // Only sync config — skip auth tokens and version files
@@ -117,13 +117,9 @@ export const adapters = [
   {
     name: 'Windsurf',
     icon: '🏄',
-    source: isWin
-      ? path.join(appData, 'Windsurf', 'User')
-      : path.join(home, 'Library', 'Application Support', 'Windsurf', 'User'),
+    source: windsurfUserDir,
     filter: (src) => {
-      const windsurfDir = isWin
-        ? path.join(appData, 'Windsurf', 'User')
-        : path.join(home, 'Library', 'Application Support', 'Windsurf', 'User');
+      const windsurfDir = windsurfUserDir;
       const rel = path.relative(windsurfDir, src);
       if (src === windsurfDir) return true;
       const basename = path.basename(src);
@@ -138,13 +134,8 @@ export const adapters = [
   {
     name: 'Zed',
     icon: '🔶',
-    source: isWin
-      ? path.join(appData, 'Zed')
-      : path.join(home, '.config', 'zed'),
+    source: zedDir,
     filter: (src) => {
-      const zedDir = isWin
-        ? path.join(appData, 'Zed')
-        : path.join(home, '.config', 'zed');
       const rel = path.relative(zedDir, src);
       if (src === zedDir) return true;
       const basename = path.basename(src);
@@ -163,13 +154,9 @@ export const adapters = [
   {
     name: 'Cline',
     icon: '🤖',
-    source: isWin
-      ? path.join(appData, 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev')
-      : path.join(home, 'Library', 'Application Support', 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev'),
+    source: clineStorageDir,
     filter: (src) => {
-      const clineDir = isWin
-        ? path.join(appData, 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev')
-        : path.join(home, 'Library', 'Application Support', 'Code', 'User', 'globalStorage', 'saoudrizwan.claude-dev');
+      const clineDir = clineStorageDir;
       const rel = path.relative(clineDir, src);
       if (src === clineDir) return true;
       const basename = path.basename(src);

package/src/commands/push.js

@@ -371,6 +371,18 @@ export async function pushCommand(options = {}) {
     let shouldEncrypt = config.encrypt;
 
     if (shouldEncrypt === undefined) {
+      if (background || !process.stdin.isTTY) {
+        // First push with nobody to ask (the detached autopush hook, CI, a
+        // pipe). Any inquirer prompt here dies or hangs against ignored
+        // stdio. Encrypt if MEMOIR_PASSPHRASE makes that possible;
+        // otherwise push unencrypted THIS ONCE without persisting the
+        // choice — a backup beats no backup, and the next interactive push
+        // still gets the real question (default Yes).
+        shouldEncrypt = Boolean(process.env.MEMOIR_PASSPHRASE);
+        if (!shouldEncrypt) {
+          config.encrypt = undefined; // do not let the fallthrough persist "off"
+        }
+      } else {
       // First push since encryption was added — ask once and save preference
       spinner.stop();
       const { wantEncrypt } = await inquirer.prompt([{
@@ -380,6 +392,7 @@ export async function pushCommand(options = {}) {
         default: true
       }]);
       shouldEncrypt = wantEncrypt;
+      }
 
       // Save to config so we don't ask again
       try {
@@ -401,14 +414,19 @@ export async function pushCommand(options = {}) {
     }
 
     if (shouldEncrypt) {
-      spinner.stop();
-      const { passphrase } = await inquirer.prompt([{
-        type: 'password',
-        name: 'passphrase',
-        message: '🔒 Encryption passphrase:',
-        mask: '*',
-        validate: (input) => input.length >= 6 ? true : 'Passphrase must be at least 6 characters'
-      }]);
+      // Headless pushes can supply the passphrase via env; interactive
+      // pushes are asked as before.
+      let passphrase = process.env.MEMOIR_PASSPHRASE || '';
+      if (!passphrase || passphrase.length < 6) {
+        spinner.stop();
+        ({ passphrase } = await inquirer.prompt([{
+          type: 'password',
+          name: 'passphrase',
+          message: '🔒 Encryption passphrase:',
+          mask: '*',
+          validate: (input) => input.length >= 6 ? true : 'Passphrase must be at least 6 characters'
+        }]));
+      }
       spinner.start(chalk.gray('Deriving encryption key...'));
 
       encryptedDir = path.join(os.tmpdir(), `memoir-encrypted-${Date.now()}`);

package/src/commands/validate.js

@@ -0,0 +1,407 @@
+// `memoir validate` — structural conformance checks for the memoir format.
+//
+// docs/SPEC.md (v0.1 draft) is the normative text; schema/*.schema.json is
+// the machine-readable mirror. The checks here are hand-rolled on purpose:
+// no JSON Schema engine dependency for a format this small, and the few
+// checks that matter (required fields, date sanity, tombstone invariants)
+// stay readable as plain code.
+//
+//   memoir validate                 validate the live session.json
+//   memoir validate <file.md> ...   validate entry files
+//   memoir validate <dir>           validate every *.md under dir
+//                                   (+ its session.json, if present)
+//   memoir validate --strict        warnings count as failures
+//
+// Severity model:
+//   error   — violates a MUST in SPEC.md; the file fails.
+//   warning — violates a SHOULD, or a legacy (pre-v0.1) dialect that
+//             readers must tolerate but writers must not emit.
+// Exit code is 1 when any error occurred (or any warning, with --strict).
+
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import { paths } from '../session/state.js';
+import { SCHEMA_VERSION } from '../session/migrations.js';
+
+const ENTRY_TYPES = ['fact', 'preference', 'decision', 'lesson', 'goal', 'next_action'];
+
+// Pre-v0.1 type vocabulary (SPEC.md Appendix A) — accepted with a warning.
+const LEGACY_TYPES = {
+  user: 'preference',
+  feedback: 'lesson',
+  reference: 'fact',
+  project: null, // dossier — no atomic mapping; read as opaque legacy entry
+};
+
+// Frontmatter date-ish fields, checked for ISO 8601 shape when present.
+const DATE_FIELDS = ['created', 'updated', 'date', 'set_on', 'added', 'done_at', 'hidden_at', 'last_fired'];
+
+// ── Frontmatter parsing (restricted YAML subset per SPEC.md 3.1) ──
+//
+// Supports: scalar `key: value`, one level of nested mapping, and simple
+// `- item` string lists. That is all the format allows in frontmatter, so
+// that is all this parses. Not a general YAML parser and not meant to be.
+
+function parseScalar(raw) {
+  let v = String(raw).trim();
+  if (
+    (v.startsWith('"') && v.endsWith('"') && v.length >= 2) ||
+    (v.startsWith("'") && v.endsWith("'") && v.length >= 2)
+  ) {
+    v = v.slice(1, -1);
+  }
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (/^-?\d+$/.test(v)) return parseInt(v, 10);
+  return v;
+}
+
+export function parseFrontmatter(raw) {
+  const lines = String(raw).split(/\r?\n/);
+  if ((lines[0] || '').trim() !== '---') {
+    return { present: false, fields: {}, body: raw, error: null };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    return { present: true, fields: {}, body: raw, error: 'unterminated frontmatter (no closing ---)' };
+  }
+
+  const fields = {};
+  let openKey = null; // most recent top-level key whose value may nest
+  for (let i = 1; i < end; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    if (/^\s/.test(line) && openKey) {
+      // One level of nesting under openKey: nested map entry or list item.
+      if (trimmed.startsWith('- ')) {
+        if (!Array.isArray(fields[openKey])) fields[openKey] = [];
+        fields[openKey].push(parseScalar(trimmed.slice(2)));
+      } else {
+        const m = trimmed.match(/^([^:]+):\s*(.*)$/);
+        if (m) {
+          if (typeof fields[openKey] !== 'object' || fields[openKey] === null || Array.isArray(fields[openKey])) {
+            fields[openKey] = {};
+          }
+          fields[openKey][m[1].trim()] = parseScalar(m[2]);
+        }
+      }
+      continue;
+    }
+
+    const m = line.match(/^([^:\s][^:]*):\s*(.*)$/);
+    if (!m) continue; // tolerate lines we don't understand — validation reports, not parsing, is the job
+    const key = m[1].trim();
+    if (m[2] === '') {
+      openKey = key;
+      fields[key] = '';
+    } else {
+      openKey = null;
+      fields[key] = parseScalar(m[2]);
+    }
+  }
+
+  return { present: true, fields, body: lines.slice(end + 1).join('\n'), error: null };
+}
+
+// ── Shared checks ────────────────────────────────────────────────
+
+function isIsoDateString(v) {
+  return typeof v === 'string' && /^\d{4}-\d{2}-\d{2}/.test(v) && !Number.isNaN(new Date(v).getTime());
+}
+
+// ── Entry file validation (SPEC.md section 3, entry.schema.json) ──
+
+export function validateEntry(raw) {
+  const errors = [];
+  const warnings = [];
+  const { present, fields, body, error } = parseFrontmatter(raw);
+
+  if (!present) {
+    warnings.push('no frontmatter — legacy bare-markdown entry (SPEC.md Appendix A); readers treat as opaque, writers must not emit this');
+    return { errors, warnings };
+  }
+  if (error) {
+    errors.push(error);
+    return { errors, warnings };
+  }
+
+  // Resolve type across dialects: canonical top-level `type`, legacy `metadata.type`.
+  let type = fields.type;
+  if (type == null && fields.metadata && typeof fields.metadata === 'object' && fields.metadata.type != null) {
+    type = fields.metadata.type;
+    warnings.push('legacy dialect: type nested under metadata (canonical: top-level `type`)');
+  }
+
+  if (!fields.name || typeof fields.name !== 'string' || !String(fields.name).trim()) {
+    errors.push('missing required field: name');
+  }
+  if (!fields.description) {
+    warnings.push('missing description (SHOULD) — entry is invisible in indexes and pickers');
+  }
+
+  if (type == null) {
+    errors.push(`missing required field: type (one of: ${ENTRY_TYPES.join(', ')})`);
+  } else if (ENTRY_TYPES.includes(type)) {
+    validateCanonicalType(type, fields, body, errors, warnings);
+  } else if (type in LEGACY_TYPES) {
+    const mapped = LEGACY_TYPES[type];
+    warnings.push(`legacy type "${type}"${mapped ? ` (reads as ${mapped})` : ' (dossier — no atomic mapping)'} — canonical types: ${ENTRY_TYPES.join(', ')}`);
+    if (type === 'feedback' && !/\*\*How to apply:?\*\*/i.test(body)) {
+      warnings.push('legacy feedback entry without a **How to apply:** body section — lesson has no application rule');
+    }
+  } else {
+    errors.push(`unknown type "${type}" — canonical: ${ENTRY_TYPES.join(', ')}; legacy (read-only): ${Object.keys(LEGACY_TYPES).join(', ')}`);
+  }
+
+  for (const f of DATE_FIELDS) {
+    if (fields[f] != null && !isIsoDateString(fields[f])) {
+      errors.push(`field ${f} is not an ISO 8601 date: ${JSON.stringify(fields[f])}`);
+    }
+  }
+  if (fields.schema_version != null && (!Number.isInteger(fields.schema_version) || fields.schema_version < 1)) {
+    errors.push(`schema_version must be a positive integer, got ${JSON.stringify(fields.schema_version)}`);
+  }
+  if (Number.isInteger(fields.schema_version) && fields.schema_version > 1) {
+    warnings.push(`schema_version ${fields.schema_version} is newer than this build understands (v1) — forward-version rule applies: quarantine + degrade, never guess (SPEC.md section 6)`);
+  }
+
+  return { errors, warnings };
+}
+
+function validateCanonicalType(type, fields, body, errors, warnings) {
+  if (type === 'decision') {
+    if (!fields.why) warnings.push('decision without a why (required-encouraged) — a decision without a why is half a decision');
+    if (!fields.rejected) warnings.push('decision without a rejected alternative (required-encouraged)');
+    if (fields.hidden === true && !fields.hidden_at) {
+      errors.push('hidden: true without hidden_at — tombstones must carry when they were set (SPEC.md 5.3.1)');
+    }
+  } else if (type === 'lesson') {
+    if (!fields.trigger) {
+      errors.push('lesson missing required field: trigger — when does this lesson apply?');
+    }
+    if (!fields.how_to_apply) {
+      if (/\*\*How to apply:?\*\*/i.test(body)) {
+        warnings.push('how_to_apply lives in the body (**How to apply:** section) — accepted for legacy entries; canonical form is the frontmatter key');
+      } else {
+        errors.push('lesson missing required field: how_to_apply — without an application rule it is an anecdote, not a lesson');
+      }
+    }
+    if (fields.fired_count != null && (!Number.isInteger(fields.fired_count) || fields.fired_count < 0)) {
+      errors.push(`fired_count must be a non-negative integer, got ${JSON.stringify(fields.fired_count)}`);
+    }
+  } else if (type === 'next_action') {
+    if (!fields.added) {
+      errors.push('next_action missing required field: added — completion semantics (done_at vs added) are undefined without it');
+    }
+    if (isIsoDateString(fields.added) && isIsoDateString(fields.done_at) && new Date(fields.done_at) < new Date(fields.added)) {
+      warnings.push('done_at is earlier than added — this action was completed before it existed');
+    }
+  } else if (type === 'preference') {
+    if (fields.scope != null && !['global', 'project'].includes(fields.scope)) {
+      warnings.push(`preference scope should be "global" or "project", got ${JSON.stringify(fields.scope)}`);
+    }
+  }
+  // fact, goal: no extra required fields.
+}
+
+// ── Session file validation (SPEC.md section 4, session.schema.json) ──
+
+function checkListItems(list, listName, dateField, errors, warnings) {
+  if (!Array.isArray(list)) {
+    errors.push(`current.${listName} must be an array`);
+    return;
+  }
+  list.forEach((item, i) => {
+    const at = `current.${listName}[${i}]`;
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      errors.push(`${at} must be an object`);
+      return;
+    }
+    if (typeof item.text !== 'string' || !item.text.trim()) {
+      errors.push(`${at} missing required field: text (the merge identity key)`);
+    }
+    if (item[dateField] != null && !isIsoDateString(item[dateField])) {
+      errors.push(`${at}.${dateField} is not an ISO 8601 date-time: ${JSON.stringify(item[dateField])}`);
+    }
+    if (item[dateField] == null) {
+      warnings.push(`${at} missing ${dateField} — merges treat a missing date as the epoch (always loses newest-wins)`);
+    }
+  });
+}
+
+export function validateSessionObject(obj) {
+  const errors = [];
+  const warnings = [];
+
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    errors.push('session must be a JSON object');
+    return { errors, warnings };
+  }
+
+  if (!Number.isInteger(obj.version) || obj.version < 1) {
+    errors.push(`version must be a positive integer, got ${JSON.stringify(obj.version)}`);
+  } else if (obj.version > SCHEMA_VERSION) {
+    warnings.push(`version ${obj.version} is newer than this build understands (v${SCHEMA_VERSION}) — forward-version rule applies: quarantine + degrade, never guess (SPEC.md section 6)`);
+  }
+
+  for (const f of ['created_at', 'updated_at']) {
+    if (obj[f] == null) errors.push(`missing required field: ${f}`);
+    else if (!isIsoDateString(obj[f])) errors.push(`${f} is not an ISO 8601 date-time: ${JSON.stringify(obj[f])}`);
+  }
+
+  if (!obj.machines || typeof obj.machines !== 'object' || Array.isArray(obj.machines)) {
+    errors.push('missing required field: machines (object of machine-uuid -> { label, last_seen })');
+  } else {
+    for (const [id, m] of Object.entries(obj.machines)) {
+      if (!m || typeof m !== 'object') { errors.push(`machines["${id}"] must be an object`); continue; }
+      if (typeof m.label !== 'string') errors.push(`machines["${id}"] missing required field: label`);
+      if (!isIsoDateString(m.last_seen)) errors.push(`machines["${id}"].last_seen is not an ISO 8601 date-time`);
+    }
+  }
+
+  const cur = obj.current;
+  if (!cur || typeof cur !== 'object' || Array.isArray(cur)) {
+    errors.push('missing required field: current');
+  } else {
+    checkListItems(cur.goals, 'goals', 'set_on', errors, warnings);
+    checkListItems(cur.next_actions, 'next_actions', 'added', errors, warnings);
+    checkListItems(cur.open_questions, 'open_questions', 'asked', errors, warnings);
+    checkListItems(cur.decisions, 'decisions', 'date', errors, warnings);
+    (Array.isArray(cur.decisions) ? cur.decisions : []).forEach((d, i) => {
+      if (d && d.hidden === true && !isIsoDateString(d.hidden_at)) {
+        errors.push(`current.decisions[${i}] hidden: true without a valid hidden_at (SPEC.md 5.3.1)`);
+      }
+    });
+    // completed_actions is optional (absent = empty), but when present its
+    // tombstones must be well-formed or the temporal merge rule breaks.
+    if (cur.completed_actions != null) {
+      if (!Array.isArray(cur.completed_actions)) {
+        errors.push('current.completed_actions must be an array when present');
+      } else {
+        cur.completed_actions.forEach((t, i) => {
+          const at = `current.completed_actions[${i}]`;
+          if (!t || typeof t !== 'object') { errors.push(`${at} must be an object`); return; }
+          if (typeof t.text !== 'string' || !t.text.trim()) errors.push(`${at} missing required field: text`);
+          if (!isIsoDateString(t.done_at)) errors.push(`${at} missing/invalid required field: done_at (the tombstone is meaningless without it)`);
+        });
+      }
+    }
+  }
+
+  if (!Array.isArray(obj.history)) {
+    errors.push('missing required field: history (array)');
+  } else {
+    obj.history.forEach((h, i) => {
+      if (!h || typeof h !== 'object') { errors.push(`history[${i}] must be an object`); return; }
+      if (!isIsoDateString(h.date)) errors.push(`history[${i}] missing/invalid required field: date`);
+      if (h.files_touched != null && !Array.isArray(h.files_touched)) errors.push(`history[${i}].files_touched must be an array`);
+      if (h.duration_min != null && typeof h.duration_min !== 'number') errors.push(`history[${i}].duration_min must be a number or null`);
+    });
+  }
+
+  return { errors, warnings };
+}
+
+// ── File collection ──────────────────────────────────────────────
+
+async function collectTargets(args) {
+  // Returns [{ path, kind: 'entry' | 'session' }]. No args: the live session.json.
+  if (!args.length) {
+    return [{ path: paths.session, kind: 'session' }];
+  }
+  const targets = [];
+  for (const arg of args) {
+    const p = path.resolve(arg);
+    let stat;
+    try { stat = await fs.stat(p); }
+    catch { targets.push({ path: p, kind: 'missing' }); continue; }
+    if (stat.isDirectory()) {
+      const sessionPath = path.join(p, 'session.json');
+      if (await fs.pathExists(sessionPath)) targets.push({ path: sessionPath, kind: 'session' });
+      const stack = [p];
+      while (stack.length) {
+        const dir = stack.pop();
+        let entries = [];
+        try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { continue; }
+        for (const e of entries) {
+          if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+          const full = path.join(dir, e.name);
+          if (e.isDirectory()) stack.push(full);
+          else if (e.name.endsWith('.md')) targets.push({ path: full, kind: 'entry' });
+        }
+      }
+    } else if (p.endsWith('.json')) {
+      targets.push({ path: p, kind: 'session' });
+    } else {
+      targets.push({ path: p, kind: 'entry' });
+    }
+  }
+  return targets;
+}
+
+// ── Command ──────────────────────────────────────────────────────
+
+export async function validateCommand(args = [], options = {}) {
+  const targets = await collectTargets(args);
+
+  console.log('\n' + chalk.bold.white('  memoir validate') + chalk.gray(' — format v0.1 draft (docs/SPEC.md)') + '\n');
+
+  let checked = 0;
+  let failed = 0;
+  let totalWarnings = 0;
+
+  for (const target of targets) {
+    const rel = target.path.startsWith(process.cwd()) ? path.relative(process.cwd(), target.path) : target.path;
+
+    if (target.kind === 'missing') {
+      failed++;
+      console.log(chalk.red('  ✖ ') + chalk.white(rel));
+      console.log(chalk.red('      error    ') + 'file not found');
+      continue;
+    }
+
+    checked++;
+    let result;
+    if (target.kind === 'session') {
+      let parsed;
+      try {
+        parsed = JSON.parse(await fs.readFile(target.path, 'utf8'));
+      } catch (err) {
+        result = { errors: [`unparseable JSON: ${err.message}`], warnings: [] };
+      }
+      if (!result) result = validateSessionObject(parsed);
+    } else {
+      let raw;
+      try {
+        raw = await fs.readFile(target.path, 'utf8');
+      } catch (err) {
+        result = { errors: [`unreadable: ${err.message}`], warnings: [] };
+      }
+      if (!result) result = validateEntry(raw);
+    }
+
+    const { errors, warnings } = result;
+    totalWarnings += warnings.length;
+    const fails = errors.length > 0 || (options.strict && warnings.length > 0);
+    if (fails) failed++;
+
+    const mark = fails ? chalk.red('  ✖ ') : warnings.length ? chalk.yellow('  ⚠ ') : chalk.green('  ✔ ');
+    console.log(mark + chalk.white(rel));
+    for (const e of errors) console.log(chalk.red('      error    ') + e);
+    for (const w of warnings) console.log(chalk.yellow('      warning  ') + w);
+  }
+
+  const parts = [`${checked} file${checked !== 1 ? 's' : ''} checked`];
+  parts.push(failed > 0 ? chalk.red(`${failed} failed`) : chalk.green('all passed'));
+  if (totalWarnings > 0) parts.push(chalk.yellow(`${totalWarnings} warning${totalWarnings !== 1 ? 's' : ''}`));
+  console.log('\n  ' + parts.join(chalk.gray(' · ')) + '\n');
+
+  if (failed > 0) process.exitCode = 1;
+  return { checked, failed, warnings: totalWarnings };
+}

package/src/session/state.js

@@ -33,6 +33,9 @@ export { SCHEMA_VERSION, emptySession };
 // Prevents unbounded growth of the live pinned block.
 const MAX_GOALS = 3;
 const MAX_NEXT = 8;
+// Completion tombstones kept so merges can't resurrect finished actions.
+// Must outlive every stale copy that might still carry the item.
+const MAX_COMPLETED_TOMBSTONES = 50;
 const MAX_QUESTIONS = 5;
 const MAX_DECISIONS_RECENT = 10;
 const MAX_HISTORY = 30;
@@ -225,7 +228,20 @@ export async function completeNext(textOrIndex) {
     }
     const completed = idx >= 0;
     if (completed) {
-      state.current.next_actions.splice(idx, 1);
+      // Removal alone is not enough: any merge with a copy that still holds
+      // this item (the push-side backup, another machine, a stale MCP-process
+      // write) re-unions it straight back — the "completed actions resurrect"
+      // bug. So completion also records a tombstone that merges consult.
+      // Temporal, not absolute like decisions' `hidden`: a re-add whose
+      // `added` postdates `done_at` is a deliberate revival and survives.
+      const [removed] = state.current.next_actions.splice(idx, 1);
+      const key = removed.text.trim().toLowerCase();
+      state.current.completed_actions = [
+        { text: removed.text, done_at: new Date().toISOString() },
+        ...(state.current.completed_actions || []).filter(
+          c => c && c.text && c.text.trim().toLowerCase() !== key
+        ),
+      ].slice(0, MAX_COMPLETED_TOMBSTONES);
     }
     await writeSession(state);
     // Only when something was actually completed — the event should mean
@@ -312,6 +328,25 @@ export function mergeSessions(local, remote) {
     history: mergeHistory(local.history, remote.history),
   };
 
+  // Completed-action tombstones beat the union above. unionByText can only
+  // union; it cannot represent "this used to exist and was finished," so a
+  // completed item surviving in ANY stale copy resurrected on every merge —
+  // the intermittent completeNext no-op observed in production (2026-08-03).
+  // Temporal on purpose: an item re-ADDED after its done_at is a deliberate
+  // revival and must survive, so tombstones only suppress copies whose
+  // `added` predates the completion.
+  const tombstones = unionTombstones(
+    local.current?.completed_actions,
+    remote.current?.completed_actions
+  );
+  merged.current.completed_actions = tombstones;
+  merged.current.next_actions = merged.current.next_actions.filter(a => {
+    const t = tombstones.find(
+      c => c.text.trim().toLowerCase() === a.text.trim().toLowerCase()
+    );
+    return !t || new Date(a.added || 0) > new Date(t.done_at);
+  });
+
   // machines: union last_seen per id (take the newer)
   for (const [id, entry] of Object.entries(remote.machines || {})) {
     const existing = merged.machines[id];
@@ -359,6 +394,21 @@ function unionByText(a = [], b = [], dateField, cap) {
     .slice(0, cap);
 }
 
+function unionTombstones(a = [], b = []) {
+  const byText = new Map();
+  for (const item of [...(a || []), ...(b || [])]) {
+    if (!item || !item.text || !item.done_at) continue;
+    const key = item.text.trim().toLowerCase();
+    const existing = byText.get(key);
+    if (!existing || new Date(item.done_at) > new Date(existing.done_at)) {
+      byText.set(key, item);
+    }
+  }
+  return Array.from(byText.values())
+    .sort((x, y) => new Date(y.done_at) - new Date(x.done_at))
+    .slice(0, MAX_COMPLETED_TOMBSTONES);
+}
+
 function mergeHistory(a = [], b = []) {
   const seen = new Set();
   const all = [...a, ...b].filter(h => h && h.date);

package/src/utils/platform.js

@@ -0,0 +1,47 @@
+// Single source of truth for OS-specific config locations.
+//
+// Why this exists: before this module, every adapter branched on a single
+// `isWin` flag — `isWin ? <windows> : <macOS>`. On Linux, `process.platform`
+// is `'linux'`, so those ternaries silently fell through to the *macOS* path
+// (`~/Library/Application Support/...`), which doesn't exist on Linux. memoir
+// would then detect zero tools, sync nothing, and the user would churn without
+// any error — the "silent-zero-memory activation cliff."
+//
+// Every function is parameterized by { platform, env, home } so the three OS
+// branches can be unit-tested from any machine, not just the target OS. Runtime
+// callers omit the options and get the live platform.
+
+import path from 'node:path';
+import os from 'node:os';
+
+const HOME = os.homedir();
+
+// VS Code-family per-user config base: <root>/<App>/User
+//   win32  : %APPDATA%/<App>/User
+//   darwin : ~/Library/Application Support/<App>/User
+//   linux  : $XDG_CONFIG_HOME (or ~/.config)/<App>/User
+export function vscodeUserDir(appName, { platform = process.platform, env = process.env, home = HOME } = {}) {
+  if (platform === 'win32') {
+    const appData = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    return path.join(appData, appName, 'User');
+  }
+  if (platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', appName, 'User');
+  }
+  // linux + anything else POSIX-y
+  const xdg = env.XDG_CONFIG_HOME || path.join(home, '.config');
+  return path.join(xdg, appName, 'User');
+}
+
+// A VS Code extension's globalStorage dir (e.g. Cline lives under the base
+// "Code" install, not its own app dir).
+export function vscodeGlobalStorage(extId, opts = {}) {
+  return path.join(vscodeUserDir('Code', opts), 'globalStorage', extId);
+}
+
+// XDG-aware ~/.config base, for non-VSCode tools that already store there
+// (zed, github-copilot). Exposed so callers don't re-hardcode ~/.config and
+// drift from XDG_CONFIG_HOME.
+export function xdgConfigDir({ env = process.env, home = HOME } = {}) {
+  return env.XDG_CONFIG_HOME || path.join(home, '.config');
+}