@lh8ppl/claude-memory-kit 0.2.1 → 0.2.3

package/src/mcp-server.mjs

@@ -1,9 +1,10 @@
 // MCP server (Task 31, T-027). Layer 5's final task — closes Layer 5.
 //
-// Per design §10 + tasks.md 31:
+// Per design §10 + tasks.md 31 + ADR-0014 (Task 108b parity):
 //   - stdio JSON-RPC transport per MCP 2025-06-18 spec
-//   - Six tools: mk_search, mk_get, mk_timeline, mk_cite, mk_remember,
-//     mk_recent_activity
+//   - Eleven tools (full CLI parity): READ — mk_search, mk_get, mk_timeline,
+//     mk_cite, mk_recent_activity; WRITE/MUTATE — mk_remember, mk_trust,
+//     mk_lessons_promote, mk_forget, mk_queue_list, mk_queue_resolve
 //   - Path-traversal validation on every read/write surface
 //   - All logs to stderr (or sessions/{date}.mcp.log); stdout pure
 //
@@ -18,7 +19,7 @@
 // handshake + tool listing. We register tool handlers; the SDK handles
 // the protocol envelope.
 //
-// Lior 2026-05-23 decision: @modelcontextprotocol/sdk library naming
+// The user's 2026-05-23 decision: @modelcontextprotocol/sdk library naming
 // goes in tasks.md Task 31 implementation, NOT in design.md. This
 // module is where the dep choice lands.
 //
@@ -32,12 +33,29 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { resolve as resolvePath, isAbsolute } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { resolve as resolvePath, isAbsolute, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { openIndexDb } from './index-db.mjs';
 import { reindexBoot } from './index-rebuild.mjs';
 import { search, SEARCH_MODES } from './search.mjs';
 import { memoryWrite } from './memory-write.mjs';
-import { ID_PATTERN, resolveTierRoot } from './tier-paths.mjs';
+import { rememberRich, nonProjectTierNote } from './remember-core.mjs';
+import { forget } from './forget.mjs';
+import { overrideTrust } from './trust.mjs';
+import { lessonsPromote } from './lessons-promote.mjs';
+import { resolveReviewQueue, listReviewQueue } from './review-queue.mjs';
+import { resolveConflictQueue, listConflictQueue } from './conflict-queue.mjs';
+import { createHash } from 'node:crypto';
+import { getObservations, citeLink, buildTimeline, recentActivity } from './read-core.mjs';
+import { resolveTierRoot } from './tier-paths.mjs';
+
+// The kit version, read from package.json — NOT hardcoded. A hardcoded '0.1.0'
+// shipped through the v0.2.3 cut and advertised the WRONG version to the MCP
+// client (D-102 / Task 121.1). PKG_ROOT is one level up from src/.
+const PKG_VERSION = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'),
+).version;
 
 // --- Path-traversal validation (design §10.2; tasks.md 31.2) ----------
 
@@ -112,130 +130,106 @@ function makeMkSearch({ db, semanticBackend }) {
 }
 
 function makeMkGet({ db }) {
-  return async ({ ids }) => {
-    const stmt = db.prepare(`
-      SELECT id, body, heading_path, source_file, source_line, tier, trust,
-             write_source, created_at, superseded_by, deleted_at
-      FROM observations WHERE id = ?
-    `);
-    const rows = ids.map((id) => {
-      if (!ID_PATTERN.test(id)) {
-        return { id, error: 'invalid id format' };
-      }
-      const row = stmt.get(id);
-      if (!row) return { id, error: 'not found' };
-      return row;
-    });
-    return {
-      content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }],
-    };
-  };
+  // Thin adapter over the shared read core (read-core.getObservations) — the
+  // SAME logic the CLI `cmk get` calls (ADR-0014 parity).
+  return async ({ ids }) => ({
+    content: [{ type: 'text', text: JSON.stringify(getObservations(db, ids), null, 2) }],
+  });
 }
 
 function makeMkTimeline({ db }) {
-  // Sequential context around an anchor ID or timestamp. v0.1.0 keeps
-  // the implementation deliberately narrow: anchor by ID; return the
-  // N observations before + N after by created_at order.
+  // Thin adapter over read-core.buildTimeline (shared with CLI `cmk timeline`).
   return async ({ anchor, depth_before, depth_after }) => {
-    const before = depth_before ?? 5;
-    const after = depth_after ?? 5;
-    if (!ID_PATTERN.test(anchor)) {
-      return {
-        content: [{ type: 'text', text: 'error: anchor must be a valid kit ID' }],
-        isError: true,
-      };
-    }
-    const anchorRow = db
-      .prepare('SELECT created_at, tier FROM observations WHERE id = ?')
-      .get(anchor);
-    if (!anchorRow) {
-      return {
-        content: [{ type: 'text', text: 'error: anchor not found' }],
-        isError: true,
-      };
+    const r = buildTimeline(db, {
+      anchor,
+      depthBefore: depth_before ?? 5,
+      depthAfter: depth_after ?? 5,
+    });
+    if (!r.ok) {
+      return { content: [{ type: 'text', text: `error: ${r.error}` }], isError: true };
     }
-    // M2: id tiebreaker on observations with identical created_at —
-    // without it, observations created the same millisecond fall out
-    // of the timeline non-deterministically. Same fix in afterRows.
-    const beforeRows = db
-      .prepare(`
-        SELECT id, body, source_file, source_line, tier, trust, created_at
-        FROM observations
-        WHERE created_at < ? AND deleted_at IS NULL
-        ORDER BY created_at DESC, id DESC LIMIT ?
-      `)
-      .all(anchorRow.created_at, before);
-    const anchorFull = db
-      .prepare(`
-        SELECT id, body, source_file, source_line, tier, trust, created_at
-        FROM observations WHERE id = ?
-      `)
-      .get(anchor);
-    const afterRows = db
-      .prepare(`
-        SELECT id, body, source_file, source_line, tier, trust, created_at
-        FROM observations
-        WHERE created_at > ? AND deleted_at IS NULL
-        ORDER BY created_at ASC, id ASC LIMIT ?
-      `)
-      .all(anchorRow.created_at, after);
-    const timeline = [...beforeRows.reverse(), anchorFull, ...afterRows];
-    return {
-      content: [{ type: 'text', text: JSON.stringify(timeline, null, 2) }],
-    };
+    return { content: [{ type: 'text', text: JSON.stringify(r.timeline, null, 2) }] };
   };
 }
 
 function makeMkCite() {
-  // Pure formatting — no DB query needed. The canonical citation link
-  // form is documented in design §10's tool table:
-  //   `[#P-S79MJHFN](memkit://obs/P-S79MJHFN)`
+  // Thin adapter over read-core.citeLink (shared with CLI `cmk cite`). The
+  // canonical link form is `[#P-S79MJHFN](memkit://obs/P-S79MJHFN)`.
   return async ({ id }) => {
-    if (!ID_PATTERN.test(id)) {
-      return {
-        content: [{ type: 'text', text: 'error: id must match ID_PATTERN' }],
-        isError: true,
-      };
+    const r = citeLink(id);
+    if (!r.ok) {
+      return { content: [{ type: 'text', text: `error: ${r.error}` }], isError: true };
     }
-    const link = `[#${id}](memkit://obs/${id})`;
-    return {
-      content: [{ type: 'text', text: link }],
-    };
+    return { content: [{ type: 'text', text: r.link }] };
   };
 }
 
 function makeMkRemember({ projectRoot, userDir }) {
-  return async ({ text, tier, cites }) => {
-    // I1 + I2 boundary checks (Task 31 code-review):
-    // - cites: memory-write doesn't currently wire cites → provenance.
-    //   Silently dropping the array would tell the model "your citation
-    //   was recorded" — false. Reject with "not yet supported" until
-    //   memoryWrite gains a cites parameter (v0.1.x).
-    // - tier 'U': the kit's user-tier templates (USER.md / HABITS.md /
-    //   LESSONS.md) don't have MEMORY.md + 'Active Threads' section,
-    //   so memoryWrite would fail with NOT_FOUND. v0.1.0 mk_remember
-    //   only writes to project-tier MEMORY.md. (v0.1.x: parameterize
-    //   scratchpad routing per tier.)
+  return async ({ text, tier, cites, why, how, type, title, links }) => {
+    // cites: memoryWrite doesn't wire cites → provenance yet. Silently dropping
+    // the array would tell the model "your citation was recorded" — false — so
+    // reject it clearly (the fact's own text is still captured if resubmitted
+    // without cites). Tracked in design §16.39.
     if (Array.isArray(cites) && cites.length > 0) {
       return {
         content: [
           {
             type: 'text',
-            text: 'error: cites parameter not yet supported by mk_remember (v0.1.x — see design §16.x). Submit the text without cites for now.',
+            text: 'error: the `cites` parameter is not recorded yet — resubmit the fact without it (reference related facts via `links` for [[cross-links]]).',
           },
         ],
         isError: true,
       };
     }
-    if (tier === 'U' || tier === 'L') {
+    // tier U/L: mk_remember writes the PROJECT tier (P) regardless; a fact
+    // becomes cross-project via mk_lessons_promote, not a direct tier write
+    // (direct U/L routing is the deferred feature in design §16.40). We do NOT error — we
+    // capture at P and attach the note, CONSISTENTLY with `cmk remember`. The
+    // three adapter paths had diverged (MCP error / CLI-rich warn / CLI-terse
+    // error); the note now comes from ONE shared source (D-102 / design §16.40).
+    const tierNote = tier === 'U' || tier === 'L' ? nonProjectTierNote(tier) : null;
+    // Task 108b — MCP write parity: when rich fields (why/how/type/title/links)
+    // are present, route to the SAME shared core (remember-core.rememberRich)
+    // the CLI `cmk remember --why/--how` uses → a granular Why/How fact file, not
+    // a terse MEMORY.md bullet. Identical fact files from both surfaces (ADR-0014).
+    if (why || how || type || title || links) {
+      const rr = rememberRich(text, { why, how, type, title, links }, { projectRoot });
+      if (rr.action === 'error') {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `error (${rr.errorCategory ?? 'unknown'}): ${(rr.errors ?? [rr.errorCategory ?? 'error']).join('; ')}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      if (rr.action === 'skipped') {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                { accepted: true, status: 'skipped', skip_reason: rr.skipReason, id: rr.id, written_to: rr.path },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
       return {
         content: [
           {
             type: 'text',
-            text: `error: mk_remember in v0.1.0 only writes to tier 'P' (project). tier '${tier}' will be supported in v0.1.x when scratchpad routing is parameterized.`,
+            text: JSON.stringify(
+              { id: rr.id, written_to: rr.path, accepted: true, action: rr.action, kind: 'rich', ...(tierNote && { tier_note: tierNote }) },
+              null,
+              2,
+            ),
           },
         ],
-        isError: true,
       };
     }
     const r = memoryWrite({
@@ -291,7 +285,7 @@ function makeMkRemember({ projectRoot, userDir }) {
         {
           type: 'text',
           text: JSON.stringify(
-            { id: r.id, written_to: r.path, accepted: true, action: r.action },
+            { id: r.id, written_to: r.path, accepted: true, action: r.action, ...(tierNote && { tier_note: tierNote }) },
             null,
             2,
           ),
@@ -302,35 +296,195 @@ function makeMkRemember({ projectRoot, userDir }) {
 }
 
 function makeMkRecentActivity({ db }) {
-  const WINDOWS = {
-    '1h': 60 * 60 * 1000,
-    '24h': 24 * 60 * 60 * 1000,
-    '7d': 7 * 24 * 60 * 60 * 1000,
-  };
+  // Thin adapter over read-core.recentActivity (shared with CLI
+  // `cmk recent-activity`).
   return async ({ window, limit }) => {
-    const w = window ?? '24h';
-    if (!WINDOWS[w]) {
+    const r = recentActivity(db, { window: window ?? '24h', limit: limit ?? 20 });
+    if (!r.ok) {
+      return { content: [{ type: 'text', text: `error: ${r.error}` }], isError: true };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(r.rows, null, 2) }] };
+  };
+}
+
+// --- Mutate tools (Task 108b — MCP parity with the CLI) ---------------
+//
+// These wrap the existing CLI cores (forget / overrideTrust / lessonsPromote)
+// so the model can perform the same mutations the user could via `cmk`. Per
+// D-85: the user never types `cmk`; the conversation is the interface, so every
+// mutate the CLI offers needs an MCP path the model can drive on their behalf.
+
+/** Map a core error / not-found result to an MCP isError envelope. */
+function mcpToolError(r) {
+  const msg = r.action === 'error'
+    ? `error (${r.errorCategory ?? 'unknown'}): ${(r.errors ?? ['operation failed']).join('; ')}`
+    : `error: ${(r.errors ?? ['not found']).join('; ')}`;
+  return { content: [{ type: 'text', text: msg }], isError: true };
+}
+
+/**
+ * Deterministic confirm token for a destructive op. Derived from id + body so a
+ * caller CANNOT produce it without first seeing the preview (the digest is not
+ * knowable from the id alone) — that forces the two-step preview→confirm flow.
+ * Stable across re-calls (idempotent), so a retried confirm with the same token
+ * still works. sha256 (not sha1) — not because this is a crypto-sensitive
+ * context (it's a preview-fingerprint nonce, not auth/signing), but so static
+ * analysis isn't tripped by a "weak hash" smell on a brand-new code path.
+ */
+function forgetConfirmToken(id, body) {
+  return createHash('sha256').update(`${id}:${body ?? ''}`).digest('hex').slice(0, 8);
+}
+
+function makeMkTrust({ projectRoot, userDir }) {
+  return async ({ id, level }) => {
+    const r = overrideTrust({ id, level, projectRoot, userDir, actor: 'mcp-user-explicit' });
+    if (r.action !== 'trust-updated') return mcpToolError(r);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(
+        { accepted: true, action: r.action, id: r.id, tier: r.tier, level: r.level }, null, 2,
+      ) }],
+    };
+  };
+}
+
+function makeMkLessonsPromote({ projectRoot, userDir }) {
+  return async ({ id, to }) => {
+    const r = lessonsPromote({ id, projectRoot, userDir, to: to ?? 'LESSONS.md' });
+    if (r.action !== 'promoted' && r.action !== 'queued') return mcpToolError(r);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(
+        {
+          accepted: true,
+          action: r.action,
+          id: r.id,
+          target: r.target,
+          section: r.section,
+          ...(r.action === 'queued'
+            ? { status: 'queued', hint: 'Promotion routed to the user-tier review/conflict queue — it lands once resolved.' }
+            : {}),
+        }, null, 2,
+      ) }],
+    };
+  };
+}
+
+function makeMkForget({ projectRoot, userDir }) {
+  return async ({ id, reason, confirm }) => {
+    // Dry pass: resolve + capture the preview via a confirm callback that
+    // refuses (returns false → action:'cancelled'), so nothing is deleted yet.
+    // A not-found / ambiguous / schema error short-circuits BEFORE the callback.
+    let preview = null;
+    const dry = forget({
+      idOrQuery: id,
+      projectRoot,
+      userDir,
+      reason,
+      confirm: (p) => { preview = p; return false; },
+    });
+    if (dry.action !== 'cancelled' || !preview) {
+      return mcpToolError(dry);
+    }
+
+    const token = forgetConfirmToken(preview.id, preview.body);
+    if (confirm !== token) {
+      // Step 1 — preview + issue the token; require a second deliberate call.
       return {
-        content: [{ type: 'text', text: 'error: window must be 1h|24h|7d' }],
-        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(
+          {
+            status: 'confirm_required',
+            would_tombstone: {
+              id: preview.id,
+              tier: preview.tier,
+              title: preview.title ?? null,
+              path: preview.path,
+              body_preview: String(preview.body ?? '').slice(0, 280),
+            },
+            confirm_token: token,
+            hint: `Permanently tombstones this fact (audit trail preserved). To proceed, call mk_forget again with confirm: "${token}".`,
+          }, null, 2,
+        ) }],
       };
     }
-    const lim = limit ?? 20;
-    const cutoff = Date.now() - WINDOWS[w];
-    const rows = db
-      .prepare(`
-        SELECT id, body, source_file, source_line, tier, trust, created_at
-        FROM observations
-        WHERE created_at >= ? AND deleted_at IS NULL
-        ORDER BY created_at DESC LIMIT ?
-      `)
-      .all(cutoff, lim);
+
+    // Step 2 — token matches → execute.
+    const r = forget({ idOrQuery: id, projectRoot, userDir, reason, yes: true });
+    if (r.action !== 'tombstoned') return mcpToolError(r);
     return {
-      content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }],
+      content: [{ type: 'text', text: JSON.stringify(
+        { accepted: true, action: 'tombstoned', id: r.id, tier: r.tier, tombstoned_to: r.tombstonePath }, null, 2,
+      ) }],
     };
   };
 }
 
+// The review/conflict queues resolve via interactive walkers that take a
+// `prompter(entry) → decision` callback. Two callback shapes give a clean,
+// non-interactive MCP surface over them WITHOUT duplicating the walk logic:
+//   - LIST: a prompter that records each entry + returns 'skip' (mutates
+//     nothing) — so the model can see what's pending and tell the user.
+//   - RESOLVE: a prompter that returns the requested action for the matching
+//     id and 'skip' for every other entry — resolves exactly one item.
+// 'merge-both' is excluded from mk_queue_resolve: it composes the two facts'
+// content (mergeFacts needs a merged body), which is an interactive decision —
+// the model is pointed at `cmk queue conflicts` for that.
+
+function makeMkQueueList({ projectRoot, userDir }) {
+  return async ({ queue }) => {
+    const q = queue ?? 'review';
+    if (q !== 'review' && q !== 'conflicts') {
+      return mcpToolError({ action: 'error', errorCategory: 'schema', errors: [`queue must be 'review' or 'conflicts' (got ${q})`] });
+    }
+    // PURE READ (code-review SR-1): list via the dedicated read helpers, NOT the
+    // resolve* walkers — those reserialize + rewrite the queue file on every call,
+    // so listing through them would mutate (mtime churn / reformat / concurrent-
+    // resolve race) on a read-only op. listReviewQueue / listConflictQueue parse
+    // the file without writing.
+    try {
+      const entries = q === 'review'
+        ? listReviewQueue({ tier: 'P', projectRoot, userDir })
+        : listConflictQueue({ tier: 'P', projectRoot, userDir });
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ queue: q, pending: entries.length, entries }, null, 2) }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `error: ${err?.message ?? err}` }], isError: true };
+    }
+  };
+}
+
+function makeMkQueueResolve({ projectRoot, userDir }) {
+  return async ({ queue, id, action }) => {
+    const q = queue ?? 'review';
+    if (q === 'review') {
+      if (action !== 'promote' && action !== 'discard') {
+        return mcpToolError({ action: 'error', errorCategory: 'schema', errors: [`review action must be 'promote' or 'discard' (got ${action})`] });
+      }
+      const prompter = async (e) => (e.id === id ? action : 'skip');
+      const r = await resolveReviewQueue({ tier: 'P', projectRoot, userDir, prompter });
+      if (r.action === 'error') return mcpToolError(r);
+      const count = action === 'promote' ? r.promoted : r.discarded;
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ accepted: count > 0, queue: 'review', id, action, result: r }, null, 2) }],
+      };
+    }
+    if (q === 'conflicts') {
+      if (action === 'merge-both') {
+        return mcpToolError({ action: 'error', errorCategory: 'schema', errors: ["merge-both composes the two facts' content — run `cmk queue conflicts` for an interactive merge. mk_queue_resolve supports 'keep-old' / 'keep-new'."] });
+      }
+      if (action !== 'keep-old' && action !== 'keep-new') {
+        return mcpToolError({ action: 'error', errorCategory: 'schema', errors: [`conflict action must be 'keep-old' or 'keep-new' (got ${action})`] });
+      }
+      const prompter = async (e) => (e.proposedId === id ? action : 'skip');
+      const r = await resolveConflictQueue({ tier: 'P', projectRoot, userDir, prompter });
+      if (r.action === 'error') return mcpToolError(r);
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ accepted: r.resolved > 0, queue: 'conflicts', id, action, result: r }, null, 2) }],
+      };
+    }
+    return mcpToolError({ action: 'error', errorCategory: 'schema', errors: [`queue must be 'review' or 'conflicts' (got ${q})`] });
+  };
+}
+
 // --- Server build + run ----------------------------------------------
 
 /**
@@ -344,7 +498,7 @@ function makeMkRecentActivity({ db }) {
 export function buildMcpServer({ projectRoot, userDir, db, semanticBackend }) {
   const server = new McpServer({
     name: 'cmk',
-    version: '0.1.0',
+    version: PKG_VERSION,
   });
 
   // mk_search
@@ -414,8 +568,15 @@ export function buildMcpServer({ projectRoot, userDir, db, semanticBackend }) {
       description: 'Explicit user-driven save to kit memory with audit trail.',
       inputSchema: {
         text: z.string().min(1).max(5000).describe('the fact text (max 5000 chars)'),
-        tier: z.enum(['U', 'P', 'L']).optional(),
-        cites: z.array(z.string()).optional(),
+        tier: z.enum(['U', 'P', 'L']).optional().describe("target tier (default P). U/L are captured to the project tier (P) with a note — use mk_lessons_promote to make a fact cross-project"),
+        cites: z.array(z.string()).optional().describe('not recorded yet — omit it'),
+        // Task 108b — rich capture parity with the CLI `cmk remember --why/--how`.
+        // Any of these routes to a granular Why/How fact file (not a terse bullet).
+        why: z.string().max(5000).optional().describe('rich: the rationale (the **Why:** block)'),
+        how: z.string().max(5000).optional().describe('rich: how to apply it (the **How to apply:** block)'),
+        type: z.enum(['feedback', 'project', 'reference', 'user']).optional().describe('rich: fact type (default feedback)'),
+        title: z.string().max(200).optional().describe('rich: short title (also the fact-file slug)'),
+        links: z.array(z.string()).optional().describe('rich: related fact names for [[cross-links]]'),
       },
     },
     makeMkRemember({ projectRoot, userDir }),
@@ -425,7 +586,7 @@ export function buildMcpServer({ projectRoot, userDir, db, semanticBackend }) {
   server.registerTool(
     'mk_recent_activity',
     {
-      description: 'List recent observation changes within a time window.',
+      description: 'List recently added observations within a time window (by creation time).',
       inputSchema: {
         window: z.enum(['1h', '24h', '7d']).optional(),
         limit: z.number().int().positive().max(1000).optional(),
@@ -434,6 +595,74 @@ export function buildMcpServer({ projectRoot, userDir, db, semanticBackend }) {
     makeMkRecentActivity({ db }),
   );
 
+  // mk_trust (Task 108b — mutate parity). Reversible; audited.
+  server.registerTool(
+    'mk_trust',
+    {
+      description: 'Override the trust level (low|medium|high) of a fact or bullet by ID. Reversible + audited. Parity with `cmk trust`.',
+      inputSchema: {
+        id: z.string().describe('kit observation ID'),
+        level: z.enum(['low', 'medium', 'high']).describe('the new trust level'),
+      },
+    },
+    makeMkTrust({ projectRoot, userDir }),
+  );
+
+  // mk_lessons_promote (Task 108b — mutate parity). Sanitized + audited.
+  server.registerTool(
+    'mk_lessons_promote',
+    {
+      description: 'Promote a project-tier (P-) fact to the cross-project user tier so it applies in every project. Sanitized + secret-screened + audited. Parity with `cmk lessons promote`.',
+      inputSchema: {
+        id: z.string().describe('kit observation ID (a project-tier P- fact)'),
+        to: z.enum(['USER.md', 'HABITS.md', 'LESSONS.md']).optional().describe('target user-tier file (default LESSONS.md)'),
+      },
+    },
+    makeMkLessonsPromote({ projectRoot, userDir }),
+  );
+
+  // mk_forget (Task 108b — DESTRUCTIVE mutate parity). Two-step confirm-token:
+  // the first call previews + returns a confirm_token; call again with that
+  // token to execute. Tombstones (audit trail preserved), never hard-deletes.
+  server.registerTool(
+    'mk_forget',
+    {
+      description: 'Tombstone (forget) a fact by ID. DESTRUCTIVE + two-step: the first call previews what would be removed and returns a confirm_token; call again with confirm set to that token to execute. Audit trail preserved. Parity with `cmk forget`.',
+      inputSchema: {
+        id: z.string().describe('kit observation ID to tombstone'),
+        reason: z.string().max(500).optional().describe('why it is being forgotten (audited)'),
+        confirm: z.string().optional().describe('the confirm_token from the preview call — required to actually delete'),
+      },
+    },
+    makeMkForget({ projectRoot, userDir }),
+  );
+
+  // mk_queue_list (Task 108b — queue parity). Read-only: show pending entries.
+  server.registerTool(
+    'mk_queue_list',
+    {
+      description: "List pending entries in the review queue (medium-trust auto-extracts awaiting promotion) or the conflict queue (writes that clashed with existing facts). Read-only. Parity with `cmk queue review` / `cmk queue conflicts`.",
+      inputSchema: {
+        queue: z.enum(['review', 'conflicts']).optional().describe("which queue (default 'review')"),
+      },
+    },
+    makeMkQueueList({ projectRoot, userDir }),
+  );
+
+  // mk_queue_resolve (Task 108b — queue parity). Resolve one entry by id.
+  server.registerTool(
+    'mk_queue_resolve',
+    {
+      description: "Resolve one queued entry by ID. review: 'promote' (land it in MEMORY.md at high trust) | 'discard'. conflicts: 'keep-old' | 'keep-new' (merge-both composes content — use `cmk queue conflicts`). Audited.",
+      inputSchema: {
+        queue: z.enum(['review', 'conflicts']).describe('which queue the entry is in'),
+        id: z.string().describe('the queued entry ID to resolve'),
+        action: z.enum(['promote', 'discard', 'keep-old', 'keep-new', 'merge-both']).describe('review: promote|discard; conflicts: keep-old|keep-new (merge-both → use `cmk queue conflicts`)'),
+      },
+    },
+    makeMkQueueResolve({ projectRoot, userDir }),
+  );
+
   return server;
 }
 

package/src/merge-facts.mjs

@@ -168,6 +168,10 @@ export function mergeFacts(opts = {}) {
     tags: mergedTags,
     projectRoot,
     userDir,
+    // A merge emits its own richer `merged`/CURATED_MERGE audit below — suppress
+    // writeFact's default `created` entry so the merge logs exactly one event
+    // (Task 123.A opt-out).
+    audit: false,
   });
   if (writeResult.action === 'error') {
     return errorResult({

package/src/persona-portability.mjs

@@ -26,6 +26,7 @@ import {
   statSync,
   renameSync,
   unlinkSync,
+  copyFileSync,
 } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { reindex } from './reindex.mjs';
@@ -142,7 +143,7 @@ function rollbackImport(created, renamed) {
     try {
       if (existsSync(bkp)) {
         mkdirSync(dirname(dest), { recursive: true });
-        renameSync(bkp, dest);
+        restoreBackup(bkp, dest);
       }
     } catch {
       /* best-effort — the backup copy still exists for manual recovery */
@@ -150,6 +151,28 @@ function rollbackImport(created, renamed) {
   }
 }
 
+// Restore a backed-up file over `dest` (Task 116.x). `dest` may already hold the
+// half-applied NEW content (Phase-2 write before the failure), so this OVERWRITES
+// it. The old code used `renameSync(bkp, dest)`, but renaming ONTO an existing
+// file can intermittently throw EPERM/EBUSY on Windows under heavy parallel FS
+// load — and rollbackImport's silent catch then left the un-rolled-back NEW file
+// in place (the rare persona-portability rollback flake). `copyFileSync` overwrites
+// the destination reliably on every platform; a short retry covers a transient
+// lock. The backup is removed only after a confirmed copy.
+export function restoreBackup(bkp, dest) {
+  let lastErr;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      copyFileSync(bkp, dest);
+      try { unlinkSync(bkp); } catch { /* backup cleanup best-effort */ }
+      return;
+    } catch (err) {
+      lastErr = err; // transient EPERM/EBUSY under load — retry
+    }
+  }
+  throw lastErr;
+}
+
 // Apply the bundle's files TRANSACTIONALLY (the Task-91 rollback discipline):
 // back up every existing target first, then write all files, and if ANY write
 // fails partway, roll the whole thing back so a mid-import disk/permission error