@namzu/sdk 8.0.0 → 10.0.0

package/src/gateway/__tests__/a-knob-nobody-can-turn.test.ts

@@ -0,0 +1,139 @@
+import type { Span } from '@opentelemetry/api'
+import { describe, expect, it } from 'vitest'
+
+import type { Agent } from '../../types/agent/core.js'
+import type { AgentManagerContract } from '../../types/agent/manager.js'
+import type {
+	AgentTask,
+	AgentTaskContext,
+	AgentTaskState,
+	SendMessageOptions,
+} from '../../types/agent/task.js'
+import type { AgentId, RunId, SessionId, TaskId, TenantId } from '../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import { LocalTaskGateway } from '../local.js'
+
+/**
+ * `CreateTaskOptions.configOverrides` was declared, typed, and never read.
+ *
+ * `createTask` built its OWN `configOverrides` object out of `parentSpan`
+ * alone, so a caller pinning a delegated run to a cheaper model, or capping
+ * its iterations, got the agent's defaults and nothing to say otherwise. The
+ * field type-checked, the call succeeded, and the run was not the run that was
+ * asked for.
+ *
+ * Reachability, not behaviour: what `configOverrides` DOES once it lands on
+ * `sendMessage` is the agent manager's business and is tested there. What was
+ * broken is the hop.
+ */
+
+/** Records what the gateway actually asked the manager for. */
+class RecordingManager implements AgentManagerContract {
+	readonly sent: SendMessageOptions[] = []
+
+	async sendMessage(options: SendMessageOptions): Promise<AgentTask> {
+		this.sent.push(options)
+		return {
+			taskId: `task_${this.sent.length}` as TaskId,
+			agentId: options.agentId,
+			agent: {} as Agent<never, never>,
+			childAbortController: new AbortController(),
+			context: {} as AgentTaskContext,
+			state: 'completed' as AgentTaskState,
+			pendingMessages: [],
+			createdAt: 1,
+		} as AgentTask
+	}
+
+	cancel(): void {}
+	cancelAll(): void {}
+	async continueTask(): Promise<void> {}
+	queueMessage(): void {}
+	drainMessages() {
+		return []
+	}
+	async waitForCompletion(): Promise<void> {}
+	getInstance(): AgentTask | undefined {
+		return undefined
+	}
+	listByParent(): AgentTask[] {
+		return []
+	}
+	listActive(): AgentTask[] {
+		return []
+	}
+	getState(): AgentTaskState | undefined {
+		return undefined
+	}
+	on(): void {}
+	off(): void {}
+	cleanup(): void {}
+	dispose(): void {}
+}
+
+function context(): AgentTaskContext {
+	return {
+		parentRunId: 'run_parent' as RunId,
+		parentAgentId: 'supervisor',
+		parentAbortController: new AbortController(),
+		depth: 0,
+		budgetTracker: { total: 100_000, remaining: 100_000 },
+		tenantId: 'tnt_k' as TenantId,
+		threadId: 'thd_k' as ThreadId,
+		sessionId: 'ses_k' as SessionId,
+		projectId: 'prj_k' as ProjectId,
+		parentActor: { kind: 'agent', agentId: 'supervisor' as AgentId, tenantId: 'tnt_k' as TenantId },
+	} as AgentTaskContext
+}
+
+describe('a delegated run is built with the config its caller asked for', () => {
+	it('forwards configOverrides to the spawn', async () => {
+		const manager = new RecordingManager()
+		const gateway = new LocalTaskGateway(manager, context())
+
+		await gateway.createTask({
+			agentId: 'worker',
+			prompt: 'work',
+			workingDirectory: '/tmp',
+			configOverrides: { model: 'cheap-model', maxIterations: 3 },
+		})
+
+		expect(manager.sent[0]?.configOverrides).toMatchObject({
+			model: 'cheap-model',
+			maxIterations: 3,
+		})
+	})
+
+	it('keeps the dedicated parentSpan option winning when both name a span', async () => {
+		// A caller who sets both is saying the same thing twice, and the named
+		// field is the specific one for the job — so it is applied last.
+		const manager = new RecordingManager()
+		const gateway = new LocalTaskGateway(manager, context())
+		const named = { spanContext: () => ({ traceId: 'named' }) } as unknown as Span
+		const buried = { spanContext: () => ({ traceId: 'buried' }) } as unknown as Span
+
+		await gateway.createTask({
+			agentId: 'worker',
+			prompt: 'work',
+			workingDirectory: '/tmp',
+			parentSpan: named,
+			configOverrides: { parentSpan: buried, model: 'cheap-model' },
+		})
+
+		expect(manager.sent[0]?.configOverrides?.parentSpan).toBe(named)
+		// ...and the rest of the caller's overrides survive alongside it.
+		expect(manager.sent[0]?.configOverrides?.model).toBe('cheap-model')
+	})
+
+	it('still sends no configOverrides at all when the caller set neither', async () => {
+		// The absent case has to stay absent: an empty object here would put
+		// `configOverrides: {}` on every spawn and override nothing, which is
+		// harmless until something starts reading its presence as intent.
+		const manager = new RecordingManager()
+		const gateway = new LocalTaskGateway(manager, context())
+
+		await gateway.createTask({ agentId: 'worker', prompt: 'work', workingDirectory: '/tmp' })
+
+		expect(manager.sent[0]).not.toHaveProperty('configOverrides')
+	})
+})

package/src/gateway/local.ts

@@ -1,3 +1,4 @@
+import { taskFailed } from '../tools/coordinator/outcome.js'
 import type { AgentInput } from '../types/agent/base.js'
 import type {
 	CreateTaskOptions,
@@ -75,10 +76,25 @@ export class LocalTaskGateway implements TaskGateway {
 				tenantId: this.taskContext.tenantId,
 				projectId: this.taskContext.projectId,
 				parentActor: this.taskContext.parentActor,
-				// Hang the child run off the span the caller supplied, so a
+				// The caller's overrides, plus the span the caller supplied so a
 				// delegated run joins the trace it belongs to instead of
 				// starting its own root.
-				...(options.parentSpan ? { configOverrides: { parentSpan: options.parentSpan } } : {}),
+				//
+				// `options.configOverrides` used to be dropped here: this built
+				// a fresh object from `parentSpan` and never looked at the
+				// field, so a caller pinning a child to a cheaper model got the
+				// agent's default and no sign anything had been ignored. The
+				// dedicated `parentSpan` option is applied last because it is
+				// the specific field for that job — a caller who sets both is
+				// saying the same thing twice, and the named one is the answer.
+				...(options.configOverrides || options.parentSpan
+					? {
+							configOverrides: {
+								...options.configOverrides,
+								...(options.parentSpan ? { parentSpan: options.parentSpan } : {}),
+							},
+						}
+					: {}),
 			},
 			// The budget tracker is SHARED on purpose and must not be cloned.
 			// `AgentManager.spawn` debits it (`remaining -= allocatedTokens`)
@@ -146,7 +162,7 @@ export class LocalTaskGateway implements TaskGateway {
 	 */
 	private applySiblingPolicy(finished: TaskHandle): void {
 		if (this.siblingFailurePolicy !== 'cancel-siblings') return
-		if (!hasFailed(finished)) return
+		if (!taskFailed(finished)) return
 
 		const cancelled: TaskId[] = []
 		for (const taskId of this.trackedTaskIds) {
@@ -251,10 +267,6 @@ export class LocalTaskGateway implements TaskGateway {
  * would therefore miss the ordinary case — an agent that tried and could
  * not — and catch only the exceptional one.
  */
-function hasFailed(handle: TaskHandle): boolean {
-	return handle.state === 'failed' || handle.result?.status === 'failed'
-}
-
 function toHandle(task: import('../types/agent/task.js').AgentTask): TaskHandle {
 	return {
 		taskId: task.taskId,

package/src/manager/agent/__tests__/lifecycle.test.ts

@@ -768,3 +768,77 @@ describe('LocalTaskGateway — what a failed child means for its siblings', () =
 		releaseSlow()
 	})
 })
+
+describe('a concurrent fan-out shares one budget', () => {
+	/**
+	 * Siblings launched from one assistant turn were each allocated a fraction
+	 * of the SAME undebited number.
+	 *
+	 * The allocation is read at the top of `sendMessage`; the debit lands
+	 * after `await provisionSpawn`, which is the only critical section. So N
+	 * siblings all enter, all read an untouched `remaining`, and each takes
+	 * its fraction of it. `create_task`'s own description instructs exactly
+	 * this shape: "'fan out 8 specialists' is one assistant message with 8
+	 * create_task blocks."
+	 *
+	 * **The children must not be allowed to finish.** A child that settles
+	 * refunds its unspent budget, and the refund restores the tracker to a
+	 * plausible number — so a test that measures after settle sees a healthy
+	 * total and reports nothing. The over-commitment is real and transient,
+	 * and transient is enough: every allocation decision taken during the
+	 * window reads a tracker that is already wrong.
+	 *
+	 * The first version of this test did settle its children, passed, and
+	 * would have certified the bug as fixed.
+	 */
+	it('never allocates more than the parent has, while the children are still running', async () => {
+		// What each child was actually HANDED. Asserting on the tracker was the
+		// first attempt and it measured the wrong thing twice over: a settled
+		// child refunds, which restores a plausible number, and the harm is not
+		// the bookkeeping anyway — it is that four children each believe they
+		// may spend half a pool that only has one half to give.
+		const allocations: number[] = []
+		let release: (() => void) | undefined
+		const held = new Promise<void>((resolve) => {
+			release = resolve
+		})
+
+		// The harness's own manager, because a hand-built one here silently
+		// fails to provision and the children never run — which looks exactly
+		// like a passing test.
+		const harness = await buildHarness(
+			makeAgent('child-1', async (_input, config) => {
+				allocations.push(config.tokenBudget)
+				await held
+				return successResult()
+			}),
+		)
+
+		// ONE tracker, shared, as a real parent's context is.
+		const shared = { total: 100_000, remaining: 100_000 }
+		const context = {
+			...buildContext(harness.parentSession.id, harness.projectId, harness.threadId),
+			budgetTracker: shared,
+		}
+
+		await Promise.allSettled(
+			Array.from({ length: 4 }, () =>
+				harness.manager.sendMessage(
+					buildOptions('child-1', harness.parentSession.id, harness.projectId),
+					context,
+				),
+			),
+		)
+
+		// Let the children record what they were handed before any settles.
+		await new Promise((r) => setTimeout(r, 20))
+		const handedOut = allocations.reduce((a, b) => a + b, 0)
+		release?.()
+
+		expect(allocations.length, 'every sibling should have started').toBe(4)
+		expect(
+			handedOut,
+			`four siblings were handed ${allocations.join(' + ')} from a pool of ${shared.total}`,
+		).toBeLessThanOrEqual(shared.total)
+	})
+})

package/src/manager/agent/lifecycle.ts

@@ -127,44 +127,29 @@ export class AgentManager {
 
 		const childAbortController = createChildAbortController(context.parentAbortController)
 
-		const maxAllocation = Math.floor(
-			context.budgetTracker.remaining * this.config.maxBudgetFraction,
-		)
-		const allocatedTokens = Math.min(
-			options.budgetAllocation?.tokenBudget ?? maxAllocation,
-			maxAllocation,
-		)
-
-		// Budget exhaustion must not INVERT into no budget at all. Downstream,
-		// `tokenBudget: 0` means "uncapped" (`LimitChecker`: `tokenBudget > 0
-		// && total >= tokenBudget`), and `maxAllocation` floors to 0 as soon as
-		// the parent's remaining drops below `1 / maxBudgetFraction`. So the
-		// most depleted parent in the tree was the one that spawned an
-		// unlimited child. Refuse instead: a caller that wants an uncapped
-		// child can say so explicitly with its own `budgetAllocation`.
-		if (allocatedTokens <= 0) {
-			throw new NamzuError({
-				code: 'invalid_config',
-				message: `Cannot spawn "${options.agentId}": the parent has ${context.budgetTracker.remaining} tokens remaining, which allocates 0 to the child — and a token budget of 0 means UNLIMITED downstream.`,
-				details: {
-					agentId: options.agentId,
-					parentRemaining: context.budgetTracker.remaining,
-					maxBudgetFraction: this.config.maxBudgetFraction,
-				},
-			})
-		}
+		// The allocation is computed INSIDE the spawn lock, not here. Reading
+		// the parent's remaining budget at this point and debiting it after
+		// `provisionSpawn` put the two halves of a read-modify-write on either
+		// side of an await — so N siblings launched from one turn all read the
+		// same undebited number and each took a fraction of it. Measured: four
+		// concurrent children were handed 50 000 + 50 000 + 50 000 + 50 000
+		// from a pool of 100 000.
+		//
+		// `create_task`'s own description instructs exactly this shape ("'fan
+		// out 8 specialists' is one assistant message with 8 create_task
+		// blocks"), so the documented usage was the reproduction.
+		//
+		// Nothing pinned it because the only concurrent test built a fresh
+		// context per call — each spawn got its own tracker, which measures
+		// width and not budget.
 
 		// Phase 6: SubSession + child Session + WorkspaceRef triple. Happens
 		// before taskId minting so a capacity failure short-circuits cleanly
 		// with no observable state change.
 		//
-		// The budget debit follows it for the same reason. It used to come
-		// first, so a spawn this call rejected still burned its allocation
-		// from a pool nobody credited back — the one state change the
-		// comment above promised there would not be.
-		const spawnRecord = await this.provisionSpawn(options, context)
-
-		context.budgetTracker.remaining -= allocatedTokens
+		// The allocation now travels with it, because the read and the debit
+		// have to be on the same side of every await to mean anything.
+		const { spawnRecord, allocatedTokens } = await this.provisionSpawn(options, context)
 
 		const taskId = generateTaskId()
 
@@ -449,7 +434,7 @@ export class AgentManager {
 	private async provisionSpawn(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-	): Promise<ChildSpawnRecord> {
+	): Promise<{ spawnRecord: ChildSpawnRecord; allocatedTokens: number }> {
 		const key = options.parentSessionId
 		const queued = (this.spawnLocks.get(key) ?? Promise.resolve()).then(
 			() => this.provisionSpawnUnlocked(options, context),
@@ -475,7 +460,42 @@ export class AgentManager {
 	private async provisionSpawnUnlocked(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-	): Promise<ChildSpawnRecord> {
+	): Promise<{ spawnRecord: ChildSpawnRecord; allocatedTokens: number }> {
+		// Read the parent's remaining budget HERE, inside the lock, so that
+		// concurrent siblings queue behind one another rather than all reading
+		// the same untouched number. The debit at the end of this method closes
+		// the pair: read and write are now on the same side of every await.
+		const maxAllocation = Math.floor(
+			context.budgetTracker.remaining * this.config.maxBudgetFraction,
+		)
+		const allocatedTokens = Math.min(
+			options.budgetAllocation?.tokenBudget ?? maxAllocation,
+			maxAllocation,
+		)
+
+		// Budget exhaustion must not INVERT into no budget at all. Downstream,
+		// `tokenBudget: 0` means "uncapped" (`LimitChecker`: `tokenBudget > 0
+		// && total >= tokenBudget`), and `maxAllocation` floors to 0 as soon as
+		// the parent's remaining drops below `1 / maxBudgetFraction`. So the
+		// most depleted parent in the tree was the one that spawned an
+		// unlimited child. Refuse instead: a caller that wants an uncapped
+		// child can say so explicitly with its own `budgetAllocation`.
+		//
+		// Refusing before any provisioning work also preserves the property the
+		// debit's placement was chosen for: a spawn this call rejects makes no
+		// state change at all, and burns no allocation.
+		if (allocatedTokens <= 0) {
+			throw new NamzuError({
+				code: 'invalid_config',
+				message: `Cannot spawn "${options.agentId}": the parent has ${context.budgetTracker.remaining} tokens remaining, which allocates 0 to the child — and a token budget of 0 means UNLIMITED downstream.`,
+				details: {
+					agentId: options.agentId,
+					parentRemaining: context.budgetTracker.remaining,
+					maxBudgetFraction: this.config.maxBudgetFraction,
+				},
+			})
+		}
+
 		// Phase 9: deps are unconditional required. Every spawn produces a
 		// SubSession + Session + WorkspaceRef triple (Convention #0: no
 		// partial/legacy path).
@@ -620,14 +640,24 @@ export class AgentManager {
 			throw err
 		}
 
+		// Debited only now, with the provisioning committed. Every path that
+		// could still have thrown is behind us, so a rejected spawn leaves the
+		// parent's budget untouched — the property the debit's original
+		// placement was chosen for, kept while closing the race that placement
+		// opened.
+		context.budgetTracker.remaining -= allocatedTokens
+
 		return {
-			subSessionId: subSession.id,
-			childSessionId: childSession.id,
-			tenantId: context.tenantId,
-			parentSessionId: options.parentSessionId,
-			rootSessionId,
-			childDepth,
-			workspaceRef,
+			spawnRecord: {
+				subSessionId: subSession.id,
+				childSessionId: childSession.id,
+				tenantId: context.tenantId,
+				parentSessionId: options.parentSessionId,
+				rootSessionId,
+				childDepth,
+				workspaceRef,
+			},
+			allocatedTokens,
 		}
 	}
 

package/src/manager/plan/__tests__/a-plan-that-succeeded-is-not-failed.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+
+import type { RunId } from '../../../types/ids/index.js'
+import { PlanManager } from '../lifecycle.js'
+
+/**
+ * `completePlan` scored an unreported step as a failure.
+ *
+ * The test was "is every step completed or skipped", and everything else fell
+ * to the same branch — so a step still `pending` produced `failed`. Since
+ * `addStep` defaults every step to `pending`, a caller that added steps, did
+ * the work, and settled the plan without reporting each one got `failed` for a
+ * plan that had fully succeeded. That is the path of least effort, not an
+ * unusual one.
+ *
+ * A step that FAILED is an outcome. A step nobody reported on is not — it says
+ * the caller and the plan disagree about whether the work is over, and
+ * answering "failed" settles that by inventing a result.
+ */
+
+const RUN = 'run_plan_outcome' as RunId
+
+function planWithSteps(count: number): PlanManager {
+	const manager = new PlanManager(RUN)
+	manager.startGenerating('a plan')
+	for (let i = 0; i < count; i += 1) {
+		manager.addStep({
+			id: `step-${i + 1}`,
+			description: `step ${i + 1}`,
+			dependsOn: [],
+			order: i,
+		})
+	}
+	manager.markReady()
+	return manager
+}
+
+describe('a plan settles on what its steps actually reported', () => {
+	it('completes when every step reported success', () => {
+		const manager = planWithSteps(2)
+		for (const step of manager.active?.steps ?? []) {
+			manager.updateStepStatus(step.id, 'completed')
+		}
+
+		expect(manager.completePlan()?.status).toBe('completed')
+	})
+
+	it('counts a skipped step as settled, not as a failure', () => {
+		const manager = planWithSteps(2)
+		const steps = manager.active?.steps ?? []
+		manager.updateStepStatus(steps[0]?.id as string, 'completed')
+		manager.updateStepStatus(steps[1]?.id as string, 'skipped')
+
+		expect(manager.completePlan()?.status).toBe('completed')
+	})
+
+	it('fails when a step actually failed', () => {
+		const manager = planWithSteps(2)
+		const steps = manager.active?.steps ?? []
+		manager.updateStepStatus(steps[0]?.id as string, 'completed')
+		manager.updateStepStatus(steps[1]?.id as string, 'failed')
+
+		expect(manager.completePlan()?.status).toBe('failed')
+	})
+
+	it('refuses rather than scoring a step nobody reported on', () => {
+		// The defect, in the shape a caller reaches it: steps added, work done,
+		// nothing reported. Answering `failed` here is the invented result.
+		const manager = planWithSteps(2)
+		manager.updateStepStatus(manager.active?.steps[0]?.id as string, 'completed')
+
+		expect(() => manager.completePlan()).toThrow(/have not reported an outcome/)
+	})
+
+	it('names the way out rather than only the refusal', () => {
+		// A caller in this position either forgot to report progress or called
+		// too early, and only they know which — so the message has to carry
+		// both moves, not just the complaint.
+		const manager = planWithSteps(1)
+
+		expect(() => manager.completePlan()).toThrow(/updateStepStatus/)
+		expect(() => manager.completePlan()).toThrow(/failPlan/)
+	})
+
+	it('still returns null when there is no plan at all', () => {
+		expect(new PlanManager(RUN).completePlan()).toBeNull()
+	})
+})

package/src/manager/plan/lifecycle.ts

@@ -26,6 +26,33 @@ export type PlanEventListener = (event: PlanEvent) => void
 
 export type PlanApprovalHandler = (request: PlanApprovalRequest) => Promise<PlanApprovalResponse>
 
+/**
+ * The plan a run declares, and the gate a host approves it through.
+ *
+ * **The kernel deliberately drives only part of this class.** It builds a plan
+ * (`approve_plan` calls `startGenerating` / `addStep` / `markReady`), gates it
+ * (`iteration/phases/context.ts` calls `approve` and `startExecution`),
+ * translates its events onto the run stream (`EventTranslator.wirePlanManager`),
+ * and settles it on failure (`runtime/query/result.ts` calls `failPlan`). It
+ * never reports a step outcome and never settles a plan that succeeded.
+ *
+ * That is a split, not an omission — `drainQuery` hands the manager to the host
+ * through `onContextCreated({ planManager })` BEFORE the iteration loop starts,
+ * precisely so a host can drive the half the kernel does not. So a grep for
+ * callers of `updateStepStatus` or `completePlan` inside this package finds
+ * none, and that is not evidence the methods are dead: the callers are hosts,
+ * and they are outside the repository. `PlanManager` is exported from
+ * `public-runtime.ts` for this reason.
+ *
+ * Recorded here because the absence has already been read once as a dead layer
+ * and proposed for deletion. What it would have deleted is a working
+ * human-in-the-loop approval gate.
+ *
+ * The one genuine gap in the split is tracked separately: nothing settles a
+ * plan that SUCCEEDED, so its status can reach `failed` or stay `executing`
+ * but never `completed`. Fixing that needs a decision about what a
+ * kernel-built plan's steps mean, not a guessed status — see `completePlan`.
+ */
 export class PlanManager {
 	private currentPlan: Plan | null = null
 	private runId: RunId
@@ -185,9 +212,43 @@ export class PlanManager {
 		return step
 	}
 
+	/**
+	 * Settle the plan, computing its outcome from its steps.
+	 *
+	 * A step that is still `pending` or `running` used to land here as
+	 * **`failed`**, because the test was "is every step completed or skipped"
+	 * and anything else fell to the same branch. So a caller that added steps,
+	 * did the work, and settled the plan without reporting each step got
+	 * `failed` for a plan that fully succeeded — and `addStep` defaults every
+	 * step to `pending`, so that is the path of least effort, not an unusual
+	 * one.
+	 *
+	 * The two cases are different facts and want different responses. A step
+	 * that FAILED is an outcome: the plan failed, report it. A step nobody
+	 * reported on is not an outcome at all — it says the caller and this plan
+	 * disagree about whether the work is over, and answering "failed" resolves
+	 * that disagreement by inventing a result.
+	 *
+	 * So an unfinished step is refused rather than scored. The message names
+	 * the steps and the two ways out, because a caller in this position either
+	 * forgot to report progress or called too early, and only they know which.
+	 */
 	completePlan(): Plan | null {
 		if (!this.currentPlan) return null
 
+		const unfinished = this.currentPlan.steps.filter(
+			(s) => s.status === 'pending' || s.status === 'running',
+		)
+		if (unfinished.length > 0) {
+			const named = unfinished.slice(0, 3).map((s) => s.description)
+			const rest = unfinished.length - named.length
+			const listed = rest > 0 ? `${named.join('; ')}, and ${rest} more` : named.join('; ')
+			const counted = `${unfinished.length} of ${this.currentPlan.steps.length} steps`
+			throw new Error(
+				`Cannot complete plan "${this.currentPlan.title}": ${counted} have not reported an outcome (${listed}). Report each step with updateStepStatus — 'skipped' is a valid outcome — or call failPlan if the plan is being abandoned. Scoring an unreported step as a failure would report a plan that succeeded as one that did not.`,
+			)
+		}
+
 		const allDone = this.currentPlan.steps.every(
 			(s) => s.status === 'completed' || s.status === 'skipped',
 		)

package/src/runtime/query/__tests__/the-plan-graph-reaches-a-host.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+
+import { InMemoryTaskStore } from '../../../store/task/memory.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import { EventTranslator } from '../events.js'
+
+/**
+ * The task store maintains a full dependency graph — `blocks` and `blockedBy`
+ * mirrored on both ends, written under a lock, and deadlock-avoided — and none
+ * of it reached the wire.
+ *
+ * So a host could draw a flat list of units and nothing about their order,
+ * while the model was already maintaining the order. Two optional fields is the
+ * smallest change that lets a host draw the plan the model has in mind.
+ */
+
+const RUN = 'run_graph' as RunId
+
+/**
+ * Only what the emitter touches — and it touches more than the id.
+ *
+ * `emitEvent` appends to the run store, so a fake without one produces an
+ * unhandled rejection AFTER the assertions have passed: every test reports
+ * green and the process exits non-zero. Worth stating because that is the
+ * failure shape this session has been unpicking all day, arriving here in a
+ * test fixture.
+ */
+const runMgr = {
+	id: RUN,
+	getRunStore: () => ({ appendEvent: async () => undefined }),
+} as never
+
+async function capture(body: (store: InMemoryTaskStore) => Promise<void>): Promise<RunEvent[]> {
+	const store = new InMemoryTaskStore()
+	const emitter = new EventTranslator(runMgr)
+	const stop = emitter.wireTaskStore(store, RUN)
+
+	await body(store)
+	// The store's listeners are async; let them settle before draining.
+	await new Promise((resolve) => setTimeout(resolve, 20))
+	stop()
+
+	return [...emitter.drainPending()]
+}
+
+type Created = Extract<RunEvent, { type: 'task_created' }>
+type Updated = Extract<RunEvent, { type: 'task_updated' }>
+
+describe('a host can see what a unit waits on', () => {
+	it('carries the edges once a dependency exists', async () => {
+		const events = await capture(async (store) => {
+			const gather = await store.create({ runId: RUN, subject: 'gather' })
+			const summarise = await store.create({ runId: RUN, subject: 'summarise' })
+			await store.block(gather.id, summarise.id)
+		})
+
+		const withEdges = events
+			.filter((e): e is Updated => e.type === 'task_updated')
+			.find((e) => e.blockedBy !== undefined)
+
+		expect(withEdges, 'the dependency the store recorded never reached the wire').toBeDefined()
+		expect(withEdges?.blockedBy).toHaveLength(1)
+	})
+
+	it('says nothing rather than empty when a unit depends on nothing', async () => {
+		// Absent and empty are different claims. A reader must be able to tell
+		// "this unit has no dependencies" from "this emitter predates the
+		// field" — an empty array asserts the first about both.
+		const events = await capture(async (store) => {
+			await store.create({ runId: RUN, subject: 'standalone' })
+		})
+
+		const created = events.find((e): e is Created => e.type === 'task_created')
+
+		expect(created).toBeDefined()
+		expect(created && 'blockedBy' in created).toBe(false)
+	})
+})