@ijfw/memory-server 1.4.4 → 1.5.1

package/src/lib/worktree-guards.js

@@ -0,0 +1,118 @@
+/**
+ * worktree-guards.js — v1.5.0-major S08: incident-driven worktree safety guards.
+ *
+ * Lifted from GSD executor (battle-tested across many incidents):
+ *   #3097 — cwd-drift assertion
+ *   #3099 — absolute-path containment check
+ *   #2924 — protected-ref deny-list (refuse commit to main/master/develop/trunk/release/*)
+ *
+ * We hit ALL THREE during v1.5.0-major dispatch (multiple subagents drifted
+ * cwd into other worktrees; W11-A0 accidentally committed to main because
+ * branch creation failed). Three small functions, large blast-radius reduction.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { resolve, isAbsolute, relative } from 'node:path';
+
+// r15-H2: resolve symlinks before containment check. Without this, a path like
+// <toplevel>/escape-link/foo (where escape-link → /etc) trivially escapes the
+// toplevel even though `relative(toplevel, path)` reports a non-`..` result for
+// the lexical path. realpathSync resolves the link first. If the path does not
+// exist yet (e.g. a not-yet-created file we're about to write), realpathSync
+// throws ENOENT — we fall back to the input path since a not-yet-existing
+// target is still a valid containment surface to check lexically.
+function safeRealpath(p) {
+  try { return realpathSync(p); } catch { return p; }
+}
+
+const PROTECTED_REF_PATTERNS = [
+  /^main$/, /^master$/, /^develop$/, /^trunk$/,
+  /^release\//, /^prod$/, /^production$/,
+];
+
+/**
+ * #3097 — Assert that current working directory matches the captured spawn-time
+ * git toplevel. Returns the captured toplevel for later use. Throws if drift detected.
+ *
+ * @param {string} capturedToplevel - what was `git rev-parse --show-toplevel` at spawn
+ * @param {string} cwd - current working directory (default: process.cwd())
+ * @returns {string} the captured toplevel (passthrough on success)
+ * @throws Error if cwd drifted off the captured toplevel
+ */
+export function assertNoCwdDrift(capturedToplevel, cwd = process.cwd()) {
+  if (!capturedToplevel) throw new Error('worktree-guards: capturedToplevel required (call captureSpawnToplevel() at spawn)');
+  let currentTop;
+  try {
+    currentTop = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' }).trim();
+  } catch {
+    throw new Error(`worktree-guards: cwd is not a git tree: ${cwd}`);
+  }
+  if (currentTop !== capturedToplevel) {
+    throw new Error(`worktree-guards: cwd drift detected! spawn=${capturedToplevel}, now=${currentTop}`);
+  }
+  return capturedToplevel;
+}
+
+/**
+ * Capture the spawn-time toplevel for later drift assertion.
+ */
+export function captureSpawnToplevel(cwd = process.cwd()) {
+  return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' }).trim();
+}
+
+/**
+ * #3099 — Assert that an absolute file path is contained within the toplevel.
+ * Refuses operations that would read/write outside the expected worktree.
+ *
+ * @param {string} absolutePath - path to check
+ * @param {string} toplevel - git toplevel (from captureSpawnToplevel)
+ * @returns {string} the path (passthrough on success)
+ * @throws if path escapes toplevel
+ */
+export function assertPathWithinToplevel(absolutePath, toplevel) {
+  if (!isAbsolute(absolutePath)) {
+    throw new Error(`worktree-guards: path must be absolute (got: ${absolutePath})`);
+  }
+  // r15-H2: resolve symlinks on BOTH path AND toplevel before comparing.
+  // A path that lexically starts with toplevel can still escape via a symlink
+  // (e.g. <toplevel>/escape-link/foo where escape-link → /etc). Resolving
+  // both ends through realpath catches the real-fs destination.
+  const resolvedPath = safeRealpath(absolutePath);
+  const resolvedTop  = safeRealpath(toplevel);
+  const rel = relative(resolvedTop, resolvedPath);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`worktree-guards: path escapes toplevel! path=${absolutePath} (resolved: ${resolvedPath}), toplevel=${toplevel} (resolved: ${resolvedTop})`);
+  }
+  return absolutePath;
+}
+
+/**
+ * #2924 — Assert the current HEAD is NOT pointing at a protected ref before commit.
+ * Subagents must commit to a wave branch (wave/W*-*), never directly to main/master/etc.
+ *
+ * @param {string} cwd
+ * @returns {string} the current branch name (passthrough on success)
+ * @throws if HEAD is on a protected ref
+ */
+export function assertNotProtectedRef(cwd = process.cwd()) {
+  const branch = execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' }).trim();
+  if (!branch) {
+    throw new Error('worktree-guards: detached HEAD — cannot commit safely');
+  }
+  for (const pattern of PROTECTED_REF_PATTERNS) {
+    if (pattern.test(branch)) {
+      throw new Error(`worktree-guards: refuse to commit to protected ref: ${branch}. Switch to a wave/feature branch first.`);
+    }
+  }
+  return branch;
+}
+
+/**
+ * Convenience: run all 3 guards in sequence before a commit. Returns the verified branch.
+ */
+export function preCommitGuards(capturedToplevel, paths = []) {
+  assertNoCwdDrift(capturedToplevel);
+  for (const p of paths) assertPathWithinToplevel(resolve(p), capturedToplevel);
+  return assertNotProtectedRef();
+}

package/src/lib/worktree-recovery.js

@@ -0,0 +1,100 @@
+/**
+ * worktree-recovery.js — v1.5.0-major S10: transactional cleanup tail for worktrees.
+ *
+ * Pattern lifted from GSD code-fixer (crash-safe recovery on next run):
+ *   1. BEFORE opening the crash window (git worktree remove), write a sentinel
+ *      file at .planning/<phase>/.worktree-recovery-pending.json with:
+ *        { worktreePath, branch, phase, ts, op: 'remove' }
+ *   2. Run the destructive op.
+ *   3. On success, DELETE the sentinel.
+ *
+ * Next run scans for orphan sentinels and offers/runs cleanup. Survives:
+ *   - Process SIGKILL between steps 1+2
+ *   - Power loss / OOM between steps 2+3
+ *   - Network filesystem partition during step 2
+ *
+ * Use this for ANY destructive op where a partial state on disk is worse
+ * than a fully-committed or fully-rolled-back state.
+ */
+
+import { writeFile, readFile, unlink, readdir, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+
+const SENTINEL_PREFIX = '.worktree-recovery-pending.';
+
+/**
+ * Write a recovery sentinel, run the op, delete on success.
+ * @param {object} sentinelData - serialised into JSON; should include worktreePath + op
+ * @param {function} op - async function to execute; if it throws, sentinel remains
+ * @param {string} projectRoot - parent project root
+ * @returns the op's return value
+ */
+export async function withRecoverySentinel(sentinelData, op, projectRoot) {
+  const sentinelDir = join(projectRoot, '.planning', 'worktree-recovery');
+  await mkdir(sentinelDir, { recursive: true });
+  const sentinelId = randomBytes(6).toString('hex');
+  const sentinelPath = join(sentinelDir, `${SENTINEL_PREFIX}${sentinelId}.json`);
+  const payload = { ...sentinelData, sentinel_id: sentinelId, ts: new Date().toISOString() };
+
+  await writeFile(sentinelPath, JSON.stringify(payload, null, 2), 'utf8');
+  try {
+    const result = await op();
+    try { await unlink(sentinelPath); } catch { /* missing → ok */ }
+    return result;
+  } catch (err) {
+    // Leave sentinel in place for next run to recover.
+    err.sentinelPath = sentinelPath;
+    throw err;
+  }
+}
+
+/**
+ * Scan for orphan sentinels (op didn't complete on previous run).
+ * @returns array of sentinel objects with full payload + path
+ */
+export async function listPendingRecoveries(projectRoot) {
+  const sentinelDir = join(projectRoot, '.planning', 'worktree-recovery');
+  try {
+    const entries = await readdir(sentinelDir);
+    const pending = [];
+    for (const name of entries) {
+      if (!name.startsWith(SENTINEL_PREFIX)) continue;
+      const fullPath = join(sentinelDir, name);
+      try {
+        const raw = await readFile(fullPath, 'utf8');
+        pending.push({ ...JSON.parse(raw), path: fullPath });
+      } catch { /* malformed, skip */ }
+    }
+    return pending;
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+}
+
+/**
+ * Attempt to complete a pending recovery. Currently handles op:'remove' for worktrees.
+ * Returns { ok, action, details? }.
+ */
+export async function recoverPending(sentinel, projectRoot) {
+  if (sentinel.op === 'remove' && sentinel.worktreePath) {
+    try {
+      // Best-effort: if the worktree dir still exists, finish the remove.
+      if (existsSync(sentinel.worktreePath)) {
+        execFileSync('git', ['worktree', 'remove', '--force', sentinel.worktreePath], {
+          cwd: projectRoot, encoding: 'utf8',
+        });
+      }
+      // Always prune to clean up dangling .git/worktrees/ refs.
+      execFileSync('git', ['worktree', 'prune'], { cwd: projectRoot, encoding: 'utf8' });
+      await unlink(sentinel.path);
+      return { ok: true, action: 'completed-remove', worktreePath: sentinel.worktreePath };
+    } catch (err) {
+      return { ok: false, action: 'remove-failed', error: err.message };
+    }
+  }
+  return { ok: false, action: 'unknown-op', op: sentinel.op };
+}

package/src/memory/auto-linker.js

@@ -0,0 +1,267 @@
+// IJFW v1.5.0 -- A-Mem-style auto-linking on memory store.
+//
+// On every memory store call (post-dedup, pre-fact-extraction), this module:
+//   1. Selects top-k neighbors via body lexical match (production
+//      memory_entries has columns id/body/source/session_id/created_at;
+//      no title, so neighbor scoring is body-only).
+//   2. Asks the LLM (one call, env-gated) to return a JSON payload:
+//        classification: "ADD" | "UPDATE" | "NOOP"
+//        links:          [{ target }]
+//        neighbor_edits: [{ id, add_tags: [...] }]
+//   3. Applies the proposal to memory_links / memory_tags atomically.
+//
+// All steps are gated by llm-call.js env vars (IJFW_AUTOLINK_OFF=1,
+// IJFW_AUTOLINK_BUDGET_USD=0, missing API key). When skipped, no writes.
+//
+// Test injections:
+//   { neighborsOnly: true } -> select neighbors, no LLM, no writes
+//   { dryProposal: <obj> }  -> skip LLM, apply the supplied proposal
+//
+// Reference: arxiv 2502.12110 (A-Mem, NeurIPS 2025). This is the
+// academically-validated "smarter with use" keystone.
+
+import { llmCall, parseLlmJsonResponse } from '../lib/llm-call.js';
+
+const DEFAULT_TOPK = 5;
+const SYSTEM_PROMPT = [
+  'You are the IJFW memory auto-linker. Given a NEW MEMORY and TOP-K NEIGHBORS,',
+  'return STRICT JSON only (no prose). Schema:',
+  '{',
+  '  "classification": "ADD" | "UPDATE" | "NOOP",',
+  '  "links":           [{ "target": "<lowercase-dash-collapsed-slug>" }],',
+  '  "neighbor_edits":  [{ "id": "<neighbor-id>", "add_tags": ["..."] }]',
+  '}',
+  'classification = UPDATE if the new memory directly supersedes a neighbor.',
+  'classification = NOOP if the new memory is fully duplicate.',
+  'links = neighbors the new memory should reference (max 3).',
+  'neighbor_edits = small tag additions to neighbors (max 2 per neighbor; max 3 total).',
+  'NEVER invent neighbors not in TOP-K. NEVER rewrite neighbor body.',
+].join('\n');
+
+function selectNeighbors(db, entry, k = DEFAULT_TOPK) {
+  // Body-only lexical proximity via tokenized LIKE -- light, deterministic,
+  // no FTS dependency. Production memory_entries has no title column.
+  //
+  // Tokenization: split on non-word chars, filter to tokens >=4 chars
+  // (skips stop-words and noise), keep first 3. Build OR-LIKE so we find
+  // any neighbor that shares at least one significant token. Ranking is
+  // implicit via the LIMIT; if multi-token scoring matters in the future,
+  // wrap in a CASE-WHEN sum.
+  const tokens = (entry.body || entry.title || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/i)
+    .filter((t) => t.length >= 4)
+    .slice(0, 3);
+  if (tokens.length === 0) return [];
+
+  const orClauses = tokens.map(() => 'body LIKE ?').join(' OR ');
+  const params = tokens.map((t) => `%${t}%`);
+  let sql = `SELECT CAST(id AS TEXT) AS id, body, source
+             FROM memory_entries
+             WHERE (${orClauses})`;
+  if (entry.id != null) {
+    sql += ' AND CAST(id AS TEXT) != ?';
+    params.push(String(entry.id));
+  }
+  sql += ' ORDER BY created_at DESC LIMIT ?';
+  params.push(k);
+  return db.prepare(sql).all(...params);
+}
+
+function applyProposal(db, entry, proposal) {
+  const insLink = db.prepare(
+    'INSERT OR IGNORE INTO memory_links (from_id, to_target, line) VALUES (?, ?, 0)',
+  );
+  const insTag = db.prepare(
+    'INSERT OR IGNORE INTO memory_tags (memory_id, tag_path, depth) VALUES (?, ?, ?)',
+  );
+  let linksAdded = 0;
+  let neighborTagsAdded = 0;
+  const tx = db.transaction(() => {
+    for (const l of (proposal.links || []).slice(0, 3)) {
+      if (l && typeof l.target === 'string' && l.target) {
+        const res = insLink.run(String(entry.id), l.target);
+        if (res.changes) linksAdded++;
+      }
+    }
+    let total = 0;
+    for (const ne of (proposal.neighbor_edits || []).slice(0, 5)) {
+      if (!ne || typeof ne.id !== 'string') continue;
+      for (const t of (ne.add_tags || []).slice(0, 2)) {
+        if (total >= 3) break;
+        if (typeof t === 'string' && t) {
+          const path = t.toLowerCase().replace(/^\/+|\/+$/g, '');
+          if (!path) continue;
+          const res = insTag.run(ne.id, path, path.split('/').length);
+          if (res.changes) {
+            neighborTagsAdded++;
+            total++;
+          }
+        }
+      }
+    }
+  });
+  tx();
+  return { links_added: linksAdded, neighbor_tags_added: neighborTagsAdded };
+}
+
+export async function autoLink(db, entry, opts = {}) {
+  // Env-gate check FIRST — before any DB work — so the off-path is a
+  // true no-op (no SELECT against memory_entries, no race against
+  // fire-and-forget db.close calls in test harnesses).
+  if (!opts.dryProposal && !opts.neighborsOnly) {
+    if (process.env.IJFW_AUTOLINK_OFF === '1') {
+      return { skipped: true, reason: 'autolink_off' };
+    }
+    const budget = process.env.IJFW_AUTOLINK_BUDGET_USD;
+    if (budget !== undefined && Number(budget) <= 0) {
+      return { skipped: true, reason: 'budget_exhausted' };
+    }
+    const hasKey = !!(process.env.IJFW_AUTOLINK_API_KEY || process.env.ANTHROPIC_API_KEY);
+    if (!hasKey) {
+      return { skipped: true, reason: 'no_key' };
+    }
+  }
+  const neighbors = selectNeighbors(db, entry, opts.k || DEFAULT_TOPK);
+  if (opts.neighborsOnly) return { skipped: true, neighbors };
+
+  let proposal = opts.dryProposal;
+  if (!proposal) {
+    const userPayload = JSON.stringify({
+      new_memory: { id: String(entry.id), body: entry.body },
+      top_k_neighbors: neighbors.map((n) => ({ id: n.id, body: (n.body || '').slice(0, 200) })),
+    });
+    const llm = await llmCall({
+      system: SYSTEM_PROMPT,
+      user: userPayload,
+      maxTokens: 512,
+    });
+    if (llm.skipped) {
+      return { skipped: true, reason: llm.reason, neighbors };
+    }
+    try {
+      proposal = parseLlmJsonResponse(llm.text);
+    } catch (e) {
+      return { skipped: true, reason: 'parse_failed', neighbors, error: e.message };
+    }
+  }
+  const applied = applyProposal(db, entry, proposal);
+  return { skipped: false, neighbors, proposal, applied };
+}
+
+// v1.5.1 R5-1.2 -- one-time M2 (A-Mem auto-link) backfill for memory written
+// during v1.5.0, when autoLink was NOT wired into the production write path.
+//
+// UNLIKE the M1 backfill (free, always-on), M2 backfill makes one LLM call
+// per row -- backfilling over a large memory can cost real money. So M2
+// backfill is OPT-IN and budget-gated:
+//
+//   - IJFW_AUTOLINK_OFF=1            -> backfill is a no-op (kill switch)
+//   - IJFW_AUTOLINK_BACKFILL!=1      -> backfill is a no-op by default
+//                                       (M1-always, M2-opt-in is the safe
+//                                        default per R5-1.2)
+//   - IJFW_AUTOLINK_BUDGET_USD unset -> backfill is a no-op. A budget MUST be
+//     OR <= 0                           explicitly configured. The per-call
+//                                       llm-call.js path treats an unset
+//                                       budget as "uncapped"; for a bulk
+//                                       backfill that is unsafe -- a large
+//                                       memory could spend without bound. So
+//                                       the backfill REQUIRES a positive cap.
+//   - no API key                    -> backfill is a no-op (autoLink skips)
+//
+// The per-row autoLink call independently re-checks the SAME env gates (off /
+// budget / key), so even mid-run the backfill respects a budget that drops to
+// zero or a kill switch that flips. Returns aggregate counts.
+export async function backfillAutoLink(db, opts = {}) {
+  if (!db || typeof db.prepare !== 'function') {
+    throw new Error('backfillAutoLink: db handle is invalid.');
+  }
+  const force = opts.force === true;
+  // Opt-in gate: M2 backfill only runs when explicitly enabled. M1 backfill
+  // (obsidian-parser.js) is the always-on default; M2 costs money so it is
+  // off unless the operator opts in via IJFW_AUTOLINK_BACKFILL=1.
+  if (!force && process.env.IJFW_AUTOLINK_BACKFILL !== '1') {
+    return { skipped: true, reason: 'backfill_not_enabled', rows: 0 };
+  }
+  if (process.env.IJFW_AUTOLINK_OFF === '1') {
+    return { skipped: true, reason: 'autolink_off', rows: 0 };
+  }
+  // Budget cap is MANDATORY for the backfill. An unset budget means
+  // llm-call.js runs uncapped -- fine for one-off write-time autoLink, but a
+  // bulk backfill over thousands of rows would spend without bound. Refuse
+  // unless the operator has set a positive IJFW_AUTOLINK_BUDGET_USD.
+  const budget = process.env.IJFW_AUTOLINK_BUDGET_USD;
+  if (budget === undefined || !(Number(budget) > 0)) {
+    return {
+      skipped: true,
+      reason: budget === undefined ? 'budget_not_set' : 'budget_exhausted',
+      rows: 0,
+    };
+  }
+  const hasKey = !!(process.env.IJFW_AUTOLINK_API_KEY || process.env.ANTHROPIC_API_KEY);
+  if (!hasKey) {
+    return { skipped: true, reason: 'no_key', rows: 0 };
+  }
+
+  const batchSize = Math.max(1, opts.batchSize || 200);
+  const result = {
+    skipped: false, rows: 0, linked: 0, links_added: 0,
+    neighbor_tags_added: 0, stopped_early: false,
+  };
+  let lastId = 0;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    let batch;
+    try {
+      batch = db
+        .prepare(
+          'SELECT id, body FROM memory_entries WHERE id > ? ORDER BY id ASC LIMIT ?',
+        )
+        .all(lastId, batchSize);
+    } catch {
+      break;
+    }
+    if (!batch || batch.length === 0) break;
+    for (const row of batch) {
+      lastId = row.id;
+      if (typeof row.body !== 'string' || row.body.length === 0) continue;
+      // Per-row re-check: a budget that drops to zero or a kill switch that
+      // flips mid-run stops the backfill before the next paid call. autoLink
+      // itself ALSO re-checks, but stopping here avoids the wasted SELECT.
+      if (process.env.IJFW_AUTOLINK_OFF === '1') {
+        result.stopped_early = true;
+        return result;
+      }
+      const b = process.env.IJFW_AUTOLINK_BUDGET_USD;
+      if (b === undefined || !(Number(b) > 0)) {
+        result.stopped_early = true;
+        return result;
+      }
+      result.rows += 1;
+      let res;
+      try {
+        res = await autoLink(db, { id: row.id, body: row.body });
+      } catch {
+        continue;
+      }
+      if (res && res.skipped) {
+        // autoLink skipped (budget exhausted / off / no key / parse fail).
+        // budget_exhausted + autolink_off mean stop the whole run.
+        if (res.reason === 'budget_exhausted' || res.reason === 'autolink_off') {
+          result.stopped_early = true;
+          return result;
+        }
+        continue;
+      }
+      result.linked += 1;
+      if (res && res.applied) {
+        result.links_added += res.applied.links_added || 0;
+        result.neighbor_tags_added += res.applied.neighbor_tags_added || 0;
+      }
+    }
+    if (batch.length < batchSize) break;
+  }
+  return result;
+}
+
+export default { autoLink, backfillAutoLink };