@llm4ts/flow 2.35.0 → 2.35.2

package/src/Roster.ts

@@ -15,6 +15,7 @@ import * as Semaphore from "effect/Semaphore"
 import type { LlmError } from "@llm4ts/core/Errors"
 import { RosterExhausted, type FlowError } from "./FlowError.ts"
 import {
+  Began,
   ExecutorExcluded,
   ExecutorLeased,
   ExecutorReleased,
@@ -461,6 +462,18 @@ export interface RosterShape {
   readonly available: (role: Role) => Effect.Effect<number>
   /** Configured slots for `role`. */
   readonly slots: (role: Role) => number
+  /**
+   * Slots for `role` on the executors in the round, whether held or not: what
+   * the round could serve at once. A call holding a slot for a moment does not
+   * lower it; an executor out of the round does.
+   */
+  readonly capacity: (role: Role) => Effect.Effect<number>
+  /**
+   * Waits until `capacity(role)` is no longer `from` and returns the new
+   * value: an executor resumed, its exclusion expired, its health came back,
+   * or one left the round. Returns at once when it already differs.
+   */
+  readonly capacityChanged: (role: Role, from: number) => Effect.Effect<number>
   /** Classifies a failure of `id`'s call; returns the exclusion it earned, if any. */
   readonly report: (id: string, error: LlmError) => Effect.Effect<Exclusion | undefined>
   readonly exclude: (exclusion: Exclusion) => Effect.Effect<void>
@@ -768,6 +781,17 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         : Effect.raceFirst(Deferred.await(wake), Effect.sleep(Duration.millis(soonest)))
     })
 
+  /** `waitForChange`, waking at least every probe interval while a health exclusion waits. */
+  const waitOrProbe = (role: Role): Effect.Effect<void> =>
+    Effect.gen(function* () {
+      const probing = yield* lock.withPermit(
+        Effect.sync(() => [...exclusions.values()].some((exclusion) => exclusion.kind === "health"))
+      )
+      yield* probing
+        ? Effect.raceFirst(waitForChange(role), Effect.sleep(healthProbeInterval))
+        : waitForChange(role)
+    })
+
   const waitingReport = (role: Role, avoid: ReadonlyArray<string>): Effect.Effect<string> =>
     lock.withPermit(
       Effect.sync(() =>
@@ -874,6 +898,13 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         }
         if (!announced) {
           announced = true
+          yield* events.publish(
+            Began.make({
+              kind: "wait",
+              label: `roster ${role}`,
+              ...(leaseOptions.label === undefined ? {} : { lane: leaseOptions.label })
+            })
+          )
           yield* say(
             `waiting for an executor to take ${role}${leaseOptions.label === undefined ? "" : ` for ${leaseOptions.label}`}: ${yield* waitingReport(role, avoid)}`
           )
@@ -884,14 +915,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
           yield* waited
           return yield* leaseOf(recovered, role, leaseOptions.label)
         }
-        const probing = yield* lock.withPermit(
-          Effect.sync(() =>
-            [...exclusions.values()].some((exclusion) => exclusion.kind === "health")
-          )
-        )
-        yield* probing
-          ? Effect.raceFirst(waitForChange(role), Effect.sleep(healthProbeInterval))
-          : waitForChange(role)
+        yield* waitOrProbe(role)
       }
     })
 
@@ -977,6 +1001,35 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
       .filter((spec) => hasRole(spec, role))
       .reduce((sum, spec) => sum + (role === "coder" ? coderSlotsOf(spec) : slotsOf(spec)), 0)
 
+  const capacity = (role: Role): Effect.Effect<number> =>
+    Effect.gen(function* () {
+      const now = yield* Clock.currentTimeMillis
+      return yield* lock.withPermit(
+        Effect.sync(() => {
+          expire(now)
+          return eligible(role, []).reduce(
+            (sum, spec) => sum + (role === "coder" ? coderSlotsOf(spec) : slotsOf(spec)),
+            0
+          )
+        })
+      )
+    })
+
+  const capacityChanged = (role: Role, from: number): Effect.Effect<number> =>
+    Effect.gen(function* () {
+      while (true) {
+        yield* probeDue
+        // The wake is taken before the count is read, so a change between
+        // the two still ends the wait.
+        const wake = yield* Ref.get(changed)
+        const now = yield* capacity(role)
+        if (now !== from) {
+          return now
+        }
+        yield* Effect.raceFirst(Deferred.await(wake), waitOrProbe(role))
+      }
+    })
+
   const snapshot: Effect.Effect<ReadonlyArray<ExecutorStatus>> = Effect.gen(function* () {
     const now = yield* Clock.currentTimeMillis
     return yield* lock.withPermit(
@@ -1005,6 +1058,8 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
     independenceBlocked,
     available,
     slots,
+    capacity,
+    capacityChanged,
     report,
     exclude,
     resume,

package/src/RosterSeats.ts

@@ -41,6 +41,10 @@ export interface RosterView {
   readonly available: (role: Role) => Effect.Effect<number>
   /** Configured slots for `role`. */
   readonly slots: (role: Role) => number
+  /** Slots for `role` on the executors in the round, held or not. */
+  readonly capacity: (role: Role) => Effect.Effect<number>
+  /** Waits until `capacity(role)` is no longer `from`; returns the new value. */
+  readonly capacityChanged: (role: Role, from: number) => Effect.Effect<number>
   /** The executor holding this context's coder, once leased. */
   readonly executor: Effect.Effect<string | undefined>
   /** Every executor that held this context's coder, in order (handovers). */

package/src/Stories.ts

@@ -7,6 +7,7 @@
 import * as Clock from "effect/Clock"
 import * as Effect from "effect/Effect"
 import * as Exit from "effect/Exit"
+import * as Option from "effect/Option"
 import * as Queue from "effect/Queue"
 import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
@@ -41,6 +42,7 @@ import {
   type FlowError
 } from "./FlowError.ts"
 import {
+  Began,
   EvidenceChecked,
   Info,
   JudgedDimension,
@@ -780,6 +782,55 @@ export const setupRecoveryPrompt = (command: string): string =>
 const failed = (story: Story, reason: string): StoryFailed =>
   StoryFailed.make({ story: story.id, reason })
 
+/** What the story scheduler can say about stories it is not starting. */
+export interface LaunchPicture {
+  readonly epicId: string
+  readonly running: number
+  readonly concurrency: number
+  /** The roster's coder capacity; absent without a roster. */
+  readonly capacity?: number
+  /** Ready stories left for a coder slot to free. */
+  readonly readyWaiting: number
+  /** Stories whose dependencies are not merged yet, with the ones they wait for. */
+  readonly blocked: ReadonlyArray<{ readonly id: string; readonly on: ReadonlyArray<string> }>
+}
+
+const shownBlocked = 3
+
+/**
+ * One line on why fewer stories run than the cap allows, or `undefined`
+ * when nothing waits: dependencies first (the common case), then capacity.
+ */
+export const launchSummary = (picture: LaunchPicture): string | undefined => {
+  if (picture.blocked.length === 0 && picture.readyWaiting === 0) {
+    return undefined
+  }
+  const cap =
+    picture.capacity === undefined
+      ? `concurrency ${picture.concurrency}`
+      : `concurrency ${picture.concurrency}, ${picture.capacity} coder slot(s)`
+  const blocked =
+    picture.blocked.length === 0
+      ? []
+      : [
+          `${picture.blocked.length} waiting on dependencies: ${picture.blocked
+            .slice(0, shownBlocked)
+            .map((story) => `${story.id} ← ${story.on.join(", ")}`)
+            .join("; ")}${
+            picture.blocked.length > shownBlocked
+              ? ` (+${picture.blocked.length - shownBlocked} more)`
+              : ""
+          }`
+        ]
+  const starved =
+    picture.readyWaiting === 0 ? [] : [`${picture.readyWaiting} ready, waiting for a coder slot`]
+  return [
+    `epic ${picture.epicId}: ${picture.running} running (${cap})`,
+    ...blocked,
+    ...starved
+  ].join(" · ")
+}
+
 // ---- The executor -------------------------------------------------------------
 
 export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(function* (
@@ -933,52 +984,56 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   /** Merge the story branch into the epic branch and re-gate the epic head, one story at a time. */
   const integrate = (story: Story, branch: string): Effect.Effect<void, FlowError> =>
     Effect.flatMap(Clock.currentTimeMillis, (requested) =>
-      mergeLock.withPermit(
-        Effect.gen(function* () {
-          const lane = laneOf(story)
-          // Merges are one at a time: how long this story queued for its turn.
-          const turn = yield* Clock.currentTimeMillis
-          yield* lane.publish(
-            Timed.make({ kind: "wait", label: "merge lock", ms: turn - requested })
-          )
-          yield* epicCheckoutClean(story)
-          const checkpoint = yield* context.git.checkpoint
-          yield* timeEffect(
-            lane,
-            context.git.merge(branch, `${plan.epicId}: merge story ${story.id}`),
-            (ms, failed) =>
-              Timed.make({ kind: "merge", label: "merge", ms, ...(failed ? { failed } : {}) })
-          )
-          const gate = yield* options.gates(context.workDir, lane)
-          // Charged only with what the merge added: the head before it had
-          // a baseline (run start or the previous merge).
-          const before = yield* ensureBaseline(
-            checkpoint,
-            Effect.succeed(ReviewResult.make({ issues: [] })),
-            context.workDir
-          )
-          const verdict = triageGates(gate, before, rootsOf(context.workDir))
-          if (!verdict.blocking.isClean) {
-            // Never leave a red epic head for the next story to inherit.
-            yield* context.git.rollback(checkpoint)
-            return yield* failed(
-              story,
-              `epic gates failed after merging; merge undone:\n${issueLines(verdict.blocking)}`
+      Effect.andThen(
+        laneOf(story).publish(Began.make({ kind: "wait", label: "merge lock" })),
+        mergeLock.withPermit(
+          Effect.gen(function* () {
+            const lane = laneOf(story)
+            // Merges are one at a time: how long this story queued for its turn.
+            const turn = yield* Clock.currentTimeMillis
+            yield* lane.publish(
+              Timed.make({ kind: "wait", label: "merge lock", ms: turn - requested })
             )
-          }
-          if (gateCommands !== undefined) {
-            const mergedHead = yield* context.git.checkpoint
-            yield* writeBaseline(
-              files,
-              options.stateDir,
-              keyFor(mergedHead),
-              yield* baselineOf(mergedHead, gate, context.workDir)
+            yield* epicCheckoutClean(story)
+            const checkpoint = yield* context.git.checkpoint
+            yield* timeEffect(
+              lane,
+              context.git.merge(branch, `${plan.epicId}: merge story ${story.id}`),
+              (ms, failed) =>
+                Timed.make({ kind: "merge", label: "merge", ms, ...(failed ? { failed } : {}) }),
+              () => Began.make({ kind: "merge", label: "merge" })
             )
-          }
-          yield* laneOf(story).publish(
-            Info.make({ message: `story ${story.id}: merged into ${epicBranch}` })
-          )
-        })
+            const gate = yield* options.gates(context.workDir, lane)
+            // Charged only with what the merge added: the head before it had
+            // a baseline (run start or the previous merge).
+            const before = yield* ensureBaseline(
+              checkpoint,
+              Effect.succeed(ReviewResult.make({ issues: [] })),
+              context.workDir
+            )
+            const verdict = triageGates(gate, before, rootsOf(context.workDir))
+            if (!verdict.blocking.isClean) {
+              // Never leave a red epic head for the next story to inherit.
+              yield* context.git.rollback(checkpoint)
+              return yield* failed(
+                story,
+                `epic gates failed after merging; merge undone:\n${issueLines(verdict.blocking)}`
+              )
+            }
+            if (gateCommands !== undefined) {
+              const mergedHead = yield* context.git.checkpoint
+              yield* writeBaseline(
+                files,
+                options.stateDir,
+                keyFor(mergedHead),
+                yield* baselineOf(mergedHead, gate, context.workDir)
+              )
+            }
+            yield* laneOf(story).publish(
+              Info.make({ message: `story ${story.id}: merged into ${epicBranch}` })
+            )
+          })
+        )
       )
     )
 
@@ -1277,7 +1332,13 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         : { rerunTest: options.testGate(state.worktree, laneOf(story)) })
     }
     if (gateCommands !== undefined) {
-      const inherited = (yield* storyBaseline)?.failingLines ?? []
+      // Recorded here, before the first task, so the lane says what the time goes to.
+      const baseline = yield* stage(
+        laneOf(story),
+        `story ${story.id}: baseline gates`,
+        storyBaseline
+      )
+      const inherited = baseline?.failingLines ?? []
       if (inherited.length > 0) {
         inheritedByStory.set(story.id, inherited)
         yield* appendFindings(
@@ -1423,7 +1484,12 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       plan: planWithinPerimeter(
         plan,
         story,
-        (text) => planTasks(watchedSeats, story, text),
+        (text) =>
+          stage(
+            laneOf(story),
+            `story ${story.id}: plan tasks`,
+            planTasks(watchedSeats, story, text)
+          ),
         prompt,
         laneOf(story)
       ),
@@ -1815,26 +1881,34 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
 
   /** Why no further story may start in this run; stories already running finish. */
   let halted: string | undefined
+  /** The last launch summary said, so a picture is told once, when it changes. */
+  let toldLaunch: string | undefined
   /** Stories retried once after the serving engine recovered. */
   const recovered = new Set<string>()
 
   yield* Effect.scoped(
     Effect.gen(function* () {
       while (true) {
+        /** The roster's coder capacity when a ready story was left waiting for it. */
+        let starvedAt: number | undefined
         if (halted === undefined) {
           const current = yield* progress
           const ready = readyStories(plan, current)
-          // 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 =
+          // With a roster, never run more stories than the round has coder
+          // slots: each running story holds one. Capacity, not the slots free
+          // this instant — a review or judge call holding a slot for a moment
+          // must not keep a story from starting; its lease waits for that call.
+          // With nothing running, launch one anyway — its lease waits for the
+          // first executor to come back (ADR 0019).
+          const capacity =
             context.roster === undefined
               ? Number.POSITIVE_INFINITY
-              : yield* context.roster.available("coder")
-          const budget = Math.min(concurrency - current.running.size, free)
+              : yield* context.roster.capacity("coder")
+          const budget = Math.min(concurrency, capacity) - current.running.size
           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))) {
+          const launching = ready.slice(0, Math.max(0, slots))
+          for (const story of launching) {
             yield* Ref.update(running, (set) => new Set([...set, story.id]))
             yield* Effect.forkScoped(
               attempt(story).pipe(
@@ -1842,11 +1916,60 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
               )
             )
           }
+          if (
+            context.roster !== undefined &&
+            ready.length > launching.length &&
+            current.running.size + launching.length < concurrency
+          ) {
+            starvedAt = capacity
+          }
+          // Say why fewer stories run than the cap allows: a plan that
+          // chains its stories looks exactly like a scheduler that stalled.
+          const started = new Set([...current.running, ...launching.map((story) => story.id)])
+          const said = launchSummary({
+            epicId: plan.epicId,
+            running: started.size,
+            concurrency,
+            ...(context.roster === undefined ? {} : { capacity }),
+            readyWaiting: ready.length - launching.length,
+            blocked: plan.stories.flatMap((story) =>
+              current.done.has(story.id) ||
+              current.failed.has(story.id) ||
+              current.waiting.has(story.id) ||
+              started.has(story.id) ||
+              ready.includes(story)
+                ? []
+                : [
+                    {
+                      id: story.id,
+                      on: story.dependsOn.filter((dependency) => !current.done.has(dependency))
+                    }
+                  ]
+            )
+          })
+          if (said !== undefined && said !== toldLaunch) {
+            yield* events.publish(Info.make({ message: said }))
+          }
+          toldLaunch = said
         }
         if ((yield* Ref.get(running)).size === 0) {
           break
         }
-        const completion = yield* Queue.take(completions)
+        // A story waiting only for coder capacity starts as soon as the round
+        // grows (an executor back from a cooldown, a health probe, a resume),
+        // not when the next running story happens to end.
+        const roster = context.roster
+        const next: Option.Option<Completion> =
+          starvedAt === undefined || roster === undefined
+            ? Option.some(yield* Queue.take(completions))
+            : yield* Effect.raceFirst(
+                Effect.map(Queue.take(completions), Option.some),
+                Effect.as(roster.capacityChanged("coder", starvedAt), Option.none<Completion>())
+              )
+        if (Option.isNone(next)) {
+          continue
+        }
+        const completion = next.value
         yield* Ref.update(running, (set) => {
           const next = new Set(set)
           next.delete(completion.story.id)

package/src/Timing.ts

@@ -13,7 +13,7 @@ import { Message, type LlmChunk, type TokenUsage } from "@llm4ts/core/Models"
 import { redactText } from "@llm4ts/core/observability/Redaction"
 import { toolCategory } from "./Activity.ts"
 import { estimateUsage, estimatedModelLabel, type EstimatedUsageOptions } from "./EstimatedUsage.ts"
-import { Timed, type FlowEventsShape } from "./FlowEvents.ts"
+import { Began, Timed, type FlowEventsShape } from "./FlowEvents.ts"
 import {
   attr,
   currentKindSpan,
@@ -192,16 +192,24 @@ const reportedMs = (chunk: LlmChunk, key: string): number | undefined => {
   return Number.isFinite(value) ? value : undefined
 }
 
-/** Times `effect`, publishing what `timed` makes of its duration whether it succeeds or fails. */
+/**
+ * Times `effect`, publishing what `timed` makes of its duration whether it
+ * succeeds or fails; with `began`, also what it makes of the start, when the
+ * effect starts, so a screen shows the work while it runs.
+ */
 export const timeEffect = <A, E, R>(
   events: FlowEventsShape,
   effect: Effect.Effect<A, E, R>,
-  timed: (ms: number, failed: boolean, role: string | undefined) => Timed
+  timed: (ms: number, failed: boolean, role: string | undefined) => Timed,
+  began?: (role: string | undefined) => Began
 ): Effect.Effect<A, E, R> =>
   Effect.flatMap(Effect.all([Clock.currentTimeMillis, TimedRole]), ([start, role]) =>
-    Effect.onExit(effect, (exit) =>
-      Effect.flatMap(Clock.currentTimeMillis, (end) =>
-        events.publish(timed(end - start, Exit.isFailure(exit), role))
+    Effect.andThen(
+      began === undefined ? Effect.void : events.publish(began(role)),
+      Effect.onExit(effect, (exit) =>
+        Effect.flatMap(Clock.currentTimeMillis, (end) =>
+          events.publish(timed(end - start, Exit.isFailure(exit), role))
+        )
       )
     )
   )
@@ -239,7 +247,7 @@ const tracedEffect = <A, E, R>(
           ...promptContent(content, [Message.make({ role: "User", content: prompt })])
         }
       },
-      timeEffect(events, effect, timed).pipe(
+      timeEffect(events, effect, timed, () => Began.make({ kind: "model", label: role })).pipe(
         Effect.onExit((exit) => {
           const known = Exit.isSuccess(exit)
             ? usageOf(exit.value)
@@ -282,6 +290,7 @@ const timedStream = <E>(
       // The call's LLM span (ADR 0026), parented to the nearest kind span and
       // ended when the stream does; each harness tool call is a TOOL child,
       // opened on `tool_use` and closed on `tool_result`.
+      yield* events.publish(Began.make({ kind: "model", label: role }))
       const parent = yield* currentKindSpan
       const span = yield* Effect.makeSpan(role, {
         kind: "client",
@@ -488,12 +497,16 @@ export const timedSeat = (
 export const timedJudgment = (judgment: JudgmentShape, events: FlowEventsShape): JudgmentShape => ({
   ...judgment,
   judge: (input) =>
-    timeEffect(events, judgment.judge(input), (ms, failed, role) =>
-      Timed.make({
-        kind: "model",
-        label: role ?? "judgment",
-        ms,
-        ...(failed ? { failed: true } : {})
-      })
+    timeEffect(
+      events,
+      judgment.judge(input),
+      (ms, failed, role) =>
+        Timed.make({
+          kind: "model",
+          label: role ?? "judgment",
+          ms,
+          ...(failed ? { failed: true } : {})
+        }),
+      (role) => Began.make({ kind: "model", label: role ?? "judgment" })
     )
 })