pi-mega-compact 0.4.14 → 0.4.16

package/dist/extensions/mega-compact.test.js

@@ -192,6 +192,34 @@ test("/megacompact-status reports live store stats", async () => {
     await h.commands["mega-status"].handler("", ctx);
     assert.ok(h.notifies.some((n) => n.includes("store:") && n.includes("chkpt")), "status shows checkpoint count");
 });
+// ---- Model/provider capture (Phase 5b model_snapshots) ----------------------
+test("model_select captures model + provider into SQL", async () => {
+    const h = harness();
+    const modelCtx = h.ctx({
+        model: { id: "claude-opus-4-8", name: "Claude Opus 4.8", provider: "anthropic", contextWindow: 200000, maxTokens: 32000, reasoning: false, cost: { input: 0.000015, output: 0.000075 } },
+        modelRegistry: { getProviderDisplayName: (p) => (p === "anthropic" ? "Anthropic" : p) },
+    });
+    await h.fire("model_select", {}, modelCtx);
+    const { latestModelSnapshot } = await import("../src/store/sqlite.js");
+    const snap = latestModelSnapshot(h.stateDir);
+    assert.ok(snap, "model_snapshots row persisted");
+    assert.equal(snap.modelId, "claude-opus-4-8", "correct model id captured");
+    assert.equal(snap.provider, "anthropic", "correct provider captured");
+    assert.equal(snap.providerName, "Anthropic", "provider display name resolved");
+    assert.equal(snap.inputRate, 0.000015, "input rate captured");
+});
+test("/mega-status surfaces the captured model + provider", async () => {
+    const h = harness();
+    const modelCtx = h.ctx({
+        model: { id: "claude-opus-4-8", name: "Claude Opus 4.8", provider: "anthropic", contextWindow: 200000, maxTokens: 32000, reasoning: false, cost: { input: 0.000015, output: 0.000075 } },
+        modelRegistry: { getProviderDisplayName: () => "Anthropic" },
+    });
+    await h.fire("model_select", {}, modelCtx);
+    await h.fire("context", { type: "context", messages: h.session }, h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) }));
+    const ctx = h.ctx({ getContextUsage: () => ({ tokens: 50000, contextWindow: 200000, percent: 25 }) });
+    await h.commands["mega-status"].handler("", ctx);
+    assert.ok(h.notifies.some((n) => n.includes("🤖 model:") && n.includes("Claude Opus 4.8") && n.includes("Anthropic")), "status surfaces captured model + provider");
+});
 // ---- Named compaction tiers -------------------------------------------------
 // low=50k, medium=100k, high=200k, ultra=1M, mega=10M. Driven through the REAL
 // loadConfig()/status path by setting MEGACOMPACT_TIER before loading the ext.

package/dist/extensions/mega-config.js

@@ -0,0 +1,100 @@
+/**
+ * mega-config.ts — extension config: named compaction tiers, env helpers,
+ * config resolution, and per-repo state-dir scoping.
+ *
+ * Pure/standalone: depends only on node built-ins + src/config. No shared
+ * closure state, so it can be imported by the runtime, commands, and events
+ * modules without a cycle.
+ */
+import { STATE_DIR_DEFAULT } from "../src/config.js";
+import { join } from "node:path";
+import { execSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: read-only `git rev-parse` to scope the store per-repo
+/**
+ * Named compaction tiers. A tier sets the token threshold at which the
+ * auto-trigger persists a checkpoint; pick by how aggressively you want the
+ * session trimmed. Explicit MEGACOMPACT_THRESHOLD_TOKENS always wins.
+ */
+export const COMPACT_TIERS = {
+    low: 50_000,
+    medium: 100_000,
+    high: 200_000,
+    ultra: 1_000_000,
+    mega: 10_000_000,
+};
+function envFlag(name, fallback) {
+    const v = process.env[name];
+    if (v == null || v === "")
+        return fallback;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : fallback;
+}
+function envBool(name, fallback) {
+    const v = process.env[name];
+    if (v == null || v === "")
+        return fallback;
+    return v === "true" || v === "1";
+}
+/** Resolve the effective token threshold from TIER (or explicit) env vars. */
+function resolveThreshold() {
+    const explicit = process.env.MEGACOMPACT_THRESHOLD_TOKENS;
+    if (explicit != null && explicit !== "") {
+        const n = Number(explicit);
+        if (Number.isFinite(n))
+            return { tier: "custom", thresholdTokens: n };
+    }
+    const raw = (process.env.MEGACOMPACT_TIER ?? "low").toLowerCase();
+    const tier = (raw in COMPACT_TIERS ? raw : "low");
+    return { tier, thresholdTokens: COMPACT_TIERS[tier] };
+}
+/** Build the resolved config from env + defaults. */
+export function loadConfig() {
+    const { tier, thresholdTokens } = resolveThreshold();
+    return {
+        tier,
+        // Global default; the live store/dashboard are rebound per-repo at runtime
+        // via MegaRuntime.bindRepo() so each git repo gets its own isolated state dir.
+        stateDir: process.env.MEGACOMPACT_STATE_DIR ?? STATE_DIR_DEFAULT,
+        fastGatePct: envFlag("MEGACOMPACT_FAST_GATE_PCT", 70),
+        thresholdTokens,
+        anchorUserMessages: envFlag("MEGACOMPACT_ANCHOR_USER_MESSAGES", 3),
+        preserveRecent: envFlag("MEGACOMPACT_PRESERVE_RECENT", 4),
+        auto: envBool("MEGACOMPACT_AUTO", true),
+        autoInline: envBool("MEGACOMPACT_AUTO_INLINE", true),
+        autoInlineK: envFlag("MEGACOMPACT_AUTO_INLINE_K", 3),
+        dedupSim: Number(process.env.MEGACOMPACT_DEDUP_SIM ?? "0.9"),
+        debug: envBool("MEGACOMPACT_DEBUG", false),
+    };
+}
+/** Mutate tier + threshold in place (used by /mega-tier at runtime). */
+export function setTier(config, tier) {
+    config.tier = tier;
+    config.thresholdTokens = COMPACT_TIERS[tier];
+}
+/**
+ * Resolve the current repo's git root from a cwd. Returns undefined for a
+ * non-git directory (caller falls back to a global state dir).
+ */
+export function resolveRepoRoot(cwd) {
+    try {
+        const out = execSync("git rev-parse --show-toplevel", {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return out || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Per-repo state dir: <repo>/.pi/mega-compact (tracked, so it travels with the
+ * repo across devices — not gitignored). Falls back to `fallback` for non-git
+ * cwds (the explicit MEGACOMPACT_STATE_DIR override, if set).
+ */
+export function repoStateDir(cwd, fallback) {
+    const root = resolveRepoRoot(cwd);
+    if (!root)
+        return fallback;
+    return join(root, ".pi", "mega-compact");
+}

package/dist/extensions/mega-dashboard-cmds.js

@@ -0,0 +1,214 @@
+/**
+ * mega-dashboard-cmds.ts — the local web-dashboard slash commands.
+ *
+ * Spawns / discovers / stops the optional localhost dashboard server
+ * (extensions/dashboard-server.ts) as a detached child process. All network
+ * usage here is loopback-only and audited via // guardrails-allow PREVENT-PI-004.
+ */
+import { join, dirname, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { spawn } from "node:child_process"; // guardrails-allow PREVENT-PI-004: spawns the optional, user-triggered localhost dashboard server only
+/** Register the dashboard server lifecycle commands. */
+export function registerDashboardCommands(pi, runtime) {
+    const portFile = join(runtime.currentStateDir, "port.pid");
+    const runnerFile = join(runtime.currentStateDir, "_dashboard-runner.mjs");
+    const launchLog = join(runtime.currentStateDir, "_dashboard-launch.log");
+    // Whether the runner must be spawned with --experimental-strip-types (true only
+    // when we fall back to the .ts source outside node_modules; false when using
+    // the shipped compiled dist/extensions/dashboard-server.js).
+    let dashboardNeedsStrip = false;
+    // The dashboard server binds 9320–9329 (TARGET_PORT..TARGET_PORT+PORT_RANGE-1
+    // in dashboard-server.js). Probe each for a live /api/snapshot so we can detect
+    // readiness even when port.pid landed in a different state dir than we poll.
+    async function findLivePort() {
+        for (let port = 9320; port <= 9329; port++) {
+            try {
+                const res = await fetch(`http://localhost:${port}/api/snapshot`, { signal: AbortSignal.timeout(800) }); // guardrails-allow PREVENT-PI-004: localhost liveness probe of the dashboard server this extension spawned
+                if (res.ok)
+                    return port;
+            }
+            catch { /* not on this port — try next */ }
+        }
+        return null;
+    }
+    /** Try to reach a running dashboard server. Returns { port, url } or null. */
+    async function isServerRunning() {
+        const port = await findLivePort();
+        if (!port) {
+            // Stale marker with no live server behind it — clean up.
+            if (existsSync(portFile)) {
+                try {
+                    unlinkSync(portFile);
+                }
+                catch { /* ignore */ }
+            }
+            return null;
+        }
+        return { port, url: `http://localhost:${port}` }; // guardrails-allow PREVENT-PI-004: localhost URL of the dashboard server this extension spawned
+    }
+    /**
+     * Resolve the launchable dashboard-server module.
+     *
+     * CRITICAL: Node's `--experimental-strip-types` REFUSES to strip .ts files that
+     * live under `node_modules` (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). Since
+     * the published package installs under node_modules, importing the .ts source
+     * fails in every real install (it only worked from a source checkout). So we
+     * prefer the COMPILED dist/extensions/dashboard-server.js (which the package
+     * ships from v0.4.6 — it imports only Node built-ins, so it runs standalone),
+     * and only fall back to the .ts source (with strip-types) when the compiled
+     * file is absent AND we're not under node_modules (dev checkout without a build).
+     *
+     * Returns { entry, needsStripTypes }.
+     */
+    function resolveDashboardEntry() {
+        const here = dirname(fileURLToPath(import.meta.url)); // .../extensions
+        const candidates = [
+            // 1. Compiled sibling when running from dist/ (import.meta is dist/extensions/…js)
+            { entry: join(here, "dashboard-server.js"), strip: false },
+            // 2. Compiled under the package's dist/ when running from source extensions/…ts
+            { entry: join(here, "..", "dist", "extensions", "dashboard-server.js"), strip: false },
+            // 3. Last resort: the .ts source (only strippable OUTSIDE node_modules)
+            { entry: join(here, "dashboard-server.ts"), strip: true },
+        ];
+        for (const c of candidates) {
+            if (!existsSync(c.entry))
+                continue;
+            if (c.strip && c.entry.includes(`${sep}node_modules${sep}`))
+                continue; // unstrippable
+            return { entry: c.entry, needsStripTypes: c.strip };
+        }
+        return null;
+    }
+    /** Write a small ESM runner script that imports and launches the dashboard server. */
+    function writeRunnerScript() {
+        const resolved = resolveDashboardEntry();
+        if (!resolved)
+            return false;
+        dashboardNeedsStrip = resolved.needsStripTypes;
+        const script = [
+            `import { appendFileSync } from "node:fs";`,
+            `const __log = ${JSON.stringify(launchLog)};`,
+            `function __fail(err) {`,
+            `  const msg = "[mega-compact] dashboard failed: " + (err && err.stack ? err.stack : String(err));`,
+            `  try { appendFileSync(__log, msg + "\\n"); } catch { /* ignore */ }`,
+            `  console.error(msg);`,
+            `  process.exit(1);`,
+            `}`,
+            `import { launchDashboardServer } from ${JSON.stringify(resolved.entry)};`,
+            `launchDashboardServer(${JSON.stringify(runtime.currentStateDir)}).catch(__fail);`,
+        ].join("\n");
+        writeFileSync(runnerFile, script);
+        return true;
+    }
+    /** Open a URL in the default browser. Platform-aware. Uses spawn (not exec) to avoid shell injection. */
+    function openBrowser(url) {
+        const cmd = process.platform === "darwin" ? "open" :
+            process.platform === "win32" ? "start" :
+                "xdg-open";
+        try {
+            spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+        }
+        catch {
+            /* non-fatal — user can open manually */
+        }
+    }
+    pi.registerCommand("mega-dashboard", {
+        description: "Start the local web dashboard and optionally open it in the default browser.",
+        handler: async (_args, ctx) => {
+            runtime.bindRepo(ctx.cwd);
+            let info = await isServerRunning();
+            if (info) {
+                ctx.ui.notify(`[mega-compact] dashboard already running at ${info.url}`);
+                const open = await ctx.ui.confirm("mega-compact dashboard", `Open ${info.url} in browser?`);
+                if (open)
+                    openBrowser(info.url);
+                return;
+            }
+            // Start the server
+            ctx.ui.notify("[mega-compact] starting dashboard server…");
+            if (!writeRunnerScript()) {
+                ctx.ui.notify("[mega-compact] dashboard entry not found — check logs.");
+                return;
+            }
+            const args = dashboardNeedsStrip ? ["--experimental-strip-types", runnerFile] : [runnerFile];
+            const child = spawn(process.execPath, args, {
+                detached: true,
+                stdio: "ignore",
+            });
+            child.unref();
+            // Poll for a live server (port 9320–9329) instead of relying solely on the
+            // port.pid marker, which can land in a different state dir than the one we
+            // poll when a prior compact left currentStateDir pointing elsewhere.
+            const deadline = Date.now() + 6_000;
+            let port = null;
+            while (Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 300));
+                port = await findLivePort();
+                if (port)
+                    break;
+            }
+            if (!port) {
+                let detail = "";
+                try {
+                    const log = readFileSync(launchLog, "utf-8").trim();
+                    if (log)
+                        detail = ` — ${log.split("\n").slice(-3).join("; ")}`;
+                }
+                catch { /* no log yet */ }
+                ctx.ui.notify(`[mega-compact] dashboard server failed to start${detail}. See ${launchLog}`);
+                return;
+            }
+            const url = `http://localhost:${port}`; // guardrails-allow PREVENT-PI-004: localhost URL of the dashboard server this extension spawned
+            ctx.ui.notify(`[mega-compact] dashboard running at ${url}`);
+            const open = await ctx.ui.confirm("mega-compact dashboard", `Open ${url} in browser?`);
+            if (open)
+                openBrowser(url);
+        },
+    });
+    pi.registerCommand("mega-dashboard-stop", {
+        description: "Stop the local dashboard server.",
+        handler: async (_args, ctx) => {
+            if (!existsSync(portFile)) {
+                ctx.ui.notify("[mega-compact] no dashboard server running.");
+                return;
+            }
+            try {
+                const info = JSON.parse(readFileSync(portFile, "utf-8"));
+                // Verify the server is actually ours by probing the port before killing
+                try {
+                    await fetch(`http://localhost:${info.port}/api/snapshot`, { signal: AbortSignal.timeout(1000) }); // guardrails-allow PREVENT-PI-004: localhost probe to verify the dashboard server is ours before stopping it
+                }
+                catch {
+                    // Not responding — just clean up stale pid file
+                    try {
+                        unlinkSync(portFile);
+                    }
+                    catch { /* ok */ }
+                    ctx.ui.notify("[mega-compact] dashboard was not running (stale pid file cleaned up).");
+                    return;
+                }
+                if (info?.pid)
+                    process.kill(info.pid, "SIGTERM");
+            }
+            catch { /* already dead */ }
+            try {
+                unlinkSync(portFile);
+            }
+            catch { /* ok */ }
+            ctx.ui.notify("[mega-compact] dashboard stopped.");
+        },
+    });
+    pi.registerCommand("mega-dashboard-status", {
+        description: "Check if the dashboard server is running.",
+        handler: async (_args, ctx) => {
+            const info = await isServerRunning();
+            if (info) {
+                ctx.ui.notify(`[mega-compact] dashboard running at ${info.url}`);
+            }
+            else {
+                ctx.ui.notify("[mega-compact] dashboard is not running. Use /dashboard to start it.");
+            }
+        },
+    });
+}

package/dist/extensions/mega-dashboard.js

@@ -0,0 +1,35 @@
+/**
+ * mega-dashboard.ts — live dashboard snapshot writer.
+ *
+ * Writes dashboard.json (full snapshot) and events.log (JSONL tail) to the
+ * state dir so any process can inspect the extension's real-time state.
+ *
+ * Usage:
+ *   cat ~/.pi/agent/extensions/pi-mega-compact/dashboard.json
+ *   jq . ~/.pi/agent/extensions/pi-mega-compact/dashboard.json
+ *   tail -f ~/.pi/agent/extensions/pi-mega-compact/events.log
+ *
+ * Standalone: the snapshot *shape* is filled in by MegaRuntime.snapshot();
+ * this module only owns the on-disk write/append mechanics.
+ */
+import { join } from "node:path";
+import { existsSync, mkdirSync, writeFileSync, appendFileSync } from "node:fs";
+export class Dashboard {
+    snapshotPath;
+    eventsPath;
+    constructor(stateDir) {
+        if (!existsSync(stateDir))
+            mkdirSync(stateDir, { recursive: true });
+        this.snapshotPath = join(stateDir, "dashboard.json");
+        this.eventsPath = join(stateDir, "events.log");
+    }
+    /** Write a full state snapshot (atomically replaces previous). */
+    snapshot(data) {
+        writeFileSync(this.snapshotPath, JSON.stringify(data, null, 2) + "\n");
+    }
+    /** Append a timestamped JSONL event line. */
+    event(type, data) {
+        const line = JSON.stringify({ ts: new Date().toISOString(), type, ...data });
+        appendFileSync(this.eventsPath, line + "\n");
+    }
+}

package/dist/extensions/mega-events.js

@@ -0,0 +1,167 @@
+/**
+ * mega-events.ts — the pi lifecycle event handlers.
+ *
+ * Wires every pi event the extension listens for: model/provider capture,
+ * session lifecycle + state reset, auto-inline injection, agent/turn tracking,
+ * and the auto-trigger compaction pipeline. Keeps the shared MegaRuntime in
+ * sync and delegates the heavy lifting to the pipeline + command modules.
+ */
+import { normalizeSessionId } from "../src/store.js";
+import { autoCompactCheck } from "../src/compact.js";
+import { estimateSessionTokens } from "../src/tokens.js";
+import { dropCompactedRange } from "../src/adapt.js";
+import { recentUserQuery, WIDGET_KEY } from "./mega-runtime.js";
+import { runCompact, doRecall } from "./mega-pipeline.js";
+/** Register all pi lifecycle event handlers. */
+export function registerEventHandlers(pi, runtime, config) {
+    // ---- Session lifecycle (state reset points) -------------------------------
+    // Capture model/provider whenever it changes (drives real cost estimation).
+    pi.on("model_select", async (_event, ctx) => {
+        runtime.captureModel(ctx);
+        runtime.snapshot(ctx);
+    });
+    pi.on("session_start", async (event, ctx) => {
+        runtime.resetRuntime(ctx.sessionManager.getSessionId());
+        runtime.captureModel(ctx); // best-effort: ctx.model may be set by session start
+        runtime.setStatus(ctx, config.auto ? "mega-compact: ready" : "mega-compact: manual only");
+        // Auto-inline on resume/fork/continue: stage the most relevant checkpoints
+        // so the next before_agent_start prepends them to the system prompt.
+        // Triggered whenever this session already has persisted checkpoints AND a
+        // usable query — that covers reason "resume"/"fork" (explicit) and
+        // reason "startup" (e.g. `pi --continue`s an existing session, which still
+        // emits "startup" but with a populated message window). A brand-new empty
+        // session has no checkpoints, so it's naturally excluded.
+        if (config.autoInline) {
+            const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+            const query = recentUserQuery(ctx);
+            if (query && runtime.store.stats(sid).checkpointCount > 0) {
+                const r = doRecall(runtime, config, ctx, query, "resume");
+                if (!r.empty) {
+                    runtime.pendingRecallBlock = r.block;
+                    runtime.setStatus(ctx, `mega-compact: recalled ${r.toInject.length} chkpt`);
+                    runtime.logger.info("auto-inline", { reason: event.reason, query, injected: r.toInject.map((h) => h.checkpoint.checkpointId) });
+                }
+            }
+        }
+        runtime.dashboard.event("session_start", { reason: event.reason, sessionId: runtime.rt.sessionId });
+        runtime.snapshot(ctx);
+    });
+    pi.on("session_tree", async (_event, ctx) => {
+        // Branch navigation invalidates region indexes — reset checkpoint memory but
+        // keep the on-disk store (markers replayed from entries below if needed).
+        runtime.resetRuntime(ctx.sessionManager.getSessionId());
+        runtime.setStatus(ctx, "mega-compact: ready (branch)");
+        if (config.autoInline) {
+            const query = recentUserQuery(ctx);
+            if (query) {
+                const r = doRecall(runtime, config, ctx, query, "resume");
+                if (!r.empty) {
+                    runtime.pendingRecallBlock = r.block;
+                    runtime.logger.info("auto-inline", { reason: "session_tree", query, injected: r.toInject.map((h) => h.checkpoint.checkpointId) });
+                }
+            }
+        }
+        runtime.dashboard.event("session_tree", { sessionId: runtime.rt.sessionId });
+        runtime.snapshot(ctx);
+    });
+    // ---- Auto-inline injection point: prepend staged recall to systemPrompt ----
+    pi.on("before_agent_start", async (event, ctx) => {
+        runtime.captureModel(ctx); // most reliable point ctx.model is populated
+        if (!runtime.pendingRecallBlock)
+            return;
+        const block = runtime.pendingRecallBlock;
+        runtime.pendingRecallBlock = undefined; // one-shot: consume so we never double-inject
+        return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+    });
+    pi.on("session_shutdown", async (_event, ctx) => {
+        runtime.setStatus(ctx, undefined);
+        runtime.activeAgents = 0;
+        runtime.currentTurn = 0;
+        ctx.ui.setWidget(WIDGET_KEY, [], { placement: "aboveEditor" });
+    });
+    // ---- Agent tracking for real-time widget + status-line updates ---------
+    pi.on("agent_start", async (_event, ctx) => {
+        runtime.activeAgents++;
+        runtime.dashboard.event("agent_start", { activeAgents: runtime.activeAgents });
+        // Surface live agent activity on the status line (toolbar), not just the
+        // above-editor widget — otherwise concurrent agents look frozen.
+        runtime.setStatus(ctx, `mega-compact: ▶ ${runtime.activeAgents} agent${runtime.activeAgents === 1 ? "" : "s"}`);
+        runtime.snapshot(ctx);
+    });
+    pi.on("agent_end", async (_event, ctx) => {
+        runtime.activeAgents = Math.max(0, runtime.activeAgents - 1);
+        runtime.dashboard.event("agent_end", { activeAgents: runtime.activeAgents });
+        if (runtime.activeAgents > 0) {
+            runtime.setStatus(ctx, `mega-compact: ▶ ${runtime.activeAgents} agent${runtime.activeAgents === 1 ? "" : "s"}`);
+        }
+        else {
+            runtime.setStatus(ctx, config.auto ? "mega-compact: ready" : "mega-compact: manual only");
+        }
+        runtime.snapshot(ctx);
+    });
+    pi.on("turn_start", async (event, ctx) => {
+        runtime.currentTurn = event.turnIndex;
+        runtime.dashboard.event("turn_start", { turnIndex: event.turnIndex });
+        runtime.snapshot(ctx);
+    });
+    pi.on("turn_end", async (event, ctx) => {
+        runtime.dashboard.event("turn_end", { turnIndex: event.turnIndex });
+        runtime.snapshot(ctx);
+    });
+    // ---- Auto-trigger: fast-gate → confirm → Trident+persist → drop --------
+    pi.on("context", async (event, ctx) => {
+        if (!config.auto)
+            return;
+        const usage = ctx.getContextUsage();
+        const pct = usage?.percent;
+        // Always track context for the dashboard, even if we return early below.
+        runtime.lastCtxTokens = usage?.tokens ?? null;
+        runtime.lastCtxPercent = pct ?? null;
+        runtime.lastCtxWindow = usage?.contextWindow ?? 0;
+        runtime.snapshot(ctx);
+        if (pct == null)
+            return;
+        const messages = event.messages;
+        const view = runtime.engineView(messages);
+        // Prefer the runtime's real token estimate; fall back to our heuristic
+        // (and to a percent-of-window proxy when tokens is unknown).
+        const currentTokens = usage?.tokens ?? estimateSessionTokens(view) ??
+            Math.round((pct / 100) * (usage?.contextWindow ?? 0));
+        // FAST GATE: token-based (tier threshold), not percentage-based.
+        // A 20% gate on a 2M window = 400k, which is way above the 50k low-tier
+        // threshold. Gate on the actual token count instead.
+        if (currentTokens < config.thresholdTokens)
+            return;
+        const check = autoCompactCheck(currentTokens, config.thresholdTokens); // SERVER-STYLE CONFIRM (local)
+        if (!check.shouldCompact)
+            return;
+        // Debounce so we don't fire on every context event past threshold.
+        const now = Date.now();
+        if (now < runtime.debounceUntil)
+            return;
+        runtime.debounceUntil = now + 2000;
+        const ran = runCompact(pi, runtime, config, ctx, messages);
+        if (ran.skipped)
+            return;
+        // DROP the compacted range from the outgoing context, honoring the anchor
+        // floor + tool-pair boundary guards (PREVENT-PI-001/002).
+        const kept = dropCompactedRange(messages, ran.keepFrom, config.anchorUserMessages);
+        if (kept.length < messages.length) {
+            return { messages: kept };
+        }
+    });
+    // ---- Cancel native compaction once we've persisted our own -------------
+    pi.on("session_before_compact", async (_event, ctx) => {
+        runtime.resetRuntime(ctx.sessionManager.getSessionId());
+        if (runtime.rt.persistedThisSession) {
+            // We already persisted a checkpoint for this session (via the context
+            // hook drop) — cancel pi's own compaction to avoid double-compacting.
+            // Our context-hook drop already trimmed the window.
+            return { cancel: true };
+        }
+        // We haven't persisted yet this session: let pi run its native compaction.
+        // (Our auto-trigger only fires again past the threshold, and will then
+        // capture a checkpoint next time around.)
+        return {};
+    });
+}