pi-mega-compact 0.15.4 → 0.16.1

package/extensions/dashboard-server/api-contracts/model-thresholds.ts

@@ -0,0 +1,76 @@
+/**
+ * api-contracts/model-thresholds.ts — per-model compaction threshold API types.
+ *
+ * Types for the /api/model-thresholds endpoints used by the Setup panel
+ * "Thresholds" sub-tab to tune the safety margin + fire point per model.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type — all types are explicit.
+ */
+/** A per-model threshold (mirrors src/store/sqlite/model-thresholds.ts
+ * ModelThreshold — duplicated here so api-contracts has no cross-package
+ * import into src/, per the ast-grep:no-relative-cross-package-import rule). */
+export interface ModelThresholdDTO {
+	readonly modelId: string;
+	readonly safetyMarginPct: number;
+	readonly firePointPct: number;
+	readonly updatedAt: number | null;
+}
+
+/** A model known to this repo (most-recent model_snapshots row, deduped). */
+export interface KnownModel {
+	readonly modelId: string;
+	readonly provider: string;
+	readonly modelName: string | null;
+	readonly contextWindow: number;
+	readonly maxTokens: number;
+	/** True when an override row exists in model_thresholds. */
+	readonly hasOverride: boolean;
+}
+
+/**
+ * Response for GET /api/model-thresholds — every known model with its
+ * threshold (override if present, otherwise defaults) for the UI table.
+ */
+export interface ModelThresholdsResponse {
+	readonly defaults: {
+		readonly safetyMarginPct: number;
+		readonly firePointPct: number;
+		readonly safetyMarginRange: readonly [number, number];
+		readonly firePointRange: readonly [number, number];
+	};
+	readonly models: ReadonlyArray<
+		KnownModel & {
+			readonly threshold: {
+				readonly safetyMarginPct: number;
+				readonly firePointPct: number;
+				readonly isOverride: boolean;
+			};
+		}
+	>;
+}
+
+/** Request body for PUT /api/model-thresholds. */
+export interface ModelThresholdPutRequest {
+	readonly modelId: string;
+	readonly safetyMarginPct: number;
+	readonly firePointPct: number;
+}
+
+/** Response for PUT /api/model-thresholds. */
+export interface ModelThresholdPutResponse {
+	readonly threshold: ModelThresholdDTO;
+}
+
+/** Response for DELETE /api/model-thresholds/:modelId. */
+export interface ModelThresholdDeleteResponse {
+	readonly deleted: boolean;
+}
+
+export type ModelThresholdsError =
+	| { readonly error: "method_not_allowed" }
+	| { readonly error: "invalid_json" }
+	| { readonly error: "body_too_large" }
+	| { readonly error: "missing_model_id" }
+	| { readonly error: "invalid_pct"; readonly detail: string }
+	| { readonly error: "internal" };

package/extensions/dashboard-server/resolve-snapshot.ts

@@ -55,7 +55,7 @@ function mostRecentOtherRepoStateDir(launchStateDir: string): string | null {
 		const { DatabaseSync } =
 			require("node:sqlite") as typeof import("node:sqlite");
 		db = new DatabaseSync(indexPath, { readOnly: true });
-			const rows = db
+		const rows = db
 			.prepare(
 				`SELECT state_dir, last_seen FROM repo_registry
 				 WHERE state_dir IS NOT NULL AND last_seen IS NOT NULL

package/extensions/dashboard-server/routes-model-thresholds.ts

@@ -0,0 +1,222 @@
+/**
+ * dashboard-server/routes-model-thresholds.ts — per-model compaction
+ * thresholds (S52 / v0.16.1).
+ *
+ * Routes for the Setup panel "Thresholds" sub-tab.
+ *
+ *   GET    /api/model-thresholds           — list every known model + its
+ *                                            threshold (override or default),
+ *                                            for the dashboard table.
+ *   PUT    /api/model-thresholds           — upsert a per-model override.
+ *                                            Body: ModelThresholdPutRequest.
+ *   DELETE /api/model-thresholds/:modelId  — delete the override (revert to
+ *                                            env/defaults).
+ *
+ * Guardrails: PREVENT-PI-004 (loopback), PREVENT-001 (null-safe JSON),
+ * PREVENT-002 (parameterized via model-thresholds.ts),
+ * PREVENT-011 (no `any`).
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import type {
+	ModelThresholdsResponse,
+	ModelThresholdPutResponse,
+	ModelThresholdDeleteResponse,
+	ModelThresholdsError,
+	KnownModel,
+} from "./api-contracts/model-thresholds.js";
+import {
+	DEFAULT_SAFETY_MARGIN_PCT,
+	DEFAULT_FIRE_POINT_PCT,
+	MAX_SAFETY_MARGIN_PCT,
+	MIN_SAFETY_MARGIN_PCT,
+	MIN_FIRE_POINT_PCT,
+	MAX_FIRE_POINT_PCT,
+	getModelThreshold,
+	listModelThresholds,
+	putModelThreshold,
+	deleteModelThreshold,
+} from "../../src/store/sqlite/model-thresholds.js";
+import { listModelSnapshots } from "../../src/store/sqlite/model-snapshots.js";
+
+function send(res: ServerResponse, status: number, body: unknown): void {
+	// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+	res.writeHead(status, { "Content-Type": "application/json" });
+	res.end(JSON.stringify(body));
+}
+
+/** Read + JSON.parse a request body (被骗: spans POST/PUT/DELETE).
+ *  Capped at 64KB; null-safe. */
+function readBody(
+	req: IncomingMessage,
+	cb: (
+		result:
+			| { ok: true; value: Record<string, unknown> }
+			| { ok: false; error: ModelThresholdsError["error"] },
+	) => void,
+): void {
+	let body = "";
+	let tooBig = false;
+	req.on("data", (chunk: Buffer) => {
+		if (body.length > 65536) {
+			tooBig = true;
+			return;
+		}
+		body += chunk.toString();
+	});
+	req.on("end", () => {
+		if (tooBig) return cb({ ok: false, error: "body_too_large" });
+		try {
+			const v = body ? JSON.parse(body) : {}; // PREVENT-001: type-checked
+			if (typeof v !== "object" || v === null || Array.isArray(v)) {
+				return cb({ ok: false, error: "invalid_json" });
+			}
+			cb({ ok: true, value: v as Record<string, unknown> });
+		} catch {
+			cb({ ok: false, error: "invalid_json" });
+		}
+	});
+	req.on("error", () => cb({ ok: false, error: "invalid_json" }));
+}
+
+/** Read body that also handles 0 bytes. */
+function requireNumber(v: unknown, label: string): number {
+	const n = Number(v);
+	if (!Number.isFinite(n)) {
+		throw new Error(`${label} must be a finite number, got ${String(v)}`);
+	}
+	return n;
+}
+
+/** List known models from model_snapshots, deduped by model_id (latest wins). */
+function listKnownModels(stateDir: string): KnownModel[] {
+	const snaps = listModelSnapshots(stateDir);
+	// Dedup by model_id, keep latest (highest capturedAt).
+	const byId = new Map<string, (typeof snaps)[number]>();
+	for (const s of snaps) {
+		const existing = byId.get(s.modelId);
+		if (!existing || s.capturedAt > existing.capturedAt) byId.set(s.modelId, s);
+	}
+	return Array.from(byId.values()).map((s) => ({
+		modelId: s.modelId,
+		provider: s.provider,
+		modelName: s.modelName,
+		contextWindow: s.contextWindow,
+		maxTokens: s.maxTokens,
+		hasOverride: getModelThreshold(s.modelId, stateDir) !== null,
+	}));
+}
+
+export function handleModelThresholds(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (!req.url?.startsWith("/api/model-thresholds")) return false;
+	const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
+
+	// GET: list every known model + its threshold.
+	if (req.method === "GET" && url.pathname === "/api/model-thresholds") {
+		try {
+			const known = listKnownModels(ctx.stateDir);
+			const overrides = new Map(
+				listModelThresholds(ctx.stateDir).map((t) => [t.modelId, t]),
+			);
+			const body: ModelThresholdsResponse = {
+				defaults: {
+					safetyMarginPct: DEFAULT_SAFETY_MARGIN_PCT,
+					firePointPct: DEFAULT_FIRE_POINT_PCT,
+					safetyMarginRange: [MIN_SAFETY_MARGIN_PCT, MAX_SAFETY_MARGIN_PCT],
+					firePointRange: [MIN_FIRE_POINT_PCT, MAX_FIRE_POINT_PCT],
+				},
+				models: known.map((m) => {
+					const ov = overrides.get(m.modelId);
+					return {
+						...m,
+						threshold: ov
+							? {
+									safetyMarginPct: ov.safetyMarginPct,
+									firePointPct: ov.firePointPct,
+									isOverride: true,
+								}
+							: {
+									safetyMarginPct: DEFAULT_SAFETY_MARGIN_PCT,
+									firePointPct: DEFAULT_FIRE_POINT_PCT,
+									isOverride: false,
+								},
+					};
+				}),
+			};
+			send(res, 200, body);
+		} catch (e) {
+			send(res, 500, { error: "internal", detail: String(e) });
+		}
+		return true;
+	}
+
+	// PUT: upsert a per-model override.
+	if (req.method === "PUT" && url.pathname === "/api/model-thresholds") {
+		readBody(req, (result) => {
+			if (!result.ok) return send(res, 400, { error: result.error });
+			try {
+				const v = result.value;
+				const modelId = v.modelId;
+				if (typeof modelId !== "string" || !modelId.trim()) {
+					return send(res, 400, { error: "missing_model_id" });
+				}
+				let safety: number;
+				let fire: number;
+				try {
+					safety = requireNumber(v.safetyMarginPct, "safetyMarginPct");
+					fire = requireNumber(v.firePointPct, "firePointPct");
+				} catch (e) {
+					return send(res, 400, {
+						error: "invalid_pct",
+						detail: e instanceof Error ? e.message : String(e),
+					});
+				}
+				const t = putModelThreshold(modelId, safety, fire, ctx.stateDir);
+				const body: ModelThresholdPutResponse = { threshold: t };
+				send(res, 200, body);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				if (/must be in \[/.test(msg)) {
+					return send(res, 400, { error: "invalid_pct", detail: msg });
+				}
+				send(res, 500, { error: "internal", detail: msg });
+			}
+		});
+		return true;
+	}
+
+	// DELETE: /api/model-thresholds/:modelId
+	if (
+		req.method === "DELETE" &&
+		url.pathname.startsWith("/api/model-thresholds/")
+	) {
+		const modelId = decodeURIComponent(
+			url.pathname.slice("/api/model-thresholds/".length),
+		);
+		if (!modelId) {
+			send(res, 400, { error: "missing_model_id" });
+			return true;
+		}
+		try {
+			const deleted = deleteModelThreshold(modelId, ctx.stateDir);
+			const body: ModelThresholdDeleteResponse = { deleted };
+			send(res, 200, body);
+		} catch (e) {
+			send(res, 500, { error: "internal", detail: String(e) });
+		}
+		return true;
+	}
+
+	// Catch-all: only GET/PUT/DELETE on /api/model-thresholds[*] are supported.
+	if (url.pathname === "/api/model-thresholds") {
+		send(res, 405, {
+			error: "method_not_allowed",
+		} satisfies ModelThresholdsError);
+		return true;
+	}
+	return false;
+}

package/extensions/dashboard-server/routes.ts

@@ -22,12 +22,21 @@ export { handleTurns } from "./routes-turns.js";
 export { handleMaintenance } from "./routes-maintenance.js";
 export { handleProviderCache } from "./routes-cache.js";
 export { handleMemoryStatus } from "./routes-memory.js";
-export { handleSetupStatus, handleSetupDetect, handleSetupConfigure } from "./routes-setup.js";
+export {
+	handleSetupStatus,
+	handleSetupDetect,
+	handleSetupConfigure,
+} from "./routes-setup.js";
 export { handleMemoryMap } from "./routes-memory-map.js";
 export { handleRaptorTree, handleRaptorBuildHistory } from "./routes-raptor.js";
 export { handleCacheStripes } from "./routes-cache.js";
-export { handleContextHealth, handleCachePoison, handleHealthSettings } from "./routes-health.js";
+export {
+	handleContextHealth,
+	handleCachePoison,
+	handleHealthSettings,
+} from "./routes-health.js";
 export { handleEmbedderHealth } from "./routes-embedder-health.js";
 export { handleRagSettings } from "./routes-rag-settings.js";
 export { handleRagMetrics } from "./routes-rag-metrics.js";
+export { handleModelThresholds } from "./routes-model-thresholds.js";
 export { handleWiki } from "./routes-wiki.js";

package/extensions/dashboard-server/server.ts

@@ -54,6 +54,7 @@ import {
 	handleEmbedderHealth,
 	handleRagSettings,
 	handleRagMetrics,
+	handleModelThresholds,
 	handleWiki,
 	handleStatic,
 } from "./routes.js";
@@ -160,7 +161,9 @@ export async function launchDashboardServer(
 			map: "application/json",
 		};
 		const payload: string | Uint8Array =
-			ext === "html" ? injectUiFlag(readFileSync(file, "utf-8")) : readFileSync(file);
+			ext === "html"
+				? injectUiFlag(readFileSync(file, "utf-8"))
+				: readFileSync(file);
 		res.writeHead(200, {
 			"Content-Type": types[ext] ?? "application/octet-stream",
 		});
@@ -270,6 +273,7 @@ export async function launchDashboardServer(
 		if (handleEmbedderHealth(req, res, ctx)) return;
 		if (handleRagSettings(req, res, ctx)) return;
 		if (handleRagMetrics(req, res, ctx)) return;
+		if (handleModelThresholds(req, res, ctx)) return;
 		if (handleWiki(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});

package/extensions/mega-events/context-handler.ts

@@ -17,9 +17,16 @@ import type {
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import {
 	openStore,
+	resolveModelThreshold,
+	DEFAULT_SAFETY_MARGIN_PCT,
+	DEFAULT_FIRE_POINT_PCT,
 } from "../../src/store/sqlite.js";
 import { autoCompactCheck } from "../../src/compact.js";
-import { estimateSessionTokens } from "../../src/tokens.js";
+import {
+	estimateSessionTokens,
+	estimateBlockTokens,
+	estimateMessageTokens,
+} from "../../src/tokens.js";
 import type { MegaRuntime } from "../mega-runtime.js";
 import { runCompact, piCompactWouldNoop } from "../mega-pipeline.js";
 import {
@@ -94,59 +101,75 @@ export function registerContextHandler(
 		const view = viewForFallback ?? runtime.engineView(messages);
 
 		// S27 DB-mirror: append incoming messages to raw_transcript.
-			// Runs BEFORE fast-gate so every message is captured, even if we
-			// don't compact this turn. Append is idempotent (content_hash PK).
-			// F3: high-water mark (mirror-append.ts) skips already-processed
-			// messages on subsequent events. On fork/rewind (shorter list or
-			// boundary hash mismatch) the mark is dropped, falling back to a
-			// full reprocess.
-			if (config.dbMirror) {
-				try {
-					const db = openStore(runtime.currentStateDir);
-					appendMirrorMessages(
-						db,
-						messages,
-						runtime.rt.sessionId,
-						epochIdFor(runtime.rt.sessionId),
-						runtime.currentTurn,
+		// Runs BEFORE fast-gate so every message is captured, even if we
+		// don't compact this turn. Append is idempotent (content_hash PK).
+		// F3: high-water mark (mirror-append.ts) skips already-processed
+		// messages on subsequent events. On fork/rewind (shorter list or
+		// boundary hash mismatch) the mark is dropped, falling back to a
+		// full reprocess.
+		if (config.dbMirror) {
+			try {
+				const db = openStore(runtime.currentStateDir);
+				appendMirrorMessages(
+					db,
+					messages,
+					runtime.rt.sessionId,
+					epochIdFor(runtime.rt.sessionId),
+					runtime.currentTurn,
+				);
+				// P2.2: populate conversation_thread + tool_results tables for
+				// prompt-cache analytics and durable separation. The live-array
+				// separation (buildSeparatedPrompt / buildCacheOptimizedPrompt in
+				// tailResult above) is sufficient for the prompt-construction path;
+				// these DB writes persist the split for post-hoc analysis, dashboard
+				// queries, and future readers. Non-fatal — failure here never breaks
+				// the agent loop (PREVENT-PI-004: zero network, local SQLite only).
+				{
+					const sid = runtime.rt.sessionId;
+					const turn = runtime.currentTurn;
+					const now = Date.now();
+					const threadStmt = db.prepare(
+						"INSERT OR IGNORE INTO conversation_thread (conversation_id, role, content, turn_index, timestamp) VALUES (?, ?, ?, ?, ?)",
 					);
-					// P2.2: populate conversation_thread + tool_results tables for
-					// prompt-cache analytics and durable separation. The live-array
-					// separation (buildSeparatedPrompt / buildCacheOptimizedPrompt in
-					// tailResult above) is sufficient for the prompt-construction path;
-					// these DB writes persist the split for post-hoc analysis, dashboard
-					// queries, and future readers. Non-fatal — failure here never breaks
-					// the agent loop (PREVENT-PI-004: zero network, local SQLite only).
-					{
-						const sid = runtime.rt.sessionId;
-						const turn = runtime.currentTurn;
-						const now = Date.now();
-						const threadStmt = db.prepare(
-							"INSERT OR IGNORE INTO conversation_thread (conversation_id, role, content, turn_index, timestamp) VALUES (?, ?, ?, ?, ?)",
-						);
-						const toolStmt = db.prepare(
-							"INSERT OR IGNORE INTO tool_results (conversation_id, role, content, turn_index, timestamp) VALUES (?, ?, ?, ?, ?)",
-						);
-						for (const m of messages) {
-							const role = m.role;
-							const content = messageContentText(m);
-							if (role === "user" || role === "assistant") {
-								threadStmt.run(sid, role, content, turn, now);
-							} else if (role === "toolResult" || role === "bashExecution") {
-								toolStmt.run(sid, role, content, turn, now);
-							}
+					const toolStmt = db.prepare(
+						"INSERT OR IGNORE INTO tool_results (conversation_id, role, content, turn_index, timestamp) VALUES (?, ?, ?, ?, ?)",
+					);
+					for (const m of messages) {
+						const role = m.role;
+						const content = messageContentText(m);
+						if (role === "user" || role === "assistant") {
+							threadStmt.run(sid, role, content, turn, now);
+						} else if (role === "toolResult" || role === "bashExecution") {
+							toolStmt.run(sid, role, content, turn, now);
 						}
 					}
-				} catch (e) {
-					runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
 				}
+			} catch (e) {
+				runtime.logger.warn("db-mirror-append-fail", { error: String(e) });
 			}
+		}
 
+		// S52 / v0.16.1: per-model threshold override. The user can tune the
+		// fire point + safety margin PER MODEL (different providers' models range
+		// 8K-1M+ context, so one global tier % is wrong). Falls back to env/default
+		// when no override row exists. Computed once here + reused in the tail cap
+		// below; the lookup is a single SQLite PK hit (cheap; cached after the
+		// first read in a session).
+		const _modelIdForThreshold = runtime.currentModel?.modelId ?? null;
+		const _perModelThreshold = resolveModelThreshold(_modelIdForThreshold, {
+			safetyMarginFallback: DEFAULT_SAFETY_MARGIN_PCT,
+			firePointFallback:
+				config.tierPct != null
+					? Math.round(config.tierPct * 100)
+					: DEFAULT_FIRE_POINT_PCT,
+			stateDir: runtime.currentStateDir,
+		});
 		// S29 FAST GATE: drive the auto-trigger off the context % (the number the
 		// menu bar shows), NOT the token count — the model under-reports tokens,
 		// so a token-only gate misses the overshoot that causes max-output-tokens
-		// truncation. The fire point is the tier's percent threshold (tierPct)
-		// unless overridden by MEGACOMPACT_AUTO_PCT_TRIGGER. `custom` (absolute
+		// truncation. The fire point is the per-model override when present,
+		// otherwise the tier's percent threshold (tierPct) unless overridden by
+		// MEGACOMPACT_AUTO_PCT_TRIGGER. `custom` (absolute
 		// MEGACOMPACT_THRESHOLD_TOKENS, tierPct null) is an explicit opt-out of
 		// percent scaling — it keeps the token gate. When pct is unavailable
 		// (window unknown / a model that doesn't report percent) a tiered config
@@ -154,7 +177,12 @@ export function registerContextHandler(
 		// skipping compaction — a percent-only gate would regress that.
 		let gatePassed = false;
 		if (config.tierPct != null && pct != null) {
-			const firePct = config.autoPctTrigger ?? config.tierPct;
+			// Per-model override is a % (10-90); tierPct is a fraction (0.1-1.0).
+			// Prefer the override; fall back to autoPctTrigger + tierPct.
+			const tierPctFraction = config.autoPctTrigger ?? config.tierPct;
+			const perModelFraction = _perModelThreshold.firePointPct / 100;
+			const firePct =
+				_modelIdForThreshold != null ? perModelFraction : tierPctFraction;
 			gatePassed = pct / 100 >= firePct;
 		} else {
 			// custom tier OR tiered-but-pct-unavailable → token gate (S27 fallback).
@@ -204,7 +232,10 @@ export function registerContextHandler(
 				runtime.snapshot(ctx);
 				// v0.8.7: shallow-copy the cached summary so pi's transformContext can't
 				// mutate the shared reference across replays (audit P3).
-				const replayView = [{ ...runtime.trimCache.summaryAgentMsg }, ...recent];
+				const replayView = [
+					{ ...runtime.trimCache.summaryAgentMsg },
+					...recent,
+				];
 				return tailResult(replayView) ?? { messages: replayView };
 			}
 			// else: context grew enough → fall through to re-compact (cache is stale)
@@ -330,7 +361,15 @@ export function registerContextHandler(
 				// model is fed a raw overflow that errors every turn — the
 				// "Already compacted" + overflow death-spiral (2026-08-01 incident).
 				// A thin anchor is recoverable; an overflowed session is not.
-				criticalOver: (pct ?? 0) >= 90,
+				//
+				// CRITICAL: pct is null for OpenAI-compatible providers that don't
+				// report usage.percent (e.g. neuralwatt). Without the token-pressure
+				// fallback the hatch never armed → cut=null → raw overflow → 400
+				// "conversation too long even after compaction" (2026-08-03 incident
+				// on glm-5.2-short, 200K window). Now also fires on pressure >= 0.9
+				// (token-basis) so the hatch arms regardless of whether the provider
+				// reports pct.
+				criticalOver: (pct ?? 0) >= 90 || pressure >= 0.9,
 			});
 			if (cut === null) {
 				runtime.diagCtxCutNull++;
@@ -357,7 +396,73 @@ export function registerContextHandler(
 				// on every replay within the same compaction epoch.
 				timestamp: runtime.rt.lastCompactAt ?? Date.now(),
 			} as unknown as AgentMessage;
-			const recent = messages.slice(cut); // guardrails-allow PREVENT-PI-002: `cut` is the pre-sanitized `compactedFrom` produced by src/boundary.ts computeDropRange, so the preserved run begins on a toolPair-safe index.
+			const recentRaw = messages.slice(cut); // guardrails-allow PREVENT-PI-002: `cut` is the pre-sanitized `compactedFrom` produced by src/boundary.ts computeDropRange, so the preserved run begins on a toolPair-safe index.
+
+			// FIX 2 (2026-08-03 incident): TOKEN-BUDGET CAP on the live-trim view.
+			// Compaction fires at tier% of the window (140K for a 200K window),
+			// but a SINGLE turn can inject a huge tool output (file read, bash) that
+			// jumps context from 139K → 199K+ before the next gate fires. When that
+			// happens [summary + preserved tail] can STILL exceed the model window,
+			// and the provider rejects with 400 "conversation too long even after
+			// compaction". The anchor floor (PREVENT-PI-001) keeps ≥N user messages
+			// but has NO token cap, so a 2-message tail of two 80K bash outputs sails
+			// right past the window.
+			//
+			// Cap: when the model context window is known, reserve room for the
+			// summary + the model's max output tokens + a 10% safety margin, then
+			// drop oldest preserved messages from the front of `recentRaw` until the
+			// tail fits. Never drops below the FINAL message (always keep the latest
+			// turn so the agent can respond). This is a last-resort HARD cap — it
+			// only fires when the preserved tail alone is oversized, which is rare.
+			const ctxWindow = runtime.lastCtxWindow;
+			// Reuse the per-model threshold resolved at the gate (single lookup).
+			const modelThreshold = _perModelThreshold;
+			// Reserve room for output tokens. Use the model's reported max output
+			// when known; fall back to 10% of the window (scales with any model —
+			// 20K for a 200K window, 100K for a 1M window) so we never let the
+			// preserved tail eat the model's output budget when maxTokens is unknown.
+			const maxOutput =
+				runtime.currentModel?.maxTokens && runtime.currentModel.maxTokens > 0
+					? runtime.currentModel.maxTokens
+					: Math.ceil(ctxWindow * 0.1);
+			let recent = recentRaw;
+			if (ctxWindow > 0 && recentRaw.length > 1) {
+				const summaryTokens = estimateBlockTokens(summaryMsg.text);
+				// Reserve: summary + max output + per-model safety margin (0-20%).
+				const safetyMargin = Math.ceil(
+					ctxWindow * (modelThreshold.safetyMarginPct / 100),
+				);
+				const budget = ctxWindow - maxOutput - safetyMargin - summaryTokens;
+				if (budget > 0) {
+					// Walk recent from the front, dropping oldest first until the
+					// remaining tail fits. Use the AgentMessage→engine-text estimate via
+					// messageContentText (already imported) + estimateMessageTokens.
+					let tailTokens = 0;
+					for (let i = recentRaw.length - 1; i >= 0; i--) {
+						const m = recentRaw[i];
+						tailTokens += estimateMessageTokens({
+							text: messageContentText(m),
+						});
+						if (tailTokens > budget) {
+							// Keep from i+1 onward; but never fewer than the final message.
+							const startIdx = Math.min(i + 1, recentRaw.length - 1);
+							if (startIdx > 0) {
+								recent = recentRaw.slice(startIdx);
+								runtime.logger.warn("live-trim-tail-cap", {
+									sessionId: runtime.rt.sessionId,
+									dropped: startIdx,
+									tailTokens,
+									safetyMarginPct: modelThreshold.safetyMarginPct,
+									budget,
+									ctxWindow,
+								});
+							}
+							break;
+						}
+					}
+				}
+			}
+
 			// v0.8.6: cache the trim view so subsequent gated calls in this epoch
 			// replay it verbatim (stabilizing the KV-cache prefix) instead of
 			// regenerating a fresh summary + sentinel every fire.
@@ -396,7 +501,11 @@ export function registerContextHandler(
 				ctxPct: pct,
 				ctxTokens: usage?.tokens ?? null,
 			});
-			return tailResult([summaryAgentMsg, ...recent]) ?? { messages: [summaryAgentMsg, ...recent] };
+			return (
+				tailResult([summaryAgentMsg, ...recent]) ?? {
+					messages: [summaryAgentMsg, ...recent],
+				}
+			);
 		} catch {
 			runtime.diagCtxThrown++;
 			return tailResult() ?? undefined; // non-fatal: no trim this call; the next context event retries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.15.4",
+  "version": "0.16.1",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",