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

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',
@@ -33,7 +33,7 @@ const SOURCE_ROWS = [
   ['S4', 'Cursor MCP', 'https://docs.cursor.com/context/model-context-protocol', 'Cursor connects external tools and data sources through MCP using stdio, SSE, and streamable HTTP transports.'],
   ['S5', 'Codex skills', 'https://developers.openai.com/codex/skills', 'Codex skills package instructions, resources, and scripts; Codex scans .agents/skills from cwd up to the repo root for repo-scope discovery. Forge installs the global $CODEX_HOME/skills from the canonical skills/ source AND commits the repo-local .agents/skills mirror (kept in sync with skills/ by a pre-commit hook + drift gate) for teammate-clone discovery.'],
   ['S6', 'Codex MCP', 'https://developers.openai.com/codex/mcp', 'Codex configures MCP servers in config.toml and supports plugin-provided MCP servers.'],
-  ['S7', 'Codex hooks', 'https://developers.openai.com/codex/hooks', 'Codex hooks run deterministic scripts during lifecycle events.'],
+  ['S7', 'Codex hooks', 'https://developers.openai.com/codex/hooks', 'Codex hooks run deterministic scripts during lifecycle events; they live in GLOBAL $CODEX_HOME/config.toml so project setup does not render them. Codex instead reads the committed project-local AGENTS.md every session, which is the always-on carrier for Forge instruction/policy including the using-forge skill-dispatch pointer (see S9).'],
   ['S8', 'Codex plugins and marketplaces', 'https://developers.openai.com/codex/plugins/build', 'Codex plugins can package skills, apps, MCP servers, hooks, and marketplace metadata.'],
   ['S9', 'AGENTS.md standard', 'https://agents.md/', 'AGENTS.md provides repository instructions for coding agents.'],
   ['S10', 'Cursor Agent Skills', 'https://docs.cursor.com/en/agent/skills', 'Cursor reads on-demand Agent Skills from .cursor/skills/<name>/SKILL.md; Forge populates them at setup from the canonical skills/ source.'],
@@ -41,7 +41,7 @@ const SOURCE_ROWS = [
   ['S12', 'Cursor ignore files', 'https://cursor.com/docs/reference/ignore-file', 'Cursor reads project-local .cursorignore (blocks AI access + indexing) and .cursorindexingignore (index-only), gitignore-style; .gitignore and common secret/lock files are ignored by default.'],
   ['S13', 'Codex sandbox and approvals config', 'https://developers.openai.com/codex/config-reference', 'Codex config.toml sets sandbox_mode (read-only/workspace-write/danger-full-access) and approval_policy (untrusted/on-request/never); a project-local .codex/config.toml is honored ONLY when the project is trusted in the GLOBAL $CODEX_HOME/config.toml (projects.<path>.trust_level).'],
   ['S14', 'Claude Code hooks', 'https://code.claude.com/docs/en/hooks', 'Claude Code hooks live in .claude/settings.json under a `hooks` block; a PreToolUse matcher group (e.g. "Write|Edit"/"Bash") runs a command that can deny the tool call via hookSpecificOutput.permissionDecision.'],
-  ['S15', 'Cursor hooks', 'https://cursor.com/docs/hooks', 'Cursor 1.7+ reads project-local .cursor/hooks.json ({ version: 1, hooks }); only before* events (beforeShellExecution/beforeReadFile/beforeMCPExecution) can deny — there is no pre-edit deny event, so afterFileEdit is observational.'],
+  ['S15', 'Cursor hooks', 'https://cursor.com/docs/hooks', 'Cursor 1.7+ reads project-local .cursor/hooks.json ({ version: 1, hooks }); only before* events (beforeShellExecution/beforeReadFile/beforeMCPExecution) can deny — there is no pre-edit deny event, so afterFileEdit is observational. Cursor hooks are therefore NOT the session-context path: Cursor auto-injects always-apply .cursor/rules/*.mdc (alwaysApply:true) every session (see S3), which is the always-on carrier for the using-forge skill-dispatch pointer.'],
   ['S16', 'Hermes Agent event hooks', 'https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/', 'Hermes (NousResearch) shell hooks are declared in a `hooks:` block in the GLOBAL ~/.hermes/config.yaml; each matcher/command entry runs as a subprocess over a JSON-stdin/stdout wire protocol, and a pre_tool_call hook CAN deny a tool call ({action:block, message} — it also accepts the Claude-Code {decision:block, reason} shape).'],
 ];
 
@@ -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',
@@ -80,6 +80,9 @@ const FORGE_INBOX_CONTEXT_MARKER = 'hooks inbox-pickup';
 // Forge UserPromptSubmit group is already recognized via the inbox marker, but this keeps
 // the shepherd-events command independently identifiable (symmetry with the other tiers).
 const FORGE_SHEPHERD_EVENTS_MARKER = 'hooks shepherd-events';
+// The memory-recall context hook (UserPromptSubmit tier). Its own idempotency marker so a
+// re-render recognizes and REPLACES the Forge-owned entry in place rather than duplicating it.
+const FORGE_MEMORY_RECALL_MARKER = 'hooks memory-recall';
 // The capture-on-exit context hook (PreCompact + Stop tier). A THIRD context marker so a
 // re-merge recognizes + replaces the Forge-owned PreCompact/Stop entries in place. Both
 // events share this one marker (they differ only by a --trigger suffix on the command).
@@ -91,16 +94,33 @@ const FORGE_SHEPHERD_EVENTS_MARKER = 'hooks shepherd-events';
 // the merge replaces exactly Forge's group and preserves the user's.
 const FORGE_CAPTURE_CONTEXT_MARKER = `${FORGE_CLI} hooks capture`;
 
-// Per-harness SessionStart context-injection capability. Honest capability matrix —
-// only Claude exposes a native session-start surface that can inject additionalContext.
-// Cursor's 1.7 hooks are deny-oriented (no session-start context surface); Codex and
-// Hermes hooks live in GLOBAL home config that project setup never writes. We NEVER
-// fake parity: each non-Claude harness carries an explicit, tested skip reason.
+// Per-harness SessionStart HOOK-render capability. This constant governs ONE thing: whether
+// Forge renders a harness-native SessionStart *hook* that injects additionalContext. Only Claude
+// exposes that surface, so only Claude is rendered:true. Every other harness is rendered:false
+// with an HONEST reason naming WHERE the same dispatch bootstrap is delivered instead — because
+// the bootstrap is NOT Claude-only, it just travels a different always-on surface per harness
+// (see BOOTSTRAP_DELIVERY below): Cursor auto-applies an always-on rule (.cursor/rules/*.mdc,
+// alwaysApply:true); Codex reads the committed project-local AGENTS.md every session; Hermes
+// consumes it through the forge CLI (forge prime/orient + forge skill for). We NEVER fake parity
+// and NEVER branch on harness identity at runtime — delivery is keyed by SURFACE TYPE.
 const SESSION_START_SUPPORT = Object.freeze({
   claude: Object.freeze({ rendered: true }),
-  cursor: Object.freeze({ rendered: false, reason: 'no-session-start-surface' }),
-  codex: Object.freeze({ rendered: false, reason: 'global-config' }),
-  hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
+  cursor: Object.freeze({ rendered: false, reason: 'delivered-via-rule-surface' }),
+  codex: Object.freeze({ rendered: false, reason: 'delivered-via-agents-md' }),
+  hermes: Object.freeze({ rendered: false, reason: 'delivered-via-cli-fallback' }),
+});
+
+// Where the using-forge dispatch BOOTSTRAP reaches each harness EVERY session. Data, not
+// identity-branching: the parity gate iterates this so no harness is silently left with no
+// auto-surface. Only Claude's is a native SessionStart hook; the rest are equally always-on
+// surfaces (a Cursor always-apply rule, the committed AGENTS.md for Codex, the forge CLI as an
+// honest fallback for Hermes). All four ALSO carry the full using-forge SKILL.md via the synced
+// skill mirrors. 'cli-fallback' is the explicit honest-fallback marker (no faked native surface).
+const BOOTSTRAP_DELIVERY = Object.freeze({
+  claude: 'session-start-hook',
+  cursor: 'always-apply-rule',
+  codex: 'agents-md',
+  hermes: 'cli-fallback',
 });
 
 // Per-harness UserPromptSubmit context-injection capability (the near-real-time inbox
@@ -179,6 +199,22 @@ const FORGE_HOOK_CONTRACT = Object.freeze({
       lifecycle: 'user-prompt-submit',
       command: `${FORGE_CLI} hooks inbox-pickup`,
     }),
+    Object.freeze({
+      id: 'memory-recall',
+      kind: 'context',
+      cliAction: 'memory-recall',
+      // QUERY-RELEVANT MEMORY (tier-2): on each prompt, ranks stored memories by BM25
+      // relevance to the submitted prompt (read from the hook's own stdin) and injects the
+      // survivors, gated by a relevance floor + anaphora guard + cross-turn dedupe + a hard
+      // token budget. Complements the recency digest at SessionStart, which answers a
+      // different question (what's newest, not what's relevant to THIS turn). Reads the
+      // user's OWN kernel memory via a supported hook and its own stdin input — it NEVER
+      // injects into a running session's stdin and never drives the agent (Anthropic Usage
+      // Policy). Kill-switch: `forge gate disable rail.memory_recall`.
+      enforces: 'Memory recall: on each UserPromptSubmit, inject query-relevant stored memories ranked by BM25 against the submitted prompt, gated by a relevance floor, an anaphora guard, cross-turn dedupe, and a hard token budget (compact to avoid additionalContext accumulation). Additive and FAIL-OPEN — nothing relevant, a disabled rail, or any error injects nothing and never blocks a prompt.',
+      lifecycle: 'user-prompt-submit',
+      command: `${FORGE_CLI} hooks memory-recall`,
+    }),
     Object.freeze({
       id: 'shepherd-events',
       kind: 'context',
@@ -295,15 +331,18 @@ function renderClaudeHooks(contract) {
     // Surfaces pending targeted dashboard instruction comments (fenced kernel DATA) on each
     // prompt; the command emits { hookSpecificOutput.additionalContext }. Reads the user's
     // own kernel data via a supported hook — NEVER stdin injection (Anthropic Usage Policy).
-    // Both UserPromptSubmit context hooks share ONE Forge-owned group (inbox-pickup +
-    // PR-shepherd deltas). Claude runs every hook in the group and appends each hook's
-    // additionalContext; keeping them in one group means a re-merge replaces the pair
-    // atomically (the group is Forge-owned via either marker). Both are compact + fail-open.
+    // The UserPromptSubmit context hooks share ONE Forge-owned group (inbox-pickup nudge,
+    // PR-shepherd deltas, and query-relevant memory recall). Claude runs every hook in the
+    // group and appends each hook's additionalContext; keeping them in one group means a
+    // re-merge replaces the set atomically (the group is Forge-owned via any of their
+    // markers). All three are compact + fail-open. (memory-recall reads its own hook stdin
+    // for the prompt — that is its supported input, not session-stdin injection.)
     UserPromptSubmit: [
       {
         hooks: [
           { type: 'command', command: harnessCommand(contract, 'inbox-pickup', 'claude') },
           { type: 'command', command: harnessCommand(contract, 'shepherd-events', 'claude') },
+          { type: 'command', command: harnessCommand(contract, 'memory-recall', 'claude') },
         ],
       },
     ],
@@ -398,6 +437,7 @@ function isForgeCommand(command) {
       || command.includes(FORGE_CONTEXT_MARKER)
       || command.includes(FORGE_INBOX_CONTEXT_MARKER)
       || command.includes(FORGE_SHEPHERD_EVENTS_MARKER)
+      || command.includes(FORGE_MEMORY_RECALL_MARKER)
       || command.includes(FORGE_CAPTURE_CONTEXT_MARKER));
 }
 
@@ -407,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;
@@ -439,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;
@@ -471,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
@@ -497,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') : '';
 
@@ -506,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 };
 }
@@ -523,8 +650,10 @@ module.exports = {
   FORGE_HOOK_MARKER,
   FORGE_CONTEXT_MARKER,
   FORGE_INBOX_CONTEXT_MARKER,
+  FORGE_MEMORY_RECALL_MARKER,
   FORGE_CAPTURE_CONTEXT_MARKER,
   SESSION_START_SUPPORT,
+  BOOTSTRAP_DELIVERY,
   USER_PROMPT_SUBMIT_SUPPORT,
   SESSION_END_SUPPORT,
   sessionStartCapability,
@@ -536,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,
 };