@namzu/sdk 0.4.4 → 0.5.0

package/src/provider/instrumentation.test.ts

@@ -1,51 +1,78 @@
+/**
+ * Phase 2 of ses_001-tool-stream-events removed `chat()` from
+ * `LLMProvider`; this suite now exercises the streaming-only wrapper.
+ *
+ * Invariants under test:
+ *   - `wrapProviderWithProbes(provider)` returns an object that
+ *     forwards `chatStream` to the inner provider while emitting
+ *     `provider_call_start` before iteration and either
+ *     `provider_call_completed` (after the iterator drains cleanly,
+ *     carrying any aggregated `usage` from the last chunk that
+ *     supplied one) or `provider_call_failed` (on a thrown error).
+ *   - `callId` is unique per call and correlates start/completed/failed.
+ *   - Optional methods (`listModels`, `healthCheck`, `doctorCheck`)
+ *     are forwarded when present on the inner provider.
+ */
+
 import { describe, expect, it, vi } from 'vitest'
 
 import { buildProbeContext } from '../probe/context.js'
 import { createProbeRegistry } from '../probe/registry.js'
 import type { AgentBusEvent } from '../types/bus/index.js'
-import type { ChatCompletionParams, ChatCompletionResponse } from '../types/provider/chat.js'
+import type { TokenUsage } from '../types/common/index.js'
+import type { ChatCompletionParams } from '../types/provider/chat.js'
 import type { LLMProvider } from '../types/provider/interface.js'
 import type { StreamChunk } from '../types/provider/stream.js'
 
 import { wrapProviderWithProbes } from './instrumentation.js'
 
+const STREAM_USAGE: TokenUsage = {
+	promptTokens: 10,
+	completionTokens: 5,
+	totalTokens: 15,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
 function makeFakeProvider(
 	overrides: Partial<{
-		chat: LLMProvider['chat']
 		chatStream: LLMProvider['chatStream']
 	}> = {},
 ): LLMProvider {
-	const defaultChat: LLMProvider['chat'] = async (
-		_params: ChatCompletionParams,
-	): Promise<ChatCompletionResponse> => {
-		return {
-			content: 'ok',
-			usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
-		} as unknown as ChatCompletionResponse
-	}
 	const defaultStream: LLMProvider['chatStream'] = async function* (
 		_params: ChatCompletionParams,
 	): AsyncIterable<StreamChunk> {
-		yield { delta: 'hi' } as unknown as StreamChunk
+		yield { id: 'm', delta: { content: 'hi' } }
+		yield {
+			id: 'm',
+			delta: {},
+			finishReason: 'stop',
+			usage: STREAM_USAGE,
+		}
 	}
 	return {
 		id: 'p1',
 		name: 'Provider 1',
-		chat: overrides.chat ?? defaultChat,
 		chatStream: overrides.chatStream ?? defaultStream,
 	}
 }
 
 const params: ChatCompletionParams = { model: 'm1', messages: [] } as ChatCompletionParams
 
-describe('wrapProviderWithProbes — chat', () => {
-	it('emits provider_call_start before the chat call and provider_call_completed after', async () => {
+async function drain(iter: AsyncIterable<StreamChunk>): Promise<StreamChunk[]> {
+	const out: StreamChunk[] = []
+	for await (const c of iter) out.push(c)
+	return out
+}
+
+describe('wrapProviderWithProbes — chatStream', () => {
+	it('emits provider_call_start before iteration and provider_call_completed after drain', async () => {
 		const reg = createProbeRegistry()
 		const seen: AgentBusEvent[] = []
 		reg.onAny((event) => seen.push(event as AgentBusEvent))
 
 		const wrapped = wrapProviderWithProbes(makeFakeProvider(), { probes: reg })
-		await wrapped.chat(params)
+		await drain(wrapped.chatStream(params))
 
 		expect(seen.map((e) => e.type)).toEqual(['provider_call_start', 'provider_call_completed'])
 		const start = seen[0] as AgentBusEvent & { type: 'provider_call_start' }
@@ -53,39 +80,55 @@ describe('wrapProviderWithProbes — chat', () => {
 		expect(start.providerId).toBe('p1')
 		expect(start.model).toBe('m1')
 		expect(completed.callId).toBe(start.callId)
-		expect(completed.usage).toEqual({ inputTokens: 10, outputTokens: 5, totalTokens: 15 })
 		expect(completed.durationMs).toBeGreaterThanOrEqual(0)
 	})
 
-	it('emits provider_call_failed and re-throws when chat throws', async () => {
+	it('captures usage from the last chunk that carries it', async () => {
+		const reg = createProbeRegistry()
+		const seen: AgentBusEvent[] = []
+		reg.onAny((event) => seen.push(event as AgentBusEvent))
+
+		const wrapped = wrapProviderWithProbes(makeFakeProvider(), { probes: reg })
+		await drain(wrapped.chatStream(params))
+
+		const completed = seen[1] as AgentBusEvent & { type: 'provider_call_completed' }
+		expect(completed.usage).toMatchObject({
+			inputTokens: STREAM_USAGE.promptTokens,
+			outputTokens: STREAM_USAGE.completionTokens,
+			totalTokens: STREAM_USAGE.totalTokens,
+		})
+	})
+
+	it('emits provider_call_failed and re-throws when chatStream throws mid-iteration', async () => {
 		const reg = createProbeRegistry()
 		const seen: AgentBusEvent[] = []
 		reg.onAny((event) => seen.push(event as AgentBusEvent))
 
 		const failing = makeFakeProvider({
-			chat: async () => {
+			chatStream: async function* () {
+				yield { id: 'm', delta: { content: 'partial' } }
 				throw new Error('boom')
 			},
 		})
 		const wrapped = wrapProviderWithProbes(failing, { probes: reg })
 
-		await expect(wrapped.chat(params)).rejects.toThrow('boom')
+		await expect(drain(wrapped.chatStream(params))).rejects.toThrow('boom')
 		expect(seen.map((e) => e.type)).toEqual(['provider_call_start', 'provider_call_failed'])
 		const failed = seen[1] as AgentBusEvent & { type: 'provider_call_failed' }
 		expect(failed.error).toBe('boom')
 	})
 
-	it('correlates start and completed by callId', async () => {
+	it('correlates start and completed by callId across multiple calls', async () => {
 		const reg = createProbeRegistry()
 		const ids: string[] = []
 		reg.on('provider_call_start', (event) => ids.push(`s:${event.callId}`))
 		reg.on('provider_call_completed', (event) => ids.push(`c:${event.callId}`))
 
 		const wrapped = wrapProviderWithProbes(makeFakeProvider(), { probes: reg })
-		await wrapped.chat(params)
-		await wrapped.chat(params)
+		await drain(wrapped.chatStream(params))
+		await drain(wrapped.chatStream(params))
 
-		expect(ids.length).toBe(4)
+		expect(ids).toHaveLength(4)
 		expect(ids[0]?.split(':')[1]).toBe(ids[1]?.split(':')[1])
 		expect(ids[2]?.split(':')[1]).toBe(ids[3]?.split(':')[1])
 		expect(ids[0]).not.toBe(ids[2])
@@ -99,94 +142,32 @@ describe('wrapProviderWithProbes — chat', () => {
 
 		wrapped.listModels?.()
 		wrapped.healthCheck?.()
-		expect(listModels).toHaveBeenCalledTimes(1)
-		expect(healthCheck).toHaveBeenCalledTimes(1)
-	})
-})
-
-describe('wrapProviderWithProbes — chatStream', () => {
-	it('emits provider_call_start before iteration and provider_call_completed after', async () => {
-		const reg = createProbeRegistry()
-		const seen: AgentBusEvent[] = []
-		reg.onAny((event) => seen.push(event as AgentBusEvent))
-
-		const wrapped = wrapProviderWithProbes(makeFakeProvider(), { probes: reg })
-		const chunks: StreamChunk[] = []
-		for await (const chunk of wrapped.chatStream(params)) {
-			chunks.push(chunk)
-		}
 
-		expect(chunks.length).toBe(1)
-		expect(seen.map((e) => e.type)).toEqual(['provider_call_start', 'provider_call_completed'])
+		expect(listModels).toHaveBeenCalled()
+		expect(healthCheck).toHaveBeenCalled()
 	})
 
-	it('emits provider_call_failed when the underlying stream throws mid-iteration', async () => {
-		const reg = createProbeRegistry()
-		const seen: AgentBusEvent[] = []
-		reg.onAny((event) => seen.push(event as AgentBusEvent))
-
-		const failing = makeFakeProvider({
-			chatStream: async function* (_params: ChatCompletionParams): AsyncIterable<StreamChunk> {
-				yield { delta: 'a' } as unknown as StreamChunk
-				throw new Error('stream-boom')
-			},
-		})
-		const wrapped = wrapProviderWithProbes(failing, { probes: reg })
-
-		await expect(async () => {
-			for await (const _chunk of wrapped.chatStream(params)) {
-				// noop
-			}
-		}).rejects.toThrow('stream-boom')
-
-		expect(seen.map((e) => e.type)).toEqual(['provider_call_start', 'provider_call_failed'])
+	it('omits optional methods when inner provider does not declare them', () => {
+		const wrapped = wrapProviderWithProbes(makeFakeProvider())
+		expect(wrapped.listModels).toBeUndefined()
+		expect(wrapped.healthCheck).toBeUndefined()
 	})
-})
 
-describe('wrapProviderWithProbes — runId propagation', () => {
-	it('attaches runId to each emitted event when supplied', async () => {
+	it('uses the configured probe context (runId)', async () => {
 		const reg = createProbeRegistry()
-		let observedRunId: string | undefined
-		reg.on('provider_call_start', (event, ctx) => {
-			observedRunId = event.runId ?? ctx.runId
+		const ctx = buildProbeContext({ runId: 'run_42' as `run_${string}` })
+		const seen: AgentBusEvent[] = []
+		reg.onAny((event, c) => {
+			seen.push(event as AgentBusEvent)
+			expect(c.runId).toBe(ctx.runId)
 		})
 
 		const wrapped = wrapProviderWithProbes(makeFakeProvider(), {
 			probes: reg,
-			runId: 'run_42' as never,
-		})
-		await wrapped.chat(params)
-		expect(observedRunId).toBe('run_42')
-	})
-})
-
-describe('wrapProviderWithProbes — uses singleton when no probes opt provided', () => {
-	it('still wraps successfully without throwing (smoke)', async () => {
-		// Use a fresh inner provider; we just want to verify the default path
-		// instantiates and runs. Singleton dispatch is exercised in registry tests.
-		const wrapped = wrapProviderWithProbes(makeFakeProvider())
-		await expect(wrapped.chat(params)).resolves.toBeDefined()
-	})
-})
-
-describe('wrapProviderWithProbes — context still flows through buildProbeContext', () => {
-	it('handler receives a frozen ctx', async () => {
-		const reg = createProbeRegistry()
-		let captured: Readonly<{ isReplay: boolean }> | undefined
-		reg.on('provider_call_start', (_event, ctx) => {
-			captured = ctx
+			runId: ctx.runId,
 		})
+		await drain(wrapped.chatStream(params))
 
-		const wrapped = wrapProviderWithProbes(makeFakeProvider(), { probes: reg })
-		await wrapped.chat(params)
-		expect(captured).toBeDefined()
-		expect(Object.isFrozen(captured)).toBe(true)
-		expect(captured?.isReplay).toBe(false)
-	})
-
-	it('buildProbeContext used internally returns a frozen ProbeContext (sanity check)', () => {
-		const ctx = buildProbeContext({ isReplay: true })
-		expect(ctx.isReplay).toBe(true)
-		expect(Object.isFrozen(ctx)).toBe(true)
+		expect(seen.map((e) => e.type)).toEqual(['provider_call_start', 'provider_call_completed'])
 	})
 })

package/src/provider/instrumentation.ts

@@ -1,8 +1,9 @@
 import { buildProbeContext } from '../probe/context.js'
 import { type ProbeRegistry, probe as defaultProbeRegistry } from '../probe/registry.js'
 import type { ProviderCallId, ProviderCallUsage } from '../types/bus/index.js'
+import type { TokenUsage } from '../types/common/index.js'
 import type { RunId } from '../types/ids/index.js'
-import type { ChatCompletionParams, ChatCompletionResponse } from '../types/provider/chat.js'
+import type { ChatCompletionParams } from '../types/provider/chat.js'
 import type { LLMProvider } from '../types/provider/interface.js'
 import type { StreamChunk } from '../types/provider/stream.js'
 
@@ -18,14 +19,14 @@ function nextCallId(): ProviderCallId {
 	return `pcall_${Date.now().toString(36)}${providerCallCounter.toString(36)}` as ProviderCallId
 }
 
-function extractUsage(response: ChatCompletionResponse): ProviderCallUsage | undefined {
-	const usage = (response as { usage?: ProviderCallUsage }).usage
+function extractStreamUsage(usage: TokenUsage | undefined): ProviderCallUsage | undefined {
 	if (!usage) return undefined
+	const u = usage as TokenUsage & Partial<ProviderCallUsage>
 	return {
-		inputTokens: usage.inputTokens,
-		outputTokens: usage.outputTokens,
-		totalTokens: usage.totalTokens,
-		costUsd: usage.costUsd,
+		inputTokens: u.inputTokens ?? u.promptTokens,
+		outputTokens: u.outputTokens ?? u.completionTokens,
+		totalTokens: u.totalTokens,
+		costUsd: u.costUsd,
 	}
 }
 
@@ -42,52 +43,6 @@ export function wrapProviderWithProbes(
 		listModels: provider.listModels?.bind(provider),
 		healthCheck: provider.healthCheck?.bind(provider),
 
-		async chat(params: ChatCompletionParams): Promise<ChatCompletionResponse> {
-			const callId = nextCallId()
-			const ctx = buildProbeContext({ runId })
-			const startedAt = Date.now()
-			probes.dispatch(
-				{
-					type: 'provider_call_start',
-					providerId: provider.id,
-					model: params.model,
-					callId,
-					runId,
-				},
-				ctx,
-			)
-			try {
-				const response = await provider.chat(params)
-				probes.dispatch(
-					{
-						type: 'provider_call_completed',
-						providerId: provider.id,
-						model: params.model,
-						callId,
-						runId,
-						durationMs: Date.now() - startedAt,
-						usage: extractUsage(response),
-					},
-					ctx,
-				)
-				return response
-			} catch (error) {
-				probes.dispatch(
-					{
-						type: 'provider_call_failed',
-						providerId: provider.id,
-						model: params.model,
-						callId,
-						runId,
-						durationMs: Date.now() - startedAt,
-						error: error instanceof Error ? error.message : String(error),
-					},
-					ctx,
-				)
-				throw error
-			}
-		},
-
 		async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
 			const callId = nextCallId()
 			const ctx = buildProbeContext({ runId })
@@ -103,7 +58,9 @@ export function wrapProviderWithProbes(
 				ctx,
 			)
 			try {
+				let lastUsage: TokenUsage | undefined
 				for await (const chunk of provider.chatStream(params)) {
+					if (chunk.usage) lastUsage = chunk.usage
 					yield chunk
 				}
 				probes.dispatch(
@@ -114,6 +71,7 @@ export function wrapProviderWithProbes(
 						callId,
 						runId,
 						durationMs: Date.now() - startedAt,
+						usage: extractStreamUsage(lastUsage),
 					},
 					ctx,
 				)

package/src/provider/mock.ts

@@ -50,13 +50,9 @@ export class MockLLMProvider implements LLMProvider {
 		}
 	}
 
-	async chat(params: ChatCompletionParams): Promise<ChatCompletionResponse> {
-		await this.delay()
-		return this.normalizeResponse(params, this.responseText)
-	}
-
 	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
-		const response = await this.chat(params)
+		await this.delay()
+		const response = this.normalizeResponse(params, this.responseText)
 		const content = response.message.content ?? ''
 		const chunkSize = 8
 

package/src/public-runtime.ts

@@ -235,10 +235,16 @@ export {
 
 export { wrapProviderWithProbes } from './provider/instrumentation.js'
 export type { ProviderInstrumentationOptions } from './provider/instrumentation.js'
+export { collect } from './provider/collect.js'
 
 export { wrapVaultWithProbes } from './vault/instrumentation.js'
 export type { VaultInstrumentationOptions } from './vault/instrumentation.js'
 
+// Doctor runtime moved to @namzu/cli in 0.5.0. SDK keeps only the
+// protocol types under `types/doctor/` (re-exported via public-types.ts)
+// + `LLMProvider.doctorCheck?()` hook on the provider interface.
+// Operators run `npx @namzu/cli doctor`; embedded usage lives there too.
+
 // ─── session runtime — explicit named lists, no `export *` ───────────────
 // See §1.5 + §4.2 of design.md. Types flow through public-types.ts.
 

package/src/run/LimitChecker.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+
+import { RuntimeConfigSchema } from '../config/runtime.js'
+import { RunConfigSchema } from '../contracts/schemas.js'
+import { checkLimitsDetailed } from './LimitChecker.js'
+
+describe('token budget limits', () => {
+	it('treats tokenBudget 0 as unlimited at runtime', () => {
+		const result = checkLimitsDetailed(
+			{
+				tokenBudget: 0,
+				timeoutMs: 60_000,
+				maxIterations: 10,
+				budgetWarningThreshold: 0.9,
+			},
+			{
+				aborted: false,
+				totalTokens: 10_000_000,
+				totalCost: 0,
+				currentIteration: 1,
+				startTime: Date.now(),
+			},
+		)
+
+		expect(result).toEqual({ type: 'ok' })
+	})
+
+	it('accepts tokenBudget 0 in public runtime config schemas', () => {
+		expect(RuntimeConfigSchema.parse({ tokenBudget: 0 }).tokenBudget).toBe(0)
+		expect(RunConfigSchema.parse({ tokenBudget: 0 }).tokenBudget).toBe(0)
+	})
+})

package/src/run/reporter.ts

@@ -60,13 +60,6 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
-			case 'llm_response':
-				log.info('LLM response received', {
-					runId: event.runId,
-					hasToolCalls: event.hasToolCalls,
-				})
-				break
-
 			case 'token_usage_updated':
 				log.info('Token usage updated', {
 					runId: event.runId,
@@ -99,6 +92,16 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 			case 'checkpoint_created':
 			case 'run_paused':
 			case 'run_resuming':
+			// v3 message + tool-input lifecycle (ses_001-tool-stream-events).
+			// The reporter is a debug log surface; per-delta lines would be
+			// too noisy. Phase 4 may add structured logging at the
+			// message_completed boundary if signal proves useful.
+			case 'message_started':
+			case 'text_delta':
+			case 'message_completed':
+			case 'tool_input_started':
+			case 'tool_input_delta':
+			case 'tool_input_completed':
 				break
 
 			case 'agent_pending':

package/src/runtime/query/__tests__/prompt.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { ToolRegistryContract } from '../../../types/tool/index.js'
+import { PromptBuilder } from '../prompt.js'
+
+function makeToolRegistry(): ToolRegistryContract {
+	return {
+		register: vi.fn(),
+		unregister: vi.fn(),
+		execute: vi.fn(),
+		get: vi.fn(() => undefined),
+		has: vi.fn(() => false),
+		listNames: vi.fn(() => []),
+		getAvailability: vi.fn(),
+		toPromptSection: vi.fn(() => ''),
+		toTierGuidance: vi.fn(() => ''),
+	} as unknown as ToolRegistryContract
+}
+
+describe('PromptBuilder runtime context', () => {
+	it('includes output contract even when no filesystem tool is registered', () => {
+		const prompt = new PromptBuilder({
+			systemPrompt: 'You are a worker.',
+			tools: makeToolRegistry(),
+			runtimeContext: {
+				label: 'test runtime',
+				outputDirectory: 'outputs/',
+				outputFileMarker: 'OUTPUT_FILE: <filename> - <description>',
+				notes: ['Mirror generated files after the turn.'],
+			},
+		}).build('full', '/tmp/work')
+
+		expect(prompt).toContain('Runtime: test runtime')
+		expect(prompt).toContain('Working directory: /tmp/work')
+		expect(prompt).toContain('Output directory: outputs/')
+		expect(prompt).toContain('OUTPUT_FILE: <filename> - <description>')
+		expect(prompt).toContain('Mirror generated files after the turn.')
+	})
+})

package/src/runtime/query/context-cache.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto'
+import type { AgentRuntimeContext } from '../../types/agent/base.js'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { AgentPersona } from '../../types/persona/index.js'
 import type { ProjectId } from '../../types/session/ids.js'
@@ -18,6 +19,7 @@ export interface PromptCacheInput {
 	basePrompt?: string
 	tools: ToolRegistryContract
 	allowedTools?: string[]
+	runtimeContext?: AgentRuntimeContext
 }
 
 export class ContextCache {
@@ -48,6 +50,7 @@ export class ContextCache {
 			basePrompt: input.basePrompt,
 			tools: input.tools,
 			allowedTools: input.allowedTools,
+			runtimeContext: input.runtimeContext,
 		})
 
 		this.cachedPrompt = builder.build()
@@ -78,6 +81,7 @@ export class ContextCache {
 			basePrompt: input.basePrompt,
 			tools: input.tools,
 			allowedTools: input.allowedTools,
+			runtimeContext: input.runtimeContext,
 		})
 
 		const segments = builder.buildSegmented(contextLevel, workingDirectory)
@@ -124,6 +128,7 @@ export class ContextCache {
 			input.basePrompt ?? '',
 			...(input.skills?.map((s) => s.metadata.name) ?? []),
 			...(input.allowedTools ?? []),
+			JSON.stringify(input.runtimeContext ?? {}),
 		]
 
 		return createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, 16)

package/src/runtime/query/events.ts

@@ -4,15 +4,33 @@ import { buildProbeContext } from '../../probe/context.js'
 import { type ProbeRegistry, probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ActivityEvent, ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
+import { isEphemeralEvent } from '../../types/run/events.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { TaskEvent, TaskStore } from '../../types/task/index.js'
+import { getRootLogger } from '../../utils/logger.js'
 
 export type EmitEvent = (event: RunEvent) => Promise<void>
 
+/**
+ * Soft cap on the in-memory pending-event queue. When the queue exceeds
+ * this size and a new ephemeral event arrives, the oldest ephemeral
+ * event is dropped to make room. Lifecycle events are never dropped —
+ * they carry state transitions consumers cannot reconstruct.
+ *
+ * Sized for ~5–10 seconds of worst-case provider delta cadence
+ * (100 deltas/s sustained) before pressure kicks in. Tune via
+ * empirical evidence; not a hard guarantee, just a safety net.
+ *
+ * Codex D2 (ses_001-tool-stream-events).
+ */
+const PENDING_EVENT_SOFT_CAP = 1000
+
 export class EventTranslator {
 	private pendingEvents: RunEvent[] = []
 	private runMgr: RunPersistence
 	private probes: ProbeRegistry
+	private droppedDeltaCount = 0
+	private readonly log = getRootLogger().child({ component: 'EventTranslator' })
 
 	constructor(runMgr: RunPersistence, probeRegistry: ProbeRegistry = defaultProbeRegistry) {
 		this.runMgr = runMgr
@@ -21,8 +39,41 @@ export class EventTranslator {
 
 	readonly emitEvent: EmitEvent = async (event: RunEvent): Promise<void> => {
 		this.probes.dispatch(event, buildProbeContext({ runId: event.runId }))
+
+		// D2: bound the queue. Drop oldest ephemeral events under
+		// pressure rather than letting unbounded growth swamp a slow
+		// consumer (or lock the orchestrator on awaitable disk I/O).
+		// Lifecycle events are sacred — they carry state transitions a
+		// consumer cannot reconstruct from neighbouring events.
+		if (this.pendingEvents.length >= PENDING_EVENT_SOFT_CAP) {
+			const dropIdx = this.pendingEvents.findIndex(isEphemeralEvent)
+			if (dropIdx !== -1) {
+				this.pendingEvents.splice(dropIdx, 1)
+				this.droppedDeltaCount += 1
+				if (this.droppedDeltaCount === 1 || this.droppedDeltaCount % 100 === 0) {
+					this.log.warn('Dropped ephemeral RunEvent under bus pressure', {
+						runId: event.runId,
+						droppedCount: this.droppedDeltaCount,
+						queueSize: this.pendingEvents.length,
+					})
+				}
+			}
+			// If no ephemeral events are buffered the lifecycle events
+			// themselves are the queue's contents — accept the overflow
+			// and rely on consumer drain catching up. Better to grow
+			// briefly than to drop a state transition.
+		}
+
 		this.pendingEvents.push(event)
-		await this.runMgr.getRunStore().appendEvent(event)
+
+		// D1 middle path: ephemeral events never enter `transcript.jsonl`.
+		// They live only on the in-memory bus for live UI rendering.
+		// Replay (`runtime/query/replay/prepare.ts`) reads checkpoints
+		// not transcripts, so this preserves replay fidelity while
+		// eliminating the durable bloat codex flagged.
+		if (!isEphemeralEvent(event)) {
+			await this.runMgr.getRunStore().appendEvent(event)
+		}
 	};
 
 	*drainPending(): Generator<RunEvent> {