forge-workflow 0.1.0-beta.4 → 0.1.0-beta.5

package/lib/forge-issues.js

@@ -25,6 +25,7 @@ function isHelpInvocation(args = []) {
 // on a missing `exec` method before ever reaching the "no tables" case.
 function createDefaultKernelBroker(brokerContext, deps) {
   let driver = deps.kernelDriver;
+  const ownsDriver = !driver;
   if (!driver) {
     const config = buildLocalBrokerConfig({
       projectRoot: brokerContext.projectRoot,
@@ -35,7 +36,7 @@ function createDefaultKernelBroker(brokerContext, deps) {
     driver = createBuiltinSQLiteDriver({ databasePath: config.databasePath });
   }
 
-  return createLocalBroker({
+  const broker = createLocalBroker({
     projectRoot: brokerContext.projectRoot,
     gitCommonDir: deps.gitCommonDir,
     databasePath: deps.kernelDatabasePath,
@@ -46,6 +47,10 @@ function createDefaultKernelBroker(brokerContext, deps) {
     // classifier instead of paying the real Windows drive probe per per-op broker.
     classifyFilesystem: deps.classifyFilesystem,
   });
+  if (ownsDriver && typeof driver.close === 'function') {
+    broker.close = () => driver.close();
+  }
+  return broker;
 }
 
 // Symbol marker for the memoized lazy-init promise. Stored ON the broker object
@@ -82,6 +87,11 @@ function withLazyKernelInit(broker) {
     async initialize() {
       return ensureInitialized();
     },
+    async close() {
+      if (typeof broker.close === 'function') {
+        await broker.close();
+      }
+    },
     async runIssueOperation(operation, args = [], context = {}) {
       await ensureInitialized();
       return broker.runIssueOperation(operation, args, context);
@@ -94,11 +104,14 @@ function createKernelIssueBackend(context = {}) {
   const createBroker = deps.createKernelBroker
     || ((brokerContext) => createDefaultKernelBroker(brokerContext, deps));
 
+  const ownsBroker = !deps.kernelBroker;
   const broker = deps.kernelBroker || createBroker(context);
-
-  return new KernelIssueAdapter({
-    broker: withLazyKernelInit(broker),
-  });
+  const managedBroker = withLazyKernelInit(broker);
+  const backend = new KernelIssueAdapter({ broker: managedBroker });
+  if (ownsBroker && typeof managedBroker?.close === 'function') {
+    backend.dispose = () => managedBroker.close();
+  }
+  return backend;
 }
 
 function createIssueService({ backend } = {}) {
@@ -108,6 +121,11 @@ function createIssueService({ backend } = {}) {
   const resolvedBackend = backend || createKernelIssueBackend();
 
   return {
+    async dispose() {
+      if (typeof resolvedBackend?.dispose === 'function') {
+        await resolvedBackend.dispose();
+      }
+    },
     async run(operation, args = [], context = {}) {
       const methodName = operation === 'show' && typeof resolvedBackend?.show !== 'function'
         ? 'read'
@@ -205,36 +223,42 @@ async function runIssueOperation(operation, rawArgs, projectRoot, deps = {}) {
   const isClaim = operation === 'claim';
   const worktreeId = isClaim ? resolveWorktreeId(projectRoot, actorEnv, deps) : undefined;
   const leaseTtlMs = isClaim ? resolveLeaseTtlMs(actorEnv) : undefined;
-  const result = await service.run(operation, rawArgs, {
-    projectRoot,
-    deps,
-    ...(actor ? { actor } : {}),
-    ...(sessionId ? { sessionId } : {}),
-    ...(worktreeId ? { worktreeId } : {}),
-    ...(leaseTtlMs ? { leaseTtlMs } : {}),
-    // Kernel mutations enqueue a projection-outbox "dirty marker" that `forge export`
-    // (the D16 git-JSONL portability projection) drains under target 'jsonl'. The
-    // broker's legacy primitive default is still 'beads', so without steering the target
-    // here every Kernel-created issue would be enqueued as 'beads' and `forge export` —
-    // which drains 'jsonl' — would find nothing, silently never emitting git-tracked
-    // JSONL. Unconditional now that the Kernel is the only backend.
-    projectionTarget: 'jsonl',
-  });
+  try {
+    const result = await service.run(operation, rawArgs, {
+      projectRoot,
+      deps,
+      ...(actor ? { actor } : {}),
+      ...(sessionId ? { sessionId } : {}),
+      ...(worktreeId ? { worktreeId } : {}),
+      ...(leaseTtlMs ? { leaseTtlMs } : {}),
+      // Kernel mutations enqueue a projection-outbox "dirty marker" that `forge export`
+      // (the D16 git-JSONL portability projection) drains under target 'jsonl'. The
+      // broker's legacy primitive default is still 'beads', so without steering the target
+      // here every Kernel-created issue would be enqueued as 'beads' and `forge export` —
+      // which drains 'jsonl' — would find nothing, silently never emitting git-tracked
+      // JSONL. Unconditional now that the Kernel is the only backend.
+      projectionTarget: 'jsonl',
+    });
 
-  const queueGitHubProjection = deps.enqueueGitHubProjection || deps.queueGitHubProjection;
-  if (result?.success && typeof queueGitHubProjection === 'function') {
-    const projectionPlan = createGitHubProjectionPlan(operation, rawArgs);
-    if (projectionPlan) {
-      await queueGitHubProjection(projectionPlan, {
-        operation,
-        args: rawArgs,
-        projectRoot,
-        result,
-      });
+    const queueGitHubProjection = deps.enqueueGitHubProjection || deps.queueGitHubProjection;
+    if (result?.success && typeof queueGitHubProjection === 'function') {
+      const projectionPlan = createGitHubProjectionPlan(operation, rawArgs);
+      if (projectionPlan) {
+        await queueGitHubProjection(projectionPlan, {
+          operation,
+          args: rawArgs,
+          projectRoot,
+          result,
+        });
+      }
     }
-  }
 
-  return result;
+    return result;
+  } finally {
+    if (!injectedService && typeof service.dispose === 'function') {
+      try { await service.dispose(); } catch { /* cleanup must not mask the operation outcome */ }
+    }
+  }
 }
 
 module.exports = {

package/lib/git-defaults.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+/**
+ * Detect the default branch of the repository.
+ *
+ * Strategy (in order):
+ *   1. `git symbolic-ref refs/remotes/origin/HEAD` -> parse branch name
+ *   2. `git remote show origin` -> parse "HEAD branch:" line
+ *   3. Fall back to `'main'`
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @param {object} [options] - Options object.
+ * @param {Function} [options._exec] - Injected execFileSync for testing.
+ * @returns {string} The default branch name.
+ */
+function detectDefaultBranch(projectRoot, options = {}) {
+  const exec = options._exec || execFileSync;
+
+  // Strategy 1: symbolic-ref
+  try {
+    const out = exec('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], {
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const ref = out.toString().trim();
+    // refs/remotes/origin/release/2026 -> release/2026 (branch names may contain '/')
+    const prefix = 'refs/remotes/origin/';
+    if (ref.startsWith(prefix)) {
+      return ref.slice(prefix.length);
+    }
+  } catch (_e) { // NOSONAR S2486 — symbolic-ref fails when origin/HEAD is unset; fall through to strategy 2
+  }
+
+  // Strategy 2: remote show origin
+  try {
+    const out = exec('git', ['remote', 'show', 'origin'], {
+      cwd: projectRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const text = out.toString();
+    const match = text.match(/HEAD branch:\s*(.+)/);
+    if (match) {
+      return match[1].trim();
+    }
+  } catch (_e) { // NOSONAR S2486 — 'git remote show origin' fails with no remote configured; fall through to the default
+  }
+
+  // Strategy 3: fallback
+  return 'main';
+}
+
+module.exports = {
+  detectDefaultBranch,
+};

package/lib/harness-capability-matrix.js

@@ -13,7 +13,7 @@ const CAPABILITY_IDS = [
   'commands',
   'agents',
   'stages',
-  'beads',
+  'issueState',
   'typedMemory',
   'patchOverrides',
   'marketplaceTrust',
@@ -157,7 +157,7 @@ const CAPABILITY_ROWS = [
     ['codex', target('skill-first', '$CODEX_HOME/skills/<stage>/SKILL.md', { role: 'generated at setup from canonical skills/', evidence: ['S5'], knownIssue: 'Repo-local Codex discovery uses .agents/skills/<stage>/SKILL.md, the committed mirror (generated from skills/, kept in sync by a pre-commit hook + drift gate) (kernel issue 55dfeccf).' })],
     ['hermes', target('forge-owned', '.hermes/skills/<stage>/SKILL.md', { role: 'Forge-owned stage-skill projection consumed via forge orient/recap' })],
   ]),
-  row('beads', 'state-and-memory', 'issue and audit state authority', HARNESS_IDS.map(id => [id, target('forge-owned', 'forge CLI + bd adapter')])),
+  row('issueState', 'state-and-memory', 'issue and audit state authority', HARNESS_IDS.map(id => [id, target('forge-owned', 'forge CLI + Forge Kernel store')])),
   row('typedMemory', 'state-and-memory', 'typed memory projection', [
     ['claude', target('not-delivered', null, { knownIssue: 'Typed memory is WRITE-ONLY (insights.js); no generator projects a memory section into any Claude instruction/rule file. Tracked as kernel issue dce9da46 (epic 90f2f631).' })],
     ['cursor', target('not-delivered', null, { knownIssue: 'Typed memory is write-only; no memory-projection renderer emits a Cursor memory section. Tracked as kernel issue dce9da46 (epic 90f2f631).' })],
@@ -312,7 +312,7 @@ const RENDERER_FAMILIES = [
   ['commands', 'Forge command shim manifest', ['shim points to canonical skill', 'no duplicated stage body']],
   ['agents', 'Forge agent role spec', ['role mapping', 'parallelism or fallback policy']],
   ['stage-graph', 'Forge skills-first stage graph', ['super skill target', 'subskill target list', 'gate mapping']],
-  ['state-and-memory', 'Beads, typed memory, and patch override manifests', ['state authority', 'projection provenance', 'protected path policy']],
+  ['state-and-memory', 'Kernel issue state, typed memory, and patch override manifests', ['state authority', 'projection provenance', 'protected path policy']],
   ['distribution', 'Forge extension manifest and lock metadata', ['lock hash', 'trusted source', 'generated target inventory']],
   ['safety', 'Forge safety-surface manifest (permissions, ignore, sandbox)', ['permission scope (allow/deny/ask)', 'read/index ignore boundary', 'sandbox/approval policy or global-scope deferral note']],
 ];

package/lib/hook-renderer.js

@@ -33,14 +33,14 @@
  * the protected-path set, and delegates the TDD gate to the real `check-tdd.js`.
  *
  * Dependency-free (JSON only; no TOML lib) so it runs under `bun test` and the
- * release gates. Reuses the MCP renderer's `backupFile` for the data-loss guard.
+ * release gates.
  *
  * @module hook-renderer
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { backupFile } = require('./mcp-config-renderer');
+const { assertNoAncestorSymlinkEscape, assertNoSymlinkEscape } = require('./protected-state-surfaces');
 
 const HARNESS_HOOK_FILES = {
   claude: '.claude/settings.json',
@@ -447,10 +447,30 @@ function isForgeClaudeGroup(group) {
   return hooks.some(h => isForgeCommand(h?.command));
 }
 
+function withoutForgeCommands(group) {
+  const hooks = Array.isArray(group?.hooks) ? group.hooks : [];
+  const userHooks = hooks.filter(hook => !isForgeCommand(hook?.command));
+  if (userHooks.length === hooks.length) return group;
+  if (userHooks.length === 0) return null;
+  return { ...group, hooks: userHooks };
+}
+
 function isForgeCursorEntry(entry) {
   return isForgeCommand(entry?.command);
 }
 
+function groupContains(actual, expected) {
+  if ((actual?.matcher || '') !== (expected?.matcher || '')) return false;
+  const actualHooks = Array.isArray(actual?.hooks) ? actual.hooks : [];
+  const expectedHooks = Array.isArray(expected?.hooks) ? expected.hooks : [];
+  const forgeHooks = actualHooks.filter(hook => isForgeCommand(hook?.command));
+  return forgeHooks.length === expectedHooks.length
+    && expectedHooks.every(expectedHook =>
+      forgeHooks.filter(actualHook =>
+        actualHook?.type === expectedHook?.type
+        && actualHook?.command === expectedHook?.command).length === 1);
+}
+
 function parseJsonConfig(existingText) {
   if (!existingText || !existingText.trim()) return {};
   let obj;
@@ -479,12 +499,55 @@ function mergeClaudeSettings(existingText, contract) {
   const rendered = renderClaudeHooks(contract);
   for (const [event, forgeGroups] of Object.entries(rendered)) {
     const existingGroups = Array.isArray(obj.hooks[event]) ? obj.hooks[event] : [];
-    const userGroups = existingGroups.filter(group => !isForgeClaudeGroup(group));
+    const userGroups = existingGroups.map(withoutForgeCommands).filter(Boolean);
     obj.hooks[event] = [...userGroups, ...forgeGroups];
   }
   return JSON.stringify(obj, null, 2) + '\n';
 }
 
+function hasForgeClaudeHooks(existingText, contract) {
+  const obj = parseJsonConfig(existingText);
+  const hooks = obj.hooks && typeof obj.hooks === 'object' && !Array.isArray(obj.hooks)
+    ? obj.hooks
+    : {};
+  return Object.entries(renderClaudeHooks(contract)).every(([event, expectedGroups]) => {
+    const actualGroups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const forgeGroups = actualGroups.filter(isForgeClaudeGroup);
+    return forgeGroups.length === expectedGroups.length
+      && expectedGroups.every(expected =>
+        forgeGroups.filter(actual => groupContains(actual, expected)).length === 1);
+  });
+}
+
+function backupHookConfig(filePath) {
+  const source = fs.readFileSync(filePath);
+  const sourceStat = fs.statSync(filePath);
+  for (let suffix = 0; ; suffix += 1) {
+    const candidate = `${filePath}.bak${suffix ? `.${suffix}` : ''}`;
+    let candidateStat;
+    try {
+      candidateStat = fs.lstatSync(candidate);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      try {
+        fs.copyFileSync(filePath, candidate, fs.constants.COPYFILE_EXCL);
+        return candidate;
+      } catch (copyError) {
+        if (copyError.code === 'EEXIST') continue;
+        throw copyError;
+      }
+    }
+    if (candidateStat.isSymbolicLink()) continue;
+    if (sourceStat.dev != null && sourceStat.ino != null
+      && sourceStat.dev === candidateStat.dev && sourceStat.ino === candidateStat.ino) continue;
+    try {
+      if (source.equals(fs.readFileSync(candidate))) return candidate;
+    } catch {
+      // An unreadable backup cannot prove the source is already safe.
+    }
+  }
+}
+
 /**
  * Merge Forge's hooks into an existing `.cursor/hooks.json` string.
  * Forces `version: 1`, preserves all non-Forge events and the user's own entries;
@@ -511,6 +574,26 @@ const MERGERS = {
   cursor: mergeCursorHooks,
 };
 
+function assertSafeHookConfigPath(targetRoot, filePath) {
+  const escape =
+    assertNoAncestorSymlinkEscape(targetRoot, filePath) ||
+    assertNoSymlinkEscape(targetRoot, filePath);
+  if (escape) throw new Error(`Refusing to render hook config: ${escape.reason}`);
+  if (hasMultipleHardLinks(filePath)) {
+    throw new Error('Refusing to render hardlinked hook config');
+  }
+}
+
+function hasMultipleHardLinks(filePath) {
+  try {
+    const stat = fs.lstatSync(filePath);
+    return stat.isFile() && stat.nlink > 1;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
 /**
  * Render (merge) Forge's native hooks into one harness's native config on disk.
  * Read → merge → write. Unparseable existing file → BACKED UP + left untouched
@@ -537,7 +620,9 @@ function renderHookConfig({ harness, targetRoot, contract = FORGE_HOOK_CONTRACT
   if (!merge || !rel) throw new Error(`Unknown hook harness: ${harness}`);
 
   const filePath = path.join(targetRoot, rel);
+  assertSafeHookConfigPath(targetRoot, filePath);
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  assertSafeHookConfigPath(targetRoot, filePath);
   const existed = fs.existsSync(filePath);
   const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
 
@@ -546,12 +631,14 @@ function renderHookConfig({ harness, targetRoot, contract = FORGE_HOOK_CONTRACT
     merged = merge(existing, contract);
   } catch (err) {
     if (err instanceof HookConfigParseError && existed) {
-      const backup = backupFile(filePath);
+      assertSafeHookConfigPath(targetRoot, filePath);
+      const backup = backupHookConfig(filePath);
       return { file: filePath, existed, skipped: true, wrote: false, backup };
     }
     throw err;
   }
 
+  assertSafeHookConfigPath(targetRoot, filePath);
   fs.writeFileSync(filePath, merged, 'utf-8');
   return { file: filePath, existed, skipped: false, wrote: true };
 }
@@ -578,6 +665,8 @@ module.exports = {
   renderCodexHooksToml,
   renderHermesHooksYaml,
   mergeClaudeSettings,
+  hasForgeClaudeHooks,
+  hasMultipleHardLinks,
   mergeCursorHooks,
   renderHookConfig,
 };

package/lib/insights.js

@@ -3,10 +3,76 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const typedMemory = require('./memory/typed-api');
+const { runIssueOperation: defaultRunIssueOperation } = require('./forge-issues');
+const { buildMigratedKernelIssueDeps } = require('./kernel/cli-broker-factory');
 
 const ISSUE_REFS = ['forge-besw.12', 'forge-1gry', 'forge-5q7s'];
 const DEFAULT_MIN_COUNT = 5;
 const DEFAULT_LIMIT = 10;
+// Upper bound on kernel_events scanned for interaction patterns — a spot-read, not a
+// full history walk. Newest-first, so recent activity dominates the signal.
+const EVENT_READ_LIMIT = 2000;
+
+// Default kernel activity read for `forge insights` (Slice C2). Builds a short-lived
+// migrated broker, reads recent kernel_events, and ALWAYS closes the driver (Windows
+// CI fails on a leaked handle). Injectable via analyzeInsights options for tests.
+async function defaultListRecentEvents(projectRoot, { since = null, limit = null } = {}) {
+  let deps;
+  try {
+    deps = await buildMigratedKernelIssueDeps({ projectRoot });
+  } catch {
+    return [];
+  }
+  try {
+    return await deps.kernelBroker.listRecentEvents({ since, limit });
+  } catch {
+    return [];
+  } finally {
+    if (deps.kernelDriver && typeof deps.kernelDriver.close === 'function') {
+      deps.kernelDriver.close();
+    }
+  }
+}
+
+// Map a kernel_events row back to the interaction shape insights consumes. Imported beads
+// interactions carry event_type `beads.interaction.<kind>` and payload_json `{ kind, ...extra }`
+// where field/new_value/reason live at the top level alongside kind (see beads-kernel-compat
+// mapBeadsInteractionToKernel). Native kernel events fall back to their event_type as the kind.
+function eventToInteraction(row) {
+  if (!row || typeof row !== 'object') return null;
+  let parsed;
+  try {
+    parsed = row.payload_json ? JSON.parse(row.payload_json) : row.payload;
+  } catch {
+    parsed = null;
+  }
+  // A scalar or array payload carries no interaction fields — treat it as empty.
+  const payload = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  const kind = payload.kind
+    || String(row.event_type || '').replace(/^beads\.interaction\./, '')
+    || 'interaction';
+  return {
+    kind,
+    id: row.id,
+    issue_id: row.entity_id || null,
+    created_at: row.created_at || null,
+    extra: payload,
+  };
+}
+
+// Read all issues from the Kernel (the sole issue-state authority) for theme mining.
+// Resilient: any read failure degrades to empty issue evidence rather than throwing.
+async function listKernelIssues(projectRoot, runIssueOperation, env) {
+  try {
+    const result = await runIssueOperation('list', [], projectRoot, { issueBackend: 'kernel', env });
+    if (result && result.ok && result.data && Array.isArray(result.data.issues)) {
+      return result.data.issues;
+    }
+  } catch {
+    // best-effort: insights never crashes on a kernel read failure
+  }
+  return [];
+}
 const STOP_WORDS = new Set([
   'after',
   'against',
@@ -108,10 +174,15 @@ function addPattern(map, key, patch) {
   map.set(key, existing);
 }
 
-function interactionPatterns(projectRoot, options, map) {
-  const rows = readJsonl(path.join(projectRoot, '.beads', 'interactions.jsonl'));
-  for (const row of rows) {
-    if (!row || typeof row !== 'object' || row._parseError || !isSince(row.created_at, options.since)) continue;
+async function interactionPatterns(projectRoot, options, map) {
+  const listRecentEvents = options.listRecentEvents || defaultListRecentEvents;
+  const since = options.since ? options.since.toISOString() : null;
+  const rawEvents = await listRecentEvents(projectRoot, { since, limit: EVENT_READ_LIMIT, env: options.env });
+  const interactions = (Array.isArray(rawEvents) ? rawEvents : [])
+    .map(eventToInteraction)
+    .filter(Boolean);
+  for (const row of interactions) {
+    if (!isSince(row.created_at, options.since)) continue;
     const extra = row.extra && typeof row.extra === 'object' ? row.extra : {};
     if (row.kind === 'field_change' && extra.field) {
       const family = reasonFamily(extra.reason);
@@ -120,7 +191,7 @@ function interactionPatterns(projectRoot, options, map) {
         kind: 'interaction',
         title: `${extra.field} changed to ${extra.new_value || 'changed'} (${family})`,
         evidence: row.issue_id || row.id,
-        source: '.beads/interactions.jsonl',
+        source: 'kernel_events',
         lastSeen: row.created_at,
       });
     } else if (row.kind) {
@@ -128,12 +199,12 @@ function interactionPatterns(projectRoot, options, map) {
         kind: 'interaction',
         title: `Interaction event: ${row.kind}`,
         evidence: row.issue_id || row.id,
-        source: '.beads/interactions.jsonl',
+        source: 'kernel_events',
         lastSeen: row.created_at,
       });
     }
   }
-  return rows;
+  return interactions;
 }
 
 function words(value) {
@@ -153,9 +224,9 @@ function words(value) {
   return tokens;
 }
 
-function issuePatterns(projectRoot, options, map) {
-  const rows = readJsonl(path.join(projectRoot, '.beads', 'issues.jsonl'))
-    .filter(row => row && !row._parseError && row._type === 'issue');
+async function issuePatterns(projectRoot, options, map) {
+  const runIssueOperation = options.runIssueOperation || defaultRunIssueOperation;
+  const rows = await listKernelIssues(projectRoot, runIssueOperation, options.env);
   const perWord = new Map();
   for (const issue of rows) {
     if (!isSince(issue.updated_at || issue.closed_at || issue.created_at, options.since)) continue;
@@ -173,7 +244,7 @@ function issuePatterns(projectRoot, options, map) {
       title: `Recurring issue theme: ${word}`,
       count: issues.length,
       evidence: issues.slice(0, 5).map(issue => issue.id).join(', '),
-      source: '.beads/issues.jsonl',
+      source: 'kernel',
       lastSeen: issues.map(issue => asDate(issue.updated_at || issue.closed_at || issue.created_at))
         .filter(Boolean)
         .sort((a, b) => b - a)[0],
@@ -244,11 +315,19 @@ function candidateFromPattern(pattern) {
   };
 }
 
-function analyzeInsights(projectRoot, options = {}) {
+async function analyzeInsights(projectRoot, options = {}) {
   const normalized = normalizeOptions(options);
+  // Read options carry the normalized thresholds PLUS the injectable kernel seams
+  // (defaulted to the real cli-broker-factory-backed reads) so tests can supply fakes.
+  const readOptions = {
+    ...normalized,
+    runIssueOperation: options.runIssueOperation,
+    listRecentEvents: options.listRecentEvents,
+    env: options.env,
+  };
   const map = new Map();
-  const interactions = interactionPatterns(projectRoot, normalized, map);
-  const issues = issuePatterns(projectRoot, normalized, map);
+  const interactions = await interactionPatterns(projectRoot, readOptions, map);
+  const issues = await issuePatterns(projectRoot, readOptions, map);
   const audit = auditPatterns(projectRoot, normalized, map);
   const patterns = toPatternList(map, normalized);
   const candidates = patterns.map(candidateFromPattern);
@@ -267,7 +346,7 @@ function analyzeInsights(projectRoot, options = {}) {
     candidates,
     limitations: [
       'Insights are local workflow signals, not proof of correctness.',
-      'Sparse Beads interactions or missing audit logs reduce confidence.',
+      'Sparse kernel events or missing audit logs reduce confidence.',
       'Accepting a suggestion records a decision; it does not install trusted executable code.',
     ],
   };
@@ -314,6 +393,8 @@ function recordInsightDecision(projectRoot, candidateId, status, options = {}) {
   }, {
     memory: options.memory,
     tags: ['insights', status],
+    // `beadsRefs` is a persisted typed-memory field name kept for data-shape compat
+    // (imported/legacy memories carry it); the values are historical issue references.
     beadsRefs: ISSUE_REFS,
     provenance: {
       actor: 'forge insights',
@@ -323,75 +404,10 @@ function recordInsightDecision(projectRoot, candidateId, status, options = {}) {
   });
 }
 
-function issueSummary(issues) {
-  return issues.reduce((summary, issue) => {
-    summary.total += 1;
-    if (issue.status === 'closed') summary.closed += 1;
-    else summary.open += 1;
-    return summary;
-  }, { total: 0, open: 0, closed: 0 });
-}
-
-function buildRecap(projectRoot, options = {}) {
-  const normalized = normalizeOptions(options);
-  const insights = analyzeInsights(projectRoot, options);
-  const issues = readJsonl(path.join(projectRoot, '.beads', 'issues.jsonl'))
-    .filter(row => row && !row._parseError && row._type === 'issue')
-    .filter(issue => isSince(issue.updated_at || issue.closed_at || issue.created_at, normalized.since));
-  const interactions = readJsonl(path.join(projectRoot, '.beads', 'interactions.jsonl'))
-    .filter(row => row && typeof row === 'object' && !row._parseError)
-    .filter(row => isSince(row.created_at, normalized.since));
-  const reviewOutcomes = interactions.filter(row => {
-    const reason = row.extra?.reason || '';
-    return reasonFamily(reason) === 'merged-and-verified' || String(reason).toLowerCase().includes('review');
-  }).length;
-  const recentIssues = [...issues]
-    .sort((a, b) => String(b.updated_at || b.closed_at || b.created_at || '').localeCompare(String(a.updated_at || a.closed_at || a.created_at || '')))
-    .slice(0, normalized.limit)
-    .map(issue => ({
-      id: issue.id,
-      title: issue.title,
-      status: issue.status,
-    }));
-
-  return {
-    generatedAt: new Date().toISOString(),
-    issueSummary: issueSummary(issues),
-    reviewOutcomes,
-    recentIssues,
-    insights,
-  };
-}
-
-function formatRecapText(recap) {
-  const lines = [
-    'Forge recap',
-    `Issues: ${recap.issueSummary.total} total, ${recap.issueSummary.open} open, ${recap.issueSummary.closed} closed`,
-    `Review outcomes found: ${recap.reviewOutcomes}`,
-    'Recent work:',
-  ];
-  for (const issue of recap.recentIssues) {
-    lines.push(`- ${issue.id}: ${issue.title} [${issue.status || 'unknown'}]`);
-  }
-  lines.push('Insight candidates:');
-  if (recap.insights.candidates.length === 0) {
-    lines.push('- No strong recurring patterns found.');
-  } else {
-    for (const candidate of recap.insights.candidates) {
-      lines.push(`- ${candidate.id}: ${candidate.title}`);
-    }
-  }
-  lines.push('Limitations:');
-  for (const limitation of recap.insights.limitations) lines.push(`- ${limitation}`);
-  return `${lines.join('\n')}\n`;
-}
-
 module.exports = {
   ISSUE_REFS,
   analyzeInsights,
-  buildRecap,
   formatInsightsText,
-  formatRecapText,
   readJsonl,
   recordInsightDecision,
 };