pi-mega-compact 0.21.2 → 0.21.4

package/extensions/mega-runtime/runtime.ts

@@ -15,13 +15,12 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { join } from "node:path";
-import type { FSWatcher } from "node:fs";
 import { VectorStore } from "../../src/vectorStore.js";
 import type { toEngineMessages } from "../../src/adapt.js";
-import { normalizeSessionId } from "../../src/store.js";
 import { Logger } from "../../src/log.js";
+
+export { RING_MAX } from "./internal-errors.js";
 import type {
-	ModelSnapshot,
 	GameState,
 } from "../../src/store/sqlite.js";
 import type {
@@ -32,10 +31,7 @@ import { Dashboard } from "../mega-dashboard.js";
 import type {
 	SessionRuntime,
 } from "./helpers.js";
-import type {
-	TickerEntry,
-	WidgetData,
-} from "./widget.js";
+import { createSessionRuntime } from "./helpers.js";
 import {
 	ensureGameStateWatcherImpl,
 	getCachedGameStateImpl,
@@ -61,12 +57,14 @@ import {
 } from "./pressure-getters.js";
 import { resetRuntimeImpl } from "./reset-runtime.js";
 import { appendEventImpl } from "./append-event.js";
+import { recordInternalErrorImpl } from "./internal-errors.js";
+import { RuntimeInstrumentation } from "./runtime-instrumentation.js";
 import { getStateDirImpl } from "./get-state-dir.js";
 import { renderWidgetImpl } from "./render-widget.js";
 import { setStatusImpl } from "./status.js";
 import { engineViewImpl } from "./engine-view.js";
 
-export class MegaRuntime {
+export class MegaRuntime extends RuntimeInstrumentation {
 	config: MegaConfig;
 	// Store/dashboard/logger are rebound per-repo by bindRepo() so each git repo
 	// gets its own isolated state dir. They start bound to the global default.
@@ -77,208 +75,14 @@ export class MegaRuntime {
 	currentStateDir: string;
 
 	// The only mutable per-session state. Reset on session_start / session_tree.
-	rt: SessionRuntime = {
-		sessionId: normalizeSessionId(undefined),
-		persistedThisSession: false,
-		lastCheckpointId: undefined,
-		lastCompactedFrom: 0,
-		lastCompactedTokens: 0,
-		dedupSkips: 0,
-		dedupAttempts: 0,
-		tokensSaved: 0,
-		lastCompactAt: null,
-		lastRecallAt: null,
-		lastInjectAt: null,
-		_prevCacheHitPct: null,
-		_lastCacheHealthScore: undefined,
-		lastNativeCompactAt: null,
-		compactCount: 0,
-		recallInjections: 0,
-		cacheHitTokens: 0,
-		lengthStopPending: false,
-		errorRetryCount: 0,
-		errorRetryUntil: 0,
-		consecutiveErrors: 0,
-		lastErrorRetryAt: 0,
-		retryNudgePending: false,
-		errorRetrySessionCount: 0,
-		lastErrorText: undefined,
-		errorTextRepeatCount: 0,
-		poisonedAdviseSent: false,
-		providerOutageAdvised: false,
-		poisonedCompactSignatures: new Set(),
-		// S53: tracks whether withRecallTail injected this turn (consumed at turn_end).
-		recallInjectedThisTurn: false,
-		poisonedCount: 0,
-		extensionInitiatedTurn: false,
-	};
-	// v0.8.6 cache-stability: the cached live-trim view for the current
-	// compaction epoch. Set after a fresh runCompact + computeLiveTrimCut, and
-	// replayed verbatim on subsequent gated context events in the SAME epoch
-	// (same checkpointId) so the provider KV-cache prefix stays stable instead
-	// of being invalidated by a freshly regenerated summary + sentinel every
-	// fire. Invalidated on session restart (resetRuntime) and on any native
-	// durable compaction (session_compact) that truncates the transcript.
-	trimCache: {
-		checkpointId: string;
-		cut: number;
-		summaryAgentMsg: AgentMessage;
-		ctxPct: number | null;
-		ctxTokens: number | null;
-	} | null = null;
-	debounceUntil = 0;
-	// S16: debounce for the agent_end resume nudge (avoid busy-loops).
-	resumeNudgeUntil = 0;
-	// Agent tracking for real-time widget updates
-	activeAgents = 0;
-	currentTurn = 0;
-	// S33: transient MEGA CACHE flare flag (armed by the turn_end scoring hook
-	// when cachePct > 100). Copied into widgetData.megaCacheFlare on the next
-	// snapshot() so the widget renders the oopsie gag, then reset (one cycle).
-	megaCacheFlare = false;
-	/** v0.8.3: ambient effect state for animated panel borders keyed off
-	 *  status transitions (level-up, mega-cache overshoot, achievement unlock,
-	 *  compaction start). Threaded into widgetData as `activeEffect`; the widget
-	 *  computes the per-frame phase from startedAt vs Date.now() (non-expired).
-	 *  Null when idle/expired. */
-	activeEffect: { type: "pulse" | "flash"; role: "accent" | "mega" | "red"; startedAt: number; durationMs: number } | null = null;
-	megaCacheFlarePct = 0;
-	levelUpFlare = false;
-	lastLevel = 0;
-	// S35: transient achievement-unlock flare (armed by the scoring hooks after
-	// evaluateAndUnlockAchievements returns newly-unlocked titles). Copied into
-	// widgetData.achievementFlare on the next snapshot() so the widget renders the
-	// unlock toast, then reset (one cycle — mirrors megaCacheFlare/levelUpFlare).
-	achievementFlare = false;
-	achievementFlareTitles: string[] = [];
-	// S33: last cumulative dedup-collapsed count seen by the session_compact
-	// hook, so we only record the DELTA as the dedupe score (leaderboard sums).
-	lastDedupCollapsed = 0;
-	// Recall block produced by auto-inline (resume/branch) that the next
-	// before_agent_start should prepend to the system prompt. Unset after use.
-	pendingRecallBlock: string | undefined;
-	// S21: memory recall block, parallel to pendingRecallBlock. Same one-shot
-	// semantics; composed with the checkpoint block in before_agent_start.
-	pendingMemoryRecallBlock: string | undefined;
-	statusKey: string | undefined; // current status text for dashboard
-	// Active model/provider (for real cost estimation). Captured from ctx.model
-	// on model_select + session_start; persisted to SQL so cost + the dashboard
-	// can read it without a live ctx.
-	currentModel: ModelSnapshot | undefined;
-	// Live "what it's doing right now" timestamp, used for the fresh-window.
-	lastActivityAt = 0;
-	// Live per-tier dedup trace (Phase 1): e.g. "L0 ✓ → L1 ✓ → L2 0.91 → stored".
-	// Built from the store's sync onTier callback during a compaction so the user
-	// watches each tier evaluate in real time. Cleared once the outcome settles.
-	tierTrace: string | undefined;
-	// Phase 3 — standout toolbar state.
-	// Recall/activity ticker: a small ring buffer (≤5) of recent compact/recall
-	// events so the widget shows a live history instead of a single last action.
-	ticker: TickerEntry[] = [];
-	readonly TICKER_MAX = 5;
-	// Pulsing status: set true while a compaction is in flight, cleared on result.
-	pulsing = false;
-	// S21.2: set by `applyMemoryOps` when a memory add/replace/remove lands in
-	// the current compaction. The pipeline reads this after a successful compact
-	// to decide whether to fire `consolidateMemories` (skip the work entirely
-	// when no memory rows changed).
-	memoriesTouchedThisCompaction = 0;
-	// Rolling "saved" goal for the progress bar — grows as we save more, so the
-	// bar always has a meaningful denominator (never sits at 100% forever).
-	savedGoal = 50_000;
-	// Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
-	// while fresh.
-	lastWhy: string | undefined = undefined;
-	// v0.8.8 Perf dashboard instrumentation: turn/provider start timestamps +
-	// the 5s cpu/mem interval handle (one per MegaRuntime, cleared in dispose()).
-	perfTurnStart = 0;
-	perfProviderStart = 0;
-	perfCpuInterval: ReturnType<typeof setInterval> | null = null;
-	perfCpuBaseline: { user: number; sys: number } | undefined;
-
-	// Context tracking for the dashboard (updated in the context handler).
-	lastCtxTokens: number | null = null;
-	lastCtxPercent: number | null = null;
-	lastCtxWindow = 0;
-
-	// Latest computed widget payload (recomputed per snapshot, rendered per frame).
-	widgetData: WidgetData | null = null;
-	// v0.8.5: material-change signature from the last full snapshot() body. When
-	// the next snapshot()'s signature matches, the expensive recompute (6 sync
-	// SQLite opens) + writeFileSync(dashboard.json) are skipped — only the
-	// (already-registered) widget factory is refreshed. Kills the per-event
-	// main-thread block during typing/idle streaming with no material change.
-	lastSnapshotSig: string | null = null;
-	lastHeartbeatAt: number = 0;
-	// v0.8.5: bumped whenever the cached game-state memo is evicted (bumpGameState
-	// for in-process /mega-game writes, the fs.watch callback for cross-process
-	// dashboard-server writes, and bindRepo on repo switch) so the snapshot gate
-	// invalidates and the widget re-reads theme/mode after the change.
-	gameStateBump = 0;
-	// Cached cross-repo drift status (recomputed at most every 30s — it opens the
-	// machine-wide registry DB, so we don't want to do it on every render frame).
-	driftCache: { at: number; status: "ok" | "warn" } | null = null;
-	// S31: cached game-mode state (game_mode_on/theme/tui_display_mode). Lazily
-	// read from the game_state SQLite row on the first widget render, then
-	// memoized until bumpGameState() evicts it (called by /mega-game after a
-	// write) so the widget picks up theme/mode/level changes live without
-	// re-querying the DB on every render frame.
-	cachedGameState: GameState | undefined;
-	// S32: fs.watch on the current repo's sqlite.db so cross-process writes
-	// (e.g. the dashboard server's PUT /api/game-state, which runs as a detached
-	// child with no MegaRuntime ref) evict the cached game-state memo. Without
-	// this, /mega-game's in-process bumpGameState() is the only eviction trigger
-	// and the widget would keep showing stale theme/mode/toggle after a dashboard
-	// edit until a restart. The watcher tracks currentStateDir — closed + re-opened
-	// by ensureGameStateWatcher() on every bindRepo repo switch. Non-fatal: any
-	// fs.watch failure (missing file / platform issue) is swallowed; the next
-	// getCachedGameState() snapshot re-queries the DB anyway.
-	gameStateWatcher?: FSWatcher;
-	gameStateWatchDir?: string;
-	// P2: the last ExtensionContext handed to snapshot()/renderWidget(), stashed
-	// so the fs.watch game-state callback can force a widget re-render without
-	// a context event (cross-process dashboard edits while pi is idle). Cleared
-	// implicitly on construction (undefined → watcher skips until first snap).
-	lastWidgetCtx?: ExtensionContext;
-
-	/**
-	 * DIAG counters for the "team run doesn't relieve context" investigation.
-	 * Plain integers, incremented at the three compaction decision points. They
-	 * let a headless test drive the real event handlers and assert the firing
-	 * cadence without scraping log files. Inert in production (the live-trim and
-	 * before-compact probes also emit logger.info, but these counters are always
-	 * updated and cost nothing).
-	 */
-	diagLiveTrimFires = 0; // context handler returned a trimmed view
-	diagLiveTrimReplays = 0; // v0.8.6: trim view returned via cached replay (skipped re-compact)
-	diagBeforeCompactFires = 0; // session_before_compact handler entered
-	diagBeforeCompactSupplied = 0; // session_before_compact supplied our trim
-	diagAgentEndIdle = 0; // agent_end with activeAgents===0
-	diagAgentEndDurable = 0; // agent_end fired ctx.compact() (mid-run durable trim)
-	diagAgentEndDurableSkipRecent = 0; // agent_end skipped ctx.compact() — compaction in last 10s (race guard)
-	// Per-skip-path counters for the team-run diagnosis.
-	diagCtxFastGate = 0; // returned at token fast-gate (below threshold)
-	diagCtxNoCompact = 0; // autoCompactCheck().shouldCompact === false
-	diagCtxDebounce = 0; // debounceUntil not yet elapsed
-	diagCtxRunSkipped = 0; // runCompact() returned skipped
-	diagCtxCutNull = 0; // computeLiveTrimCut returned null (anchor/boundary)
-	diagCtxThrown = 0; // live-trim try threw (caught)
-
-	// Context health instrumentation (v0.12): rolling ring buffers for
-	// drift detection + cache poison Layer 1 hash baseline.
-	recentTurnEmbeddings: number[][] = [];
-	recentErrorCategories: (string | null)[] = [];
-	lastPrefixHash: string | null = null;
-	lastErrorCategory: string | null = null;
+	// Initialized via createSessionRuntime() (helpers.ts delegate-shell split).
+	rt: SessionRuntime = createSessionRuntime();
 
-	/**
-	 * S26 capture instrumentation: the "model_snapshots empty → $0.00 cost card"
-	 * bug was invisible because captureModel swallowed the DB write in a silent
-	 * `catch {}`. These always-updated counters (zero cost) let a headless test or
-	 * a live capture tell whether captureModel ran and whether the snapshot landed.
-	 */
-	diagCaptureModelCalls = 0; // captureModel entered with a populated ctx.model
-	diagCaptureModelFails = 0; // recordModelSnapshot threw → model_snapshots stays empty
+	// All other field declarations (instrumentation counters, context-health
+	// rings, the Sprint-H internal-error ring, live display / cache-stability
+	// state) live on the RuntimeInstrumentation base class — see
+	// runtime-instrumentation.ts. Field names are unchanged (this.diagXxx,
+	// this.trimCache, this.recentInternalErrors, etc).
 
 	// ---- pressure accessors (bodies in pressure-getters.ts) -------------------
 
@@ -301,6 +105,7 @@ export class MegaRuntime {
 	}
 
 	constructor(config: MegaConfig) {
+		super();
 		this.config = config;
 		this.store = new VectorStore({
 			dedupSim: config.dedupSim,
@@ -362,6 +167,21 @@ export class MegaRuntime {
 		appendEventImpl(this, event, fields);
 	}
 
+	/**
+	 * Sprint H (Finding 3 / Option A): record an internal store/service-write
+	 * failure category into the `recentInternalErrors` ring. Called AT each
+	 * failure emit site (see the §2.3a audit in
+	 * docs/specs/c2-resume-and-health-fixes.md) — never by a central log filter.
+	 * Mirrors `recentErrorCategories` (cap = RING_MAX, shift when over).
+	 *
+	 * NOTE (process boundary): the ring is per-runtime / in-memory. A child
+	 * subprocess's failures do NOT reach the parent's ring; the parent-side
+	 * dashboard already aggregates events.log cross-process, so nothing is lost.
+	 */
+	recordInternalError(category: string): void {
+		recordInternalErrorImpl(this, category);
+	}
+
 	/** S21: state dir of the currently bound repo (where memories live) — thin
 	 *  delegate to `getStateDirImpl` (get-state-dir.ts). */
 	getStateDir(): string {

package/extensions/mega-runtime/state.ts

@@ -5,4 +5,4 @@
  * every existing `import { MegaRuntime } from "./state.js"` continues to
  * resolve without changes.
  */
-export { MegaRuntime } from "./runtime.js";
+export { MegaRuntime, RING_MAX } from "./runtime.js";

package/extensions/mega-runtime/widget.ts

@@ -129,7 +129,7 @@ export function buildWidgetLines(
 		`${C.gray}all-time${C.reset} ${fmtTokens(wd.repoIn)}→${fmtTokens(wd.repoKept)} kept ${C.blue}(${wd.rTxt}% freed)${C.reset}`,
 		`${wd.repoChk} chk/${wd.repoSess} sess`,
 		`${C.gray}mem${C.reset} ${wd.embedderName} · ${wd.chk} chunks · ${C.blue}comp ${wd.compStr}${C.reset}`,
-		`${C.gray}drift${C.reset} ${wd.driftStatus === "ok" ? C.green : C.amber}${wd.driftStatus}${C.reset}`,
+		`${C.gray}comp lag${C.reset} ${wd.driftStatus === "ok" ? C.green : C.amber}${wd.driftStatus}${C.reset}`,
 		`${C.gray}compact${C.reset} ${sinceCompactStr(wd.sinceCompact)}`,
 		...(wd.perTurnCacheHitPct != null
 			? [

package/extensions/mega-turn-store.ts

@@ -12,6 +12,7 @@
 import {
 	createTurnStore,
 	type TurnStore,
+	type TurnReader,
 	type TurnEntry,
 	type TurnRecallEntry,
 	type TurnHydeTelemetry,
@@ -40,6 +41,11 @@ function storeFor(stateDir: string): TurnStore {
 	return s;
 }
 
+/** Read-only view of the turn store for a state dir (e.g. nextTurnIndexFor). */
+export function turnReaderFor(stateDir: string): TurnReader {
+	return storeFor(stateDir).asReader();
+}
+
 /** Map a legacy RecallSource onto the contract `TurnRecallEntry.source` enum. */
 function mapSource(s: string): TurnRecallEntry["source"] {
 	switch (s) {
@@ -77,6 +83,8 @@ export function recordTurnWrite(
 		conversationId: string;
 		sessionId: string;
 		turnIndex: number;
+		/** S49R: pi's per-session counter, carried for the raw_transcript join. */
+		sessionTurnIndex?: number;
 		role: string;
 		startedAt?: number;
 		endedAt?: number;
@@ -100,6 +108,7 @@ export function recordTurnWrite(
 		conversationId: input.conversationId,
 		sessionId: input.sessionId,
 		turnIndex: input.turnIndex,
+		sessionTurnIndex: input.sessionTurnIndex,
 		role: input.role as TurnEntry["role"],
 		endedAt: input.endedAt ?? input.startedAt ?? Date.now(),
 		ctxTokens: input.ctxTokens,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.21.2",
+  "version": "0.21.4",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -51,7 +51,7 @@
     "postbuild": "node scripts/vector-cortex-publish-acceptance.mjs",
     "build:dashboard": "cd extensions/dashboard-client && npx vite build",
     "test:dashboard-smoke": "node scripts/dashboard-tab-smoke.mjs",
-    "lint": "tsc --noEmit && node scripts/guardrails-scan.mjs && node scripts/semantic-scan.mjs && node scripts/stub-scan.mjs --fail-on-unregistered && node scripts/mock-scan.mjs --fail-on-unregistered",
+    "lint": "tsc --noEmit && node scripts/guardrails-scan.mjs && node scripts/semantic-scan.mjs && node scripts/stub-scan.mjs --fail-on-unregistered && node scripts/mock-scan.mjs --fail-on-unregistered && node scripts/internal-err-scan.mjs --fail-on-unregistered",
     "test": "npm run build && node scripts/run-tests.mjs",
     "guardrails": "python3 scripts/regression_check.py --all || node scripts/guardrails-scan.mjs || node scripts/semantic-scan.mjs",
     "precommit": "bash .claude/hooks/pre-commit.sh",

package/src/bridge/factory.ts

@@ -0,0 +1,245 @@
+/**
+ * bridge/factory.ts — `createMegaBridge(opts)` implementation.
+ *
+ * A thin, pi-agnostic wrapper over the engine's compaction / recall / memory /
+ * fork / vector APIs. Stores are constructed lazily on first use (a consumer
+ * that only calls recallMemories pays no VectorStore cost). Exceptions
+ * propagate from every method except `fork` (catches ForkError by design) and
+ * `close` (swallows best-effort cleanup), so failures surface in tests.
+ */
+import { compactSession } from "../engine.js";
+import {
+  recallAndInline,
+  recallAndInlineAsync,
+  recallMemoriesAndInline,
+} from "../recall.js";
+import type {
+  RecallInjectOptions,
+  RecallInjectResult,
+  MemoryRecallInjectOptions,
+} from "../recall/types.js";
+import { forkFromConversation, ForkError } from "../fork.js";
+import { createTurnStore } from "../store/turns/index.js";
+import type { TurnStore, TurnEntry } from "../store/turns/types.js";
+import { addMemory } from "../store/sqlite/memories.js";
+import { VectorStore, vectorSearch } from "../vectorStore.js";
+import type { SearchHit } from "../vectorStore.js";
+import { repoKey } from "../store/repoKey.js";
+import type {
+  BridgeOptions,
+  BridgeCompactInput,
+  BridgeCompactResult,
+  BridgeRecallOptions,
+  BridgeRecallResult,
+  BridgeMemoryRecallOptions,
+  BridgeMemoryRecallResult,
+  BridgeForkOptions,
+  BridgeForkResult,
+  BridgeCortexOptions,
+  BridgeCortexResult,
+  BridgeAddMemoryInput,
+  BridgeRecordTurnInput,
+  MegaBridge,
+} from "./types.js";
+
+/** Map a RecallInjectResult to the bridge's slimmer result contract. */
+function mapRecallResult(r: RecallInjectResult): BridgeRecallResult {
+  return {
+    block: r.block,
+    report: r.report,
+    hitCount: r.toInject.length,
+    empty: r.empty,
+  };
+}
+
+/** Map the memoryRecallAndInline tuple result to the bridge contract. */
+function mapMemoryResult(
+  r: { empty: boolean; block: string; report: string[] },
+): BridgeMemoryRecallResult {
+  return {
+    block: r.block,
+    report: r.report,
+    hitCount: r.report.length,
+    empty: r.empty,
+  };
+}
+
+/** Map vectorSearch hits to the cortex result contract. */
+function mapCortexHits(hits: SearchHit[], limit: number): BridgeCortexResult {
+  const top = hits.slice(0, limit);
+  return {
+    results: top.map((h) => ({
+      checkpointId: h.checkpoint.checkpointId,
+      score: h.score,
+      summary: h.checkpoint.summary,
+    })),
+    hitCount: top.length,
+  };
+}
+
+/**
+ * Create a MegaBridge over a single stateDir.
+ *
+ * The VectorStore and TurnStore are lazy: constructed on first use and cached
+ * in closures. The stateDir is retained for memory recall, which needs it
+ * directly.
+ */
+export function createMegaBridge(opts: BridgeOptions): MegaBridge {
+  const stateDir = opts.stateDir;
+  let vectorStore: VectorStore | undefined;
+  let turnStore: TurnStore | undefined;
+
+  const getVectorStore = (): VectorStore => {
+    if (!vectorStore) vectorStore = new VectorStore({ stateDir });
+    return vectorStore;
+  };
+  const getTurnStore = (): TurnStore => {
+    if (!turnStore) turnStore = createTurnStore({ stateDir });
+    return turnStore;
+  };
+
+  return {
+    compact(input: BridgeCompactInput): BridgeCompactResult {
+      const result = compactSession(
+        {
+          sessionId: input.sessionId,
+          messages: input.messages,
+          keepFrom: input.keepFrom,
+          summary: input.summary,
+          keyDecisions: input.keyDecisions,
+          nextSteps: input.nextSteps,
+          filesModified: input.filesModified,
+          compressionPressure: input.compressionPressure,
+        },
+        getVectorStore(),
+      );
+      return {
+        skipped: result.skipped,
+        deduped: result.deduped,
+        summary: result.summary,
+        checkpointId: result.checkpointId,
+        tokenEstimate: result.tokenEstimate,
+        originalTokenEstimate: result.originalTokenEstimate,
+        compactedFrom: result.compactedFrom,
+      };
+    },
+
+    recallCheckpoints(opts: BridgeRecallOptions): BridgeRecallResult {
+      const recallOpts: RecallInjectOptions = {
+        sessionId: opts.sessionId,
+        query: opts.query,
+        limit: opts.limit ?? 3,
+        source: "command",
+        skipInjected: opts.skipInjected,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      return mapRecallResult(recallAndInline(recallOpts, getVectorStore()));
+    },
+
+    async recallMemories(opts: BridgeMemoryRecallOptions): Promise<BridgeMemoryRecallResult> {
+      const memOpts: MemoryRecallInjectOptions = {
+        query: opts.query,
+        stateDir,
+        limit: opts.limit,
+        minSimilarity: opts.minSimilarity,
+        crossRepo: opts.crossRepo,
+        crossRepoCosine: opts.crossRepoCosine,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      const r = await recallMemoriesAndInline(memOpts);
+      return mapMemoryResult(r);
+    },
+
+    async recallAndInlineAsync(opts: BridgeRecallOptions): Promise<BridgeRecallResult> {
+      const recallOpts: RecallInjectOptions = {
+        sessionId: opts.sessionId,
+        query: opts.query,
+        limit: opts.limit ?? 3,
+        source: "command",
+        skipInjected: opts.skipInjected,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      const r = await recallAndInlineAsync(recallOpts, getVectorStore());
+      return mapRecallResult(r);
+    },
+
+    fork(opts: BridgeForkOptions): BridgeForkResult {
+      try {
+        const outcome = forkFromConversation(
+          getTurnStore(),
+          opts.parentConversationId,
+          opts.turnIndex,
+        );
+        return {
+          childConversationId: outcome.childConversationId,
+          checkpointIds: outcome.checkpointIds,
+          forkTurnIndex: opts.turnIndex,
+        };
+      } catch (e) {
+        if (e instanceof ForkError) {
+          return { error: e.code };
+        }
+        // The bridge is pi-agnostic (no runtime handle) — the host-side adapter
+        // (ithacus) owns the internal-error ring for fork failures, so this
+        // re-thrown non-ForkError is recorded there, not here.
+        // guardrails-allow INTERNAL-ERR: bridge is pi-agnostic; no runtime handle — host adapter records fork failures
+        throw e;
+      }
+    },
+
+    cortexQuery(opts: BridgeCortexOptions): BridgeCortexResult {
+      const limit = opts.limit ?? 3;
+      const scope = opts.repo ?? repoKey(stateDir);
+      const hits = vectorSearch(getVectorStore(), scope, opts.query, limit);
+      return mapCortexHits(hits, limit);
+    },
+
+    addMemory(input: BridgeAddMemoryInput): number | void {
+      // repo === null ⇒ stateDir-scoped durable memory (matches recallMemories).
+      return addMemory(
+        {
+          kind: input.kind,
+          content: input.content,
+          tags: input.tags,
+          category: input.category,
+        },
+        null,
+        stateDir,
+      );
+    },
+
+    recordTurn(input: BridgeRecordTurnInput): void {
+      // S49R: child turns get the conversation-monotonic index (MAX+1) so a
+      // re-dispatched child (same conversation, restarted session counter) never
+      // collides with UNIQUE(conversation_id, turn_index). Carry the child's
+      // session counter as sessionTurnIndex for the raw_transcript join.
+      const turnIndex = getTurnStore().asReader().nextTurnIndexFor(input.conversationId);
+      const turn: TurnEntry = {
+        conversationId: input.conversationId,
+        sessionId: input.sessionId,
+        turnIndex,
+        sessionTurnIndex: input.turnIndex,
+        role: (input.role as TurnEntry["role"]) ?? "assistant",
+        endedAt: input.endedAt ?? Date.now(),
+        ctxTokens: input.ctxTokens,
+        ctxPercent: input.ctxPercent,
+        model: input.model,
+      };
+      // The bridge is pi-agnostic (no runtime handle); the host-side adapter
+      // (ithacus) owns the internal-error ring for appendTurn failures. The
+      // recordTurn child-path twin of Finding 2 is recorded there, not here.
+      // guardrails-allow INTERNAL-ERR: bridge is pi-agnostic; no runtime handle — host adapter records appendTurn failures
+      getTurnStore().asWriter().appendTurn(turn);
+    },
+
+    close(): void {
+      if (turnStore) {
+        try {
+          turnStore.close();
+        } catch {
+          /* best-effort */
+        }
+      }
+    },
+  };
+}