claude-mem-lite 2.34.0 → 2.34.2

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "2.34.0",
+      "version": "2.34.2",
       "source": "./",
       "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.34.0",
+  "version": "2.34.2",
   "description": "Lightweight persistent memory system for Claude Code — FTS5 search, episode batching, error-triggered recall",
   "author": {
     "name": "sdsrss"

package/hook.mjs

@@ -417,27 +417,35 @@ async function handleStop() {
       try { buildAndSaveHandoff(db, sessionId, project, 'exit', episodeSnapshot, ccSessionId || sessionId); }
       catch (e) { debugCatch(e, 'handleStop-handoff'); }
 
-      // Fast summary baseline — ensures summary exists even if background LLM fails
+      // Fast summary baseline — ensures summary exists even if background LLM fails.
+      // T4-P2-B: guard against Stop firing twice for the same session (rare but possible;
+      // mirrors handleSessionStart line 795 hasSummary guard). Uses mem-internal sessionId
+      // as the WHERE key per the top-of-file dual-id invariant (#7789).
       try {
-        const firstPrompt = db.prepare(`
-          SELECT prompt_text FROM user_prompts
-          WHERE content_session_id = ?
-          ORDER BY prompt_number ASC LIMIT 1
-        `).get(sessionId);
-        const recentObs = db.prepare(`
-          SELECT title FROM observations
-          WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0
-          ORDER BY created_at_epoch DESC LIMIT 5
-        `).all(sessionId);
-        const fastRequest = truncate(firstPrompt?.prompt_text || '', 200);
-        const fastCompleted = recentObs.map(o => o.title).filter(Boolean).join('; ');
-        if (fastRequest || fastCompleted) {
-          const now = new Date();
-          db.prepare(`
-            INSERT INTO session_summaries
-            (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, created_at, created_at_epoch)
-            VALUES (?, ?, ?, '', '', ?, '', '', '[]', '[]', 'fast', ?, ?)
-          `).run(sessionId, project, fastRequest, truncate(fastCompleted, 300), now.toISOString(), now.getTime());
+        const existingSummary = db.prepare(
+          'SELECT 1 FROM session_summaries WHERE memory_session_id = ? LIMIT 1'
+        ).get(sessionId);
+        if (!existingSummary) {
+          const firstPrompt = db.prepare(`
+            SELECT prompt_text FROM user_prompts
+            WHERE content_session_id = ?
+            ORDER BY prompt_number ASC LIMIT 1
+          `).get(sessionId);
+          const recentObs = db.prepare(`
+            SELECT title FROM observations
+            WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0
+            ORDER BY created_at_epoch DESC LIMIT 5
+          `).all(sessionId);
+          const fastRequest = truncate(firstPrompt?.prompt_text || '', 200);
+          const fastCompleted = recentObs.map(o => o.title).filter(Boolean).join('; ');
+          if (fastRequest || fastCompleted) {
+            const now = new Date();
+            db.prepare(`
+              INSERT INTO session_summaries
+              (memory_session_id, project, request, investigated, learned, completed, next_steps, remaining_items, files_read, files_edited, notes, created_at, created_at_epoch)
+              VALUES (?, ?, ?, '', '', ?, '', '', '[]', '[]', 'fast', ?, ?)
+            `).run(sessionId, project, fastRequest, truncate(fastCompleted, 300), now.toISOString(), now.getTime());
+          }
         }
       } catch (e) { debugCatch(e, 'handleStop-fast-summary'); }
     } finally {
@@ -603,12 +611,14 @@ async function handleSessionStart() {
         const STALE_AGE = Date.now() - 30 * 86400000;
         const OP_CAP = 500;
 
-        // Purge FIRST: delete entries already marked pending-purge from previous cycles (7-day retention)
-        // Must run before decay/idle-mark to avoid same-cycle delete of newly-marked entries
+        // Purge FIRST: delete pending-purge entries. Schema has no marked_at_epoch, so we
+        // anchor retention on created_at_epoch instead: 30d marking gate + 7d grace = 37d.
+        // Older cutoffs (e.g. 7d) were always redundant with the 30d marking filter and
+        // made purge effectively immediate on the next maintenance cycle — fix for T4-P1-A.
         const purged = db.prepare(`
           DELETE FROM observations WHERE compressed_into = ${COMPRESSED_PENDING_PURGE}
             AND created_at_epoch < ?
-        `).run(Date.now() - 7 * 86400000);
+        `).run(Date.now() - 37 * 86400000);
         if (purged.changes > 0) debugLog('DEBUG', 'auto-maintain', `purged ${purged.changes} stale observations`);
 
         // Cleanup: remove broken observations (no title AND no narrative)
@@ -906,9 +916,13 @@ async function handleUserPrompt() {
       VALUES (?, ?, ?, ?, ?, 'active')
     `).run(sessionId, sessionId, project, now.toISOString(), now.getTime());
 
-    // Increment prompt counter
-    db.prepare('UPDATE sdk_sessions SET prompt_counter = COALESCE(prompt_counter, 0) + 1 WHERE content_session_id = ?').run(sessionId);
-    const counter = db.prepare('SELECT prompt_counter FROM sdk_sessions WHERE content_session_id = ?').get(sessionId);
+    // T4-P2-D: atomic increment+read via UPDATE ... RETURNING (SQLite 3.35+).
+    // Previously UPDATE + SELECT as two statements; parallel prompts could read a stale
+    // counter and emit duplicate prompt_number values. better-sqlite3 ships a modern SQLite.
+    const bumped = db.prepare(
+      'UPDATE sdk_sessions SET prompt_counter = COALESCE(prompt_counter, 0) + 1 WHERE content_session_id = ? RETURNING prompt_counter'
+    ).get(sessionId);
+    const promptNumber = bumped?.prompt_counter || 1;
 
     db.prepare(`
       INSERT INTO user_prompts (content_session_id, prompt_text, prompt_number, created_at, created_at_epoch)
@@ -916,7 +930,7 @@ async function handleUserPrompt() {
     `).run(
       sessionId,
       scrubSecrets(promptText.slice(0, 10000)),
-      counter?.prompt_counter || 1,
+      promptNumber,
       now.toISOString(), now.getTime()
     );
 
@@ -928,7 +942,7 @@ async function handleUserPrompt() {
     const ccSessionId = typeof hookData.session_id === 'string' && hookData.session_id.length > 0
       ? hookData.session_id
       : null;
-    if (counter?.prompt_counter <= 3) {
+    if (promptNumber <= 3) {
       try {
         if (detectContinuationIntent(db, promptText, project, ccSessionId)) {
           const injection = renderHandoffInjection(db, project, ccSessionId);

package/mem-cli.mjs

@@ -742,8 +742,11 @@ function cmdTimeline(db, args) {
     return;
   }
 
-  const projectFilter = project ? 'AND project = ?' : '';
-  const baseParams = project ? [project] : [];
+  // Auto-scope to anchor's project when --project not explicitly given: users asking
+  // "what happened around #N" expect same-project context, not cross-project time-bleed.
+  const effectiveProject = project || anchorRow.project;
+  const projectFilter = effectiveProject ? 'AND project = ?' : '';
+  const baseParams = effectiveProject ? [effectiveProject] : [];
 
   // Before anchor
   const beforeRows = db.prepare(`
@@ -783,7 +786,7 @@ function cmdSave(db, args) {
   const { positional, flags } = parseArgs(args);
   const text = positional.join(' ');
   if (!text) {
-    fail('[mem] Usage: mem save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2]');
+    fail('[mem] Usage: mem save "<text>" [--type T] [--title T] [--importance N] [--project P] [--files f1,f2] [--lesson T]');
     return;
   }
 
@@ -805,9 +808,21 @@ function cmdSave(db, args) {
   const project = flags.project ? resolveProject(db, flags.project) : inferProject();
   const saveFiles = flags.files ? flags.files.split(',').map(f => f.trim()).filter(Boolean) : [];
 
+  // Optional lesson_learned — accepts --lesson or --lesson-learned (alias)
+  // Mirrors MCP memSaveSchema.lesson_learned (≤500 chars) and cmdUpdate's flag handling.
+  const rawLesson = flags.lesson !== undefined ? flags.lesson
+    : flags['lesson-learned'] !== undefined ? flags['lesson-learned']
+    : null;
+  if (rawLesson !== null && typeof rawLesson === 'string' && rawLesson.length > 500) {
+    fail(`[mem] --lesson too long (${rawLesson.length} chars, max 500).`);
+    return;
+  }
+
   // Secret scrubbing (aligned with MCP mem_save)
   const safeContent = scrubSecrets(text);
   const safeTitle = scrubSecrets(rawTitle);
+  const safeLesson = (rawLesson !== null && typeof rawLesson === 'string' && rawLesson.length > 0)
+    ? scrubSecrets(rawLesson) : null;
 
   // Dedup: skip if similar title/content saved in last 5 minutes (aligned with MCP mem_save)
   const fiveMinAgo = Date.now() - 5 * 60 * 1000;
@@ -827,8 +842,11 @@ function cmdSave(db, args) {
   }
 
   // MinHash + CJK bigrams (aligned with MCP mem_save)
+  // Include lesson in the FTS-indexed text so the +0.3 lesson-boost actually surfaces
+  // lesson-bearing rows (mirrors MCP mem_save which builds the same indexText).
   const minhashSig = computeMinHash(safeTitle + ' ' + safeContent);
-  const bigramText = cjkBigrams(safeTitle + ' ' + safeContent);
+  const indexText = [safeTitle, safeContent, safeLesson].filter(Boolean).join(' ');
+  const bigramText = cjkBigrams(indexText);
   const textField = bigramText ? safeContent + ' ' + bigramText : safeContent;
 
   const now = new Date();
@@ -843,9 +861,9 @@ function cmdSave(db, args) {
   // Atomic: insert observation + observation_files + TF-IDF vector (aligned with MCP mem_save)
   const saveTx = db.transaction(() => {
     const result = db.prepare(`
-      INSERT INTO observations (memory_session_id, project, text, type, title, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, branch, created_at, created_at_epoch)
-      VALUES (?, ?, ?, ?, ?, ?, '', '', '[]', ?, ?, ?, ?, ?, ?)
-    `).run(sessionId, project, textField, type, safeTitle, safeContent, JSON.stringify(saveFiles), importance, minhashSig, getCurrentBranch(), now.toISOString(), now.getTime());
+      INSERT INTO observations (memory_session_id, project, text, type, title, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, lesson_learned, branch, created_at, created_at_epoch)
+      VALUES (?, ?, ?, ?, ?, ?, '', '', '[]', ?, ?, ?, ?, ?, ?, ?)
+    `).run(sessionId, project, textField, type, safeTitle, safeContent, JSON.stringify(saveFiles), importance, minhashSig, safeLesson, getCurrentBranch(), now.toISOString(), now.getTime());
     const savedId = Number(result.lastInsertRowid);
 
     // Populate observation_files junction table (aligned with MCP mem_save)
@@ -870,7 +888,8 @@ function cmdSave(db, args) {
   });
   const result = saveTx();
 
-  out(`[mem] Saved #${result.lastInsertRowid} [${type}] "${truncate(safeTitle, 80)}" (project: ${project})`);
+  const lessonNote = safeLesson ? ' 💡lesson captured' : '';
+  out(`[mem] Saved #${result.lastInsertRowid} [${type}] "${truncate(safeTitle, 80)}" (project: ${project})${lessonNote}`);
 }
 
 // N-1: Quality-focused stats for R-2 A/B baseline.
@@ -1645,6 +1664,9 @@ function cmdMaintain(db, args) {
   const OP_CAP = 1000;
   const results = [];
 
+  // T2-P1-B: surface the OP_CAP hit so users know to re-run, matching MCP mem_maintain.
+  const capHint = (changes) => (changes >= OP_CAP ? ' (cap reached, re-run for more)' : '');
+
   db.transaction(() => {
     if (ops.includes('cleanup')) {
       const deleted = db.prepare(`
@@ -1655,7 +1677,7 @@ function cmdMaintain(db, args) {
             ${projectFilter} LIMIT ${OP_CAP}
         )
       `).run(...baseParams);
-      results.push(`Cleaned up ${deleted.changes} broken observations`);
+      results.push(`Cleaned up ${deleted.changes} broken observations${capHint(deleted.changes)}`);
     }
 
     if (ops.includes('decay')) {
@@ -1683,7 +1705,8 @@ function cmdMaintain(db, args) {
             ${projectFilter} LIMIT ${OP_CAP}
         )
       `).run(staleAge, ...baseParams);
-      results.push(`Decayed ${decayed.changes} stale observations, marked ${idleMarked.changes} idle as pending-purge`);
+      const decayCap = (decayed.changes >= OP_CAP || idleMarked.changes >= OP_CAP) ? ' (cap reached, re-run for more)' : '';
+      results.push(`Decayed ${decayed.changes} stale observations, marked ${idleMarked.changes} idle as pending-purge${decayCap}`);
     }
 
     if (ops.includes('boost')) {
@@ -1697,35 +1720,68 @@ function cmdMaintain(db, args) {
             ${projectFilter} LIMIT ${OP_CAP}
         )
       `).run(...baseParams);
-      results.push(`Boosted ${boosted.changes} frequently-accessed observations`);
+      results.push(`Boosted ${boosted.changes} frequently-accessed observations${capHint(boosted.changes)}`);
     }
 
     if (ops.includes('dedup') && flags['merge-ids']) {
-      // Parse merge-ids: "keepId:removeId1:removeId2,keepId2:removeId3" format
+      // Parse merge-ids: "keepId:removeId1:removeId2,keepId2:removeId3" format.
+      // Surface malformed segments (non-numeric tokens, single-element pairs) instead of
+      // silently dropping them, so typos like "abc:def" don't hide behind "Merged 0".
       let totalMerged = 0;
+      const invalidSegments = [];
       const mergeStmt = db.prepare('UPDATE observations SET compressed_into = ? WHERE id = ? AND COALESCE(compressed_into, 0) = 0');
-      const groups = flags['merge-ids'].split(',').map(g => g.trim().split(':').map(Number).filter(n => !isNaN(n)));
-      for (const group of groups) {
-        if (group.length < 2) continue;
-        const [keepId, ...removeIds] = group;
+      const rawSegments = flags['merge-ids'].split(',').map(s => s.trim()).filter(Boolean);
+      for (const seg of rawSegments) {
+        const parts = seg.split(':').map(s => s.trim());
+        const nums = parts.map(p => Number(p));
+        const badToken = parts.length < 2 || nums.some(n => !Number.isFinite(n) || n <= 0);
+        if (badToken) { invalidSegments.push(seg); continue; }
+        const [keepId, ...removeIds] = nums;
         for (const removeId of removeIds) {
           totalMerged += mergeStmt.run(keepId, removeId).changes;
         }
       }
+      if (invalidSegments.length) {
+        results.push(`Warning: ignored ${invalidSegments.length} malformed --merge-ids segment(s): ${invalidSegments.join(', ')} (expected keepId:removeId[:removeId...] with positive integers)`);
+      }
       results.push(`Merged ${totalMerged} duplicate observations`);
     }
 
+    // T2-P1-B parity with MCP: warn when merge-ids is provided but dedup wasn't requested.
+    if (!ops.includes('dedup') && flags['merge-ids']) {
+      results.push('Warning: --merge-ids provided but "dedup" not in operations — merge-ids ignored');
+    }
+
     if (ops.includes('purge_stale')) {
       const retainDays = parseInt(flags['retain-days'], 10) || 30;
       const retainCutoff = Date.now() - retainDays * 86400000;
-      const purged = db.prepare(`
-        DELETE FROM observations WHERE id IN (
-          SELECT id FROM observations
-          WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ?
-            ${projectFilter} LIMIT ${OP_CAP}
-        )
-      `).run(retainCutoff, ...baseParams);
-      results.push(`Purged ${purged.changes} stale observations`);
+      // T2-P0-A (CLI parity): purge_stale is the only DELETE in this code path — require
+      // --confirm so a mis-typed `maintain execute --ops purge_stale` can't wipe rows silently.
+      const confirmed = flags.confirm === true || flags.confirm === 'true';
+      if (!confirmed) {
+        const previewRow = db.prepare(`
+          SELECT COUNT(*) AS candidates, MIN(created_at_epoch) AS oldest, MAX(created_at_epoch) AS newest
+          FROM observations
+          WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ? ${projectFilter}
+        `).get(retainCutoff, ...baseParams);
+        const pushLines = [`purge_stale preview (no --confirm):`,
+          `  Candidates (pending-purge, older than ${retainDays}d): ${previewRow.candidates}`];
+        if (previewRow.candidates > 0) {
+          pushLines.push(`  Oldest: ${new Date(previewRow.oldest).toISOString().slice(0, 10)}`);
+          pushLines.push(`  Newest: ${new Date(previewRow.newest).toISOString().slice(0, 10)}`);
+        }
+        pushLines.push(`  To delete, re-run with --confirm.`);
+        results.push(pushLines.join('\n'));
+      } else {
+        const purged = db.prepare(`
+          DELETE FROM observations WHERE id IN (
+            SELECT id FROM observations
+            WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ?
+              ${projectFilter} LIMIT ${OP_CAP}
+          )
+        `).run(retainCutoff, ...baseParams);
+        results.push(`Purged ${purged.changes} stale observations (retained last ${retainDays} days)${capHint(purged.changes)}`);
+      }
     }
   })();
 
@@ -1993,6 +2049,7 @@ Commands:
     --importance N      1-3 (default: 2)
     --project P         Project name
     --files f1,f2       Comma-separated file paths
+    --lesson T          Lesson learned (≤500 chars; alias: --lesson-learned)
 
   delete <id1,id2,...>  Delete observations by ID
     --confirm           Execute deletion (preview by default)
@@ -2025,6 +2082,16 @@ Commands:
     --project P         Filter by project
     --retain-days N     For purge_stale: keep last N days (default 30)
 
+  optimize              LLM-powered memory optimization (preview by default)
+    --run               Execute (default: preview gates)
+    --run-all           Execute bypassing gates
+    --task T            Comma-separated: re-enrich,normalize,cluster-merge,smart-compress
+    --max N             Max items per task (1-100, default 15)
+    --scope S           re-enrich scope: narrow (default) or wide
+
+  doctor                Environment diagnostics and benchmarks
+    --benchmark         Run perf benchmark and emit JSON
+
   fts-check <check|rebuild>  FTS5 index check or rebuild
 
   stats                 Show memory statistics
@@ -2180,10 +2247,32 @@ async function cmdEnrich(argv) {
 async function cmdOptimize(db, args) {
   const run = args.includes('--run');
   const runAll = args.includes('--run-all');
+  // T2-P1-D: --task accepts a single task or a comma-separated list, parity with MCP memOptimizeSchema.tasks.
+  const VALID_TASKS = ['re-enrich', 'normalize', 'cluster-merge', 'smart-compress'];
   const taskIdx = args.indexOf('--task');
-  const tasks = taskIdx >= 0 && args[taskIdx + 1] ? [args[taskIdx + 1]] : undefined;
+  let tasks;
+  if (taskIdx >= 0 && args[taskIdx + 1]) {
+    const parsed = args[taskIdx + 1].split(',').map(s => s.trim()).filter(Boolean);
+    const invalid = parsed.filter(t => !VALID_TASKS.includes(t));
+    if (invalid.length > 0) {
+      fail(`[mem] Unknown task(s): ${invalid.join(', ')}. Valid: ${VALID_TASKS.join(', ')}`);
+      return;
+    }
+    tasks = parsed;
+  }
+  // T2-P1-C: reject --max 0 / --max <non-positive> / --max <non-number> explicitly — the old
+  // `|| 15` fallback silently turned these into the default (15), burning LLM tokens.
   const maxIdx = args.indexOf('--max');
-  const maxItems = maxIdx >= 0 ? parseInt(args[maxIdx + 1], 10) || 15 : 15;
+  let maxItems = 15;
+  if (maxIdx >= 0) {
+    const raw = args[maxIdx + 1];
+    const parsed = parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 1 || parsed > 100) {
+      fail(`[mem] Invalid --max "${raw}". Must be an integer between 1 and 100.`);
+      return;
+    }
+    maxItems = parsed;
+  }
   // R-7 micro: --scope wide targets bugfix/refactor/feature/decision with narrative but no
   // lesson_learned (the "Haiku judged 'none'" cases). Default 'narrow' preserves old behavior.
   const scopeIdx = args.indexOf('--scope');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "2.34.0",
+  "version": "2.34.2",
   "description": "Lightweight persistent memory system for Claude Code",
   "type": "module",
   "engines": {

package/scripts/pre-skill-bridge.js

@@ -66,13 +66,24 @@ try {
 
     // Read and output
     const content = readFileSync(skillPath, 'utf8');
-    // Token budget: ~4 chars per token, 4000 token limit = 16000 chars
+    // T4-P1-B: JSON hookSpecificOutput parity with pre-tool-recall.js. Some CC variants
+    // (notably sdscc) silently drop plain-text stdout from PreToolUse — the previous
+    // console.log() form would render on stock CC but no-op on those variants.
+    // Token budget: ~4 chars per token, 4000 token limit = 16000 chars.
+    let additionalContext;
     if (content.length > 16000) {
       const summary = content.slice(0, 800);
-      console.log(`<skill-bridge name="${row.name}" source="managed" truncated="true">\n${summary}\n...\n</skill-bridge>\n\nSkill content truncated. Use mem_use(name="${row.name}") to load full content.`);
+      additionalContext = `<skill-bridge name="${row.name}" source="managed" truncated="true">\n${summary}\n...\n</skill-bridge>\n\nSkill content truncated. Use mem_use(name="${row.name}") to load full content.`;
     } else {
-      console.log(`<skill-bridge name="${row.name}" source="managed">\n${content}\n</skill-bridge>\n\nThis skill was loaded from the managed registry. Follow the instructions above.`);
+      additionalContext = `<skill-bridge name="${row.name}" source="managed">\n${content}\n</skill-bridge>\n\nThis skill was loaded from the managed registry. Follow the instructions above.`;
     }
+    process.stdout.write(JSON.stringify({
+      suppressOutput: true,
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext,
+      },
+    }));
   } catch {
     // Silent failure — never block Skill tool
   } finally {

package/scripts/pre-tool-recall.js

@@ -188,15 +188,19 @@ try {
     const lines = [];
     if (allRows.length > 0) {
       lines.push(`[mem] Lessons for ${fname}:`);
+      // R3-UX: raised from 120 → 240 after measuring 97% of lessons exceed 120 chars
+      // (p50=218, avg=247). Previous limit truncated the actionable "Fix:" tail in 80%
+      // of lessons containing it. 3 × 240 ≈ 180 tokens/Edit — negligible context cost.
+      const LESSON_MAX = 240;
       for (const r of allRows) {
         if (r.lesson_learned) {
-          const lesson = r.lesson_learned.length > 120
-            ? r.lesson_learned.slice(0, 117) + '...'
+          const lesson = r.lesson_learned.length > LESSON_MAX
+            ? r.lesson_learned.slice(0, LESSON_MAX - 3) + '...'
             : r.lesson_learned;
           lines.push(`  #${r.id} [${r.type}] ${lesson}`);
         } else {
-          const title = (r.title || '').length > 120
-            ? r.title.slice(0, 117) + '...'
+          const title = (r.title || '').length > LESSON_MAX
+            ? r.title.slice(0, LESSON_MAX - 3) + '...'
             : (r.title || '');
           lines.push(`  #${r.id} [${r.type}] ${title}`);
         }

package/server.mjs

@@ -159,7 +159,7 @@ function buildObsFtsQuery(scoring, { multiplier, withSnippet, withOffset, includ
   const mult = multiplier ? ` * ${multiplier}` : '';
   const lowSignalClause = includeNoise ? '' : `AND ${notLowSignalTitleClause('o')}`;
   return `
-    SELECT o.id, o.type, o.title, o.subtitle, o.project, o.created_at, o.importance,
+    SELECT o.id, o.type, o.title, o.subtitle, o.project, o.created_at, o.created_at_epoch, o.importance,
            o.files_modified,
            ${withSnippet ? "snippet(observations_fts, 2, '»', '«', '…', 10) as match_snippet," : ''}
            ${scoreExpr}${mult} as score
@@ -201,7 +201,8 @@ function buildObsFtsParams({ now, projectBoost, ftsQuery, args, epochFrom, epoch
 function ftsRowToResult(r, { scoreMultiplier, snippet } = {}) {
   return {
     source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle,
-    project: r.project, date: r.created_at, score: scoreMultiplier ? r.score * scoreMultiplier : r.score,
+    project: r.project, date: r.created_at, created_at_epoch: r.created_at_epoch,
+    score: scoreMultiplier ? r.score * scoreMultiplier : r.score,
     files_modified: r.files_modified, importance: r.importance, snippet: snippet ? (r.match_snippet || '') : '',
   };
 }
@@ -312,7 +313,7 @@ function searchObservations(ctx) {
       LIMIT ? OFFSET ?
     `).all(...params);
     for (const r of rows) {
-      results.push({ source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle, project: r.project, date: r.created_at, dateEpoch: r.created_at_epoch });
+      results.push({ source: 'obs', id: r.id, type: r.type, title: r.title, subtitle: r.subtitle, project: r.project, date: r.created_at, created_at_epoch: r.created_at_epoch, files_modified: r.files_modified, importance: r.importance });
     }
   }
 
@@ -371,7 +372,7 @@ function searchSessions(ctx) {
     const now = Date.now();
     const sessionProjectBoost = args.project ? null : currentProject;
     const rows = db.prepare(`
-      SELECT s.id, s.request, s.completed, s.project, s.created_at,
+      SELECT s.id, s.request, s.completed, s.project, s.created_at, s.created_at_epoch,
              ${SESS_BM25}
                * (1.0 + EXP(-0.693 * (? - s.created_at_epoch) / ${RECENCY_HALF_LIFE_MS}.0))
                * (CASE WHEN ? IS NOT NULL AND s.project = ? THEN 2.0 ELSE 1.0 END) as score
@@ -393,7 +394,7 @@ function searchSessions(ctx) {
       perSourceLimit, perSourceOffset
     );
     for (const r of rows) {
-      results.push({ source: 'session', id: r.id, request: r.request, completed: r.completed, project: r.project, date: r.created_at, score: r.score });
+      results.push({ source: 'session', id: r.id, request: r.request, completed: r.completed, project: r.project, date: r.created_at, created_at_epoch: r.created_at_epoch, score: r.score });
     }
   } else if (!searchType) {
     // Skip sessions in unfiltered no-query mode (too noisy)
@@ -412,7 +413,7 @@ function searchSessions(ctx) {
       LIMIT ? OFFSET ?
     `).all(...params);
     for (const r of rows) {
-      results.push({ source: 'session', id: r.id, request: r.request, completed: r.completed, project: r.project, date: r.created_at, dateEpoch: r.created_at_epoch });
+      results.push({ source: 'session', id: r.id, request: r.request, completed: r.completed, project: r.project, date: r.created_at, created_at_epoch: r.created_at_epoch });
     }
   }
 
@@ -425,7 +426,7 @@ function searchPrompts(ctx) {
 
   if (ftsQuery) {
     const rows = db.prepare(`
-      SELECT p.id, p.prompt_text, p.content_session_id, p.created_at,
+      SELECT p.id, p.prompt_text, p.content_session_id, p.created_at, p.created_at_epoch,
              bm25(user_prompts_fts, 1) as score
       FROM user_prompts_fts
       JOIN user_prompts p ON user_prompts_fts.rowid = p.id
@@ -445,7 +446,7 @@ function searchPrompts(ctx) {
       perSourceLimit, perSourceOffset
     );
     for (const r of rows) {
-      results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, score: r.score });
+      results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, created_at_epoch: r.created_at_epoch, score: r.score });
     }
     // CJK LIKE fallback: FTS5 unicode61 can't tokenize CJK substrings in prompts
     if (rows.length === 0 && args.query) {
@@ -454,7 +455,7 @@ function searchPrompts(ctx) {
         const likeConds = cjkPatterns.map(() => 'p.prompt_text LIKE ?');
         const likeParams = cjkPatterns.map(p => `%${p}%`);
         const fallbackRows = db.prepare(`
-          SELECT p.id, p.prompt_text, p.content_session_id, p.created_at
+          SELECT p.id, p.prompt_text, p.content_session_id, p.created_at, p.created_at_epoch
           FROM user_prompts p
           JOIN sdk_sessions s ON p.content_session_id = s.content_session_id
           WHERE (${likeConds.join(' OR ')})
@@ -472,7 +473,7 @@ function searchPrompts(ctx) {
           perSourceLimit, perSourceOffset
         );
         for (const r of fallbackRows) {
-          results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, score: 0 });
+          results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, created_at_epoch: r.created_at_epoch, score: 0 });
         }
       }
     }
@@ -493,7 +494,7 @@ function searchPrompts(ctx) {
       LIMIT ? OFFSET ?
     `).all(...params);
     for (const r of rows) {
-      results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, dateEpoch: r.created_at_epoch });
+      results.push({ source: 'prompt', id: r.id, text: r.prompt_text, session: r.content_session_id, date: r.created_at, created_at_epoch: r.created_at_epoch });
     }
   }
 
@@ -522,7 +523,10 @@ function formatSearchOutput(paginatedResults, args, ftsQuery, totalCount, isCros
     ? `${paginatedResults.length} of ${totalCount}`
     : `${paginatedResults.length}`;
   const hasMixed = paginatedResults.some(r => r.source === 'session' || r.source === 'prompt');
-  lines.push(`Found ${countLabel} result(s)${args.query ? ` for "${args.query}"` : ''}:${hasMixed ? ' (# observation, S# session, P# prompt)' : ''}\n`);
+  // P2-6: empty/omitted query falls through to a "listing recent" path — label it explicitly
+  // so callers don't mistake BM25-less results for relevance-ranked ones.
+  const qLabel = args.query ? ` for "${args.query}"` : ' (no query — listing recent)';
+  lines.push(`Found ${countLabel} result(s)${qLabel}:${hasMixed ? ' (# observation, S# session, P# prompt)' : ''}\n`);
 
   for (const r of paginatedResults) {
     if (r.source === 'obs') {
@@ -627,7 +631,7 @@ server.registerTool(
       if (ftsQuery) {
         results.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
       } else {
-        results.sort((a, b) => (b.dateEpoch ?? 0) - (a.dateEpoch ?? 0));
+        results.sort((a, b) => (b.created_at_epoch ?? 0) - (a.created_at_epoch ?? 0));
       }
     }
 
@@ -785,8 +789,11 @@ server.registerTool(
       db.prepare('UPDATE observations SET access_count = COALESCE(access_count, 0) + 1, last_accessed_at = ? WHERE id = ?').run(Date.now(), anchorId);
     } catch { /* non-critical: FTS5 trigger may fail on corrupted index */ }
 
-    const projectFilter = args.project ? 'AND project = ?' : '';
-    const baseParams = args.project ? [args.project] : [];
+    // Auto-scope to anchor's project when caller didn't pass one: "timeline around #N"
+    // means same-project context by default; cross-project bleed breaks user mental model.
+    const effectiveProject = args.project || anchorRow.project;
+    const projectFilter = effectiveProject ? 'AND project = ?' : '';
+    const baseParams = effectiveProject ? [effectiveProject] : [];
 
     // Before anchor
     const beforeRows = db.prepare(`
@@ -832,15 +839,17 @@ server.registerTool(
     const source = args.source || 'obs';
     const placeholders = args.ids.map(() => '?').join(',');
 
-    let rows, allFields, prefix;
+    let rows, allFields, prefix, sourceLabel;
     if (source === 'session') {
       rows = db.prepare(`SELECT * FROM session_summaries WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...args.ids);
       allFields = ['id', 'request', 'investigated', 'learned', 'completed', 'next_steps', 'files_read', 'files_edited', 'notes', 'project', 'created_at', 'memory_session_id', 'prompt_number'];
       prefix = 'S#';
+      sourceLabel = 'sessions';
     } else if (source === 'prompt') {
       rows = db.prepare(`SELECT * FROM user_prompts WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...args.ids);
       allFields = ['id', 'prompt_text', 'content_session_id', 'prompt_number', 'created_at'];
       prefix = 'P#';
+      sourceLabel = 'prompts';
     } else {
       // Increment access_count for retrieved observations (batch UPDATE)
       try {
@@ -852,15 +861,43 @@ server.registerTool(
       rows = db.prepare(`SELECT * FROM observations WHERE id IN (${placeholders}) ORDER BY created_at_epoch ASC`).all(...args.ids);
       allFields = ['id', 'type', 'title', 'subtitle', 'narrative', 'text', 'facts', 'concepts', 'lesson_learned', 'search_aliases', 'files_read', 'files_modified', 'project', 'created_at', 'memory_session_id', 'prompt_number', 'importance', 'related_ids', 'access_count', 'branch', 'superseded_at', 'superseded_by', 'last_accessed_at'];
       prefix = '#';
+      sourceLabel = 'observations';
+    }
+
+    // P1-3: validate requested fields — throw on all-invalid so callers don't silently get an
+    // empty record (header only). Partial-invalid is tolerated but surfaced as a note.
+    let fieldsNote = '';
+    if (args.fields?.length) {
+      const invalid = args.fields.filter(f => !allFields.includes(f));
+      const valid = args.fields.filter(f => allFields.includes(f));
+      if (valid.length === 0) {
+        throw new Error(`No valid fields. Unknown field(s): ${invalid.join(', ')}. Valid: ${allFields.join(', ')}`);
+      }
+      if (invalid.length > 0) {
+        fieldsNote = `Note: unknown field(s) dropped: ${invalid.join(', ')}. Valid: ${allFields.join(', ')}`;
+      }
     }
 
     if (rows.length === 0) {
-      return { content: [{ type: 'text', text: `No ${source === 'session' ? 'sessions' : source === 'prompt' ? 'prompts' : 'observations'} found for given IDs.` }] };
+      // P2-7: for source=session/prompt, check whether the IDs exist as observations so the
+      // caller can switch source instead of chasing a phantom miss.
+      let hint = '';
+      if (source === 'session' || source === 'prompt') {
+        try {
+          const obsHits = db.prepare(`SELECT id FROM observations WHERE id IN (${placeholders})`).all(...args.ids);
+          if (obsHits.length > 0) {
+            hint = ` These ID(s) exist as observations: ${obsHits.map(r => r.id).join(', ')}. Try source='obs'.`;
+          }
+        } catch { /* best-effort hint */ }
+      }
+      const msg = `No ${sourceLabel} found for given IDs.${hint}`;
+      return { content: [{ type: 'text', text: fieldsNote ? `${msg}\n\n${fieldsNote}` : msg }] };
     }
 
     const fields = args.fields?.length ? args.fields.filter(f => allFields.includes(f)) : allFields;
 
     const parts = [];
+    if (fieldsNote) parts.push(fieldsNote);
     for (const row of rows) {
       const lines = [`── ${prefix}${row.id} ──`];
       for (const f of fields) {
@@ -875,6 +912,13 @@ server.registerTool(
       parts.push(lines.join('\n'));
     }
 
+    // P1-4: surface IDs that weren't found (mirrors mem_delete's missing-ID note).
+    const foundIds = new Set(rows.map(r => r.id));
+    const missing = args.ids.filter(id => !foundIds.has(id));
+    if (missing.length > 0) {
+      parts.push(`Note: ID(s) ${missing.join(', ')} not found.`);
+    }
+
     return { content: [{ type: 'text', text: parts.join('\n\n') }] };
   })
 );
@@ -1366,11 +1410,43 @@ server.registerTool(
     }
 
     if (action === 'execute') {
-      const ops = args.operations || ['cleanup', 'decay', 'boost'];
+      const ops = args.operations && args.operations.length > 0
+        ? args.operations
+        : ['cleanup', 'decay', 'boost'];
+      // T2-P1-A: reject explicit empty array (vs. omitted → defaults above). Empty-array
+      // callers are almost always mistakes; silently running only FTS5 optimize hides the error.
+      if (args.operations && args.operations.length === 0) {
+        return { content: [{ type: 'text', text: 'operations array is empty. Pass a non-empty list (e.g. ["cleanup","decay","boost"]) or omit operations to use the default set.' }], isError: true };
+      }
       const results = [];
       const staleAge = Date.now() - STALE_AGE_MS;
       const OP_ROW_CAP = 1000; // safety cap per operation
 
+      // T2-P0-A: purge_stale is the only DELETE in this handler. Require confirm=true;
+      // a first call without confirm returns a dry-run preview so callers know the blast radius.
+      const purgeRequested = ops.includes('purge_stale');
+      if (purgeRequested && args.confirm !== true) {
+        const retainDays = args.retain_days ?? 30;
+        const retainCutoff = Date.now() - retainDays * 86400000;
+        const previewRow = db.prepare(`
+          SELECT COUNT(*) AS candidates, MIN(created_at_epoch) AS oldest, MAX(created_at_epoch) AS newest
+          FROM observations
+          WHERE compressed_into = ${COMPRESSED_PENDING_PURGE} AND created_at_epoch < ? ${projectFilter}
+        `).get(retainCutoff, ...baseParams);
+        const lines = [
+          'purge_stale preview (confirm=false):',
+          `  Candidates (pending-purge, older than ${retainDays}d): ${previewRow.candidates}`,
+        ];
+        if (previewRow.candidates > 0) {
+          lines.push(`  Oldest: ${new Date(previewRow.oldest).toISOString().slice(0, 10)}`);
+          lines.push(`  Newest: ${new Date(previewRow.newest).toISOString().slice(0, 10)}`);
+        }
+        lines.push('');
+        lines.push('Nothing was deleted. To execute, re-run with confirm=true:');
+        lines.push(`  mem_maintain(action="execute", operations=${JSON.stringify(ops)}, confirm=true${args.retain_days ? `, retain_days=${args.retain_days}` : ''}${args.project ? `, project="${args.project}"` : ''})`);
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+      }
+
       db.transaction(() => {
         if (ops.includes('cleanup')) {
           const deleted = db.prepare(`
@@ -1541,6 +1617,9 @@ server.registerTool(
       tasks: args.tasks,
       maxItems: args.max_items || 15,
       force,
+      // T2-P0-B: scope parity with CLI (--scope wide). When omitted, optimizeRun defaults
+      // to narrow via its own code; passing through keeps that fallback intact.
+      reenrichScope: args.scope,
     });
 
     const lines = ['🔧 LLM Optimization Results:'];
@@ -1626,15 +1705,18 @@ server.registerTool(
       const typeFilter = args.type;
       const where = typeFilter ? 'WHERE type = ? AND status = ?' : 'WHERE status = ?';
       const params = typeFilter ? [typeFilter, 'active'] : ['active'];
+      // T3-P2-A: order by adoption then recommendation (CLI parity), and coalesce NULL counts
+      // so the output shows "adopt:0" rather than the jarring "adopt:null".
       const resources = rdb.prepare(`
         SELECT name, type, invocation_name, recommend_count, adopt_count, capability_summary
-        FROM resources ${where} ORDER BY type, name
+        FROM resources ${where}
+        ORDER BY COALESCE(adopt_count, 0) DESC, COALESCE(recommend_count, 0) DESC, type, name
       `).all(...params);
 
       if (resources.length === 0) return { content: [{ type: 'text', text: 'No resources found.' }] };
 
       const lines = resources.map(r =>
-        `${r.type === 'skill' ? 'S' : 'A'} ${r.name}${r.invocation_name ? ` (${r.invocation_name})` : ''} — rec:${r.recommend_count} adopt:${r.adopt_count} — ${truncate(r.capability_summary || '', 80)}`
+        `${r.type === 'skill' ? 'S' : 'A'} ${r.name}${r.invocation_name ? ` (${r.invocation_name})` : ''} — rec:${r.recommend_count ?? 0} adopt:${r.adopt_count ?? 0} — ${truncate(r.capability_summary || '', 80)}`
       );
       return { content: [{ type: 'text', text: `Resources (${resources.length}):\n${lines.join('\n')}` }] };
     }
@@ -1909,19 +1991,29 @@ server.registerTool(
     wheres.push('superseded_at IS NULL');
     if (args.project) { wheres.push('project = ?'); params.push(resolveProject(args.project)); }
     if (args.type) { wheres.push('type = ?'); params.push(args.type); }
+    // T3-P1-A: surface invalid dates instead of silently dropping the filter — mirrors
+    // mem_search, which threw. A dropped filter can quietly expand the export blast radius.
     if (args.date_from) {
       const epoch = new Date(args.date_from).getTime();
-      if (!isNaN(epoch)) { wheres.push('created_at_epoch >= ?'); params.push(epoch); }
+      if (isNaN(epoch)) throw new Error(`Invalid date_from: "${args.date_from}" (use ISO 8601 or YYYY-MM-DD)`);
+      wheres.push('created_at_epoch >= ?');
+      params.push(epoch);
     }
     if (args.date_to) {
       const d = args.date_to.length === 10 ? args.date_to + 'T23:59:59.999Z' : args.date_to;
       const epoch = new Date(d).getTime();
-      if (!isNaN(epoch)) { wheres.push('created_at_epoch <= ?'); params.push(epoch); }
+      if (isNaN(epoch)) throw new Error(`Invalid date_to: "${args.date_to}" (use ISO 8601 or YYYY-MM-DD)`);
+      wheres.push('created_at_epoch <= ?');
+      params.push(epoch);
     }
 
     const where = wheres.length > 0 ? 'WHERE ' + wheres.join(' AND ') : '';
     const exportLimit = Math.min(args.limit ?? 200, 1000);
-    const rows = db.prepare(`SELECT id, project, type, title, subtitle, narrative, concepts, facts, lesson_learned, importance, files_modified, created_at, created_at_epoch FROM observations ${where} ORDER BY created_at_epoch DESC LIMIT ?`).all(...params, exportLimit);
+    // T3-P2-B: probe limit+1 so we can tell "user hit their own limit with more waiting" from
+    // "user got exactly what existed". Trim to exportLimit before rendering.
+    const probed = db.prepare(`SELECT id, project, type, title, subtitle, narrative, concepts, facts, lesson_learned, importance, files_modified, branch, access_count, memory_session_id, created_at, created_at_epoch FROM observations ${where} ORDER BY created_at_epoch DESC LIMIT ?`).all(...params, exportLimit + 1);
+    const rows = probed.slice(0, exportLimit);
+    const moreAvailable = probed.length > exportLimit;
 
     if (rows.length === 0) return { content: [{ type: 'text', text: 'No observations found matching the criteria.' }] };
 
@@ -1929,7 +2021,7 @@ server.registerTool(
       ? rows.map(r => JSON.stringify(r)).join('\n')
       : JSON.stringify(rows, null, 2);
 
-    const cap = rows.length >= exportLimit ? `\nNote: Results capped at ${exportLimit}. Use date_from/date_to or increase limit (max 1000) to export more.` : '';
+    const cap = moreAvailable ? `\nNote: Results capped at ${exportLimit}. Use date_from/date_to or increase limit (max 1000) to export more.` : '';
     return { content: [{ type: 'text', text: `Exported ${rows.length} observations:${cap}\n${output}` }] };
   })
 );
@@ -1988,20 +2080,20 @@ server.registerTool(
     inputSchema: memFtsCheckSchema,
   },
   safeHandler(async (args) => {
+    // T3-P2-C: Zod `action: z.enum(['check','rebuild'])` filters any other value before we
+    // reach this handler, so there's no "Unknown action" fallback to write.
     if (args.action === 'check') {
       const result = checkFTSIntegrity(db);
       return { content: [{ type: 'text', text: result.healthy
         ? 'FTS5 indexes are healthy — all integrity checks passed.'
         : `FTS5 issues found:\n${result.details.join('\n')}` }] };
     }
-    if (args.action === 'rebuild') {
-      const result = rebuildFTS(db);
-      const summary = result.errors.length > 0
-        ? `Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`
-        : `Successfully rebuilt: ${result.rebuilt.join(', ')}`;
-      return { content: [{ type: 'text', text: summary }] };
-    }
-    return { content: [{ type: 'text', text: `Unknown action: ${args.action}` }], isError: true };
+    // args.action === 'rebuild'
+    const result = rebuildFTS(db);
+    const summary = result.errors.length > 0
+      ? `Rebuilt: ${result.rebuilt.join(', ')}. Errors: ${result.errors.join(', ')}`
+      : `Successfully rebuilt: ${result.rebuilt.join(', ')}`;
+    return { content: [{ type: 'text', text: summary }] };
   })
 );
 

package/tool-schemas.mjs

@@ -50,8 +50,8 @@ export const memRecentSchema = {
 };
 
 export const memTimelineSchema = {
-  anchor: coerceInt.pipe(z.number().int()).optional().describe('Observation ID as center point'),
-  query: z.string().optional().describe('FTS5 query to auto-find anchor'),
+  anchor: coerceInt.pipe(z.number().int()).optional().describe('Observation ID as center point. Takes precedence over query when both are provided.'),
+  query: z.string().optional().describe('FTS5 query to auto-find anchor. Ignored when anchor is also given; use one or the other.'),
   before: coerceInt.pipe(z.number().int().min(0).max(50)).optional().describe('Items before anchor (default 5)'),
   after: coerceInt.pipe(z.number().int().min(0).max(50)).optional().describe('Items after anchor (default 5)'),
   project: z.string().optional().describe('Filter by project'),
@@ -96,18 +96,22 @@ export const memOptimizeSchema = {
     .describe('Which optimization tasks to run (default: all)'),
   max_items: coerceInt.pipe(z.number().int().min(1).max(100)).optional().default(15)
     .describe('Maximum LLM calls across all tasks (default: 15)'),
+  scope: z.enum(['narrow', 'wide']).optional().default('narrow')
+    .describe("Re-enrich scope: narrow=narrative-only candidates (default); wide=R-7 backfill (bugfix/refactor/feature/decision with narrative but lesson_learned='none'). CLI parity: --scope wide."),
 };
 
 export const memMaintainSchema = {
   action: z.enum(['scan', 'execute']).describe('scan=analyze candidates, execute=apply changes'),
   operations: z.array(z.enum(['dedup', 'decay', 'cleanup', 'boost', 'purge_stale', 'rebuild_vectors'])).optional()
-    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, purge_stale=delete decayed obs (needs confirm via scan first), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors'),
+    .describe('Operations: dedup=find/merge duplicate observations, decay=reduce importance of old low-value obs, cleanup=remove orphaned records, boost=promote frequently-accessed obs, purge_stale=DELETE pending-purge obs older than retain_days (requires confirm=true; first call previews), rebuild_vectors=rebuild TF-IDF vocabulary and all observation vectors'),
   merge_ids: z.preprocess(
     (v) => Array.isArray(v) ? v.map(g => Array.isArray(g) ? g.map(x => typeof x === 'string' ? parseInt(x, 10) : x) : g) : v,
     z.array(z.array(z.number().int()).min(2))
   ).optional().describe('For dedup: [[keepId, removeId1, removeId2], ...] — first ID in each group is kept'),
   retain_days: coerceInt.pipe(z.number().int().min(7).max(365)).optional()
     .describe('For purge_stale: keep observations newer than N days (default 30)'),
+  confirm: coerceBool.optional()
+    .describe('Required for destructive ops in `execute` mode (currently: purge_stale). Omit/false → dry-run preview; true → actually delete.'),
   project: z.string().optional().describe('Filter by project'),
 };