@lh8ppl/claude-memory-kit 0.2.2 → 0.2.4

package/src/subcommands.mjs

@@ -26,9 +26,9 @@ import { weeklyCurate } from './weekly-curate.mjs';
 import { autoPersona } from './auto-persona.mjs';
 import { exportPersona, importPersona } from './persona-portability.mjs';
 import { setNativeAutoMemory, nativeMemoryInstallNote } from './native-memory.mjs';
-import { writeFact } from './write-fact.mjs';
-import { buildRichFactBody, slugifyFact } from './rich-fact.mjs';
-import { createHash } from 'node:crypto';
+import { rememberRich, richFactTitle, nonProjectTierNote } from './remember-core.mjs';
+import { getObservations, citeLink, buildTimeline, recentActivity } from './read-core.mjs';
+import { readHookStdin } from './read-hook-stdin.mjs';
 import { runLazyCompress } from './lazy-compress.mjs';
 import { runDoctor } from './doctor.mjs';
 import { importAnthropicMemory } from './import-anthropic-memory.mjs';
@@ -61,7 +61,7 @@ import { resolveReviewQueue } from './review-queue.mjs';
 import { createInterface } from 'node:readline';
 import { resolve as resolvePath, join, basename } from 'node:path';
 
-const NOTICE_PREFIX = 'not yet implemented in v0.1.0';
+const NOTICE_PREFIX = 'not yet implemented';
 
 /**
  * Real `cmk install` action — wired in Task 3, extended in Task 4 with
@@ -249,10 +249,11 @@ function runLessonsPromote(id, options = {}) {
 /**
  * `cmk search` — Task 30. Hybrid keyword + optional semantic.
  *
- * v0.1.0 ships the keyword backend (FTS5 BM25 over the observations
- * index). Semantic + hybrid modes require the Layer 5b memsearch+Milvus
- * install which isn't bundled in v0.1.0; both error with exit code 2
- * and a clear "memsearch not installed" hint per tasks.md 30.2.
+ * The keyword backend (FTS5 BM25 over the observations index) always
+ * ships. Semantic + hybrid modes require the Layer-5b semantic backend,
+ * which is not yet shipped; both error with exit code 2 and a clear
+ * "not yet shipped" hint per tasks.md 30.2. The `semanticBackend` DI seam
+ * is the drop-in point for the future backend.
  *
  * Filter flags (per tasks.md 30.4):
  *   --mode <keyword|semantic|hybrid>   (default keyword)
@@ -323,6 +324,99 @@ function runSearch(queryParts, options) {
   }
 }
 
+// --- Read verbs (Task 108b — CLI parity with the MCP read tools) ------
+//
+// `cmk get` / `timeline` / `cite` / `recent-activity` mirror the MCP tools
+// mk_get / mk_timeline / mk_cite / mk_recent_activity by calling the SAME
+// shared read cores (read-core.mjs) — identical results from CLI + MCP
+// (ADR-0014). cite is pure (no DB); the rest open the index + reindex first
+// (same fresh-install freshness guard as `cmk search`).
+
+// `deps` (projectRoot / log / logError) are injection seams: production passes
+// nothing (defaults to cwd + console), in-process tests pass a temp projectRoot
+// + captured loggers so the glue is covered WITHOUT a subprocess (the D-86
+// lesson — real-binary tests don't contribute line coverage). Exported for the
+// unit tests.
+
+/** Open the index DB, refresh it (best-effort), run `fn(db)`, always close. */
+export function withReadDb(fn, deps = {}) {
+  const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
+  const userDir =
+    deps.userDir ?? process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
+  const logError = deps.logError ?? console.error;
+  const db = openIndexDb({ projectRoot });
+  try {
+    try {
+      reindexBoot({ projectRoot, userDir, db });
+    } catch (err) {
+      logError(`cmk: index refresh failed (${err?.message ?? err}); using the existing index.`);
+    }
+    return fn(db);
+  } finally {
+    db.close();
+  }
+}
+
+export function runGet(ids, _options = {}, _command, deps = {}) {
+  const log = deps.log ?? console.log;
+  const list = Array.isArray(ids) ? ids : [ids];
+  const rows = withReadDb((db) => getObservations(db, list), deps);
+  log(JSON.stringify(rows, null, 2));
+  // All-missing/invalid → exit 2 (lets a script tell "nothing matched" from a hit).
+  if (rows.length > 0 && rows.every((r) => r.error)) process.exitCode = 2;
+}
+
+export function runCite(id, _options = {}, _command, deps = {}) {
+  const log = deps.log ?? console.log;
+  const logError = deps.logError ?? console.error;
+  const r = citeLink(id);
+  if (!r.ok) {
+    logError(`cmk cite: ${r.error}`);
+    process.exitCode = 2;
+    return;
+  }
+  log(r.link);
+}
+
+export function runTimeline(anchor, options = {}, _command, deps = {}) {
+  const log = deps.log ?? console.log;
+  const logError = deps.logError ?? console.error;
+  const r = withReadDb(
+    (db) =>
+      buildTimeline(db, {
+        anchor,
+        depthBefore: options.before !== undefined ? Number(options.before) : 5,
+        depthAfter: options.after !== undefined ? Number(options.after) : 5,
+      }),
+    deps,
+  );
+  if (!r.ok) {
+    logError(`cmk timeline: ${r.error}`);
+    process.exitCode = 2;
+    return;
+  }
+  log(JSON.stringify(r.timeline, null, 2));
+}
+
+export function runRecentActivity(options = {}, _command, deps = {}) {
+  const log = deps.log ?? console.log;
+  const logError = deps.logError ?? console.error;
+  const r = withReadDb(
+    (db) =>
+      recentActivity(db, {
+        window: options.window ?? '24h',
+        limit: options.limit !== undefined ? Number(options.limit) : 20,
+      }),
+    deps,
+  );
+  if (!r.ok) {
+    logError(`cmk recent-activity: ${r.error}`);
+    process.exitCode = 2;
+    return;
+  }
+  log(JSON.stringify(r.rows, null, 2));
+}
+
 /**
  * `cmk reindex` — three modes.
  *
@@ -365,57 +459,27 @@ function runSearch(queryParts, options) {
  * carries injection seams for testing.
  */
 export function runRememberRich(text, options = {}, deps = {}) {
-  const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
   const log = deps.log ?? console.log;
   const logError = deps.logError ?? console.error;
-  const write = deps.writeFact ?? writeFact;
 
-  // M2: rich capture writes the project tier (P) in v0.1.x — same deferral as
-  // the terse path + mk_remember (U/L need per-tier scratchpad routing, design
-  // §16). Terse mode ERRORS on a non-P --tier; rich mode notes it and proceeds
-  // (a no-write surprise is worse than a captured-to-P note). Surface it so the
-  // divergence isn't silent.
+  // Non-P --tier: capture at the project tier (P) + surface the note (don't
+  // silently honor it, don't hard-error). ONE shared note across CLI + MCP so
+  // the message can't drift (D-102 / Task 121).
   if (options.tier && options.tier !== 'P') {
-    log(
-      `cmk remember: --tier '${options.tier}' is v0.1.x — rich capture writes the project tier (P) for now.`,
-    );
+    log(`cmk remember: ${nonProjectTierNote(options.tier)}`);
   }
 
-  const headline = String(text).trim();
-  const title = (options.title && String(options.title).trim()) || headline.split('\n')[0].slice(0, 80);
-  const body = buildRichFactBody({ text: headline, why: options.why, how: options.how });
-  const related = options.links
-    ? String(options.links).split(',').map((s) => s.trim()).filter(Boolean)
-    : undefined;
-
-  const r = write({
-    tier: 'P',
-    type: options.type ?? 'feedback',
-    slug: slugifyFact(title),
-    title,
-    body,
-    writeSource: 'user-explicit',
-    trust: options.trust ?? 'high',
-    sourceFile: 'user-explicit',
-    sourceLine: 1,
-    // Content fingerprint for provenance/dedup — NOT a security context.
-    // Matches the kit's sha1-of-content convention (memory-write.mjs,
-    // index-rebuild.mjs); writeFact dedups by content-addressed id, this is
-    // just the source_sha1 provenance field. // NOSONAR
-    sourceSha1: createHash('sha1').update(body).digest('hex'), // NOSONAR
-
-    related,
-    projectRoot,
-  });
+  // The write is the shared core (remember-core.rememberRich) — the SAME one the
+  // MCP `mk_remember` rich path calls, so both surfaces emit identical fact files
+  // (ADR-0014). This wrapper only formats the CLI's messages from the result.
+  const r = rememberRich(text, options, deps);
 
   if (r.action === 'error') {
-    // M1: a collision means a fact file with this title (→ slug) already exists
-    // but with different content (different id). Give an actionable hint rather
-    // than the raw "refusing overwrite" — the user almost certainly wants to
-    // edit the existing fact or pick a new --title.
     if (r.errorCategory === 'collision') {
+      // M1: a same-title / different-content collision — actionable hint over
+      // the raw "refusing overwrite".
       logError(
-        `cmk remember: a fact titled "${title}" already exists with different content. ` +
+        `cmk remember: a fact titled "${richFactTitle(text, options)}" already exists with different content. ` +
           `Edit it directly, or capture under a new --title.`,
       );
       return r;
@@ -431,11 +495,128 @@ export function runRememberRich(text, options = {}, deps = {}) {
   return r;
 }
 
-function runRemember(textParts, options) {
-  const projectRoot = resolvePath(process.cwd());
+/**
+ * Task 108.2 (108a) — parse a structured fact from the off-shell input channel
+ * (`--from-file <path>` or `--json` stdin). PURE + dependency-injected (the CLI
+ * passes real fs readers; tests pass fakes) so every parse/validate/allowlist
+ * branch is covered IN-PROCESS — the real-binary subprocess tests prove the CLI
+ * wiring but don't contribute line coverage.
+ *
+ * @param {object} options - subcommand options (fromFile/json + the rich flags).
+ * @param {object} deps
+ * @param {(path:string)=>string} deps.readFile - read a file to a string (throws on error).
+ * @param {()=>string} deps.readStdin - read stdin to a string ('' for TTY/empty).
+ * @returns {{ok:true,channel:string,fields:object,ignored:string[]}
+ *          | {ok:false,channel:string,error:string,ignored:string[]}}
+ */
+export function parseFactInput(options, { readFile, readStdin } = {}) {
+  const channel = options.fromFile ? '--from-file' : '--json';
+  // --from-file/--json are self-contained (the JSON is the whole fact); rich /
+  // terse flags passed alongside are ignored — surfaced so they aren't dropped silently.
+  const ignored = ['why', 'how', 'type', 'title', 'links', 'tier', 'trust', 'section']
+    .filter((k) => options[k] != null)
+    .map((k) => '--' + k);
+  const fail = (error) => ({ ok: false, channel, error, ignored });
+
+  let raw;
+  if (options.fromFile) {
+    try {
+      raw = readFile(options.fromFile);
+    } catch (e) {
+      return fail(`${channel} could not read ${options.fromFile}: ${e.message}`);
+    }
+  } else {
+    // '' = interactive TTY or empty pipe (read-hook-stdin returns '' for a TTY).
+    raw = readStdin();
+    if (!raw || !raw.trim()) {
+      return fail('--json expects a JSON object on stdin (pipe it in, or use --from-file).');
+    }
+  }
+
+  // Bound the input so a pathological file can't burn Poison_Guard regex time
+  // (the M1 concern that capped mk_remember). 64 KB is generous for one fact.
+  const MAX_INPUT_BYTES = 64 * 1024;
+  if (Buffer.byteLength(raw, 'utf8') > MAX_INPUT_BYTES) {
+    return fail(`${channel} fact is too large (max ${MAX_INPUT_BYTES / 1024} KB). Split it into smaller facts.`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return fail(`${channel} could not parse JSON: ${e.message}`);
+  }
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    Array.isArray(parsed) ||
+    typeof parsed.text !== 'string' ||
+    !parsed.text.trim()
+  ) {
+    return fail(`${channel} JSON must be an object with a non-empty "text" field.`);
+  }
+
+  // Allowlist the honored fields — NEVER forward the raw parsed object. A crafted
+  // JSON must not reach a field runRememberRich might read; provenance
+  // (write_source / source_file) stays hardcoded user-explicit in runRememberRich.
+  return {
+    ok: true,
+    channel,
+    ignored,
+    fields: {
+      text: parsed.text,
+      why: parsed.why,
+      how: parsed.how,
+      type: parsed.type,
+      title: parsed.title,
+      links: parsed.links,
+      tier: parsed.tier,
+      trust: parsed.trust,
+    },
+  };
+}
+
+export function runRemember(textParts, options, deps = {}) {
+  const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
   const userDir =
-    process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
+    deps.userDir ?? process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
+  const log = deps.log ?? console.log;
+  const logError = deps.logError ?? console.error;
+
+  // Task 108.2 (108a) — structured off-shell input. `--from-file`/`--json` carry
+  // the fact as a JSON object from a FILE or STDIN, so rich content (backticks,
+  // $(), quotes, newlines) never rides the shell command line — the D-81 fix.
+  // The parse/validate/allowlist lives in the pure parseFactInput() helper.
+  if (options?.fromFile || options?.json) {
+    const parsed = parseFactInput(options, {
+      readFile: (p) => readFileSync(p, 'utf8'),
+      readStdin: () => readHookStdin({ isTTY: process.stdin.isTTY }),
+    });
+    if (parsed.ignored.length) {
+      logError(
+        `cmk remember: ${parsed.channel} is self-contained — ignoring ${parsed.ignored.join(', ')} (put these in the JSON instead).`,
+      );
+    }
+    if (!parsed.ok) {
+      logError(`cmk remember: ${parsed.error}`);
+      process.exitCode = 2;
+      return;
+    }
+    runRememberRich(parsed.fields.text, parsed.fields, { projectRoot, log, logError });
+    return;
+  }
+
   const text = Array.isArray(textParts) ? textParts.join(' ') : textParts;
+  // Bare `cmk remember` — no positional text and no input channel. The positional
+  // arg is optional now (for --from-file/--json), so guard explicitly instead of
+  // falling through to a vague empty-text write error.
+  if (!text || !String(text).trim()) {
+    logError(
+      'cmk remember: provide a fact to remember, or use --from-file <json> / --json (stdin).',
+    );
+    process.exitCode = 2;
+    return;
+  }
   // Rich mode: any of --why/--how/--type/--title/--links → write a real fact
   // file (the F1 fix) instead of a terse MEMORY.md bullet. M3: --trust and
   // --section are intentionally NOT triggers — --trust is shared by both forms
@@ -445,15 +626,15 @@ function runRemember(textParts, options) {
     runRememberRich(text, options, { projectRoot });
     return;
   }
-  const tier = options?.tier ?? 'P';
-  if (tier !== 'P') {
-    console.error(
-      `cmk remember: tier '${tier}' not yet supported — v0.1.0 writes the project tier (P). ` +
-        'For machine-only config, edit context.local/machine-paths.md directly (v0.1.x will add --tier routing).',
-    );
-    process.exitCode = 2;
-    return;
+  // Non-P --tier: capture at P + note (consistent with the rich path + the MCP
+  // tool — D-102). A fact becomes cross-project via `cmk lessons promote`, not a
+  // direct tier write (direct U/L routing is the deferred feature in design §16.40). We do NOT
+  // hard-error — losing the capture to an error is worse than landing it at P.
+  const requestedTier = options?.tier ?? 'P';
+  if (requestedTier !== 'P') {
+    log(`cmk remember: ${nonProjectTierNote(requestedTier)}`);
   }
+  const tier = 'P';
   const trust = options?.trust ?? 'high';
   const section = options?.section ?? 'Active Threads';
   const r = memoryWrite({
@@ -547,6 +728,11 @@ function runForget(idOrQuery, options /* , command */) {
   const result = forgetAction({
     idOrQuery,
     projectRoot,
+    // Pass the resolved userDir (same source as `cmk search`) so forget's
+    // in-band reindex covers all three tiers and its orphan-prune fires
+    // IMMEDIATELY (Task 110) — without it the prune is skipped here and only
+    // self-heals on the next search. Also lets forget tombstone U-tier facts.
+    userDir: resolveUserDir(),
     reason: options.reason,
     deletedBy: options.deletedBy,
     yes: true,
@@ -667,11 +853,19 @@ export async function runPersonaGenerate(opts = {}) {
   try {
     const backend =
       opts.backend ?? new (await import('./compressor.mjs')).HaikuViaAnthropicApi();
-    const r = await autoPersona({ projectRoot, userDir, backend });
+    // Task 111 (F-2): `cmk persona generate` is an explicit one-shot with NO outer
+    // hook ceiling (unlike the 60s-bounded SessionEnd path), so it gives the Haiku
+    // classifier generous headroom — the whole-project facts sweep is a heavier
+    // call than a session summary, and the user is willing to wait for the command
+    // they ran. The corpus is byte-capped (PERSONA_CORPUS_BYTES) so this can't run
+    // unbounded. Overridable via opts.timeoutMs.
+    const r = await autoPersona({ projectRoot, userDir, backend, timeoutMs: opts.timeoutMs ?? 120_000 });
     if (r.action === 'error') {
-      logError(
-        `cmk persona generate: error (${r.errorCategory ?? 'unknown'})${(r.errors && r.errors.length) ? `: ${r.errors.join('; ')}` : ''}`,
-      );
+      const detail = (r.errors && r.errors.length) ? `: ${r.errors.join('; ')}` : '';
+      const hint = /did not return within/.test(detail)
+        ? ' — the Haiku classifier timed out; this is usually a transient API slowdown. Re-run `cmk persona generate` (the weekly curate pass also retries it automatically).'
+        : '';
+      logError(`cmk persona generate: error (${r.errorCategory ?? 'unknown'})${detail}${hint}`);
       return;
     }
     const promoted = r.promoted?.length ?? 0;
@@ -795,9 +989,9 @@ function runRegisterCrons(options /* , command */) {
   // Helper: quote a path for the platform's cron-line shell.
   // Linux + macOS: double-quote (the cron line is single-quoted around the
   // whole `echo '...'`; double-quotes inside are safe).
-  // Windows: the schtasks /TR value is already double-quoted by registerCron,
-  // with `\"` escaping for inner quotes — registerCron's existing
-  // escapedCommand handles this.
+  // Windows: registerCron execs schtasks with an args array (no shell), so this
+  // double-quoted /TR value is delivered verbatim — no escaping needed (Task 109
+  // / D-83). macOS strips these wrapping quotes before building the plist.
   const quote = (s) => `"${s}"`;
 
   const jobs = [
@@ -988,40 +1182,44 @@ async function runRollCli(options /* , command */) {
   }
 }
 
-async function runImportAnthropicMemory(options /* , command */) {
-  const projectRoot = resolvePath(process.cwd());
+// Task 114 (F-13): dep-injectable (projectRoot / harnessRoot / log / logError) so
+// the real-import CLI path is verifiable on real input WITHOUT touching the user's
+// ~/.claude. Defaults are unchanged for production. Returns the core result.
+export async function runImportAnthropicMemory(options = {}) {
+  const projectRoot = options?.projectRoot ?? resolvePath(process.cwd());
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
   const dryRun = options?.dryRun === true;
   const acceptAll = options?.yes === true;
+  // options.importFn is a test seam (default = the real core) so the error +
+  // catch branches below — unreachable via normal input — are coverable.
+  const importFn = options?.importFn ?? importAnthropicMemory;
   try {
-    // I1 fix (skill-review 2026-05-28): userDir was unused, dropped.
-    const r = await importAnthropicMemory({ projectRoot, dryRun, acceptAll });
+    const r = await importFn({ projectRoot, dryRun, acceptAll, harnessRoot: options?.harnessRoot });
     if (r.action === 'error') {
-      console.error(`cmk import-anthropic-memory: error — ${(r.errors ?? []).join('; ')}`);
+      logError(`cmk import-anthropic-memory: error — ${(r.errors ?? []).join('; ')}`);
       process.exitCode = 2;
-      return;
+      return r;
     }
     if (r.reason === 'no-source') {
-      console.log(`cmk import-anthropic-memory: no Anthropic auto-memory found at ${r.sourcePath}`);
-      return;
+      log(`cmk import-anthropic-memory: no Anthropic auto-memory found at ${r.sourcePath}`);
+      return r;
     }
     if (r.mode === 'dry-run') {
-      console.log(`cmk import-anthropic-memory: dry-run — ${r.proposals.length} proposal(s), ${r.skipped} duplicate(s) skipped`);
-      for (const p of r.proposals) {
-        console.log(`  + ${p.id}: ${p.text}`);
-      }
-      return;
+      log(`cmk import-anthropic-memory: dry-run — ${r.proposals.length} proposal(s), ${r.skipped} duplicate(s) skipped`);
+      for (const p of r.proposals) log(`  + ${p.id}: ${p.text}`);
+      return r;
     }
     if (r.mode === 'requires-confirmation') {
-      console.log(`cmk import-anthropic-memory: ${r.proposals.length} proposal(s) ready to apply.`);
-      console.log('  Re-run with --yes to apply, or --dry-run to inspect.');
-      for (const p of r.proposals) {
-        console.log(`  + ${p.id}: ${p.text}`);
-      }
-      return;
+      log(`cmk import-anthropic-memory: ${r.proposals.length} proposal(s) ready to apply.`);
+      log('  Re-run with --yes to apply, or --dry-run to inspect.');
+      for (const p of r.proposals) log(`  + ${p.id}: ${p.text}`);
+      return r;
     }
-    console.log(`cmk import-anthropic-memory: applied ${r.accepted} proposal(s), skipped ${r.skipped} duplicate(s)`);
+    log(`cmk import-anthropic-memory: applied ${r.accepted} proposal(s), skipped ${r.skipped} duplicate(s)`);
+    return r;
   } catch (err) {
-    console.error(`cmk import-anthropic-memory: unexpected error: ${err?.message ?? err}`);
+    logError(`cmk import-anthropic-memory: unexpected error: ${err?.message ?? err}`);
     process.exitCode = 2;
   }
 }
@@ -1131,8 +1329,12 @@ async function runCompress(options /* , command */) {
 
 async function runMcpDispatch(childName) {
   if (childName === 'serve') {
-    const projectRoot = resolvePath(process.cwd());
-    const userDir = join(homedir(), '.claude-memory-kit');
+    // Claude Code sets CLAUDE_PROJECT_DIR in the spawned MCP server's environment
+    // to the project root (code.claude.com/docs/en/mcp). Prefer it over cwd so the
+    // server indexes the right project even when Claude Code launches it with a
+    // different working directory. Falls back to cwd for a manual `cmk mcp serve`.
+    const projectRoot = resolvePath(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+    const userDir = process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
     // ALL logs to stderr per design §10.1; stdout is reserved for
     // JSON-RPC messages handled by the SDK's StdioServerTransport.
     // Don't console.log() anything before/during the server's run.
@@ -1169,43 +1371,44 @@ async function runQueueDispatch(childName) {
  * canonical kit usage). User-tier / language-tier conflicts queues
  * can be added when the kit's CLI gains explicit `--tier` selection.
  */
-async function runQueueConflicts() {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const askOnce = (q) =>
-    new Promise((resolve) => {
-      rl.question(q, (answer) => resolve(answer));
-    });
-
-  const VALID_DECISIONS = new Set(['keep-old', 'keep-new', 'merge-both', 'skip']);
-
-  const prompter = async ({
-    proposedId,
-    proposedText,
-    proposedTrust,
-    existingId,
-    existingText,
-    existingTrust,
-    similarity,
-  }) => {
-    console.log('');
-    console.log('─── pending conflict ──────────────────────────────────────');
-    console.log(`existing  (${existingId}, trust=${existingTrust}): ${existingText}`);
-    console.log(`proposed  (${proposedId}, trust=${proposedTrust}): ${proposedText}`);
-    console.log(`similarity: ${Number(similarity).toFixed(4)}`);
+// Task 113 (F-9): conflict prompter LOGIC extracted as a factory over `ask`
+// (see buildReviewPrompter) so it's unit-testable without stdin.
+export function buildConflictPrompter({ ask, log }) {
+  const VALID = new Set(['keep-old', 'keep-new', 'merge-both', 'skip']);
+  return async ({ proposedId, proposedText, proposedTrust, existingId, existingText, existingTrust, similarity }) => {
+    log('');
+    log('─── pending conflict ──────────────────────────────────────');
+    log(`existing  (${existingId}, trust=${existingTrust}): ${existingText}`);
+    log(`proposed  (${proposedId}, trust=${proposedTrust}): ${proposedText}`);
+    log(`similarity: ${Number(similarity).toFixed(4)}`);
     let decision = '';
-    while (!VALID_DECISIONS.has(decision)) {
-      const answer = await askOnce(
-        `  [keep-old / keep-new / merge-both / skip]: `,
-      );
+    while (!VALID.has(decision)) {
+      const answer = await ask(`  [keep-old / keep-new / merge-both / skip]: `);
       decision = String(answer).trim();
-      if (!VALID_DECISIONS.has(decision)) {
-        console.log(
-          `  unknown answer "${decision}" — please type one of: keep-old, keep-new, merge-both, skip`,
-        );
+      if (!VALID.has(decision)) {
+        log(`  unknown answer "${decision}" — please type one of: keep-old, keep-new, merge-both, skip`);
       }
     }
     return decision;
   };
+}
+
+// Task 113 (F-9): dep-injectable (see runQueueReview). Defaults unchanged for prod;
+// a test injects { projectRoot, prompter, log, logError } to drive a real keep-old
+// / keep-new / merge-both resolution end-to-end without stdin. Returns the result.
+export async function runQueueConflicts(opts = {}) {
+  const projectRoot = opts.projectRoot ?? process.cwd();
+  const log = opts.log ?? console.log;
+  const logError = opts.logError ?? console.error;
+
+  let rl = null;
+  let prompter = opts.prompter;
+  if (!prompter) {
+    rl = createInterface({ input: process.stdin, output: process.stdout });
+    const askOnce = (q) =>
+      new Promise((resolve) => rl.question(q, (answer) => resolve(answer)));
+    prompter = buildConflictPrompter({ ask: askOnce, log });
+  }
 
   // merge-both wiring (Task 25b — closes Task 25's cross-layer
   // composition gap). The proposed bullet from the conflict queue
@@ -1251,34 +1454,35 @@ async function runQueueConflicts() {
       idB: proposedId,
     });
     if (result.action === 'error') {
-      console.error(
+      logError(
         `cmk queue conflicts: merge-both for ${existingId} + ${proposedId} failed: ${result.errors.join('; ')}`,
       );
     } else {
-      console.log(
-        `  merge-both → ${existingId} + ${proposedId} merged into ${result.id}`,
-      );
+      log(`  merge-both → ${existingId} + ${proposedId} merged into ${result.id}`);
     }
   };
 
+  // opts.resolve test seam (default = the real resolver) — see runQueueReview.
+  const resolve = opts.resolve ?? resolveConflictQueue;
   try {
-    const result = await resolveConflictQueue({
+    const result = await resolve({
       tier: 'P',
-      projectRoot: process.cwd(),
+      projectRoot,
       prompter,
       mergeFn,
     });
     if (result.action === 'error') {
-      for (const e of result.errors) console.error(`cmk queue conflicts: ${e}`);
+      for (const e of result.errors) logError(`cmk queue conflicts: ${e}`);
       process.exitCode = 2;
-      return;
+      return result;
     }
-    console.log('');
-    console.log(
+    log('');
+    log(
       `cmk queue conflicts: ${result.resolved} resolved (${result.kept_old} kept-old, ${result.kept_new} kept-new, ${result.merged} merged), ${result.skipped} skipped`,
     );
+    return result;
   } finally {
-    rl.close();
+    if (rl) rl.close();
   }
 }
 
@@ -1291,59 +1495,74 @@ async function runQueueConflicts() {
  *
  * Resolves the PROJECT tier's review queue (the canonical kit usage).
  */
-async function runQueueReview() {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const askOnce = (q) =>
-    new Promise((resolve) => {
-      rl.question(q, (answer) => resolve(answer));
-    });
-
-  const VALID_DECISIONS = new Set(['promote', 'discard', 'skip']);
-
-  const prompter = async ({ id, text, ts, provenance }) => {
-    console.log('');
-    console.log('─── pending review ────────────────────────────────────────');
-    console.log(`id:   ${id}`);
-    console.log(`ts:   ${ts}`);
-    console.log(`text: ${text}`);
-    if (provenance) console.log(`prov: ${provenance.trim()}`);
+// Task 113 (F-9): the interactive prompter LOGIC (formatting + the validate-retry
+// loop) extracted as a factory over an injectable `ask`, so it's unit-testable
+// without a real readline/stdin — only the 2-line createInterface wrapper in the
+// runner stays an uncovered shim.
+export function buildReviewPrompter({ ask, log }) {
+  const VALID = new Set(['promote', 'discard', 'skip']);
+  return async ({ id, text, ts, provenance }) => {
+    log('');
+    log('─── pending review ────────────────────────────────────────');
+    log(`id:   ${id}`);
+    log(`ts:   ${ts}`);
+    log(`text: ${text}`);
+    if (provenance) log(`prov: ${provenance.trim()}`);
     let decision = '';
-    while (!VALID_DECISIONS.has(decision)) {
-      const answer = await askOnce(`  [promote / discard / skip]: `);
+    while (!VALID.has(decision)) {
+      const answer = await ask(`  [promote / discard / skip]: `);
       decision = String(answer).trim();
-      if (!VALID_DECISIONS.has(decision)) {
-        console.log(
-          `  unknown answer "${decision}" — please type one of: promote, discard, skip`,
-        );
+      if (!VALID.has(decision)) {
+        log(`  unknown answer "${decision}" — please type one of: promote, discard, skip`);
       }
     }
     return decision;
   };
+}
+
+// Task 113 (F-9): dep-injectable so the CLI resolution path is verifiable on REAL
+// queued items. Defaults (readline over stdin + cwd + console) are unchanged for
+// production; a test injects { projectRoot, prompter, log, logError } to drive a
+// real promote/discard end-to-end without stdin. Returns the resolver result.
+export async function runQueueReview(opts = {}) {
+  const projectRoot = opts.projectRoot ?? process.cwd();
+  const log = opts.log ?? console.log;
+  const logError = opts.logError ?? console.error;
 
+  // Build the interactive prompter only when the caller didn't inject one — so a
+  // test never opens a real readline on stdin.
+  let rl = null;
+  let prompter = opts.prompter;
+  if (!prompter) {
+    rl = createInterface({ input: process.stdin, output: process.stdout });
+    const askOnce = (q) =>
+      new Promise((resolve) => rl.question(q, (answer) => resolve(answer)));
+    prompter = buildReviewPrompter({ ask: askOnce, log });
+  }
+
+  // opts.resolve is a test seam (default = the real resolver) so the error-
+  // handling branches below — unreachable via normal input since tier/prompter
+  // are always valid here — are coverable (Task 113).
+  const resolve = opts.resolve ?? resolveReviewQueue;
   try {
-    const result = await resolveReviewQueue({
-      tier: 'P',
-      projectRoot: process.cwd(),
-      prompter,
-    });
+    const result = await resolve({ tier: 'P', projectRoot, prompter });
     if (result.action === 'error') {
-      for (const e of result.errors) console.error(`cmk queue review: ${e}`);
+      for (const e of result.errors) logError(`cmk queue review: ${e}`);
       process.exitCode = 2;
-      return;
+      return result;
     }
-    console.log('');
-    console.log(
+    log('');
+    log(
       `cmk queue review: ${result.promoted} promoted, ${result.discarded} discarded, ${result.skipped} skipped${result.errors && result.errors.length ? `, ${result.errors.length} errored` : ''}`,
     );
     if (result.errors && result.errors.length) {
       for (const err of result.errors) {
-        console.error(
-          `  error on ${err.id} (${err.decision}): ${err.errors.join('; ')}`,
-        );
+        logError(`  error on ${err.id} (${err.decision}): ${err.errors.join('; ')}`);
       }
     }
+    return result;
   } finally {
-    rl.close();
+    if (rl) rl.close();
   }
 }
 
@@ -1412,7 +1631,7 @@ export const subcommands = [
     name: 'remember',
     description: 'capture a durable fact (Poison_Guard + home-path abstraction). Terse → a MEMORY.md bullet; RICH (--why/--how/--type) → a granular fact file with rationale (the safe way to capture richly).',
     milestone: 24,
-    argSpec: [{ flags: '<text...>', description: 'the fact to remember' }],
+    argSpec: [{ flags: '[text...]', description: 'the fact to remember (omit when using --from-file)' }],
     optionSpec: [
       { flags: '--tier <tier>', description: 'P (default; U/L are v0.1.x)' },
       { flags: '--trust <level>', description: 'high | medium | low (default: high)' },
@@ -1423,6 +1642,8 @@ export const subcommands = [
       { flags: '--type <type>', description: 'rich: feedback | project | reference | user (default: feedback)' },
       { flags: '--title <text>', description: 'rich: a short title (also the fact-file slug)' },
       { flags: '--links <a,b>', description: 'rich: related fact names for [[cross-links]]' },
+      { flags: '--from-file <path>', description: 'rich: read the fact as a JSON object from a file — shell-safe (content never touches argv; the safe way to capture backtick/quote-heavy Why/How). JSON keys: text (required), why, how, type, title, links. Self-contained — other flags are ignored.' },
+      { flags: '--json', description: 'rich: read the fact as a JSON object from stdin (pipe-safe, shell-safe) — same JSON keys as --from-file' },
     ],
     action: runRemember,
   },
@@ -1432,7 +1653,7 @@ export const subcommands = [
     milestone: 30,
     argSpec: [{ flags: '<query...>', description: 'query terms' }],
     optionSpec: [
-      { flags: '--mode <mode>', description: 'keyword | semantic | hybrid (default: keyword; semantic+hybrid need memsearch — Layer 5b install, not in v0.1.0)' },
+      { flags: '--mode <mode>', description: 'keyword | semantic | hybrid (default: keyword; semantic + hybrid need the Layer-5b semantic backend, not yet shipped)' },
       { flags: '--min-trust <level>', description: 'low | medium | high' },
       { flags: '--tier <tier>', description: 'U | P | L (filter to a single tier)' },
       { flags: '--since <date>', description: 'ISO date — exclude observations older than this' },
@@ -1441,6 +1662,41 @@ export const subcommands = [
     ],
     action: runSearch,
   },
+  {
+    name: 'get',
+    description: 'fetch full observation bodies + provenance by ID (parity with the mk_get MCP tool)',
+    milestone: 108,
+    argSpec: [{ flags: '<ids...>', description: 'one or more citation IDs (e.g. P-S79MJHFN)' }],
+    action: runGet,
+  },
+  {
+    name: 'timeline',
+    description: 'sequential context around an anchor observation — N before + N after (mk_timeline parity)',
+    milestone: 108,
+    argSpec: [{ flags: '<anchor>', description: 'citation ID to anchor the timeline on' }],
+    optionSpec: [
+      { flags: '--before <n>', description: 'observations before the anchor (default: 5)' },
+      { flags: '--after <n>', description: 'observations after the anchor (default: 5)' },
+    ],
+    action: runTimeline,
+  },
+  {
+    name: 'cite',
+    description: 'render the canonical Markdown citation link for an observation (mk_cite parity)',
+    milestone: 108,
+    argSpec: [{ flags: '<id>', description: 'citation ID' }],
+    action: runCite,
+  },
+  {
+    name: 'recent-activity',
+    description: 'list recent observation changes within a time window (mk_recent_activity parity)',
+    milestone: 108,
+    optionSpec: [
+      { flags: '--window <w>', description: '1h | 24h | 7d (default: 24h)' },
+      { flags: '--limit <n>', description: 'max results (default: 20)' },
+    ],
+    action: runRecentActivity,
+  },
   {
     name: 'reindex',
     description: 'rebuild the markdown INDEX.md pointer index for the project tier',