@namzu/sdk 2.0.0 → 3.1.0

package/src/runtime/query/iteration/phases/advisory.test.ts

@@ -4,7 +4,7 @@
  *   This file pins the live mutation boundary that `src/advisory/*` tests
  *   intentionally do NOT cover: the advisory phase IS where advisories
  *   inject user messages into the run via `ctx.runMgr.pushMessage(...)`
- *   (Codex #6). A regression that drops the `pushMessage` call — silently
+ *  . A regression that drops the `pushMessage` call — silently
  *   dropping all advisor output — would pass `src/advisory` tests,
  *   typecheck, and lint. This file is the only thing that catches it.
  *
@@ -142,6 +142,9 @@ function makeCtx(options: MockCtxOptions = {}): {
 		runMgr: {
 			id: 'run_1' as RunId,
 			messages: [],
+			// An advisory call is a billed model call on the run's budget;
+			// the phase now reports it so the guard can see it.
+			accumulateUsage: vi.fn(),
 			tokenUsage: {
 				promptTokens: 0,
 				completionTokens: 0,

package/src/runtime/query/iteration/phases/advisory.ts

@@ -1,5 +1,6 @@
 import { serializeState } from '../../../../compaction/serializer.js'
 import type { AdvisoryRequest, TriggerEvaluationState } from '../../../../types/advisory/index.js'
+import { toolResultToText } from '../../../../types/message/content.js'
 import { createUserMessage } from '../../../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import { toErrorMessage } from '../../../../utils/error.js'
@@ -110,6 +111,14 @@ export async function runAdvisoryPhase(
 
 		advisoryCtx.evaluator.recordFiring(trigger.id, iterationNum)
 
+		// An advisory call is a real model call on the run's dime. It was
+		// recorded into `callHistory` for reporting but never reached
+		// `runMgr.tokenUsage`, so the guard could not see it: a run with
+		// `tokenBudget: 200_000` and an `on_error` trigger could send well
+		// past 200k and never trip `token_budget`. The usage is already in
+		// hand — this just tells the accountant about it.
+		ctx.runMgr.accumulateUsage(executionResult.usage)
+
 		advisoryCtx.recordCall({
 			advisorId: advisor.id,
 			triggerId: trigger.id,
@@ -176,8 +185,11 @@ function extractLastErrorFromMessages(ctx: IterationContext): string | undefined
 	const messages = ctx.runMgr.messages
 	for (let i = messages.length - 1; i >= 0; i--) {
 		const msg = messages[i]
-		if (msg?.role === 'tool' && msg.content?.startsWith('Error:')) {
-			return msg.content
+		if (msg?.role === 'tool') {
+			// Tool results can now carry content blocks; the error sentinel is
+			// a text convention, so flatten before matching it.
+			const text = toolResultToText(msg.content)
+			if (text.startsWith('Error:')) return text
 		}
 	}
 	return undefined

package/src/runtime/query/iteration/phases/checkpoint.ts

@@ -3,7 +3,7 @@ import { CheckpointManager } from '../../checkpoint.js'
 import {
 	type IterationContext,
 	type PhaseSignal,
-	awaitDecisionOrAbort,
+	awaitDecisionDurably,
 	handleHITLDecision,
 } from './context.js'
 
@@ -47,7 +47,7 @@ export async function* runIterationCheckpoint(
 	yield* ctx.drainPending()
 
 	const summary = CheckpointManager.buildSummary(ctx.runMgr, iterationNum)
-	const iterDecision = await awaitDecisionOrAbort(ctx, {
+	const iterDecision = await awaitDecisionDurably(ctx, iterCheckpoint, {
 		type: 'iteration_checkpoint',
 		runId: ctx.runMgr.id,
 		checkpointId: iterCheckpoint.id,

package/src/runtime/query/iteration/phases/compaction-safe-cut.test.ts

@@ -180,7 +180,9 @@ describe('compaction — the unbounded cut', () => {
 
 		await runCompactionCheck(ctx)
 
-		const marker = messages.filter((m) => m.content?.includes('UNIQUE-MARKER'))
+		const marker = messages.filter(
+			(m) => typeof m.content === 'string' && m.content.includes('UNIQUE-MARKER'),
+		)
 		expect(marker).toHaveLength(1)
 	})
 })

package/src/runtime/query/iteration/phases/compaction.ts

@@ -1,7 +1,11 @@
+import { resolveContextWindow } from '../../../../compaction/context-window.js'
 import { findSafeTrimIndex } from '../../../../compaction/dangling.js'
+import { findRetainedIndices } from '../../../../compaction/retention.js'
 import { serializeState } from '../../../../compaction/serializer.js'
+import { clearStaleToolResults } from '../../../../compaction/tool-result-editing.js'
 import { buildVerifiedSummary } from '../../../../compaction/verifier.js'
 import { CHARS_PER_TOKEN } from '../../../../constants/limits.js'
+import type { Message } from '../../../../types/message/index.js'
 import { createSystemMessage } from '../../../../types/message/index.js'
 import type { IterationContext } from './context.js'
 import { isWorkingMemoryMessage } from './working-memory.js'
@@ -32,12 +36,46 @@ export function isCompactionMessage(content: string | null | undefined): boolean
  */
 const MIN_OLDER_MESSAGES_TO_COMPACT = 1
 
-function estimateTokens(ctx: IterationContext): number {
+/**
+ * How much a forced pass must shed before the turn is worth retrying.
+ *
+ * Both floors, whichever is larger. The fraction is what makes the bar
+ * scale: shedding 2 KB out of a 900 KB prompt is not relief, and retrying
+ * on it spends a whole model call to be told the same thing again. The
+ * absolute floor keeps a small prompt from being held to a meaningless
+ * fraction of itself.
+ */
+const MIN_RELIEF_FRACTION = 0.02
+const MIN_RELIEF_CHARS = 2_000
+
+/**
+ * Model-visible size of a message body, in characters.
+ *
+ * An image block is measured by its base64 payload because that is what
+ * actually occupies the request. It is NOT what the model is billed for —
+ * an image costs far fewer tokens than its base64 length divided by four —
+ * but under-counting it to zero is the worse error: it let a run full of
+ * screenshots read as an empty context.
+ */
+function measureContentChars(content: unknown): number {
+	if (typeof content === 'string') return content.length
+	if (!Array.isArray(content)) return 0
+	let total = 0
+	for (const block of content as readonly Record<string, unknown>[]) {
+		if (block.type === 'text' && typeof block.text === 'string') total += block.text.length
+		else if (block.type === 'image' && typeof block.data === 'string') total += block.data.length
+	}
+	return total
+}
+
+function estimateMessageTokens(messages: readonly Message[]): number {
 	let chars = 0
-	for (const msg of ctx.runMgr.messages) {
-		if (msg.content) {
-			chars += msg.content.length
-		}
+	for (const msg of messages) {
+		// `content` is `string | ToolResultBlock[]`. On an array, `.length` is
+		// the BLOCK COUNT, so a tool result carrying a 400 KB screenshot
+		// contributed 1 — and the estimate that decides when to compact read
+		// near zero for exactly the runs that need compacting most.
+		chars += measureContentChars(msg.content)
 		if (msg.role === 'assistant' && msg.toolCalls) {
 			for (const tc of msg.toolCalls) {
 				chars += tc.function.name.length + tc.function.arguments.length
@@ -47,7 +85,127 @@ function estimateTokens(ctx: IterationContext): number {
 	return Math.ceil(chars / CHARS_PER_TOKEN)
 }
 
-export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
+/**
+ * Tokens the tool catalogue occupies in every request.
+ *
+ * The catalogue is assembled separately from the message array and never
+ * entered the estimate, so a 30-tool registry — easily 10-20k tokens of
+ * JSON Schema — was invisible to the trigger. It is also the most stable
+ * part of the prompt, which is exactly why forgetting it biases every
+ * reading the same way rather than averaging out.
+ */
+function estimateToolCatalogTokens(ctx: IterationContext): number {
+	try {
+		const tools = ctx.tools.toLLMTools(ctx.allowedTools)
+		if (tools.length === 0) return 0
+		return Math.ceil(JSON.stringify(tools).length / CHARS_PER_TOKEN)
+	} catch {
+		// The catalogue is an optimisation of the estimate, not a
+		// precondition for compacting. A registry that cannot render is a
+		// problem for the model call, which will report it far better than
+		// a crash inside the trigger would.
+		return 0
+	}
+}
+
+function estimateTokens(ctx: IterationContext): number {
+	return estimateMessageTokens(ctx.runMgr.messages) + estimateToolCatalogTokens(ctx)
+}
+
+/**
+ * How full the context is, in tokens.
+ *
+ * Prefer the provider's own count of the last prompt — it is a measurement,
+ * not a guess, and it includes everything the heuristic cannot see (tool
+ * schemas, system blocks, image tokens, per-message framing). The chars/4
+ * estimate remains the fallback for iteration 1, before any turn has
+ * reported, and for providers that do not return usage.
+ *
+ * The measurement describes the prompt as it was SENT, so everything the
+ * turn appended afterwards — the assistant message and every one of its
+ * tool results — falls outside it. Reading it verbatim therefore reported
+ * a context one full turn stale, and staleness is largest on precisely the
+ * turns that add the most: a turn that returns 200 KB of tool output was
+ * counted as if it had returned nothing. That error and the missing tool
+ * catalogue both point the same way — under-count — so the trigger did not
+ * jitter around the threshold, it sat systematically late. The tail is
+ * estimated rather than measured because no provider in the repo exposes a
+ * token-count call; an approximate tail beats a certain omission.
+ */
+function measureContext(ctx: IterationContext): {
+	tokens: number
+	source: 'provider' | 'estimate'
+} {
+	const reported = ctx.runMgr.lastPromptTokens
+	if (reported !== undefined && reported > 0) {
+		const measuredThrough = ctx.runMgr.lastPromptMessageCount ?? ctx.runMgr.messages.length
+		const appended = ctx.runMgr.messages.slice(measuredThrough)
+		return { tokens: reported + estimateMessageTokens(appended), source: 'provider' }
+	}
+	return { tokens: estimateTokens(ctx), source: 'estimate' }
+}
+
+/**
+ * Shed history because the PROVIDER said the prompt is too long.
+ *
+ * The threshold path guesses when to compact and can guess low — the
+ * estimate is a heuristic, and a run carrying images or a language the
+ * chars-per-token ratio does not fit will hit the real window while still
+ * reading as comfortable. When that happens the provider tells us exactly
+ * what is wrong, and the kernel already classifies it precisely and then
+ * did nothing with it: the call was correctly marked non-retryable
+ * (resending the identical prompt cannot help) and the run died holding a
+ * compaction subsystem that could have made room.
+ *
+ * Forced rather than threshold-gated, because the threshold is the thing
+ * that was just proven wrong.
+ *
+ * @returns whether anything was actually shed. `false` means retrying would
+ *   send the same prompt again, so the caller must not.
+ */
+export async function relieveOverflow(ctx: IterationContext): Promise<boolean> {
+	const before = ctx.runMgr.messages.length
+	const beforeChars = totalChars(ctx.runMgr.messages)
+
+	await runCompactionCheck(ctx, { force: true })
+
+	const shed = beforeChars - totalChars(ctx.runMgr.messages)
+	// A shed has to be big enough to plausibly change the provider's verdict.
+	// Any positive number used to count, so clearing a single short tool
+	// result reported success, the turn was retried against a prompt that was
+	// still over the window, and the retry burned a call to learn nothing.
+	// The floor is a fraction of what was there rather than a constant: what
+	// counts as meaningful scales with the prompt.
+	const meaningful = Math.max(MIN_RELIEF_CHARS, beforeChars * MIN_RELIEF_FRACTION)
+	if (shed < meaningful) {
+		ctx.log.warn('Context overflow with too little left to shed — the prompt is irreducible', {
+			runId: ctx.runMgr.id,
+			messages: before,
+			charsShed: shed,
+			neededAtLeast: Math.ceil(meaningful),
+		})
+		return false
+	}
+
+	ctx.log.info('Relieved a context overflow by compacting', {
+		runId: ctx.runMgr.id,
+		messagesBefore: before,
+		messagesAfter: ctx.runMgr.messages.length,
+		charsShed: shed,
+	})
+	return true
+}
+
+function totalChars(messages: readonly { content: unknown }[]): number {
+	let total = 0
+	for (const msg of messages) total += measureContentChars(msg.content)
+	return total
+}
+
+export async function runCompactionCheck(
+	ctx: IterationContext,
+	options?: { force?: boolean },
+): Promise<void> {
 	const config = ctx.compactionConfig
 	if (!config) return
 	if (config.strategy === 'disabled') return
@@ -55,29 +213,92 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	const manager = ctx.workingStateManager
 	if (!manager) return
 
-	const estimatedTokens = estimateTokens(ctx)
-	// F1: measure the CURRENT window against the model context window when the
-	// host supplies one, falling back to the run-level cumulative `tokenBudget`
-	// otherwise. Repointing the SINGLE `budget` assignment moves BOTH the
-	// `<= 0` guard AND the divisor at once — so "compaction on + tokenBudget=0"
-	// is no longer a silent no-op. Existing consumers (no contextWindowTokens)
-	// stay byte-identical.
-	const budget = config.contextWindowTokens ?? ctx.runConfig.tokenBudget
-	if (budget <= 0) return
+	const measured = measureContext(ctx)
+	const estimatedTokens = measured.tokens
+
+	// The divisor is a WINDOW, never `runConfig.tokenBudget`. The old
+	// fallback compared a live context size against a cumulative spend cap
+	// — dimensionally the wrong quantity, and self-defeating: the guard
+	// force-finalizes at 0.9 x tokenBudget while this needs 0.7 x the same
+	// number. Nothing in the estate ever set `contextWindowTokens`, so the
+	// fallback WAS the behavior, and the shipped CLI's 1M budget put the
+	// trigger at ~700k. See `compaction/context-window.ts`.
+	const window = resolveContextWindow(config.contextWindowTokens, ctx.runConfig.model)
+	const budget = window.tokens
 
 	const usage = estimatedTokens / budget
 
-	if (usage < config.triggerThreshold) return
+	// A forced pass skips the threshold: it runs because the provider
+	// rejected the prompt, which is stronger evidence than any estimate.
+	if (!options?.force && usage < config.triggerThreshold) return
 
 	ctx.log.info('Compaction threshold reached — compacting context', {
 		runId: ctx.runMgr.id,
-		estimatedTokens,
-		budget,
+		contextTokens: estimatedTokens,
+		measuredBy: measured.source,
+		window: budget,
+		windowSource: window.source,
 		usage: Math.round(usage * 100),
 		triggerThreshold: config.triggerThreshold,
 		slotCount: manager.slotCount(),
 	})
 
+	// Try the cheap, NON-destructive reclaim first: clear the output of old,
+	// large tool results in place. Compaction paraphrases the agent's own
+	// reasoning away, which is a heavy price for a context problem usually
+	// caused by something dumber — a few enormous tool outputs the agent
+	// already read and moved past. Clearing those keeps every message
+	// verbatim, and keeps `tool_use` ↔ `tool_result` pairing intact by
+	// construction, because nothing moves.
+	if (config.clearToolResults !== false) {
+		const edit = clearStaleToolResults(ctx.runMgr.messages, {
+			...(config.keepRecentToolResults !== undefined
+				? { keepRecentToolResults: config.keepRecentToolResults }
+				: {}),
+			...(config.minToolResultCharsToClear !== undefined
+				? { minCharsToClear: config.minToolResultCharsToClear }
+				: {}),
+			...(config.preserveToolResultsFrom ? { preserveTools: config.preserveToolResultsFrom } : {}),
+		})
+
+		if (edit.clearedCount > 0) {
+			// Element-wise, not a rebuild: the edit is length-preserving by
+			// construction (only `content` changes), so writing entries back
+			// keeps the live array identity the rest of the run holds.
+			const live = ctx.runMgr.messages
+			edit.messages.forEach((msg, i) => {
+				live[i] = msg
+			})
+
+			const reclaimedTokens = Math.ceil(edit.charsReclaimed / CHARS_PER_TOKEN)
+			ctx.log.info('Cleared stale tool results instead of compacting', {
+				runId: ctx.runMgr.id,
+				cleared: edit.clearedCount,
+				charsReclaimed: edit.charsReclaimed,
+				reclaimedTokens,
+			})
+
+			// If that was enough, stop here and keep the history verbatim.
+			// The measurement is an estimate either way; the provider's own
+			// count for the NEXT turn will correct it, and an over-eager
+			// summarization is far more costly than one late pass.
+			//
+			// NOT on a forced pass. A forced pass runs because the provider
+			// REJECTED the prompt as too long, which is a measurement — and
+			// this branch would answer it with the same estimate the provider
+			// just refuted, declare success after clearing one result, and
+			// hand back a history that overflows again on the retry. The
+			// estimate is the thing that was proven wrong; it does not get to
+			// end the pass.
+			if (
+				!options?.force &&
+				(estimatedTokens - reclaimedTokens) / budget < config.triggerThreshold
+			) {
+				return
+			}
+		}
+	}
+
 	const messages = ctx.runMgr.messages
 	if (messages.length < config.keepRecentMessages + 2) {
 		ctx.log.debug('Not enough messages to compact', {
@@ -94,35 +315,17 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	}
 	if (systemMessages.length === 0) return
 
-	// Tool-pair atomicity guard, taken DOWNWARD.
-	//
-	// A naive cut at `length - keepRecentMessages` can land BETWEEN an
-	// assistant-with-toolCalls (dropped into `olderMessages`) and its `tool`
-	// results (kept in `recentMessages`), leaving orphaned `tool_result` blocks at
-	// the head of the recent window. The Anthropic provider then emits a
-	// `tool_result` with no matching `tool_use` and the API rejects the next turn
-	// with a 400 — so compaction, whose whole job is to keep a long run alive,
-	// instead kills it.
-	//
-	// Snapping FORWARD via `findSafeTrimIndex` fixes the orphan and introduces a
-	// worse failure. That walk skips leading `tool` messages with no stop short of
-	// `messages.length`, so whenever the entire suffix from the naive index is
-	// `tool` messages, the boundary lands ON `messages.length`: `recentMessages`
-	// comes back EMPTY and `[...preservedSystem, compactionMessage]` replaces the
-	// whole recent window. The model is then asked to answer a conversation whose
-	// last turn — including the user's own message — was deleted, and it answers a
-	// question nobody asked. The shape is routine, not exotic: one assistant turn
-	// fanning out `>= keepRecentMessages` parallel tool calls, measured at the
-	// start of the very next iteration, which is exactly where this runs. The
-	// `olderMessages` floor guard below cannot catch it either — in that shape
-	// `olderMessages` is the whole transcript.
-	//
-	// So take the LARGEST safe boundary AT OR BELOW naive instead. A cut that low
-	// removes no more than the naive cut would, so at least `keepRecentMessages`
-	// original messages always survive verbatim, and the transcript can never be
-	// reduced to system messages alone. `findSafeTrimIndex(m, k) === k` is the
-	// safety predicate — reused rather than reimplemented, so the function itself
-	// (public API, other callers) is untouched.
+	// Tool-pair atomicity guard. A naive cut at `length - keepRecentMessages`
+	// can land BETWEEN an assistant-with-toolCalls (which would be dropped into
+	// `olderMessages`) and its `tool` results (kept in `recentMessages`),
+	// leaving orphaned `tool_result` blocks at the head of the recent window.
+	// The provider then emits a `tool_result` with no matching
+	// `tool_use` and the API rejects the next turn with a 400 — so compaction,
+	// whose whole job is to keep a long run alive, instead kills it. Snap the
+	// boundary FORWARD to a safe point (existing `findSafeTrimIndex`, previously
+	// only wired to the unused ConversationManager strategy classes) so no pair
+	// is split. Any message this moves out of the recent window is already
+	// represented in the extracted WorkingState the summary is built from.
 	const naiveKeepStart = messages.length - config.keepRecentMessages
 	let keepStart = -1
 	for (let candidate = naiveKeepStart; candidate > systemMessages.length; candidate--) {
@@ -153,10 +356,14 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 
 	// D7: nothing meaningful to compact — skip instead of thrashing the
 	// permanent leading floor every iteration (and avoid an LLM verification
-	// call when there is no older history to summarize). Scoped to the new
-	// contextWindowTokens path so any existing consumer (tokenBudget-only) keeps
-	// its exact prior behavior — byte-identical (ses_055 verify).
-	if (config.contextWindowTokens != null && olderMessages.length < MIN_OLDER_MESSAGES_TO_COMPACT) {
+	// call when there is no older history to summarize).
+	//
+	// This guard used to be gated on `contextWindowTokens != null` to keep
+	// the tokenBudget path byte-identical. That path's actual behavior was
+	// "never fires", so there is nothing left to preserve — and now that the
+	// trigger works, an ungated consumer would thrash. Same for the prior-
+	// summary replacement below.
+	if (olderMessages.length < MIN_OLDER_MESSAGES_TO_COMPACT) {
 		ctx.log.debug('Skipping compaction — too few older messages', {
 			runId: ctx.runMgr.id,
 			olderMessages: olderMessages.length,
@@ -167,25 +374,42 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	let compactedContent: string
 
 	if (config.llmVerification && manager.slotCount() < config.richStateThreshold) {
-		compactedContent = await buildVerifiedSummary(manager, olderMessages, ctx.provider, config)
+		compactedContent = await buildVerifiedSummary(
+			manager,
+			olderMessages,
+			ctx.provider,
+			config,
+			(usage) => ctx.runMgr.accumulateUsage(usage),
+			ctx.runConfig.model,
+		)
 	} else {
 		compactedContent = serializeState(manager.getState())
 	}
 
 	const compactionMessage = createSystemMessage(`${COMPACTION_HEADER}\n\n${compactedContent}`)
 
-	// On the new per-iteration (contextWindowTokens) path, drop any PRIOR
-	// `[COMPACTED CONTEXT]` summary from the leading floor — `serializeState` is
-	// cumulative, so the new summary supersedes it. Without this the never-trimmed
-	// floor accumulates one redundant summary per pass and the frequent
-	// per-iteration trigger makes that bloat unbounded (ses_055 verify, MEDIUM).
-	// Legacy consumers (no contextWindowTokens) keep their exact prior
-	// accumulation behavior — byte-identical.
-	const preservedSystem =
-		config.contextWindowTokens != null
-			? systemMessages.filter((m) => !isCompactionMessage(m.content))
-			: systemMessages
-	const newMessages = [...preservedSystem, compactionMessage, ...recentMessages]
+	// Drop any PRIOR `[COMPACTED CONTEXT]` summary from the leading floor —
+	// `serializeState` is cumulative, so the new summary supersedes it.
+	// Without this the never-trimmed floor accumulates one redundant summary
+	// per pass, unbounded. Unconditional now, for the reason given at the
+	// thrash guard above.
+	const preservedSystem = systemMessages.filter(
+		(m) => !isCompactionMessage(typeof m.content === 'string' ? m.content : null),
+	)
+
+	// Pinned turns from the older window survive verbatim, in order, between
+	// the summary and the recent window. They are also described by the
+	// summary, which is the point rather than a waste: a paraphrase is what
+	// the pin exists to refuse.
+	const retained = findRetainedIndices(messages)
+	const retainedOlder =
+		retained.size === 0
+			? []
+			: messages
+					.slice(systemMessages.length, keepStart)
+					.filter((_, offset) => retained.has(systemMessages.length + offset))
+
+	const newMessages = [...preservedSystem, compactionMessage, ...retainedOlder, ...recentMessages]
 
 	// OPAQUE survival guard (ses_055 D1): the pinned working-memory slot is a
 	// leading system message, so it is kept in `preservedSystem` (the compaction
@@ -215,6 +439,29 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 
 	const newEstimate = estimateTokens(ctx)
 
+	// The provider's count described the PRE-compaction prompt; the window
+	// it just shrank to has not been sent yet, so the post number is
+	// necessarily an estimate. Invalidate the stale reading so the next
+	// trigger check does not compare the old prompt size against the new
+	// context and compact again immediately.
+	ctx.runMgr.clearLastPromptTokens?.()
+
+	// Hysteresis. A pass that only gets the context from 0.72 to 0.71 of the
+	// window leaves the trigger armed, so the next iteration compacts again
+	// — paying a summarization call and busting the prompt-cache prefix each
+	// time, for nothing. Report the shortfall rather than repeating a move
+	// that demonstrably does not work; `resetThreshold` was declared and
+	// CLI-set but read by nothing until now.
+	const reachedReset = newEstimate / budget <= config.resetThreshold
+	if (!reachedReset) {
+		ctx.log.warn('Compaction did not reach its reset threshold — context may still be tight', {
+			runId: ctx.runMgr.id,
+			afterUsage: Math.round((newEstimate / budget) * 100),
+			resetThreshold: Math.round(config.resetThreshold * 100),
+			hint: 'lower keepRecentMessages, or raise the context window if the model supports one',
+		})
+	}
+
 	ctx.log.info('Context compacted', {
 		runId: ctx.runMgr.id,
 		oldMessageCount: oldCount,
@@ -223,6 +470,24 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 		oldTokenEstimate: estimatedTokens,
 		newTokenEstimate: newEstimate,
 		reductionPercent: Math.round((1 - newEstimate / estimatedTokens) * 100),
+		reachedReset,
 		slotCount: manager.slotCount(),
 	})
+
+	// Compaction is destructive and was, until now, completely silent: no
+	// event, no transcript record, nothing a host could surface. Emit the
+	// loss so it is observable.
+	await ctx.emitEvent?.({
+		type: 'compaction_completed',
+		runId: ctx.runMgr.id,
+		iteration: ctx.runMgr.currentIteration,
+		messagesBefore: oldCount,
+		messagesAfter: messages.length,
+		tokensBefore: estimatedTokens,
+		tokensAfter: newEstimate,
+		measuredBy: measured.source,
+		contextWindowTokens: budget,
+		windowSource: window.source,
+		reachedResetThreshold: reachedReset,
+	})
 }