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

package/lib/issue-backend.js

@@ -3,10 +3,34 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const VALID_BACKENDS = new Set(['kernel', 'beads']);
+const VALID_BACKENDS = new Set(['kernel']);
 const DEFAULT_BACKEND = 'kernel';
 const ENV_VAR = 'FORGE_ISSUE_BACKEND';
 
+// Backends that Forge used to accept and has since retired. Kept as an explicit set
+// (rather than folding them into the generic "unknown backend" path) so a user who
+// still carries `issueBackend: beads` in config — or `FORGE_ISSUE_BACKEND=beads` in a
+// shell profile — gets the ONE actionable instruction instead of a bare valid-values
+// list: import the Beads store into the kernel.
+const REMOVED_BACKENDS = new Set(['beads']);
+
+// The single migrate pointer shared by every removed-backend surface (the resolver's
+// warning and the CLI flag's hard error) so the two can never drift.
+const BEADS_REMOVED_HINT =
+  'the beads backend was removed; run `forge migrate --from beads` to import a Beads store into the kernel';
+
+/**
+ * The migrate-pointer hint for a retired backend value, or null when the value is
+ * not a retired backend (callers then use the generic unknown-backend wording).
+ *
+ * @param {string} value
+ * @returns {string|null}
+ */
+function removedBackendHint(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return REMOVED_BACKENDS.has(normalized) ? BEADS_REMOVED_HINT : null;
+}
+
 /**
  * Read the `issueBackend` key from `<projectRoot>/.forge/config.yaml`, if the
  * file exists and is parseable. Returns `null` when the file is missing, the
@@ -72,14 +96,17 @@ function collectBackendSignal({ deps = {}, env = process.env, projectRoot } = {}
  *   explicit deps.issueBackend > FORGE_ISSUE_BACKEND env > .forge/config.yaml > 'kernel'.
  *
  * An unknown value (from any source) falls back to the default backend and emits
- * a warning via the injected `warn` callback (defaults to console.warn).
+ * a warning via the injected `warn` callback (defaults to console.warn). A RETIRED
+ * value (`beads`) takes the same fallback path but warns with the migrate pointer,
+ * because "unknown backend, valid backends: kernel" would not tell a user carrying
+ * `issueBackend: beads` in config what to actually do about it.
  *
  * @param {object} [options]
  * @param {object} [options.deps]
  * @param {object} [options.env]
  * @param {string} [options.projectRoot]
  * @param {function(string): void} [options.warn]
- * @returns {'kernel'|'beads'}
+ * @returns {'kernel'}
  */
 function resolveIssueBackend({
   deps = {},
@@ -98,6 +125,15 @@ function resolveIssueBackend({
     return normalized;
   }
 
+  const removedHint = removedBackendHint(normalized);
+  if (removedHint) {
+    warn(
+      `Issue backend "${value}" from ${source} is no longer available: ${removedHint}. `
+      + `Falling back to "${DEFAULT_BACKEND}".`,
+    );
+    return DEFAULT_BACKEND;
+  }
+
   warn(
     `Unknown issue backend "${value}" from ${source}; `
     + `falling back to "${DEFAULT_BACKEND}". Valid backends: ${[...VALID_BACKENDS].join(', ')}.`,
@@ -139,7 +175,10 @@ module.exports = {
   hasExplicitBackendSignal,
   shouldUseKernelBroker,
   readConfigBackend,
+  removedBackendHint,
   VALID_BACKENDS,
+  REMOVED_BACKENDS,
+  BEADS_REMOVED_HINT,
   DEFAULT_BACKEND,
   ENV_VAR,
 };

package/lib/kernel/backing-issue.js

@@ -171,7 +171,12 @@ function findExistingLink(driver, { worktreePath, branch }) {
     }
     if (typeof driver.listWorktrees === 'function') {
       const rows = driver.listWorktrees() || [];
-      const match = rows.find(row => row && row.branch === branch && row.issue_id);
+      // Match ACTIVE (live) rows only: a superseded/stale registration for a
+      // reused branch name must not be treated as the existing link (be18881c —
+      // the third resolver, kept consistent with resolveActiveIssueId and
+      // currentBranchIssueFromDriver). Tolerate a null state for legacy rows.
+      const match = rows.find(row => row && row.branch === branch && row.issue_id
+        && (row.state === 'active' || row.state == null));
       if (match) return match;
     }
   } catch {
@@ -298,6 +303,7 @@ module.exports = {
   classifyBranch,
   deriveTitle,
   extractEncodedIssueId,
+  findExistingLink,
   matchesIgnoreGlob,
   DEFAULT_PROTECTED_BRANCHES,
   DEFAULT_IGNORE_GLOBS,

package/lib/kernel/broker.js

@@ -1177,6 +1177,34 @@ function createLocalBroker(options = {}) {
 			return driver.importIssues(kernel, options, {}, config);
 		},
 
+		// 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.
+		async listOpenPrs(gitCommonDir, context = {}) {
+			requireDriverMethod(driver, 'listOpenPrs');
+			return driver.listOpenPrs(gitCommonDir, context, getConfig());
+		},
+
+		// PR reconcile-ledger WRITE path (autonomous-shepherd design §5a). Mirror of the
+		// listOpenPrs wrapper: guard the driver method, delegate with getConfig(). pr rows
+		// are derived reconcile state (a direct idempotent upsert), not the guarded-event
+		// issue path. upsertPr = register/refresh; updatePrVerdict = the one verdict authority
+		// with freshest-head precedence enforced at the write; retirePr = merged/closed.
+		async upsertPr(row, context = {}) {
+			requireDriverMethod(driver, 'upsertPr');
+			return driver.upsertPr(row, context, getConfig());
+		},
+
+		async updatePrVerdict(key, patch = {}, context = {}) {
+			requireDriverMethod(driver, 'updatePrVerdict');
+			return driver.updatePrVerdict(key, patch, context, getConfig());
+		},
+
+		async retirePr(key, patch = {}, context = {}) {
+			requireDriverMethod(driver, 'retirePr');
+			return driver.retirePr(key, patch, context, getConfig());
+		},
+
 		// --- Projection-outbox read/update surface (D16) -----------------------
 		// Additive read/update methods for projection consumers. These never touch
 		// the append/CAS path above (runGuardedEvent / enqueueKernelProjection);

package/lib/kernel/migrations.js

@@ -57,8 +57,8 @@ function renderDropTable(table) {
 // stays the full current schema; the named tables are filtered out of 001 so they are
 // created exactly once by their dedicated migration (both on a fresh DB and, via the
 // ledger, on an existing DB). KEEP IN SYNC with every new table-creating migration.
-//   memories → 005
-const MIGRATION_ADDED_TABLES = ['memories'];
+//   memories → 005 ; pr → 009
+const MIGRATION_ADDED_TABLES = ['memories', 'pr'];
 
 function getInitialKernelSchema() {
 	const schema = getKernelSchema();
@@ -278,6 +278,32 @@ function buildMemoryFtsMigration() {
 	};
 }
 
+// 009: the PR reconcile ledger + verdict store (kernel_pr). Rendered from the schema.js
+// table definition so the DDL never drifts from the registry — mirroring migration 005.
+// A NEW authority table (NOT columns on kernel_worktrees) because a PR can outlive its
+// worktree or have none at all (autonomous-shepherd design §3.1). Excluded from the 001
+// initial schema (MIGRATION_ADDED_TABLES), so a fresh DB creates it exactly once here and
+// an existing DB picks it up through the broker's per-migration ledger. CREATE … IF NOT
+// EXISTS keeps a re-run idempotent; it is a create-table with no data backfill, so no
+// BEGIN IMMEDIATE is needed (broker.js apply-loop caveat does not bite).
+function buildPrLinkageMigration() {
+	const pr = getKernelSchema().tables.find(table => table.name === 'pr');
+	if (!pr) {
+		throw new Error('Kernel schema is missing the pr authority table');
+	}
+	return {
+		id: '009_kernel_pr_linkage',
+		apply: [
+			renderCreateTable(pr),
+			...pr.indexes.map(prIndex => renderCreateIndex(pr, prIndex)),
+		],
+		rollback: [
+			...[...pr.indexes].reverse().map(prIndex => renderDropIndex(prIndex)),
+			renderDropTable(pr),
+		],
+	};
+}
+
 function validateKernelMigrations(migrations) {
 	const ids = new Set();
 	for (const migration of migrations) {
@@ -308,6 +334,7 @@ function buildKernelMigrationPlan(migrations = [
 	buildIssueFidelityColumnsMigration(),
 	buildWorktreeLinkageColumnsMigration(),
 	buildMemoryFtsMigration(),
+	buildPrLinkageMigration(),
 ]) {
 	validateKernelMigrations(migrations);
 
@@ -326,6 +353,7 @@ module.exports = {
 	buildKernelMigrationPlan,
 	buildMemoryFtsMigration,
 	buildMemoryProjectionMigration,
+	buildPrLinkageMigration,
 	buildSchemaMigration,
 	buildWorktreeLinkageColumnsMigration,
 	memoryFtsDdl,

package/lib/kernel/owned-kernel.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * @module kernel/owned-kernel
+ *
+ * Shared kernel-lifecycle helper for the pure-append event modules
+ * (grounding/context-events, gate-events). Both resolve a kernel driver the same
+ * way and carry the same close-what-you-built invariant, so it lives here once
+ * instead of being copied per module.
+ *
+ * The invariant: an INJECTED (shared) kernel is caller-owned and must NEVER be
+ * closed here — closing it would break the next operation that reuses it. A
+ * kernel this module BUILDS for a single short-lived read/append it MUST close —
+ * an unclosed SQLite handle leaks and, on Windows, locks the DB directory
+ * (`EBUSY` on `rmSync`, kernel issue e62e4bde).
+ */
+
+const { buildMigratedKernelIssueDeps } = require('./cli-broker-factory');
+
+/**
+ * Resolve the kernel driver + config. An injected (shared) kernel is returned
+ * untouched with `ownsKernel:false` — the caller owns its lifecycle. Otherwise a
+ * fresh one is built (via `deps.kernelBuilder`, a test seam over
+ * `buildMigratedKernelIssueDeps`, or the real builder) and tagged
+ * `ownsKernel:true` so {@link closeIfOwned} closes it.
+ */
+async function resolveOwnedKernel(projectRoot, deps = {}) {
+  if (deps.kernelBroker && deps.kernelDriver) {
+    return { broker: deps.kernelBroker, driver: deps.kernelDriver, config: deps.kernelBroker.config, ownsKernel: false };
+  }
+  const build = deps.kernelBuilder || buildMigratedKernelIssueDeps;
+  const built = await build({ projectRoot });
+  return { broker: built.kernelBroker, driver: built.kernelDriver, config: built.kernelBroker.config, ownsKernel: true };
+}
+
+/** Close a kernel driver only when this module built it (never an injected one). */
+function closeIfOwned(kernel) {
+  if (kernel && kernel.ownsKernel && kernel.driver && typeof kernel.driver.close === 'function') {
+    try { kernel.driver.close(); } catch { /* best-effort: closing is cleanup, never fatal */ }
+  }
+}
+
+module.exports = { resolveOwnedKernel, closeIfOwned };

package/lib/kernel/schema.js

@@ -278,6 +278,41 @@ const TABLE_LIST = deepFreeze([
 	], [
 		index('idx_kernel_memories_source_agent', ['source_agent']),
 	]),
+	// The PR reconcile ledger + verdict store (autonomous-shepherd design §3): a
+	// first-class `pr` authority row links a pull request to its issue, worktree and
+	// journal, and records the winning verdict with its freshness discriminators
+	// (head_sha, verdict_source, verdict_at). A PR is the unit of ownership and can
+	// outlive its worktree (or have none — a hand-opened/other-harness PR), so it is a
+	// separate table, NOT columns on kernel_worktrees. git_common_dir keys every open PR
+	// to its repo so all worktrees share one reconcile view. issue_id/worktree_id are
+	// soft nullable links. Created by migration 009 (excluded from the 001 initial schema
+	// via MIGRATION_ADDED_TABLES), so a fresh DB creates it exactly once and an existing
+	// DB picks it up through the broker's per-migration ledger.
+	table('pr', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('git_common_dir', 'TEXT', { notNull: true }),
+		field('repo', 'TEXT', { notNull: true }),
+		field('number', 'INTEGER', { notNull: true }),
+		field('issue_id', 'TEXT'),
+		field('worktree_id', 'TEXT'),
+		field('branch', 'TEXT'),
+		field('head_sha', 'TEXT'),
+		field('verdict', 'TEXT'),
+		field('verdict_source', 'TEXT'),
+		field('verdict_at', 'TEXT'),
+		field('journal_ptr', 'TEXT'),
+		field('state', 'TEXT', { notNull: true, default: "'open'" }),
+		field('registered_at', 'TEXT', { notNull: true }),
+		field('retired_at', 'TEXT'),
+	], [
+		// Covering index for the reconciler's hot read `listOpenPrs` (WHERE
+		// git_common_dir=? AND state='open' ORDER BY repo, number): the trailing
+		// repo/number let SQLite satisfy both the state filter AND the ordering from
+		// this one index, instead of scanning every PR for the common-dir once the
+		// ledger retains merged/closed history. (Codex review, PR #424.)
+		index('idx_pr_common_dir_state_repo_number', ['git_common_dir', 'state', 'repo', 'number']),
+		index('idx_pr_common_dir_repo_number', ['git_common_dir', 'repo', 'number'], { unique: true }),
+	]),
 ]);
 
 const KERNEL_TABLES = deepFreeze(Object.fromEntries(TABLE_LIST.map(candidate => [candidate.name, candidate])));

package/lib/kernel/sqlite-driver.js

@@ -1113,8 +1113,41 @@ function loadWorktreeRowByPath(runtime, db, worktreePath) {
 	return rows[0] || null;
 }
 
+// The idempotent upsert key. `forge plan` registers MULTIPLE branches from ONE
+// checkout (same absolute path), so keying by path ALONE made a second plan-first
+// feature UPDATE-in-place over the first branch's row and dead-end its ship (R1).
+// Key by (path, branch) so each branch keeps its own row; fall back to path-only
+// when no branch is supplied (worktree flows use distinct paths, so behavior there
+// is unchanged).
+function loadWorktreeRowByPathAndBranch(runtime, db, worktreePath, branch) {
+	if (!worktreePath) return null;
+	if (!branch) return loadWorktreeRowByPath(runtime, db, worktreePath);
+	const rows = safeAll(
+		runtime,
+		db,
+		'SELECT * FROM kernel_worktrees WHERE path = ? AND branch = ? ORDER BY registered_at DESC LIMIT 1',
+		[worktreePath, branch],
+	);
+	return rows[0] || null;
+}
+
+// A git branch is checked out in exactly ONE worktree, so a NEW active registration
+// for a branch supersedes any prior ACTIVE row carrying that same branch under a
+// different id (be18881c): a reused/deleted-and-recreated branch must not keep a
+// stale binding to the OLD issue. Marking those rows state='superseded' lets the
+// active-only branch resolver skip them regardless of their timestamp.
+function supersedePriorBranchRegistrations(runtime, db, branch, keepId) {
+	if (!branch) return;
+	runParams(
+		runtime,
+		db,
+		"UPDATE kernel_worktrees SET state = 'superseded' WHERE branch = ? AND state = 'active' AND id != ?",
+		[branch, keepId || ''],
+	);
+}
+
 function upsertWorktreeRow(runtime, db, input) {
-	const existing = loadWorktreeRowByPath(runtime, db, input.path);
+	const existing = loadWorktreeRowByPathAndBranch(runtime, db, input.path, input.branch);
 	const row = {
 		id: input.id || existing?.id || randomUUID(),
 		git_common_dir: input.git_common_dir,
@@ -1142,6 +1175,9 @@ function upsertWorktreeRow(runtime, db, input) {
 			KERNEL_WORKTREE_COLUMNS.map(column => row[column]),
 		);
 	}
+	if (row.state === 'active') {
+		supersedePriorBranchRegistrations(runtime, db, row.branch, row.id);
+	}
 	return row;
 }
 
@@ -2034,6 +2070,30 @@ function searchMemoryRowsRanked(runtime, db, query, limit) {
 	).map(memoryRowToEntry);
 }
 
+// Relevance-ONLY BM25 recall that exposes the raw bm25 score on each entry. The
+// per-turn auto-recall hook needs the score to apply a relevance FLOOR (inject nothing
+// when nothing clears the bar) — ordinal rank can't express "nothing was relevant".
+// 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) {
+	const capped = Number.isInteger(limit) && limit > 0 ? limit : 20;
+	const match = buildMemoryFtsMatch(query);
+	if (!match) {
+		return [];
+	}
+	return allParams(
+		runtime,
+		db,
+		`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)
+			LIMIT ?`,
+		[match, capped],
+	).map(row => ({ ...memoryRowToEntry(row), score: row.__score }));
+}
+
 function closeDatabase(db) {
 	if (db && typeof db.close === 'function') {
 		db.close();
@@ -2145,6 +2205,124 @@ function createDriver(runtime, configuredDatabasePath) {
 				[`${escaped}%`, limit],
 			);
 		},
+		// Open PRs under shepherd for one repo (autonomous-shepherd design §3.4): the
+		// reconciler's "open PRs in this repo" read, keyed by git_common_dir so every
+		// worktree shares one view. Parameterized (git_common_dir is a filesystem path —
+		// never interpolate it), covered by idx_pr_common_dir_state_repo_number. Ordered so
+		// the result is deterministic. `context` is part of the broker contract but unused
+		// by this direct SELECT (prefixed `_` for eslint no-unused-vars).
+		async listOpenPrs(gitCommonDir, _context = {}, config = {}) {
+			return allParams(
+				runtime, getDatabase(config),
+				"SELECT * FROM kernel_pr WHERE git_common_dir = ? AND state = 'open' ORDER BY repo ASC, number ASC",
+				[gitCommonDir],
+			);
+		},
+		// --- kernel_pr WRITE path (autonomous-shepherd design §5a). pr rows are DERIVED
+		// reconcile state (reconstructable from GitHub), not audit-critical issue authority,
+		// so they take a DIRECT idempotent upsert — NOT the event-sourced guarded path
+		// (applyAcceptedIssueMutation). All target the physical `kernel_pr` table (matching
+		// the listOpenPrs read) and are parameterized (git_common_dir/branch/head_sha are
+		// externally-influenced values — never interpolate). `context` is part of the broker
+		// contract but unused by these direct writes (prefixed `_` for eslint no-unused-vars).
+		//
+		// Register/refresh a PR row keyed by (git_common_dir, repo, number). Idempotent via
+		// ON CONFLICT on the unique idx_pr_common_dir_repo_number: a re-upsert updates the
+		// mutable columns and coalesces soft links (a later null never clobbers an existing
+		// issue_id/worktree_id). registered_at is set on INSERT only; state defaults 'open'.
+		async upsertPr(row, _context = {}, config = {}) {
+			const id = row.id || randomUUID();
+			const registeredAt = row.registered_at || new Date().toISOString();
+			const state = row.state || 'open';
+			runParams(
+				runtime, getDatabase(config),
+				`INSERT INTO kernel_pr
+					(id, git_common_dir, repo, number, issue_id, worktree_id, branch, head_sha, journal_ptr, state, registered_at)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+				 ON CONFLICT(git_common_dir, repo, number) DO UPDATE SET
+					head_sha = excluded.head_sha,
+					branch = excluded.branch,
+					issue_id = coalesce(excluded.issue_id, kernel_pr.issue_id),
+					worktree_id = coalesce(excluded.worktree_id, kernel_pr.worktree_id),
+					-- journal_ptr is a soft link: coalesce it (like issue_id/worktree_id) so a
+					-- head-only refresh that omits journalPtr never severs the ledger↔journal
+					-- link with NULL. (Codex review, PR #426.)
+					journal_ptr = coalesce(excluded.journal_ptr, kernel_pr.journal_ptr),
+					-- REOPEN semantics: upsertPr is only ever called for PRs GitHub reports as
+					-- OPEN, so re-registering a previously retired row (a reopened PR) must flip
+					-- it back to open and clear retired_at — else listOpenPrs (state='open') would
+					-- keep the reopened PR invisible forever. (Codex review, PR #426.)
+					state = 'open',
+					retired_at = NULL,
+					-- A new commit INVALIDATES the prior verdict: when the head advances to a
+					-- different non-null sha, clear verdict/source/at so a verdict computed
+					-- against the OLD head is never presented as fresh for the new head (and the
+					-- freshest-head guard in updatePrVerdict keeps intact evidence). IS NOT is the
+					-- null-safe distinctness test; a headless refresh (excluded.head_sha NULL)
+					-- never clears. (Codex review, PR #426.)
+					verdict = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict END,
+					verdict_source = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict_source END,
+					verdict_at = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict_at END`,
+				[
+					id,
+					row.git_common_dir,
+					row.repo,
+					row.number,
+					row.issue_id ?? null,
+					row.worktree_id ?? null,
+					row.branch ?? null,
+					row.head_sha ?? null,
+					row.journal_ptr ?? null,
+					state,
+					registeredAt,
+				],
+			);
+			return { ok: true, id };
+		},
+		// The ONE verdict authority WRITE (design §1.2 rule 2) — FRESHEST-HEAD-SHA
+		// PRECEDENCE enforced in the WHERE so a verdict computed against a SUPERSEDED head is
+		// DISCARDED, not written (kills stale 9d35c14b at the write). A non-local (Actions
+		// backstop) write lands only when its head_sha matches the row's current head (or the
+		// row has none yet); a `local` verdict is computed live against the current head and
+		// is always authoritative, so it bypasses the head match.
+		async updatePrVerdict(key, patch = {}, _context = {}, config = {}) {
+			const headSha = patch.head_sha ?? null;
+			const source = patch.verdict_source ?? null;
+			runParams(
+				runtime, getDatabase(config),
+				`UPDATE kernel_pr SET verdict = ?, verdict_source = ?, verdict_at = ?, head_sha = ?
+				 WHERE git_common_dir = ? AND repo = ? AND number = ?
+					AND (head_sha IS NULL OR head_sha = ? OR ? = 'local')`,
+				[
+					patch.verdict ?? null,
+					source,
+					patch.verdict_at ?? null,
+					headSha,
+					key.git_common_dir,
+					key.repo,
+					key.number,
+					headSha,
+					source,
+				],
+			);
+			return { ok: true };
+		},
+		// Retire a PR row (merged/closed): flip state + stamp retired_at so it drops out of
+		// the open-PR read while the reconcile history is retained.
+		async retirePr(key, patch = {}, _context = {}, config = {}) {
+			runParams(
+				runtime, getDatabase(config),
+				'UPDATE kernel_pr SET state = ?, retired_at = ? WHERE git_common_dir = ? AND repo = ? AND number = ?',
+				[
+					patch.state ?? 'closed',
+					patch.retired_at ?? new Date().toISOString(),
+					key.git_common_dir,
+					key.repo,
+					key.number,
+				],
+			);
+			return { ok: true };
+		},
 		// --- Event-store primitives (Wave 2) — composed by broker.runGuardedEvent.
 		// `context` is part of the broker contract but unused by these direct SQL
 		// reads/writes (prefixed `_` for eslint no-unused-vars).
@@ -2277,6 +2455,14 @@ function createDriver(runtime, configuredDatabasePath) {
 			ensureMemorySchema(database);
 			return searchMemoryRowsRanked(runtime, database, query, limit);
 		},
+		// Relevance-only BM25 recall that also returns the raw bm25 `score` per entry, so a
+		// caller can apply a relevance floor. A no-match/empty query returns [] (no recency
+		// 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);
+		},
 		// 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).
 		recentMemories(limit, options = {}, config = {}) {

package/lib/memory-recall.js

@@ -0,0 +1,151 @@
+'use strict';
+
+/**
+ * @module memory-recall
+ *
+ * Pure selection core for the per-turn memory-recall hook (the query-relevant tier-2
+ * that complements the recency digest pushed at SessionStart). Kept free of stdin/fs so
+ * it is fully testable; lib/commands/hooks.js does the I/O wiring around it.
+ *
+ * Design constraints (verified against the Claude Code hooks contract + external memory
+ * research, kernel issue 781f6f65):
+ *   - UserPromptSubmit additionalContext APPENDS to history every prompt, so a per-turn
+ *     injector must stay tiny: a hard token budget, a relevance floor, and cross-turn
+ *     dedupe. Below the bar -> inject NOTHING (silence is safe; a wrong memory at
+ *     authority every turn is not).
+ *   - Anaphora guard: a trivial query ("continue", "fix it") carries no retrieval signal,
+ *     so ranking on it is worse than silence. Require a minimum of distinct content tokens.
+ *   - Scope is a FILTER; relevance is the RANKER (bm25). Never sort by recency here — that
+ *     is the recency digest's job, not tier-2's.
+ */
+
+// A query needs at least this many distinct content tokens to be worth ranking on.
+// Below it we treat the prompt as anaphora and inject nothing.
+const MIN_QUERY_TOKENS = 2;
+
+// Default token budget for the whole tier-2 injection. Deliberately small: it rides on
+// EVERY prompt, and it must never starve the always-on SessionStart digest.
+const DEFAULT_TOKEN_BUDGET = 400;
+
+// Default relevance floor for the live hook path so it never runs floor-less. bm25 is
+// more-negative-is-better, so 0 keeps every token-AND FTS match: the ACTIVE relevance gate
+// today is the token-AND match plus the anaphora guard, and the numeric floor is a knob to
+// be tightened (made negative) once shadow-logging measurement (781f6f65 step 0) shows where
+// the corpus's relevant/irrelevant boundary sits. Named + wired so the default is explicit,
+// not an accidental `undefined`.
+const DEFAULT_SCORE_FLOOR = 0;
+
+// Short/function words that carry no retrieval signal. Not exhaustive — just enough to
+// stop pure anaphora ("do that now", "same for it") from clearing the guard.
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'but', 'for', 'to', 'of', 'in', 'on', 'at', 'by', 'is',
+  'it', 'this', 'that', 'these', 'those', 'do', 'did', 'now', 'then', 'same', 'again',
+  'continue', 'go', 'ok', 'okay', 'yes', 'no', 'fix', 'please', 'thanks', 'with', 'as',
+  'we', 'i', 'you', 'he', 'she', 'they', 'them', 'his', 'her', 'my', 'our', 'your',
+]);
+
+// Rough token estimate: ~4 chars/token, matching lib/memory-digest.js's convention so
+// the two tiers budget on the same scale.
+function estimateTokens(text) {
+  return Math.ceil(String(text || '').length / 4);
+}
+
+/**
+ * Parse the JSON payload Claude Code delivers on a UserPromptSubmit hook's stdin. Never
+ * throws — any malformed input yields an empty prompt so the hook fails open.
+ *
+ * @param {string} raw
+ * @returns {{ prompt: string, sessionId: (string|null) }}
+ */
+function parseHookInput(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { prompt: '', sessionId: null };
+    }
+    const prompt = typeof parsed.prompt === 'string' ? parsed.prompt : '';
+    const sessionId = typeof parsed.session_id === 'string' ? parsed.session_id : null;
+    return { prompt, sessionId };
+  } catch {
+    return { prompt: '', sessionId: null };
+  }
+}
+
+/**
+ * Distinct content tokens in a query — lowercased, length >= 3, minus stopwords. The
+ * anaphora guard counts these; the FTS layer does its own tokenization for the actual match.
+ *
+ * @param {string} query
+ * @returns {string[]}
+ */
+function meaningfulTokens(query) {
+  const seen = new Set();
+  // Unicode-aware split, matching the FTS tokenizer (/[\p{L}\p{N}]+/gu in the kernel driver)
+  // so non-Latin prompts (Cyrillic/CJK/accented) aren't silently stripped — otherwise the
+  // anaphora guard would disable recall for every non-Latin-script user.
+  for (const rawToken of String(query || '').toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    if (!rawToken) continue;
+    if (STOPWORDS.has(rawToken)) continue;
+    // The length>=3 filter suppresses ASCII noise ("it", "do"), but CJK words are 1-2 chars
+    // and any non-ASCII token is inherently content — keep those regardless of length.
+    if (rawToken.length < 3 && /^[a-z0-9]+$/.test(rawToken)) continue;
+    seen.add(rawToken);
+  }
+  return [...seen];
+}
+
+/**
+ * Choose which memories to inject this turn. PURE.
+ *
+ * @param {object} args
+ * @param {string} args.query — the submitted prompt
+ * @param {Array<{key:string, value:string, score:number}>} args.hits — bm25-ordered
+ *   (best/lowest score first), already relevance-only (token-AND matched)
+ * @param {number} [args.scoreFloor] — keep only hits with score <= floor (more negative =
+ *   stronger). Omit/null to rely on the FTS match alone. The VALUE is corpus-dependent and
+ *   should be tuned from shadow-logging measurement, not guessed — this is the knob.
+ * @param {number} [args.tokenBudget]
+ * @param {string[]} [args.excludeKeys] — keys injected on recent turns (cross-turn dedupe)
+ * @returns {{ lines: string[], injectedKeys: string[] }}
+ */
+function selectInjection({ query, hits, scoreFloor = null, tokenBudget = DEFAULT_TOKEN_BUDGET, excludeKeys = [] }) {
+  // Anaphora guard: a query with too little signal ranks garbage — stay silent.
+  if (meaningfulTokens(query).length < MIN_QUERY_TOKENS) {
+    return { lines: [], injectedKeys: [] };
+  }
+
+  const exclude = new Set(excludeKeys || []);
+  const lines = [];
+  const injectedKeys = [];
+  let spent = 0;
+
+  for (const hit of hits || []) {
+    if (!hit || typeof hit.key !== 'string') continue;
+    if (exclude.has(hit.key)) continue;
+    // Relevance floor: below the bar contributes nothing. bm25 is more-negative-is-better.
+    if (typeof scoreFloor === 'number' && !(typeof hit.score === 'number' && hit.score <= scoreFloor)) {
+      continue;
+    }
+    const body = String(hit.value == null ? '' : hit.value);
+    const cost = estimateTokens(body);
+    if (spent + cost > tokenBudget) {
+      // Budget exhausted; stop rather than skip-and-continue so the strongest fit.
+      break;
+    }
+    lines.push(body);
+    injectedKeys.push(hit.key);
+    spent += cost;
+  }
+
+  return { lines, injectedKeys };
+}
+
+module.exports = {
+  MIN_QUERY_TOKENS,
+  DEFAULT_TOKEN_BUDGET,
+  DEFAULT_SCORE_FLOOR,
+  estimateTokens,
+  parseHookInput,
+  meaningfulTokens,
+  selectInjection,
+};