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

package/lib/kernel/backing-issue.js

@@ -39,7 +39,14 @@ const DEFAULT_IGNORE_GLOBS = Object.freeze(['tmp/*', 'spike/*', 'wip/*', 'throwa
 const AUTO_STUB_LABEL = 'auto-stub';
 // Branch prefixes stripped before deriving a title / probing for an encoded issue id.
 const BRANCH_PREFIX = /^(feat|feature|fix|bugfix|hotfix|chore|refactor|docs|test|spike|wip)\//i;
-// An issue key encoded in a branch slug, e.g. `feat/kap-7-foo` -> `kap-7`.
+// A full Kernel issue id (UUID) named anywhere in the branch, e.g.
+// `feat/18f1988e-...-close-on-merge`. Kernel ids ARE UUIDs, so this is the shape a
+// real branch->issue reference actually takes; kept identical to the UUID_RE that
+// resolveActiveIssueId (lib/workflow/enforce-stage.js) matches, so every resolver
+// agrees on which issue a branch names.
+const ENCODED_UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+// Legacy Beads-era issue key encoded in a branch slug, e.g. `feat/kap-7-foo` -> `kap-7`.
+// Still honored for stores imported via `forge migrate --from beads`.
 const ENCODED_ISSUE_ID = /^([a-z][a-z0-9]*-\d+)\b/i;
 // Regex metacharacters escaped when compiling an ignore glob.
 const GLOB_METACHARS = '.+^${}()|[]\\';
@@ -145,12 +152,17 @@ function deriveTitle(branch) {
 }
 
 /**
- * Extract an issue id encoded in the branch name (e.g. `feat/kap-7-foo` -> `kap-7`).
+ * Extract an issue id named in the branch: a Kernel UUID anywhere in the name
+ * (`feat/18f1988e-...-foo`), else a legacy Beads key at the head of the slug
+ * (`feat/kap-7-foo` -> `kap-7`). The caller VERIFIES the id exists before linking,
+ * so a branch that merely looks like an id never binds to a phantom issue.
  *
  * @param {string} branch
  * @returns {string|null}
  */
 function extractEncodedIssueId(branch) {
+  const uuid = ENCODED_UUID.exec(String(branch));
+  if (uuid) return uuid[0];
   const match = ENCODED_ISSUE_ID.exec(stripPrefix(branch));
   return match ? match[1] : null;
 }

package/lib/kernel/broker.js

@@ -782,6 +782,12 @@ async function buildIssueMutationEvent(driver, operation, args, context, config)
 	const payload = operation === 'comment'
 		? buildCommentPayload(issueId, args)
 		: buildUpdatePayload(flags);
+	// `close` already means the terminal `done` transition. Treat an explicit
+	// `--status done` as that same default close intent so it does not get checked
+	// as the generic (and illegal) open -> done update transition below.
+	if (operation === 'close' && payload.status === 'done') {
+		delete payload.status;
+	}
 	// update/close validate only the supplied taxonomy fields (no mandatory title);
 	// comment carries no taxonomy fields, so it is exempt.
 	if (operation !== 'comment') {
@@ -1177,6 +1183,16 @@ function createLocalBroker(options = {}) {
 			return driver.importIssues(kernel, options, {}, config);
 		},
 
+		// Bulk activity read for `forge insights` (Slice C2). Read-only SELECT over
+		// kernel_events, newest first, bounded by an optional `since` ISO cutoff + `limit`.
+		// Additive: deliberately NOT registered in GUARDED_DRIVER_METHODS (the write-path
+		// contract), so existing driver stubs that never call it stay valid. Imported beads
+		// interactions live here as `beads.interaction.<kind>` events. Creates/migrates nothing.
+		async listRecentEvents(options = {}, context = {}) {
+			requireDriverMethod(driver, 'listRecentKernelEvents');
+			return driver.listRecentKernelEvents(options, context, getConfig());
+		},
+
 		// PR reconcile-ledger read (autonomous-shepherd design §3.4). Read-only SELECT of
 		// the open `pr` rows for a repo (keyed by git_common_dir); creates/migrates nothing.
 		// Consumed later by prime and the reconciler to enumerate PRs under shepherd.

package/lib/kernel/cli-broker-factory.js

@@ -113,7 +113,18 @@ async function buildMigratedKernelIssueDeps(options = {}) {
     databasePath: deps.kernelDatabasePath,
     driver: deps.kernelDriver,
   });
-  await ensureKernelMigrated(broker);
+  const close = async () => {
+    if (typeof deps.kernelDriver.close === 'function') {
+      await deps.kernelDriver.close();
+    }
+  };
+  broker.close = close;
+  try {
+    await ensureKernelMigrated(broker);
+  } catch (error) {
+    try { await close(); } catch { /* preserve the migration failure */ }
+    throw error;
+  }
   return {
     useKernelBroker: true,
     kernelBroker: broker,

package/lib/kernel/close-on-merge.js

@@ -0,0 +1,154 @@
+'use strict';
+
+/**
+ * Close-on-merge linkage (kernel issue 18f1988e).
+ *
+ * The branch->issue linkage backbone shipped (kernel_worktrees rows written by
+ * `forge worktree create` and the auto-file rail), but nothing ever consumed it:
+ * a merged PR closed no kernel issue, so finished work stayed open forever. A
+ * hygiene sweep on 2026-07-25 closed 104 such issues, 61 of them auto-stubs
+ * minted on branch push whose merged PR closed nothing.
+ *
+ * This module is the consumer. Given a branch whose PR is known to be MERGED, it
+ * comments the merge evidence onto the linked kernel issue and closes it.
+ *
+ * Safety properties (each covered by test/kernel/close-on-merge.test.js):
+ *   - LINKED ONLY. The issue comes from the kernel_worktrees linkage registry via
+ *     resolveActiveIssueId — the same authoritative resolver `forge ship` stage
+ *     state uses. An issue is never guessed from the branch/PR title, so a merge
+ *     can only ever close the issue the branch was actually bound to.
+ *   - IDEMPOTENT. The issue's status is read back first; a terminal issue
+ *     (`done` / `cancelled` — the kernel's real terminal vocabulary) is a pure
+ *     no-op that writes neither a comment nor a close. Running clean twice
+ *     closes once.
+ *   - NEVER CLOSES BLIND. An unreadable status is a skip, not an assumption.
+ *   - BEST EFFORT. Every failure path — no kernel, a throwing driver, a rejected
+ *     mutation — resolves to `{ closed: false, reason }`. Nothing throws, so
+ *     `forge clean` still removes worktrees when tracking is broken.
+ *
+ * Writes go through the supported `runIssueOperation` seam (lib/forge-issues.js),
+ * the same path `forge inbox ack` uses, so kernel events/provenance are recorded
+ * exactly as a hand-run `forge comment` / `forge close` would be.
+ *
+ * @module kernel/close-on-merge
+ */
+
+const { resolveActiveIssueId } = require('../workflow/enforce-stage');
+const { isWorkableStatus } = require('./readiness-model');
+
+/**
+ * Render the merge-evidence comment posted onto the issue before it is closed.
+ * Stays honest when the PR could not be resolved: `forge clean` also detects a
+ * merge by git patch-equivalence, with no GitHub data to cite.
+ *
+ * @param {object} params
+ * @param {string} params.branch - Merged branch name
+ * @param {{number: number, title?: string, mergeCommitOid?: string}|null} [params.pr]
+ * @returns {string} Comment body
+ */
+function buildMergeEvidence({ branch, pr }) {
+  const lines = ['Closed automatically: the branch backing this issue was merged.', '', `branch: ${branch}`];
+  if (pr && pr.number) {
+    lines.push(`pull request: #${pr.number}${pr.title ? ` — ${pr.title}` : ''}`);
+    if (pr.mergeCommitOid) lines.push(`merge commit: ${pr.mergeCommitOid}`);
+  } else {
+    lines.push('pull request: no pull request resolved (merge detected from git history)');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Render the `--reason` recorded on the close event.
+ *
+ * @param {object} params
+ * @param {string} params.branch
+ * @param {{number: number}|null} [params.pr]
+ * @returns {string}
+ */
+function buildCloseReason({ branch, pr }) {
+  return pr && pr.number ? `merged in PR #${pr.number}` : `branch ${branch} merged`;
+}
+
+/**
+ * Read an issue's current status through the supported read path.
+ *
+ * @param {Function} runIssueOperation
+ * @param {string} issueId
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>} the status, or null when it could not be read.
+ */
+async function readIssueStatus(runIssueOperation, issueId, projectRoot) {
+  const result = await runIssueOperation('show', [issueId, '--json'], projectRoot);
+  if (!result || result.ok !== true || !result.data) return null;
+  const status = result.data.status;
+  return typeof status === 'string' && status ? status : null;
+}
+
+/** @returns {boolean} whether a mutation envelope reports success. */
+function mutationSucceeded(result) {
+  return Boolean(result && (result.ok === true || result.success === true));
+}
+
+/**
+ * Comment the merge evidence onto the linked kernel issue and close it.
+ * See the module doc for the full contract. NEVER throws.
+ *
+ * @param {object} options
+ * @param {string} options.branch - The merged branch.
+ * @param {string} [options.projectRoot] - Repo root threaded to the issue runner.
+ * @param {{number: number, title?: string, mergeCommitOid?: string}|null} [options.pr]
+ *   Merge evidence from GitHub, when available.
+ * @param {object} options.driver - Kernel driver exposing the worktree linkage registry.
+ * @param {Function} options.runIssueOperation - (operation, args, projectRoot) => envelope.
+ * @param {Function} [options.resolveIssueId] - Override the branch->issue resolver (tests).
+ * @returns {Promise<{closed: boolean, issueId?: string|null, reason?: string,
+ *   commented?: boolean, status?: string, error?: string}>}
+ */
+async function closeLinkedIssueOnMerge(options = {}) {
+  const { branch, projectRoot, pr = null, driver, runIssueOperation } = options;
+  try {
+    if (!branch || typeof branch !== 'string') return { closed: false, reason: 'no-branch' };
+    if (!driver || typeof runIssueOperation !== 'function') {
+      return { closed: false, reason: 'unavailable' };
+    }
+
+    // Linked only — never a title/heuristic match.
+    const resolveIssueId = options.resolveIssueId || resolveActiveIssueId;
+    const issueId = await resolveIssueId(driver, branch);
+    if (!issueId) return { closed: false, reason: 'not-linked' };
+
+    // Idempotency + never-close-blind: read the current status first.
+    const status = await readIssueStatus(runIssueOperation, issueId, projectRoot);
+    if (!status) return { closed: false, reason: 'read-failed', issueId };
+    if (!isWorkableStatus(status)) {
+      return { closed: false, reason: 'already-closed', issueId, status };
+    }
+
+    // Evidence first, so it survives even if the close is rejected.
+    const commentResult = await runIssueOperation(
+      'comment',
+      [issueId, buildMergeEvidence({ branch, pr })],
+      projectRoot,
+    );
+    const commented = mutationSucceeded(commentResult);
+
+    const closeResult = await runIssueOperation(
+      'close',
+      [issueId, '--reason', buildCloseReason({ branch, pr })],
+      projectRoot,
+    );
+    if (!mutationSucceeded(closeResult)) {
+      return { closed: false, reason: 'close-failed', issueId, commented };
+    }
+    return { closed: true, issueId, commented };
+  } catch (error) {
+    // Best-effort: cleanup must never break on tracking.
+    return { closed: false, reason: 'error', error: error && error.message };
+  }
+}
+
+module.exports = {
+  closeLinkedIssueOnMerge,
+  buildMergeEvidence,
+  buildCloseReason,
+};

package/lib/kernel/fs-class.js

@@ -284,7 +284,7 @@ function driveLetterOf(absPath) {
 
 // Bounded exec options for the Windows drive probes. The timeout is the BLOCKER-1
 // fix: execFileSync's try/catch only catches throws, never hangs, so an
-// unresponsive `net use` / PowerShell (e.g. a wedged network redirector) would
+// an unresponsive `net use` probe (e.g. a wedged network redirector) would
 // hang the whole process indefinitely. With a timeout, a hang becomes a throw
 // that the gatherSignals catch turns into driveType='unknown' → warn (never
 // refuse), symmetric with the G1 fail-safe. killSignal forces the child dead.
@@ -310,18 +310,21 @@ function parseNetUseDriveType(stdout, driveLetter) {
 	return null;
 }
 
-// PURE (M5): a non-empty PowerShell DisplayRoot means the PSDrive is backed by a
-// network/remote root. Returns 'network' when non-blank, else null.
-function parseDisplayRoot(stdout) {
-	return String(stdout || '').trim() ? 'network' : null;
-}
-
 // Windows: detect whether a drive letter is a mapped network drive.
-// FAIL-SAFE FALLBACK (locked decision G1, option a): try `net use`, then a
-// PowerShell DisplayRoot fallback; on ANY probe failure (including a timeout-
-// induced throw, per BLOCKER 1) the caller treats the result as 'unknown'.
-// Probes use arg ARRAYS (no shell) so they remain injection-free.
+// The conventional local C: drive is fixed without a subprocess. `net use` is
+// authoritative for other mapped drive letters, while a no-match remains
+// unknown because it does not prove that an SMB/cloud redirector is absent. The unknown
+// result is fail-open (warn), while UNC and cloud path signals still refuse.
+// Do not launch a second shell process for every kernel child. Under a heavily
+// sharded suite those redundant fallback probes contend for host resources and
+// can leave a shard blocked indefinitely.
+// A probe failure still propagates to the gatherer, which maps it to the
+// fail-safe `unknown`/warn classification.
+// The probe uses an arg ARRAY (no shell) so it remains injection-free.
 function defaultProbeDriveType(driveLetter, deps = {}) {
+	const normalizedDriveLetter = String(driveLetter || '').trim().toUpperCase();
+	if (normalizedDriveLetter === 'C:') return 'fixed';
+
 	const exec = deps.execFileSync || execFileSync;
 
 	// Primary: `net use` lists mapped drive letters (and their remote paths).
@@ -330,17 +333,9 @@ function defaultProbeDriveType(driveLetter, deps = {}) {
 		return 'network';
 	}
 
-	// Secondary: PowerShell DisplayRoot — non-empty for network-backed PSDrives.
-	const psLetter = String(driveLetter).replace(':', '');
-	const psCmd =
-		`(Get-PSDrive -Name '${psLetter}' -ErrorAction SilentlyContinue).DisplayRoot`;
-	const psOut = exec('powershell', ['-NoProfile', '-Command', psCmd], WIN_PROBE_EXEC_OPTIONS);
-	if (parseDisplayRoot(psOut) === 'network') {
-		return 'network';
-	}
-
-	// Letter exists, no network backing detected → fixed.
-	return 'fixed';
+	// `net use` completed successfully without listing this non-system letter.
+	// A no-match is not evidence that an SMB/cloud redirector is absent.
+	return 'unknown';
 }
 
 // Linux: read /proc/mounts, return fs type of the longest mountpoint prefixing absPath.
@@ -443,27 +438,49 @@ function isUnsafeFsOverrideActive(env = {}) {
 	return value === '1' || value === 'true';
 }
 
+// The gate runs on every broker instance, and one command builds several
+// (`forge status` and `forge prime` each build four), so an un-memoized advisory
+// printed four times per command. The advisory describes the process's database
+// path, not the broker, so it is emitted once per (tier, class, path) per
+// process. Keyed rather than a single flag so a second path — or a path that
+// reclassifies — is still reported. Warnings only: `refuse` still throws on
+// every call, so deduping can never turn a refusal into a pass.
+const warnedFilesystemKeys = new Set();
+
+function resetFilesystemWarningMemo() {
+	warnedFilesystemKeys.clear();
+}
+
 function assertFilesystemSafeForKernel(dbPath, deps = {}) {
 	const env = deps.env || process.env;
+	// console.warn writes to stderr, which is the contract here: `--json`
+	// consumers parse stdout, so an advisory on stdout would corrupt the envelope.
 	const warn = deps.warn || (msg => console.warn(msg));
 	const classify = deps.classifyFilesystem || classifyFilesystem;
 
 	const classification = classify(dbPath, deps);
 	const remediation = REMEDIATION[classification.remediationKey] || REMEDIATION.unknown;
 
+	const warnOnce = message => {
+		const key = `${classification.riskTier}|${classification.class}|${dbPath}`;
+		if (warnedFilesystemKeys.has(key)) return;
+		warnedFilesystemKeys.add(key);
+		warn(message);
+	};
+
 	if (classification.riskTier === 'safe') {
 		return classification;
 	}
 
 	if (classification.riskTier === 'warn') {
-		warn(`forge kernel filesystem warning (${classification.class}):\n${remediation}`);
+		warnOnce(`forge kernel filesystem warning (${classification.class}):\n${remediation}`);
 		return classification;
 	}
 
 	// refuse
 	const overrideActive = isUnsafeFsOverrideActive(env);
 	if (overrideActive) {
-		warn(
+		warnOnce(
 			`forge kernel filesystem REFUSE downgraded by FORGE_KERNEL_ALLOW_UNSAFE_FS ` +
 			`(${classification.class}) — override active:\n${remediation}`,
 		);
@@ -487,9 +504,9 @@ module.exports = {
 	gatherSignals,
 	classifyFilesystem,
 	assertFilesystemSafeForKernel,
+	resetFilesystemWarningMemo,
 	isUnsafeFsOverrideActive,
 	defaultProbeDriveType,
 	parseNetUseDriveType,
-	parseDisplayRoot,
 	REMEDIATION,
 };

package/lib/kernel/sqlite-driver.js

@@ -17,6 +17,7 @@ const { buildMemoryProjectionMigration, memoryFtsDdl } = require('./migrations')
 const { rankForPriorityLabel } = require('./taxonomy-validator');
 const { isLeaseExpired } = require('./lease-enforcer');
 const { CONFLICT_SIGNAL, classifyConflictSignal } = require('./conflict-signal');
+const { normalizeRecallHit } = require('../memory-recall');
 
 const BUILTIN_SQLITE_RUNTIME_ORDER = Object.freeze(['bun:sqlite', 'node:sqlite']);
 let probeCounter = 0;
@@ -800,6 +801,28 @@ function listKernelEventRows(runtime, db, entityType, entityId) {
 	);
 }
 
+// Bulk activity read (Slice C2, additive + read-only) across ALL entities, newest first,
+// for `forge insights`. `since` is an optional ISO cutoff (created_at >= since); `limit`
+// bounds the row count (default 1000). Imported beads interactions live here as
+// `beads.interaction.<kind>` events, so insights derives interaction patterns from this
+// instead of the retired legacy interactions log. Creates/migrates nothing.
+function listRecentKernelEventRows(runtime, db, since, limit) {
+	const params = [];
+	let where = '';
+	if (since) {
+		where = 'WHERE created_at >= ?';
+		params.push(since);
+	}
+	const cap = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.floor(Number(limit)) : 1000;
+	params.push(cap);
+	return allParams(
+		runtime,
+		db,
+		`SELECT * FROM kernel_events ${where} ORDER BY created_at DESC LIMIT ?`,
+		params,
+	);
+}
+
 // Look up the committed event for an idempotency key (the duplicate-replay probe).
 // The broker calls this unconditionally inside a Promise.all even for keyless
 // events, so guard a falsy key up front rather than binding undefined.
@@ -2049,6 +2072,17 @@ function buildMemoryFtsMatch(query) {
 	return tokens.map(token => `"${token}"`).join(' AND ');
 }
 
+// Like buildMemoryFtsMatch but OR-joins the tokens: a natural-language prompt matches a note
+// containing ANY of its keywords, not EVERY one. Used ONLY by the relevance-only SCORED read
+// (the per-turn recall hook) — a raw prompt ("why is my forge push taking so long") token-ANDed
+// required every word in one note and matched nothing (0% recall). Each token is double-quoted
+// for FTS5 safety (tokens may be non-Latin unicode). Returns '' when the query has no tokens.
+function buildMemoryFtsMatchOr(query) {
+	const tokens = String(query ?? '').match(/[\p{L}\p{N}]+/gu);
+	if (!tokens || tokens.length === 0) return '';
+	return tokens.map(token => `"${token}"`).join(' OR ');
+}
+
 // BM25 top-N recall over the kernel_memories_fts index (migration 008). Joins the FTS
 // rowid back to the memory row and orders by bm25 (lower = better match). An empty/tokenless
 // query falls back to recent entries so `recall` never returns a bare full dump.
@@ -2076,22 +2110,97 @@ function searchMemoryRowsRanked(runtime, db, query, limit) {
 // Unlike searchMemoryRowsRanked, a no-match (or empty) query returns [] with NO recency
 // fallback: the whole point is to avoid surfacing recent-but-irrelevant notes. bm25()
 // returns more-negative for stronger matches, so rows come back best (lowest) first.
-function searchMemoryRowsRankedScored(runtime, db, query, limit) {
+function confirmedMemorySql(alias) {
+	return `(EXISTS (
+		SELECT 1 FROM json_each(${alias}.tags_json)
+		WHERE lower(json_each.value) = 'trust:confirmed'
+	) OR (${alias}.source_agent = 'forge remember'
+		AND json_type(${alias}.value_json) = 'text'
+		AND NOT EXISTS (
+			SELECT 1 FROM json_each(${alias}.tags_json)
+			WHERE lower(json_each.value) LIKE 'trust:%'
+				OR lower(json_each.value) = 'forge:auto-capture'
+		)))`;
+}
+
+function projectMemoryScopeSql(alias) {
+	return `(${alias}.scope IS NULL OR ${alias}.scope = 'project' OR ${alias}.scope = ?)`;
+}
+
+function suggestedFreshnessCutoff(now) {
+	const timestamp = Date.parse(now || new Date().toISOString());
+	return new Date(timestamp - (7 * 24 * 60 * 60 * 1000)).toISOString();
+}
+
+function searchMemoryRowsRankedScored(runtime, db, query, limit, options = {}) {
 	const capped = Number.isInteger(limit) && limit > 0 ? limit : 20;
-	const match = buildMemoryFtsMatch(query);
+	// keyword-OR (NOT the token-AND of searchMemoryRowsRanked): this relevance-only read backs
+	// the per-turn recall hook, where a natural-language prompt must match on ANY keyword.
+	const match = buildMemoryFtsMatchOr(query);
 	if (!match) {
 		return [];
 	}
-	return allParams(
-		runtime,
-		db,
-		`SELECT m.*, bm25(kernel_memories_fts) AS __score FROM kernel_memories m
+	const projectId = options.projectId;
+	if (typeof projectId !== 'string' || !projectId) return [];
+	const cutoff = suggestedFreshnessCutoff(options.now);
+	const excludeKeys = Array.isArray(options.excludeKeys)
+		? [...new Set(options.excludeKeys.filter(key => typeof key === 'string'))].slice(0, 256)
+		: [];
+	const seenSql = excludeKeys.length > 0
+		? `AND m.key NOT IN (${excludeKeys.map(() => '?').join(', ')})`
+		: '';
+	const confirmed = confirmedMemorySql('m');
+	const supersederConfirmed = confirmedMemorySql('s');
+	// Expand eligible supersession edges once. A correlated json_each scan repeated the
+	// entire memory table for every FTS candidate and dominated the 1,000-row prompt path.
+	// Recall temporarily waits less than the connection default so a real lock cannot outlive
+	// the prompt hook; the finally block restores the caller's normal connection behavior.
+	const previousBusyTimeout = Number(queryOne(runtime, db, 'PRAGMA busy_timeout;').timeout) || 0;
+	const requestedBusyTimeout = Number(options.busyTimeoutMs);
+	const busyTimeout = Number.isFinite(requestedBusyTimeout) && requestedBusyTimeout >= 0
+		? Math.floor(requestedBusyTimeout)
+		: Math.min(previousBusyTimeout, 2_500);
+	if (busyTimeout !== previousBusyTimeout) {
+		execSql(runtime, db, `PRAGMA busy_timeout=${busyTimeout};`);
+	}
+	try {
+		return allParams(
+			runtime,
+			db,
+			`WITH eligible_superseders AS MATERIALIZED (
+				SELECT superseded.value AS memory_key,
+					CASE WHEN ${supersederConfirmed} THEN 1 ELSE 0 END AS is_confirmed
+				FROM kernel_memories s,
+					json_each(COALESCE(s.supersedes_json, '[]')) superseded
+				WHERE ${projectMemoryScopeSql('s')}
+				AND (${supersederConfirmed} OR s.updated_at >= ?)
+			)
+			SELECT m.*, bm25(kernel_memories_fts) AS __score FROM kernel_memories m
 			JOIN kernel_memories_fts ON kernel_memories_fts.rowid = m.rowid
 			WHERE kernel_memories_fts MATCH ?
-			ORDER BY bm25(kernel_memories_fts)
+			AND ${projectMemoryScopeSql('m')}
+			AND (${confirmed} OR m.updated_at >= ?)
+			${seenSql}
+			AND NOT EXISTS (
+				SELECT 1
+				FROM eligible_superseders superseder
+				WHERE superseder.memory_key = m.key
+				AND (superseder.is_confirmed = 1 OR NOT ${confirmed})
+			)
+			ORDER BY bm25(kernel_memories_fts),
+				CASE WHEN ${confirmed} THEN 0 ELSE 1 END,
+				m.source_agent ASC, m.updated_at DESC, m.key ASC
 			LIMIT ?`,
-		[match, capped],
-	).map(row => ({ ...memoryRowToEntry(row), score: row.__score }));
+			[projectId, cutoff, match, projectId, cutoff, ...excludeKeys, capped],
+		).map(row => normalizeRecallHit(
+			{ ...memoryRowToEntry(row), score: row.__score },
+			projectId,
+		));
+	} finally {
+		if (busyTimeout !== previousBusyTimeout) {
+			execSql(runtime, db, `PRAGMA busy_timeout=${previousBusyTimeout};`);
+		}
+	}
 }
 
 function closeDatabase(db) {
@@ -2109,12 +2218,17 @@ function createDriver(runtime, configuredDatabasePath) {
 	// synchronous project-memory facade writes WITHOUT first running migrations. Lazily
 	// ensure the table (idempotent CREATE IF NOT EXISTS, rendered from the same migration)
 	// plus a busy_timeout for the second connection the issue backend may hold open.
-	function ensureMemorySchema(database) {
+	function ensureMemorySchema(database, busyTimeoutMs) {
 		if (memorySchemaEnsured) return;
-		execSql(runtime, database, 'PRAGMA busy_timeout=5000;');
-		for (const statement of buildMemoryProjectionMigration().apply) {
-			execSql(runtime, database, statement);
-		}
+		const requestedBusyTimeout = Number(busyTimeoutMs);
+		const busyTimeout = Number.isFinite(requestedBusyTimeout) && requestedBusyTimeout >= 0
+			? Math.floor(requestedBusyTimeout)
+			: 5_000;
+		execSql(runtime, database, `PRAGMA busy_timeout=${busyTimeout};`);
+		try {
+			for (const statement of buildMemoryProjectionMigration().apply) {
+				execSql(runtime, database, statement);
+			}
 		// FTS5 recall index (migration 008): create the virtual table + sync triggers
 		// idempotently so a synchronous memory write stays indexed without a prior
 		// broker.initialize(). When the index is NEWLY created, rebuild once to backfill any
@@ -2125,20 +2239,25 @@ function createDriver(runtime, configuredDatabasePath) {
 		// Staleness is detected by TABLE EXISTENCE (sqlite_master), never by count(*): on an
 		// external-content FTS5 table `count(*)` returns the CONTENT row count, not the
 		// indexed-doc count, so it can never reveal an un-backfilled index.
-		const ftsDdl = memoryFtsDdl();
-		const ftsExisted = Number(queryOne(
-			runtime,
-			database,
-			"SELECT count(*) AS count FROM sqlite_master WHERE type = 'table' AND name = 'kernel_memories_fts'",
-		).count) > 0;
-		execSql(runtime, database, ftsDdl.create);
-		for (const trigger of ftsDdl.triggers) {
-			execSql(runtime, database, trigger);
-		}
-		if (!ftsExisted) {
-			execSql(runtime, database, ftsDdl.rebuild);
+			const ftsDdl = memoryFtsDdl();
+			const ftsExisted = Number(queryOne(
+				runtime,
+				database,
+				"SELECT count(*) AS count FROM sqlite_master WHERE type = 'table' AND name = 'kernel_memories_fts'",
+			).count) > 0;
+			execSql(runtime, database, ftsDdl.create);
+			for (const trigger of ftsDdl.triggers) {
+				execSql(runtime, database, trigger);
+			}
+			if (!ftsExisted) {
+				execSql(runtime, database, ftsDdl.rebuild);
+			}
+			memorySchemaEnsured = true;
+		} finally {
+			if (busyTimeout !== 5_000) {
+				execSql(runtime, database, 'PRAGMA busy_timeout=5000;');
+			}
 		}
-		memorySchemaEnsured = true;
 	}
 
 	function resolveDatabasePath(config) {
@@ -2335,6 +2454,11 @@ function createDriver(runtime, configuredDatabasePath) {
 		async listKernelEvents(entityType, entityId, _context = {}, config = {}) {
 			return listKernelEventRows(runtime, getDatabase(config), entityType, entityId);
 		},
+		// Additive bulk read for `forge insights` (Slice C2). Read-only; NOT part of the
+		// GUARDED_DRIVER_METHODS write-path contract, so existing driver stubs stay valid.
+		async listRecentKernelEvents({ since = null, limit = null } = {}, _context = {}, config = {}) {
+			return listRecentKernelEventRows(runtime, getDatabase(config), since, limit);
+		},
 		async loadKernelEventByIdempotencyKey(idempotencyKey, _context = {}, config = {}) {
 			return loadKernelEventByIdempotencyKeyRow(runtime, getDatabase(config), idempotencyKey);
 		},
@@ -2460,8 +2584,8 @@ function createDriver(runtime, configuredDatabasePath) {
 		// fallback). Used by the per-turn memory-recall hook.
 		searchMemoriesRankedScored(query, limit, config = {}) {
 			const database = getDatabase(config);
-			ensureMemorySchema(database);
-			return searchMemoryRowsRankedScored(runtime, database, query, limit);
+			ensureMemorySchema(database, config.busyTimeoutMs);
+			return searchMemoryRowsRankedScored(runtime, database, query, limit, config);
 		},
 		// The newest `limit` entries (default recall with no query). `options.agents` scopes
 		// the read to a source_agent allow-list (e.g. human `remember` notes only).

package/lib/lefthook-wiring.js

@@ -55,6 +55,20 @@ pre-push:
       run: npm test --if-present
 `;
 
+// The same config MINUS the TDD pre-commit job, written when the project already has its own
+// pre-commit TDD/coupling gate (kernel 5b425a85 / 2699b234). Stacking a second gate on the same
+// commit is the reported bug, so Forge defers on pre-commit but still wires pre-push.
+const FORGE_USER_LEFTHOOK_YML_NO_TDD = `# Forge git hooks — installed by \`forge setup\` / \`forge init\`.
+# Your project already has its own pre-commit TDD/coupling gate, so Forge did NOT add a second
+# one here. To use Forge's gate instead, remove yours and run: forge gate enable rail.tdd_intent
+# Edit freely to add your own checks — Forge only replaces a fully-commented stub.
+
+pre-push:
+  commands:
+    tests:
+      run: npm test --if-present
+`;
+
 /**
  * A fresh `lefthook install` (run by lefthook's own npm postinstall) drops a stock
  * EXAMPLE lefthook.yml with every hook commented out. That disposable stub used to
@@ -221,10 +235,13 @@ npm test --if-present || exit 1
  * `skipped`) rather than destroyed.
  *
  * @param {string} projectRoot - Absolute path to the project root.
+ * @param {{ skipHooks?: string[] }} [options] - Hook names to leave alone entirely. `forge setup`
+ *   passes `['pre-commit']` when the project already has its own pre-commit TDD/coupling gate,
+ *   so Forge defers instead of stacking a second one (kernel 5b425a85 / 2699b234).
  * @returns {{ installed: boolean, method?: string, hooksDir?: string,
  *   written?: string[], skipped?: string[], reason?: string }}
  */
-function installNativeGitHooks(projectRoot) {
+function installNativeGitHooks(projectRoot, options = {}) {
   const hooksDir = resolveGitHooksDir(projectRoot);
   if (!hooksDir) {
     return { installed: false, reason: 'not-a-git-repo' };
@@ -235,9 +252,11 @@ function installNativeGitHooks(projectRoot) {
     return { installed: false, reason: `hooks-dir-unwritable: ${error.message}` };
   }
 
+  const skipHooks = new Set(Array.isArray(options.skipHooks) ? options.skipHooks : []);
   const written = [];
   const skipped = [];
   for (const [name, body] of Object.entries(NATIVE_HOOK_BODIES)) {
+    if (skipHooks.has(name)) continue;
     const outcome = writeNativeHook(path.join(hooksDir, name), body);
     (outcome === 'written' ? written : skipped).push(name);
   }
@@ -406,6 +425,7 @@ function verifyHooksActive(projectRoot) {
 module.exports = {
   FORGE_NATIVE_HOOK_SENTINEL,
   FORGE_USER_LEFTHOOK_YML,
+  FORGE_USER_LEFTHOOK_YML_NO_TDD,
   forgeShouldWriteLefthookConfig,
   resolveGitHooksDir,
   installNativeGitHooks,