dsh-switchman 1.11.5 → 1.11.7

package/host/context-trim/index.js

@@ -24,15 +24,16 @@
  *
  * Config fields (host/config.js, all volatile): trimEnabled, trimMode
  * ("off"|"advisory"|"auto"), trimGrowthTokens, trimIncrementTokens,
- * trimPressurePercent, trimEmergencyPercent, trimWindowTokens,
+ * trimPressurePercent, trimEmergencyPercent, trimAdvisoryPercent,
+ * trimAdvisoryCriticalPercent, trimWindowTokens,
  * trimProtectedTail, trimMaxFoldsPerHour, trimSideModel, trimFoldFallbackModel, trimStateDir,
  * trimLadderEnabled, trimLadderT2Tokens, trimLadderT2MinBlocks,
  * trimLadderT3Tokens, trimLadderT3MinBlocks.
  */
 
-import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { buildView, estimateTokensOf, injectView, ledgerIsStale, messageTokens, rangeIsSegmentAligned, refOf, refPositions } from "./view.js";
+import { appendFileSync, mkdirSync, realpathSync, renameSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { buildView, estimateTokensOf, injectView, isFoldSummaryMessage, ledgerIsStale, messageTokens, rangeIsSegmentAligned, refOf, refPositions } from "./view.js";
 import { computeFoldableRange, evaluateTrigger, EMERGENCY_COOLDOWN_MS } from "./trigger.js";
 import { LADDER_SYSTEM_PROMPT, mechanicalSummary, renderLadderMaterial, renderMaterial, summarizeWithModel } from "./summarizer.js";
 import { createStore } from "./state.js";
@@ -40,6 +41,46 @@ import { createMetrics, extractUsage, promptTokensOf, wrapStreamForMetrics } fro
 import { forkLinkOf, loadForkLinks, recordForkLink, resolveInheritance, INHERIT_WINDOW_MS } from "./fork.js";
 import { createSurfaceFoldPass } from "./surface.js";
 import { childSessionIdOf } from "../subagent-model.js";
+import { tmpdir } from "node:os";
+import { dshHome } from "../lib/dsh-home.js";
+import { fileURLToPath } from "node:url";
+
+// Module build stamp ([2026-11-15]-[stale-module observability]): the
+// per-dispatch view-applied row carries it, so a host process still
+// running a pre-reload copy of this engine is identifiable in
+// decisions.log without after-the-fact reconciliation. Fail-open: 0
+// omits the field (2026-11-15 incident: a stale module nudged at
+// 81-125% for two hours while the relief code sat uninstalled on disk —
+// nothing in the log distinguished the running copy from the repo one).
+const MODULE_BUILD_STAMP = (() => {
+	try {
+		return Math.round(statSync(fileURLToPath(import.meta.url)).mtimeMs);
+	} catch {
+		return 0;
+	}
+})();
+/** Resolve the configured ledger state dir to an absolute path that
+ *  stays inside the plugin's own state root (<dshHome>/.dsh-switchman/
+ *  state/trim/) or the OS temp root (os.tmpdir(), for throwaway test
+ *  state). The dir is settings-writable, and the ledger writer mkdirSyncs
+ *  and writes JSON there — an arbitrary out-of-root value would aim that
+ *  writer at any directory. Empty/unset keeps the store default; a
+ *  relative value resolves inside the root; anything else is refused
+ *  with a warn and the default root is used. Exported for tests. */
+export function resolveStateDir(raw, warn = () => {}) {
+	const root = resolve(dshHome(), ".dsh-switchman", "state", "trim");
+	if (typeof raw !== "string" || raw.trim() === "") return undefined;
+	const candidate = resolve(root, raw);
+	if (candidate === root || candidate.startsWith(root + "/")) return candidate;
+	// The OS temp root hosts throwaway state (tests mkdtemp under it); it is
+	// per-user and 0700 on macOS/Linux, so it stays inside the threat model.
+	const tmpRoots = [resolve(tmpdir())];
+	try { tmpRoots.push(realpathSync(tmpRoots[0])); } catch { /* first is enough */ }
+	if (tmpRoots.some((t) => candidate === t || candidate.startsWith(t + "/"))) return candidate;
+	warn(`dsh-switchman: trimStateDir refused (must stay under ${root} or the OS temp root): ${raw}`);
+	return undefined;
+}
+
 
 // ---- agent reference helpers --------------------------------------------------
 
@@ -58,6 +99,7 @@ import { childSessionIdOf } from "../subagent-model.js";
 // it and the stored tally takes over.
 const trimViewBySession = new Map(); // sessionId -> { viewTokens, at, inject, lastNoneAt }
 const trimWireBySession = new Map(); // sessionId -> { promptTokens, at } — last sampled provider prompt of an accepted MAIN dispatch (side calls never write; a tiny inherited-id usage sample must not lower the watermark's wire floor)
+const trimProjectedBySession = new Map(); // sessionId -> { totalTokens, at } — last host-meter reading (tokenMeter.measure().totalTokens: provider-anchored projection of the NEXT prompt, the figure the DSH context panel displays). Observability only — recorded at the idle boundary where the agent object is reachable; the trim tiers never read it.
 const capturedModelBySession = new Map(); // sessionId -> { provider, model, at } — last stream-captured model route, read by the watermark layer to scale subagent tiers to the session's own model window
 /** Freshness TTL for the in-memory view/injection registry (watermark and
  *  banner display only). NEVER a fold gate: gating folds on "did the surface
@@ -177,6 +219,45 @@ function noteTrimWireTokens(sessionId, usage) {
 	}
 }
 
+/** Record the host meter's projected prompt size for one session. Read from
+ * the agent/status idle boundary (the only place the agent object — and thus
+ * agent.session for tokenMeter.measure — is reachable in this layer). The
+ * figure is the DSH context panel's number (projectedTokens domain):
+ * provider-anchored plus heuristic surface deltas, i.e. what the NEXT prompt
+ * would cost — ahead of the wire, which only updates when the next response
+ * reports usage. Observability only: it lands in the view-applied row as
+ * proj=<n> so view/wire/proj divergence (estimator vs provider vs
+ * projection-domain) is one grep away. Fail-open, bounded (200 sessions). */
+function noteTrimProjectedTokens(sessionId, agent, ctx) {
+	try {
+		if (typeof sessionId !== "string" || sessionId === "") return;
+		const measurement = agent?.session ? ctx?.tokenMeter?.measure?.(agent.session) : undefined;
+		const total = Number.isFinite(measurement?.totalTokens) ? measurement.totalTokens : null;
+		if (total === null) return;
+		trimProjectedBySession.set(sessionId, { totalTokens: total, at: Date.now() });
+		if (trimProjectedBySession.size > 200) trimProjectedBySession.delete(trimProjectedBySession.keys().next().value);
+	} catch {
+		/* observability must never throw */
+	}
+}
+
+// ---- pressure-snapshot bridge (client badge) -------------------------------
+// The routes layer (host/routes.js) serves GET /trim-pressure for the client
+// dock chip; the live window/pressure math lives in THIS closure. A module
+// bridge mirrors the recentTrim*Of pattern: applyContextTrim publishes a
+// snapshot function once at mount; the route reads it per request. Null
+// publisher (module unloaded) or null window (nothing to measure against)
+// degrades to { available: false } — the chip renders nothing.
+let trimPressureSnapshotFn = null;
+export function trimPressureSnapshotOf(sessionId) {
+	try {
+		if (typeof trimPressureSnapshotFn !== "function") return { available: false };
+		return trimPressureSnapshotFn(sessionId) ?? { available: false };
+	} catch {
+		return { available: false };
+	}
+}
+
 /** 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
@@ -271,9 +352,81 @@ export const TRIM_PROTOCOL_TEXT = [
 	"- Old message ranges may be replaced by ONE synthetic [SWITCHMAN:TRIM] summary message; treat those summaries as faithful compressions, and message refs inside them as historical anchors.",
 	"- NEVER contradict or re-derive content a summary already settled; build on it.",
 	"- You may fold a contiguous range yourself with the ctx_trim_fold tool (give firstId/lastId message refs and a summary following the compression rules); ctx_trim_status lists the compressible ranges with their true sizes.",
+	"- When run_code is your only directly callable tool (program-transport mode), invoke these from inside a run_code program: await tools.ctx_trim_status({}) to list ranges, await tools.ctx_trim_fold({ firstId, lastId, count, summary }) to fold.",
 	"- Tool-call pairs (an assistant tool call and its results) must always be folded together or not at all.",
 ].join("\n");
 
+// Advisory nudge thresholds: the default speak line (50%) deliberately sits
+// well below the protocol's own 80% fold line so the model is nudged while
+// it still has comfortable headroom; critical wording escalates at 80%.
+// [2026-11-15]-[advisory lines recalibrated 65/95 → 50/80]-[the 2026-11-14
+// turn-25 incident (nudges ignored, 74%→99% in 28 minutes) showed a speak
+// line at 65% arrives too late to matter]. At most one nudge per session
+// per 10 minutes (an instant re-nudge when the level band changes). Both
+// lines are config-tunable via trimAdvisoryPercent / trimAdvisoryCriticalPercent.
+export const ADVISORY_NUDGE_PERCENT = 50;
+export const ADVISORY_NUDGE_CRITICAL_PERCENT = 80;
+/** Repeat cadence of the live tail nudge, per band. The nudge REPLACES
+ *  itself at the new surface tail (prune old seq, append fresh) — the old
+ *  10-minute single repeat let a spoken nudge slide under ~50 messages of
+ *  new turn output and become background noise (2026-11-15 turn observation:
+ *  the model folded only after the throttle window expired). Critical
+ *  escalates faster than high; relief (>= 80%) owns the mechanical path
+ *  independently of this cadence. Config-tunable via trimAdvisoryRepeatMs,
+ *  falling back to the defaults when absent or out of range. */
+export const ADVISORY_NUDGE_REPEAT_MS = 120_000;
+export const ADVISORY_NUDGE_REPEAT_CRITICAL_MS = 45_000;
+
+/** Effective advisory lines for one dispatch: config-tunable, falling back to
+ * the configured defaults (50/80) when absent, inverted, or out of range —
+ * a broken pair never silences the nudge. */
+function advisoryNudgeLines(config) {
+	const line = readNumber(config, "trimAdvisoryPercent", ADVISORY_NUDGE_PERCENT);
+	const critical = readNumber(config, "trimAdvisoryCriticalPercent", ADVISORY_NUDGE_CRITICAL_PERCENT);
+	const sane = (v) => Number.isFinite(v) && v > 0 && v <= 100;
+	if (!sane(line) || !sane(critical) || line >= critical) return { line: ADVISORY_NUDGE_PERCENT, critical: ADVISORY_NUDGE_CRITICAL_PERCENT };
+	return { line, critical };
+}
+
+/** Effective nudge repeat cadence for one dispatch: config-tunable
+ *  (trimAdvisoryRepeatMs), falling back to the built-in per-band defaults
+ *  when absent, negative, or above one hour — a broken value never pins
+ *  the nudge to the old 10-minute cadence nor spams every dispatch. */
+function advisoryRepeatLines(config) {
+	const highMs = readNumber(config, "trimAdvisoryRepeatMs", ADVISORY_NUDGE_REPEAT_MS);
+	const saneMs = (v) => Number.isFinite(v) && v >= 5_000 && v <= 3_600_000;
+	if (!saneMs(highMs)) return { highMs: ADVISORY_NUDGE_REPEAT_MS, criticalMs: ADVISORY_NUDGE_REPEAT_CRITICAL_MS };
+	return { highMs, criticalMs: Math.min(highMs, ADVISORY_NUDGE_REPEAT_CRITICAL_MS) };
+}
+
+/** Advisory-mode nudge text. Deliberate, bounded exception to the
+ * digit-free disclosure policy of TRIM_PROTOCOL_TEXT above: advisory mode
+ * never folds on a schedule (the modeNow gate); besides the model's own
+ * fold, the only engine-initiated relief is the one-shot critical relief
+ * fold (trimCriticalRelief, cooldown-gated). At threshold, the live-number
+ * instruction is appended to the session surface tail, not injected into
+ * the registered system section. */
+export function advisoryNudgeText(pressurePercent, critical, foldLine = ADVISORY_NUDGE_PERCENT, criticalLine = ADVISORY_NUDGE_CRITICAL_PERCENT, target = null, nth = 0) {
+	const action = critical
+		? `Pressure is CRITICAL (${pressurePercent}% ≥ ${criticalLine}%): fold down to under ~50% of the context IN THIS TURN.`
+		: `At ${pressurePercent}% (fold line ${foldLine}%): ${foldLine}–${foldLine + 9}% → fold roughly half of the older history now; ≥${foldLine + 10}% → fold down to under ~50%.`;
+	if (nth >= 2) {
+		const targetLine = target !== null ? ` Recommended: ${target}` : " Get ranges with ctx_trim_status."; // eslint-disable-line no-template-curly-in-string
+		return [
+			`[SWITCHMAN:TRIM] Advisory nudge (repeat #${nth + 1}) — still above the fold line. ${action} Fold FIRST, resume afterwards.${targetLine}`
+		].join("\n");
+	}
+	const actNow = target !== null
+		? `Act now: ONE ctx_trim_fold call is enough — fold the recommended range. Recommended: ${target}. (tool-call pairs fold together or not at all; existing summaries stay.) If run_code is your only directly callable tool, run: await tools.ctx_trim_fold({ firstId: "<firstRef>", lastId: "<lastRef>", count: <count>, summary: <your summary> }). Do not wait for a routine moment.`
+		: "Act now: call ctx_trim_status to list compressible ranges, pick one contiguous range, and fold it with ctx_trim_fold (tool-call pairs fold together or not at all; existing summaries stay). If run_code is your only directly callable tool, run both inside a program: await tools.ctx_trim_status({}) then await tools.ctx_trim_fold({ firstId, lastId, count, summary }). Do not wait for a routine moment.";
+	return [
+		'[SWITCHMAN:TRIM] Advisory nudge — pinned to the session tail until pressure falls below the fold line.',
+		`Live context pressure on this session has reached the fold line. ${action}`,
+		"FOLD FIRST: treat this nudge as a preemption, not background advice. Finish the current tool call if (and only if) aborting it mid-flight would leave broken state; otherwise interrupt the task queue and fold before continuing. Every queued step, plan item and pending subtask waits until pressure is back under the fold line. The only valid excuse to defer is a task that genuinely cannot be resumed after an interruption — and even then, fold at the first safe pause rather than at task end.",
+		actNow
+	].join("\n");
+}
+
 /** Effective window for the pressure/emergency tier math:
  * min(model-resolved window, configured cap). Null only when BOTH inputs
  * are unusable — the trigger then skips those tiers (fail-open). */
@@ -323,7 +476,7 @@ 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 });
+	const store = createStore({ stateDir: resolveStateDir(readString(config, "trimStateDir", null), warn) ?? 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
@@ -359,10 +512,319 @@ export function applyContextTrim(ctx, config) {
 			return null;
 		}
 	};
+
+	// Advisory nudge state: sessionId -> { at, critical, seq }. Bounded like the
+	// other per-session registries (200 entries).
+	const advisoryNudgeBySession = new Map();
+
+	// Single-flight for nudge warm-ups: during resolveRawWindow's <=10s window
+	// every main dispatch would otherwise re-fire the same resolve. Entries
+	// self-delete on settle; the expiry is only a belt-and-suspenders bound.
+	const windowWarmupInFlight = new Map(); // "provider/model" -> expiresAt
+	function warmWindowOnce(model, now) {
+		const key = `${model.provider}/${model.model}`;
+		const until = windowWarmupInFlight.get(key);
+		if (until !== undefined && now < until) return;
+		windowWarmupInFlight.set(key, now + 15_000); // > resolveRawWindow's 10s ceiling
+		void windowTokensFor(model).catch(() => {}).finally(() => {
+			if (windowWarmupInFlight.get(key) === until) windowWarmupInFlight.delete(key);
+		});
+	}
+
+	/** One-step fold target for the nudge text: the SAME recommendation the
+	 *  ctx_trim_status tool prints (first/last message refs + count of the raw
+	 *  compressible range). null when no capture exists yet or nothing is
+	 *  foldable — the nudge then keeps the two-step status-first wording.
+	 *  Read-only over the live capture: no host access, no throw. */
+	function recommendedFoldTargetOf(sessionId) {
+		try {
+			const capture = captures.get(sessionId);
+			if (capture === undefined || !Array.isArray(capture.messages) || capture.messages.length === 0) return null;
+			const ledger = store.ledgerOf(sessionId);
+			const { protectedTail, protectTaskIntent } = thresholdsNow();
+			const foldable = computeFoldableRange(capture.messages, ledger, protectedTail, { protectTaskIntent });
+			if (foldable === null) return null;
+			const firstRef = refOf(capture.messages[foldable.startIdx], foldable.startIdx);
+			const lastRef = refOf(capture.messages[foldable.endIdx], foldable.endIdx);
+			return {
+				firstId: "m" + firstRef,
+				lastId: "m" + lastRef,
+				count: foldable.endIdx - foldable.startIdx + 1,
+				tokens: estimateTokensOf(capture.messages, foldable.startIdx, foldable.endIdx),
+			};
+		} catch {
+			return null;
+		}
+	}
+
+	/** Advisory-mode pressure nudge (text: advisoryNudgeText). Appends the live
+	 * instruction to the session surface tail once pressure crosses the fold
+	 * line. Pressure reuses the meter-duality bridge (wire preferred, view
+	 * estimate as floor) against the session model's window read from the SYNC
+	 * cache — a cache miss fires an async warm-up (windowTokensFor) and defers
+	 * the nudge to a later dispatch instead of blocking this one — and it only
+	 * reaches the wire on the NEXT dispatch (the current request is already
+	 * assembled). The speak is a pure suffix, so the prompt prefix stays
+	 * untouched; a later clear or upgrade prunes only the nudge nodes, so
+	 * cache reuse survives up to the nudge instead of invalidating the whole
+	 * prefix as the old system-head splice did. */
+	function deliverAdvisoryNudge(sessionId, viewTokens) {
+		if (modeNow() !== "advisory") {
+			debug(`nudge skip mode=${modeNow()} session=${sessionId}`);
+			return;
+		}
+		const model = capturedModelBySession.get(sessionId) ?? null;
+		if (model === null) {
+			decisionLog("advisory-nudge skip why=no-captured-model");
+			return;
+		}
+		if (typeof model.provider !== "string" || typeof model.model !== "string") {
+			decisionLog("advisory-nudge skip why=bad-model-shape");
+			return;
+		}
+		const cached = windowCache.get(model.provider + "/" + model.model);
+		let resolvedWindow; // model-resolved window, or the configured cap when unknown
+		if (cached === undefined) {
+			// Unknown: warm up single-flight but stay AUDIBLE — fall back to the
+			// configured cap (the same denominator the emergency tier uses), so a
+			// model whose metadata never resolves still gets nudged at the fold
+			// line instead of burning to force unseen (2026-11-14: window-unknown
+			// swallowed every nudge at 89% pressure).
+			warmWindowOnce(model, Date.now());
+			resolvedWindow = windowCapNow();
+		} else {
+			// Stale-but-known still gates correctly: effectiveWindowTokens binds to the
+			// configured cap for every model larger than it, so the pressure math is
+			// unchanged. Re-warm in the background instead of burning this boundary.
+			if (Date.now() - cached.at >= 600_000) warmWindowOnce(model, Date.now());
+			// Resolution failed inside the TTL: same cap fallback instead of going
+			// quiet (no retry hammering — the warm-up stays single-flight).
+			resolvedWindow = cached.windowTokens ?? windowCapNow();
+		}
+		// Bind the resolved window to the configured cap before computing pressure.
+		const windowTokens = effectiveWindowTokens(resolvedWindow, windowCapNow());
+		if (windowTokens === null) {
+			// Cap unavailable too (wmForceTokens=0 and no explicit cap): nothing to
+			// measure against — the one remaining legitimate silence.
+			decisionLog("advisory-nudge skip why=window-unknown");
+			return;
+		}
+		const wire = wireTokensOf(sessionId);
+		const mass = Math.max(Number.isFinite(wire) ? wire : 0, Number.isFinite(viewTokens) ? viewTokens : 0);
+		if (mass <= 0) {
+			debug(`nudge skip empty-mass session=${sessionId}`);
+			return;
+		}
+		const pressurePercent = (mass / windowTokens) * 100;
+		const nudgeLines = advisoryNudgeLines(config);
+		const prior = advisoryNudgeBySession.get(sessionId);
+		if (pressurePercent < nudgeLines.line) {
+			// Below the line every live nudge must go. The sweep is NOT gated
+			// on `prior`: restarts and registry evictions lose the episode while
+			// the node stays visible. The recorded seq joins the union even when
+			// it fell out of the 50-node scan window; nudgePrune skips seqs a
+			// fold already consumed, so a vanished prior.seq cannot wedge this.
+			const seqs = new Set(surfacePass.nudgeScan(sessionId));
+			if (Number.isFinite(prior?.seq)) seqs.add(prior.seq);
+			if (seqs.size > 0) {
+				if (!surfacePass.nudgePrune(sessionId, [...seqs])) {
+					decisionLog("advisory-nudge skip why=prune-failed pressure=" + Math.round(pressurePercent) + "%");
+					return;
+				}
+				advisoryNudgeBySession.delete(sessionId);
+				// Log the resolved denominator (cap fallback included), not
+				// cached.windowTokens — on a cache miss `cached` is undefined
+				// here and this row threw after a successful prune
+				// (2026-11-15T02:28:12Z advisory-nudge-failed).
+				decisionLog("advisory-nudge below-line pressure=" + Math.round(pressurePercent) + "% mass=" + Math.round(mass) + " resolved=" + resolvedWindow + " cap=" + windowCapNow() + " pruned=" + seqs.size);
+			} else if (prior !== undefined) {
+				advisoryNudgeBySession.delete(sessionId); // nothing visible left; close the episode quietly
+			}
+			return; // fresh episode on the next crossing
+		}
+	const critical = pressurePercent >= nudgeLines.critical;
+	// One-step fold target (2026-11-15 advisory rework, item 2): the status
+	// tool's exact recommendation inlined into the nudge, so the model can
+	// comply with a single ctx_trim_fold call instead of a status round trip.
+	// The relief cycle below reuses the same target.
+	const foldTarget = recommendedFoldTargetOf(sessionId);
+	const targetText = foldTarget === null ? null
+		: `[m${foldTarget.firstId}]..[m${foldTarget.lastId}] (${foldTarget.count} messages, ~${Math.round(foldTarget.tokens)} tokens) — pass firstId="${foldTarget.firstId}", lastId="${foldTarget.lastId}", count=${foldTarget.count}`;
+	// Three-band advisory ladder (2026-11-15 rework, item 3): high = at the
+	// speak line (re-pin every trimAdvisoryRepeatMs); escal = ten points
+	// above it (re-pin EVERY dispatch — a reminder that keeps sliding under
+	// the turn tail must sit at the tail); critical = the escalation line
+	// (fastest re-pin + the mechanical relief path below).
+	const escal = !critical && pressurePercent >= nudgeLines.line + 10;
+	const band = critical ? "critical" : escal ? "escal" : "high";
+	// Relief extension (item 4): critical is not the only engine fold
+	// trigger — three consecutive same-band speaks with no fold commit
+	// (prior.repeats >= 3) put an escal-band session on the SAME mechanical
+	// relief path, cooldown-gated like critical. Nudge-only purity survives
+	// for genuinely attended sessions: repeats < 3 never folds.
+	const reliefDue = critical || (escal && (prior?.repeats ?? 0) >= 3);
+		const now = Date.now();
+		// Critical relief ([2026-11-15]-[advisory critical relief fold]-[nudges
+		// alone let a session burn from the speak line to host compaction —
+		// turn-25: nudges ignored, 74%→99% in 28 minutes]). At the critical line
+		// the engine performs ONE mechanical (emergency-style) fold itself,
+		// cooldown-gated like the emergency tier, instead of only nudging.
+		// Runs ahead of the same-band nudge throttle: the relief cadence is owned
+		// by reliefBySession + inFlight alone. `trimCriticalRelief: false`
+		// restores nudge-only advisory mode.
+		if (reliefDue && reliefEnabledNow() && !inFlight.has(sessionId) && captures.has(sessionId)
+			&& now - (reliefBySession.get(sessionId) ?? 0) >= EMERGENCY_COOLDOWN_MS) {
+			// Cooldown armed BEFORE the cycle (same pre-set semantics as the
+			// emergency tier): every attempt, folded or rejected, cools down.
+			reliefBySession.set(sessionId, now);
+			if (reliefBySession.size > 200) reliefBySession.delete(reliefBySession.keys().next().value);
+			const reliefCapture = captures.get(sessionId);
+			const cycleToken = {};
+			inFlight.set(sessionId, cycleToken);
+			void (async () => {
+				try {
+					if (disposedSince(now)) {
+						decisionLog(`session=${sessionId} advisory-relief outcome=reload-aborted tier=emergency pressure=${Math.round(pressurePercent)}% trigger=${band}`);
+						return;
+					}
+					const { protectedTail, protectTaskIntent, ...reliefThresholds } = thresholdsNow();
+					const ledger = store.ledgerOf(sessionId);
+					const foldable = computeFoldableRange(reliefCapture.messages, ledger, protectedTail, { protectTaskIntent });
+					const decision = evaluateTrigger({
+						foldable,
+						messages: reliefCapture.messages,
+						viewTokens: mass, // same basis as the nudge line: max(view, wire)
+						windowTokens,
+						thresholds: { ...reliefThresholds, emergencyPercent: 1 }, // force the mechanical tier through
+						now,
+						lastFoldAt: ledger.lastFoldAt,
+						foldsThisHour: ledger.foldsThisHour,
+						lastEmergencyAt: 0, // reliefBySession owns the relief cadence
+						ledger,
+						ladderRuns: { t2: [], t3: [] }, // relief is mechanical-only; no ladder cut-in
+					});
+					if (decision.action !== "emergency") {
+						decisionLog(`session=${sessionId} advisory-relief outcome=none reason=${decision.reason || "-"} pressure=${Math.round(pressurePercent)}% trigger=${band}`);
+						return;
+					}
+					const outcome = await runFoldCycle(sessionId, decision, now, cycleToken);
+					decisionLog(`session=${sessionId} advisory-relief outcome=${outcome} tier=emergency pressure=${Math.round(pressurePercent)}% trigger=${band}`);
+					if (outcome.startsWith("folded:") || outcome === "summary-unavailable" || outcome.startsWith("commit-rejected:")) {
+						warn(`[context-trim] ${sessionId}: advisory relief ${outcome} at ${Math.round(pressurePercent)}%`);
+					}
+				} catch (error) {
+					decisionLog(`session=${sessionId} advisory-relief outcome=error why=${error?.message ?? error}`);
+					warn(`[context-trim] ${sessionId}: advisory relief failed: ${error?.message ?? error}`);
+				} finally {
+					// Only the cycle owning the CURRENT token may release the lock.
+					if (inFlight.get(sessionId) === cycleToken) inFlight.delete(sessionId);
+				}
+			})();
+		} else if (reliefDue) {
+			debug(`relief gate held pressure=${Math.round(pressurePercent)}% session=${sessionId}`);
+			// Audible silence ([2026-11-15]-[relief skip diagnostics]): the turn-25
+			// incident hid here — a session sat at 81-125% critical while the gate
+			// held, and the only trace was a two-hour view-applied reconciliation.
+			// One throttled row per minute names the exact gate that held the
+			// relief back (cooldown / cycle in flight / no capture / disabled).
+			if (now - (reliefSkipLogAt.get(sessionId) ?? 0) >= 60_000) {
+				reliefSkipLogAt.set(sessionId, now);
+				if (reliefSkipLogAt.size > 200) reliefSkipLogAt.delete(reliefSkipLogAt.keys().next().value);
+				debug(`relief gate detail enabled=${reliefEnabledNow()} cycle=${inFlight.has(sessionId)} capture=${captures.has(sessionId)} sinceLast=${now - (reliefBySession.get(sessionId) ?? 0)}ms session=${sessionId}`);
+			const why = !reliefEnabledNow() ? "relief-disabled"
+					: inFlight.has(sessionId) ? "cycle-in-flight"
+					: !captures.has(sessionId) ? "no-capture"
+					: "cooldown";
+				decisionLog(`session=${sessionId} advisory-relief skip why=${why} pressure=${Math.round(pressurePercent)}%`);
+			}
+		}
+		// Any band CHANGE re-speaks immediately: escalation high->critical, and
+		// intentionally also a downgrade back into high after a partial fold.
+		// [2026-11-15]-[per-band tail re-pin]-[a spoken nudge slides under the
+		// growing turn tail and becomes background noise; the single 10-minute
+		// repeat let 2.5 minutes of throttled silence precede the only fold
+		// (decisions.log 10:19→10:22). The nudge now REPLACES itself at the new
+		// tail every trimAdvisoryRepeatMs (high band) / min(that, 45 s)
+		// (critical): prune old seq, append fresh. Counts same-band repeats for
+		// the terse repeat wording.]
+		const repeatLines = advisoryRepeatLines(config);
+		const repeatMs = band === "high" ? repeatLines.highMs
+			: band === "escal" ? 0 // every dispatch: the reminder must own the tail
+			: Math.min(repeatLines.highMs, repeatLines.criticalMs);
+		if (prior !== undefined && prior.band === band && now - prior.at < repeatMs) {
+			debug(`nudge throttle band=${band} age=${now - prior.at}ms repeats=${prior.repeats ?? 0} session=${sessionId}`);
+			return;
+		}
+		if (!surfacePass.nudgeSupported(sessionId)) {
+			decisionLog("advisory-nudge skip why=surface-unavailable pressure=" + Math.round(pressurePercent) + "%");
+			return;
+		}
+
+		// Replace the recorded prior nudge, or clear orphans a restart left
+		// behind, before speaking fresh. nudgePrune only touches seqs still
+		// live on the surface, so a prior a fold already consumed is a no-op.
+		const priorSeq = Number.isFinite(prior?.seq) ? prior.seq : null;
+		if (priorSeq !== null) {
+			if (!surfacePass.nudgePrune(sessionId, [priorSeq])) {
+				decisionLog("advisory-nudge skip why=prune-failed pressure=" + Math.round(pressurePercent) + "%");
+				return;
+			}
+		} else {
+			const orphans = surfacePass.nudgeScan(sessionId);
+			if (orphans.length > 0) {
+				if (!surfacePass.nudgePrune(sessionId, orphans)) {
+					decisionLog("advisory-nudge skip why=prune-failed pressure=" + Math.round(pressurePercent) + "%");
+					return;
+				}
+				decisionLog("advisory-nudge orphan-pruned seqs=" + orphans.length + " pressure=" + Math.round(pressurePercent) + "%");
+			}
+		}
+		// One-step targeting for the model (2026-11-15 advisory rework): the nudge
+		// carries the status tool's exact recommendation, so compliance is a
+		// single ctx_trim_fold call; without a foldable range it stays two-step.
+		const nextRepeats = prior !== undefined && prior.band === band ? (prior.repeats ?? 0) + 1 : 1;
+		const nudge = advisoryNudgeText(
+			Math.round(pressurePercent), critical, nudgeLines.line, nudgeLines.critical,
+			targetText,
+			nextRepeats - 1,
+		);
+		const appended = surfacePass.nudgeAppend(sessionId, nudge);
+		if (appended.error !== null || !Number.isFinite(appended.seq)) {
+			advisoryNudgeBySession.delete(sessionId); // a pruned prior must not throttle the retry
+			decisionLog("advisory-nudge skip why=append-failed err=" + (appended.error ?? "unknown") + " pressure=" + Math.round(pressurePercent) + "%");
+			return;
+		}
+		const seq = appended.seq;
+		advisoryNudgeBySession.delete(sessionId); // re-insert: refresh recency so eviction drops the least recently nudged
+		advisoryNudgeBySession.set(sessionId, { at: now, band, seq, repeats: nextRepeats });
+		debug(`nudge prepared seq=${seq} level=${band} pressure=${Math.round(pressurePercent)}% session=${sessionId}`);
+		if (advisoryNudgeBySession.size > 200) advisoryNudgeBySession.delete(advisoryNudgeBySession.keys().next().value);
+		decisionLog("session=" + sessionId + " advisory-nudge pressure=" + Math.round(pressurePercent) + "% mass=" + Math.round(mass) + " window=" + windowTokens + " level=" + band + " repeats=" + nextRepeats + " seq=" + seq);
+	}
+
 	const captures = new Map(); // sessionId -> { messages, refs, viewTokens, model, at }
-	const inFlight = new Set(); // sessionIds with a fold running
+	// sessionId -> generation token of the running fold cycle. A plain Set
+	// pinned a session forever once a cycle's await never settled; the
+	// maybeFold watchdog swaps the token so wedged cycles release the lock.
+	const inFlight = new Map();
+	// Fold-cycle watchdog: a cycle still "in flight" after this long logs a
+	// cycle-stuck row, releases the lock, and lets the next trigger retry.
+	// The ceiling must exceed the worst LEGITIMATE cycle — a raw fold can
+	// summarize on side AND fallback routes (2 x SUMMARY_TIMEOUT_MS = 240s) —
+	// so a healthy slow cycle is never preempted.
+	const CYCLE_WATCHDOG_MS = 300_000;
+	// Hard ceiling for one host model-info lookup: some llm builds never
+	// settle resolveModelInfo for unresolvable routes, and that wedged
+	// await used to pin the whole fold cycle until restart.
+	const WINDOW_RESOLVE_TIMEOUT_MS = 10_000;
 	const windowCache = new Map(); // "provider/model" -> { windowTokens, at }
 	const lastEmergencyAtBySession = new Map(); // sessionId -> epoch ms of last emergency fold (per-session cooldown)
+	// Advisory critical relief cooldown: sessionId -> epoch ms of the last
+	// relief fold. Set BEFORE the cycle (emergency semantics: a rejected
+	// commit cools the relief like a success, or a failing range retries at
+	// every dispatch forever). Bounded 200 like the sibling registries.
+	const reliefBySession = new Map();
+	const reliefSkipLogAt = new Map(); // sessionId -> epoch ms of the last relief-skip diagnostic row (60 s throttle, bounded 200)
 	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)
 
@@ -412,6 +874,34 @@ export function applyContextTrim(ctx, config) {
 		}
 	}
 
+	/** Debug-trace verbosity gate ([2026-11-15]-[verbose debug log]): the
+	 *  turn-25 and window-unknown incidents both hid inside gates that
+	 *  outcomes-only logging never names. With trimVerboseLog on, every
+	 *  step/gate/decision path writes a debug row; off keeps key rows only. */
+	function verboseNow() {
+		try {
+			return readBool(config, "trimVerboseLog", false) === true;
+		} catch {
+			return false;
+		}
+	}
+	/** Verbose-only row: one line naming a step/gate/decision path. */
+	function debug(entry) {
+		if (!verboseNow()) return;
+		decisionLog("debug " + entry);
+	}
+	/** ALWAYS-ON exception detail ([2026-11-15]-[verbose debug log]):
+	 *  independent of trimVerboseLog — message + top stack frames, so a
+	 *  swallowed catch is reconstructable without reproducing it. */
+	function errorLog(where, error) {
+		try {
+			const stack = typeof error?.stack === "string" ? error.stack.split("\n").slice(0, 5).join(" | ") : "no-stack";
+			decisionLog(`error where=${where} msg=${error?.message ?? error} stack=${stack}`);
+		} catch {
+			/* observability must never throw */
+		}
+	}
+
 	// ---- fork-state inheritance (copy-on-fork; design in fork.js header) ------
 	const linksCache = { mtime: -1, map: null }; // mtime-gated fork-links map
 	const inheritFirstSeen = new Map(); // sessionId -> epoch ms of first eligibility check
@@ -494,17 +984,23 @@ export function applyContextTrim(ctx, config) {
 		const mode = readString(config, "trimMode", "auto");
 		return mode === "off" || mode === "advisory" || mode === "auto" ? mode : "auto";
 	};
+	const reliefEnabledNow = () => readBool(config, "trimCriticalRelief", true);
 	const thresholdsNow = () => ({
 		growthTokens: readNumber(config, "trimGrowthTokens", 22_500),
-		incrementTokens: readNumber(config, "trimIncrementTokens", 25_000),
-		pressurePercent: readNumber(config, "trimPressurePercent", 65),
-		emergencyPercent: readNumber(config, "trimEmergencyPercent", 95),
-		protectedTail: Math.max(0, Math.round(readNumber(config, "trimProtectedTail", 10))),
-		maxFoldsPerHour: readNumber(config, "trimMaxFoldsPerHour", 30),
+		incrementTokens: readNumber(config, "trimIncrementTokens", 45_000),
+		// Count-typed fields integerize here (Math.round): the schema allows
+		// decimals (z.number()), but trigger.js gates them with Number.isInteger
+		// — a non-integer config value would otherwise fall back to the
+		// hard-coded default silently (convention mismatch, F6).
+		pressurePercent: readNumber(config, "trimPressurePercent", 45),
+		emergencyPercent: readNumber(config, "trimEmergencyPercent", 90),
+		protectedTail: Math.max(0, Math.round(readNumber(config, "trimProtectedTail", 6))),
+		maxFoldsPerHour: Math.max(1, Math.round(readNumber(config, "trimMaxFoldsPerHour", 30))),
 		ladderT2Tokens: readNumber(config, "trimLadderT2Tokens", 8_000),
-		ladderT2MinBlocks: readNumber(config, "trimLadderT2MinBlocks", 3),
+		ladderT2MinBlocks: Math.max(2, Math.round(readNumber(config, "trimLadderT2MinBlocks", 3))),
 		ladderT3Tokens: readNumber(config, "trimLadderT3Tokens", 6_000),
-		ladderT3MinBlocks: readNumber(config, "trimLadderT3MinBlocks", 2),
+		ladderT3MinBlocks: Math.max(2, Math.round(readNumber(config, "trimLadderT3MinBlocks", 2))),
+		protectTaskIntent: readBool(config, "trimProtectTaskIntent", true),
 	});
 	const ladderEnabledNow = () => readBool(config, "trimLadderEnabled", true);
 	/** CJK-aware summary-mass estimator for the ladder census (same units
@@ -546,10 +1042,69 @@ export function applyContextTrim(ctx, config) {
 	const windowCapNow = () => {
 		const explicit = readNumber(config, "trimWindowTokens", 0);
 		if (explicit > 0) return explicit;
-		const force = readNumber(config, "wmForceTokens", 150_000);
+		const force = readNumber(config, "wmForceTokens", 200_000);
 		return force > 0 ? force : null;
 	};
 
+	// Publish the client-badge snapshot bridge (module-level trimPressureSnapshotOf
+	// reads this). Every field is recomputed per request from live config + the
+	// session's captured model/window/wire — same math as the nudge line, no new
+	// state. viewTokens arrives from the recent-view bridge (10-min TTL); proj
+	// from the meter-projection registry. Failure of any component degrades that
+	// field to null; the chip hides on available=false or window=null.
+	trimPressureSnapshotFn = (sessionId) => {
+		try {
+			if (!enabledNow() || typeof sessionId !== "string" || sessionId === "") return { available: false };
+			const model = recentTrimModelOf(sessionId, TRIM_VIEW_MAX_AGE_MS);
+			let resolvedWindow = null;
+			if (model !== null) {
+				const cached = windowCache.get(model.provider + "/" + model.model);
+				if (cached !== undefined) resolvedWindow = cached.windowTokens ?? null;
+			}
+			const cap = windowCapNow();
+			const windowTokens = resolvedWindow !== null ? effectiveWindowTokens(resolvedWindow, cap) : cap;
+			if (windowTokens === null || windowTokens <= 0) return { available: false };
+			const viewTokens = recentTrimViewTokensOf(sessionId, TRIM_VIEW_MAX_AGE_MS);
+			const wire = wireTokensOf(sessionId);
+			const mass = Math.max(Number.isFinite(wire) ? wire : 0, Number.isFinite(viewTokens) ? viewTokens : 0);
+			const projectedEntry = trimProjectedBySession.get(sessionId);
+			const proj = projectedEntry !== undefined && Date.now() - projectedEntry.at <= TRIM_VIEW_MAX_AGE_MS ? Math.round(projectedEntry.totalTokens) : null;
+			const lines = advisoryNudgeLines(config);
+			const pressure = mass > 0 ? (mass / windowTokens) * 100 : 0;
+			// Cooldown story must match the GATE, not just the timestamp
+			// ([2026-11-15]-[relief snapshot coherence]): the gate is
+			// enabled + advisory + no cycle in flight + cooldown elapsed;
+			// reporting only the arithmetic let the chip claim "ready"
+			// while the engine would still skip (cycle in flight).
+			const reliefAt = reliefBySession.get(sessionId) ?? 0;
+			const reliefCooldownRemaining = reliefEnabledNow() && modeNow() === "advisory"
+				? Math.max(0, EMERGENCY_COOLDOWN_MS - (Date.now() - reliefAt))
+				: null;
+			const reliefReady = reliefCooldownRemaining !== null
+				&& reliefCooldownRemaining === 0
+				&& !inFlight.has(sessionId)
+				&& captures.has(sessionId);
+
+			return {
+				available: true,
+				mode: modeNow(),
+				mass: Math.round(mass),
+				window: windowTokens,
+				pressure: Math.round(pressure),
+				view: viewTokens !== null ? Math.round(viewTokens) : null,
+				wire: Number.isFinite(wire) ? Math.round(wire) : null,
+				proj,
+				advisoryLine: lines.line,
+				criticalLine: lines.critical,
+				reliefEnabled: reliefEnabledNow(),
+				reliefCooldownRemaining,
+				reliefReady,
+			};
+		} catch {
+			return { available: false };
+		}
+	};
+
 	/** Session id for a stream call: options.sessionId, else the current
 	 * initiator's session (try/catch — host internals shift). */
 	function sessionIdOf(options) {
@@ -573,20 +1128,41 @@ export function applyContextTrim(ctx, config) {
 		return effectiveWindowTokens(resolved, windowCapNow());
 	}
 
-	/** Async raw-window resolution (fills the cache; null when unknown). */
+	/** Async raw-window resolution (fills the cache; null when unknown).
+	 * Two fixes over the historical behavior: the host contract is
+	 * resolveModelInfo(provider, model) — two strings; passing the model
+	 * object threw NO_ADAPTER on every route, so every decision row ran on
+	 * the cap fallback. And the lookup is raced against a hard timeout:
+	 * a never-settling promise must not pin the fold cycle. */
 	async function resolveRawWindow(model, key, now) {
+		let timer = null;
 		try {
 			const llm = ctx.get("llm", false);
-			const info = await llm?.resolveModelInfo?.(model);
+			const lookup = Promise.resolve(llm?.resolveModelInfo?.(model.provider, model.model));
+			const info = await Promise.race([
+				lookup,
+				new Promise((_, reject) => {
+					timer = setTimeout(() => reject(new Error(`no settle within ${WINDOW_RESOLVE_TIMEOUT_MS}ms`)), WINDOW_RESOLVE_TIMEOUT_MS);
+					timer.unref?.();
+				}),
+			]);
 			const windowTokens = info?.context?.contextWindow;
 			const value = Number.isFinite(windowTokens) && windowTokens > 0 ? windowTokens : null;
+			if (value === null) decisionLog(`window-resolve-failed key=${key} why=no context metadata`);
 			windowCache.set(key, { windowTokens: value, at: now });
 			if (windowCache.size > 200) windowCache.delete(windowCache.keys().next().value);
+			if (value !== null) decisionLog(`window-resolved key=${key} window=${value}`);
 			return value;
-		} catch {
+		} catch (error) {
 			windowCache.set(key, { windowTokens: null, at: now });
 			if (windowCache.size > 200) windowCache.delete(windowCache.keys().next().value);
+			// One row per model per 10-min cache window (plus rare concurrent
+			// misses inside the 10s race window): a silently failing resolution
+			// is what hid the wrong-arity call for months.
+			decisionLog(`window-resolve-failed key=${key} why=${error?.message ?? error}`);
 			return null;
+		} finally {
+			if (timer !== null) clearTimeout(timer);
 		}
 	}
 
@@ -595,7 +1171,8 @@ export function applyContextTrim(ctx, config) {
 	function captureOf(sessionId, messages, model, viewTokens) {
 		captures.set(sessionId, { messages: messages.slice(), model, viewTokens, at: Date.now() });
 		if (model !== null && typeof model === "object" && typeof model.provider === "string" && typeof model.model === "string") {
-			capturedModelBySession.set(sessionId, { provider: model.provider, model: model.model, at: Date.now() });
+		capturedModelBySession.set(sessionId, { provider: model.provider, model: model.model, at: Date.now() });
+		if (!windowCache.has(model.provider + "/" + model.model)) warmWindowOnce(model, Date.now());
 			if (capturedModelBySession.size > 200) capturedModelBySession.delete(capturedModelBySession.keys().next().value);
 		}
 		// keep the capture map bounded (200 sessions)
@@ -636,10 +1213,16 @@ export function applyContextTrim(ctx, config) {
 		// 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);
+		// Projection truth in the row: the host meter's projected NEXT-prompt
+		// size (context-panel domain) sampled at the last idle boundary. Diverges
+		// from wire by design — wire is the last PAID prompt, proj estimates the
+		// next one — so the two columns bracket the real pressure band.
+		const projectedEntry = trimProjectedBySession.get(sessionId);
+		const projectedTokens = projectedEntry !== undefined && Date.now() - projectedEntry.at <= TRIM_VIEW_MAX_AGE_MS ? Math.round(projectedEntry.totalTokens) : null;
 		// 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}${wireTokens === null ? "" : ` wire=${wireTokens}`}`);
+		decisionLog(`session=${sessionId} view-applied applied=${view.applied} foldedMsgs=${view.foldedMessages} view=${Math.round(viewTokens)} blocks=${blocksCount} injected=${injected}${wireTokens === null ? "" : ` wire=${wireTokens}`}${projectedTokens === null ? "" : ` proj=${projectedTokens}`}${MODULE_BUILD_STAMP > 0 ? ` b=${MODULE_BUILD_STAMP}` : ""}`);
 		// 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
@@ -744,9 +1327,12 @@ export function applyContextTrim(ctx, config) {
 
 	/** Run one fold cycle for a session (called at the idle boundary ONLY).
 	 * Returns a short outcome string for logging. */
-	async function runFoldCycle(sessionId, decision, cycleStartedAt) {
+	async function runFoldCycle(sessionId, decision, cycleStartedAt, cycleToken) {
 		const capture = captures.get(sessionId);
-		if (capture === undefined) return "no-capture";
+		if (capture === undefined) {
+			debug(`cycle step no-capture session=${sessionId}`);
+			return "no-capture";
+		}
 		const { protectedTail } = thresholdsNow();
 		// Ladder cycle (docs/ladder-fold.md): distill the decision's consumed
 		// run of block summaries into ONE replacement. Never mechanical — a
@@ -770,6 +1356,7 @@ export function applyContextTrim(ctx, config) {
 			// Ladder folds never degrade to mechanical (docs/ladder-fold.md):
 			// after both routes fail the cycle stays fail-open with backoff.
 			if (summary === null) return disposedSince(cycleStartedAt) ? "reload-aborted" : "summary-unavailable"; // skip cycle, fail-open; a dispose cut is not a model failure
+			if (inFlight.get(sessionId) !== cycleToken) return "superseded"; // watchdog released us; a retry owns the session
 			const result = store.commitFold(
 				sessionId,
 				{ consumes: decision.consumes.slice(), summary, kind: "summary", tier: decision.tier === "ladder-3" ? 3 : 2, approxTokens },
@@ -790,6 +1377,7 @@ export function applyContextTrim(ctx, config) {
 		const refs = slice.map((message, i) => refOf(message, startIdx + i));
 		const count = slice.length;
 		const approxTokens = estimateTokensOf(slice);
+		debug(`cycle step begin kind=${decision.kind} tier=${decision.tier ?? "-"} range=${startIdx}..${endIdx} session=${sessionId}`);
 		let summary = null;
 		let kind = "summary";
 		let degraded = false; // set when a PRESSURE fold falls back to mechanical
@@ -812,6 +1400,7 @@ export function applyContextTrim(ctx, config) {
 				onFail: (why) => decisionLog(`session=${sessionId} summary-fail route=${tag} why=${why} msgs=${count} ~${approxTokens}t`),
 				onNotice: (why) => decisionLog(`session=${sessionId} summary-retry route=${tag} why=${why} msgs=${count} ~${approxTokens}t`),
 			});
+			debug(`cycle step summarize route=${route ? `${route.provider}/${route.model}` : "none"} fallback=${fallback ? `${fallback.provider}/${fallback.model}` : "none"} msgs=${count} ~${approxTokens}t session=${sessionId}`);
 			summary = route !== null ? await summarize(route, "side") : null;
 			if (summary === null && fallback !== null && !sameRoute(fallback, route)) summary = await summarize(fallback, "fallback");
 			// Last resort for PRESSURE folds only: relief beats fidelity when
@@ -828,6 +1417,8 @@ export function applyContextTrim(ctx, config) {
 			if (summary === null) return disposedSince(cycleStartedAt) ? "reload-aborted" : "summary-unavailable"; // skip cycle, fail-open; a dispose cut is not a model failure
 		}
 		const positions = refPositions(capture.messages);
+		if (inFlight.get(sessionId) !== cycleToken) return "superseded"; // watchdog released us; a retry owns the session
+		debug(`cycle step commit kind=${kind} tier=${decision.tier} msgs=${count} ~${approxTokens}t session=${sessionId}`);
 		const result = store.commitFold(
 			sessionId,
 			{ refRange: { firstId: refs[0], lastId: refs[refs.length - 1] }, count, approxTokens, summary, kind, tier: decision.tier },
@@ -852,15 +1443,28 @@ export function applyContextTrim(ctx, config) {
 	async function maybeFold(agent, via = "idle") {
 		const sessionId = agent;
 		if (sessionId === null || sessionId === undefined || sessionId === "") return;
-		if (!enabledNow() || modeNow() !== "auto") return;
-		if (inFlight.has(sessionId)) return;
+		if (!enabledNow() || modeNow() !== "auto") {
+			debug(`session=${sessionId} via=${via} skip enabled=${enabledNow()} mode=${modeNow()}`);
+			return;
+		}
+		if (inFlight.has(sessionId)) {
+			debug(`session=${sessionId} via=${via} skip cycle-in-flight`);
+			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 failureCooldown = foldFailureCooldownOf(sessionId);
+		if (failureCooldown > 0) {
+			debug(`session=${sessionId} via=${via} skip failure-backoff remaining=${failureCooldown}ms`);
+			return;
+		}
 		const capture = captures.get(sessionId);
-		if (capture === undefined) return;
+		if (capture === undefined) {
+			debug(`session=${sessionId} via=${via} skip no-capture`);
+			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:
@@ -874,15 +1478,28 @@ export function applyContextTrim(ctx, config) {
 			decisionLog(`session=${sessionId} via=${via} action=none reason=injection-unavailable view=${Math.round(capture.viewTokens)}`);
 			return;
 		}
-		inFlight.add(sessionId);
 		const cycleStartedAt = Date.now();
+		// Generation token lock (was a plain Set): a cycle wedged on an await
+		// that never settles used to pin this session's fold path until
+		// restart. The watchdog logs the wedge and releases the lock; an
+		// abandoned cycle returns "superseded" at its commit guard, and its
+		// finally can no longer delete a retry's entry.
+		const cycleToken = {};
+		inFlight.set(sessionId, cycleToken);
+		const cycleWatchdog = setTimeout(() => {
+			if (inFlight.get(sessionId) !== cycleToken) return;
+			inFlight.delete(sessionId);
+			decisionLog(`session=${sessionId} via=${via} outcome=cycle-stuck elapsedMs=${Date.now() - cycleStartedAt}`);
+			warn(`[context-trim] ${sessionId}: fold cycle stuck >${CYCLE_WATCHDOG_MS}ms — lock released for the next trigger`);
+		}, CYCLE_WATCHDOG_MS);
+		cycleWatchdog.unref?.();
 		// Hoisted for the catch below: a dispose-cut throw may land before the
 		// trigger ever ran, and the catch must not touch a dead binding.
 		let decision = null;
 		try {
-			const { protectedTail, ...thresholds } = thresholdsNow();
+			const { protectedTail, protectTaskIntent, ...thresholds } = thresholdsNow();
 			const ledger = store.ledgerOf(sessionId);
-			const foldable = computeFoldableRange(capture.messages, ledger, protectedTail);
+			const foldable = computeFoldableRange(capture.messages, ledger, protectedTail, { protectTaskIntent });
 			const windowTokens = await windowTokensFor(capture.model);
 			// Pressure tiers run on the REAL prompt size when the tally is known:
 			// max(view, wire). The view estimate misses the system/context
@@ -905,12 +1522,15 @@ export function applyContextTrim(ctx, config) {
 			});
 			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, cycleStartedAt);
+			const outcome = await runFoldCycle(sessionId, decision, cycleStartedAt, cycleToken);
 			// 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). A ladder run whose
 			// consumed blocks vanished between trigger and commit is the same
 			// family: without backoff it would re-fire at every boundary.
+			// "superseded" (watchdog released the lock mid-cycle) and neutral
+			// skips advance no ladder either — the retry that owns the session
+			// is judged alone.
 			if (outcome.startsWith("folded:")) clearFoldFailure(sessionId);
 			else if (outcome === "summary-unavailable" || outcome.startsWith("commit-rejected:") || outcome === "ladder-consumed-missing") recordFoldFailure(sessionId);
 			// Outcome lands in the decision log too: warn() has no reachable
@@ -923,11 +1543,15 @@ export function applyContextTrim(ctx, config) {
 			// that is a reload cut, not a model failure: log it and skip the ladder.
 			if (disposedSince(cycleStartedAt)) decisionLog(`session=${sessionId} outcome=reload-aborted tier=${decision?.tier ?? "-"}`);
 			else {
+				errorLog("fold-cycle", error);
 				recordFoldFailure(sessionId); // a thrown cycle counts as failed too
 				warn(`[context-trim] fold cycle failed: ${error?.message ?? error}`);
 			}
 		} finally {
-			inFlight.delete(sessionId);
+			clearTimeout(cycleWatchdog);
+			// Only the cycle owning the CURRENT token may release the lock —
+			// a watchdog-superseded wedged cycle must not delete a retry's entry.
+			if (inFlight.get(sessionId) === cycleToken) inFlight.delete(sessionId);
 		}
 	}
 
@@ -953,6 +1577,9 @@ export function applyContextTrim(ctx, config) {
 				// agent }) — derive the session id per host/context-watch.js:122.
 				const sessionId = agentSessionIdOf(payload?.agent);
 				if (sessionId === null) return;
+				// Meter projection sample: host meter's projected NEXT-prompt size
+				// (the context panel's figure) for the view-applied proj=<n> column.
+				noteTrimProjectedTokens(sessionId, payload?.agent, ctx);
 				// 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.
@@ -962,7 +1589,12 @@ export function applyContextTrim(ctx, config) {
 					} catch {
 						/* sweep must never break the idle hook */
 					}
-				});
+						}).catch((error) => {
+							// Parity with the stream path: maybeFold is catch-total by design,
+							// but a dispose-cut throw or a future regression must not become
+							// an unhandled rejection on the void'd chain.
+							errorLog("fold-idle", error);
+						});
 			} catch {
 				/* idle hook must never throw */
 			}
@@ -1037,19 +1669,27 @@ export function applyContextTrim(ctx, config) {
 			name: "ctx_trim_status",
 			description: "List this session's compressible context ranges with their true sizes: the fold ledger, the raw range a fold would cover, and distillation targets. Read-only. Contains sizes only — never progress percentages.",
 			parameters: { type: "object", properties: {}, additionalProperties: false },
-			required: [],
+			// Register-level shape: bare ctx.tools.register runs no defineTool DSL
+			// compilation and REJECTS a definition without an output block — the
+			// missing block silently killed both tools in every session (native
+			// and PTC). The execute bodies return plain strings, rendered as one
+			// text block.
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{ type: "text", text: value }],
+			},
 			async execute() {
 				const sessionId = sessionIdOf({});
 				if (sessionId === null) return "No session context available.";
 				if (!enabledNow()) return "Context trimming is disabled for this deployment.";
 				const ledger = store.ledgerOf(sessionId);
 				const capture = captures.get(sessionId);
-				const { protectedTail } = thresholdsNow();
+				const { protectedTail, protectTaskIntent } = thresholdsNow();
 				const lines = [`ctx_trim_status — mode: ${modeNow()} (enabled: ${enabledNow()})`];
 				lines.push(...renderStatusLedger(ledger));
 				// The raw range a fold would cover next, with its true size.
 				if (capture !== undefined) {
-					const foldable = computeFoldableRange(capture.messages, ledger, protectedTail);
+					const foldable = computeFoldableRange(capture.messages, ledger, protectedTail, { protectTaskIntent });
 					if (foldable !== null) {
 						const firstRef = refOf(capture.messages[foldable.startIdx], foldable.startIdx);
 						const lastRef = refOf(capture.messages[foldable.endIdx], foldable.endIdx);
@@ -1087,6 +1727,11 @@ export function applyContextTrim(ctx, config) {
 				required: ["firstId", "lastId", "count", "summary"],
 				additionalProperties: false,
 			},
+			// Register-level output block — see ctx_trim_status above.
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{ type: "text", text: value }],
+			},
 			async execute(args) {
 				const sessionId = sessionIdOf({});
 				if (sessionId === null) return "No session context available.";
@@ -1094,8 +1739,26 @@ export function applyContextTrim(ctx, config) {
 				const capture = captures.get(sessionId);
 				if (capture === undefined) return "No captured history yet — fold is unavailable until the next model call.";
 				const positions = refPositions(capture.messages);
-				const firstList = positions.get(String(args?.firstId ?? ""));
-				const lastList = positions.get(String(args?.lastId ?? ""));
+				// Ref normalization ([2026-11-15]-[m-prefix fold refs]): ctx_trim_status
+				// displays anchors in the protocol's [m...] form — "m" prepended to
+				// refOf's raw id/hash — and its description tells the model to pass
+				// exactly that form. The lookup map is keyed by the RAW ref, so an
+				// m-prefixed argument (the only form the model can copy) never matched:
+				// every model-driven fold failed with "Refs not found" (found live in
+				// the PTC runtime — status listed a 234-message range and the fold
+				// rejected it four times in a row). Resolve both forms: try the
+				// argument as given, then with one leading "m" stripped.
+				const resolveKey = (raw) => {
+					const given = String(raw ?? "");
+					if (positions.has(given)) return given;
+					if (given.startsWith("m") && positions.has(given.slice(1))) return given.slice(1);
+					return given;
+				};
+				const resolveRef = (raw) => positions.get(resolveKey(raw));
+
+				const firstList = resolveRef(args?.firstId);
+				const lastList = resolveRef(args?.lastId);
+
 				if (firstList === undefined || lastList === undefined) return "Refs not found in the current history — re-check with ctx_trim_status.";
 				// Count-anchored resolution: duplicate refs (identical content)
 				// make the first/last occurrence lists ambiguous — anchor on the
@@ -1110,6 +1773,15 @@ export function applyContextTrim(ctx, config) {
 				}
 				if (firstIdx < 0) { firstIdx = firstList[0]; lastIdx = lastList[lastList.length - 1]; }
 				if (lastIdx < firstIdx) return "lastId sorts before firstId in the current history.";
+				// Prior fold summaries are never raw-fold material: a T1 fold
+				// covering an acp_summary_* node would shadow the replacement
+				// node and break the ladder's consumed-run bookkeeping.
+				// Summaries consolidate only through ladder T2/T3 distillation.
+				for (let i = firstIdx; i <= lastIdx; i++) {
+					if (isFoldSummaryMessage(capture.messages[i])) {
+						return "Range covers a previous fold's summary (acp_summary_*) — summaries are preserved and consolidate via T2/T3 ladder; pick a range that excludes them.";
+					}
+				}
 				const { protectedTail } = thresholdsNow();
 				if (lastIdx >= capture.messages.length - Math.max(0, protectedTail)) return `Range reaches into the protected tail (last ${protectedTail} messages are never folded).`;
 				if (!rangeIsSegmentAligned(capture.messages, firstIdx, lastIdx)) return "Range splits a tool-call pair — fold whole assistant/tool segments (extend firstId/lastId to the segment boundaries).";
@@ -1117,7 +1789,12 @@ export function applyContextTrim(ctx, config) {
 				const result = store.commitFold(
 					sessionId,
 					{
-						refRange: { firstId: String(args.firstId), lastId: String(args.lastId) },
+						// Resolved refs: strip the display "m" prefix so commitFold's raw-key
+						// posMap lookup matches (same normalization as resolveRef above).
+						refRange: {
+							firstId: resolveKey(args.firstId),
+							lastId: resolveKey(args.lastId),
+						},
 						count,
 						approxTokens: estimateTokensOf(capture.messages, firstIdx, lastIdx),
 						summary: String(args.summary ?? ""),
@@ -1127,6 +1804,11 @@ export function applyContextTrim(ctx, config) {
 					positions,
 				);
 				if (!result.ok) return `Fold rejected: ${result.reason}.`;
+				// Auditable commit ([2026-11-15]-[tool-fold observability]): the only
+				// prior trace was the fold-commit SURFACE sweep; a sweep that failed
+				// or stayed pending left the commit itself invisible in the log.
+				decisionLog(`session=${sessionId} via=tool action=fold tier=advisory block=${result.block.id} msgs=${count} tokens=~${result.block.approxTokens}`);
+
 				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
@@ -1134,7 +1816,18 @@ export function applyContextTrim(ctx, config) {
 				const lowLedger = store.ledgerOf(sessionId);
 				const lowView = estimateTokensOf(buildView(capture.messages, lowLedger, { protectedTail: thresholdsNow().protectedTail }).messages);
 				store.recordFoldBaseline(sessionId, capture.viewTokens, lowView);
-				return `Folded ${count} messages into block ${result.block.id}. The view applies on the next model call.`;
+				// Ship the fresh block onto the session surface NOW instead of waiting for
+				// the next idle/turn-stopping boundary: a fold committed mid-turn used to
+				// stay meter-only for the rest of the turn (2026-11-14 live test: two
+				// tool-path folds left the wire carrying raw history for ~11 min at 97%
+				// pressure — injected=none on frozen dispatches, both blocks pending).
+				// The sweep's own guards (enabled flag, capable session, compaction lock,
+				// per-block validation) fail closed to pending; the boundary sweeps
+				// remain the closure pass.
+				void surfacePass.sweep(sessionId, "fold-commit").catch((error) => {
+					decisionLog(`session=${sessionId} surface-replace failed via=fold-commit why=${error?.message ?? error}`);
+				});
+				return `Folded ${count} messages into block ${result.block.id}. An immediate surface ship was queued (via=fold-commit): when it lands, even frozen dispatches carry the reduced history; if the surface cannot accept it right now the block stays pending and the boundary sweeps retry.`;
 			},
 		});
 	} catch (error) {
@@ -1152,11 +1845,24 @@ export function applyContextTrim(ctx, config) {
 				if (applied !== null) {
 					viewTokens = applied.viewTokens;
 					mainDispatch = applied.sideDispatch !== true;
+					if (mainDispatch) {
+						// Advisory pressure nudge (modeNow gates inside): the model's
+						// own fold is advisory mode's primary relief channel, plus the
+						// cooldown-gated critical relief fold below — speak at the fold
+						// line. Fail-open, never breaks the dispatch.
+						try {
+							deliverAdvisoryNudge(applied.sessionId, applied.viewTokens);
+						} catch (error) {
+							decisionLog(`advisory-nudge-failed why=${error?.message ?? error}`);
+							errorLog("advisory-nudge", error);
+						}
+					}
 				}
 			}
 		} catch (error) {
 			decisionLog(`view-build-failed why=${error?.message ?? error}`);
 			warn(`[context-trim] view build failed: ${error?.message ?? error}`);
+			errorLog("view-build", error);
 		}
 		const result = next();
 		let wrappedSession = null;
@@ -1169,10 +1875,24 @@ export function applyContextTrim(ctx, config) {
 				if (usage !== null) {
 					metrics.recordUsage(wrappedSession, usage);
 					if (mainDispatch) noteTrimWireTokens(wrappedSession, usage);
+					// Second proj sample point ([2026-11-15]-[proj sampling gaps]):
+					// the agent/status idle boundary alone left proj=null on most rows —
+					// long-running turns never go idle mid-flight, so the view-applied
+					// column went dark exactly when the divergence data mattered. At
+					// response end the agent handle is resolvable via
+					// ctx.agents.get(sessionId) (the same service subagents.js reads);
+					// unreachable => the sample silently skips, as designed.
+					try {
+						noteTrimProjectedTokens(wrappedSession, ctx.agents?.get?.(wrappedSession), ctx);
+					} catch {
+						/* observability must never break the stream */
+					}
 				}
 			});
 		} catch (error) {
 			warn(`[context-trim] stream wrap failed: ${error?.message ?? error}`);
+			decisionLog(`stream-wrap-failed why=${error?.message ?? error}`);
+			errorLog("stream-wrap", error);
 			return result;
 		} finally {
 			// Fallback fold check on the stream path: the agent/status idle event
@@ -1190,17 +1910,32 @@ export function applyContextTrim(ctx, config) {
 					if (nowMs - (lastStreamCheckAt.get(wrappedSession) ?? 0) >= 60_000) {
 						lastStreamCheckAt.set(wrappedSession, nowMs);
 						if (lastStreamCheckAt.size > 200) lastStreamCheckAt.delete(lastStreamCheckAt.keys().next().value);
-						void maybeFold(wrappedSession, "stream").finally(() => surfacePass.sweep(wrappedSession, "stream"));
+						void maybeFold(wrappedSession, "stream").finally(() => {
+							try {
+								void surfacePass.sweep(wrappedSession, "stream");
+							} catch (error) {
+								errorLog("surface-sweep-stream", error);
+							}
+						}).catch((error) => {
+							// maybeFold never rejects by design (its own catch is total), but a
+							// dispose-cut throw or a future regression must not become an
+							// unhandled rejection: the .finally here chains the sweep, so the
+							// void'd chain needs its own terminal handler (parity with the
+							// fold-commit sweep's .catch below).
+							errorLog("fold-stream", error);
+						});
 					}
 				}
-			} catch {
+			} catch (error) {
 				/* fallback must never break the stream */
+				errorLog("stream-fallback", error);
 			}
 		}
 	}
 
 	try {
 		ctx.inject(["llm"], (llmCtx) => {
+			const disposeListenerOf = new Map(); // "llm/stream" -> the on() disposer of the current attach
 			const attach = () => {
 				try {
 					// Global + prepend: the cordis dispatch filter silently drops NON-global
@@ -1209,10 +1944,23 @@ export function applyContextTrim(ctx, config) {
 					// subtree) — that silenced the whole stream path for a resumed session
 					// while fresh sessions kept logging. Stock consumers (dsh-session-title)
 					// register exactly this way.
-					llmCtx.on?.("llm/stream", streamListener, { global: true, prepend: true });
-					decisionLog(`llm-attached hasOn=${typeof llmCtx.on} hasOff=${typeof llmCtx.off} hasEffect=${typeof llmCtx.effect} pid=${process.pid}`);
+					// [2026-11-15]-[llm-attach diagnostics proxy trap]: reading llmCtx.off
+					// through the context proxy THROWS on the cordis build the harness
+					// ships (the events mixin exposes on/once/emit/… but NOT off —
+					// vendor/cordis/src/reflect.ts get-trap: `cannot get property "off"
+					// without inject`). `?.` cannot defend against a throwing getter, so
+					// the old SUCCESS row itself raised, landed as llm-attach-failed, and
+					// the true success line vanished (2026-11-15 06:29Z). on()'s returned
+					// disposer is the unsubscribe API; off never existed here.
+					const disposeListener = llmCtx.on?.("llm/stream", streamListener, { global: true, prepend: true });
+					disposeListenerOf.set("llm/stream", disposeListener);
+					let hasOff = false;
+					try { hasOff = typeof llmCtx.off === "function"; } catch { hasOff = false; }
+					decisionLog(`llm-attached hasOn=${typeof llmCtx.on} hasOff=${hasOff} hasDisposer=${typeof disposeListener} hasEffect=${typeof llmCtx.effect} pid=${process.pid}`);
 				} catch (error) {
 					warn(`[context-trim] llm/stream attach failed: ${error?.message ?? error}`);
+					decisionLog(`llm-attach-failed why=${error?.message ?? error}`);
+					errorLog("llm-attach", error);
 				}
 			};
 			// Reload-safe release (applyIntent precedent): undo the listener
@@ -1221,14 +1969,21 @@ export function applyContextTrim(ctx, config) {
 				const effect = llmCtx.effect;
 				if (typeof effect === "function") {
 					effect(function* () {
-						yield () => {
-							try {
-								llmCtx.off?.("llm/stream", streamListener);
-							} catch {
-								/* best effort */
-							}
-						};
-					}, "context-trim-stream-listener");
+					yield () => {
+						try {
+							// The on() disposer is the only real unsubscribe: ctx.off is not
+							// exposed by this cordis build (see the attach comment above) — the
+							// old llmCtx.off?.() call threw on EVERY reload teardown and the
+							// cleanup silently never ran (fiber-unload auto-dispose was the
+							// only thing that actually removed the listener).
+							const dispose = disposeListenerOf.get("llm/stream");
+							disposeListenerOf.delete("llm/stream");
+							if (typeof dispose === "function") dispose();
+						} catch {
+							/* best effort */
+						}
+					};
+				}, "context-trim-stream-listener");
 				}
 			} catch {
 				/* effect registration is best-effort */
@@ -1239,5 +1994,5 @@ export function applyContextTrim(ctx, config) {
 		warn(`[context-trim] ctx.inject(llm) failed: ${error?.message ?? error}`);
 	}
 
-	return { store, metrics, captures, inFlight, maybeFold, maybeInherit, applyViewToOptions, surfacePass };
+	return { store, metrics, captures, inFlight, windowCache, advisoryNudgeBySession, maybeFold, maybeInherit, applyViewToOptions, surfacePass };
 }