pi-mega-compact 0.13.1 → 0.13.2

package/extensions/mega-compact-s38.test/_helpers.ts

@@ -0,0 +1,201 @@
+/**
+ * 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";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+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: string): string[] {
+	const { readFileSync: rf, existsSync: ex } =
+		require("node:fs") as typeof import("node:fs");
+	const { join: j } = require("node:path") as typeof import("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): t is string => typeof t === "string");
+}
+
+/** R11: read events.log and return full JSON payloads for a given type. */
+export function eventPayloads(stateDir: string, type: string): Record<string, unknown>[] {
+	const { readFileSync: rf, existsSync: ex } =
+		require("node:fs") as typeof import("node:fs");
+	const { join: j } = require("node:path") as typeof import("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): p is Record<string, unknown> => typeof p === "object" && p !== null && p.type === type);
+}
+
+/** Build a mock pi + ctx and load the extension into them. */
+export function harness(opts: { keepTier?: boolean; keepThreshold?: boolean } = {}) {
+	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: Record<string, Function[]> = {};
+	const appended: any[] = [];
+	const sendUserMessages: string[] = [];
+	const compactCalls: any[] = [];
+
+	const session: AgentMessage[] = [
+		{ role: "user", content: "read src/vec.ts and understand the index", timestamp: 0 } as unknown as AgentMessage,
+		{ 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 } as unknown as AgentMessage,
+		{ role: "user", content: "edit src/vec.ts to add a cosine helper", timestamp: 0 } as unknown as AgentMessage,
+		{ 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 } as unknown as AgentMessage,
+	];
+	const toEntry = (m: AgentMessage, i: number): any => ({ 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: Partial<any> = {}) {
+		return {
+			ui: { setStatus: () => {}, notify: () => {}, select: () => {}, confirm: async () => true, input: async () => "", setWidget: () => {} },
+			mode: "tui" as any, hasUI: true, cwd: stateDir, sessionManager,
+			modelRegistry: {} as any, model: undefined,
+			isIdle: () => true, isProjectTrusted: () => true,
+			signal: undefined, abort: () => {}, hasPendingMessages: () => false, shutdown: () => {},
+			getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }),
+			compact: (opts?: any) => {
+				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 } } as any, makeCtx());
+				return undefined;
+			},
+			getSystemPrompt: () => "system base", ...over,
+		} as any;
+	}
+	const pi = {
+		on: (ev: string, h: Function) => { if (!handlers[ev]) handlers[ev] = []; handlers[ev].push(h); },
+		registerCommand: () => {}, registerTool: () => {}, registerShortcut: () => {},
+		registerFlag: () => {}, getFlag: () => undefined,
+		registerMessageRenderer: () => {}, registerEntryRenderer: () => {},
+		sendMessage: () => {}, sendUserMessage: (m: string) => { sendUserMessages.push(m); },
+		appendEntry: (t: string, d: any) => appended.push({ t, d }),
+		setSessionName: () => {}, getSessionName: () => undefined, setLabel: () => {},
+		exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+		getActiveTools: () => [], getAllTools: () => {}, setActiveTools: () => {},
+		getCommands: () => [], setModel: async () => false,
+		getThinkingLevel: () => "off" as any, setThinkingLevel: () => {},
+	} as any;
+	const mod = require("../mega-compact.js") as { default: (p: any) => void };
+	mod.default(pi);
+	return {
+		stateDir, handlers, appended, compactCalls, sendUserMessages,
+		fire: async (ev: string, event: any, ctx: any) => { let r: any; for (const h of handlers[ev] || []) r = await h(event, ctx); return r; },
+		ctx: makeCtx, session,
+	};
+}
+
+export type Harness = ReturnType<typeof harness>;
+
+export const { classifyError: classifyErrorFn, classifyErrorDetailed: classifyErrorDetailedFn, extractErrorSignature: extractErrorSignatureFn } =
+	require("../mega-events.js") as { classifyError: typeof import("../mega-events.js").classifyError; classifyErrorDetailed: typeof import("../mega-events.js").classifyErrorDetailed; extractErrorSignature: typeof import("../mega-events.js").extractErrorSignature };
+
+/** 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: Harness, stopReason: string | undefined, text?: string) {
+	const lowCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }) });
+	const message: any = { 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: Harness, stopReason: string | undefined, text: string | undefined, tokens: number) {
+	const lowCtx = h.ctx({ isIdle: () => true, hasPendingMessages: () => false, getContextUsage: () => ({ tokens: 100, contextWindow: 200000, percent: 0 }) });
+	const message: any = { 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: Harness, text: string, count: number) {
+	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: Harness, label: string) {
+	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/extensions/mega-compact.test/_helpers.ts

@@ -0,0 +1,237 @@
+/**
+ * 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";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+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: { keepTier?: boolean; keepThreshold?: boolean } = {}) {
+	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: Record<string, Function[]> = {};
+	const commands: Record<
+		string,
+		{ handler: (a: string, c: any) => Promise<void> }
+	> = {};
+	const appended: any[] = [];
+	let statusKey: string | undefined;
+	let statusText: string | undefined;
+	const notifies: string[] = [];
+	const compactCalls: any[] = [];
+	const sendUserMessages: string[] = [];
+
+	// Minimal AgentMessage factory for the session we project into the extension.
+	function msg(role: string, text: string, toolName?: string): AgentMessage {
+		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,
+			} as unknown as AgentMessage;
+		}
+		if (role === "toolResult" && toolName) {
+			return {
+				role: "toolResult",
+				toolCallId: "c1",
+				toolName,
+				content: [{ type: "text", text }],
+				isError: false,
+				timestamp: 0,
+			} as unknown as AgentMessage;
+		}
+		return {
+			role: "user",
+			content: text,
+			timestamp: 0,
+		} as unknown as AgentMessage;
+	}
+
+	const session: AgentMessage[] = [
+		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: AgentMessage, i: number): any => ({
+		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: Partial<any> = {}) {
+		return {
+			ui: {
+				setStatus: (k: string, t: string | undefined) => {
+					statusKey = k;
+					statusText = t;
+				},
+				notify: (s: string) => notifies.push(s),
+				select: () => {},
+				confirm: async () => true,
+				input: async () => "",
+				setWidget: () => {},
+			},
+			mode: "tui" as any,
+			hasUI: true,
+			cwd: stateDir,
+			sessionManager,
+			modelRegistry: {} as any,
+			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?: any) => {
+				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,
+							},
+						} as any,
+						makeCtx(),
+					);
+				}
+				return undefined;
+			},
+			getSystemPrompt: () => "system base",
+			...over,
+		} as any;
+	}
+
+	const pi = {
+		on: (ev: string, h: Function) => {
+			if (!handlers[ev]) handlers[ev] = [];
+			handlers[ev].push(h);
+		},
+		registerCommand: (name: string, opts: any) => {
+			commands[name] = opts;
+		},
+		registerTool: () => {},
+		registerShortcut: () => {},
+		registerFlag: () => {},
+		getFlag: () => undefined,
+		registerMessageRenderer: () => {},
+		registerEntryRenderer: () => {},
+		sendMessage: (_m: any) => {},
+		sendUserMessage: (m: string) => {
+			sendUserMessages.push(m);
+		},
+		appendEntry: (t: string, d: any) => appended.push({ t, d }),
+		setSessionName: () => {},
+		getSessionName: () => undefined,
+		setLabel: () => {},
+		exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+		getActiveTools: () => [],
+		getAllTools: () => [],
+		setActiveTools: () => {},
+		getCommands: () => [],
+		setModel: async () => false,
+		getThinkingLevel: () => "off" as any,
+		setThinkingLevel: () => {},
+	} as any;
+
+	// Import the compiled extension (same dist dir as this test's parent).
+	const mod = require("../mega-compact.js") as { default: (p: any) => void };
+	mod.default(pi);
+
+	return {
+		stateDir,
+		handlers,
+		commands,
+		appended,
+		get status() {
+			return { statusKey, statusText };
+		},
+		notifies,
+		compactCalls,
+		sendUserMessages,
+		fire: async (ev: string, event: any, ctx: any) => { let r: any; for (const h of handlers[ev] || []) r = await h(event, ctx); return r; },
+		ctx: makeCtx,
+		session,
+	};
+}

package/extensions/mega-events/agent-handlers/agentEndHandler.ts

@@ -0,0 +1,238 @@
+/**
+ * agent-handlers/agentEndHandler.ts — the pi `agent_end` handler body.
+ *
+ * Extracted from agent-handlers.ts (delegate-shell split) to keep every source
+ * file under the extensions limit. Contains the live-agent status-line updates,
+ * the S16/S38.5 mid-run durable trim (race-guarded, deferred ctx.compact), the
+ * S28 length-stop nudge, and the R4-R11 error-retry safety net.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "../../mega-runtime.js";
+import { piCompactWouldNoop } from "../../mega-pipeline.js";
+import type { MegaConfig } from "../../mega-config.js";
+import { safeSendUserMessage } from "../send-safe.js";
+
+/** Handle the `agent_end` pi event. Non-fatal end-to-end. */
+export async function handleAgentEnd(
+	ctx: ExtensionContext,
+	pi: ExtensionAPI,
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): Promise<void> {
+	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);
+}