@namzu/sdk 42.0.2 → 44.0.0

package/src/bus/breaker.ts

@@ -2,18 +2,19 @@ import {
 	DEFAULT_BREAKER_FAILURE_THRESHOLD,
 	DEFAULT_BREAKER_RESET_TIMEOUT_MS,
 } from '../constants/bus/index.js'
+import { NAMZU } from '../constants/telemetry/index.js'
 import type {
 	AgentBusEvent,
 	CircuitBreakerSnapshot,
 	CircuitBreakerState,
 } from '../types/bus/index.js'
-import type { RunId } from '../types/ids/index.js'
+import type { SessionId } from '../types/ids/index.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import type { Logger } from '../utils/logger.js'
 
 interface MutableBreakerState {
 	state: CircuitBreakerState
-	agentRunId: RunId
+	agentSessionId: SessionId
 	consecutiveFailures: number
 	lastFailureAt?: number
 	lastSuccessAt?: number
@@ -39,8 +40,8 @@ export class CircuitBreaker {
 		this.emit = emit
 	}
 
-	canExecute(agentRunId: RunId): boolean {
-		const breaker = this.breakers.get(agentRunId)
+	canExecute(agentSessionId: SessionId): boolean {
+		const breaker = this.breakers.get(agentSessionId)
 		if (!breaker) return true
 
 		switch (breaker.state) {
@@ -51,10 +52,10 @@ export class CircuitBreaker {
 				if (elapsed >= this.resetTimeoutMs) {
 					breaker.state = 'half_open'
 					this.log.info('circuit breaker transitioning to half_open', {
-						'namzu.agent.run_id': agentRunId,
+						[NAMZU.SESSION_ID]: agentSessionId,
 						'namzu.bus.elapsed': elapsed,
 					})
-					this.emit({ type: 'breaker_half_open', agentRunId })
+					this.emit({ type: 'breaker_half_open', agentSessionId })
 					return true
 				}
 				return false
@@ -68,8 +69,8 @@ export class CircuitBreaker {
 		}
 	}
 
-	recordSuccess(agentRunId: RunId): void {
-		const breaker = this.breakers.get(agentRunId)
+	recordSuccess(agentSessionId: SessionId): void {
+		const breaker = this.breakers.get(agentSessionId)
 		if (!breaker) return
 
 		const previousState = breaker.state
@@ -83,14 +84,14 @@ export class CircuitBreaker {
 				breaker.state = 'closed'
 				breaker.trippedAt = undefined
 				this.log.info('circuit breaker reset after probe success', {
-					'namzu.agent.run_id': agentRunId,
+					[NAMZU.SESSION_ID]: agentSessionId,
 				})
-				this.emit({ type: 'breaker_probe_success', agentRunId })
-				this.emit({ type: 'breaker_reset', agentRunId })
+				this.emit({ type: 'breaker_probe_success', agentSessionId })
+				this.emit({ type: 'breaker_reset', agentSessionId })
 				break
 			case 'open':
 				this.log.warn('recordSuccess called while breaker is open', {
-					'namzu.agent.run_id': agentRunId,
+					[NAMZU.SESSION_ID]: agentSessionId,
 					'namzu.bus.previous_state': previousState,
 				})
 				break
@@ -101,15 +102,15 @@ export class CircuitBreaker {
 		}
 	}
 
-	recordFailure(agentRunId: RunId): void {
-		let breaker = this.breakers.get(agentRunId)
+	recordFailure(agentSessionId: SessionId): void {
+		let breaker = this.breakers.get(agentSessionId)
 		if (!breaker) {
 			breaker = {
 				state: 'closed',
-				agentRunId,
+				agentSessionId,
 				consecutiveFailures: 0,
 			}
-			this.breakers.set(agentRunId, breaker)
+			this.breakers.set(agentSessionId, breaker)
 		}
 
 		breaker.consecutiveFailures += 1
@@ -121,12 +122,12 @@ export class CircuitBreaker {
 					breaker.state = 'open'
 					breaker.trippedAt = Date.now()
 					this.log.warn('circuit breaker tripped', {
-						'namzu.agent.run_id': agentRunId,
+						[NAMZU.SESSION_ID]: agentSessionId,
 						'namzu.bus.consecutive_failures': breaker.consecutiveFailures,
 					})
 					this.emit({
 						type: 'breaker_tripped',
-						agentRunId,
+						agentSessionId,
 						consecutiveFailures: breaker.consecutiveFailures,
 					})
 				}
@@ -135,12 +136,12 @@ export class CircuitBreaker {
 				breaker.state = 'open'
 				breaker.trippedAt = Date.now()
 				this.log.warn('circuit breaker re-tripped from half_open', {
-					'namzu.agent.run_id': agentRunId,
+					[NAMZU.SESSION_ID]: agentSessionId,
 				})
-				this.emit({ type: 'breaker_probe_failure', agentRunId })
+				this.emit({ type: 'breaker_probe_failure', agentSessionId })
 				this.emit({
 					type: 'breaker_tripped',
-					agentRunId,
+					agentSessionId,
 					consecutiveFailures: breaker.consecutiveFailures,
 				})
 				break
@@ -153,13 +154,13 @@ export class CircuitBreaker {
 		}
 	}
 
-	getSnapshot(agentRunId: RunId): CircuitBreakerSnapshot | undefined {
-		const breaker = this.breakers.get(agentRunId)
+	getSnapshot(agentSessionId: SessionId): CircuitBreakerSnapshot | undefined {
+		const breaker = this.breakers.get(agentSessionId)
 		if (!breaker) return undefined
 
 		return {
 			state: breaker.state,
-			agentRunId: breaker.agentRunId,
+			agentSessionId: breaker.agentSessionId,
 			consecutiveFailures: breaker.consecutiveFailures,
 			lastFailureAt: breaker.lastFailureAt,
 			lastSuccessAt: breaker.lastSuccessAt,
@@ -167,15 +168,15 @@ export class CircuitBreaker {
 		}
 	}
 
-	reset(agentRunId: RunId): void {
-		const breaker = this.breakers.get(agentRunId)
+	reset(agentSessionId: SessionId): void {
+		const breaker = this.breakers.get(agentSessionId)
 		if (!breaker) return
 
 		breaker.state = 'closed'
 		breaker.consecutiveFailures = 0
 		breaker.trippedAt = undefined
-		this.log.info('circuit breaker manually reset', { 'namzu.agent.run_id': agentRunId })
-		this.emit({ type: 'breaker_reset', agentRunId })
+		this.log.info('circuit breaker manually reset', { [NAMZU.SESSION_ID]: agentSessionId })
+		this.emit({ type: 'breaker_reset', agentSessionId })
 	}
 
 	listTripped(): CircuitBreakerSnapshot[] {
@@ -184,7 +185,7 @@ export class CircuitBreaker {
 			if (breaker.state === 'open' || breaker.state === 'half_open') {
 				tripped.push({
 					state: breaker.state,
-					agentRunId: breaker.agentRunId,
+					agentSessionId: breaker.agentSessionId,
 					consecutiveFailures: breaker.consecutiveFailures,
 					lastFailureAt: breaker.lastFailureAt,
 					lastSuccessAt: breaker.lastSuccessAt,

package/src/bus/index.ts

@@ -8,7 +8,7 @@ import {
 import { buildProbeContext } from '../probe/context.js'
 import { type ProbeRegistry, probe as defaultProbeRegistry } from '../probe/registry.js'
 import type { AgentBusEvent, AgentBusEventListener } from '../types/bus/index.js'
-import type { RunId } from '../types/ids/index.js'
+import type { SessionId } from '../types/ids/index.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import type { Logger } from '../utils/logger.js'
 
@@ -95,14 +95,14 @@ export class AgentBus {
 		})
 	}
 
-	cleanupAgent(runId: RunId): void {
-		this.log.info('cleaning up agent resources', { [NAMZU.RUN_ID]: runId })
-		const locksReleased = this.locks.releaseAll(runId)
-		const ownershipsReleased = this.ownership.releaseAll(runId)
-		this.breaker.reset(runId)
+	cleanupAgent(sessionId: SessionId): void {
+		this.log.info('cleaning up agent resources', { [NAMZU.SESSION_ID]: sessionId })
+		const locksReleased = this.locks.releaseAll(sessionId)
+		const ownershipsReleased = this.ownership.releaseAll(sessionId)
+		this.breaker.reset(sessionId)
 
 		this.log.info('agent cleanup complete', {
-			[NAMZU.RUN_ID]: runId,
+			[NAMZU.SESSION_ID]: sessionId,
 			'namzu.bus.locks_released': locksReleased,
 			'namzu.bus.ownerships_released': ownershipsReleased,
 		})

package/src/bus/lock.ts

@@ -8,7 +8,7 @@ import {
 	LOCK_ACQUIRE_POLL_INTERVAL_MS,
 } from '../constants/bus/index.js'
 import type { AgentBusEvent, FileLock, LockAcquireResult, LockId } from '../types/bus/index.js'
-import type { RunId } from '../types/ids/index.js'
+import type { SessionId } from '../types/ids/index.js'
 import { asLockId } from '../utils/id.js'
 import type { Logger } from '../utils/logger.js'
 
@@ -45,7 +45,7 @@ export class FileLockManager {
 		return asLockId(randomUUID())
 	}
 
-	private getAgentLockSet(owner: RunId): Set<string> {
+	private getAgentLockSet(owner: SessionId): Set<string> {
 		let lockSet = this.agentLocks.get(owner)
 		if (!lockSet) {
 			lockSet = new Set()
@@ -54,7 +54,7 @@ export class FileLockManager {
 		return lockSet
 	}
 
-	private tryAcquire(filePath: string, owner: RunId): LockAcquireResult {
+	private tryAcquire(filePath: string, owner: SessionId): LockAcquireResult {
 		const existing = this.locks.get(filePath)
 		if (existing) {
 			if (existing.owner === owner) {
@@ -106,7 +106,7 @@ export class FileLockManager {
 		return { acquired: true, lock }
 	}
 
-	async acquire(filePath: string, owner: RunId): Promise<LockAcquireResult> {
+	async acquire(filePath: string, owner: SessionId): Promise<LockAcquireResult> {
 		this.expireStale()
 
 		const immediate = this.tryAcquire(filePath, owner)
@@ -131,7 +131,7 @@ export class FileLockManager {
 		}
 	}
 
-	release(filePath: string, owner: RunId): boolean {
+	release(filePath: string, owner: SessionId): boolean {
 		const existing = this.locks.get(filePath)
 		if (!existing || existing.owner !== owner) {
 			return false
@@ -158,7 +158,7 @@ export class FileLockManager {
 		return true
 	}
 
-	releaseAll(owner: RunId): number {
+	releaseAll(owner: SessionId): number {
 		const agentLockSet = this.agentLocks.get(owner)
 		if (!agentLockSet) return 0
 
@@ -196,7 +196,7 @@ export class FileLockManager {
 		return true
 	}
 
-	getHolder(filePath: string): RunId | undefined {
+	getHolder(filePath: string): SessionId | undefined {
 		const lock = this.locks.get(filePath)
 		if (!lock) return undefined
 		if (lock.expiresAt !== undefined && Date.now() > lock.expiresAt) {

package/src/bus/ownership.ts

@@ -2,7 +2,7 @@ import path from 'node:path'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 
 import type { AgentBusEvent, FileOwnership, OwnershipClaimResult } from '../types/bus/index.js'
-import type { RunId } from '../types/ids/index.js'
+import type { SessionId } from '../types/ids/index.js'
 import type { Logger } from '../utils/logger.js'
 
 export class EditOwnershipTracker {
@@ -19,7 +19,7 @@ export class EditOwnershipTracker {
 		return path.resolve(filePath)
 	}
 
-	claim(filePath: string, owner: RunId): OwnershipClaimResult {
+	claim(filePath: string, owner: SessionId): OwnershipClaimResult {
 		const normalized = this.normalizePath(filePath)
 		const existing = this.ownerships.get(normalized)
 
@@ -54,7 +54,7 @@ export class EditOwnershipTracker {
 		return { claimed: true, ownership }
 	}
 
-	release(filePath: string, owner: RunId): boolean {
+	release(filePath: string, owner: SessionId): boolean {
 		const normalized = this.normalizePath(filePath)
 		const existing = this.ownerships.get(normalized)
 
@@ -71,7 +71,7 @@ export class EditOwnershipTracker {
 		return true
 	}
 
-	transfer(filePath: string, from: RunId, to: RunId): boolean {
+	transfer(filePath: string, from: SessionId, to: SessionId): boolean {
 		const normalized = this.normalizePath(filePath)
 		const existing = this.ownerships.get(normalized)
 
@@ -95,7 +95,7 @@ export class EditOwnershipTracker {
 		return true
 	}
 
-	releaseAll(owner: RunId): number {
+	releaseAll(owner: SessionId): number {
 		let released = 0
 		for (const [normalized, ownership] of this.ownerships) {
 			if (ownership.owner === owner) {
@@ -115,12 +115,12 @@ export class EditOwnershipTracker {
 		return released
 	}
 
-	getOwner(filePath: string): RunId | undefined {
+	getOwner(filePath: string): SessionId | undefined {
 		const normalized = this.normalizePath(filePath)
 		return this.ownerships.get(normalized)?.owner
 	}
 
-	listByOwner(owner: RunId): FileOwnership[] {
+	listByOwner(owner: SessionId): FileOwnership[] {
 		const result: FileOwnership[] = []
 		for (const ownership of this.ownerships.values()) {
 			if (ownership.owner === owner) {
@@ -130,7 +130,7 @@ export class EditOwnershipTracker {
 		return result
 	}
 
-	checkConflict(filePath: string, requester: RunId): RunId | undefined {
+	checkConflict(filePath: string, requester: SessionId): SessionId | undefined {
 		const normalized = this.normalizePath(filePath)
 		const existing = this.ownerships.get(normalized)
 		if (existing && existing.owner !== requester) {

package/src/compaction/consolidation.ts

@@ -1,26 +1,36 @@
 /**
- * Consolidation: what a run learned, written down where the next run can
+ * Consolidation: what a turn learned, written down where a later turn can
  * find it.
  *
- * The working state is episodic memory — what happened in THIS run: the
+ * The working state is episodic memory — what happened in THIS turn: the
  * decisions taken, the discoveries made, the failures met and how. It
- * dies with the run, and the semantic store behind `search_memory` only
+ * dies with the turn, and the semantic store behind `search_memory` only
  * ever received what a model chose to `save_memory` mid-task, which is
- * rarely the thing a later run needed. Consolidation is the bridge: at
- * the end of a run, the entries that can outlive it become one memory
- * entry, tagged so a later run can search for what was learned rather
+ * rarely the thing a later turn needed. Consolidation is the bridge: at
+ * the end of a turn, the entries that can outlive it become one memory
+ * entry, tagged so a later turn can search for what was learned rather
  * than what was done. What is deliberately NOT carried: the tool
  * results, the plan, the requirements — those describe the task, not a
  * lesson. Pure: the caller writes the entry, this only says what it is.
  */
 
-import type { CreateMemoryParams } from '../types/memory/index.js'
+import {
+	KNOWLEDGE_TAG_PREFIX,
+	holdsKnowledgeDigest,
+	knowledgeDigest,
+} from '../store/memory/digest.js'
+import { CONSOLIDATION_KIND } from '../store/memory/origin.js'
+import type { SessionId, TurnId } from '../types/ids/index.js'
+import type { CreateMemoryParams, MemoryStore } from '../types/memory/index.js'
 import type { WorkingState } from './types.js'
 
 export const CONSOLIDATION_TAG = 'learning'
 
 export interface ConsolidationMeta {
-	readonly runId: string
+	/** The session the learning turn belongs to; tagged `session:<id>`. */
+	readonly sessionId: SessionId
+	/** The turn that learned it; tagged `turn:<id>`. */
+	readonly turnId: TurnId
 	/** Milliseconds since the epoch, for the entry's metadata. */
 	readonly at: number
 }
@@ -33,9 +43,30 @@ function head(text: string, max: number): string {
 }
 
 /**
- * The memory entry a run's state consolidates to, or `null` when the run
- * learned nothing worth a later run's attention — no decisions, no
- * discoveries, no failures. A run that only read and edited leaves no
+ * Whether `store` already holds a consolidation of exactly this knowledge.
+ *
+ * {@link consolidationEntry} is pure and cannot ask; the caller asks this
+ * before writing, the way the promoter does, so a turn that learned what an
+ * earlier turn already recorded — archived included — writes nothing.
+ */
+export async function isConsolidated(
+	store: MemoryStore,
+	entry: CreateMemoryParams,
+): Promise<boolean> {
+	const digest = entry.metadata?.knowledgeDigest
+	if (typeof digest !== 'string') return false
+	return holdsKnowledgeDigest(
+		store,
+		[CONSOLIDATION_TAG],
+		digest,
+		(metadata) => metadata?.kind === CONSOLIDATION_KIND,
+	)
+}
+
+/**
+ * The memory entry a turn's state consolidates to, or `null` when the turn
+ * learned nothing worth a later turn's attention — no decisions, no
+ * discoveries, no failures. A turn that only read and edited leaves no
  * entry rather than an empty one.
  */
 export function consolidationEntry(
@@ -68,12 +99,27 @@ export function consolidationEntry(
 			: '',
 		failures.length ? `${failures.length} failure${failures.length === 1 ? '' : 's'}` : '',
 	].filter((part) => part.length > 0)
+	// What was learned, not which turn learned it: two turns reaching the same
+	// decisions, discoveries and failures consolidate to one record.
+	const digest = knowledgeDigest({ decisions, discoveries, failures })
 	return {
-		title: task ? `Learned: ${head(task, MAX_TASK_IN_TITLE)}` : `Learned in run ${meta.runId}`,
-		summary: `${counts.join(', ')} from run ${meta.runId}.`,
+		title: task ? `Learned: ${head(task, MAX_TASK_IN_TITLE)}` : `Learned in turn ${meta.turnId}`,
+		summary: `${counts.join(', ')} from turn ${meta.turnId} of session ${meta.sessionId}.`,
 		content,
 		format: 'markdown',
-		tags: [CONSOLIDATION_TAG, `run:${meta.runId}`],
-		metadata: { runId: meta.runId, consolidatedAt: meta.at, kind: 'consolidation' },
+		type: 'project',
+		tags: [
+			CONSOLIDATION_TAG,
+			`session:${meta.sessionId}`,
+			`turn:${meta.turnId}`,
+			`${KNOWLEDGE_TAG_PREFIX}${digest}`,
+		],
+		metadata: {
+			sessionId: meta.sessionId,
+			turnId: meta.turnId,
+			consolidatedAt: meta.at,
+			kind: CONSOLIDATION_KIND,
+			knowledgeDigest: digest,
+		},
 	}
 }

package/src/compaction/context-window.ts

@@ -2,8 +2,8 @@
  * Model context-window resolution for the compaction trigger.
  *
  * Compaction asks "how full is the window?". That question needs a WINDOW,
- * and the runtime previously answered it with `runConfig.tokenBudget` — the
- * run's cumulative spend cap. The two are different quantities, and using
+ * and the runtime previously answered it with `turnConfig.tokenBudget` — the
+ * turn's cumulative spend cap. The two are different quantities, and using
  * the second as the divisor for the first is self-defeating: cumulative
  * spend always exceeds the live window, and the guard force-finalizes at
  * 0.9 x tokenBudget while compaction needs 0.7 x the same number, so the
@@ -34,7 +34,7 @@
  * Conservative default for a model we do not recognise.
  *
  * Under-estimating is the safe direction: it compacts earlier than needed,
- * costing a summarization pass. Over-estimating means the run dies on a
+ * costing a summarization pass. Over-estimating means the turn dies on a
  * provider `context_length_exceeded` with nothing recoverable.
  */
 export const DEFAULT_ASSUMED_CONTEXT_WINDOW = 128_000
@@ -133,7 +133,7 @@ export function resolveContextWindow(
 	 *
 	 * A plain number rather than a promise, because both call sites are
 	 * synchronous and sit in the hot loop. Resolving happens once at the
-	 * start of a run; this parameter is that answer being carried in.
+	 * start of a turn; this parameter is that answer being carried in.
 	 */
 	providerReported?: number,
 ): ResolvedContextWindow {

package/src/compaction/index.ts

@@ -97,6 +97,6 @@ export type {
 } from './salience/index.js'
 export { DEFAULT_SOFT_TARGET, planSalienceWorkingSet } from './plan.js'
 
-// Episodic → semantic: what a run learned, as the entry a later run searches.
-export { CONSOLIDATION_TAG, consolidationEntry } from './consolidation.js'
+// Episodic → semantic: what a turn learned, as the entry a later turn searches.
+export { CONSOLIDATION_TAG, consolidationEntry, isConsolidated } from './consolidation.js'
 export type { ConsolidationMeta } from './consolidation.js'

package/src/compaction/manager.ts

@@ -98,7 +98,7 @@ export class WorkingStateManager {
 	 * Failures evict OLDEST-first, unlike every other slot here.
 	 *
 	 * `keepFirstEntries` exists because early decisions are load-bearing —
-	 * the one that set the run's approach outlives twenty-five incidental
+	 * the one that set the turn's approach outlives twenty-five incidental
 	 * notes. That reasoning is right for decisions and backwards for
 	 * failures: the earliest failure is the one the model has most likely
 	 * already worked around, and the recent one is the thing it reads to
@@ -107,7 +107,7 @@ export class WorkingStateManager {
 	 * It also matters more than a preference. Sinha et al.,
 	 * "The Illusion of Diminishing Returns" (arXiv:2509.09677), inject
 	 * errors into a model's own history at controlled rates and measure
-	 * accuracy far later in the run: conditioning a model on its own
+	 * accuracy far later in the turn: conditioning a model on its own
 	 * error-prone history raises the likelihood of further errors, and
 	 * scaling does not rescue it. So a permanently-protected early failure
 	 * is not neutral ballast — it is the input that paper measures.
@@ -182,7 +182,7 @@ export class WorkingStateManager {
 	/**
 	 * Adopt a previously captured state.
 	 *
-	 * Used on resume: a run that compacted, checkpointed and came back in a
+	 * Used on resume: a turn that compacted, checkpointed and came back in a
 	 * new process needs the state its earlier summary was built from, or the
 	 * next compaction supersedes that summary with one covering only what
 	 * happened after the resume. See {@link restoreWorkingState}.
@@ -198,7 +198,7 @@ export class WorkingStateManager {
 	/**
 	 * Append, evicting from the MIDDLE once the list is full.
 	 *
-	 * This used to `shift()`, dropping the oldest entry — so on a long run
+	 * This used to `shift()`, dropping the oldest entry — so on a long turn
 	 * the 26th assistant note silently deleted the 1st, and "the structured
 	 * state that survives compaction" degraded into a rolling window over
 	 * recent activity. The early entries are the load-bearing ones: the

package/src/compaction/manual.ts

@@ -31,7 +31,7 @@ import { type CompactionVerificationOptions, buildVerifiedSummary } from './veri
  *
  * These are that entry point, built on the planner rather than on a second
  * copy of the boundary arithmetic. Nothing here touches an
- * `IterationContext`: there is no run, which is the whole point.
+ * `IterationContext`: there is no turn, which is the whole point.
  */
 
 export interface CompactionResult {
@@ -45,7 +45,7 @@ export interface CompactionResult {
 	 * Tokens spent by this host-triggered pass's optional verifier call.
 	 *
 	 * A zero record means no verifier model call ran. The manual path has no
-	 * `RunManager` to account for side-channel usage, so returning it is the
+	 * `TurnRecorder` to account for side-channel usage, so returning it is the
 	 * only way a host can include that real provider work in its own ledger.
 	 */
 	readonly usage: TokenUsage
@@ -101,8 +101,8 @@ function splice(
 	retainedOlder: readonly Message[],
 	recentMessages: readonly Message[],
 ): { messages: Message[]; summary: Message } {
-	// A host-triggered pass has no run-scoped WorkingStateManager to carry the
-	// summary into a later query. Pin this summary itself: until a future run
+	// A host-triggered pass has no turn-scoped WorkingStateManager to carry the
+	// summary into a later query. Pin this summary itself: until a future turn
 	// has rebuilt equivalent state, this message is the only surviving record
 	// of what the pass removed.
 	const summary = { ...buildCompactionMessage(summaryBody), retain: true }
@@ -285,7 +285,7 @@ export async function compactRegion(input: CompactRegionInput): Promise<Compacti
 	)
 
 	// Same cross-run ownership as compactNow: a selected region has been
-	// replaced outside a run, so its only surviving account is pinned.
+	// replaced outside a turn, so its only surviving account is pinned.
 	const summary = { ...buildCompactionMessage(body), retain: true }
 	const out = [...messages.slice(0, start), summary, ...retainedSelected, ...messages.slice(end)]
 

package/src/compaction/plan.ts

@@ -8,7 +8,7 @@ import { estimateMessageTokens, estimateMessagesTokens } from './token-estimate.
 import { clearStaleToolResults } from './tool-result-editing.js'
 
 /**
- * The compaction decision, with no run attached.
+ * The compaction decision, with no turn attached.
  *
  * The whole algorithm — the leading-system floor scan, the tool-result
  * pre-pass, the boundary search, the guards — lived inside
@@ -20,13 +20,13 @@ import { clearStaleToolResults } from './tool-result-editing.js'
  *
  * This file therefore holds NO reference to that context, and a test greps
  * for one: reintroducing a single field read would quietly re-couple the
- * arithmetic to a run and nothing else would fail.
+ * arithmetic to a turn and nothing else would fail.
  *
  * What stayed behind is everything with an effect: the model call, the
  * working-memory re-pin, the array install, the logging, every
  * `emitEvent`. What moved here is the arithmetic. The split is the
  * question "what should happen" separated from "make it happen", and only
- * the first half can be asked without a run.
+ * the first half can be asked without a turn.
  */
 
 /** Why a pass decided to do nothing. */
@@ -70,7 +70,7 @@ export interface CompactionPlanInput {
 	 * Let a host-created pass establish its own retained summary floor.
 	 *
 	 * This is deliberately separate from `force`: a provider overflow can
-	 * force the threshold decision without changing the live run's prompt
+	 * force the threshold decision without changing the live turn's prompt
 	 * invariant, while a host may own a durable user/assistant-only history
 	 * that has no system floor yet.
 	 */
@@ -101,7 +101,7 @@ export interface CompactionPlanInput {
  *
  * Floored at one message. A single final message larger than the whole
  * budget still has to be kept: it is the live turn, and dropping it to
- * satisfy a size preference would delete the thing the run is answering.
+ * satisfy a size preference would delete the thing the turn is answering.
  *
  * Exported for its own tests. There used to be a second copy of this in the
  * phase file with a `__forTests` export beside it; two implementations of
@@ -115,7 +115,7 @@ export function naiveKeepStartByTokens(messages: readonly Message[], budgetToken
 		const cost = estimateMessageTokens(messages[index] as Message)
 		// Checked BEFORE adding, so the boundary never includes a message
 		// that pushes the tail over. Adding first and trimming after would
-		// admit one oversized message on every run.
+		// admit one oversized message on every turn.
 		if (start < messages.length && tokens + cost > budgetTokens) break
 		tokens += cost
 		start = index
@@ -214,7 +214,7 @@ export function planCompaction(input: CompactionPlanInput): CompactionPlan {
 	// needs one older and one recent message before the token walk and safe
 	// boundary search can make the real decision.
 	//
-	// Preserve the old short-history ordering for a run with no floor: until
+	// Preserve the old short-history ordering for a turn with no floor: until
 	// a host explicitly allows a floorless pass, one notional system message
 	// remains part of the admission minimum and `no_system_floor` follows it.
 	const floorForAdmission =
@@ -236,7 +236,7 @@ export function planCompaction(input: CompactionPlanInput): CompactionPlan {
 	// `tool` results (kept in `recent`), 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 — so compaction, whose whole job is to keep a long run alive,
+	// turn — so compaction, whose whole job is to keep a long turn alive,
 	// kills it instead. Snap the boundary backward to a safe point.
 	const naiveKeepStart =
 		config.keepRecentTokens === undefined