@llm4ts/flow 2.8.0 → 2.9.1

package/src/Stories.ts

@@ -18,16 +18,17 @@ import type { LlmError } from "@llm4ts/core/Errors"
 import { BoardItem, type BoardSyncShape } from "./BoardSync.ts"
 import { makeChat } from "./Chat.ts"
 import { implementPlanFlow } from "./Flow.ts"
-import type { FlowContextShape } from "./FlowContext.ts"
+import type { ContextOptions, FlowContextShape } from "./FlowContext.ts"
 import {
   describeFlowError,
+  rosterExhaustedPrefix,
   EpicCheckoutDirty,
   MissingDependency,
   PerimeterViolation,
   StoryFailed,
   type FlowError
 } from "./FlowError.ts"
-import { Info } from "./FlowEvents.ts"
+import { Info, withLane, type FlowEventsShape } from "./FlowEvents.ts"
 import { statusPaths, type GitToolShape } from "./GitTool.ts"
 import {
   checkPerimeter,
@@ -89,7 +90,9 @@ export class StoryState extends Schema.Class<StoryState>("StoryState")({
   hash: Schema.String,
   branch: Schema.String,
   worktree: Schema.String,
-  status: StoryStatus
+  status: StoryStatus,
+  /** The roster executor that last held the story's coder (ADR 0019); preferred on resume. */
+  executor: Schema.optionalKey(Schema.String)
 }) {}
 
 export const EpicReportVersion = 1
@@ -106,6 +109,8 @@ export class StoryOutcome extends Schema.Class<StoryOutcome>("StoryOutcome")({
   /** Failure reason, or what a waiting story waits for. */
   reason: Schema.optionalKey(Schema.String),
   judge: Schema.optionalKey(Schema.String),
+  /** The roster executor(s) that coded the story, in order ("codex → claude"). */
+  executor: Schema.optionalKey(Schema.String),
   /** ESTIMATES, never measurements (ADR 0012). */
   estimatedTokens: Schema.optionalKey(Schema.Int),
   estimatedCostUsd: Schema.optionalKey(Schema.Number)
@@ -159,6 +164,27 @@ export const renderEpicReport = (report: EpicReport): string => {
   if (cost.length > 0) {
     lines.push(`- Estimated cost: ${money(cost.reduce((sum, value) => sum + value, 0))}`)
   }
+  const coded = report.stories.filter((story) => story.executor !== undefined)
+  if (coded.length > 0) {
+    // A story is counted for the executor that finished it; a handover chain
+    // is shown in full next to the story.
+    const byExecutor = new Map<string, { stories: Array<string>; tokens: number; cost: number }>()
+    for (const story of coded) {
+      const chain = story.executor ?? ""
+      const last = chain.split(" → ").at(-1) ?? chain
+      const entry = byExecutor.get(last) ?? { stories: [], tokens: 0, cost: 0 }
+      entry.stories.push(chain === last ? story.id : `${story.id} (${chain})`)
+      entry.tokens += story.estimatedTokens ?? 0
+      entry.cost += story.estimatedCostUsd ?? 0
+      byExecutor.set(last, entry)
+    }
+    lines.push("", "## By executor", "")
+    for (const [executor, entry] of byExecutor) {
+      lines.push(
+        `- ${executor}: ${entry.stories.join(", ")} — ~${entry.tokens} tokens, ${money(entry.cost)} (estimated)`
+      )
+    }
+  }
   lines.push("")
   return lines.join("\n")
 }
@@ -423,7 +449,10 @@ export interface StoriesOptions {
   /** Default `epic/<epicId>`. */
   readonly epicBranch?: string
   /** Seats rooted in a worktree; the executor never resolves seats itself. */
-  readonly contextFor: (workDir: string) => Effect.Effect<StorySeats, FlowError, Scope.Scope>
+  readonly contextFor: (
+    workDir: string,
+    options?: ContextOptions
+  ) => Effect.Effect<StorySeats, FlowError, Scope.Scope>
   readonly board: BoardSyncShape
   /**
    * Prepares a worktree before its coder runs — a fresh checkout has no
@@ -434,7 +463,11 @@ export interface StoriesOptions {
   /** The target's gates, run in a worktree per task and on the epic checkout after each merge. */
   readonly gates: (workDir: string) => Effect.Effect<ReviewResult, FlowError>
   /** Story-level judge over the branch's diff against the epic branch; omit to skip. */
-  readonly judge?: (story: Story, diff: string) => Effect.Effect<ReviewResult, FlowError>
+  readonly judge?: (
+    story: Story,
+    diff: string,
+    seats: StorySeats
+  ) => Effect.Effect<ReviewResult, FlowError>
   /** Judge attempts, each but the last followed by one coder feedback round. Default 2. */
   readonly judgeRounds?: number
   /** Extra system context per story (house rules, shared read-only excerpts). */
@@ -459,7 +492,8 @@ export interface StoriesOptions {
   readonly verifyBlocked?: (
     story: Story,
     need: string,
-    workDir: string
+    workDir: string,
+    seats: StorySeats
   ) => Effect.Effect<BlockedVerdict, FlowError>
   /**
    * Waits until a serving engine that went down (`isOutageMessage`) is back;
@@ -528,6 +562,18 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       }
     })
 
+  /** A story's own events say so (a lane), so concurrent stories stay apart on screen. */
+  const lanes = new Map<string, FlowEventsShape>()
+  const laneOf = (story: Story): FlowEventsShape => {
+    const known = lanes.get(story.id)
+    if (known !== undefined) {
+      return known
+    }
+    const lane = withLane(events, { lane: story.id })
+    lanes.set(story.id, lane)
+    return lane
+  }
+
   yield* epicCheckoutClean()
   yield* stage(events, "epic branch", context.git.checkoutOrCreate(epicBranch))
 
@@ -566,7 +612,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             `epic gates failed after merging; merge undone:\n${issueLines(gate)}`
           )
         }
-        yield* events.publish(
+        yield* laneOf(story).publish(
           Info.make({ message: `story ${story.id}: merged into ${epicBranch}` })
         )
       })
@@ -582,7 +628,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     const path = statePath(story)
     let stored = yield* loadVersioned(files, path, StoryStateVersion, StoryState)
     if (stored !== undefined && stored.hash !== hash) {
-      yield* events.publish(
+      yield* laneOf(story).publish(
         Info.make({
           message: `story ${story.id}: plan entry changed since its branch was created; starting over`
         })
@@ -593,7 +639,9 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         .removeWorktree(stored.worktree, true)
         .pipe(
           Effect.catch((error) =>
-            events.publish(Info.make({ message: `story ${story.id}: ${describeFlowError(error)}` }))
+            laneOf(story).publish(
+              Info.make({ message: `story ${story.id}: ${describeFlowError(error)}` })
+            )
           )
         )
       if (yield* context.git.branchExists(stored.branch)) {
@@ -621,7 +669,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     if (stored.worktree !== worktree) {
       if ((yield* files.read(join(stored.worktree, ".git"))) !== undefined) {
         yield* context.git.moveWorktree(stored.worktree, worktree)
-        yield* events.publish(
+        yield* laneOf(story).publish(
           Info.make({ message: `story ${story.id}: moved its worktree to ${worktree}` })
         )
       }
@@ -632,7 +680,9 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     if (marker === undefined) {
       yield* context.git.addWorktree(state.worktree, state.branch)
     }
-    yield* events.publish(Info.make({ message: `story ${story.id}: resuming ${state.branch}` }))
+    yield* laneOf(story).publish(
+      Info.make({ message: `story ${story.id}: resuming ${state.branch}` })
+    )
     return { state, alreadyMerged: false }
   })
 
@@ -654,7 +704,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       yield* git.merge(epicBranch, `${story.id}: catch up with ${epicBranch}`, {
         preferIncoming: true
       })
-      yield* events.publish(
+      yield* laneOf(story).publish(
         Info.make({ message: `story ${story.id}: caught up with ${epicBranch}` })
       )
     })
@@ -675,11 +725,29 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     story: Story,
     state: StoryState
   ): Effect.fn.Return<
-    { readonly judge: string | undefined; readonly totals: TokenUsage | undefined },
+    {
+      readonly judge: string | undefined
+      readonly totals: TokenUsage | undefined
+      readonly executor: string | undefined
+    },
     FlowError,
     Scope.Scope
   > {
-    const seats = yield* options.contextFor(state.worktree)
+    const seats = yield* options.contextFor(state.worktree, {
+      label: story.id,
+      ...(state.executor === undefined ? {} : { prefer: state.executor })
+    })
+    const roster = seats.context.roster
+    const coderExecutor = roster === undefined ? undefined : yield* roster.executor
+    if (coderExecutor !== undefined && coderExecutor !== state.executor) {
+      yield* saveVersioned(
+        files,
+        statePath(story),
+        StoryStateVersion,
+        StoryState,
+        StoryState.make({ ...state, executor: coderExecutor })
+      )
+    }
     const blocked = yield* Ref.make<string | undefined>(undefined)
     const pushbacks = yield* Ref.make(0)
     const storyContext: FlowContextShape = {
@@ -700,7 +768,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     // Catch up before setup: the epic may have changed the manifest too.
     yield* catchUp(story, git)
     if (options.setup !== undefined) {
-      yield* stage(events, `story ${story.id}: setup`, options.setup(state.worktree))
+      yield* stage(laneOf(story), `story ${story.id}: setup`, options.setup(state.worktree))
     }
 
     // The target's gates plus the perimeter: a stray path is a gate failure
@@ -750,7 +818,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         let rebuttal = blockedRebuttal(plan, story, need)
         if (rebuttal === undefined && options.verifyBlocked !== undefined) {
           const verdict = yield* options
-            .verifyBlocked(story, need, state.worktree)
+            .verifyBlocked(story, need, state.worktree, watchedSeats)
             .pipe(Effect.catch(() => Effect.succeed(undefined)))
           rebuttal = verdict === undefined || verdict.real ? undefined : verdict.reason
         }
@@ -759,7 +827,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         }
         yield* Ref.set(blocked, undefined)
         yield* Ref.update(pushbacks, (count) => count + 1)
-        yield* events.publish(
+        yield* laneOf(story).publish(
           Info.make({ message: `story ${story.id}: BLOCKED_ON rejected — ${rebuttal}` })
         )
         yield* coderTurn(
@@ -812,7 +880,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       if (!isWithinPerimeter(second)) {
         const stray = [...second.sharedReadOnly, ...second.outside]
         yield* git.restorePaths(epicBranch, stray)
-        yield* events.publish(
+        yield* laneOf(story).publish(
           Info.make({
             message: `story ${story.id}: restored ${stray.length} path(s) outside its perimeter from ${epicBranch}: ${stray.join(", ")}`
           })
@@ -830,7 +898,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         story,
         (text) => planTasks(watchedSeats, story, text),
         prompt,
-        events
+        laneOf(story)
       ),
       system,
       chatPerTask: true,
@@ -861,7 +929,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
           // a model asked to score an empty diff scores the prompt instead.
           return yield* failed(story, "the story branch has no changes against the epic branch")
         }
-        const verdict = yield* judge(story, diff)
+        const verdict = yield* judge(story, diff, watchedSeats)
         if (verdict.isClean) {
           judgeNote = `judge cleared (round ${round})`
           break
@@ -890,7 +958,12 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     const changed = yield* git.changedFilesVsBase(epicBranch)
     yield* enforcePerimeter(changed, story)
     const totals = seats.totals === undefined ? undefined : yield* seats.totals
-    return { judge: judgeNote, totals }
+    const history = roster === undefined ? [] : yield* roster.history
+    return {
+      judge: judgeNote,
+      totals,
+      executor: history.length === 0 ? undefined : history.join(" → ")
+    }
   })
 
   const runStory = Effect.fn("@llm4ts/flow/Stories.runStory")(function* (
@@ -899,7 +972,9 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     yield* board.start(story.id)
     const { state, alreadyMerged } = yield* prepareWorktree(story)
     if (alreadyMerged) {
-      yield* events.publish(Info.make({ message: `story ${story.id}: already merged; skipping` }))
+      yield* laneOf(story).publish(
+        Info.make({ message: `story ${story.id}: already merged; skipping` })
+      )
       return StoryOutcome.make({
         id: story.id,
         title: story.title,
@@ -910,12 +985,17 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     }
     const result = yield* Effect.scoped(implementStory(story, state))
     yield* integrate(story, state.branch)
+    const last = result.executor?.split(" → ").at(-1)
     yield* saveVersioned(
       files,
       statePath(story),
       StoryStateVersion,
       StoryState,
-      StoryState.make({ ...state, status: "merged" })
+      StoryState.make({
+        ...state,
+        status: "merged",
+        ...(last === undefined ? {} : { executor: last })
+      })
     )
     return StoryOutcome.make({
       id: story.id,
@@ -923,6 +1003,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       status: "done",
       branch: state.branch,
       ...(result.judge === undefined ? {} : { judge: result.judge }),
+      ...(result.executor === undefined ? {} : { executor: result.executor }),
       ...(result.totals === undefined ? {} : { estimatedTokens: result.totals.total }),
       ...(result.totals?.costUsd === undefined ? {} : { estimatedCostUsd: result.totals.costUsd })
     })
@@ -930,7 +1011,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
 
   /** A story's run as a completion — failures become outcomes, never fiber deaths. */
   const attempt = (story: Story): Effect.Effect<Completion> =>
-    stage(events, `story ${story.id}`, runStory(story)).pipe(
+    stage(laneOf(story), `story ${story.id}`, runStory(story)).pipe(
       Effect.map((outcome): Completion => ({ story, outcome })),
       Effect.catch((error) =>
         Effect.gen(function* () {
@@ -949,7 +1030,9 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             ).pipe(Effect.ignore)
           }
           const interruption: Interruption | undefined =
-            error._tag === "EpicCheckoutDirty"
+            error._tag === "EpicCheckoutDirty" ||
+            error._tag === "RosterExhausted" ||
+            reason.includes(rosterExhaustedPrefix)
               ? "halt"
               : isOutageMessage(reason)
                 ? "outage"
@@ -1020,7 +1103,16 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         if (halted === undefined) {
           const current = yield* progress
           const ready = readyStories(plan, current)
-          const slots = concurrency - current.running.size
+          // With a roster, never launch more stories than there are free
+          // coders; with nothing running, launch one anyway — its lease waits
+          // for the first executor to come back (ADR 0019).
+          const free =
+            context.roster === undefined
+              ? Number.POSITIVE_INFINITY
+              : yield* context.roster.available("coder")
+          const budget = Math.min(concurrency - current.running.size, free)
+          const slots =
+            current.running.size === 0 && ready.length > 0 ? Math.max(1, budget) : budget
           for (const story of ready.slice(0, Math.max(0, slots))) {
             yield* Ref.update(running, (set) => new Set([...set, story.id]))
             yield* Effect.forkScoped(
@@ -1043,7 +1135,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         if (completion.interruption === "outage" && halted === undefined) {
           if (options.awaitRecovery !== undefined && !recovered.has(completion.story.id)) {
             recovered.add(completion.story.id)
-            yield* events.publish(
+            yield* laneOf(completion.story).publish(
               Info.make({
                 message: `story ${completion.story.id}: the serving engine is down; waiting for it to recover, then retrying the story`
               })
@@ -1066,7 +1158,16 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         if (outcome.status === "done") {
           yield* board.complete(outcome.id, {
             ...(outcome.branch === undefined ? {} : { branch: outcome.branch }),
-            ...(outcome.judge === undefined ? {} : { detail: outcome.judge }),
+            ...(outcome.judge === undefined && outcome.executor === undefined
+              ? {}
+              : {
+                  detail: [
+                    outcome.judge,
+                    outcome.executor === undefined ? undefined : `coder ${outcome.executor}`
+                  ]
+                    .filter((part): part is string => part !== undefined)
+                    .join(" · ")
+                }),
             ...(outcome.estimatedTokens === undefined
               ? {}
               : { estimatedTokens: outcome.estimatedTokens }),