@llm4ts/flow 2.40.1 → 2.41.0

package/src/CostReport.ts

@@ -3,7 +3,7 @@ import * as Option from "effect/Option"
 import * as Schema from "effect/Schema"
 import type { TokenUsage } from "@llm4ts/core/Models"
 import { isEstimatedModel } from "./EstimatedUsage.ts"
-import { TokensUsed } from "./FlowEvents.ts"
+import { TokensUsed, cloneName } from "./FlowEvents.ts"
 import type { TraceLine } from "./FlowRecorder.ts"
 import { estimateCostUsd, PricesAsOf } from "./PriceList.ts"
 
@@ -31,7 +31,10 @@ export class UsageSample extends Schema.Class<UsageSample>("UsageSample")({
   total: Schema.Int,
   cached: Schema.optionalKey(Schema.Int),
   costUsd: Schema.optionalKey(Schema.Number),
-  estimated: Schema.Boolean
+  estimated: Schema.Boolean,
+  /** The lane's executor and clone, when the usage came from a roster lane (ADR 0033). */
+  executor: Schema.optionalKey(Schema.String),
+  clone: Schema.optionalKey(Schema.Int)
 }) {}
 
 export class UsageTotals extends Schema.Class<UsageTotals>("UsageTotals")({
@@ -87,6 +90,13 @@ export class UsageProjection extends Schema.Class<UsageProjection>("UsageProject
   costUsdPerDay: Schema.optionalKey(Schema.Number)
 }) {}
 
+/** One executor clone's usage (`codex#2`): the coder's calls on a lane that holds that clone. */
+export class ExecutorUsage extends Schema.Class<ExecutorUsage>("ExecutorUsage")({
+  executor: Schema.String,
+  totals: UsageTotals,
+  share: Schema.Number
+}) {}
+
 export class CostReport extends Schema.Class<CostReport>("CostReport")({
   schemaVersion: Schema.Int,
   timeZone: Schema.String,
@@ -102,10 +112,12 @@ export class CostReport extends Schema.Class<CostReport>("CostReport")({
   byDay: Schema.Array(UsageBucket),
   byHour: Schema.Array(UsageBucket),
   byModel: Schema.Array(ModelUsage),
-  byAgent: Schema.Array(AgentUsage)
+  byAgent: Schema.Array(AgentUsage),
+  /** Per executor clone, for lanes served by a roster (schema 3, ADR 0033). */
+  byExecutor: Schema.Array(ExecutorUsage)
 }) {}
 
-export const CurrentCostReportSchema = 2
+export const CurrentCostReportSchema = 3
 
 const tokensUsedCodec = Schema.fromJsonString(TokensUsed)
 const decodeTokensUsed = Schema.decodeUnknownOption(tokensUsedCodec)
@@ -145,7 +157,9 @@ export const usageSamplesFromTrace = (
         total: event.usage.total,
         ...(event.usage.cached === undefined ? {} : { cached: event.usage.cached }),
         ...(costUsd === undefined ? {} : { costUsd }),
-        estimated: isEstimatedModel(model)
+        estimated: isEstimatedModel(model),
+        ...(event.executor === undefined ? {} : { executor: event.executor }),
+        ...(event.clone === undefined ? {} : { clone: event.clone })
       })
     ]
   })
@@ -320,6 +334,26 @@ export const buildCostReport = (
         right.totals.total - left.totals.total || left.agent.localeCompare(right.agent)
     )
 
+  // Coder clones only: a sample that names the lane's executor without its
+  // clone is a reviewer's or judge's, which ran elsewhere (ADR 0033).
+  const byExecutorGroups = new Map<string, Array<UsageSample>>()
+  for (const sample of ordered) {
+    if (sample.executor !== undefined && sample.clone !== undefined) {
+      const key = cloneName(sample.executor, sample.clone)
+      byExecutorGroups.set(key, [...(byExecutorGroups.get(key) ?? []), sample])
+    }
+  }
+  const byExecutor = [...byExecutorGroups.entries()]
+    .map(([executor, members]) => {
+      const executorTotals = totalsOf(members)
+      return ExecutorUsage.make({
+        executor,
+        totals: executorTotals,
+        share: tokens === 0 ? 0 : executorTotals.total / tokens
+      })
+    })
+    .sort((left, right) => left.executor.localeCompare(right.executor))
+
   return CostReport.make({
     schemaVersion: CurrentCostReportSchema,
     timeZone: zoneLabel(timeZone),
@@ -349,7 +383,8 @@ export const buildCostReport = (
     byDay,
     byHour,
     byModel,
-    byAgent
+    byAgent,
+    byExecutor
   })
 }
 
@@ -427,6 +462,16 @@ export const renderCostReport = (report: CostReport): string => {
       )
     )
   }
+  if (report.byExecutor.length > 0) {
+    sections.push(
+      "",
+      "by executor clone:",
+      ...report.byExecutor.map(
+        (entry) =>
+          `  ${entry.executor}  ${thousands(entry.totals.total)} tokens (${Math.round(entry.share * 100)}%)${money(entry.totals.costUsd)}`
+      )
+    )
+  }
   const notes = [
     `costs are backend-reported where available, otherwise estimated from the pricing table (rates as of ${report.pricesAsOf} — may be stale)`,
     ...(report.estimated.requests === 0

package/src/FlowEvents.ts

@@ -88,6 +88,8 @@ export class Info extends Schema.TaggedClass<Info>()("Info", {
 export class ToolUse extends Schema.TaggedClass<ToolUse>()("ToolUse", {
   tool: Schema.String,
   args: Schema.String,
+  /** The tool call this one runs inside, when a harness delegated it to a sub-agent (ADR 0033). */
+  parent: Schema.optionalKey(Schema.String),
   /** The concurrent unit (a story) this event belongs to; absent for run-wide events. */
   lane: Schema.optionalKey(Schema.String),
   /** The roster executor working that lane, when there is one (ADR 0019). */
@@ -109,7 +111,9 @@ export class TokensUsed extends Schema.TaggedClass<TokensUsed>()("TokensUsed", {
   /** The concurrent unit (a story) this event belongs to; absent for run-wide events. */
   lane: Schema.optionalKey(Schema.String),
   /** The roster executor working that lane, when there is one (ADR 0019). */
-  executor: Schema.optionalKey(Schema.String)
+  executor: Schema.optionalKey(Schema.String),
+  /** The executor's clone that made the call, when the lane's coder holds a slot (ADR 0033). */
+  clone: Schema.optionalKey(Schema.Int)
 }) {}
 
 /** One issue a review round found, as the operator sees it. */
@@ -270,9 +274,54 @@ export class StoryJudged extends Schema.TaggedClass<StoryJudged>()("StoryJudged"
  * The executor roster's events (ADR 0019, 0022). `label` names who holds the
  * lease — a story's id, or "the run" — so a view can put an executor on its lane.
  */
+/** One task of a story's plan as the task loop announces it (ADR 0033). */
+export const PlannedTask = Schema.Struct({
+  title: Schema.String,
+  completed: Schema.Boolean,
+  /** The acceptance criteria the task's description names (`Satisfies: 1, 3`). */
+  satisfies: Schema.optionalKey(Schema.Array(Schema.Int))
+})
+
+/** The task loop's plan, before its first task: every task in order (ADR 0033). */
+export class TasksPlanned extends Schema.TaggedClass<TasksPlanned>()("TasksPlanned", {
+  tasks: Schema.Array(PlannedTask),
+  lane: Schema.optionalKey(Schema.String),
+  executor: Schema.optionalKey(Schema.String)
+}) {}
+
+/** A task begins: its position in the plan, from 1, and the plan's size (ADR 0033). */
+export class TaskStarted extends Schema.TaggedClass<TaskStarted>()("TaskStarted", {
+  index: Schema.Int,
+  count: Schema.Int,
+  title: Schema.String,
+  satisfies: Schema.optionalKey(Schema.Array(Schema.Int)),
+  lane: Schema.optionalKey(Schema.String),
+  executor: Schema.optionalKey(Schema.String)
+}) {}
+
+/** A task is ticked in the plan (ADR 0033). */
+export class TaskCompleted extends Schema.TaggedClass<TaskCompleted>()("TaskCompleted", {
+  index: Schema.Int,
+  count: Schema.Int,
+  title: Schema.String,
+  lane: Schema.optionalKey(Schema.String),
+  executor: Schema.optionalKey(Schema.String)
+}) {}
+
+/** A story moved on the epic's board (ADR 0033); the statuses are `BoardSync`'s. */
+export class StoryStatusChanged extends Schema.TaggedClass<StoryStatusChanged>()(
+  "StoryStatusChanged",
+  {
+    id: Schema.String,
+    status: Schema.Literals(["planned", "active", "waiting", "done", "failed", "skipped"])
+  }
+) {}
+
 export class ExecutorLeased extends Schema.TaggedClass<ExecutorLeased>()("ExecutorLeased", {
   executor: Schema.String,
   role: Schema.String,
+  /** Which of the executor's clones took the slot, from 1 (ADR 0033); absent when borrowed or before 2.41. */
+  clone: Schema.optionalKey(Schema.Int),
   label: Schema.optionalKey(Schema.String),
   /** What the call is for beyond its role: a review lens, a vote. */
   purpose: Schema.optionalKey(Schema.String),
@@ -290,6 +339,8 @@ export class ExecutorLeased extends Schema.TaggedClass<ExecutorLeased>()("Execut
 export class ExecutorReleased extends Schema.TaggedClass<ExecutorReleased>()("ExecutorReleased", {
   executor: Schema.String,
   role: Schema.String,
+  /** Which of the executor's clones freed the slot (ADR 0033); absent when borrowed or before 2.41. */
+  clone: Schema.optionalKey(Schema.Int),
   label: Schema.optionalKey(Schema.String)
 }) {}
 
@@ -335,12 +386,16 @@ const resumedWords: Readonly<Record<ExecutorResumed["why"], string>> = {
  * the roster used to publish as `Info` — or `undefined` for one it does not
  * show (a release) and for any other event.
  */
+/** `codex#2` for a numbered clone, the bare executor otherwise (ADR 0033). */
+export const cloneName = (executor: string, clone: number | undefined): string =>
+  clone === undefined ? executor : `${executor}#${clone}`
+
 export const rosterEventMessage = (event: FlowEvent): string | undefined => {
   const forLabel = (label: string | undefined): string =>
     label === undefined ? "" : ` for ${label}`
   switch (event._tag) {
     case "ExecutorLeased": {
-      const taken = `roster: ${event.executor} takes ${event.role}${forLabel(event.label)}${
+      const taken = `roster: ${cloneName(event.executor, event.clone)} takes ${event.role}${forLabel(event.label)}${
         event.purpose === undefined ? "" : ` · ${event.purpose}`
       }`
       if (event.because === undefined && event.borrowed !== true) {
@@ -395,7 +450,11 @@ export const FlowEvent = Schema.Union([
   ExecutorHandedOver,
   StoryJudged,
   Timed,
-  Began
+  Began,
+  TasksPlanned,
+  TaskStarted,
+  TaskCompleted,
+  StoryStatusChanged
 ])
 export type FlowEvent = typeof FlowEvent.Type
 
@@ -419,6 +478,8 @@ export interface Lane {
   readonly lane: string
   /** The executor working it now; read at every publish, so a handover shows. */
   readonly executor?: Effect.Effect<string | undefined>
+  /** The coder's clone number, read at every publish as `executor` is (ADR 0033). */
+  readonly clone?: Effect.Effect<number | undefined>
   /** The lane's working directory, dropped from tool arguments (the lane already names it). */
   readonly workDir?: string
 }
@@ -436,10 +497,33 @@ const stamped = (
   event: FlowEvent,
   lane: string,
   executor: string | undefined,
-  workDir: string | undefined
+  workDir: string | undefined,
+  clone: number | undefined
 ): FlowEvent => {
   const tags = { lane, ...(executor === undefined ? {} : { executor }) }
+  const usageTags = { ...tags, ...(clone === undefined ? {} : { clone }) }
   switch (event._tag) {
+    case "TasksPlanned":
+      return event.lane !== undefined ? event : TasksPlanned.make({ tasks: event.tasks, ...tags })
+    case "TaskStarted":
+      return event.lane !== undefined
+        ? event
+        : TaskStarted.make({
+            index: event.index,
+            count: event.count,
+            title: event.title,
+            ...(event.satisfies === undefined ? {} : { satisfies: event.satisfies }),
+            ...tags
+          })
+    case "TaskCompleted":
+      return event.lane !== undefined
+        ? event
+        : TaskCompleted.make({
+            index: event.index,
+            count: event.count,
+            title: event.title,
+            ...tags
+          })
     case "StageStarted":
       return event.lane !== undefined ? event : StageStarted.make({ stage: event.stage, ...tags })
     case "StageCompleted":
@@ -456,6 +540,7 @@ const stamped = (
         : ToolUse.make({
             tool: event.tool,
             args: shortenLaneArgs(event.args, workDir),
+            ...(event.parent === undefined ? {} : { parent: event.parent }),
             ...tags
           })
     case "AssistantMessage":
@@ -485,7 +570,9 @@ const stamped = (
             agent: event.agent,
             usage: event.usage,
             ...(event.model === undefined ? {} : { model: event.model }),
-            ...tags
+            // The lane's clone is its coder's: a reviewer or judge on the
+            // lane's events ran on another executor (ADR 0033).
+            ...(event.agent === "coder" ? usageTags : tags)
           })
     // The lane's executor is its coder's: it names a coder call or tool, not
     // a reviewer's or judge's call made on another executor.
@@ -523,7 +610,9 @@ const stamped = (
 export const withLane = (events: FlowEventsShape, lane: Lane): FlowEventsShape => ({
   publish: (event) =>
     Effect.flatMap(lane.executor ?? Effect.succeed(undefined), (executor) =>
-      events.publish(stamped(event, lane.lane, executor, lane.workDir))
+      Effect.flatMap(lane.clone ?? Effect.succeed(undefined), (clone) =>
+        events.publish(stamped(event, lane.lane, executor, lane.workDir, clone))
+      )
     )
 })
 

package/src/PlanExecution.ts

@@ -1,5 +1,13 @@
 import * as Effect from "effect/Effect"
-import { StageCompleted, StageFailed, StageStarted, type FlowEventsShape } from "./FlowEvents.ts"
+import {
+  StageCompleted,
+  StageFailed,
+  StageStarted,
+  TaskCompleted,
+  TaskStarted,
+  TasksPlanned,
+  type FlowEventsShape
+} from "./FlowEvents.ts"
 import { withKindSpan, type SpanOptions } from "./Spans.ts"
 import { describeFlowError, type FlowError } from "./FlowError.ts"
 import type { Plan, Task } from "./Plan.ts"
@@ -35,6 +43,26 @@ export const stage = <A, E, R>(
     )
   )
 
+/** The acceptance criteria a task's description names: `Satisfies: 1, 3` → `[1, 3]` (ADR 0033). */
+export const satisfiesOf = (description: string): ReadonlyArray<number> | undefined => {
+  // The planner writes JSON, so the line is usually the description's last sentence.
+  const match = /\bSatisfies:\s*([^\n]*)/iu.exec(description)
+  if (match === null) {
+    return undefined
+  }
+  const numbers = (match[1] ?? "")
+    .split(/[^\d]+/u)
+    .filter((part) => part.length > 0)
+    .map((part) => Number.parseInt(part, 10))
+    .filter((number) => Number.isInteger(number) && number > 0)
+  return numbers.length === 0 ? undefined : numbers
+}
+
+const withSatisfies = (description: string): { readonly satisfies?: ReadonlyArray<number> } => {
+  const satisfies = satisfiesOf(description)
+  return satisfies === undefined ? {} : { satisfies }
+}
+
 export const implementTaskLoop = Effect.fn("@llm4ts/flow/PlanExecution.implementTaskLoop")(
   function* <E, R>(
     store: PlanStoreShape,
@@ -44,11 +72,26 @@ export const implementTaskLoop = Effect.fn("@llm4ts/flow/PlanExecution.implement
     perTask: (task: Task, planSoFar: Plan) => Effect.Effect<void, E, R>
   ): Effect.fn.Return<Plan, E | FlowError, R> {
     let current = plan
-    for (const task of plan.tasks) {
+    const count = plan.tasks.length
+    yield* events.publish(
+      TasksPlanned.make({
+        tasks: plan.tasks.map((task) => ({
+          title: task.title,
+          completed: task.completed,
+          ...withSatisfies(task.description)
+        }))
+      })
+    )
+    for (const [position, task] of plan.tasks.entries()) {
       if (!task.completed) {
+        const index = position + 1
+        yield* events.publish(
+          TaskStarted.make({ index, count, title: task.title, ...withSatisfies(task.description) })
+        )
         yield* stage(events, task.title, perTask(task, current))
         current = current.complete(task.title)
         yield* store.save(planPath, current)
+        yield* events.publish(TaskCompleted.make({ index, count, title: task.title }))
       }
     }
     return current

package/src/Roster.ts

@@ -55,7 +55,7 @@ export class ExecutorSpec extends Schema.Class<ExecutorSpec>("ExecutorSpec")({
   baseUrl: Schema.optionalKey(Schema.String),
   roles: Schema.Array(Schema.String),
   slots: Schema.optionalKey(Schema.Number),
-  /** Slots coders may use; default `slots - 1` when the executor also reasons. */
+  /** Slots coders may use; default: every slot (ADR 0033). */
   coderSlots: Schema.optionalKey(Schema.Number),
   /** Lower first. A number for every role, or per role with a `default`. */
   priority: Schema.optionalKey(
@@ -105,8 +105,6 @@ export class RosterState extends Schema.Class<RosterState>("RosterState")({
 
 // ---- Pure helpers -------------------------------------------------------------
 
-const reasoningRoles: ReadonlyArray<Role> = ["planner", "reviewer", "judge", "verifier"]
-
 export const isRole = (value: string): value is Role => roles.some((role) => role === value)
 
 export const rolesOf = (spec: ExecutorSpec): ReadonlyArray<Role> => spec.roles.filter(isRole)
@@ -115,14 +113,12 @@ export const hasRole = (spec: ExecutorSpec, role: Role): boolean => rolesOf(spec
 
 export const slotsOf = (spec: ExecutorSpec): number => Math.max(1, Math.floor(spec.slots ?? 1))
 
-/** Slots coders may hold: one stays free for reasoning on an executor that does both. */
+/** Slots coders may hold: every clone, unless the roster sets `coderSlots` lower (ADR 0033). */
 export const coderSlotsOf = (spec: ExecutorSpec): number => {
   const slots = slotsOf(spec)
-  if (spec.coderSlots !== undefined) {
-    return Math.max(0, Math.min(slots, Math.floor(spec.coderSlots)))
-  }
-  const reasons = rolesOf(spec).some((role) => reasoningRoles.includes(role))
-  return hasRole(spec, "coder") && reasons && slots > 1 ? slots - 1 : slots
+  return spec.coderSlots === undefined
+    ? slots
+    : Math.max(0, Math.min(slots, Math.floor(spec.coderSlots)))
 }
 
 /** The effort a role runs at on this executor (ADR 0029); absent is the harness's default. */
@@ -419,6 +415,8 @@ export interface Lease {
   readonly role: Role
   /** Frees the slot; idempotent, and also run when the lease's scope closes. */
   readonly release: Effect.Effect<void>
+  /** Which of the executor's clones this is, from 1; absent on a borrowed lease (ADR 0033). */
+  readonly clone: number | undefined
   /** Took no slot: the context's own coder executor serves the call (see `LeaseOptions.borrow`). */
   readonly borrowed: boolean
   /** Set when the executor is the context's own coder (not independent), and why; see `ExecutorLeased.because`. */
@@ -522,6 +520,12 @@ interface Usage {
   busyCoders: number
 }
 
+/** A slot taken under the lock: the executor and which of its clones. */
+interface Taken {
+  readonly spec: ExecutorSpec
+  readonly clone: number
+}
+
 export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
   options: RosterOptions
 ): Effect.fn.Return<RosterShape, FlowError> {
@@ -534,6 +538,21 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
   const rateLimits = new Map<string, ReadonlyArray<number>>()
   const lastLeased = new Map<string, number>()
   let leases = 0
+  /** Clone numbers in use per executor; a lease takes the lowest free one (ADR 0033). */
+  const clones = new Map<string, Set<number>>(executors.map((spec) => [spec.id, new Set<number>()]))
+  const takeClone = (spec: ExecutorSpec): number => {
+    const used = clones.get(spec.id) ?? new Set<number>()
+    let clone = 1
+    while (used.has(clone)) {
+      clone += 1
+    }
+    used.add(clone)
+    clones.set(spec.id, used)
+    return clone
+  }
+  const freeClone = (spec: ExecutorSpec, clone: number): void => {
+    clones.get(spec.id)?.delete(clone)
+  }
   const changed = yield* Ref.make(yield* Deferred.make<void>())
   const known = new Set(executors.map((spec) => spec.id))
 
@@ -611,7 +630,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
       : best
   }
 
-  const release = (spec: ExecutorSpec, role: Role): Effect.Effect<void> =>
+  const release = (spec: ExecutorSpec, role: Role, clone: number): Effect.Effect<void> =>
     lock
       .withPermit(
         Effect.sync(() => {
@@ -622,33 +641,42 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
               used.busyCoders = Math.max(0, used.busyCoders - 1)
             }
           }
+          freeClone(spec, clone)
         })
       )
       .pipe(Effect.andThen(signal))
 
   const leaseOf = (
-    spec: ExecutorSpec,
+    taken: Taken,
     role: Role,
     who: LeaseOptions,
     because?: "nobody" | "held" | "out"
   ): Effect.Effect<Lease, never, Scope.Scope> =>
     Effect.gen(function* () {
+      const { spec, clone } = taken
       const labelled = who.label === undefined ? {} : { label: who.label }
       const own = because === undefined ? {} : { because }
       yield* events.publish(
-        ExecutorLeased.make({ executor: spec.id, role, ...labelled, ...purposeOf(who), ...own })
+        ExecutorLeased.make({
+          executor: spec.id,
+          role,
+          clone,
+          ...labelled,
+          ...purposeOf(who),
+          ...own
+        })
       )
       const done = yield* Ref.make(false)
       const free = Effect.flatMap(Ref.getAndSet(done, true), (was) =>
         was
           ? Effect.void
           : Effect.andThen(
-              release(spec, role),
-              events.publish(ExecutorReleased.make({ executor: spec.id, role, ...labelled }))
+              release(spec, role, clone),
+              events.publish(ExecutorReleased.make({ executor: spec.id, role, clone, ...labelled }))
             )
       )
       yield* Effect.addFinalizer(() => free)
-      return { executor: spec, role, release: free, borrowed: false, ...own }
+      return { executor: spec, role, clone, release: free, borrowed: false, ...own }
     })
 
   /** A lease over the context's own coder executor: no slot taken, none freed. */
@@ -677,32 +705,30 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
           : events.publish(ExecutorReleased.make({ executor: spec.id, role, ...labelled }))
       )
       yield* Effect.addFinalizer(() => free)
-      return { executor: spec, role, release: free, borrowed: true, because }
+      return { executor: spec, role, clone: undefined, release: free, borrowed: true, because }
     })
 
-  /** One attempt: expire, pick, take the slot — all under the lock. */
-  const attempt = (
-    role: Role,
-    leaseOptions: LeaseOptions
-  ): Effect.Effect<ExecutorSpec | undefined> =>
+  /** One attempt: expire, pick, take the slot and its clone number — all under the lock. */
+  const attempt = (role: Role, leaseOptions: LeaseOptions): Effect.Effect<Taken | undefined> =>
     Effect.gen(function* () {
       const now = yield* Clock.currentTimeMillis
-      const { spec, back } = yield* lock.withPermit(
+      const { taken, back } = yield* lock.withPermit(
         Effect.sync(() => {
           const back = expire(now)
           const spec = pick(role, leaseOptions)
-          if (spec !== undefined) {
-            const used = usage.get(spec.id)
-            if (used !== undefined) {
-              used.busy += 1
-              if (role === "coder") {
-                used.busyCoders += 1
-              }
+          if (spec === undefined) {
+            return { taken: undefined, back }
+          }
+          const used = usage.get(spec.id)
+          if (used !== undefined) {
+            used.busy += 1
+            if (role === "coder") {
+              used.busyCoders += 1
             }
-            leases += 1
-            lastLeased.set(spec.id, leases)
           }
-          return { spec, back }
+          leases += 1
+          lastLeased.set(spec.id, leases)
+          return { taken: { spec, clone: takeClone(spec) }, back }
         })
       )
       if (back.length > 0) {
@@ -711,7 +737,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         )
         yield* persist
       }
-      return spec
+      return taken
     })
 
   const canEverServe = (role: Role, avoid: ReadonlyArray<string> = []): Effect.Effect<boolean> =>
@@ -880,7 +906,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
             prefer: borrow.id
           })
           yield* waited
-          return own !== undefined && own.id === borrow.id
+          return own !== undefined && own.spec.id === borrow.id
             ? yield* leaseOf(own, role, leaseOptions, because)
             : own !== undefined
               ? // Someone came back between the check and the pick: independent after all.

package/src/RosterSeats.ts

@@ -258,6 +258,8 @@ export interface HeldCoderOptions {
 export interface HeldCoder {
   readonly service: LlmServiceShape
   readonly executor: Effect.Effect<string | undefined>
+  /** The held coder's clone number, when it holds a slot (ADR 0033). */
+  readonly clone: Effect.Effect<number | undefined>
   readonly lease: Effect.Effect<ExecutorSpec | undefined>
   readonly history: Effect.Effect<ReadonlyArray<string>>
 }
@@ -375,6 +377,7 @@ export const makeHeldCoder = Effect.fn("@llm4ts/flow/RosterSeats.heldCoder")(fun
   return {
     service: serviceOver({ run, stream, isAvailable: roster.canEverServe("coder") }),
     executor: Effect.map(Ref.get(current), (held) => held?.lease.executor.id),
+    clone: Effect.map(Ref.get(current), (held) => held?.lease.clone),
     lease: Effect.map(Ref.get(current), (held) => held?.lease.executor),
     history: Ref.get(history)
   }

package/src/Stories.ts

@@ -18,7 +18,7 @@ import type { LlmServiceShape } from "@llm4ts/core/LlmService"
 import { cap } from "./Context.ts"
 import type { LlmChunk, TokenUsage } from "@llm4ts/core/Models"
 import type { LlmError } from "@llm4ts/core/Errors"
-import { BoardItem, type BoardSyncShape } from "./BoardSync.ts"
+import { BoardItem, eventedBoard, type BoardSyncShape } from "./BoardSync.ts"
 import { makeChat } from "./Chat.ts"
 import { implementPlanFlow } from "./Flow.ts"
 import {
@@ -873,8 +873,10 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   options: StoriesOptions
 ): Effect.fn.Return<EpicReport, FlowError> {
   const plan = yield* validateStoryPlan(options.plan)
-  const { files, board } = options
+  const { files } = options
   const events = context.events
+  // Every board move is also an event, so the trace and the dashboard see it (ADR 0033).
+  const board = eventedBoard(options.board, events)
   const epicBranch = options.epicBranch ?? `epic/${plan.epicId}`
   const concurrency = Math.max(1, options.concurrency ?? 3)
   const judgeRounds = Math.max(1, options.judgeRounds ?? 2)

package/src/Transcript.ts

@@ -22,6 +22,8 @@ const Call = Schema.TaggedStruct("Call", {
   call: Schema.String,
   role: Schema.String,
   executor: Schema.optionalKey(Schema.String),
+  /** The executor's clone, when the seat's coder holds a slot (ADR 0033). */
+  clone: Schema.optionalKey(Schema.Int),
   /** The system prompt, on a chat's first call only. */
   system: Schema.optionalKey(Schema.String),
   /** The input: a chat's newest message, or a one-shot prompt. */
@@ -96,6 +98,8 @@ export interface TranscriptSeatOptions {
   readonly role: string
   /** Who serves the seat, read at each call (a roster hands the coder over). */
   readonly executor?: Effect.Effect<string | undefined>
+  /** Which clone of that executor, read at each call (ADR 0033). */
+  readonly clone?: Effect.Effect<number | undefined>
 }
 
 /** A seat whose every call is written to `sink`, as it happens. */
@@ -115,12 +119,14 @@ export const transcriptSeat = (
       const start = yield* Clock.currentTimeMillis
       const role = yield* roleOr(options.role)
       const executor = options.executor === undefined ? undefined : yield* options.executor
+      const clone = options.clone === undefined ? undefined : yield* options.clone
       yield* write({
         _tag: "Call",
         at: start,
         call,
         role,
         ...(executor === undefined ? {} : { executor }),
+        ...(clone === undefined ? {} : { clone }),
         ...(extra.system === undefined ? {} : { system: clean(extra.system, inputChars) }),
         input: clean(input, inputChars),
         ...(extra.earlier === undefined ? {} : { earlier: extra.earlier })