@llm4ts/flow 2.18.0 → 2.20.0

package/src/FlowEvents.ts

@@ -181,6 +181,106 @@ export class BlackboardRun extends Schema.TaggedClass<BlackboardRun>()("Blackboa
   result: RunResult
 }) {}
 
+/** One rubric dimension of a story verdict: its score out of `max`. */
+export const JudgedDimension = Schema.Struct({
+  id: Schema.String,
+  score: Schema.Number,
+  max: Schema.Number
+})
+export type JudgedDimension = typeof JudgedDimension.Type
+
+/** The story judge ruled on a story's branch (ADR 0022): one event per judge round. */
+export class StoryJudged extends Schema.TaggedClass<StoryJudged>()("StoryJudged", {
+  lane: Schema.String,
+  round: Schema.Int,
+  cleared: Schema.Boolean,
+  /** Issues the coder gets back when it is not cleared. */
+  issues: Schema.Int,
+  /** The rubric's scores, when the judge reports them. */
+  dimensions: Schema.Array(JudgedDimension)
+}) {}
+
+/**
+ * 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.
+ */
+export class ExecutorLeased extends Schema.TaggedClass<ExecutorLeased>()("ExecutorLeased", {
+  executor: Schema.String,
+  role: Schema.String,
+  label: Schema.optionalKey(Schema.String),
+  /** Took the role on its own context's coder slot: nobody independent could. */
+  borrowed: Schema.optionalKey(Schema.Boolean)
+}) {}
+
+export class ExecutorReleased extends Schema.TaggedClass<ExecutorReleased>()("ExecutorReleased", {
+  executor: Schema.String,
+  role: Schema.String,
+  label: Schema.optionalKey(Schema.String)
+}) {}
+
+export class ExecutorExcluded extends Schema.TaggedClass<ExecutorExcluded>()("ExecutorExcluded", {
+  executor: Schema.String,
+  /** How long and why, as the roster describes it ("for this run: not logged in"). */
+  reason: Schema.String
+}) {}
+
+export class ExecutorResumed extends Schema.TaggedClass<ExecutorResumed>()("ExecutorResumed", {
+  executor: Schema.String,
+  /** `expired`: its exclusion ran out; `health`: its engine answers again; `resumed`: by hand. */
+  why: Schema.Literals(["expired", "health", "resumed"])
+}) {}
+
+export class ExecutorHandedOver extends Schema.TaggedClass<ExecutorHandedOver>()(
+  "ExecutorHandedOver",
+  {
+    from: Schema.String,
+    role: Schema.String,
+    label: Schema.optionalKey(Schema.String),
+    reason: Schema.String,
+    /** `call`: one call moves to another executor; `coder`: a context's coder changes hands. */
+    scope: Schema.Literals(["call", "coder"])
+  }
+) {}
+
+export type RosterEvent =
+  | ExecutorLeased
+  | ExecutorReleased
+  | ExecutorExcluded
+  | ExecutorResumed
+  | ExecutorHandedOver
+
+const resumedWords: Readonly<Record<ExecutorResumed["why"], string>> = {
+  expired: "back in the round",
+  health: "answers its health check again; back in the round",
+  resumed: "resumed"
+}
+
+/**
+ * The line the classic terminal shows for a roster event — the same words
+ * the roster used to publish as `Info` — or `undefined` for one it does not
+ * show (a release) and for any other event.
+ */
+export const rosterEventMessage = (event: FlowEvent): string | undefined => {
+  const forLabel = (label: string | undefined): string =>
+    label === undefined ? "" : ` for ${label}`
+  switch (event._tag) {
+    case "ExecutorLeased":
+      return event.borrowed === true
+        ? `roster: ${event.executor} takes ${event.role}${forLabel(event.label)} on its own coder's slot — not independent (no other executor can take ${event.role})`
+        : `roster: ${event.executor} takes ${event.role}${forLabel(event.label)}`
+    case "ExecutorExcluded":
+      return `roster: ${event.executor} out of the round ${event.reason}`
+    case "ExecutorResumed":
+      return `roster: ${event.executor} ${resumedWords[event.why]}`
+    case "ExecutorHandedOver":
+      return event.scope === "coder"
+        ? `roster: ${event.label ?? "the run"}: handing the coder over from ${event.from} (${event.reason})`
+        : `roster: ${event.role}${forLabel(event.label)} moves off ${event.from} (${event.reason})`
+    default:
+      return undefined
+  }
+}
+
 export const FlowEvent = Schema.Union([
   JudgmentObserved,
   BlackboardRun,
@@ -197,7 +297,13 @@ export const FlowEvent = Schema.Union([
   CapabilityUsedEvent,
   CapabilityDeniedEvent,
   CapabilityUnenforceable,
-  Declassified
+  Declassified,
+  ExecutorLeased,
+  ExecutorReleased,
+  ExecutorExcluded,
+  ExecutorResumed,
+  ExecutorHandedOver,
+  StoryJudged
 ])
 export type FlowEvent = typeof FlowEvent.Type
 

package/src/FlowRecorder.ts

@@ -20,11 +20,17 @@ export class TraceLine extends Schema.Class<TraceLine>("TraceLine")({
   fields: Schema.Record(Schema.String, Schema.Json)
 }) {}
 
+/** How a run ended, as its trace's last line says (ADR 0022). */
+export const RunOutcome = Schema.Literals(["completed", "failed", "interrupted"])
+export type RunOutcome = typeof RunOutcome.Type
+
 export interface FlowRecorderShape extends StreamRecorder {
   readonly runId: string
   readonly tracePath: string
   readonly record: (event: FlowEvent) => Effect.Effect<void>
   readonly consume: (hub: FlowEventHub) => Effect.Effect<void, never, Scope.Scope>
+  /** Appends the `RunEnded` line: a reader knows the run is over, not stalled. */
+  readonly end: (outcome: RunOutcome) => Effect.Effect<void>
   /** Waits for this recorder to catch up; `false` means it gave up first. */
   readonly awaitDrained: (hub: FlowEventHub, timeout?: Duration.Input) => Effect.Effect<boolean>
 }
@@ -104,6 +110,7 @@ export const makeFlowRecorder = Effect.fn("@llm4ts/flow/FlowRecorder.make")(func
           Effect.asVoid
         )
       }),
+    end: (outcome) => append("RunEnded", { outcome }),
     awaitDrained: (hub, timeout) => awaitConsumed(hub, consumed, timeout)
   }
   return recorder

package/src/Landing.ts

@@ -15,7 +15,7 @@ import { statusPaths } from "./GitTool.ts"
 import { loadVersioned, saveVersioned, type PlainFileStoreShape } from "./Persistence.ts"
 import type { ReviewResult } from "./Review.ts"
 import { StoryState, StoryStateVersion } from "./Stories.ts"
-import type { StoryPlan } from "./StoryPlan.ts"
+import type { Story, StoryPlan } from "./StoryPlan.ts"
 
 const join = (root: string, path: string): string =>
   `${root.replace(/[\\/]+$/, "")}/${path.replace(/^[\\/]+/, "")}`
@@ -49,6 +49,11 @@ export interface LandOptions {
   readonly maxRounds?: number
   /** Keep the story worktrees and branches after landing. Default false: they go. */
   readonly keepWorktrees?: boolean
+  /**
+   * The epic's refine rounds (ADR 0021), each with its own plan and state
+   * folder: they must be merged too, and their worktrees go with the plan's.
+   */
+  readonly rounds?: ReadonlyArray<{ readonly plan: StoryPlan; readonly stateDir: string }>
 }
 
 export interface LandReport {
@@ -88,11 +93,15 @@ export const landEpic = Effect.fn("@llm4ts/flow/Landing.land")(function* (
   const failed = (reason: string) => LandingFailed.make({ epicBranch, target, reason })
 
   // 1. Only a finished epic lands.
+  // The plan's stories, then each round's, every one against its own state folder.
+  const tracked = [{ plan, stateDir: options.stateDir }, ...(options.rounds ?? [])].flatMap(
+    (part) => part.plan.stories.map((story) => ({ id: story.id, stateDir: part.stateDir }))
+  )
   const unmerged: Array<string> = []
-  for (const story of plan.stories) {
+  for (const story of tracked) {
     const state = yield* loadVersioned(
       files,
-      join(options.stateDir, `stories/${story.id}.json`),
+      join(story.stateDir, `stories/${story.id}.json`),
       StoryStateVersion,
       StoryState
     )
@@ -133,7 +142,16 @@ export const landEpic = Effect.fn("@llm4ts/flow/Landing.land")(function* (
     events,
     agent: "coder"
   })
-  const stories = plan.stories.map((story) => `- ${story.id}: ${story.provides.join("; ")}`)
+  const provided = (story: Story): string => `- ${story.id}: ${story.provides.join("; ")}`
+  // A round changed what the plan's stories built (it may have removed some of
+  // it): the coder must not resolve a conflict back to the older intent.
+  const stories = [
+    ...plan.stories.map(provided),
+    ...(options.rounds ?? []).flatMap((round, index) => [
+      `and later changed on feedback (refine round ${index + 1}, which wins over the above):`,
+      ...round.plan.stories.map(provided)
+    ])
+  ]
   let rounds = 0
   while (true) {
     const withMarkers: Array<string> = []
@@ -211,10 +229,10 @@ export const landEpic = Effect.fn("@llm4ts/flow/Landing.land")(function* (
   let deletedBranches = 0
   if (options.keepWorktrees !== true) {
     const kept: Array<string> = []
-    for (const story of plan.stories) {
+    for (const story of tracked) {
       const state = yield* loadVersioned(
         files,
-        join(options.stateDir, `stories/${story.id}.json`),
+        join(story.stateDir, `stories/${story.id}.json`),
         StoryStateVersion,
         StoryState
       )

package/src/RefineRound.ts

@@ -0,0 +1,227 @@
+// Refine rounds (ADR 0021): follow-up stories on a finished epic, planned
+// from feedback. A round is its own story plan on the epic's branch, so the
+// executor and the ownership rule are the ones a plan has. Pure: reading the
+// round folders and asking the planner belong to the flow.
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { JsonSchema } from "@llm4ts/core/Models"
+import { Story, StoryPlan } from "./StoryPlan.ts"
+
+/** A feedback item the planner left out, with the reason or the question to answer. */
+export class NotPlanned extends Schema.Class<NotPlanned>("NotPlanned")({
+  item: Schema.String,
+  reason: Schema.String
+}) {}
+
+/** What the planner returns for a round: the stories it can place, and the rest. */
+export class RefineProposal extends Schema.Class<RefineProposal>("RefineProposal")({
+  stories: Schema.Array(Story),
+  notPlanned: Schema.Array(NotPlanned).pipe(
+    Schema.withConstructorDefault(Effect.succeed([])),
+    Schema.withDecodingDefaultKey(Effect.succeed([]))
+  )
+}) {}
+
+const strings: JsonSchema = { type: "array", items: { type: "string" } }
+
+export const refineProposalJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    stories: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          title: { type: "string" },
+          description: { type: "string" },
+          dependsOn: strings,
+          owned: strings,
+          sharedReadOnly: strings,
+          provides: strings
+        },
+        required: ["id", "title", "description", "dependsOn", "owned", "sharedReadOnly", "provides"]
+      }
+    },
+    notPlanned: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: { item: { type: "string" }, reason: { type: "string" } },
+        required: ["item", "reason"]
+      }
+    }
+  },
+  required: ["stories", "notPlanned"]
+}
+
+/** Round stories are `r<n>-…`: unique across the epic, whatever the planner called them. */
+export const roundPrefix = (round: number): string => `r${round}-`
+
+/**
+ * The round's story plan from a proposal. Ids get the round's prefix (once),
+ * dependencies follow, and a dependency on a story merged before the round
+ * (`earlier`) is dropped: a round only starts once those are in the branch.
+ */
+export const assembleRound = (inputs: {
+  readonly epicId: string
+  readonly round: number
+  readonly feedback: string
+  readonly proposal: RefineProposal
+  /** Ids of every story of the epic's plan and of the earlier rounds. */
+  readonly earlier: ReadonlyArray<string>
+}): StoryPlan => {
+  const prefix = roundPrefix(inputs.round)
+  const prefixed = (id: string): string => (id.startsWith(prefix) ? id : `${prefix}${id}`)
+  const own = new Set(inputs.proposal.stories.map((story) => story.id))
+  const earlier = new Set(inputs.earlier)
+  return StoryPlan.make({
+    epicId: inputs.epicId,
+    epic: inputs.feedback,
+    stories: inputs.proposal.stories.map((story) =>
+      Story.make({
+        ...story,
+        id: prefixed(story.id),
+        dependsOn: story.dependsOn
+          .filter((dependency) => own.has(dependency) || !earlier.has(dependency))
+          .map(prefixed)
+      })
+    )
+  })
+}
+
+/** What to do about a round whose plan cannot be read: a plan alone is never deleted. */
+export const roundRepair = (round: number): string =>
+  `fix the plan, or delete the folder rounds/${round} and every later round`
+
+/** A round as the run decision sees it. */
+export interface RoundProgress {
+  readonly round: number
+  readonly stories: number
+  readonly merged: number
+  /** Why its plan cannot be read, naming the file. */
+  readonly unreadable?: string
+}
+
+export type RunAction =
+  | { readonly _tag: "RunPlan" }
+  | { readonly _tag: "RunRound"; readonly round: number }
+  | { readonly _tag: "PlanRound"; readonly round: number }
+  | { readonly _tag: "Land" }
+  | { readonly _tag: "Refused"; readonly reason: string }
+  | { readonly _tag: "Usage"; readonly message: string }
+
+export interface RunInputs {
+  /** The epic has a story plan. */
+  readonly planned: boolean
+  readonly stories: number
+  readonly merged: number
+  /** The branch the epic landed on, once it has. */
+  readonly landed: string | undefined
+  readonly rounds: ReadonlyArray<RoundProgress>
+  /** `--refine` was given. */
+  readonly refine: boolean
+  /** The text given with `--refine`. */
+  readonly feedback: string
+  /** `--land` was given. */
+  readonly land: boolean
+}
+
+/**
+ * What a run of the epic does: its plan's stories, the open round, a new
+ * round, or the landing. A round starts only when everything before it is
+ * merged, and an open round is finished before another is planned.
+ */
+export const runAction = (inputs: RunInputs): RunAction => {
+  if (inputs.land) {
+    // Landing with feedback in hand would drop the feedback for good.
+    return inputs.refine && inputs.feedback.trim().length > 0
+      ? {
+          _tag: "Usage",
+          message:
+            "--refine with feedback and --land do not go together: run the round first, then land"
+        }
+      : { _tag: "Land" }
+  }
+  const planOpen = inputs.merged < inputs.stories
+  const unreadable = inputs.rounds.find((round) => round.unreadable !== undefined)
+  const open = inputs.rounds.find((round) => round.merged < round.stories)
+  const broken = (round: RoundProgress): RunAction => ({
+    _tag: "Refused",
+    reason: `round ${round.round}'s plan cannot be read (${round.unreadable ?? ""}); ${roundRepair(round.round)}`
+  })
+  if (!inputs.refine) {
+    if (planOpen) {
+      return { _tag: "RunPlan" }
+    }
+    if (unreadable !== undefined) {
+      return broken(unreadable)
+    }
+    return open === undefined ? { _tag: "RunPlan" } : { _tag: "RunRound", round: open.round }
+  }
+  if (!inputs.planned) {
+    return { _tag: "Refused", reason: "it has no story plan yet: run the epic first" }
+  }
+  if (inputs.landed !== undefined) {
+    return {
+      _tag: "Refused",
+      reason: `it has landed on ${inputs.landed}; give the changes as a new epic`
+    }
+  }
+  if (unreadable !== undefined) {
+    return broken(unreadable)
+  }
+  if (planOpen) {
+    return {
+      _tag: "Refused",
+      reason: `${inputs.merged} of ${inputs.stories} stories merged: rerun the epic until every story merges`
+    }
+  }
+  const feedback = inputs.feedback.trim()
+  if (open !== undefined) {
+    return feedback.length === 0
+      ? { _tag: "RunRound", round: open.round }
+      : {
+          _tag: "Refused",
+          reason: `round ${open.round} is open (${open.merged} of ${open.stories} stories merged): rerun without --refine text to finish it, or edit its plan`
+        }
+  }
+  if (feedback.length === 0) {
+    return { _tag: "Usage", message: "--refine needs the feedback to plan a round from" }
+  }
+  return { _tag: "PlanRound", round: inputs.rounds.length + 1 }
+}
+
+const oneLine = (text: string): string => text.replace(/\s+/g, " ").trim()
+
+/** `not-planned.md`: one line per item left out, for the person and for the next round's planner. */
+export const renderNotPlanned = (round: number, items: ReadonlyArray<NotPlanned>): string =>
+  [
+    `# Not planned in round ${round}`,
+    "",
+    ...(items.length === 0
+      ? ["Every feedback item was planned."]
+      : items.map((entry) => `- **${oneLine(entry.item)}** — ${oneLine(entry.reason)}`)),
+    ""
+  ].join("\n")
+
+export const countNotPlanned = (markdown: string): number =>
+  markdown.split("\n").filter((line) => line.startsWith("- **")).length
+
+/** An earlier story as a round's planner is shown it: what was built, and where. */
+export interface EarlierStory {
+  readonly id: string
+  readonly title: string
+  readonly owned: ReadonlyArray<string>
+  readonly provides: ReadonlyArray<string>
+}
+
+export const earlierStories = (plans: ReadonlyArray<StoryPlan>): ReadonlyArray<EarlierStory> =>
+  plans.flatMap((plan) =>
+    plan.stories.map((story) => ({
+      id: story.id,
+      title: story.title,
+      owned: story.owned,
+      provides: story.provides
+    }))
+  )

package/src/Roster.ts

@@ -14,7 +14,14 @@ import type * as Scope from "effect/Scope"
 import * as Semaphore from "effect/Semaphore"
 import type { LlmError } from "@llm4ts/core/Errors"
 import { RosterExhausted, type FlowError } from "./FlowError.ts"
-import { Info, type FlowEventsShape } from "./FlowEvents.ts"
+import {
+  ExecutorExcluded,
+  ExecutorLeased,
+  ExecutorReleased,
+  ExecutorResumed,
+  Info,
+  type FlowEventsShape
+} from "./FlowEvents.ts"
 import { loadVersioned, saveVersioned, type PlainFileStoreShape } from "./Persistence.ts"
 import { isOutage } from "./TransientRetry.ts"
 
@@ -541,11 +548,22 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
       )
       .pipe(Effect.andThen(signal))
 
-  const leaseOf = (spec: ExecutorSpec, role: Role): Effect.Effect<Lease, never, Scope.Scope> =>
+  const leaseOf = (
+    spec: ExecutorSpec,
+    role: Role,
+    label: string | undefined
+  ): Effect.Effect<Lease, never, Scope.Scope> =>
     Effect.gen(function* () {
+      const labelled = label === undefined ? {} : { label }
+      yield* events.publish(ExecutorLeased.make({ executor: spec.id, role, ...labelled }))
       const done = yield* Ref.make(false)
       const free = Effect.flatMap(Ref.getAndSet(done, true), (was) =>
-        was ? Effect.void : release(spec, role)
+        was
+          ? Effect.void
+          : Effect.andThen(
+              release(spec, role),
+              events.publish(ExecutorReleased.make({ executor: spec.id, role, ...labelled }))
+            )
       )
       yield* Effect.addFinalizer(() => free)
       return { executor: spec, role, release: free }
@@ -577,7 +595,9 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         })
       )
       if (back.length > 0) {
-        yield* say(`${back.join(", ")} back in the round`)
+        yield* Effect.forEach(back, (id) =>
+          events.publish(ExecutorResumed.make({ executor: id, why: "expired" }))
+        )
         yield* persist
       }
       return spec
@@ -638,7 +658,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         })
       )
       if (up) {
-        yield* say(`${exclusion.id} answers its health check again; back in the round`)
+        yield* events.publish(ExecutorResumed.make({ executor: exclusion.id, why: "health" }))
         yield* persist
         yield* signal
       }
@@ -693,10 +713,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
       while (true) {
         const spec = yield* attempt(role, leaseOptions)
         if (spec !== undefined) {
-          yield* say(
-            `${spec.id} takes ${role}${leaseOptions.label === undefined ? "" : ` for ${leaseOptions.label}`}`
-          )
-          return yield* leaseOf(spec, role)
+          return yield* leaseOf(spec, role, leaseOptions.label)
         }
         if (!(yield* canEverServe(role, avoid))) {
           const reasons = yield* lock.withPermit(
@@ -723,10 +740,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         yield* probeDue
         const recovered = yield* attempt(role, leaseOptions)
         if (recovered !== undefined) {
-          yield* say(
-            `${recovered.id} takes ${role}${leaseOptions.label === undefined ? "" : ` for ${leaseOptions.label}`}`
-          )
-          return yield* leaseOf(recovered, role)
+          return yield* leaseOf(recovered, role, leaseOptions.label)
         }
         const probing = yield* lock.withPermit(
           Effect.sync(() =>
@@ -744,7 +758,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
     leaseOptions: LeaseOptions = {}
   ): Effect.Effect<Lease | undefined, never, Scope.Scope> =>
     Effect.flatMap(attempt(role, leaseOptions), (spec) =>
-      spec === undefined ? Effect.succeed(undefined) : leaseOf(spec, role)
+      spec === undefined ? Effect.succeed(undefined) : leaseOf(spec, role, leaseOptions.label)
     )
 
   const exclude = (exclusion: Exclusion): Effect.Effect<void> =>
@@ -753,7 +767,9 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
         return
       }
       yield* lock.withPermit(Effect.sync(() => exclusions.set(exclusion.id, exclusion)))
-      yield* say(`${exclusion.id} out of the round ${describeExclusion(exclusion)}`)
+      yield* events.publish(
+        ExecutorExcluded.make({ executor: exclusion.id, reason: describeExclusion(exclusion) })
+      )
       yield* persist
       yield* signal
     })
@@ -790,7 +806,7 @@ export const makeRoster = Effect.fn("@llm4ts/flow/Roster.make")(function* (
     Effect.gen(function* () {
       const removed = yield* lock.withPermit(Effect.sync(() => exclusions.delete(id)))
       if (removed) {
-        yield* say(`${id} resumed`)
+        yield* events.publish(ExecutorResumed.make({ executor: id, why: "resumed" }))
         yield* persist
         yield* signal
       }

package/src/RosterSeats.ts

@@ -12,7 +12,7 @@ import { ConfigError, type LlmError } from "@llm4ts/core/Errors"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
 import { Message, type ConnectorCapabilities, type LlmChunk } from "@llm4ts/core/Models"
 import { describeFlowError, type FlowError } from "./FlowError.ts"
-import { Info, type FlowEventsShape } from "./FlowEvents.ts"
+import { ExecutorHandedOver, ExecutorLeased, type FlowEventsShape } from "./FlowEvents.ts"
 import {
   describeExclusion,
   hasRole,
@@ -51,9 +51,6 @@ export interface RosterView {
 const asLlmError = (error: FlowError): LlmError =>
   ConfigError.make({ message: describeFlowError(error) })
 
-const say = (events: FlowEventsShape, message: string): Effect.Effect<void> =>
-  events.publish(Info.make({ message: `roster: ${message}` }))
-
 /** Shared plumbing: every service method as "run this on some seat". */
 interface SeatRunner {
   readonly run: <A, R>(
@@ -133,9 +130,13 @@ export const rosterSeat = (
       if (avoid.length > 0 && !(yield* roster.canEverServe(role, avoid))) {
         const borrowed = options.borrow === undefined ? undefined : yield* options.borrow
         if (borrowed !== undefined && hasRole(borrowed, role)) {
-          yield* say(
-            options.events,
-            `${borrowed.id} takes ${role}${options.label === undefined ? "" : ` for ${options.label}`} on its own coder's slot — not independent (no other executor can take ${role})`
+          yield* options.events.publish(
+            ExecutorLeased.make({
+              executor: borrowed.id,
+              role,
+              ...(options.label === undefined ? {} : { label: options.label }),
+              borrowed: true
+            })
           )
           return borrowed
         }
@@ -167,9 +168,14 @@ export const rosterSeat = (
       const avoid = options.avoid === undefined ? [] : yield* options.avoid
       const other = yield* roster.canEverServe(role, [...avoid, executor.id])
       if (other) {
-        yield* say(
-          options.events,
-          `${role}${options.label === undefined ? "" : ` for ${options.label}`} moves off ${executor.id} (${describeExclusion(exclusion)})`
+        yield* options.events.publish(
+          ExecutorHandedOver.make({
+            from: executor.id,
+            role,
+            ...(options.label === undefined ? {} : { label: options.label }),
+            reason: describeExclusion(exclusion),
+            scope: "call"
+          })
         )
       }
       return other
@@ -318,9 +324,14 @@ export const makeHeldCoder = Effect.fn("@llm4ts/flow/RosterSeats.heldCoder")(fun
       yield* Ref.set(prefer, undefined)
       yield* held.lease.release
       yield* Ref.set(current, undefined)
-      yield* say(
-        options.events,
-        `${options.label ?? workDir}: handing the coder over from ${held.lease.executor.id} (${describeExclusion(exclusion)})`
+      yield* options.events.publish(
+        ExecutorHandedOver.make({
+          from: held.lease.executor.id,
+          role: "coder",
+          label: options.label ?? workDir,
+          reason: describeExclusion(exclusion),
+          scope: "coder"
+        })
       )
       return takeoverNote(held.lease.executor.id, exclusion.reason)
     })

package/src/Stories.ts

@@ -28,7 +28,7 @@ import {
   StoryFailed,
   type FlowError
 } from "./FlowError.ts"
-import { Info, withLane, type FlowEventsShape } from "./FlowEvents.ts"
+import { Info, JudgedDimension, StoryJudged, withLane, type FlowEventsShape } from "./FlowEvents.ts"
 import { statusPaths, type GitToolShape } from "./GitTool.ts"
 import {
   checkPerimeter,
@@ -70,6 +70,11 @@ const join = (root: string, path: string): string =>
 // ---- Story seats ----------------------------------------------------------
 
 /** A flow context rooted in a story's worktree, plus that story's own usage totals. */
+/** A story judge's review with the rubric's scores; a plain `ReviewResult` has none. */
+export class StoryVerdict extends ReviewResult.extend<StoryVerdict>("StoryVerdict")({
+  dimensions: Schema.Array(JudgedDimension)
+}) {}
+
 export interface StorySeats {
   readonly context: FlowContextShape
   /** Running usage of this story's seats — estimates where the backend reports none. */
@@ -986,6 +991,15 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
           return yield* failed(story, "the story branch has no changes against the epic branch")
         }
         const verdict = yield* judge(story, diff, watchedSeats)
+        yield* laneOf(story).publish(
+          StoryJudged.make({
+            lane: story.id,
+            round,
+            cleared: verdict.isClean,
+            issues: verdict.issues.length,
+            dimensions: verdict instanceof StoryVerdict ? verdict.dimensions : []
+          })
+        )
         if (verdict.isClean) {
           judgeNote = `judge cleared (round ${round})`
           break