pi-mega-compact 0.13.0 → 0.13.2

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

@@ -0,0 +1,194 @@
+/**
+ * Shared harness for the mega-compact-s38 split test files.
+ *
+ * Extracted from the top of mega-compact-s38.test.ts: the mock-pi harness that
+ * loads the compiled extension, the eventTypes/eventPayloads log readers, the
+ * s38TurnEnd helpers, and the classifyError fixtures.
+ *
+ * Every split file imports this module, which also registers an `after()` hook
+ * that force-exits the test subprocess. Each harness() creates a MegaRuntime
+ * with an fs.watch game-state watcher that is never disposed (no
+ * session_shutdown in tests); those handles keep the event loop alive
+ * indefinitely, so without a force-exit `node --test` (without
+ * --test-force-exit) would hang. The hook drains stdout/stderr then defers the
+ * exit — a bare process.exit() discards unflushed pipe buffers (observed
+ * 2026-07-30: piped test results silently vanished).
+ *
+ * Relative paths are one directory deeper than the original file, hence
+ * `../mega-compact.js` / `../mega-events.js`.
+ */
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { after } from "node:test";
+import assert from "node:assert/strict";
+import { closeVectorIndex } from "../../src/store/vectorIndex.js";
+export const require = createRequire(import.meta.url);
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-s38-"));
+export const baseTmpDir = baseTmp;
+export { closeVectorIndex };
+// Isolate the machine-wide repo index so test runs never pollute the real one.
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+let counter = 0;
+after(async () => {
+    // PGlite WASM close can hang; race with a timeout to prevent 40-min hangs.
+    try {
+        await Promise.race([closeVectorIndex(), new Promise((r) => setTimeout(r, 3000))]);
+    }
+    catch { /* ignore */ }
+    if (existsSync(baseTmp))
+        rmSync(baseTmp, { recursive: true, force: true });
+    // Drain stdout/stderr, then defer the exit so the final test report flushes.
+    await new Promise((r) => process.stdout.write("", r));
+    await new Promise((r) => process.stderr.write("", r));
+    await new Promise((r) => setTimeout(r, 1500));
+    process.exit(0);
+});
+/** Read events.log and return an array of event type strings. */
+export function eventTypes(stateDir) {
+    const { readFileSync: rf, existsSync: ex } = require("node:fs");
+    const { join: j } = require("node:path");
+    const logPath = j(stateDir, "events.log");
+    if (!ex(logPath))
+        return [];
+    const content = rf(logPath, "utf-8").trim();
+    if (content.length === 0)
+        return [];
+    return content
+        .split("\n")
+        .map((line) => { try {
+        return JSON.parse(line).type;
+    }
+    catch {
+        return undefined;
+    } })
+        .filter((t) => typeof t === "string");
+}
+/** R11: read events.log and return full JSON payloads for a given type. */
+export function eventPayloads(stateDir, type) {
+    const { readFileSync: rf, existsSync: ex } = require("node:fs");
+    const { join: j } = require("node:path");
+    const logPath = j(stateDir, "events.log");
+    if (!ex(logPath))
+        return [];
+    const content = rf(logPath, "utf-8").trim();
+    if (content.length === 0)
+        return [];
+    return content
+        .split("\n")
+        .map((line) => { try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    } })
+        .filter((p) => typeof p === "object" && p !== null && p.type === type);
+}
+/** Build a mock pi + ctx and load the extension into them. */
+export function harness(opts = {}) {
+    const stateDir = join(baseTmp, `run-${counter++}`);
+    process.env.MEGACOMPACT_STATE_DIR = stateDir;
+    process.env.MEGACOMPACT_DEBUG = "true";
+    if (!opts.keepThreshold)
+        process.env.MEGACOMPACT_THRESHOLD_TOKENS = "50";
+    if (!opts.keepTier)
+        delete process.env.MEGACOMPACT_TIER;
+    process.env.MEGACOMPACT_FAST_GATE_PCT = "1";
+    const handlers = {};
+    const appended = [];
+    const sendUserMessages = [];
+    const compactCalls = [];
+    const session = [
+        { role: "user", content: "read src/vec.ts and understand the index", timestamp: 0 },
+        { role: "assistant", content: [{ type: "toolCall", name: "Read", id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 },
+        { role: "user", content: "edit src/vec.ts to add a cosine helper", timestamp: 0 },
+        { role: "assistant", content: [{ type: "toolCall", name: "Edit", id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 },
+    ];
+    const toEntry = (m, i) => ({ type: "message", id: `e${i}`, parentId: null, timestamp: String(i), message: m });
+    const sessionManager = { getSessionId: () => "sess_ext_001", getEntries: () => session.map(toEntry), getBranch: () => session.map(toEntry) };
+    function makeCtx(over = {}) {
+        return {
+            ui: { setStatus: () => { }, notify: () => { }, select: () => { }, confirm: async () => true, input: async () => "", setWidget: () => { } },
+            mode: "tui", hasUI: true, cwd: stateDir, sessionManager,
+            modelRegistry: {}, model: undefined,
+            isIdle: () => true, isProjectTrusted: () => true,
+            signal: undefined, abort: () => { }, hasPendingMessages: () => false, shutdown: () => { },
+            getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }),
+            compact: (opts) => {
+                compactCalls.push(opts);
+                const _sbc = handlers["session_before_compact"];
+                if (_sbc && _sbc.length)
+                    return _sbc[0]({ type: "session_before_compact", reason: "threshold", willRetry: false, signal: undefined, preparation: { firstKeptEntryId: "e2", messagesToSummarize: session.slice(0, 2), tokensBefore: 500 } }, makeCtx());
+                return undefined;
+            },
+            getSystemPrompt: () => "system base", ...over,
+        };
+    }
+    const pi = {
+        on: (ev, h) => { if (!handlers[ev])
+            handlers[ev] = []; handlers[ev].push(h); },
+        registerCommand: () => { }, registerTool: () => { }, registerShortcut: () => { },
+        registerFlag: () => { }, getFlag: () => undefined,
+        registerMessageRenderer: () => { }, registerEntryRenderer: () => { },
+        sendMessage: () => { }, sendUserMessage: (m) => { sendUserMessages.push(m); },
+        appendEntry: (t, d) => appended.push({ t, d }),
+        setSessionName: () => { }, getSessionName: () => undefined, setLabel: () => { },
+        exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+        getActiveTools: () => [], getAllTools: () => { }, setActiveTools: () => { },
+        getCommands: () => [], setModel: async () => false,
+        getThinkingLevel: () => "off", setThinkingLevel: () => { },
+    };
+    const mod = require("../mega-compact.js");
+    mod.default(pi);
+    return {
+        stateDir, handlers, appended, compactCalls, sendUserMessages,
+        fire: async (ev, event, ctx) => { let r; for (const h of handlers[ev] || [])
+            r = await h(event, ctx); return r; },
+        ctx: makeCtx, session,
+    };
+}
+export const { classifyError: classifyErrorFn, classifyErrorDetailed: classifyErrorDetailedFn, extractErrorSignature: extractErrorSignatureFn } = require("../mega-events.js");
+/** S38 helper: fire a turn_end with a given stopReason + optional text, using a
+ *  low-pressure ctx so the durable-trim branch (ctx.compact) does NOT fire. */
+export async function s38TurnEnd(h, stopReason, text) {
+    const lowCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }) });
+    const message = { role: "assistant" };
+    if (stopReason !== undefined)
+        message.stopReason = stopReason;
+    if (text)
+        message.content = text;
+    await h.fire("turn_end", { type: "turn_end", turnIndex: 1, message }, lowCtx);
+}
+/** R3 helper: like s38TurnEnd but attaches a `usage` object so the classifier's
+ *  0-token poisoned-context signal is exercised (usage PRESENT with 0 tokens).
+ *  Pass `tokens` > 0 to simulate a turn that reached the model. */
+export async function s38TurnEndUsage(h, stopReason, text, tokens) {
+    const lowCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }) });
+    const message = { role: "assistant", usage: { inputTokens: tokens, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 } };
+    if (stopReason !== undefined)
+        message.stopReason = stopReason;
+    if (text)
+        message.content = text;
+    await h.fire("turn_end", { type: "turn_end", turnIndex: 1, message }, lowCtx);
+}
+/** R7 helper: fire the same transient error text `count` times with turn_start
+ *  + elapsed backoff between turns so each turn's nudge can fire. */
+export async function r7RepeatTurns(h, text, count) {
+    for (let i = 0; i < count; i++) {
+        await s38TurnEnd(h, "error", text);
+        await h.fire("turn_start", { type: "turn_start", turnIndex: i + 2 }, h.ctx());
+        await new Promise((r) => setTimeout(r, 3));
+    }
+}
+/** R7 helper: shared assertions for "stays transient" — no poisoned upgrade,
+ *  no /clear advise, and the transient retry path actually ran. */
+export function assertStaysTransient(h, label) {
+    assert.ok(!eventTypes(h.stateDir).includes("poisoned_context"), `${label}: no poisoned_context event (network errors never upgrade)`);
+    assert.ok(!h.sendUserMessages.some((m) => m.includes("/clear")), `${label}: no /clear advise message`);
+    assert.ok(eventTypes(h.stateDir).includes("error_retry"), `${label}: transient retry path ran (error_retry event)`);
+}
+/** The exact error bodies from the 2026-07-30 incident (GLM router flapping). */
+export const R8_NO_HEALTHY_TARGET = '{"message":"No healthy target selected for alias \'hf:zai-org/GLM-4.7\'","type":"api_error"}';
+export const R8_SOCKET_CLOSED = "All targets failed: modal/zai-org/GLM-5.1-FP8. Last error: The socket connection was closed unexpectedly. For more information, pass `verbose: true` in the second argument to fetch()"; // guardrails-allow PREVENT-PI-004: verbatim 2026-07-30 incident error text (string fixture, not a network call)
+export const R8_TOO_MANY_CONCURRENT = 'All targets failed: modal/zai-org/GLM-5.1-FP8. Last error: {"error": "Too many concurrent requests for this model"}';

package/dist/extensions/mega-compact.js

@@ -27,7 +27,7 @@
  */
 import { closeVectorIndex } from "../src/store/vectorIndex.js";
 import { closeMemoryIndex } from "../src/store/memoryIndex.js";
-import { loadConfig } from "./mega-config.js";
+import { loadConfig, repoStateDir } from "./mega-config.js";
 import { loadMegaEnv } from "./mega-runtime/env-loader.js";
 import { MegaRuntime } from "./mega-runtime.js";
 import { registerEventHandlers } from "./mega-events.js";
@@ -42,7 +42,17 @@ export default function (pi) {
     // Load .mega-compact.env (written by /mega-setup + dashboard Setup tab) BEFORE
     // config resolution so the wizard's choices take effect. Shell env wins over
     // the file (see env-loader.ts). Non-fatal: missing/malformed file is a no-op.
-    loadMegaEnv(loadConfig().stateDir);
+    //
+    // The dashboard Setup tab + /mega-setup write the file to the PER-REPO state
+    // dir (<repo>/.pi/mega-compact, resolved via repoStateDir), NOT the global
+    // default (~/.pi/agent/extensions/pi-mega-compact). Loading from the global
+    // dir was the root cause of the embedder-never-activates bug: the file sat in
+    // the per-repo dir, the loader read the empty global dir, and the configured
+    // embedder silently never loaded after restart. Load per-repo first (where
+    // the wizard writes), then the global dir as a legacy fallback.
+    const globalStateDir = loadConfig().stateDir;
+    loadMegaEnv(repoStateDir(process.cwd(), globalStateDir));
+    loadMegaEnv(globalStateDir);
     const config = loadConfig();
     // S38.9: preflight env validation — check for obviously invalid values at startup.
     // Non-fatal: log warnings and fall back to defaults.

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

@@ -0,0 +1,225 @@
+/**
+ * Shared harness for the mega-compact split test files.
+ *
+ * Extracted from the top of mega-compact.test.ts: the mock-pi harness that loads
+ * the compiled extension and lets tests fire event/command handlers against it.
+ * Each split test file imports `harness()` (and `require`/`baseTmp` where
+ * needed) so the per-test isolated state-dir environment is preserved.
+ *
+ * Note: relative paths are one directory deeper than the original file, hence
+ * `../mega-compact.js` for the extension entry and `../../src/...` for src.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { closeVectorIndex } from "../../src/store/vectorIndex.js";
+export const require = createRequire(import.meta.url);
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-ext-"));
+// Isolate the machine-wide repo index so test runs (which call bindRepo ->
+// upsertRepoRegistry) never pollute the developer's real ~/.mega-compact-index.
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+// This end-to-end extension test drives the compact/recall flow through the
+// synchronous node:sqlite store (the authoritative path). The redundant PGlite
+// HNSW cross-repo index is additive and exercised in its own dedicated test
+// (store/vectorIndex.test.ts); starting the WASM worker here only risks the
+// teardown stall that hangs node --test on some machines. Disable it for this
+// suite — the extension behavior under test is identical with it off.
+process.env.MEGACOMPACT_PGLITE_DISABLED = "1";
+export const baseTmpDir = baseTmp;
+export { closeVectorIndex };
+let counter = 0;
+/** Build a mock pi + ctx and load the extension into them. */
+export function harness(opts = {}) {
+    const stateDir = join(baseTmp, `run-${counter++}`);
+    process.env.MEGACOMPACT_STATE_DIR = stateDir;
+    process.env.MEGACOMPACT_DEBUG = "true";
+    // Low threshold so the auto-trigger gate trips on our small mock context.
+    // Tier tests opt out (keepTier/keepThreshold) so they can drive the real
+    // tier resolution instead of the forced 50-token threshold.
+    if (!opts.keepThreshold)
+        process.env.MEGACOMPACT_THRESHOLD_TOKENS = "50";
+    if (!opts.keepTier)
+        delete process.env.MEGACOMPACT_TIER;
+    process.env.MEGACOMPACT_FAST_GATE_PCT = "1";
+    const handlers = {};
+    const commands = {};
+    const appended = [];
+    let statusKey;
+    let statusText;
+    const notifies = [];
+    const compactCalls = [];
+    const sendUserMessages = [];
+    // Minimal AgentMessage factory for the session we project into the extension.
+    function msg(role, text, toolName) {
+        if (role === "assistant" && toolName) {
+            return {
+                role: "assistant",
+                content: [
+                    { type: "toolCall", name: toolName, id: "c1", arguments: {} },
+                ],
+                api: "anthropic-messages",
+                provider: "anthropic",
+                model: "m",
+                usage: {
+                    inputTokens: 1,
+                    outputTokens: 1,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                },
+                stopReason: "tool_use",
+                timestamp: 0,
+            };
+        }
+        if (role === "toolResult" && toolName) {
+            return {
+                role: "toolResult",
+                toolCallId: "c1",
+                toolName,
+                content: [{ type: "text", text }],
+                isError: false,
+                timestamp: 0,
+            };
+        }
+        return {
+            role: "user",
+            content: text,
+            timestamp: 0,
+        };
+    }
+    const session = [
+        msg("user", "read src/vec.ts and understand the index"),
+        msg("assistant", "ok", "Read"),
+        msg("user", "edit src/vec.ts to add a cosine helper"),
+        msg("assistant", "ok", "Edit"),
+        msg("user", "now fix the dedupe bug in store.ts"),
+        msg("assistant", "ok", "Edit"),
+        msg("user", "actually we should add recall sorting too"),
+        msg("assistant", "ok", "Edit"),
+    ];
+    // Mirror the REAL SessionManager: getEntries() returns SessionEntry objects,
+    // which the extension projects to messages via the SDK's
+    // sessionEntryToContextMessages(entry). The harness must use the same shape
+    // (type:"message" with a .message) or recentUserQuery() silently queries "".
+    const toEntry = (m, i) => ({
+        type: "message",
+        id: `e${i}`,
+        parentId: null,
+        timestamp: String(i),
+        message: m,
+    });
+    const sessionManager = {
+        getSessionId: () => "sess_ext_001",
+        getEntries: () => session.map(toEntry),
+        // Faithful mock: getBranch() returns the current branch's entries, which
+        // piCompactWouldNoop() reads to predict whether ctx.compact() would no-op.
+        getBranch: () => session.map(toEntry),
+    };
+    function makeCtx(over = {}) {
+        return {
+            ui: {
+                setStatus: (k, t) => {
+                    statusKey = k;
+                    statusText = t;
+                },
+                notify: (s) => notifies.push(s),
+                select: () => { },
+                confirm: async () => true,
+                input: async () => "",
+                setWidget: () => { },
+            },
+            mode: "tui",
+            hasUI: true,
+            cwd: stateDir,
+            sessionManager,
+            modelRegistry: {},
+            model: undefined,
+            isIdle: () => true,
+            isProjectTrusted: () => true,
+            signal: undefined,
+            abort: () => { },
+            hasPendingMessages: () => false,
+            shutdown: () => { },
+            getContextUsage: () => ({
+                tokens: 200000,
+                contextWindow: 200000,
+                percent: 100,
+            }),
+            // Faithful mock: ctx.compact() starts pi's flow, which fires the
+            // session_before_compact handler (where WE supply the durable trim).
+            compact: (opts) => {
+                compactCalls.push(opts);
+                const _sbc = handlers["session_before_compact"];
+                if (_sbc && _sbc.length) {
+                    return _sbc[0]({
+                        type: "session_before_compact",
+                        reason: "threshold",
+                        willRetry: false,
+                        signal: undefined,
+                        // pi computed the cut honoring anchor floor + tool-pair (PREVENT-PI-002);
+                        // our handler reuses it as firstKeptEntryId.
+                        preparation: {
+                            firstKeptEntryId: "e2",
+                            messagesToSummarize: session.slice(0, 2),
+                            tokensBefore: 500,
+                        },
+                    }, makeCtx());
+                }
+                return undefined;
+            },
+            getSystemPrompt: () => "system base",
+            ...over,
+        };
+    }
+    const pi = {
+        on: (ev, h) => {
+            if (!handlers[ev])
+                handlers[ev] = [];
+            handlers[ev].push(h);
+        },
+        registerCommand: (name, opts) => {
+            commands[name] = opts;
+        },
+        registerTool: () => { },
+        registerShortcut: () => { },
+        registerFlag: () => { },
+        getFlag: () => undefined,
+        registerMessageRenderer: () => { },
+        registerEntryRenderer: () => { },
+        sendMessage: (_m) => { },
+        sendUserMessage: (m) => {
+            sendUserMessages.push(m);
+        },
+        appendEntry: (t, d) => appended.push({ t, d }),
+        setSessionName: () => { },
+        getSessionName: () => undefined,
+        setLabel: () => { },
+        exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+        getActiveTools: () => [],
+        getAllTools: () => [],
+        setActiveTools: () => { },
+        getCommands: () => [],
+        setModel: async () => false,
+        getThinkingLevel: () => "off",
+        setThinkingLevel: () => { },
+    };
+    // Import the compiled extension (same dist dir as this test's parent).
+    const mod = require("../mega-compact.js");
+    mod.default(pi);
+    return {
+        stateDir,
+        handlers,
+        commands,
+        appended,
+        get status() {
+            return { statusKey, statusText };
+        },
+        notifies,
+        compactCalls,
+        sendUserMessages,
+        fire: async (ev, event, ctx) => { let r; for (const h of handlers[ev] || [])
+            r = await h(event, ctx); return r; },
+        ctx: makeCtx,
+        session,
+    };
+}

package/dist/extensions/mega-events/agent-handlers/agentEndHandler.js

@@ -0,0 +1,211 @@
+import { piCompactWouldNoop } from "../../mega-pipeline.js";
+import { safeSendUserMessage } from "../send-safe.js";
+/** Handle the `agent_end` pi event. Non-fatal end-to-end. */
+export async function handleAgentEnd(ctx, pi, runtime, config) {
+    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");
+    }
+    // S16 continuation fallback: if the turn settled idle right after a live-trim
+    // compaction AND there is queued work AND we haven't nudged recently, nudge
+    // once so the agent continues (the live trim should make this rare). Guarded
+    // to never busy-loop: one nudge per 30s, only when truly idle + queued.
+    if ((config.auto || config.autoContinueLengthStop) &&
+        runtime.activeAgents === 0) {
+        try {
+            const idle = ctx.isIdle?.() ?? true;
+            const queued = ctx.hasPendingMessages?.() ?? false;
+            const now = Date.now();
+            // S38.5: read LIVE pressure from ctx.getContextUsage() instead of the
+            // stale runtime.lastCtxTokens (only updated by the `context` event).
+            // agent_end may fire without a preceding context event this turn (e.g.
+            // a sub-agent settling), so the cached value can be null/stale and the
+            // durable-trim branch would be unreachable. ctx.getContextUsage() is the
+            // authoritative live reading (mirrors context-handler.ts:86). Fall back
+            // to the cached value only if the ctx omits it.
+            const liveUsage = ctx.getContextUsage?.();
+            const liveTokens = typeof liveUsage?.tokens === "number"
+                ? liveUsage.tokens
+                : (runtime.lastCtxTokens ?? 0);
+            // Keep the cache fresh for snapshot()/diag regardless of which source we use.
+            if (typeof liveUsage?.tokens === "number") {
+                runtime.lastCtxTokens = liveUsage.tokens;
+            }
+            if (typeof liveUsage?.percent === "number") {
+                runtime.lastCtxPercent = liveUsage.percent;
+            }
+            if (typeof liveUsage?.contextWindow === "number") {
+                runtime.lastCtxWindow = liveUsage.contextWindow;
+            }
+            // DIAG (team-run relief): surface whether the agent is idle + over
+            // threshold at agent_end so we can see if a mid-run durable-trim trigger
+            // *should* have fired but didn't.
+            const overThreshold = liveTokens >= runtime.effectiveThreshold;
+            runtime.diagAgentEndIdle++;
+            runtime.logger.info("agent-end-idle", {
+                sessionId: runtime.rt.sessionId,
+                idle,
+                queued,
+                overThreshold,
+                ctxPct: runtime.lastCtxPercent,
+                ctxTokens: runtime.lastCtxTokens,
+                thresholdTokens: config.thresholdTokens,
+                wouldNudge: idle &&
+                    (queued || overThreshold) &&
+                    now >= runtime.resumeNudgeUntil,
+            });
+            // S16+S24: MID-RUN DURABLE TRIM. During a long team run (sub-agents),
+            // pi's native durable compaction only fires from _checkCompaction at
+            // PARENT settle (agent-session.js:760/844), so the on-disk transcript +
+            // context meter balloon to ~150k and never relieve until the very end
+            // ("compacts but doesn't resume"). agent_end with activeAgents===0 is a
+            // SAFE, settled point: calling ctx.compact() here does NOT abort an
+            // in-flight turn (the S16 danger is only mid-turn). ctx.compact() runs
+            // pi's flow, which fires our session_before_compact handler to supply
+            // the durable trim (truncates the transcript from firstKeptEntryId).
+            // Guarded three ways: only when truly idle + over threshold, only when
+            // pi would actually compact (piCompactWouldNoop skips the user-facing
+            // no-op throw), and debounced (one durable trim per 2s) to avoid
+            // thrashing the transcript while sub-agents keep settling.
+            //
+            // FIX "compacts but doesn't resume": the manual ctx.compact() path
+            // STOPS the agent loop (agent-session.js:1345). The old resume-nudge
+            // was gated on `queued`, so when a sub-agent settled with no
+            // *immediately* queued message, the trim fired but the nudge did not,
+            // and the (stopped) session hung. The trim still fires on
+            // `idle && overThreshold` — we intentionally do NOT add a `!queued`
+            // guard, because that would suppress mid-run relief exactly during
+            // team-run waves where queued is usually true and relief is needed
+            // most. Instead we DECOUPLE the nudge from `queued`: after a durable
+            // trim we ALWAYS nudge so the agent reliably restarts. Debounced 30s.
+            let didDurableTrim = false;
+            if (config.auto &&
+                idle &&
+                overThreshold &&
+                now >= runtime.debounceUntil) {
+                // COMPACT-DEDUP FIX: skip the manual durable-trim trigger when pi's
+                // NATIVE auto-compaction just fired (or is in-flight). pi emits
+                // agent_end BEFORE its own _checkCompaction (per its docstring:
+                // "Called after agent_end and before prompt submission"), so a
+                // synchronous `piCompactWouldNoop` branch check misses a native
+                // compaction that hasn't appended its entry yet — calling
+                // ctx.compact() then races with pi and throws "Already compacted"
+                // to the user. The `lastNativeCompactAt` cooldown (updated by the
+                // session_compact listener for EVERY compaction, native or
+                // extension-supplied) closes that race window.
+                //
+                // S38.5: strict race guard widens the cooldown 10s -> 30s AND defers
+                // ctx.compact() via setTimeout(500) with a re-check, so pi's
+                // about-to-run native _checkCompaction can append its `compaction`
+                // branch entry first (closes the first-race-in-burst window). Gated
+                // by MEGACOMPACT_RACE_GUARD_STRICT (default true); false reverts to
+                // the v0.7.4 synchronous 10s guard. Mirrors the legacy path in
+                // context-handler.ts:258-287 so both call sites stay in sync.
+                const cooldownMs = config.raceGuardStrict ? 30_000 : 10_000;
+                const sinceCompact = now - (runtime.rt.lastNativeCompactAt ?? 0);
+                // CRITICAL-OVER ESCAPE HATCH: when context is critically over the
+                // window (>= 90%), force the durable ctx.compact() even if
+                // piCompactWouldNoop says it would no-op ("Already compacted").
+                // Without this, the on-disk transcript never truncates and the
+                // session stays overflowed on every resume — the "Already
+                // compacted" + overflow death-spiral (2026-08-01 incident). The
+                // cooldown still applies (we don't spam compact), but the no-op
+                // gate is bypassed when critical. pi's ctx.compact() may throw
+                // "Already compacted" in the truly-no-op case — wrapped in
+                // try/catch so the throw is non-fatal.
+                const criticalOver = (runtime.lastCtxPercent ?? 0) >= 90;
+                if (sinceCompact < cooldownMs) {
+                    runtime.diagAgentEndDurableSkipRecent++;
+                }
+                else if (criticalOver || !piCompactWouldNoop(ctx)) {
+                    runtime.debounceUntil = now + 2000;
+                    runtime.diagAgentEndDurable++;
+                    runtime.logger.info("agent-end-durable-trigger", {
+                        sessionId: runtime.rt.sessionId,
+                        ctxTokens: runtime.lastCtxTokens,
+                        thresholdTokens: config.thresholdTokens,
+                        queued,
+                    });
+                    if (config.raceGuardStrict) {
+                        // Strict: defer ctx.compact() with a re-check so pi's
+                        // about-to-run native _checkCompaction can append its
+                        // `compaction` branch entry first. setTimeout(500) — pi's
+                        // compaction-summary append is async I/O, so queueMicrotask
+                        // would re-check before it lands.
+                        const stamp = runtime.rt.lastNativeCompactAt;
+                        const liveSid = runtime.rt.sessionId;
+                        const liveCritical = criticalOver;
+                        setTimeout(() => {
+                            try {
+                                if (runtime.rt.sessionId !== liveSid)
+                                    return; // session reset
+                                // IMPORTANT: recompute Date.now() inside the timeout.
+                                // `now` above is the durable-trim handler's timestamp and can be
+                                // ~500ms stale by the time this callback runs.
+                                const since2 = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
+                                if (runtime.rt.lastNativeCompactAt !== stamp &&
+                                    since2 < cooldownMs)
+                                    return;
+                                // CRITICAL-OVER ESCAPE HATCH: bypass the no-op gate when
+                                // critical (captured at handler time) so the durable trim fires.
+                                if (!liveCritical && piCompactWouldNoop(ctx))
+                                    return;
+                                ctx.compact({
+                                    customInstructions: undefined,
+                                }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated. May throw "Already compacted" when the escape hatch forces it — caught below.
+                            }
+                            catch {
+                                /* non-fatal: "Already compacted" throws are expected when the critical-over hatch forces a no-op compact */
+                            }
+                        }, 500);
+                    }
+                    else {
+                        try {
+                            ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. May throw "Already compacted" when the critical-over escape hatch forces it — caught.
+                        }
+                        catch {
+                            /* non-fatal */
+                        }
+                    }
+                    didDurableTrim = true;
+                }
+            }
+            // Restart the agent after a mid-run durable trim (which stopped it), or
+            // when it settled idle with queued work. Decoupled from `queued` for the
+            // durable-trim case — see FIX note above. Debounced 30s; never blocks.
+            const lengthStop = config.autoContinueLengthStop && runtime.rt.lengthStopPending;
+            if (idle &&
+                now >= runtime.resumeNudgeUntil &&
+                ((config.auto && (didDurableTrim || queued)) || lengthStop)) {
+                runtime.resumeNudgeUntil = now + 30_000;
+                if (runtime.rt.lengthStopPending) {
+                    runtime.rt.lengthStopPending = false; // one-shot: never re-fire for same stop
+                    runtime.dashboard.event("length_stop_continue", {
+                        turnIndex: runtime.currentTurn,
+                    });
+                    runtime.logger.info("length_stop_continue", {
+                        sessionId: runtime.rt.sessionId,
+                        didDurableTrim,
+                        queued,
+                    });
+                }
+                // S28: when a length-stop (max-output-token truncation) fired WITHOUT a durable trim, do NOT claim a compaction happened
+                // (nothing was compacted on the low-pressure length path). Branch the message so the nudge matches reality.
+                const nudgeMsg = lengthStop && !didDurableTrim
+                    ? "[mega-compact] the last response hit the output-token cap; continue from where it stopped."
+                    : "[mega-compact] continue from the compacted context above.";
+                await safeSendUserMessage(pi, nudgeMsg);
+            }
+        }
+        catch {
+            /* non-fatal: a failed nudge never blocks */
+        }
+    }
+    runtime.snapshot(ctx);
+}