@llm4ts/flow 2.7.2 → 2.9.0

package/src/Stories.ts

@@ -5,6 +5,7 @@
 // target's gates run on the epic branch after every merge. Scheduling,
 // gating, resume and failure policy live here; seats come from `contextFor`.
 import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
 import * as Queue from "effect/Queue"
 import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
@@ -17,30 +18,51 @@ 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 { describeFlowError, MissingDependency, StoryFailed, type FlowError } from "./FlowError.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 { enforcePerimeter } from "./Perimeter.ts"
+import { statusPaths, type GitToolShape } from "./GitTool.ts"
+import {
+  checkPerimeter,
+  enforcePerimeter,
+  isWithinPerimeter,
+  perimeterGate,
+  strayTasks,
+  type PerimeterCheck
+} from "./Perimeter.ts"
 import {
   loadVersioned,
   makePlanStore,
   saveVersioned,
   type PlainFileStoreShape
 } from "./Persistence.ts"
-import type { Plan } from "./Plan.ts"
+import { Plan } from "./Plan.ts"
 import { stage } from "./PlanExecution.ts"
 import { planFrom } from "./Planner.ts"
-import type { ReviewResult } from "./Review.ts"
+import { ReviewResult } from "./Review.ts"
 import type { Reviewer } from "./Reviewer.ts"
 import {
   dependentsOf,
+  ownerOf,
+  pathsNamedIn,
   readyStories,
+  relationOf,
   storyHash,
   topologicalWaves,
   validateStoryPlan,
   type Story,
-  type StoryPlan
+  type StoryPlan,
+  type StoryRelation
 } from "./StoryPlan.ts"
+import { isOutageMessage } from "./TransientRetry.ts"
 
 const join = (root: string, path: string): string =>
   `${root.replace(/[\\/]+$/, "")}/${path.replace(/^[\\/]+/, "")}`
@@ -68,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
@@ -85,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)
@@ -138,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")
 }
@@ -172,8 +219,43 @@ export const blockedOnIn = (text: string): string | undefined => {
 const bullets = (items: ReadonlyArray<string>): string =>
   items.length === 0 ? "- (none)" : items.map((item) => `- ${item}`).join("\n")
 
+/** Where a story runs, which is what lets its rules name the other stories and checkouts. */
+export interface StoryWhereabouts {
+  readonly plan: StoryPlan
+  /** The story's own worktree — the coder's working directory. */
+  readonly worktree: string
+  /** The epic branch's checkout, which no coder may touch. */
+  readonly epicCheckout: string
+}
+
+const relationNotes: Readonly<Record<Exclude<StoryRelation, "self">, string>> = {
+  dependency: "merged into the epic before you started — it is in your working tree; read it",
+  dependent:
+    "built AFTER you, on top of your work — leave it alone (wiring your work in is that story's job)",
+  parallel: "built at the same time by another coder — leave it alone"
+}
+
+const whereaboutsRules = (story: Story, where: StoryWhereabouts): ReadonlyArray<string> => {
+  const others = where.plan.stories
+    .filter((other) => other.id !== story.id)
+    .map((other) => {
+      const relation = relationOf(where.plan, story, other)
+      const note = relation === "self" ? "" : relationNotes[relation]
+      return `${other.owned.join(", ")} — story ${other.id}: ${note}`
+    })
+  return [
+    "",
+    `Your working directory is ${where.worktree}. Run every command there. Never cd into, read`,
+    `from, or write to any other checkout — above all not ${where.epicCheckout}, the epic`,
+    "branch's checkout: a change there breaks every other story's merge.",
+    "",
+    "Paths other stories own — never create or change them, and none of them is a reason to stop:",
+    bullets(others)
+  ]
+}
+
 /** The hard rules every story coder receives; the perimeter check enforces them afterwards. */
-export const perimeterRules = (story: Story): string =>
+export const perimeterRules = (story: Story, where?: StoryWhereabouts): string =>
   [
     `You are implementing ONE story of a larger epic: "${story.title}" (id: ${story.id}).`,
     "",
@@ -185,6 +267,7 @@ export const perimeterRules = (story: Story): string =>
     "",
     "What this story must provide for other stories:",
     bullets(story.provides),
+    ...(where === undefined ? [] : whereaboutsRules(story, where)),
     "",
     "Rules:",
     "- Do not touch any path outside the owned list; a change there fails the story.",
@@ -204,7 +287,10 @@ export const storyTaskPlanInstructions = (story: Story): string =>
   [
     "You are planning the implementation of ONE story inside a larger epic. Break the story",
     "into an ordered list of small, independently verifiable tasks, each described by its",
-    "observable outcome. Every task must stay inside the story's owned paths.",
+    "observable outcome. Every task must stay inside the story's owned paths:",
+    bullets(story.owned),
+    "Never plan a task that creates or changes anything outside them — registering or wiring",
+    "the story in elsewhere (the app's composition point, a shared kit file) is another story's job.",
     `Use exactly this epicId: "${story.id}".`,
     'Respond only with JSON: {"epicId":"' + story.id + '","tasks":',
     '[{"title":"...","description":"...","completed":false}]}'
@@ -218,6 +304,100 @@ export const defaultPlanTasks = (
 ): Effect.Effect<Plan, FlowError> =>
   planFrom(seats.context.coder, prompt, storyTaskPlanInstructions(story))
 
+/**
+ * Asks the planner again, once, when its tasks name paths outside the story;
+ * tasks that still name ANOTHER story's paths are then dropped (that work is
+ * planned elsewhere) and any remaining stray is left to the perimeter gate.
+ */
+export const planWithinPerimeter = (
+  plan: StoryPlan,
+  story: Story,
+  planTasks: (prompt: string) => Effect.Effect<Plan, FlowError>,
+  prompt: string,
+  events: FlowContextShape["events"]
+): Effect.Effect<Plan, FlowError> =>
+  Effect.gen(function* () {
+    const first = yield* planTasks(prompt)
+    const strays = strayTasks(plan, story, first.tasks)
+    if (strays.length === 0) {
+      return first
+    }
+    const describe = strays.map((stray) => `- "${stray.task.title}": ${stray.paths.join(", ")}`)
+    yield* events.publish(
+      Info.make({
+        message: `story ${story.id}: ${strays.length} planned task(s) name paths outside the story; re-planning:\n${describe.join("\n")}`
+      })
+    )
+    const second = yield* planTasks(
+      [
+        prompt,
+        "",
+        "Your previous task list named paths outside this story's owned paths:",
+        ...describe,
+        "Plan again: only work inside the owned paths. Work on any other path is not this story's."
+      ].join("\n")
+    )
+    const remaining = strayTasks(plan, story, second.tasks)
+    const foreign = new Set(remaining.filter((stray) => stray.foreign).map((stray) => stray.task))
+    const kept = second.tasks.filter((task) => !foreign.has(task))
+    if (remaining.length > 0) {
+      yield* events.publish(
+        Info.make({
+          message:
+            `story ${story.id}: the re-plan still names paths outside the story` +
+            (foreign.size > 0
+              ? `; dropped ${foreign.size} task(s) that belong to other stories`
+              : "")
+        })
+      )
+    }
+    return kept.length === 0 ? second : Plan.make({ ...second, tasks: kept })
+  })
+
+/**
+ * Why a BLOCKED_ON claim is wrong, when the plan alone can tell: the named
+ * path is the story's own, a dependency's (already merged into the worktree),
+ * or a dependent's (built later on top of this story). Undefined when the
+ * plan cannot settle it — a path no story owns, or a parallel story's.
+ */
+export const blockedRebuttal = (
+  plan: StoryPlan,
+  story: Story,
+  need: string
+): string | undefined => {
+  for (const path of pathsNamedIn(plan, need)) {
+    const owner = ownerOf(plan, path)
+    if (owner === undefined) {
+      continue
+    }
+    switch (relationOf(plan, story, owner)) {
+      case "self":
+        return `${path} is under your own owned paths: building it is your job, not another story's.`
+      case "dependent":
+        return (
+          `${path} belongs to story '${owner.id}', which runs AFTER you and builds on your work. ` +
+          "Leave it alone: it is neither missing nor a blocker for this story."
+        )
+      case "dependency":
+        return (
+          `${path} belongs to story '${owner.id}', merged into the epic branch before you started, ` +
+          `so it is already in your working tree: read it there. That story provides: ${owner.provides.join("; ")}.`
+        )
+      case "parallel":
+        continue
+    }
+  }
+  return undefined
+}
+
+/** A second opinion on a BLOCKED_ON claim the plan cannot settle. */
+export class BlockedVerdict extends Schema.Class<BlockedVerdict>("BlockedVerdict")({
+  /** True: the work is genuinely missing and owned by no dependency. */
+  real: Schema.Boolean,
+  /** Why — shown to the coder when the claim is rejected. */
+  reason: Schema.String
+}) {}
+
 // ---- BLOCKED_ON detection ---------------------------------------------------
 
 const watchStream = (
@@ -269,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
@@ -280,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). */
@@ -297,13 +484,46 @@ export interface StoriesOptions {
   readonly failFast?: boolean
   readonly reviewers?: ReadonlyArray<Reviewer>
   readonly maxRounds?: number
+  /**
+   * Second opinion on a BLOCKED_ON claim the plan cannot settle (a path no
+   * story owns, or a parallel story's). `real: false` sends the coder back
+   * once with the reason. Omit to accept every such claim.
+   */
+  readonly verifyBlocked?: (
+    story: Story,
+    need: string,
+    workDir: string,
+    seats: StorySeats
+  ) => Effect.Effect<BlockedVerdict, FlowError>
+  /**
+   * Waits until a serving engine that went down (`isOutageMessage`) is back;
+   * the story it interrupted is then retried once. Omit, or fail it, and the
+   * executor stops launching stories instead of failing each in turn.
+   */
+  readonly awaitRecovery?: (reason: string) => Effect.Effect<void, FlowError>
 }
 
+/**
+ * A failure that says nothing about the story: the serving engine went down,
+ * or the epic checkout was dirtied. Launching more stories would only fail
+ * them the same way.
+ */
+type Interruption = "outage" | "halt"
+
 interface Completion {
   readonly story: Story
   readonly outcome: StoryOutcome
+  readonly interruption?: Interruption
 }
 
+const combined = (first: ReviewResult, second: ReviewResult): ReviewResult =>
+  first.isClean && second.isClean
+    ? first
+    : ReviewResult.make({
+        issues: [...first.issues, ...second.issues],
+        summary: [first.summary, second.summary].filter((part) => part.length > 0).join("; ")
+      })
+
 const issueLines = (result: ReviewResult): string =>
   result.issues.map((issue) => `- ${issue.title}: ${issue.description}`).join("\n")
 
@@ -325,6 +545,24 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   const statePath = (story: Story): string => join(options.stateDir, `stories/${story.id}.json`)
   const planPath = (story: Story): string => join(options.stateDir, `stories/${story.id}.plan.md`)
 
+  /**
+   * The epic checkout must hold nothing uncommitted: every merge and epic
+   * gate runs there, and git refuses a merge that would overwrite a stray
+   * file. A dirty checkout means a coder escaped its worktree.
+   */
+  const epicCheckoutClean = (story?: Story): Effect.Effect<void, FlowError> =>
+    Effect.gen(function* () {
+      const paths = statusPaths(yield* context.git.status)
+      if (paths.length > 0) {
+        return yield* EpicCheckoutDirty.make({
+          checkout: context.workDir,
+          paths,
+          ...(story === undefined ? {} : { story: story.id })
+        })
+      }
+    })
+
+  yield* epicCheckoutClean()
   yield* stage(events, "epic branch", context.git.checkoutOrCreate(epicBranch))
 
   const waves = topologicalWaves(plan)
@@ -350,6 +588,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   const integrate = (story: Story, branch: string): Effect.Effect<void, FlowError> =>
     mergeLock.withPermit(
       Effect.gen(function* () {
+        yield* epicCheckoutClean(story)
         const checkpoint = yield* context.git.checkpoint
         yield* context.git.merge(branch, `${plan.epicId}: merge story ${story.id}`)
         const gate = yield* options.gates(context.workDir)
@@ -409,84 +648,272 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       return { state, alreadyMerged: false }
     }
     // Resume: the branch exists; the worktree may not (a worktree has a
-    // `.git` FILE at its root, which is how its presence is checked).
-    const marker = yield* files.read(join(stored.worktree, ".git"))
+    // `.git` FILE at its root, which is how its presence is checked). A
+    // worktree left under an older root moves to the current one, work and
+    // all, so every story of the epic runs under the same root.
+    let state = stored
+    if (stored.worktree !== worktree) {
+      if ((yield* files.read(join(stored.worktree, ".git"))) !== undefined) {
+        yield* context.git.moveWorktree(stored.worktree, worktree)
+        yield* events.publish(
+          Info.make({ message: `story ${story.id}: moved its worktree to ${worktree}` })
+        )
+      }
+      state = StoryState.make({ ...stored, worktree })
+      yield* saveVersioned(files, path, StoryStateVersion, StoryState, state)
+    }
+    const marker = yield* files.read(join(state.worktree, ".git"))
     if (marker === undefined) {
-      yield* context.git.addWorktree(stored.worktree, stored.branch)
+      yield* context.git.addWorktree(state.worktree, state.branch)
     }
-    yield* events.publish(Info.make({ message: `story ${story.id}: resuming ${stored.branch}` }))
-    return { state: stored, alreadyMerged: false }
+    yield* events.publish(Info.make({ message: `story ${story.id}: resuming ${state.branch}` }))
+    return { state, alreadyMerged: false }
   })
 
+  /**
+   * Brings a story branch up to date with the epic branch. A story that
+   * started before a dependency was re-merged (or that resumes after other
+   * stories merged) would otherwise build on, and be judged against, code
+   * the epic no longer has. Conflicting hunks take the epic's side: the epic
+   * holds only other stories' merged work, and those paths are theirs.
+   */
+  const catchUp = (story: Story, git: GitToolShape): Effect.Effect<void, FlowError> =>
+    Effect.gen(function* () {
+      if (yield* git.isAncestor(epicBranch, "HEAD")) {
+        return
+      }
+      if ((yield* git.uncommittedFiles).length > 0) {
+        yield* git.commitAll(`${story.id}: work in progress`)
+      }
+      yield* git.merge(epicBranch, `${story.id}: catch up with ${epicBranch}`, {
+        preferIncoming: true
+      })
+      yield* events.publish(
+        Info.make({ message: `story ${story.id}: caught up with ${epicBranch}` })
+      )
+    })
+
+  /** The perimeter over everything the branch changed, committed or not. */
+  const perimeterNow = (
+    story: Story,
+    git: GitToolShape
+  ): Effect.Effect<PerimeterCheck, FlowError> =>
+    Effect.gen(function* () {
+      const committed = yield* git.changedFilesVsBase(epicBranch)
+      const uncommitted = yield* git.uncommittedFiles
+      return checkPerimeter([...new Set([...committed, ...uncommitted])], story)
+    })
+
   /** Everything that happens inside a story's worktree: plan, implement, judge, perimeter. */
   const implementStory = Effect.fn("@llm4ts/flow/Stories.implementStory")(function* (
     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 ${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 = {
       ...seats.context,
       coder: watchForBlockedOn(seats.context.coder, blocked)
     }
+    const git = storyContext.git
     const watchedSeats: StorySeats = { ...seats, context: storyContext }
     const extra = options.system === undefined ? undefined : yield* options.system(story)
-    const system = [perimeterRules(story), extra]
+    const system = [
+      perimeterRules(story, { plan, worktree: state.worktree, epicCheckout: context.workDir }),
+      extra
+    ]
       .filter((part): part is string => part !== undefined && part.trim().length > 0)
       .join("\n\n")
     const prompt = storyPrompt(story)
-    const blockedOr = <A>(effect: Effect.Effect<A, FlowError>): Effect.Effect<A, FlowError> =>
-      effect.pipe(
-        Effect.catch((error) =>
-          Effect.flatMap(Ref.get(blocked), (need) =>
-            need === undefined
-              ? Effect.fail(error)
-              : Effect.fail(MissingDependency.make({ story: story.id, need }))
-          )
-        ),
-        Effect.tap(() =>
-          Effect.flatMap(Ref.get(blocked), (need) =>
-            need === undefined
-              ? Effect.void
-              : Effect.fail(MissingDependency.make({ story: story.id, need }))
-          )
-        )
+
+    // 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))
+    }
+
+    // The target's gates plus the perimeter: a stray path is a gate failure
+    // the task review loop hands back to the coder before anything commits.
+    const gates: Effect.Effect<ReviewResult, FlowError> = Effect.gen(function* () {
+      const target = yield* options.gates(state.worktree)
+      const changed = yield* perimeterNow(story, git)
+      return combined(target, perimeterGate([...changed.sharedReadOnly, ...changed.outside], story))
+    })
+
+    const coderTurn = (text: string): Effect.Effect<string, FlowError> =>
+      Effect.flatMap(makeChat(storyContext.coder, { system, events, agent: "coder" }), (chat) =>
+        chat.ask(text)
       )
 
-    yield* blockedOr(
-      implementPlanFlow(storyContext, {
-        store: makePlanStore(files),
-        planPath: planPath(story),
-        plan: (options.planTasks ?? defaultPlanTasks)(watchedSeats, story, prompt),
-        system,
-        chatPerTask: true,
-        checkoutBranch: false,
-        lint: options.gates(state.worktree),
-        // A story's final state is judged and gated downstream (judge round,
-        // perimeter check, epic gates), so a task the coder finds already
-        // satisfied — without saying the exact sentinel — must not sink the
-        // story: the option exists for pipelines shaped like this one.
-        noopTaskPolicy: "complete",
-        ...(options.reviewers === undefined ? {} : { reviewers: options.reviewers }),
-        ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds })
+    const commitGreen = (message: string, why: string): Effect.Effect<void, FlowError> =>
+      Effect.gen(function* () {
+        const regated = yield* gates
+        if (!regated.isClean) {
+          return yield* failed(story, `gates broke ${why}:\n${issueLines(regated)}`)
+        }
+        yield* git.commitAll(`${story.id}: ${message}`)
       })
-    )
+
+    /**
+     * Runs `effect`; a BLOCKED_ON the plan or the verifier refutes sends the
+     * coder back once with the reason, then `resume` runs. Any other claim —
+     * or a second one — ends the story as a typed MissingDependency.
+     */
+    const guarded = <A>(
+      effect: Effect.Effect<A, FlowError>,
+      resume: Effect.Effect<void, FlowError>
+    ): Effect.Effect<void, FlowError> =>
+      Effect.gen(function* () {
+        const exit = yield* Effect.exit(effect)
+        const need = yield* Ref.get(blocked)
+        if (need === undefined) {
+          if (Exit.isFailure(exit)) {
+            return yield* Effect.failCause(exit.cause)
+          }
+          return
+        }
+        const missing = MissingDependency.make({ story: story.id, need })
+        if ((yield* Ref.get(pushbacks)) > 0) {
+          return yield* missing
+        }
+        let rebuttal = blockedRebuttal(plan, story, need)
+        if (rebuttal === undefined && options.verifyBlocked !== undefined) {
+          const verdict = yield* options
+            .verifyBlocked(story, need, state.worktree, watchedSeats)
+            .pipe(Effect.catch(() => Effect.succeed(undefined)))
+          rebuttal = verdict === undefined || verdict.real ? undefined : verdict.reason
+        }
+        if (rebuttal === undefined) {
+          return yield* missing
+        }
+        yield* Ref.set(blocked, undefined)
+        yield* Ref.update(pushbacks, (count) => count + 1)
+        yield* events.publish(
+          Info.make({ message: `story ${story.id}: BLOCKED_ON rejected — ${rebuttal}` })
+        )
+        yield* coderTurn(
+          [
+            `You stopped with "${blockedOnSentinel} ${need}".`,
+            "That claim was checked against the epic's plan and rejected:",
+            rebuttal,
+            "",
+            "It is not a missing dependency. Continue the story inside your owned paths until it is",
+            `complete, then stop. Use ${blockedOnSentinel} only for work another story owns that is`,
+            "absent from your working tree."
+          ].join("\n")
+        )
+        const again = yield* Ref.get(blocked)
+        if (again !== undefined) {
+          return yield* MissingDependency.make({ story: story.id, need: again })
+        }
+        yield* commitGreen("continue after a rejected BLOCKED_ON", "after a rejected BLOCKED_ON")
+        yield* guarded(resume, Effect.void)
+      })
+
+    /**
+     * Stray paths go back before a judge sees the branch: first the coder is
+     * asked to move or revert them, then whatever is left is restored from
+     * the epic branch — a deterministic rule never needs a judge round.
+     */
+    const repairPerimeter: Effect.Effect<void, FlowError> = Effect.gen(function* () {
+      const first = yield* perimeterNow(story, git)
+      if (isWithinPerimeter(first)) {
+        return
+      }
+      const violation = PerimeterViolation.make({
+        story: story.id,
+        outside: first.outside,
+        sharedReadOnly: first.sharedReadOnly
+      })
+      yield* guarded(
+        coderTurn(
+          [
+            violation.message,
+            "",
+            "Put each of these paths back as it is on the epic branch (restore a changed file, delete",
+            "a file you created there). Work that belongs to this story moves into your owned paths.",
+            "Then stop."
+          ].join("\n")
+        ),
+        Effect.void
+      )
+      const second = yield* perimeterNow(story, git)
+      if (!isWithinPerimeter(second)) {
+        const stray = [...second.sharedReadOnly, ...second.outside]
+        yield* git.restorePaths(epicBranch, stray)
+        yield* events.publish(
+          Info.make({
+            message: `story ${story.id}: restored ${stray.length} path(s) outside its perimeter from ${epicBranch}: ${stray.join(", ")}`
+          })
+        )
+      }
+      yield* git.commitAll(`${story.id}: put paths outside the perimeter back`)
+    })
+
+    const planTasks = options.planTasks ?? defaultPlanTasks
+    const implementTasks = implementPlanFlow(storyContext, {
+      store: makePlanStore(files),
+      planPath: planPath(story),
+      plan: planWithinPerimeter(
+        plan,
+        story,
+        (text) => planTasks(watchedSeats, story, text),
+        prompt,
+        events
+      ),
+      system,
+      chatPerTask: true,
+      checkoutBranch: false,
+      lint: gates,
+      // A story's final state is judged and gated downstream (judge round,
+      // perimeter check, epic gates), so a task the coder finds already
+      // satisfied — without saying the exact sentinel — must not sink the
+      // story: the option exists for pipelines shaped like this one.
+      noopTaskPolicy: "complete",
+      ...(options.reviewers === undefined ? {} : { reviewers: options.reviewers }),
+      ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds })
+    })
+    yield* guarded(implementTasks, implementTasks)
+
+    // Other stories may have merged while this one ran: judge the branch
+    // against the epic as it is now.
+    yield* catchUp(story, git)
+    yield* repairPerimeter
 
     let judgeNote: string | undefined
     if (options.judge !== undefined) {
       const judge = options.judge
       for (let round = 1; round <= judgeRounds; round += 1) {
-        const diff = yield* storyContext.git.diffVsBase(epicBranch)
+        const diff = yield* git.diffVsBase(epicBranch)
         if (diff.trim().length === 0) {
           // Nothing to judge is a deterministic failure, not a model call:
           // 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
@@ -497,35 +924,30 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             `judge not cleared after ${judgeRounds} round(s):\n${issueLines(verdict)}`
           )
         }
-        const feedback = yield* makeChat(storyContext.coder, {
-          system,
-          events,
-          agent: "coder"
-        })
-        yield* blockedOr(
-          feedback.ask(
+        yield* guarded(
+          coderTurn(
             [
               `The story "${story.title}" scored below the bar. Close these gaps without`,
               "weakening any test and without leaving your owned paths, then stop:",
               issueLines(verdict)
             ].join("\n")
-          )
+          ),
+          Effect.void
         )
-        const regated = yield* options.gates(state.worktree)
-        if (!regated.isClean) {
-          return yield* failed(
-            story,
-            `gates broke while addressing judge feedback:\n${issueLines(regated)}`
-          )
-        }
-        yield* storyContext.git.commitAll(`${story.id}: address judge feedback`)
+        yield* repairPerimeter
+        yield* commitGreen("address judge feedback", "while addressing judge feedback")
       }
     }
 
-    const changed = yield* storyContext.git.changedFilesVsBase(epicBranch)
+    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* (
@@ -543,17 +965,19 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         judge: "merged on a previous run"
       })
     }
-    if (options.setup !== undefined) {
-      yield* stage(events, `story ${story.id}: setup`, options.setup(state.worktree))
-    }
     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,
@@ -561,6 +985,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 })
     })
@@ -586,7 +1011,15 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
               StoryState.make({ ...stored, status: "failed" })
             ).pipe(Effect.ignore)
           }
-          return {
+          const interruption: Interruption | undefined =
+            error._tag === "EpicCheckoutDirty" ||
+            error._tag === "RosterExhausted" ||
+            reason.includes(rosterExhaustedPrefix)
+              ? "halt"
+              : isOutageMessage(reason)
+                ? "outage"
+                : undefined
+          const completion: Completion = {
             story,
             outcome: StoryOutcome.make({
               id: story.id,
@@ -594,8 +1027,10 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
               status: "failed",
               reason,
               ...(stored === undefined ? {} : { branch: stored.branch })
-            })
+            }),
+            ...(interruption === undefined ? {} : { interruption })
           }
+          return completion
         })
       )
     )
@@ -639,19 +1074,35 @@ 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
+  /** Stories retried once after the serving engine recovered. */
+  const recovered = new Set<string>()
+
   yield* Effect.scoped(
     Effect.gen(function* () {
       while (true) {
-        const current = yield* progress
-        const ready = readyStories(plan, current)
-        const slots = concurrency - current.running.size
-        for (const story of ready.slice(0, Math.max(0, slots))) {
-          yield* Ref.update(running, (set) => new Set([...set, story.id]))
-          yield* Effect.forkScoped(
-            attempt(story).pipe(
-              Effect.flatMap((completion) => Queue.offer(completions, completion))
+        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 =
+            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(
+              attempt(story).pipe(
+                Effect.flatMap((completion) => Queue.offer(completions, completion))
+              )
             )
-          )
+          }
         }
         if ((yield* Ref.get(running)).size === 0) {
           break
@@ -662,12 +1113,43 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
           next.delete(completion.story.id)
           return next
         })
+        const reason = completion.outcome.reason ?? "failed"
+        if (completion.interruption === "outage" && halted === undefined) {
+          if (options.awaitRecovery !== undefined && !recovered.has(completion.story.id)) {
+            recovered.add(completion.story.id)
+            yield* events.publish(
+              Info.make({
+                message: `story ${completion.story.id}: the serving engine is down; waiting for it to recover, then retrying the story`
+              })
+            )
+            const back = yield* Effect.result(options.awaitRecovery(reason))
+            if (back._tag === "Success") {
+              // Not recorded: the story is ready again and relaunches.
+              continue
+            }
+            halted = `the serving engine did not recover (${describeFlowError(back.failure)})`
+          } else {
+            halted = `the serving engine is down: ${reason}`
+          }
+        }
+        if (completion.interruption === "halt" && halted === undefined) {
+          halted = reason
+        }
         yield* record(completion.outcome)
         const outcome = completion.outcome
         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 }),
@@ -689,6 +1171,24 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     })
   )
 
+  if (halted !== undefined) {
+    const stopped = halted
+    yield* events.publish(
+      Info.make({ message: `epic ${plan.epicId}: stopped launching stories — ${stopped}` })
+    )
+    const known = new Set((yield* Ref.get(outcomes)).map((outcome) => outcome.id))
+    for (const story of plan.stories) {
+      if (known.has(story.id)) {
+        continue
+      }
+      const reason = `not started: ${stopped}`
+      yield* record(
+        StoryOutcome.make({ id: story.id, title: story.title, status: "waiting", reason })
+      )
+      yield* board.wait(story.id, reason)
+    }
+  }
+
   const recorded = yield* Ref.get(outcomes)
   const ordered = plan.stories.flatMap((story) => {
     const outcome = recorded.find((candidate) => candidate.id === story.id)