@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/mcp_telemetry_store.ts

@@ -22,10 +22,14 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import type { DatabaseSync } from 'node:sqlite';
-import type * as NodeSqlite from 'node:sqlite';
 
 import { TELEMETRY_FILENAME, TELEMETRY_REL_DIR } from './mcp_server/telemetry.js';
+import { loadSqlite, readUserVersion, stampUserVersion } from './_lib/sqlite_guard.js';
 
+// cache-invalidation: the path carries no version segment (existing CLI
+// intent tests pin this exact string in stdout); invalidation instead runs
+// through `PRAGMA user_version = SCHEMA_VERSION`, stamped on every connect
+// by `_connect()` below (road-to-reachable-code-memory Phase 7).
 export const DEFAULT_DB_REL = 'agents/runtime/mcp-telemetry/calls.sqlite3';
 export const SCHEMA_VERSION = 1;
 
@@ -173,42 +177,18 @@ export function resolve_db(consumer_root?: string | null): string {
     return path.join(root, DEFAULT_DB_REL);
 }
 
-// Python's stdlib sqlite3 emits nothing on stderr; node:sqlite is flagged
-// experimental on node 22 and prints an `ExperimentalWarning: SQLite …` line
-// to stderr on first import (stable / silent on node >= 23). Drop only that
-// specific warning so stderr stays byte-stable across node versions (tests
-// pin the exact bytes). Installed once, narrowly matched.
-let _sqliteWarningSilenced = false;
-function _silenceSqliteExperimentalWarning(): void {
-    if (_sqliteWarningSilenced) return;
-    _sqliteWarningSilenced = true;
-    const orig = process.emitWarning.bind(process);
-    process.emitWarning = ((warning: string | Error, ...rest: unknown[]): void => {
-        const text = typeof warning === 'string' ? warning : (warning?.message ?? '');
-        if (/SQLite is an experimental/i.test(text)) return;
-        (orig as (w: string | Error, ...a: unknown[]) => void)(warning, ...rest);
-    }) as typeof process.emitWarning;
-}
-
-/** Lazy `node:sqlite` import — keeps the module loadable on a runtime without it. */
-async function _loadSqlite(): Promise<typeof NodeSqlite> {
-    _silenceSqliteExperimentalWarning();
-    try {
-        return await import('node:sqlite');
-    } catch (exc) {
-        const message = exc instanceof Error ? exc.message : String(exc);
-        throw new Error(
-            `node:sqlite is unavailable in this runtime (${message}). ` +
-                'mcp_telemetry_store requires Node with the built-in SQLite module.',
-        );
+/** Remove a possibly-corrupt DB file + its WAL/SHM sidecars, best-effort. */
+function _discardDb(db_path: string): void {
+    for (const p of [db_path, `${db_path}-wal`, `${db_path}-shm`]) {
+        try {
+            fs.rmSync(p, { force: true });
+        } catch {
+            /* best-effort */
+        }
     }
 }
 
-/** Open + schema-init the DB. Mirrors the Python `_connect` helper. */
-async function _connect(db_path: string): Promise<DatabaseSync> {
-    fs.mkdirSync(path.dirname(db_path), { recursive: true });
-    const { DatabaseSync } = await _loadSqlite();
-    const conn = new DatabaseSync(db_path);
+function _createSchema(conn: DatabaseSync): void {
     conn.exec('PRAGMA journal_mode=WAL');
     conn.exec(
         `
@@ -226,6 +206,56 @@ async function _connect(db_path: string): Promise<DatabaseSync> {
     conn.exec('CREATE INDEX IF NOT EXISTS idx_calls_tool ON calls(tool_name)');
     conn.exec('CREATE INDEX IF NOT EXISTS idx_calls_ts ON calls(ts)');
     conn.exec('CREATE INDEX IF NOT EXISTS idx_calls_outcome ON calls(outcome)');
+}
+
+/**
+ * Open + schema-init the DB. Mirrors the Python `_connect` helper.
+ *
+ * road-to-reachable-code-memory Phase 7 — fixes the previously never-read
+ * `SCHEMA_VERSION` constant: `PRAGMA user_version` is stamped on create AND
+ * checked on open.
+ *
+ * - Absent file, or `user_version == 0` (a pre-Phase-7 DB written before this
+ *   fix existed — same table shape, just never versioned): create/open
+ *   normally, then stamp the current version. This is the "legacy-path
+ *   sweep on first run".
+ * - `user_version` present but NOT `SCHEMA_VERSION`: a real future schema
+ *   change landed. The DB is a derived, idempotently-rebuildable view of the
+ *   JSONL sink (source of truth) — silently discard it and rebuild fresh
+ *   rather than attempt an in-place migration for a schema this code
+ *   doesn't know.
+ * - File exists but fails to even OPEN (truncated / corrupt): same
+ *   discard-and-rebuild path. Corruption is a non-event, not an error the
+ *   caller has to handle.
+ */
+async function _connect(db_path: string): Promise<DatabaseSync> {
+    fs.mkdirSync(path.dirname(db_path), { recursive: true });
+    const { DatabaseSync } = await loadSqlite('mcp_telemetry_store');
+
+    if (fs.existsSync(db_path)) {
+        let probe: DatabaseSync | null = null;
+        let drift = false;
+        try {
+            probe = new DatabaseSync(db_path);
+            const existing = readUserVersion(probe);
+            drift = existing !== 0 && existing !== SCHEMA_VERSION;
+        } catch {
+            drift = true; // corrupt / unreadable → rebuild
+        } finally {
+            try {
+                probe?.close();
+            } catch {
+                /* best-effort */
+            }
+        }
+        if (drift) {
+            _discardDb(db_path);
+        }
+    }
+
+    const conn = new DatabaseSync(db_path);
+    _createSchema(conn);
+    stampUserVersion(conn, SCHEMA_VERSION);
     return conn;
 }
 

package/src/scripts/measure_rule_budget.ts

@@ -29,6 +29,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots } from './_lib/agent_src.js';
 import * as token_count from './_lib/token_count.js';
+import { KERNEL_RULE_ID_SET } from './_lib/kernel_rules.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/measure_rule_budget.ts → parents[2] is the repo root (mirrors
@@ -47,18 +48,8 @@ const PER_RULE_HARD = 2_500;
 const PER_RULE_TARGET = 2_000;
 const PER_RULE_OVERRIDE_CEILING = 4_000; // Iron-Law-override ADR ceiling.
 
-// Locked kernel set — docs/contracts/kernel-membership.md § 4.
-const KERNEL_RULES: ReadonlySet<string> = new Set([
-    'agent-authority',
-    'ask-when-uncertain',
-    'commit-policy',
-    'direct-answers',
-    'language-and-tone',
-    'no-cheap-questions',
-    'non-destructive-by-default',
-    'scope-control',
-    'verify-before-complete',
-]);
+// Locked kernel set — single-sourced in _lib/kernel_rules.ts (contract: docs/contracts/kernel-membership.md § 4).
+const KERNEL_RULES: ReadonlySet<string> = KERNEL_RULE_ID_SET;
 
 export interface RuleMeasure {
     id: string;

package/src/scripts/memory_learn_hook.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * session_end concern — memory learning sidecar aggregation
+ * (road-to-reachable-code-memory Phase 4).
+ *
+ * Joins the EXISTING `session_end` concern set in hook_manifest.yaml — no
+ * new platform hook wiring. On session end it aggregates
+ * `agents/memory/intake/signals-*.jsonl` through the learning sidecar
+ * (`learning_sidecar.ts`: 30-day decay, ≥2-origin corroboration, dead-end
+ * ledger) into the gitignored `agents/memory/.agent-learning.json` +
+ * // cache-invalidation: path owned by learning_sidecar.ts (schema_version field inside the JSON; name pinned there)
+ * `LESSONS.md`. Local-only, budget-capped, fail-open:
+ *
+ * - Default-OFF. Fires only when `memory.learn_on_session_end: true` in
+ *   `.agent-settings.yml` (council decision 2026-07-27: ships off; the
+ *   default flip is proposed only after the 30-day dogfood shows
+ *   non-trivial signal AND session-end p95 < 2 s).
+ * - Budget-capped: a wall-clock budget (default 2000 ms) aborts the write
+ *   and exits 0 — a slow aggregation must never tax session teardown.
+ * - Fail-open: any error → exit 0, no output. `fail_closed: false`.
+ * - Promotion stays human: this hook only refreshes the sidecar; a
+ *   PROMOTED lesson is surfaced as a one-line visibility marker pointing
+ *   at the existing /memory:propose flow. Nothing auto-writes curated
+ *   `agents/memory/*.yml`.
+ *
+ * Exit codes (dispatcher contract): 0 always (allow).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    buildSidecar,
+    LESSONS_NAME,
+    renderLessonsMd,
+    SIDECAR_NAME,
+} from './learning_sidecar.js';
+
+const SETTINGS_FILE = '.agent-settings.yml';
+/** Wall-clock budget for the whole aggregation (ms). */
+export const BUDGET_MS = 2000;
+
+/**
+ * Minimal `.agent-settings.yml` reader for `memory.learn_on_session_end`
+ * (same hand-rolled mini-parser pattern as the sibling hooks — no YAML
+ * dependency in the hook hot path).
+ */
+export function enabled(root: string): boolean {
+    const p = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        text = fs.readFileSync(p, 'utf8');
+    } catch {
+        return false;
+    }
+    let inMemory = false;
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.replace(/\s+$/u, '');
+        if (/^memory:\s*(#.*)?$/u.test(line)) {
+            inMemory = true;
+            continue;
+        }
+        if (inMemory) {
+            if (/^\S/u.test(line) && line !== '') {
+                inMemory = false; // left the memory: block
+                continue;
+            }
+            const m = /^\s{2,}learn_on_session_end:\s*(\S+)/u.exec(line);
+            if (m) return m[1] === 'true';
+        }
+    }
+    return false;
+}
+
+/** Run the aggregation. Returns the one-line marker to emit, or null. */
+export function runLearn(root: string, nowIso: string, budgetMs: number = BUDGET_MS): string | null {
+    const started = Date.now();
+    const intakeDir = path.join(root, 'agents', 'memory', 'intake');
+    const outDir = path.join(root, 'agents', 'memory');
+    if (!fs.existsSync(intakeDir)) return null;
+    const sidecar = buildSidecar(intakeDir, nowIso);
+    if (Date.now() - started > budgetMs) return null; // over budget — skip the write
+    if (sidecar.lessons.length === 0) return null;
+    fs.writeFileSync(path.join(outDir, SIDECAR_NAME), `${JSON.stringify(sidecar, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(path.join(outDir, LESSONS_NAME), renderLessonsMd(sidecar), 'utf8');
+    const promoted = sidecar.lessons.filter((l) => l.verdict === 'preferred').length;
+    const deadEnds = sidecar.lessons.filter((l) => l.verdict === 'dead_end').length;
+    // Memory-visibility contract shape: one line, ids/counters only, no bodies.
+    return (
+        `🧠 Memory: sidecar refreshed — ${sidecar.lessons.length} lesson(s) ` +
+        `(${promoted} preferred · ${deadEnds} dead-end); promote via /memory:propose`
+    );
+}
+
+export function main(): number {
+    try {
+        const root = process.cwd();
+        if (!enabled(root)) return 0;
+        const marker = runLearn(root, new Date().toISOString());
+        if (marker) process.stdout.write(`${marker}\n`);
+    } catch {
+        // fail-open: session teardown must never break on a learning hook.
+    }
+    return 0;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _isMain = (() => {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    try {
+        return (
+            pathToFileURL(fs.realpathSync(path.resolve(process.argv[1]))).href ===
+            import.meta.url
+        );
+    } catch {
+        return pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+    }
+})();
+if (_isMain) {
+    process.exit(main());
+}
+
+export const _HERE = fileURLToPath(import.meta.url);

package/src/scripts/memory_replay_24.ts

@@ -0,0 +1,312 @@
+#!/usr/bin/env tsx
+/**
+ * Rollback-trigger replay for the memory FTS5 index
+ * (road-to-reachable-code-memory Phase 6 item 2 / ADR-129).
+ *
+ * ADR-129 makes the FTS5 substrate ship WITHOUT a ship-gate lift benchmark
+ * (the separator-recall gap is a correctness defect, not a ranking question
+ * a lift-gate could measure), but it still records a ROLLBACK trigger: this
+ * replay reports recall + tie-distribution for the substring `_score`
+ * fallback vs the persisted FTS5 index, over a FIXED 24-query set drawn from
+ * REAL entry ids in `agents/memory/*.yml` — not the synthetic
+ * needed+distractor bench store `measure_lexical_ranking.ts` uses.
+ *
+ * Two prior baselines are cited (per ADR-129: "the replay must state which
+ * baseline artefact it compares against"), but NEITHER is directly
+ * comparable to this replay's own numbers — both were measured over
+ * `internal/bench/second-brain/retrieval-store/` (a small store engineered
+ * with keyword-overlapping distractors specifically to produce ties), not
+ * over the real, distractor-free `agents/memory` corpus this script runs
+ * against:
+ *
+ *   - `internal/bench/reports/second-brain-retrieval.json`:
+ *     mean_tie_set_size = 4.111... (live retrieval-precision measurement)
+ *   - `internal/bench/reports/lexical-ranking.json`: implied mean tie-set
+ *     3.333 for the SAME `_score` scorer over the SAME store (a different
+ *     measurement pass — the cross-artefact discrepancy is a known, already
+ *     documented finding, see `docs/proof.md`).
+ *
+ * This replay's own baseline-vs-FTS comparison (computed on the same corpus,
+ * same query set, same run) is the load-bearing measurement; the two
+ * externals above are context, printed for the record, never averaged in.
+ *
+ * Usage: memory_replay_24.ts [--write] [--format text|json]
+ *   --write  persist the dated note to agents/evidence/reports/memory-fts-replay.md
+ * Exit codes: 0 ok, 1 internal error, 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { _iter_curated_entries } from './memory_report.js';
+import { _score } from './memory_lookup.js';
+import { buildIndex, isStale, queryIndex, resolveIndexPath } from './_lib/memory_fts_index.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const MEMORY_ROOT = path.join(REPO_ROOT, 'agents', 'memory');
+export const INTAKE_ROOT = path.join(MEMORY_ROOT, 'intake');
+export const NOTE_PATH = path.join(REPO_ROOT, 'agents', 'evidence', 'reports', 'memory-fts-replay.md');
+
+const CURATED_STATUS_EXCLUDE: ReadonlySet<string> = new Set(['deprecated', 'archived', 'superseded']);
+
+/**
+ * Fixed 24-query set — real curated entry ids from `agents/memory/*.yml`
+ * (2026-07-27 snapshot), deliberately hyphen-heavy so the set exercises the
+ * exact separator-recall defect ADR-129 names (`ai_council`-style queries
+ * scoring 0 under the literal substring scorer). Each query is the entry's
+ * OWN id — "recall" means "does querying by an entry's id retrieve that
+ * same entry within the top 5".
+ */
+export const REPLAY_QUERIES: readonly string[] = [
+    'adr-number-collision-on-parallel-prs',
+    'agent-config-hooks-need-global-binary',
+    'ai-council-cli-repo-local-only',
+    'auto-commit-empties-roadmaps',
+    'bench-ab-cost-and-activation-mechanics',
+    'capability-matrix-coverage-guard',
+    'claude-plugin-local-install-via-worktree',
+    'command-cluster-ci-surface',
+    'commit-relocates-into-per-branch-worktree',
+    'council-a1-subagent-contract',
+    'council-access-control-and-remediation',
+    'council-agent-memory-sunset',
+    'council-ai-failure-mode-prevention',
+    'council-analysis-workbench',
+    'council-chat-history-consolidation',
+    'council-claude-code-single-surface',
+    'council-command-cluster-phase4',
+    'council-contract-integrity',
+    'council-curl-timeout-fix',
+    'council-decisions-workspace-phases',
+    'council-design-antislop-harvest',
+    'council-design-exploration-skills',
+    'council-discipline-axis-benchmark',
+    'council-ecc-harvest',
+];
+
+const K = 5;
+
+interface RankedRow {
+    id: string;
+    score: number;
+}
+
+interface EngineResult {
+    rank: number; // 0-based index within the top-K, -1 = not recalled
+    tieSet: number; // count of entries sharing the TOP score (over the whole ranking)
+    top5: string[];
+}
+
+interface QueryResult {
+    query: string;
+    baseline: EngineResult;
+    fts: EngineResult;
+    top5Overlap: number; // |baseline.top5 ∩ fts.top5| / K
+}
+
+/** Corpus entries (id + searchable text), status-excluded entries dropped — mirrors `retrieve()`'s candidate set. */
+function _corpusEntries(): Array<{ id: string; entry: Record<string, unknown> }> {
+    const out: Array<{ id: string; entry: Record<string, unknown> }> = [];
+    for (const [, , entry] of _iter_curated_entries()) {
+        const status = entry['status'];
+        if (typeof status === 'string' && CURATED_STATUS_EXCLUDE.has(status)) continue;
+        const id = typeof entry['id'] === 'string' ? entry['id'] : '';
+        if (id === '') continue;
+        out.push({ id, entry });
+    }
+    return out;
+}
+
+/** Deterministic ordering: score DESC, id ASC — the memory_lookup.ts contract. */
+function _sortRanked(rows: RankedRow[]): void {
+    rows.sort((a, b) => (b.score - a.score) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+function _diagnose(ranked: RankedRow[], needed: string): EngineResult {
+    const positive = ranked.filter((r) => r.score > 0);
+    if (positive.length === 0) return { rank: -1, tieSet: 0, top5: [] };
+    const top = positive[0]?.score ?? 0;
+    const tieSet = positive.filter((r) => r.score === top).length;
+    const top5 = positive.slice(0, K).map((r) => r.id);
+    const rank = top5.indexOf(needed);
+    return { rank, tieSet, top5 };
+}
+
+function _baselineRanked(corpus: Array<{ id: string; entry: Record<string, unknown> }>, keys: string[]): RankedRow[] {
+    const rows = corpus.map((c) => ({ id: c.id, score: _score(c.entry, keys) }));
+    _sortRanked(rows);
+    return rows;
+}
+
+function _ftsRanked(indexPath: string, keys: string[]): RankedRow[] {
+    const hits = queryIndex(indexPath, keys, []);
+    const rows = hits.map((h) => ({ id: h.id, score: h.relevance }));
+    _sortRanked(rows);
+    return rows;
+}
+
+export interface ReplaySummary {
+    schema_version: 1;
+    kind: 'memory-fts-replay';
+    generated_at: string;
+    corpus: string;
+    corpus_entries: number;
+    queries: number;
+    k: number;
+    baseline_recall_at_k: number;
+    fts_recall_at_k: number;
+    baseline_mean_tie_set_size: number;
+    fts_mean_tie_set_size: number;
+    mean_top5_overlap: number;
+    compared_against: {
+        second_brain_retrieval_json: { path: string; mean_tie_set_size: number };
+        lexical_ranking_json: { path: string; note: string };
+        comparability_note: string;
+    };
+}
+
+export function replay(): { results: QueryResult[]; summary: ReplaySummary } {
+    const corpus = _corpusEntries();
+    const indexPath = resolveIndexPath(REPO_ROOT);
+    if (isStale(indexPath, MEMORY_ROOT, INTAKE_ROOT)) {
+        buildIndex(indexPath, MEMORY_ROOT, INTAKE_ROOT);
+    }
+
+    const results: QueryResult[] = [];
+    for (const query of REPLAY_QUERIES) {
+        const baseline = _diagnose(_baselineRanked(corpus, [query]), query);
+        const fts = _diagnose(_ftsRanked(indexPath, [query]), query);
+        const overlapCount = baseline.top5.filter((id) => fts.top5.includes(id)).length;
+        const top5Overlap = K > 0 ? overlapCount / K : 0;
+        results.push({ query, baseline, fts, top5Overlap });
+    }
+
+    const n = results.length;
+    const mean = (sel: (r: QueryResult) => number): number =>
+        n === 0 ? 0 : Math.round((results.reduce((a, r) => a + sel(r), 0) / n) * 1000) / 1000;
+    const recallAt = (sel: (r: QueryResult) => EngineResult): number =>
+        n === 0 ? 0 : Math.round((results.filter((r) => sel(r).rank >= 0).length / n) * 1000) / 1000;
+
+    const summary: ReplaySummary = {
+        schema_version: 1,
+        kind: 'memory-fts-replay',
+        generated_at: new Date().toISOString(),
+        corpus: 'agents/memory/ (real, distractor-free)',
+        corpus_entries: corpus.length,
+        queries: n,
+        k: K,
+        baseline_recall_at_k: recallAt((r) => r.baseline),
+        fts_recall_at_k: recallAt((r) => r.fts),
+        baseline_mean_tie_set_size: mean((r) => r.baseline.tieSet),
+        fts_mean_tie_set_size: mean((r) => r.fts.tieSet),
+        mean_top5_overlap: mean((r) => r.top5Overlap),
+        compared_against: {
+            second_brain_retrieval_json: {
+                path: 'internal/bench/reports/second-brain-retrieval.json',
+                mean_tie_set_size: 4.111111111111111,
+            },
+            lexical_ranking_json: {
+                path: 'internal/bench/reports/lexical-ranking.json',
+                note: 'records ~3.333 mean baseline tie-set for the same _score scorer over the SAME bench store — a different measurement pass, cross-artefact discrepancy documented in docs/proof.md',
+            },
+            comparability_note:
+                'Both cited artefacts were measured over internal/bench/second-brain/retrieval-store/ (engineered needed+distractor fixture). This replay runs over the real agents/memory/ corpus (no engineered distractors) with a DIFFERENT query set (real entry ids, not curated needed/distractor tasks) — the numbers above are NOT directly comparable to either cited artefact. They are cited per ADR-129\'s instruction to name which baseline artefact a replay compares against; this replay\'s own baseline-vs-FTS delta (computed on one corpus, one run) is the load-bearing number.',
+        },
+    };
+    return { results, summary };
+}
+
+function _renderMarkdown(out: { results: QueryResult[]; summary: ReplaySummary }): string {
+    const s = out.summary;
+    const date = s.generated_at.slice(0, 10);
+    const lines: string[] = [];
+    lines.push(`# Memory FTS5 replay — ${date}`);
+    lines.push('');
+    lines.push(
+        'Rollback-trigger measurement for the memory FTS5 index (road-to-reachable-code-memory ' +
+            'Phase 6 item 2 / ADR-129). Compares the substring `_score` fallback against the ' +
+            'persisted FTS5 index over a fixed 24-query set of real `agents/memory/*.yml` entry ids.',
+    );
+    lines.push('');
+    lines.push('## Comparability note');
+    lines.push('');
+    lines.push(s.compared_against.comparability_note);
+    lines.push('');
+    lines.push('## Cited baselines (context only — not directly comparable, see above)');
+    lines.push('');
+    lines.push(
+        `- \`${s.compared_against.second_brain_retrieval_json.path}\` — ` +
+            `mean_tie_set_size = ${s.compared_against.second_brain_retrieval_json.mean_tie_set_size}`,
+    );
+    lines.push(`- \`${s.compared_against.lexical_ranking_json.path}\` — ${s.compared_against.lexical_ranking_json.note}`);
+    lines.push('');
+    lines.push('## This replay');
+    lines.push('');
+    lines.push(`- Corpus: ${s.corpus} (${s.corpus_entries} entries)`);
+    lines.push(`- Queries: ${s.queries}, k=${s.k}`);
+    lines.push(`- Recall@${s.k}: baseline=${s.baseline_recall_at_k}  fts=${s.fts_recall_at_k}`);
+    lines.push(
+        `- Mean top tie-set size: baseline=${s.baseline_mean_tie_set_size}  fts=${s.fts_mean_tie_set_size}`,
+    );
+    lines.push(`- Mean top-${s.k} overlap (baseline ∩ fts): ${s.mean_top5_overlap}`);
+    lines.push('');
+    lines.push('## Per-query detail');
+    lines.push('');
+    lines.push('| query | baseline rank | baseline tie | fts rank | fts tie | top5 overlap |');
+    lines.push('|---|---|---|---|---|---|');
+    for (const r of out.results) {
+        lines.push(
+            `| \`${r.query}\` | ${r.baseline.rank} | ${r.baseline.tieSet} | ${r.fts.rank} | ${r.fts.tieSet} | ${r.top5Overlap} |`,
+        );
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function main(argv: string[]): number {
+    let write = false;
+    let format: 'text' | 'json' = 'text';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--write') write = true;
+        else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? 'text';
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: memory_replay_24.ts [--write] [--format text|json]\n');
+            return 0;
+        } else {
+            process.stderr.write(`memory_replay_24: unknown argument ${a}\n`);
+            return 2;
+        }
+    }
+
+    let out: { results: QueryResult[]; summary: ReplaySummary };
+    try {
+        out = replay();
+    } catch (exc) {
+        process.stderr.write(`memory_replay_24: error: ${String(exc)}\n`);
+        return 1;
+    }
+
+    if (write) {
+        fs.mkdirSync(path.dirname(NOTE_PATH), { recursive: true });
+        fs.writeFileSync(NOTE_PATH, _renderMarkdown(out) + '\n');
+    }
+
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+        return 0;
+    }
+    const s = out.summary;
+    process.stdout.write(
+        `memory-fts-replay (${s.queries} queries, k=${s.k}, corpus=${s.corpus_entries} entries):\n` +
+            `  recall@${s.k}       baseline=${s.baseline_recall_at_k}  fts=${s.fts_recall_at_k}\n` +
+            `  mean top tie-set   baseline=${s.baseline_mean_tie_set_size}  fts=${s.fts_mean_tie_set_size}\n` +
+            `  mean top-${s.k} overlap: ${s.mean_top5_overlap}\n`,
+    );
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/memory_report.ts

@@ -189,10 +189,17 @@ function _pyYamlDatetimeStr(raw: string): string {
 
 // --- curated/intake iteration -----------------------------------------------
 
-type CuratedTuple = [string, string, Record<string, unknown>];
+export type CuratedTuple = [string, string, Record<string, unknown>];
 
-/** Yield [file, type, entry] across both curated layouts. */
-function _iter_curated_entries(): CuratedTuple[] {
+/**
+ * Yield [file, type, entry] across both curated layouts.
+ *
+ * Exported for reuse by `_lib/memory_fts_index.ts` (road-to-reachable-code-memory
+ * Phase 6) — the FTS index builder repoints `MEMORY_ROOT` via `_setMemoryRoot`
+ * before calling this, then restores it, so it never needs a second copy of
+ * the curated-layout scan.
+ */
+export function _iter_curated_entries(): CuratedTuple[] {
     const out: CuratedTuple[] = [];
     for (const mtype of CURATED_TYPES) {
         const single = path.join(MEMORY_ROOT, `${mtype}.yml`);
@@ -838,7 +845,13 @@ export function main(): number {
     return 0;
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }