pi-mega-compact 0.9.0 → 0.9.2

package/README.md

@@ -61,6 +61,7 @@ Set env vars before starting pi. Defaults are in `src/config/dedup.ts`.
 | `MEGACOMPACT_DEDUP_SIM` | `0.90` | Cosine threshold for near-dup collapse |
 | `MEGACOMPACT_CROSSREPO_ENABLED` | `true` | Cross-repo recall on resume |
 | `MEGACOMPACT_EMBEDDING_URL` | _(unset)_ | BYO localhost embedder endpoint |
+| `MEGACOMPACT_TUI_WIDGET` | `true` | Render the above-editor panel. Set to `0` to suppress it — useful when pi runs inside an editor terminal (e.g. Neovim `:terminal`) where you drive scrollback yourself and the panel's repaints fight it. Compaction is unaffected. |
 
 Full config reference: [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md)
 

package/dist/extensions/mega-compact.js

@@ -25,6 +25,8 @@
  * This file is the thin wiring layer: it owns the default export, constructs
  * the runtime, and registers handlers/commands. Behavior is unchanged.
  */
+import { closeVectorIndex } from "../src/store/vectorIndex.js";
+import { closeMemoryIndex } from "../src/store/memoryIndex.js";
 import { loadConfig } from "./mega-config.js";
 import { MegaRuntime } from "./mega-runtime.js";
 import { registerEventHandlers } from "./mega-events.js";
@@ -79,5 +81,18 @@ export default function (pi) {
     // dispose() is idempotent, and the next snapshot() re-opens the watcher
     // lazily via bindRepo() → ensureGameStateWatcher(), so there is no permanent
     // leak and no per-session fd accumulation.
-    pi.on("session_shutdown", () => runtime.dispose());
+    // The PGlite indexes (vectorIndex / memoryIndex) are lazily opened module
+    // singletons. closeVectorIndex()/closeMemoryIndex() existed but had no
+    // non-test callers, so a session left both open: PGlite is WASM Postgres and
+    // its handles keep node's event loop alive, so `pi -p` produced its answer
+    // and then hung until killed rather than exiting. dispose() only released the
+    // fs.watch handle and the perf interval, neither of which was the culprit
+    // (the interval is unref'd).
+    //
+    // Both closes are idempotent and safe when the index was never opened, and
+    // the next initVectorIndex()/initMemoryIndex() re-opens lazily.
+    pi.on("session_shutdown", async () => {
+        runtime.dispose();
+        await Promise.all([closeVectorIndex(), closeMemoryIndex()]);
+    });
 }

package/dist/extensions/mega-config.js

@@ -160,6 +160,7 @@ export function loadConfig() {
         memoryReviewInterval: envFlag("MEGACOMPACT_MEMORY_REVIEW_INTERVAL", 10),
         recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
+        tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
         debug: envBool("MEGACOMPACT_DEBUG", false),
     };
 }

package/dist/extensions/mega-runtime/game-state.js

@@ -108,6 +108,13 @@ export function ensureGameStateWatcherImpl(self, view) {
                 }
             }
         });
+        // The watcher is a cache-eviction convenience, never a reason to stay
+        // alive: an active+referenced fs_event handle holds node's event loop
+        // open, so a runtime that was never dispose()d (every extension test, and
+        // any `pi -p` run that skips session_shutdown) hangs the process after all
+        // work is done. unref'd like the perf interval — while pi runs there are
+        // always other referenced handles, so the watcher still fires normally.
+        self.gameStateWatcher.unref?.();
         self.gameStateWatchDir = self.currentStateDir;
     }
     catch {

package/dist/extensions/mega-runtime/reset-runtime.js

@@ -32,6 +32,14 @@ export function resetRuntimeImpl(self, sessionId) {
         errorRetryCount: 0,
         errorRetryUntil: 0,
         consecutiveErrors: 0,
+        lastErrorRetryAt: 0,
+        retryNudgePending: false,
+        errorRetrySessionCount: 0,
+        lastErrorText: undefined,
+        errorTextRepeatCount: 0,
+        poisonedAdviseSent: false,
+        poisonedCompactSignatures: new Set(),
+        poisonedCount: 0,
     };
     self.trimCache = null; // v0.8.6: never replay a stale trim into a new session
     self.statusKey = undefined;

package/dist/extensions/mega-runtime/runtime.js

@@ -23,6 +23,7 @@ import { captureModelImpl } from "./capture-model.js";
 import { bindRepoImpl } from "./bind-repo.js";
 import { snapshotImpl } from "./runtime-snapshot.js";
 import { pressureImpl, effectiveThresholdImpl, pressureBandImpl, } from "./pressure-getters.js";
+import { resetRuntimeImpl } from "./reset-runtime.js";
 import { appendEventImpl } from "./append-event.js";
 import { getStateDirImpl } from "./get-state-dir.js";
 import { renderWidgetImpl } from "./render-widget.js";
@@ -56,7 +57,6 @@ export class MegaRuntime {
         errorRetryCount: 0,
         errorRetryUntil: 0,
         consecutiveErrors: 0,
-        // R1-R3 (retry redesign): in-flight dedup, session cap, poisoned-context state.
         lastErrorRetryAt: 0,
         retryNudgePending: false,
         errorRetrySessionCount: 0,
@@ -255,8 +255,15 @@ export class MegaRuntime {
         snapshotImpl(this, ctx);
     }
     /** Width-aware above-editor widget factory registration — thin delegate to
-     *  `renderWidgetImpl` (render-widget.ts). */
+     *  `renderWidgetImpl` (render-widget.ts).
+     *
+     *  Gated on `config.tuiWidget` (MEGACOMPACT_TUI_WIDGET=0 to disable). This
+     *  is the single chokepoint every caller funnels through, so returning here
+     *  means setWidget is never called and the panel is never registered — as
+     *  opposed to registering an empty one, which would still occupy a row. */
     renderWidget(ctx) {
+        if (!this.config.tuiWidget)
+            return;
         renderWidgetImpl(this, ctx);
     }
     /** Mirror the dashboard status text onto pi's status line — thin delegate to
@@ -264,55 +271,10 @@ export class MegaRuntime {
     setStatus(ctx, text) {
         setStatusImpl(this, ctx, text);
     }
-    /** Per-session state reset (session_start / session_tree) — inlined by the
-     *  raptor-promotion merge (R1–R3 retry-redesign fields); reset-runtime.ts was
-     *  retired by that branch. */
+    /** Per-session state reset (session_start / session_tree) — thin delegate to
+     *  `resetRuntimeImpl` (reset-runtime.ts). */
     resetRuntime(sessionId) {
-        const sid = normalizeSessionId(sessionId);
-        if (this.rt.sessionId === sid && this.rt.persistedThisSession)
-            return; // same session, keep checkpoint memory
-        this.rt = {
-            sessionId: sid,
-            persistedThisSession: false,
-            lastCheckpointId: undefined,
-            lastCompactedFrom: 0,
-            lastCompactedTokens: 0,
-            dedupSkips: 0,
-            dedupAttempts: 0,
-            tokensSaved: 0,
-            lastCompactAt: null,
-            lastNativeCompactAt: null,
-            compactCount: 0,
-            recallInjections: 0,
-            cacheHitTokens: 0,
-            lengthStopPending: false,
-            errorRetryCount: 0,
-            errorRetryUntil: 0,
-            consecutiveErrors: 0,
-            // R1-R3 (retry redesign): in-flight dedup, session cap, poisoned-context state.
-            lastErrorRetryAt: 0,
-            retryNudgePending: false,
-            errorRetrySessionCount: 0,
-            lastErrorText: undefined,
-            errorTextRepeatCount: 0,
-            poisonedAdviseSent: false,
-            poisonedCompactSignatures: new Set(),
-            poisonedCount: 0,
-        };
-        this.trimCache = null; // v0.8.6: never replay a stale trim into a new session
-        this.statusKey = undefined;
-        this.activeAgents = 0;
-        this.currentTurn = 0;
-        this.lastActivityAt = 0;
-        this.tierTrace = undefined;
-        this.ticker.length = 0;
-        this.pulsing = false;
-        this.savedGoal = 50_000;
-        this.lastWhy = undefined;
-        // S31 audit P2: symmetry with bindRepo — a reset can coincide with a context
-        // that re-binds the repo, so drop the memo too. Cheap; the next
-        // getCachedGameState() re-queries lazily.
-        this.cachedGameState = undefined;
+        resetRuntimeImpl(this, sessionId);
     }
     captureModel(ctx) {
         captureModelImpl(this, ctx);

package/dist/extensions/mega-shutdown-widget.test.js

@@ -0,0 +1,121 @@
+/**
+ * mega-shutdown-widget.test.ts — regression cover for two host-integration
+ * fixes that the rest of the suite cannot see, because both are about what
+ * happens at the boundary with pi rather than inside the compaction engine:
+ *
+ *  1. session_shutdown must close the PGlite indexes. They are lazily-opened
+ *     module singletons whose handles keep node's event loop alive, so leaving
+ *     them open made `pi -p` produce its answer and then hang instead of
+ *     exiting. closeVectorIndex()/closeMemoryIndex() existed but had no
+ *     non-test callers.
+ *
+ *  2. The above-editor widget must be suppressible. It is a persistent,
+ *     animated, full-width panel that repaints on its own cadence, which fights
+ *     terminals where the user drives scrollback (pi inside a Neovim
+ *     `:terminal`). MEGACOMPACT_TUI_WIDGET=0 turns it off without touching
+ *     compaction.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { closeVectorIndex, initVectorIndex, isVectorIndexDisabled, } from "../src/store/vectorIndex.js";
+import { closeMemoryIndex } from "../src/store/memoryIndex.js";
+import { loadConfig } from "./mega-config.js";
+import { MegaRuntime } from "./mega-runtime.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-shutdown-"));
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+let counter = 0;
+/** Fresh per-test state dir so concurrent runs never collide on disk. */
+function isolate() {
+    process.env.MEGACOMPACT_STATE_DIR = join(baseTmp, `run-${counter++}`);
+}
+/** Minimal ExtensionContext slice: renderWidget only reaches ctx.ui.setWidget. */
+function widgetCtx(calls) {
+    return {
+        ui: {
+            setWidget: (key) => calls.push(key),
+        },
+    };
+}
+test.after(async () => {
+    // This file is itself a demonstration of the bug under test: without these
+    // closes the PGlite handles opened above keep the event loop alive and the
+    // test process never exits.
+    await Promise.all([closeVectorIndex(), closeMemoryIndex()]);
+    rmSync(baseTmp, { recursive: true, force: true });
+});
+test("MEGACOMPACT_TUI_WIDGET defaults on and is disabled by 0", () => {
+    isolate();
+    delete process.env.MEGACOMPACT_TUI_WIDGET;
+    assert.equal(loadConfig().tuiWidget, true, "widget should default to on");
+    process.env.MEGACOMPACT_TUI_WIDGET = "0";
+    assert.equal(loadConfig().tuiWidget, false);
+    process.env.MEGACOMPACT_TUI_WIDGET = "1";
+    assert.equal(loadConfig().tuiWidget, true);
+    delete process.env.MEGACOMPACT_TUI_WIDGET;
+});
+test("renderWidget registers the panel when tuiWidget is on", () => {
+    isolate();
+    delete process.env.MEGACOMPACT_TUI_WIDGET;
+    const runtime = new MegaRuntime(loadConfig());
+    try {
+        const calls = [];
+        runtime.renderWidget(widgetCtx(calls));
+        assert.equal(calls.length, 1, "expected one setWidget registration");
+    }
+    finally {
+        runtime.dispose();
+    }
+});
+test("renderWidget registers nothing when tuiWidget is off", () => {
+    isolate();
+    process.env.MEGACOMPACT_TUI_WIDGET = "0";
+    const runtime = new MegaRuntime(loadConfig());
+    try {
+        const calls = [];
+        // Repeated calls, because the panel is re-registered on every snapshot
+        // and every game-state change — one guarded path is not enough.
+        runtime.renderWidget(widgetCtx(calls));
+        runtime.renderWidget(widgetCtx(calls));
+        assert.deepEqual(calls, [], "widget must never be registered when disabled");
+    }
+    finally {
+        runtime.dispose();
+        delete process.env.MEGACOMPACT_TUI_WIDGET;
+    }
+});
+test("the extension's session_shutdown handler awaits index teardown", async () => {
+    isolate();
+    const handlers = {};
+    const pi = {
+        on(event, handler) {
+            (handlers[event] ??= []).push(handler);
+        },
+        registerCommand() { },
+        registerProvider() { },
+    };
+    const { default: extension } = await import("./mega-compact.js");
+    extension(pi);
+    const shutdown = handlers["session_shutdown"] ?? [];
+    assert.ok(shutdown.length, "extension must register a session_shutdown handler");
+    const event = { type: "session_shutdown" };
+    const ctx = {
+        ui: { setStatus: () => { }, notify: () => { }, setWidget: () => { } },
+        cwd: process.env.MEGACOMPACT_STATE_DIR,
+    };
+    // Assert the close by identity rather than by "some handler returned a
+    // promise": several modules register on session_shutdown and at least one
+    // other is already async, so a promise proves nothing about teardown. The
+    // index is a module singleton, so if shutdown really closed it, re-init
+    // hands back a *different* instance.
+    const before = await initVectorIndex();
+    if (isVectorIndexDisabled() || !before)
+        return; // PGlite unavailable — nothing to close
+    await Promise.all(shutdown.map((handler) => handler(event, ctx)));
+    const after = await initVectorIndex();
+    assert.notEqual(after, before, "session_shutdown must close the PGlite vector index");
+    // Idempotent: a second shutdown (reload, double-fire) must not throw.
+    await Promise.all(shutdown.map((handler) => handler(event, ctx)));
+});

package/dist/src/compact.js

@@ -26,7 +26,7 @@ function firstText(m) {
 /** Heuristic: does this text look like chatty filler we can collapse? */
 export function isChatty(text) {
     const low = text.toLowerCase();
-    if (low.includes("hello") || low.includes("thanks") || low.includes("great") || low.includes("ok")) {
+    if (/\b(hello|thanks|great|ok)\b/i.test(low)) {
         return true;
     }
     return text.length < 40 && !/(\/|\.|\{|import |def |function )/.test(text);
@@ -141,7 +141,9 @@ export function summarizeMessages(messages) {
     const users = messages.filter((m) => m.role === "user").length;
     const assistants = messages.filter((m) => m.role === "assistant").length;
     const tools = messages.filter((m) => m.role === "tool").length;
-    const toolNames = [...new Set(messages.flatMap((m) => (m.toolName ? [m.toolName] : [])))].sort();
+    const toolNames = [
+        ...new Set(messages.flatMap((m) => (m.toolName ? [m.toolName] : []))),
+    ].sort();
     const lines = [
         "<summary>",
         "Conversation summary:",

package/dist/src/memoryOps.test.js

@@ -1,3 +1,18 @@
+// This file exercises the sync node:sqlite memory ops only, but every
+// applyMemoryOps() write also fires indexMemoryWrite() → upsertMemoryEmbedding()
+// at the machine-wide PGlite index, fire-and-forget, keyed by repoKey(stateDir)
+// — which for these tmp state dirs is the tmp path itself. Left alone that lands
+// in the developer's real ~/.pi/mega-compact-vector, where the rows stay
+// eligible for cross-repo recall forever: a live session can be handed
+// "threshold is 50k" and "the threshold is 100k" from this file as if they were
+// another project's memories. scripts/run-tests.mjs sets MEGACOMPACT_INDEX_DIR
+// per child, so the suite was already safe; running the file directly was not.
+//
+// Disabling PGlite is the same guard memoryRoundtrip.test.ts uses for the same
+// reason, and it also keeps the file's exit clean (no WASM handle, and no
+// initdb still running when the first test ends). MEGACOMPACT_INDEX_DIR is set
+// as well so the isolation holds if a later test needs the index re-enabled.
+process.env.MEGACOMPACT_PGLITE_DISABLED = "true";
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, rmSync } from "node:fs";
@@ -6,6 +21,7 @@ import { join } from "node:path";
 import { applyMemoryOps } from "./memoryOps.js";
 import { addMemory, listMemories, replaceMemory, referenceMemory, MEMORY_MAX_CHARS, } from "./store/sqlite.js";
 const baseTmp = mkdtempSync(join(tmpdir(), "mc-memops-"));
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
 test("applyMemoryOps: ADD inserts a new memory", async () => {
     const dir = join(baseTmp, "add");
     await applyMemoryOps([{ op: "add", memory: { content: "we use node:sqlite as the store", category: "decision", sourceTurn: 0 } }], dir);

package/dist/src/store/memoryIndex.js

@@ -24,6 +24,7 @@ import { join } from "node:path";
 import { mkdirSync, rmSync, existsSync } from "node:fs";
 /** Vector dimension produced by the default TrigramEmbedder (src/embedder.ts). */
 export const MEMORY_INDEX_DIM = 512;
+import { withOpenTimeout } from "./pgOpenGuard.js";
 let db;
 let initPromise;
 let disabled = false;
@@ -110,12 +111,18 @@ async function openPgLite(retryOnCorrupt) {
             return undefined;
         const dir = indexDir();
         mkdirSync(dir, { recursive: true });
-        const pg = await new mod.PGlite({
-            dataDir: dir,
-            extensions: { vector: mod.vector },
-        });
-        await pg.exec("CREATE EXTENSION IF NOT EXISTS vector;");
-        await pg.exec(`
+        // Bounded open: PGlite is single-writer over a shared dataDir, so a second
+        // pi process on the same dir can block here forever. Without the ceiling the
+        // never-settling promise gets cached in initPromise and every later caller
+        // awaits it — which is how a stalled index wedged a whole pi turn.
+        let openTimedOut = false;
+        const pg = await withOpenTimeout((async () => {
+            const inst = await new mod.PGlite({
+                dataDir: dir,
+                extensions: { vector: mod.vector },
+            });
+            await inst.exec("CREATE EXTENSION IF NOT EXISTS vector;");
+            await inst.exec(`
       CREATE TABLE IF NOT EXISTS memory_index (
         repo_id    TEXT NOT NULL,
         memory_id  INTEGER NOT NULL,
@@ -124,7 +131,22 @@ async function openPgLite(retryOnCorrupt) {
         PRIMARY KEY (repo_id, memory_id)
       );
     `);
-        await pg.exec("CREATE INDEX IF NOT EXISTS memory_index_hnsw ON memory_index USING hnsw (embedding vector_cosine_ops);");
+            await inst.exec("CREATE INDEX IF NOT EXISTS memory_index_hnsw ON memory_index USING hnsw (embedding vector_cosine_ops);");
+            return inst;
+        })(), (reason) => {
+            openTimedOut = true;
+            logWarn(`init ${reason}`);
+        });
+        if (!pg) {
+            if (openTimedOut) {
+                // Don't leave the dead open cached, and don't retry on the next call —
+                // a contended dataDir would just burn another full timeout per caller.
+                // Same terminal state as any other init failure: fall back to the scan.
+                initPromise = undefined;
+                disabled = true;
+            }
+            return undefined;
+        }
         db = pg;
         return pg;
     }

package/dist/src/store/pgOpenGuard.js

@@ -0,0 +1,83 @@
+/**
+ * pgOpenGuard.ts — bound the PGlite open so a stalled WASM init can never wedge
+ * a pi turn.
+ *
+ * Both index modules (vectorIndex / memoryIndex) cache their in-flight open in a
+ * module-level `initPromise`. That cache is what turns a single stalled open
+ * into a permanent hang: PGlite is a single-writer WASM Postgres over a shared
+ * dataDir (~/.pi/mega-compact-vector), so a second pi process opening the same
+ * dir can block indefinitely. `await new PGlite(...)` then never settles, the
+ * never-settling promise is cached, and every later caller awaits that same dead
+ * promise — with no timers and no sockets left, node reports
+ * "Promise resolution is still pending but the event loop has already resolved"
+ * and the pi turn that awaited it never ends.
+ *
+ * withOpenTimeout() puts a ceiling on that wait. On timeout the caller gets
+ * undefined (both modules already degrade to a synchronous scan), and the
+ * abandoned open is disowned: if it does eventually settle, the instance is
+ * closed so a stray PGlite can't keep the loop alive or hold the dataDir lock.
+ *
+ * A rejected open is NOT swallowed — it propagates so the callers' existing
+ * corrupt-dir detection (Aborted / RuntimeError → wipe + one retry) still runs.
+ * Only the timeout resolves to undefined.
+ */
+/** Sentinel so a legitimately-undefined open is distinguishable from a timeout. */
+const TIMED_OUT = Symbol("pglite-open-timeout");
+/** Default ceiling for a PGlite open. Generous — a cold WASM + HNSW init is slow. */
+export const DEFAULT_PG_OPEN_TIMEOUT_MS = 30_000;
+/** Resolve the open timeout. 0 (or negative) disables the guard entirely. */
+export function pgOpenTimeoutMs() {
+    const raw = process.env.MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_PG_OPEN_TIMEOUT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_PG_OPEN_TIMEOUT_MS;
+    return n;
+}
+/**
+ * Race `open` against the configured timeout.
+ *
+ * Resolves to the opened value, or to undefined when the open outruns the
+ * timeout (`onTimeout` fires first so the caller can log and flip its own
+ * disabled state). Rejections propagate to the caller unchanged.
+ */
+export async function withOpenTimeout(open, onTimeout, timeoutMs = pgOpenTimeoutMs()) {
+    // Guard disabled — preserve the original unbounded behavior verbatim.
+    if (timeoutMs <= 0)
+        return open;
+    let timer;
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+        // Never hold the process open on account of the guard itself.
+        timer.unref?.();
+    });
+    try {
+        // `open` is raced as-is so a rejection rejects the race — and therefore
+        // this function — leaving the caller's corrupt-retry path intact.
+        const winner = await Promise.race([open, expiry]);
+        if (winner === TIMED_OUT) {
+            // Disown the open. If it ever settles, close the instance so an orphaned
+            // PGlite cannot keep the event loop alive or hold the dataDir lock.
+            void open
+                .then((late) => {
+                try {
+                    void late?.close?.();
+                }
+                catch {
+                    /* ignore */
+                }
+            })
+                .catch(() => {
+                /* the abandoned open failed on its own — nothing left to release */
+            });
+            onTimeout(`timed out after ${timeoutMs}ms`);
+            return undefined;
+        }
+        return winner;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/src/store/pgOpenGuard.test.js

@@ -0,0 +1,74 @@
+/**
+ * pgOpenGuard.test.ts — the PGlite open must never hang a turn.
+ *
+ * Regression cover for the wedge: a stalled `await new PGlite(...)` was cached
+ * in initPromise, so every later caller awaited a promise that could not settle
+ * and the pi turn awaiting it never ended.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { withOpenTimeout, pgOpenTimeoutMs, DEFAULT_PG_OPEN_TIMEOUT_MS } from "./pgOpenGuard.js";
+test("a never-settling open resolves to undefined instead of hanging", async () => {
+    const never = new Promise(() => {
+        /* deliberately never settles — the wedge */
+    });
+    const reasons = [];
+    const t0 = Date.now();
+    const result = await withOpenTimeout(never, (r) => reasons.push(r), 50);
+    assert.equal(result, undefined, "caller gets undefined and can fall back");
+    assert.ok(Date.now() - t0 < 5_000, "returned promptly rather than hanging");
+    assert.equal(reasons.length, 1, "onTimeout fired exactly once");
+    assert.match(reasons[0], /timed out after 50ms/);
+});
+test("a successful open passes its value through untouched", async () => {
+    const reasons = [];
+    const result = await withOpenTimeout(Promise.resolve("pg"), (r) => reasons.push(r), 5_000);
+    assert.equal(result, "pg");
+    assert.deepEqual(reasons, [], "no timeout reported on the happy path");
+});
+test("a rejected open propagates so the corrupt-dir retry still runs", async () => {
+    const reasons = [];
+    await assert.rejects(() => withOpenTimeout(Promise.reject(new Error("Aborted()")), (r) => reasons.push(r), 5_000), /Aborted/, "rejection reaches the caller's catch, which owns the wipe-and-retry path");
+    assert.deepEqual(reasons, [], "a rejection is not reported as a timeout");
+});
+test("an abandoned open is closed if it settles after the timeout", async () => {
+    let closed = false;
+    let release = () => { };
+    const late = new Promise((r) => {
+        release = r;
+    });
+    const result = await withOpenTimeout(late, () => { }, 25);
+    assert.equal(result, undefined, "timed out first");
+    // The open finally completes, long after we stopped waiting for it.
+    release({
+        close: () => {
+            closed = true;
+        },
+    });
+    await late;
+    await new Promise((r) => setImmediate(r));
+    assert.ok(closed, "the orphaned instance was closed, not left holding the dataDir");
+});
+test("timeout of 0 disables the guard (unbounded, original behavior)", async () => {
+    const result = await withOpenTimeout(Promise.resolve("pg"), () => { }, 0);
+    assert.equal(result, "pg");
+});
+test("pgOpenTimeoutMs honors the env override and rejects junk", async () => {
+    const prev = process.env.MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS;
+    try {
+        process.env.MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS = "1234";
+        assert.equal(pgOpenTimeoutMs(), 1234);
+        process.env.MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS = "0";
+        assert.equal(pgOpenTimeoutMs(), 0, "0 is a valid opt-out, not junk");
+        for (const junk of ["", "   ", "abc", "-5"]) {
+            process.env.MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS = junk;
+            assert.equal(pgOpenTimeoutMs(), DEFAULT_PG_OPEN_TIMEOUT_MS, `junk "${junk}" falls back`);
+        }
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS;
+        else
+            process.env.MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS = prev;
+    }
+});

package/dist/src/store/vectorIndex.js

@@ -20,6 +20,7 @@ import { join } from "node:path";
 import { mkdirSync, rmSync, existsSync } from "node:fs";
 /** Vector dimension produced by the default TrigramEmbedder (src/embedder.ts). */
 export const EMBEDDING_DIM = 512;
+import { withOpenTimeout } from "./pgOpenGuard.js";
 let db;
 let initPromise;
 let disabled = false;
@@ -107,12 +108,18 @@ async function openPgLite(retryOnCorrupt) {
             return undefined;
         const dir = indexDir();
         mkdirSync(dir, { recursive: true });
-        const pg = await new mod.PGlite({
-            dataDir: dir,
-            extensions: { vector: mod.vector },
-        });
-        await pg.exec("CREATE EXTENSION IF NOT EXISTS vector;");
-        await pg.exec(`
+        // Bounded open: PGlite is single-writer over a shared dataDir, so a second
+        // pi process on the same dir can block here forever. Without the ceiling the
+        // never-settling promise gets cached in initPromise and every later caller
+        // awaits it — which is how a stalled index wedged a whole pi turn.
+        let openTimedOut = false;
+        const pg = await withOpenTimeout((async () => {
+            const inst = await new mod.PGlite({
+                dataDir: dir,
+                extensions: { vector: mod.vector },
+            });
+            await inst.exec("CREATE EXTENSION IF NOT EXISTS vector;");
+            await inst.exec(`
       CREATE TABLE IF NOT EXISTS vector_index (
         repo_id       TEXT NOT NULL,
         session_id    TEXT NOT NULL,
@@ -121,8 +128,23 @@ async function openPgLite(retryOnCorrupt) {
         PRIMARY KEY (repo_id, session_id, checkpoint_id)
       );
     `);
-        // HNSW index over cosine distance for fast NN. Created idempotently.
-        await pg.exec("CREATE INDEX IF NOT EXISTS vector_index_hnsw ON vector_index USING hnsw (embedding vector_cosine_ops);");
+            // HNSW index over cosine distance for fast NN. Created idempotently.
+            await inst.exec("CREATE INDEX IF NOT EXISTS vector_index_hnsw ON vector_index USING hnsw (embedding vector_cosine_ops);");
+            return inst;
+        })(), (reason) => {
+            openTimedOut = true;
+            logWarn(`init ${reason}`);
+        });
+        if (!pg) {
+            if (openTimedOut) {
+                // Don't leave the dead open cached, and don't retry on the next call —
+                // a contended dataDir would just burn another full timeout per caller.
+                // Same terminal state as any other init failure: fall back to the scan.
+                initPromise = undefined;
+                disabled = true;
+            }
+            return undefined;
+        }
         db = pg;
         return pg;
     }

package/extensions/mega-compact.ts

@@ -27,6 +27,8 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { closeVectorIndex } from "../src/store/vectorIndex.js";
+import { closeMemoryIndex } from "../src/store/memoryIndex.js";
 import { loadConfig } from "./mega-config.js";
 import { MegaRuntime } from "./mega-runtime.js";
 import { registerEventHandlers } from "./mega-events.js";
@@ -82,5 +84,18 @@ export default function (pi: ExtensionAPI) {
   // dispose() is idempotent, and the next snapshot() re-opens the watcher
   // lazily via bindRepo() → ensureGameStateWatcher(), so there is no permanent
   // leak and no per-session fd accumulation.
-  pi.on("session_shutdown", () => runtime.dispose());
+  // The PGlite indexes (vectorIndex / memoryIndex) are lazily opened module
+  // singletons. closeVectorIndex()/closeMemoryIndex() existed but had no
+  // non-test callers, so a session left both open: PGlite is WASM Postgres and
+  // its handles keep node's event loop alive, so `pi -p` produced its answer
+  // and then hung until killed rather than exiting. dispose() only released the
+  // fs.watch handle and the perf interval, neither of which was the culprit
+  // (the interval is unref'd).
+  //
+  // Both closes are idempotent and safe when the index was never opened, and
+  // the next initVectorIndex()/initMemoryIndex() re-opens lazily.
+  pi.on("session_shutdown", async () => {
+    runtime.dispose();
+    await Promise.all([closeVectorIndex(), closeMemoryIndex()]);
+  });
 }