pi-mega-compact 0.8.23 → 0.8.25

package/extensions/mega-pipeline/compact.ts

@@ -24,6 +24,7 @@ import {
 } from "../mega-runtime.js";
 import { resolveRepoRoot, preserveRecentForPressure, type MegaConfig } from "../mega-config.js";
 import { runRaptor } from "../../src/dedup/raptor/index.js";
+import { isRaptorTreeFresh } from "../../src/dedup/raptor/buildHistory.js";
 import { loadDedupConfig } from "../../src/config/dedup.js";
 import { upsertEmbedding as indexUpsertEmbedding } from "../../src/store/vectorIndex.js";
 import { runMemoryReview } from "./memory-review.js";
@@ -221,22 +222,33 @@ function doCompact(
         embedding: cp.embedding,
       }));
       if (leaves.length >= 2) {
-        // S25: stamp the tree with the newest checkpoint epoch so the
-        // freshness guard in raptorSearchHits can reject stale trees after a
-        // later compaction adds newer checkpoints.
-        const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
-        runRaptor(
-          leaves,
-          {
-            stateDir: runtime.currentStateDir,
-            sessionId: sid,
-            budgetMs: dd.RAPTOR_BUDGET_MS,
-            clustersPerLevel: dd.RAPTOR_CLUSTERS_PER_LEVEL,
-            consistencyThreshold: dd.RAPTOR_CONSISTENCY,
-            logger: runtime.logger,
-            builtAt: Number.isFinite(builtAt) ? builtAt : Date.now(),
-          },
-        );
+        // S42D: skip the rebuild when the last build is fresh (within
+        // RAPTOR_FRESHNESS_HOURS) and the checkpoint count hasn't drifted by
+        // more than 20%. avoids re-clustering on every compaction when the
+        // tree is still representative. 0 disables (always rebuild).
+        if (
+          dd.RAPTOR_FRESHNESS_HOURS > 0 &&
+          isRaptorTreeFresh(sid, runtime.currentStateDir, dd.RAPTOR_FRESHNESS_HOURS, all.length)
+        ) {
+          runtime.logger?.info("raptor_skip_fresh", { sessionId: sid });
+        } else {
+          // S25: stamp the tree with the newest checkpoint epoch so the
+          // freshness guard in raptorSearchHits can reject stale trees after a
+          // later compaction adds newer checkpoints.
+          const builtAt = all.length > 0 ? Math.max(...all.map((c) => c.timestamp)) : Date.now();
+          runRaptor(
+            leaves,
+            {
+              stateDir: runtime.currentStateDir,
+              sessionId: sid,
+              budgetMs: dd.RAPTOR_BUDGET_MS,
+              clustersPerLevel: dd.RAPTOR_CLUSTERS_PER_LEVEL,
+              consistencyThreshold: dd.RAPTOR_CONSISTENCY,
+              logger: runtime.logger,
+              builtAt: Number.isFinite(builtAt) ? builtAt : Date.now(),
+            },
+          );
+        }
       }
     } catch {
       /* non-fatal: tree refresh never blocks a compaction */

package/extensions/mega-pipeline/recall.ts

@@ -10,7 +10,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import { recallAndInline, recallAndInlineAsync, formatRecallBlock, type RecallInjectResult } from "../../src/recall.js";
 import { normalizeSessionId } from "../../src/store.js";
-import { incRecallInjected, incCacheHitTokens } from "../../src/store/sqlite.js";
+import { incRecallInjected, incCacheHitTokens, getIndexDir } from "../../src/store/sqlite.js";
+import { ensureConversationId, recordTurn, recordTurnRecall, type RecallSource } from "../../src/store/sqlite/turns.js";
 import {
   type MegaRuntime,
   C,
@@ -64,6 +65,30 @@ export function doRecall(
     runtime.rt.cacheHitTokens += sumTokens;
     incRecallInjected(result.toInject.length, runtime.currentStateDir);
     incCacheHitTokens(sumTokens, runtime.currentStateDir);
+    // S43: record recall provenance — which checkpoints/summaries served this
+    // turn, their score + source path. Linked to the turn row written at
+    // turn_end via the conversation+turnIndex. Best-effort + non-fatal.
+    try {
+      const convId = ensureConversationId(sid, runtime.currentStateDir);
+      const turnId = recordTurn({
+        conversationId: convId,
+        sessionId: sid,
+        turnIndex: runtime.currentTurn,
+        startedAt: Date.now(),
+      }, runtime.currentStateDir);
+      recordTurnRecall(
+        turnId,
+        result.toInject.map((h) => ({
+          checkpointId: h.checkpoint.checkpointId,
+          score: h.score,
+          source: (h.raptorLevel !== undefined ? "raptor" : h.repoId ? "cross-repo" : "flat") as RecallSource,
+          raptorLevel: h.raptorLevel,
+        })),
+        runtime.currentStateDir,
+      );
+    } catch {
+      /* non-fatal: recall provenance never breaks the recall path */
+    }
   }
   return result;
 }
@@ -108,7 +133,14 @@ export async function doRecallAsync(
         sessionId: sid, query, limit: config.autoInlineK, source, skipInjected: true,
         recallMaxTokens: config.recallMaxTokens, windowDedupe: config.windowDedupe,
         liveWindow, dedupSim: config.crossRepoCosine, crossRepo: true,
-        globalIndexDir: process.env.MEGACOMPACT_INDEX_DIR,
+        // F2: resolve the machine-wide index dir via the shared resolver so the
+        // cross-repo injected-set dedup works even when MEGACOMPACT_INDEX_DIR is
+        // unset. The env var still wins when set (getIndexDir checks it first);
+        // the default (~/.mega-compact-index) is the same DB mega-commands and the
+        // dashboard read, so injection counts stay consistent. Without this, a
+        // bare `process.env` read returns undefined → cross-repo hits re-inject in
+        // every new session (the global injected-set is never consulted).
+        globalIndexDir: getIndexDir(),
       },
       runtime.store,
     );

package/extensions/mega-runtime/DECOMPOSITION.md

@@ -0,0 +1,180 @@
+# mega-runtime — Decomposition Tracker
+
+This file tracks the progressive decomposition of the original `mega-runtime.ts`
+monolith (2 600+ lines) into focused single-responsibility modules.
+
+---
+
+## Current State (raptor-promotion branch)
+
+### Completed — Phase 1: Extract pure helpers
+
+The original `state.ts` (later `mega-runtime.ts`) has been split into:
+
+| File | Lines | Responsibility |
+|---|---|---|
+| `state.ts` | 8 | **Re-export placeholder** — re-exports `MegaRuntime` from `runtime.ts` so all existing imports keep working |
+| `runtime.ts` | ~522 | **MegaRuntime class** — the orchestrator (constructor, dispose, bindRepo, 1-line delegate methods) |
+| `runtime-snapshot.ts` | ~289 | `snapshotImpl(ctx, ctxPi)` — the full `snapshot()` body (vector stats, threshold/armed/ready, drift, widget, dashboard.json write) |
+| `runtime-helpers.ts` | ~119 | Extracted private helpers: `materialSigImpl`, `embedderNameImpl`, `driftStatusImpl`, `getTurnLevelImpl` + `RuntimeHelpersContext` |
+| `snapshot.ts` | ~229 | `computeMegaSnapshot()` — pure function, no class state |
+| `dashboard-snapshot.ts` | ~173 | `computeDashboardSnapshot()` — dashboard-specific snapshot variant |
+| `widget.ts` | ~172 | **Thin barrel** — owns `buildWidgetLines()` + re-exports from `widget-ansi.ts`/`widget-types.ts` |
+| `widget-ansi.ts` | ~218 | ANSI palette (`C`), `PULSE`, panel layout helpers, ambient border-effect helpers, token/time formatters |
+| `widget-types.ts` | ~81 | `TickerEntry` + `WidgetData` interfaces (pure types, zero imports) |
+| `effects.ts` | ~129 | Effect/flare helpers: `armMegaCacheFlareImpl`, `armAchievementFlareImpl`, `setEffectImpl`, `pushTickerImpl` |
+| `game-state.ts` | ~125 | Game state cache: `ensureGameStateWatcherImpl`, `bumpGameStateImpl`, `refreshWidgetGameStateImpl` |
+| `capture-model.ts` | ~101 | Model capture: `captureModelImpl` |
+| `bind-repo.ts` | ~81 | Repo binding: `resolveRepoId`, `resolveMemoRoot` |
+| `perf.ts` | ~60 | Perf sample helpers: `recordPerfSample`, `ensurePerfIntervalImpl`, `disposePerf` |
+| `helpers.ts` | ~73 | Shared constants/types (`MEGA_HOME`, `DEFAULT_CONFIG`, `MegaConfig`, etc.) |
+| `query.ts` | ~29 | Query helpers (`recentUserQuery`) |
+
+All tests pass (the suite is built and run via `npm test` → `node scripts/run-tests.mjs`).
+
+### Completed — Phase 2a: Split `widget.ts` (~422 → 172 + 218 + 81 lines)
+
+The original monolithic `widget.ts` has been decomposed into three files with a
+preserved barrel so **no consumer import changed**:
+
+| New file | Content | Source of the code |
+|---|---|---|
+| `widget-types.ts` | `TickerEntry`, `WidgetData` interfaces | moved verbatim from the old `widget.ts` |
+| `widget-ansi.ts` | `C` palette, `PULSE`, `DEFAULT_PANEL_BG`, `panelBgFor`, `themeAnsi`, `sgrReset`, `wrapLine`, `panelLine`, `panelBar`, `EFFECT_BASE`, `effectBorderSgr`, `effectBar`, `fmtTokens`, `ramp`, `sinceCompactStr` | moved verbatim; the previously-private helpers are now `export`ed |
+| `widget.ts` (slimmed) | `buildWidgetLines()` + `export { … } from "./widget-ansi.js"` + `export type { … } from "./widget-types.js"` | the render function stays here; barrel re-exports keep `./widget.js` resolving `C`, `TickerEntry`, `WidgetData`, `buildWidgetLines` |
+
+**Compatibility:** the only names the old `widget.ts` exported were `C`,
+`TickerEntry`, `WidgetData`, `buildWidgetLines`; every other helper was a
+non-exported `const`/`function`. The new `widget.ts` re-exports **all** of them
+(additive — more public surface, no removed names), and there is **zero name
+collision** with the sibling barrels (`helpers.ts`/`state.ts`/`query.ts`), so the
+`extensions/mega-runtime.ts` `export * from "./mega-runtime/widget.js"` keeps
+resolving identically. Verified: `tsc --noEmit` passes; `widget.test.ts`
+(S31 matrix + ambient-effect + footer-stability + achievement-flare) green.
+
+---
+
+## Completed — Phase 2b: Extract `runtime.ts` private helpers (~783 → ~754 lines + 120)
+
+The four pure/instance helpers were extracted from the `MegaRuntime` class into
+`runtime-helpers.ts` following the established context-interface + free-function
++ thin-delegate pattern (same as `effects.ts` / `game-state.ts` / `capture-model.ts`
+/ `bind-repo.ts` / `perf.ts`).
+
+| New file | Content | Source of the code |
+|---|---|---|
+| `runtime-helpers.ts` | `RuntimeHelpersContext` interface + `materialSigImpl(ctx)`, `embedderNameImpl()`, `driftStatusImpl(ctx)`, `getTurnLevelImpl(ctx)` | moved verbatim from the old private methods |
+| `runtime.ts` (slightly slimmer) | the four methods are now 1-line delegates (`return *Impl(this)`); `driftCache` is now public so `MegaRuntime` satisfies `RuntimeHelpersContext` structurally | — |
+
+**What moved:**
+- `materialSig()` → `materialSigImpl(ctx)` — pure over all-public fields.
+- `embedderName()` → `embedderNameImpl()` — trivially pure (reads `process.env`).
+- `driftStatus()` → `driftStatusImpl(ctx)` — required `driftCache` to become
+  public (one-token change; internal state, not an API contract). The
+  `detectCrossRepoDrift` import moved into `runtime-helpers.ts` (was only used
+  there) and was dropped from `runtime.ts`.
+- `getTurnLevel()` → `getTurnLevelImpl(ctx)` — the `turnLevel` import moved into
+  `runtime-helpers.ts` and was dropped from `runtime.ts`.
+
+All call sites (`this.materialSig()`, `this.embedderName()`, `this.driftStatus()`,
+`this.getTurnLevel()`) are unchanged — the thin in-class delegates preserve the
+existing API. Verified: `tsc --noEmit` passes; full suite green.
+
+## Completed — Phase 2c: Extract `snapshot()` body to `runtime-snapshot.ts` (~783 → ~522 lines + 289)
+
+The `snapshot()` method — the single largest method on `MegaRuntime` — was
+extracted into `runtime-snapshot.ts` as `snapshotImpl(self, ctx?)`, following
+the same context-interface + free-function + thin-delegate pattern.
+
+| New file | Content | Source of the code |
+|---|---|---|
+| `runtime-snapshot.ts` | `RuntimeSnapshotContext` interface + `snapshotImpl(self, ctx?)` — the full snapshot body: material-sig gate, vector stats, effective threshold/armed/ready, drift status, `computeMegaSnapshot` → `widgetData` + `renderWidget`, `writeFileSync(dashboard.json)`, perf sample, ticker push, flare arming | moved verbatim from the old `snapshot()` method |
+| `runtime.ts` (slimmed) | `snapshot(ctx?)` is now a 1-line delegate (`return snapshotImpl(this, ctx)`); `lastSnapshotSig` is now public so `MegaRuntime` satisfies `RuntimeSnapshotContext` structurally | — |
+
+**What moved:**
+- The `computeMegaSnapshot`, `buildDashboardSnapshot`, `detectCrossRepoDrift`,
+  `vectorStats`/`vectorRepoStats`/`vectorDataInvariant`, `recordPerfSample`,
+  `recordSessionHeartbeat`, `appendTokenSample`, and `latestModelSnapshot`
+  imports moved into `runtime-snapshot.ts` (none are used by `runtime.ts`
+  anymore) — `runtime.ts` only imports `VectorStore` (type) now.
+- `lastSnapshotSig` became public (one-token change; internal state, not an
+  API contract) so `MegaRuntime` satisfies `RuntimeSnapshotContext`.
+
+All call sites (the `before_agent_start`/`context`/`compact` handlers that
+call `this.snapshot(ctx)`) are unchanged — the thin in-class delegate
+preserves the existing API. Verified: `tsc --noEmit` passes; full suite
+green (649 tests across 61 files).
+
+## Completed — Phase 2d: Maximal split of `runtime.ts` (~522 → ~437 lines, zero method bodies)
+
+The maximal split moves **every** remaining method body in `runtime.ts` into
+its own single-responsibility module, leaving the class as field declarations,
+the constructor, and 1-line delegates only. This completes the decomposition
+charter: no logic lives in the orchestrator file anymore.
+
+| New file | Content | Source of the code |
+|---|---|---|
+| `pressure-getters.ts` | `PressureContext` + `pressureImpl` / `effectiveThresholdImpl` / `pressureBandImpl` | moved verbatim from the `pressure` / `effectiveThreshold` / `pressureBand` getters |
+| `reset-runtime.ts` | `ResetRuntimeContext` + `resetRuntimeImpl(self, sessionId)` | moved verbatim from `resetRuntime()` |
+| `append-event.ts` | `AppendEventContext` + `appendEventImpl(self, event, fields)` | moved verbatim from `appendEvent()` |
+| `get-state-dir.ts` | `GetStateDirContext` + `getStateDirImpl(self)` | moved verbatim from `getStateDir()` |
+| `render-widget.ts` | `RenderWidgetContext` + `renderWidgetImpl(self, ctx)` | moved verbatim from `renderWidget()` |
+| `status.ts` | `SetStatusContext` + `setStatusImpl(self, ctx, text)` | moved verbatim from `setStatus()` |
+| `engine-view.ts` | `engineViewImpl(messages)` | moved verbatim from `engineView()` |
+| `game-state.ts` (+append) | `DisposeRuntimeContext` + `disposeRuntimeImpl(self)` | moved verbatim from `dispose()` (game-state.ts already owns the watcher context, so this lands there alongside `ensureGameStateWatcherImpl`) |
+
+**What moved / changed:**
+- `runtime.ts` import block rewritten: dropped `appendFileSync`/`mkdirSync`,
+  `STATUS_KEY`/`WIDGET_KEY`, `buildWidgetLines`, and
+  `pressureRatio`/`pressureFromPct`/`pressureBand`/`effectiveThresholdTokens`
+  (now consumed only in their respective modules); added imports of the 7 new
+  `*Impl` functions + `disposeRuntimeImpl`. `toEngineMessages` is kept
+  (`engineView`'s return type still references it); `normalizeSessionId` is kept
+  (the `rt` field initializer still uses it).
+- The big pressure doc comment moved to `pressure-getters.ts`; `runtime.ts`
+  keeps a one-line pointer comment per delegate.
+- `dispose()` delegates to `disposeRuntimeImpl` (in `game-state.ts`), which
+  composes `GameStateContext` + `PerfContext` and calls the existing
+  `disposePerf` — so `disposePerf` is no longer imported by `runtime.ts`.
+
+**Why maximal:** the soft `~500 line` doc-length target (CLAUDE.md §6) applies to
+source files too. `runtime.ts` at 522 lines was the only mega-runtime source
+file over the target; the split brings it to **437 lines** (delegates + fields +
+constructor only), with every new file ≤96 lines. The pattern (context-interface
++ free-function + thin-delegate) is the same one established in Phase 1
+(`effects.ts`/`game-state.ts`/`capture-model.ts`/`bind-repo.ts`/`perf.ts`) and
+extended in Phase 2b/2c (`runtime-helpers.ts`/`runtime-snapshot.ts`).
+
+Verified: `tsc --noEmit` passes; `npm run lint` (tsc + guardrails-scan +
+semantic-scan) green; `npm test` green (678 tests, 61 files, 0 failures);
+`python3 scripts/regression_check.py --all` green; 8-point structural audit
+green (line counts, no logic primitives left, 22 `Impl(this)` delegates, no
+`this.` in new files, each `*Impl` defined exactly once, git scope limited to
+the 2 modified + 7 new files, game-state.ts diff is purely additive, tsc clean).
+
+
+### Deferred — effects wrappers
+
+The `armMegaCacheFlare` / `armAchievementFlare` / `setEffect` / `pushTicker`
+methods on `MegaRuntime` are already thin one-line delegates whose bodies live
+in `effects.ts` (`*Impl` functions). They could optionally be collapsed into a
+`runtime-effects.ts` barrel-of-delegates, but this yields little benefit (each
+is already one line) and risks churn. **Deferred** unless `runtime.ts` grows.
+
+## Sprint Backlog (prioritised)
+
+1. ~~**Split `widget.ts`** — done (Phase 2a).~~
+2. ~~**Split `runtime.ts`** — extract `materialSig`/`embedderName`/`driftStatus`/`getTurnLevel` into `runtime-helpers.ts` — done (Phase 2b).~~
+3. ~~**Extract `snapshot()` body** into `runtime-snapshot.ts` — done (Phase 2c).~~
+4. ~~**Verify `state.ts` re-export** — confirm `state.ts` → `runtime.ts` → final modules chain works (`state.test.ts` uses `createRequire` to load compiled JS) — green after Phase 2b.~~
+5. ~~**Run full test suite** after each split (`npm test`) — green after 2a, 2b, and 2c (649 tests, 61 files, 0 failures).~~
+6. **Final cleanup** — remove the `state.ts` placeholder once all consumers are updated to import `MegaRuntime` directly from `runtime.ts` (low priority; `state.ts` re-export is zero-cost).
+7. **Commit Phase 2** — stage the Phase 2a/2b/2c changes (`runtime-helpers.ts`, `widget-ansi.ts`, `widget-types.ts`, `widget.ts`, `runtime-snapshot.ts`, `runtime.ts`, `DECOMPOSITION.md`) and commit.
+
+---
+
+## Notes
+
+- `state.ts` is intentionally kept as a re-export to avoid a breaking change in `extensions/mega-runtime.ts:18` which imports `MegaRuntime` from `./mega-runtime/state.js`.
+- `state.test.ts` and `widget.test.ts` exist alongside the source — they use `createRequire` to load compiled JS, not direct TS imports, so they exercise the built `dist/` output (build before testing).
+- The `extensions/mega-runtime.ts` barrel does `export * from "./mega-runtime/widget.js"`; the widget split keeps that resolving because `widget.ts` re-exports the same public surface.

package/extensions/mega-runtime/README.md

@@ -0,0 +1,38 @@
+# mega-runtime
+
+Runtime state and widget rendering for the mega-compact dashboard.
+
+## Module structure
+
+`MegaRuntime` (in `runtime.ts`) is a delegates-only orchestrator: field
+declarations, the constructor, and 1-line delegates to `*Impl` free functions in
+single-responsibility modules. Keep it that way — when adding logic, put the body
+in a new `*.ts` module and add a thin delegate, rather than growing `runtime.ts`
+(see `DECOMPOSITION.md` + the "no large files" rule in `CLAUDE.md` §6).
+
+| Module | Responsibility |
+|---|---|
+| `state.ts` | Barrel re-export of `MegaRuntime` (backwards-compat import path) |
+| `runtime.ts` | `MegaRuntime` class — delegates-only orchestrator (fields + constructor + 1-line delegates) |
+| `runtime-snapshot.ts` | `snapshotImpl()` — the full `snapshot()` body (dashboard write + widget-data compute + gate) |
+| `runtime-helpers.ts` | `materialSigImpl` / `embedderNameImpl` / `driftStatusImpl` / `getTurnLevelImpl` + `RuntimeHelpersContext` |
+| `pressure-getters.ts` | `pressureImpl` / `effectiveThresholdImpl` / `pressureBandImpl` (the pressure accessors) |
+| `reset-runtime.ts` | `resetRuntimeImpl()` — per-session state reset |
+| `append-event.ts` | `appendEventImpl()` — structured events.log sink |
+| `get-state-dir.ts` | `getStateDirImpl()` — bound repo state dir (S21) |
+| `render-widget.ts` | `renderWidgetImpl()` — width-aware above-editor widget factory |
+| `status.ts` | `setStatusImpl()` — status-key text mirrored to pi's status line |
+| `engine-view.ts` | `engineViewImpl()` — pi→engine message adapter passthrough |
+| `snapshot.ts` | `computeMegaSnapshot()` pure function |
+| `dashboard-snapshot.ts` | `computeDashboardSnapshot()` |
+| `widget.ts` | Barrel — `buildWidgetLines()` + re-exports from `widget-ansi.ts` / `widget-types.ts` |
+| `widget-ansi.ts` | ANSI palette (`C`), `PULSE`, panel layout + border-effect helpers, token/time formatters |
+| `widget-types.ts` | `TickerEntry` + `WidgetData` interfaces (pure types) |
+| `effects.ts` | Effect/flare helpers (`setEffectImpl`, `armMegaCacheFlareImpl`, etc.) |
+| `game-state.ts` | Game-state cache + watcher (`ensureGameStateWatcherImpl`, `bumpGameStateImpl`, `disposeRuntimeImpl`) |
+| `capture-model.ts` | Model capture (`captureModelImpl`) |
+| `bind-repo.ts` | Repo binding utilities (`bindRepoImpl`) |
+| `perf.ts` | Perf sample recording + interval (`ensurePerfIntervalImpl`, `disposePerf`) |
+| `helpers.ts` | Shared constants/types (`SessionRuntime`, `STATUS_KEY`, `WIDGET_KEY`, …) |
+| `query.ts` | Query helpers (`recentUserQuery`) |
+

package/extensions/mega-runtime/append-event.ts

@@ -0,0 +1,40 @@
+/**
+ * append-event.ts — extracted `MegaRuntime.appendEvent()`: the structured
+ * events.log diagnostics sink. Same context-interface + free-function +
+ * thin-delegate pattern as runtime-helpers.ts / effects.ts / game-state.ts.
+ */
+
+import { join } from "node:path";
+import { appendFileSync, mkdirSync } from "node:fs";
+
+// ---------------------------------------------------------------------- types
+
+/** The slice of `MegaRuntime` appendEvent reads (the bound repo's state dir). */
+export interface AppendEventContext {
+	readonly currentStateDir: string;
+}
+
+// ---------------------------------------------------------------- appendEvent
+
+/**
+ * Append a structured line to the repo's events.log — the always-on
+ * diagnostics sink the dashboard live-streams. Unlike the runtime logger
+ * (gated by config.debug), this fires in production, so capture failures
+ * surface during a real capture even with debugging off. Best-effort +
+ * non-fatal.
+ */
+export function appendEventImpl(
+	self: AppendEventContext,
+	event: string,
+	fields: Record<string, unknown>,
+): void {
+	try {
+		mkdirSync(self.currentStateDir, { recursive: true });
+		appendFileSync(
+			join(self.currentStateDir, "events.log"),
+			JSON.stringify({ ts: Date.now(), event, ...fields }) + "\n",
+		);
+	} catch {
+		/* non-fatal */
+	}
+}

package/extensions/mega-runtime/bind-repo.ts

@@ -0,0 +1,81 @@
+/**
+ * bind-repo.ts — extracted per-repo binding for MegaRuntime.
+ *
+ * Point store/dashboard/logger at the current repo's state dir. Rebuilds the
+ * instances only when the repo root changes, so cross-repo dedup stats, db,
+ * and events are fully isolated. Falls back to the global default outside git.
+ */
+
+import { join } from "node:path";
+import { VectorStore, vectorRepoStats, vectorDataInvariant } from "../../src/vectorStore.js";
+import { repoStateDir, resolveRepoRoot } from "../mega-config.js";
+import { upsertRepoRegistry } from "../../src/store/sqlite.js";
+import { Logger } from "../../src/log.js";
+import { Dashboard } from "../mega-dashboard.js";
+import type { MegaConfig } from "../mega-config.js";
+
+// ---------------------------------------------------------------------- types
+
+export interface BindRepoContext {
+	readonly config: MegaConfig;
+	activeRepoRoot: string | null;
+	currentStateDir: string;
+	store: VectorStore;
+	dashboard: Dashboard;
+	logger: Logger;
+	cachedGameState: import("../../src/store/sqlite.js").GameState | undefined;
+	gameStateBump: number;
+	ensureGameStateWatcher(): void;
+}
+
+// ------------------------------------------------------------------ bindRepo
+
+export function bindRepoImpl(ctx: BindRepoContext, cwd: string | undefined): string {
+	const dir = cwd
+		? repoStateDir(cwd, ctx.config.stateDir)
+		: ctx.config.stateDir;
+	const key = cwd ? (resolveRepoRoot(cwd) ?? dir) : dir;
+	if (key === ctx.activeRepoRoot) return dir;
+	ctx.activeRepoRoot = key;
+	ctx.currentStateDir = dir;
+	// S31 audit P2: bindRepo switched currentStateDir but left cachedGameState
+	// memoized -> the widget kept showing the previous repo's theme/mode/toggle
+	// until /mega-game or a restart. The game_state row is per-repo (per
+	// stateDir), so evict the memo on every repo switch; the next widget render
+	// re-queries lazily via getCachedGameState().
+	ctx.cachedGameState = undefined;
+	ctx.gameStateBump++;
+	// S32: re-target the fs.watch cache-eviction watcher at the NEW stateDir's
+	// sqlite.db so cross-process writes (dashboard server) still evict the memo.
+	ctx.ensureGameStateWatcher();
+	ctx.store = new VectorStore({
+		dedupSim: ctx.config.dedupSim,
+		stateDir: dir,
+	});
+	ctx.logger = new Logger({
+		enabled: ctx.config.debug,
+		path: join(dir, "mega-compact.log"),
+	});
+	ctx.dashboard = new Dashboard(dir);
+	// Aggregate this repo into the machine-wide index so the multi-repo
+	// dashboard (Summary / All-repos tabs) can show it alongside every other
+	// repo. Best-effort + non-fatal: a read-only index dir or contention must
+	// never break the per-repo compaction path. Runs only on repo-switch
+	// (this branch), so it's infrequent — not per-context-event.
+	try {
+		const repo = vectorRepoStats(ctx.store);
+		const di = vectorDataInvariant(ctx.store);
+		const root = key !== dir ? key : (resolveRepoRoot(cwd ?? dir) ?? dir);
+		upsertRepoRegistry({
+			repoRoot: root,
+			displayName: root.split(/[\\/]/).filter(Boolean).pop() ?? root,
+			stateDir: dir,
+			checkpointCount: repo.checkpointCount,
+			tokensSaved: repo.tokensSaved,
+			compressedOriginalBytes: di.compressedOriginalBytes,
+		});
+	} catch {
+		/* non-fatal: index aggregation must not block compaction */
+	}
+	return dir;
+}

package/extensions/mega-runtime/capture-model.ts

@@ -0,0 +1,101 @@
+/**
+ * capture-model.ts — extracted model-capture logic for MegaRuntime.
+ *
+ * Captures the active model/provider from ctx.model and persists it so cost
+ * estimation + the dashboard can read real pricing. Cheap + idempotent-ish:
+ * only writes a new row when the model id changes (models change rarely).
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveRepoRoot } from "../mega-config.js";
+import { recordModelSnapshot, recordRepoModel } from "../../src/store/sqlite.js";
+import type { ModelSnapshot } from "../../src/store/sqlite.js";
+
+// ---------------------------------------------------------------------- types
+
+export interface CaptureModelContext {
+	readonly currentStateDir: string;
+	currentModel: (ModelSnapshot & { capturedAt: number }) | null | undefined;
+	diagCaptureModelCalls: number;
+	diagCaptureModelFails: number;
+	appendEvent(event: string, fields: Record<string, unknown>): void;
+}
+
+// -------------------------------------------------------------- captureModel
+
+export function captureModelImpl(ctx: CaptureModelContext, ectx: ExtensionContext): void {
+	const m = ectx.model;
+	if (!m) {
+		ctx.appendEvent("captureModel:no-model", { cwd: ectx.cwd });
+		return;
+	}
+	if (
+		ctx.currentModel &&
+		ctx.currentModel.modelId === m.id &&
+		ctx.currentModel.provider === m.provider
+	)
+		return;
+	let providerName: string | null = null;
+	try {
+		providerName =
+			ectx.modelRegistry?.getProviderDisplayName(m.provider) ?? null;
+	} catch {
+		/* optional */
+	}
+	const snap: Omit<ModelSnapshot, "capturedAt"> = {
+		provider: m.provider,
+		providerName,
+		modelId: m.id,
+		modelName: m.name ?? null,
+		inputRate: m.cost?.input ?? 0,
+		outputRate: m.cost?.output ?? 0,
+		contextWindow: m.contextWindow ?? 0,
+		maxTokens: m.maxTokens ?? 0,
+		reasoning: !!m.reasoning,
+	};
+	ctx.currentModel = { ...snap, capturedAt: Date.now() };
+	ctx.diagCaptureModelCalls++;
+	const repo = resolveRepoRoot(ectx.cwd) ?? ctx.currentStateDir;
+	// S26: previously a single silent `catch {}` hid every capture failure, so
+	// model_snapshots stayed empty and the cost card read $0.00 with zero signal.
+	// Split per-write + append to events.log (always-on, dashboard live-streams
+	// it) + bump a DIAG counter so a live capture surfaces the root cause.
+	try {
+		recordModelSnapshot(repo, snap, ctx.currentStateDir);
+		ctx.appendEvent("captureModel:recorded", {
+			repo,
+			modelId: snap.modelId,
+			provider: snap.provider,
+			inputRate: snap.inputRate,
+			outputRate: snap.outputRate,
+		});
+	} catch (e) {
+		ctx.diagCaptureModelFails++;
+		ctx.appendEvent("captureModel:record-failed", {
+			repo,
+			modelId: snap.modelId,
+			error: e instanceof Error ? e.message : String(e),
+			stack: e instanceof Error ? e.stack : undefined,
+		});
+	}
+	try {
+		// Denormalize the active model into the machine-wide index so the
+		// All-repos dashboard table can show provider/model per repo without
+		// opening every repo's DB. Best-effort + non-fatal.
+		recordRepoModel(repo, {
+			provider: snap.provider,
+			providerName: snap.providerName,
+			modelName: snap.modelName,
+			inputRate: snap.inputRate,
+			outputRate: snap.outputRate,
+			stateDir: ctx.currentStateDir,
+			displayName: repo.split(/[\\/]/).filter(Boolean).pop() ?? repo,
+		});
+	} catch (e) {
+		ctx.appendEvent("captureModel:index-record-failed", {
+			repo,
+			modelId: snap.modelId,
+			error: e instanceof Error ? e.message : String(e),
+		});
+	}
+}