dsh-switchman 1.9.0 → 1.10.2

package/host/context-trim/index.js

@@ -30,8 +30,9 @@ import { buildView, estimateTokensOf, injectView, ledgerIsStale, rangeIsSegmentA
 import { computeFoldableRange, evaluateTrigger, EMERGENCY_COOLDOWN_MS } from "./trigger.js";
 import { mechanicalSummary, renderMaterial, summarizeWithModel } from "./summarizer.js";
 import { createStore } from "./state.js";
-import { createMetrics, extractUsage, wrapStreamForMetrics } from "./metrics.js";
+import { createMetrics, extractUsage, promptTokensOf, wrapStreamForMetrics } from "./metrics.js";
 import { forkLinkOf, loadForkLinks, recordForkLink, resolveInheritance, INHERIT_WINDOW_MS } from "./fork.js";
+import { createSurfaceFoldPass } from "./surface.js";
 import { childSessionIdOf } from "../subagent-model.js";
 
 // ---- agent reference helpers --------------------------------------------------
@@ -47,24 +48,73 @@ import { childSessionIdOf } from "../subagent-model.js";
 // stored tally while it is fresh, so the watermark tracks what the model
 // actually sees after billion-context folding instead of over-triggering
 // handovers off a stale stored measure.
-const trimViewBySession = new Map(); // sessionId -> { viewTokens, at }
+const trimViewBySession = new Map(); // sessionId -> { viewTokens, at, inject, lastNoneAt }
+/** Freshness TTL for the in-memory view/injection registry (watermark and
+ *  banner display only). NEVER a fold gate: gating folds on "did the surface
+ *  channel ship recently" deadlocks resumed sessions (2026-11-05). The fold
+ *  gate asks surfacePass.supported() — a durable capability question. */
 const TRIM_VIEW_MAX_AGE_MS = 600_000; // 10 minutes
 
+/** Dispatches below this message count are never treated as the session's
+ *  main history (the side-dispatch guard in applyViewToOptions): auxiliary
+ *  llm calls (web-search summaries, title generation) inherit the session id
+ *  with 1-6 message arrays and would clobber every per-session meter. */
+const SIDE_DISPATCH_MIN_MESSAGES = 12;
+
+/** Consecutive side-dispatch skips tolerated before one is accepted as the
+ *  main history anyway — the release valve for a genuine host-compaction
+ *  epoch that shrank the history below SIDE_DISPATCH_MIN_MESSAGES (without
+ *  it the guard would stick: no capture refresh, no epoch reset, folds run
+ *  against a stale capture forever). */
+const SIDE_DISPATCH_SKIP_BUDGET = 2;
+
+/** Consecutive side-dispatch skips per session (bounded; reset on every
+ *  accepted main dispatch). */
+const sideDispatchSkipsBySession = new Map();
+
 /** Most recent outbound-view token estimate for a session, or null when
- * missing, non-positive, or older than maxAgeMs. Read by the watermark
- * layer (meter duality); itself fail-open. */
+ * missing, non-positive, older than maxAgeMs — or when the recent dispatch
+ * stream could not carry the view (injected "none": frozen options AND
+ * messages, so the model still receives the raw history and the provider
+ * tally is the only truthful meter). The gate is deliberately sticky: a
+ * single mutable dispatch right after frozen ones re-arms maybeFold, but
+ * the WATERMARK keeps falling back to the tally until no "none" occurred
+ * within the TTL window (mixed sessions exist — one real session logged 46
+ * none + 14 swapped). Read by the watermark layer (meter duality); itself
+ * fail-open. */
 export function recentTrimViewTokensOf(sessionId, maxAgeMs = TRIM_VIEW_MAX_AGE_MS) {
 	try {
 		if (typeof sessionId !== "string" || sessionId === "") return null;
 		const entry = trimViewBySession.get(sessionId);
 		if (entry === undefined) return null;
 		if (Date.now() - entry.at > maxAgeMs) return null;
+		// Wire-truth gate: a view that never reaches the wire must not drive
+		// the watermark (observed 2026-11-04: view ~80k vs a 176k wire while
+		// the force tier stayed silent and the auto-handover never fired).
+		if (entry.inject === "none") return null;
+		if (Number.isFinite(entry.lastNoneAt) && entry.lastNoneAt > 0 && Date.now() - entry.lastNoneAt < maxAgeMs) return null;
 		return Number.isFinite(entry.viewTokens) && entry.viewTokens > 0 ? entry.viewTokens : null;
 	} catch {
 		return null;
 	}
 }
 
+/** Injection outcome of the last dispatch for one session ("in-place" |
+ * "swapped" | "none"), or null when unknown or stale. Read by maybeFold:
+ * when the wire cannot carry the view, folding cannot relieve anything and
+ * only burns a summarizer call — the watermark's tally-driven auto-handover
+ * is the correct relief path instead. */
+export function recentTrimInjectOf(sessionId, maxAgeMs = TRIM_VIEW_MAX_AGE_MS) {
+	try {
+		if (typeof sessionId !== "string" || sessionId === "") return null;
+		const entry = trimViewBySession.get(sessionId);
+		if (entry === undefined || Date.now() - entry.at > maxAgeMs) return null;
+		return typeof entry.inject === "string" ? entry.inject : null;
+	} catch {
+		return null;
+	}
+}
+
 export function agentSessionIdOf(agent) {
 	if (typeof agent === "string") return agent !== "" ? agent : null;
 	if (agent !== null && typeof agent === "object") {
@@ -160,8 +210,11 @@ export function effectiveWindowTokens(resolved, cap) {
 }
 
 /** Live context line renderer (pure; exported for tests). Silent in "off"
- * mode and whenever nothing has been measured yet. */
-export function renderTrimContextLine(agent, { enabled, mode, viewTokens, windowTokens, folds, growthTokens, lastModel }) {
+ * mode and whenever nothing has been measured yet. wireRaw marks a session
+ * whose last dispatch could not carry the fold view (frozen request) — the
+ * displayed view is then meter-only and the watermark governs off the
+ * provider tally. */
+export function renderTrimContextLine(agent, { enabled, mode, viewTokens, windowTokens, folds, growthTokens, lastModel, wireRaw = false }) {
 	if (!enabled) return "";
 	if (mode === "off") return "";
 	if (agent === null || agent === undefined || agent === "") return "";
@@ -175,6 +228,7 @@ export function renderTrimContextLine(agent, { enabled, mode, viewTokens, window
 		if (Number.isFinite(windowTokens) && windowTokens > 0) usage = ` (${Math.round((viewTokens / windowTokens) * 100)}% of window ${kilo(windowTokens)})`;
 		else usage = " (window unknown — pressure tiers off)";
 		parts.push(`view ~${kilo(viewTokens)} tokens${usage}`);
+		if (wireRaw) parts.push("wire=raw (folds not shipping; watermark reads the tally)");
 	}
 	if (hasFolds) {
 		parts.push(`folds ${folds}`);
@@ -203,7 +257,56 @@ export function applyContextTrim(ctx, config) {
 	// Per-process pipeline state (process-wide by design: ledgers persist on
 	// disk per session, metrics/captures live per session in memory).
 	const store = createStore({ stateDir: readString(config, "trimStateDir", null) ?? undefined, warn });
+
+	// Surface-replace pass (docs/surface-fold.md): ships committed fold blocks
+	// onto the session surface so folds reach the wire even for frozen
+	// dispatches. Registers its own agent/turn-stopping trigger; the idle
+	// sweep below runs after each fold cycle.
+	const surfacePass = createSurfaceFoldPass({ ctx, config, store, decisionLog, warn });
+
+	// Durable capability probe (surface.js supported): the fold gate asks THIS,
+	// never a recency window. An in-memory "did we ship in the last 10 minutes"
+	// test deadlocked resumed sessions: dispatches report injected=none, so
+	// after the window expired no fold ran, no fold meant no new ship, and the
+	// gate stayed shut forever while the provider prompt grew to 135k.
+	const surfaceChannelCapable = (sessionId) => {
+		try {
+			return surfacePass.supported(sessionId);
+		} catch {
+			return false;
+		}
+	};
+	// Durable surface-channel EVIDENCE for the banner: a block that already
+	// SHIPPED a replacement (surfaceReplaced) proves the channel reaches the
+	// wire, even across a process restart and after the in-memory recency
+	// window expired. A commit-time capture (surfaceSeqs) does NOT — the block
+	// may never ship, and a capture must not silence the honest wire=raw
+	// warning. Display only — the fold gate uses the live capability probe.
+	const ledgerShowsShippedReplacement = (sessionId) => {
+		try {
+			const blocks = store.ledgerOf(sessionId)?.blocks;
+			if (!Array.isArray(blocks)) return false;
+			return blocks.some((block) => block?.surfaceReplaced !== null && block?.surfaceReplaced !== undefined);
+		} catch {
+			return false;
+		}
+	};
 	const metrics = createMetrics();
+
+	/** Most recent provider prompt size for one session, or null when unknown.
+	 * The tally is the FULL prompt: the host reports TokenUsage as
+	 * { inputTokens (uncached), cacheReadTokens, cacheWriteTokens }, so a
+	 * heavily cached session (~130k of 136k cached) would otherwise read as
+	 * the uncached delta and keep max(view, wire) silent. The view estimate
+	 * only counts the messages array, so it under-reports by the system and
+	 * context sections; pressure tiers must not run blind on it. */
+	const wireTokensOf = (sessionId) => {
+		try {
+			return promptTokensOf(metrics.of(sessionId));
+		} catch {
+			return null;
+		}
+	};
 	const captures = new Map(); // sessionId -> { messages, refs, viewTokens, model, at }
 	const inFlight = new Set(); // sessionIds with a fold running
 	const windowCache = new Map(); // "provider/model" -> { windowTokens, at }
@@ -211,6 +314,37 @@ export function applyContextTrim(ctx, config) {
 	const lastStreamCheckAt = new Map(); // sessionId -> epoch ms of last stream-path fold check (throttle)
 	const epochResetDoneBySession = new Map(); // sessionId -> ledger-stale baseline reset already done for this host epoch (cleared when a fold applies again)
 
+	// Per-session fold-failure cooldown: a failing summarize/commit cycle
+	// advances NONE of the cadence gates (lastFoldAt / foldsThisHour only
+	// move on a successful commitFold), so without this the same failure
+	// re-fires at every idle boundary plus every >=60s stream check forever.
+	// In-memory only by design — a process restart re-arms the cycle open.
+	const foldFailureBySession = new Map(); // sessionId -> { count, lastAt }
+	const FOLD_FAILURE_BASE_MS = 60_000; // backoff ladder start (2^(n-1) growth)
+	const FOLD_FAILURE_MAX_MS = 900_000; // 15 min ceiling
+
+	/** Record one failed fold cycle (summary unavailable / commit rejected /
+	 * thrown): consecutive-attempt count + timestamp drive the backoff. */
+	function recordFoldFailure(sessionId) {
+		const prior = foldFailureBySession.get(sessionId);
+		foldFailureBySession.set(sessionId, { count: Math.min((prior?.count ?? 0) + 1, 16), lastAt: Date.now() });
+		if (foldFailureBySession.size > 200) foldFailureBySession.delete(foldFailureBySession.keys().next().value);
+	}
+
+	/** Remaining cooldown ms for one session (0 when not cooling): the delay
+	 * doubles per consecutive failure from 60s, capped at 15 min. */
+	function foldFailureCooldownOf(sessionId, now = Date.now()) {
+		const entry = foldFailureBySession.get(sessionId);
+		if (entry === undefined || entry.count <= 0) return 0;
+		const backoff = Math.min(FOLD_FAILURE_BASE_MS * 2 ** (entry.count - 1), FOLD_FAILURE_MAX_MS);
+		return Math.max(0, entry.lastAt + backoff - now);
+	}
+
+	/** A committed fold resets the failure ladder. */
+	function clearFoldFailure(sessionId) {
+		foldFailureBySession.delete(sessionId);
+	}
+
 	/** Append one fold-decision line to <stateDir>/decisions.log (fail-open,
 	 * best-effort observability — console warn stays reserved for outcomes). */
 	function decisionLog(entry) {
@@ -399,10 +533,42 @@ export function applyContextTrim(ctx, config) {
 		const injected = injectView(options, messages, view);
 		const viewTokens = estimateTokensOf(view.messages);
 		const blocksCount = Array.isArray(ledger.blocks) ? ledger.blocks.length : 0;
+		// Wire truth in the row: the most recent provider prompt size (from the
+		// previous response's usage) makes the view-vs-wire divergence visible
+		// instead of leaving the view estimate as the only lullaby in the log.
+		const wireTokens = wireTokensOf(sessionId);
 		// Per-request application evidence: whether the ledger's blocks actually
 		// locate inside THIS re-send (the host may compact/replace history, in
 		// which case applied=0 explains a stuck-high view without any failure).
-		decisionLog(`session=${sessionId} view-applied applied=${view.applied} foldedMsgs=${view.foldedMessages} view=${Math.round(viewTokens)} blocks=${blocksCount} injected=${injected}`);
+		decisionLog(`session=${sessionId} view-applied applied=${view.applied} foldedMsgs=${view.foldedMessages} view=${Math.round(viewTokens)} blocks=${blocksCount} injected=${injected}${wireTokens === null ? "" : ` wire=${wireTokens}`}`);
+		// Side-dispatch guard: auxiliary llm calls that inherit the session id
+		// (web-search summaries, title generation, fold-span material) present
+		// tiny arrays in which the ledger cannot locate. Accepting them as the
+		// session view clobbers the capture, the cross-layer registry that
+		// measureNow reads, and the growth baseline (observed 2026-11-04: a
+		// baseline reset to ~150 tokens mid-session). Fold-span dispatches are
+		// already covered by inFlight. A tiny dispatch is a side candidate
+		// whenever the session ALREADY carries trim state — fold blocks, a
+		// capture, or a view registry entry — regardless of blocksCount,
+		// which is exactly 0 in the young zero-fold sessions an auxiliary
+		// dispatch most often hits. A session's very FIRST dispatch is
+		// indistinguishable from a real one and stays accepted: it cannot
+		// clobber state that does not exist yet, and the next real dispatch
+		// overwrites the capture. A genuine host-compaction epoch ALSO shrinks
+		// history below the floor, so the guard must not stick: after
+		// SIDE_DISPATCH_SKIP_BUDGET consecutive skips the dispatch is accepted
+		// as main, which re-arms capture/baseline on the compacted history.
+		const sideCandidate = inFlight.has(sessionId)
+			|| (view.applied === 0 && messages.length < SIDE_DISPATCH_MIN_MESSAGES && (blocksCount > 0 || captures.has(sessionId) || trimViewBySession.has(sessionId)));
+		const skipCount = sideDispatchSkipsBySession.get(sessionId) ?? 0;
+		if (sideCandidate && skipCount < SIDE_DISPATCH_SKIP_BUDGET) {
+			sideDispatchSkipsBySession.set(sessionId, skipCount + 1);
+			if (sideDispatchSkipsBySession.size > 200) sideDispatchSkipsBySession.delete(sideDispatchSkipsBySession.keys().next().value);
+			decisionLog(`session=${sessionId} side-dispatch skipped n=${skipCount + 1} msgs=${messages.length} view=${Math.round(viewTokens)} blocks=${blocksCount}`);
+			return { sessionId, viewTokens, sideDispatch: true };
+		}
+		if (sideCandidate) decisionLog(`session=${sessionId} side-dispatch budget exhausted — accepting as main msgs=${messages.length}`);
+		sideDispatchSkipsBySession.delete(sessionId);
 		// Host-compaction epoch boundary: every block failed to LOCATE inside
 		// this re-send, so the ledger aged out as a whole. Re-anchor the growth
 		// baseline at the true post-epoch view once per epoch — carrying the
@@ -424,7 +590,9 @@ export function applyContextTrim(ctx, config) {
 		const model = { provider: options.provider ?? null, model: options.model ?? null };
 		captureOf(sessionId, rawSnapshot, model, viewTokens);
 		metrics.noteView(sessionId, viewTokens, model);
-		trimViewBySession.set(sessionId, { viewTokens, at: Date.now() });
+		const priorEntry = trimViewBySession.get(sessionId);
+		const lastNoneAt = injected === "none" ? Date.now() : Number.isFinite(priorEntry?.lastNoneAt) ? priorEntry.lastNoneAt : 0;
+		trimViewBySession.set(sessionId, { viewTokens, at: Date.now(), inject: injected, lastNoneAt });
 		// keep the view registry bounded (200 sessions, same as captures)
 		if (trimViewBySession.size > 200) {
 			const oldest = trimViewBySession.keys().next().value;
@@ -459,6 +627,13 @@ export function applyContextTrim(ctx, config) {
 		let summary = null;
 		let kind = "summary";
 		if (decision.action === "emergency") {
+			// Emergency cooldown timestamp set BEFORE the cycle: a commitFold
+			// rejection (e.g. duplicate-range) must cool the emergency tier
+			// down like a success, or a rejected emergency fold retries at
+			// every idle boundary forever. The 90s trigger gate semantics
+			// (EMERGENCY_COOLDOWN_MS) stay untouched.
+			lastEmergencyAtBySession.set(sessionId, Date.now());
+			if (lastEmergencyAtBySession.size > 200) lastEmergencyAtBySession.delete(lastEmergencyAtBySession.keys().next().value);
 			summary = mechanicalSummary(capture.messages, startIdx, endIdx, refOf);
 			kind = "mechanical";
 		} else {
@@ -476,14 +651,16 @@ export function applyContextTrim(ctx, config) {
 			positions,
 		);
 		if (!result.ok) return `commit-rejected:${result.reason}`;
+		// Commit-time surface capture (primary range-mapping strategy, see
+		// surface.js header): store the covered event seqs while the live
+		// surface still resolves the folded range.
+		surfacePass.captureFoldSeqs(sessionId, result.block);
 		// Growth-gate baseline pair: pre-fold view (banner display) plus the
 		// post-fold low (tier-a anchor — keeps the gate armed after folds
 		// that commit at high view points).
 		const lowLedger = store.ledgerOf(sessionId);
 		const lowView = estimateTokensOf(buildView(capture.messages, lowLedger, { protectedTail: thresholdsNow().protectedTail }).messages);
 		store.recordFoldBaseline(sessionId, capture.viewTokens, lowView);
-		if (decision.action === "emergency") lastEmergencyAtBySession.set(sessionId, Date.now());
-		if (lastEmergencyAtBySession.size > 200) lastEmergencyAtBySession.delete(lastEmergencyAtBySession.keys().next().value);
 		return `folded:${decision.tier}:${count} msgs (~${approxTokens} tokens)`;
 	}
 
@@ -494,18 +671,42 @@ export function applyContextTrim(ctx, config) {
 		if (sessionId === null || sessionId === undefined || sessionId === "") return;
 		if (!enabledNow() || modeNow() !== "auto") return;
 		if (inFlight.has(sessionId)) return;
+		// Failure backoff: a session whose recent cycles failed stays quiet
+		// for 60s*2^(n-1) (cap 15 min) instead of re-firing at every idle
+		// boundary and stream check. Silent gate — the outcome row that armed
+		// the cooldown is already in decisions.log.
+		if (foldFailureCooldownOf(sessionId) > 0) return;
 		const capture = captures.get(sessionId);
 		if (capture === undefined) return;
+		// Injection-unavailable: the last dispatch could not carry the view
+		// (frozen options AND messages — the wire always ships raw history).
+		// Folding is pointless ONLY when NEITHER channel can reach the wire:
+		// the spliced view (inject !== "none") OR the surface-replace pass
+		// (durable capability probe, not a recency window — a proven channel
+		// that last shipped before the process restarted is still capable and
+		// the next fold ships a fresh surface event). When neither can, the
+		// watermark's tally-driven force tier + auto-handover is the relief
+		// path.
+		if (recentTrimInjectOf(sessionId) === "none" && !surfaceChannelCapable(sessionId)) {
+			decisionLog(`session=${sessionId} via=${via} action=none reason=injection-unavailable view=${Math.round(capture.viewTokens)}`);
+			return;
+		}
 		inFlight.add(sessionId);
 		try {
 			const { protectedTail, ...thresholds } = thresholdsNow();
 			const foldable = computeFoldableRange(capture.messages, store.ledgerOf(sessionId), protectedTail);
 			const windowTokens = await windowTokensFor(capture.model);
 			const ledger = store.ledgerOf(sessionId);
+			// Pressure tiers run on the REAL prompt size when the tally is known:
+			// max(view, wire). The view estimate misses the system/context
+			// sections, so a 136k wire once read as a 50k view and the tiers
+			// stayed silent. Unknown tally → exactly today's behavior.
+			const wireTokens = wireTokensOf(sessionId);
+			const pressureTokens = wireTokens !== null ? Math.max(capture.viewTokens, wireTokens) : capture.viewTokens;
 			const decision = evaluateTrigger({
 				foldable,
 				messages: capture.messages,
-				viewTokens: capture.viewTokens,
+				viewTokens: pressureTokens,
 				windowTokens,
 				thresholds,
 				now: Date.now(),
@@ -514,15 +715,21 @@ export function applyContextTrim(ctx, config) {
 				lastEmergencyAt: lastEmergencyAtBySession.get(sessionId) ?? 0,
 				ledger,
 			});
-			decisionLog(`session=${sessionId} via=${via} action=${decision.action} tier=${decision.tier ?? "-"} reason=${decision.reason || "-"} view=${Math.round(capture.viewTokens)} window=${windowTokens ?? "null"}`);
+			decisionLog(`session=${sessionId} via=${via} action=${decision.action} tier=${decision.tier ?? "-"} reason=${decision.reason || "-"} view=${Math.round(capture.viewTokens)}${wireTokens === null ? "" : ` wire=${wireTokens}`} window=${windowTokens ?? "null"}`);
 			if (decision.action === "none") return;
 			const outcome = await runFoldCycle(sessionId, decision);
+			// Failure ladder: commit resets it; a summarize/commit failure
+			// climbs it (the no-backoff loop this closes — those outcomes
+			// advance no cadence gate on their own).
+			if (outcome.startsWith("folded:")) clearFoldFailure(sessionId);
+			else if (outcome === "summary-unavailable" || outcome.startsWith("commit-rejected:")) recordFoldFailure(sessionId);
 			// Outcome lands in the decision log too: warn() has no reachable
 			// sink on some hosts, and the commit/fail boundary is exactly what
 			// live diagnosis needs.
 			decisionLog(`session=${sessionId} outcome=${outcome} tier=${decision.tier}`);
 			warn(`[context-trim] ${sessionId}: ${outcome} (${decision.reason})`);
 		} catch (error) {
+			recordFoldFailure(sessionId); // a thrown cycle counts as failed too
 			warn(`[context-trim] fold cycle failed: ${error?.message ?? error}`);
 		} finally {
 			inFlight.delete(sessionId);
@@ -554,7 +761,13 @@ export function applyContextTrim(ctx, config) {
 					const model = captureModelOf(sessionId);
 					const windowTokens = model === null ? null : cachedWindowOf(model);
 					const growthBaseline = ledger !== null && Number.isFinite(ledger.lastFoldLowTokens) && ledger.lastFoldLowTokens > 0 ? ledger.lastFoldLowTokens : ledger !== null && Number.isFinite(ledger.lastFoldViewTokens) && ledger.lastFoldViewTokens > 0 ? ledger.lastFoldViewTokens : null;
-return renderTrimContextLine(label, {
+					// Honest wire status: the wire is only "raw" when NEITHER channel
+					// can reach it — a capable surface pass, or a ledger that already
+					// proves a SHIPPED replacement (a capture alone does not: it may
+					// never ship), keeps the marker off even after the in-memory
+					// recency window expired.
+					const wireRaw = recentTrimInjectOf(sessionId) === "none" && !surfaceChannelCapable(sessionId) && !ledgerShowsShippedReplacement(sessionId);
+					return renderTrimContextLine(label, {
 						enabled: enabledNow(),
 						mode: modeNow(),
 						viewTokens: record?.viewTokens ?? null,
@@ -562,6 +775,7 @@ return renderTrimContextLine(label, {
 						folds: Array.isArray(ledger?.blocks) ? ledger.blocks.length : 0,
 						growthTokens: record?.viewTokens !== null && record !== undefined && growthBaseline !== null ? record.viewTokens - growthBaseline : null,
 						lastModel: record?.lastModel ?? null,
+						wireRaw,
 					});
 				} catch {
 					return "";
@@ -590,7 +804,16 @@ return renderTrimContextLine(label, {
 				// agent }) — derive the session id per host/context-watch.js:122.
 				const sessionId = agentSessionIdOf(payload?.agent);
 				if (sessionId === null) return;
-				void maybeFold(sessionId);
+				// Fold first, then the surface-replace idle sweep (design
+				// docs/surface-fold.md): a block committed by this idle pass
+				// ships on the same boundary.
+				void maybeFold(sessionId).finally(() => {
+					try {
+						void surfacePass.sweep(sessionId, "idle");
+					} catch {
+						/* sweep must never break the idle hook */
+					}
+				});
 			} catch {
 				/* idle hook must never throw */
 			}
@@ -727,6 +950,7 @@ return renderTrimContextLine(label, {
 					positions,
 				);
 				if (!result.ok) return `Fold rejected: ${result.reason}.`;
+				surfacePass.captureFoldSeqs(sessionId, result.block);
 				// Growth-gate baseline pair: pre-fold view (banner display) plus the
 				// post-fold low (tier-a anchor — keeps the gate armed after folds
 				// that commit at high view points).
@@ -826,5 +1050,5 @@ return renderTrimContextLine(label, {
 		warn(`[context-trim] ctx.inject(llm) failed: ${error?.message ?? error}`);
 	}
 
-	return { store, metrics, captures, inFlight, maybeFold, maybeInherit, applyViewToOptions, renderTrimContextLine: (agent) => renderTrimContextLine(agent, { enabled: enabledNow(), mode: modeNow(), viewTokens: null, windowTokens: null, folds: 0, growthTokens: null, lastModel: null }) };
+	return { store, metrics, captures, inFlight, maybeFold, maybeInherit, applyViewToOptions, surfacePass, renderTrimContextLine: (agent) => renderTrimContextLine(agent, { enabled: enabledNow(), mode: modeNow(), viewTokens: null, windowTokens: null, folds: 0, growthTokens: null, lastModel: null, wireRaw: false }) };
 }

package/host/context-trim/metrics.js

@@ -10,28 +10,50 @@
  */
 
 /** Extract usage fields from a stream chunk. Returns
- * { inputTokens, cachedTokens, outputTokens } or null when the chunk
- * carries none. Defensive field walk — providers shape usage differently
- * (usage.input_tokens, usage.prompt_tokens, cached_tokens,
- * cache_read_input_tokens, ...). */
+ * { inputTokens, cachedTokens, cacheWriteTokens, outputTokens } or null when
+ * the chunk carries none. Defensive field walk — providers shape usage
+ * differently (usage.input_tokens, usage.prompt_tokens, cached_tokens,
+ * cache_read_input_tokens, ...).
+ *
+ * Two shapes matter here. The host's own stream chunks carry a normalized
+ * TokenUsage ({ inputTokens, cacheReadTokens, cacheWriteTokens, ... }) where
+ * inputTokens counts UNCACHED prompt tokens only — the camelCase buckets do
+ * not overlap (llm-deepseek/src/translate.ts). Raw provider payloads use the
+ * snake_case twins, which on the Anthropic side have the same meaning. Only
+ * the OpenAI-style prompt_tokens shape would make inputTokens the inclusive
+ * total; summing there would over-count the prompt, which merely folds
+ * earlier — the safe direction for this plugin. */
 export function extractUsage(chunk) {
 	if (chunk === null || typeof chunk !== "object") return null;
 	const candidates = [chunk.usage, chunk.metadata?.usage, chunk.response?.usage];
 	for (const usage of candidates) {
 		if (usage === null || typeof usage !== "object") continue;
 		const input = usage.input_tokens ?? usage.prompt_tokens ?? usage.inputTokens;
-		const cached = usage.cache_read_input_tokens ?? usage.cached_tokens ?? usage.cachedTokens ?? usage.prompt_tokens_details?.cached_tokens;
+		const cached = usage.cache_read_input_tokens ?? usage.cached_tokens ?? usage.cachedTokens ?? usage.cacheReadTokens ?? usage.prompt_tokens_details?.cached_tokens;
+		const cacheWrite = usage.cache_creation_input_tokens ?? usage.cache_write_tokens ?? usage.cacheWriteTokens;
 		const output = usage.output_tokens ?? usage.completion_tokens ?? usage.outputTokens;
-		if (!Number.isFinite(input) && !Number.isFinite(cached) && !Number.isFinite(output)) continue;
+		if (!Number.isFinite(input) && !Number.isFinite(cached) && !Number.isFinite(cacheWrite) && !Number.isFinite(output)) continue;
 		return {
 			inputTokens: Number.isFinite(input) ? input : null,
 			cachedTokens: Number.isFinite(cached) ? cached : null,
+			cacheWriteTokens: Number.isFinite(cacheWrite) ? cacheWrite : null,
 			outputTokens: Number.isFinite(output) ? output : null,
 		};
 	}
 	return null;
 }
 
+/** Total prompt tokens for one metrics record: uncached input + cache read +
+ * cache write (host TokenUsage buckets do not overlap). Null when no input
+ * sample has ever been recorded — callers must treat unknown as "no wire
+ * signal" and stay on the view estimate. Missing cache buckets count as 0. */
+export function promptTokensOf(record) {
+	if (record === null || record === undefined) return null;
+	if (!Number.isFinite(record.lastInputTokens)) return null;
+	const total = record.lastInputTokens + (Number.isFinite(record.cachedTokens) ? record.cachedTokens : 0) + (Number.isFinite(record.cacheWriteTokens) ? record.cacheWriteTokens : 0);
+	return total > 0 ? Math.round(total) : null;
+}
+
 /** Per-session metrics store. */
 export function createMetrics() {
 	const sessions = new Map(); // sessionId -> record
@@ -40,8 +62,9 @@ export function createMetrics() {
 		let record = sessions.get(sessionId);
 		if (record === undefined) {
 			record = {
-				lastInputTokens: null,
-				cachedTokens: null,
+				lastInputTokens: null, // UNCACHED prompt tokens of the last sample
+				cachedTokens: null, // cache-read bucket of the last sample
+				cacheWriteTokens: null, // cache-write bucket of the last sample
 				outputTokens: null,
 				viewTokens: null, // view estimate noted by the listener pre-request
 				lastModel: null, // { provider, model } of the last stream
@@ -75,6 +98,7 @@ export function createMetrics() {
 			const record = recordOf(sessionId);
 			if (usage.inputTokens !== null) record.lastInputTokens = usage.inputTokens;
 			if (usage.cachedTokens !== null) record.cachedTokens = usage.cachedTokens;
+			if (usage.cacheWriteTokens !== null) record.cacheWriteTokens = usage.cacheWriteTokens;
 			if (usage.outputTokens !== null) record.outputTokens = usage.outputTokens;
 			return record;
 		},

package/host/context-trim/summarizer.js

@@ -97,7 +97,7 @@ export function renderMaterial(messages, startIdx, endIdx, refOf) {
 		parts.push(head + body);
 		chars += head.length + body.length;
 	}
-	if (truncated) parts.push(`--- [...material truncated after ${chars} chars; ${endIdx - startIdx + 1 - (parts.length - 1)} messages dropped from this render...] ---\n`);
+	if (truncated) parts.push(`--- [...material truncated after ${chars} chars; ${endIdx - startIdx + 1 - parts.length} messages dropped from this render...] ---\n`);
 	return parts.join("");
 }