@llm4ts/flow 2.7.2 → 2.8.0

package/dist/Stories.js

@@ -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";
@@ -13,13 +14,17 @@ import * as Stream from "effect/Stream";
 import { BoardItem } from "./BoardSync.js";
 import { makeChat } from "./Chat.js";
 import { implementPlanFlow } from "./Flow.js";
-import { describeFlowError, MissingDependency, StoryFailed } from "./FlowError.js";
+import { describeFlowError, EpicCheckoutDirty, MissingDependency, PerimeterViolation, StoryFailed } from "./FlowError.js";
 import { Info } from "./FlowEvents.js";
-import { enforcePerimeter } from "./Perimeter.js";
+import { statusPaths } from "./GitTool.js";
+import { checkPerimeter, enforcePerimeter, isWithinPerimeter, perimeterGate, strayTasks } from "./Perimeter.js";
 import { loadVersioned, makePlanStore, saveVersioned } from "./Persistence.js";
+import { Plan } from "./Plan.js";
 import { stage } from "./PlanExecution.js";
 import { planFrom } from "./Planner.js";
-import { dependentsOf, readyStories, storyHash, topologicalWaves, validateStoryPlan } from "./StoryPlan.js";
+import { ReviewResult } from "./Review.js";
+import { dependentsOf, ownerOf, pathsNamedIn, readyStories, relationOf, storyHash, topologicalWaves, validateStoryPlan } from "./StoryPlan.js";
+import { isOutageMessage } from "./TransientRetry.js";
 const join = (root, path) => `${root.replace(/[\\/]+$/, "")}/${path.replace(/^[\\/]+/, "")}`;
 // ---- Durable state ----------------------------------------------------------
 export const StoryStateVersion = 1;
@@ -115,8 +120,31 @@ export const blockedOnIn = (text) => {
     return need === undefined || need.length === 0 ? undefined : need;
 };
 const bullets = (items) => items.length === 0 ? "- (none)" : items.map((item) => `- ${item}`).join("\n");
+const relationNotes = {
+    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, where) => {
+    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) => [
+export const perimeterRules = (story, where) => [
     `You are implementing ONE story of a larger epic: "${story.title}" (id: ${story.id}).`,
     "",
     "Paths you own — create and change files only here:",
@@ -127,6 +155,7 @@ export const perimeterRules = (story) => [
     "",
     "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.",
@@ -142,13 +171,86 @@ export const storyPrompt = (story) => [`Story: ${story.title}`, "", story.descri
 export const storyTaskPlanInstructions = (story) => [
     "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}]}'
 ].join("\n");
 /** The coder plans its own tasks from the story — the orchestrator split the epic, not the story. */
 export const defaultPlanTasks = (seats, story, prompt) => 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, story, planTasks, prompt, events) => 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, story, need) => {
+    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")({
+    /** 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 = (stream, blocked) => Stream.unwrap(Effect.gen(function* () {
     const text = yield* Ref.make("");
@@ -171,6 +273,12 @@ export const watchForBlockedOn = (service, blocked) => ({
     executeStream: (prompt) => watchStream(service.executeStream(prompt), blocked),
     executeStreamWithHistory: (messages) => watchStream(service.executeStreamWithHistory(messages), blocked)
 });
+const combined = (first, second) => 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) => result.issues.map((issue) => `- ${issue.title}: ${issue.description}`).join("\n");
 const failed = (story, reason) => StoryFailed.make({ story: story.id, reason });
 // ---- The executor -------------------------------------------------------------
@@ -183,6 +291,22 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     const judgeRounds = Math.max(1, options.judgeRounds ?? 2);
     const statePath = (story) => join(options.stateDir, `stories/${story.id}.json`);
     const planPath = (story) => 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) => 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);
     const waveOf = (id) => {
@@ -201,6 +325,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     const mergeLock = yield* Semaphore.make(1);
     /** Merge the story branch into the epic branch and re-gate the epic head, one story at a time. */
     const integrate = (story, branch) => 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);
@@ -245,41 +370,177 @@ 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, git) => 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, git) => 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, state) {
         const seats = yield* options.contextFor(state.worktree);
         const blocked = yield* Ref.make(undefined);
+        const pushbacks = yield* Ref.make(0);
         const storyContext = {
             ...seats.context,
             coder: watchForBlockedOn(seats.context.coder, blocked)
         };
+        const git = storyContext.git;
         const watchedSeats = { ...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 !== undefined && part.trim().length > 0)
             .join("\n\n");
         const prompt = storyPrompt(story);
-        const blockedOr = (effect) => 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 })))));
-        yield* blockedOr(implementPlanFlow(storyContext, {
+        // 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.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) => Effect.flatMap(makeChat(storyContext.coder, { system, events, agent: "coder" }), (chat) => chat.ask(text));
+        const commitGreen = (message, why) => 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 = (effect, resume) => 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)
+                    .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.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: (options.planTasks ?? defaultPlanTasks)(watchedSeats, story, prompt),
+            plan: planWithinPerimeter(plan, story, (text) => planTasks(watchedSeats, story, text), prompt, events),
             system,
             chatPerTask: true,
             checkoutBranch: false,
-            lint: options.gates(state.worktree),
+            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
@@ -287,12 +548,17 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             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;
         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.
@@ -306,24 +572,16 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
                 if (round >= judgeRounds) {
                     return yield* failed(story, `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")));
-                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`);
+                ].join("\n")), Effect.void);
+                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 };
@@ -341,9 +599,6 @@ 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);
         yield* saveVersioned(files, statePath(story), StoryStateVersion, StoryState, StoryState.make({ ...state, status: "merged" }));
@@ -365,7 +620,12 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         if (stored !== undefined && stored.status !== "merged") {
             yield* saveVersioned(files, path, StoryStateVersion, StoryState, StoryState.make({ ...stored, status: "failed" })).pipe(Effect.ignore);
         }
-        return {
+        const interruption = error._tag === "EpicCheckoutDirty"
+            ? "halt"
+            : isOutageMessage(reason)
+                ? "outage"
+                : undefined;
+        const completion = {
             story,
             outcome: StoryOutcome.make({
                 id: story.id,
@@ -373,8 +633,10 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
                 status: "failed",
                 reason,
                 ...(stored === undefined ? {} : { branch: stored.branch })
-            })
+            }),
+            ...(interruption === undefined ? {} : { interruption })
         };
+        return completion;
     })));
     const outcomes = yield* Ref.make([]);
     const running = yield* Ref.make(new Set());
@@ -406,14 +668,20 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
             yield* board.wait(id, reason);
         }
     });
+    /** Why no further story may start in this run; stories already running finish. */
+    let halted;
+    /** Stories retried once after the serving engine recovered. */
+    const recovered = new Set();
     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);
+                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 ((yield* Ref.get(running)).size === 0) {
                 break;
@@ -424,6 +692,27 @@ 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") {
@@ -450,6 +739,19 @@ 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);