@hyperdrive.bot/paseo-server 0.3.42 → 0.3.43

package/dist/server/server/workflow/workflow-manager.js

@@ -1,9 +1,20 @@
 import { randomUUID } from "node:crypto";
 import { PARENT_AGENT_ID_LABEL, WORKFLOW_ID_LABEL, WORKFLOW_TASK_ID_LABEL, } from "@hyperdrive.bot/paseo-protocol/agent-labels";
-import { projectWorkflowPhases, projectWorkflowProgress, resolveExecutionLayers, } from "./workflow-progress.js";
+import { startCreatedAgentInitialPrompt } from "../agent/agent-prompt.js";
+import { assertSchedulableGraph, projectWorkflowPhases, projectWorkflowProgress, resolveExecutionLayers, } from "./workflow-progress.js";
+import { assertKnownAgents, resolveTaskConfig } from "./workflow-agent-resolution.js";
 // Re-exported for back-compat: this error used to be declared here before the
 // execution-layer logic moved to `workflow-progress.ts` (Epic 3, Story 3.1).
 export { WorkflowCycleError } from "./workflow-progress.js";
+// Re-exported alongside WorkflowCycleError so every create-time graph rejection is
+// importable from ONE module. Callers of `createWorkflow` catch against the manager's
+// surface; making them reach into `workflow-progress.js` for half the errors would leak
+// the internal split.
+export { WorkflowInvalidGraphError } from "./workflow-progress.js";
+// Re-exported for the same reason as WorkflowCycleError above: the class is declared in
+// the leaf module `workflow-agent-resolution.ts` (which this file imports as a value) so
+// there is no runtime import cycle, but callers import it from the manager.
+export { WorkflowUnknownAgentError } from "./workflow-agent-resolution.js";
 // Default settle window (ms) for coalescing a burst of child `agent_state` events
 // into ONE projection emit. Mirrors AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS.
 export const WORKFLOW_PROJECTION_COALESCE_WINDOW_MS = 60;
@@ -33,8 +44,9 @@ export class WorkflowManager {
         this.storage = options.storage;
         this.coalesceWindowMs = options.coalesceWindowMs ?? WORKFLOW_PROJECTION_COALESCE_WINDOW_MS;
         this.timers = options.timers ?? { setTimeout, clearTimeout };
+        this.logger = options.logger;
         // Subscribe to child lifecycle changes so progress is projected live. We only
-        // care about FUTURE state — `replayState: false` skips the synchronous replay of
+        // care about FUTURE state - `replayState: false` skips the synchronous replay of
         // every existing agent at construction time.
         this.unsubscribeAgents = this.agentManager.subscribe((event) => this.onAgentEvent(event), {
             replayState: false,
@@ -54,9 +66,25 @@ export class WorkflowManager {
     /**
      * Build a workflow snapshot from a task graph, persist it (Story 1.1 storage),
      * register it in memory, emit to subscribers, and return the snapshot. No process
-     * is spawned here — that happens in {@link startWorkflow}/{@link spawnPhaseAgent}.
+     * is spawned here - that happens in {@link startWorkflow}/{@link spawnPhaseAgent}.
      */
     async createWorkflow(input) {
+        // FIRST statement: an unschedulable graph must be rejected before an id is minted,
+        // before layers are resolved, and above all before anything is written to disk or
+        // registered in `this.workflows`. Throws WorkflowInvalidGraphError (no tasks at all,
+        // or the same task id twice) or WorkflowCycleError (dangling dependency, cycle);
+        // both callers (session.ts RPC, mcp-server.ts workflow_start) already surface
+        // `error.message` verbatim to the operator, which is why those messages name ids.
+        assertSchedulableGraph(input.graph);
+        // SECOND guard in the same validation region, above the id mint and above every
+        // write: a task naming an agent nobody defined is a create-time error, never a
+        // silent downgrade to `baseConfig`. Kept separate from `assertSchedulableGraph`,
+        // whose contract is pinned to `(graph) => void` derived from dependencies alone.
+        assertKnownAgents({
+            graph: input.graph,
+            agentPresets: input.agentPresets ?? {},
+            workflowId: input.id,
+        });
         const id = input.id ?? randomUUID();
         const now = new Date().toISOString();
         const layers = resolveExecutionLayers(input.graph);
@@ -73,6 +101,12 @@ export class WorkflowManager {
             status: "pending",
             title: input.title ?? input.graph.goal,
             labels: input.labels ?? {},
+            // Gated on non-empty, not `?? {}`: `saveWorkflow` serialises the record verbatim,
+            // so an unconditional spread would add an `"agentPresets": {}` line to every
+            // workflow file the daemon has ever written (Story 2.2 AC2).
+            ...(input.agentPresets && Object.keys(input.agentPresets).length > 0
+                ? { agentPresets: input.agentPresets }
+                : {}),
             phases,
             childAgentIds: [],
             totalStoryCount: input.graph.tasks.length,
@@ -85,14 +119,18 @@ export class WorkflowManager {
             snapshot,
             graph: input.graph,
             baseConfig: input.baseConfig,
+            agentPresets: input.agentPresets ?? {},
             parentAgentId: input.parentAgentId,
             terminalOutcomes: new Map(),
+            closeRequestedAgentIds: new Set(),
+            spawnedTaskIds: new Set(),
+            childTaskIds: new Map(),
         });
         this.emit(snapshot);
         return snapshot;
     }
     /**
-     * List every known workflow — storage records overlaid with in-memory snapshots.
+     * List every known workflow - storage records overlaid with in-memory snapshots.
      * Live workflows are returned with progress PROJECTED from current child state
      * (Story 3.1), so list surfaces show the same live counts as the detail/SSE views.
      */
@@ -109,7 +147,7 @@ export class WorkflowManager {
     /**
      * Resolve a single workflow. A hard miss throws {@link WorkflowNotFoundError}.
      * For a live workflow the returned snapshot carries progress PROJECTED from the
-     * current child-agent states — the persisted counter is never trusted as truth.
+     * current child-agent states - the persisted counter is never trusted as truth.
      */
     async getWorkflow(id) {
         const live = this.workflows.get(id);
@@ -155,7 +193,7 @@ export class WorkflowManager {
     /**
      * Return the workflow's recorded lifecycle events, derived deterministically
      * from its snapshot's timestamps (created/started/completed/archived). A
-     * one-shot read — continuous event push is Epic 2. Throws
+     * one-shot read - continuous event push is Epic 2. Throws
      * {@link WorkflowNotFoundError} for an unknown id.
      */
     async getWorkflowEvents(workflowId) {
@@ -163,9 +201,47 @@ export class WorkflowManager {
         return projectWorkflowEvents(snapshot);
     }
     /**
-     * Drive a workflow to completion of its spawn phase: transition pending -> running,
-     * then walk `executionLayers` sequentially, spawning each layer's task agents (in
-     * task order). Returns the updated snapshot.
+     * Readiness predicate for the spawn scheduler - a pure function of `live`.
+     *
+     * Returns, in `graph.tasks` array order (so spawn order is deterministic), the NODE of
+     * every task that is not yet spawned, not yet terminal, and whose every declared
+     * dependency has already recorded a `"success"` outcome. Nodes, not ids: both callers
+     * need the node to spawn it, and returning ids made each of them re-scan `graph.tasks`
+     * (an O(n^2) lookup) behind an unreachable `if (!node) continue` guard.
+     *
+     * Readiness is computed from `TaskNode.dependencies` DIRECTLY, never from
+     * `resolveExecutionLayers`, whose declared-layer branch returns
+     * `metadata.executionLayers` verbatim and unvalidated, and never from layer output.
+     *
+     * A dependency id absent from `terminalOutcomes` is NOT satisfied. That single rule
+     * also makes an out-of-graph dependency unsatisfiable: a ghost id can never gain a
+     * terminal outcome, because outcomes are only ever written for real spawned children.
+     * This is a DELIBERATE divergence from `computeLayersFromDependencies`
+     * (workflow-progress.ts:268), whose `|| !byId.has(dep)` clause treats an out-of-graph
+     * dep as already met so it can keep layering already-stored graphs. Under a scheduler,
+     * "satisfied because it does not exist" would launch a task whose stated precondition
+     * was never met.
+     *
+     * Performs no I/O, no clock read and no `agentManager` call.
+     */
+    readyTaskNodes(live) {
+        return live.graph.tasks.filter((node) => !live.spawnedTaskIds.has(node.id) &&
+            !live.terminalOutcomes.has(node.id) &&
+            node.dependencies.every((dep) => live.terminalOutcomes.get(dep) === "success"));
+    }
+    /**
+     * Drive a workflow's FIRST spawn wave: transition pending -> running, then spawn
+     * exactly the tasks that are ready: those whose declared `dependencies` are already
+     * satisfied. On a fresh graph that is the dependency-free set; a task that declares a
+     * dependency is deliberately NOT launched here, which is what makes
+     * `TaskNode.dependencies` a real runtime constraint rather than a decorative field.
+     *
+     * Parallelism is residual, not declared: two tasks run together because nothing holds
+     * them, not because a layer listed them side by side.
+     *
+     * This method never launches a later wave. Tasks unblocked by a child reaching a
+     * terminal state are launched by the continuation path (Story 1.2), driven from
+     * `onAgentEvent`, not from here. Returns the updated snapshot.
      */
     async startWorkflow(workflowId) {
         const live = this.requireLive(workflowId);
@@ -178,15 +254,39 @@ export class WorkflowManager {
         };
         await this.persist(live);
         this.emit(live.snapshot);
-        const layers = resolveExecutionLayers(live.graph);
-        for (const layer of layers) {
-            for (const taskId of layer) {
-                const node = live.graph.tasks.find((task) => task.id === taskId);
-                if (!node) {
-                    throw new Error(`Task ${taskId} not found in workflow ${workflowId} graph`);
-                }
-                await this.spawnPhaseAgent({ workflowId, node, config: live.baseConfig });
+        // Claim the WHOLE first wave before the first await, not one id per iteration. The
+        // ledger must be authoritative for every readiness check that runs while any
+        // `createAgent` is in flight -- and from Story 1.2 onward such checks exist: spawning
+        // the first child dispatches `agent_state` synchronously inside `await createAgent`
+        // (agent-manager.ts:2848, :2854), which re-enters `onAgentEvent` -> `continueWorkflow`
+        // while this loop is still suspended on its first await. Claiming per-iteration would
+        // leave the rest of the wave unclaimed at that moment, so continuation would spawn
+        // those tasks and this loop would then spawn them a second time.
+        const firstWave = this.readyTaskNodes(live);
+        for (const node of firstWave) {
+            live.spawnedTaskIds.add(node.id);
+        }
+        for (const node of firstWave) {
+            // Re-read the status BETWEEN spawns, never once up front: `cancelWorkflow` mutates
+            // this same `live.snapshot` and can land while this loop is suspended on a previous
+            // `await`. Without this, cancelling a 3-task wave mid-flight still launched every
+            // remaining task into a workflow the caller had already stopped.
+            //
+            // `revokesInFlightWork`, NOT `isTerminalStatus`: a task failing elsewhere in this
+            // same wave must not abandon the independent tasks after it. Only a cancel stops
+            // the wave. See {@link revokesInFlightWork}.
+            if (revokesInFlightWork(live.snapshot.status)) {
+                break;
             }
+            await this.spawnPhaseAgent({
+                workflowId,
+                node,
+                config: resolveTaskConfig({
+                    node,
+                    baseConfig: live.baseConfig,
+                    agentPresets: live.agentPresets,
+                }),
+            });
         }
         return this.requireLive(workflowId).snapshot;
     }
@@ -195,6 +295,16 @@ export class WorkflowManager {
      * `agentManager.createAgent` surface, tagging it with WORKFLOW_ID_LABEL (and
      * PARENT_AGENT_ID_LABEL when the workflow is owned by a parent agent). Records the
      * child id on the snapshot and persists. Never spawns a process directly.
+     *
+     * `config` arrives ALREADY RESOLVED by the caller (`resolveTaskConfig`, Story 2.1);
+     * this method performs no resolution of its own, so one helper serves both spawn
+     * call sites with no duplicated precedence rule.
+     *
+     * Returns the child on the normal path and `undefined` when the workflow was cancelled
+     * mid-spawn and the child was discarded (gate 1.002 NIT-4). The two cases are otherwise
+     * indistinguishable to a caller - same type, same shape - and the discarded agent is a
+     * corpse: archived, and deliberately absent from `childAgentIds`. `undefined` is the
+     * only honest way to say "there is no child here" through a public surface.
      */
     async spawnPhaseAgent(args) {
         const { workflowId, node, config } = args;
@@ -202,18 +312,40 @@ export class WorkflowManager {
         const labels = {
             ...live.snapshot.labels,
             [WORKFLOW_ID_LABEL]: workflowId,
-            // Story 3.1 — map this child to its specific story node so the live progress
+            // Story 3.1 - map this child to its specific story node so the live progress
             // projection can derive completion/phase/gate from real child lifecycle state.
             [WORKFLOW_TASK_ID_LABEL]: node.id,
         };
         if (live.parentAgentId) {
             labels[PARENT_AGENT_ID_LABEL] = live.parentAgentId;
         }
+        // NOTE: `createAgent`'s options bag DECLARES `initialPrompt` and never reads it
+        // (agent-manager.ts:1005 declares, zero readers; `initialTitle` at :1028 is read).
+        // Passing it here created agents that sat idle forever with no prompt and no
+        // provider session, so a workflow reported `running` while doing nothing. The
+        // prompt is sent below, through the same helper the MCP/CLI create path uses.
         const agent = await this.agentManager.createAgent(config, undefined, {
             labels,
-            initialPrompt: node.prompt,
             initialTitle: node.title,
         });
+        // RECONCILE AFTER THE AWAIT. `createAgent` is the only slow step here, and
+        // `cancelWorkflow` mutates this same `live.snapshot` synchronously from another task,
+        // so the workflow can be CANCELLED while this spawn is in flight. The pre-spawn checks
+        // in `startWorkflow`/`continueWorkflow` cannot see that: they ran before this await.
+        // Without this branch a cancelled workflow still gained a live, unarchived child and
+        // persisted its id onto the cancelled snapshot.
+        //
+        // Scoped to cancellation on purpose. A workflow that settles to `failed` while this
+        // spawn is in flight keeps the child: settling observes the graph, it does not revoke
+        // siblings. See {@link revokesInFlightWork} for why the wider test was a defect.
+        if (revokesInFlightWork(live.snapshot.status)) {
+            await this.discardOrphanedChild(agent.id, workflowId, node.id);
+            return undefined;
+        }
+        // Bound here, in the same synchronous step as the `childAgentIds` append and after the
+        // same cancellation reconcile, so the two can never disagree: every acknowledged child
+        // has a task binding, and a discarded orphan has neither.
+        live.childTaskIds.set(agent.id, node.id);
         live.snapshot = {
             ...live.snapshot,
             childAgentIds: [...live.snapshot.childAgentIds, agent.id],
@@ -221,10 +353,48 @@ export class WorkflowManager {
         };
         await this.persist(live);
         this.emit(live.snapshot);
+        // Start the run only AFTER `childTaskIds` is bound and the snapshot is persisted:
+        // a child that terminates immediately would otherwise fire `onAgentEvent` before
+        // its task binding existed, and its outcome would be dropped on the floor.
+        try {
+            await startCreatedAgentInitialPrompt({
+                agentManager: this.agentManager,
+                agentId: agent.id,
+                snapshot: agent,
+                prompt: node.prompt,
+                logger: this.logger,
+            });
+        }
+        catch (error) {
+            // A child that never starts can never reach a terminal outcome, so its
+            // dependents never become ready and the workflow stalls at `running`. That is
+            // the failure this whole story exists to remove, so it is logged loudly rather
+            // than swallowed. The child is left in place and visible.
+            this.logger?.error({ err: error, workflowId, taskId: node.id, agentId: agent.id }, "Workflow child agent was created but its initial prompt failed to start");
+        }
         return agent;
     }
     /**
-     * Archive every child agent tagged to the workflow — no orphans — mirroring
+     * Tear down a child that was created for a workflow which went terminal mid-spawn.
+     * Uses `archiveAgent`, the same public surface {@link cascadeArchiveChildren} uses, so
+     * the child is closed and marked archived rather than left running for a workflow
+     * nobody is watching. The child id is deliberately NOT appended to the snapshot: a
+     * cancelled workflow gains no children.
+     *
+     * Best effort and never throws. It runs on the failure path of a spawn that has already
+     * happened; a teardown error must not turn into a rejected `startWorkflow`, nor into an
+     * unhandled rejection from the detached continuation IIFE.
+     */
+    async discardOrphanedChild(agentId, workflowId, taskId) {
+        try {
+            await this.agentManager.archiveAgent(agentId);
+        }
+        catch (error) {
+            this.logger?.error({ workflowId, taskId, agentId, err: error }, "workflow.spawn.discard_failed");
+        }
+    }
+    /**
+     * Archive every child agent tagged to the workflow - no orphans - mirroring
      * `AgentManager.cascadeArchiveChildren`, but keyed on WORKFLOW_ID_LABEL and using
      * only the public archive surface (`listAgents` + `archiveAgent`). `archiveAgent`
      * requires a live agent, so we iterate the live set exactly as the original guards
@@ -247,7 +417,7 @@ export class WorkflowManager {
         }
     }
     /**
-     * Number of live snapshot subscribers. Read-only observability — used by the
+     * Number of live snapshot subscribers. Read-only observability - used by the
      * SSE route's leak-guard test (Story 2.1) to assert that a disconnected client
      * unsubscribes back to baseline. Additive; does not affect emit behaviour.
      */
@@ -267,14 +437,33 @@ export class WorkflowManager {
                 subscriber({ workflow });
             }
             catch {
-                // Subscriber error isolation — one bad listener never blocks the others.
+                // Subscriber error isolation - one bad listener never blocks the others.
             }
         }
     }
     /**
-     * AgentManager subscription handler (Story 3.1). Reacts only to child state
-     * changes for an agent tagged to a tracked, non-terminal workflow; schedules a
-     * coalesced projection emit for that workflow.
+     * AgentManager subscription handler. Reacts only to child state changes for an
+     * agent tagged to a tracked, RUNNING workflow (pending, cancelled and finished
+     * workflows are all rejected by the early return). It does three things:
+     *
+     * 1. Records the child's terminal outcome while the event still carries the closed
+     *    agent (Story 3.1),
+     * 2. Drives ORCHESTRATION (Story 1.2): every surviving event sweeps the graph for
+     *    tasks whose dependencies just became satisfied and spawns them. This is the
+     *    only continuation path; there is no poll loop and no second `startWorkflow`, and
+     * 3. SETTLES the workflow (Story 1.3): once every declared task has a terminal
+     *    outcome it flips to `completed`, and the first `failed` outcome flips it to
+     *    `failed`, freezing the projected counts into the snapshot at that instant.
+     *
+     * Then it schedules a coalesced projection emit for the workflow. Continuation runs
+     * ALONGSIDE that emit, never behind it: the 60 ms window throttles display, and
+     * routing scheduling through it would add a window's dead time per graph edge.
+     *
+     * MUST stay synchronous and MUST NOT throw. `AgentManager.dispatch` invokes
+     * `subscriber.callback(event)` with no try/catch (agent-manager.ts:3992), so a throw
+     * here starves every later subscriber and propagates out of the caller's
+     * `await closeAgent(id)`. Making it `async` is the other half of the same bug:
+     * `dispatch` ignores the returned promise, so a rejection becomes an unhandled one.
      */
     onAgentEvent(event) {
         if (event.type !== "agent_state") {
@@ -285,14 +474,52 @@ export class WorkflowManager {
             return;
         }
         const live = this.workflows.get(workflowId);
-        if (!live || isTerminalStatus(live.snapshot.status)) {
+        // `!== "running"` rather than `!isTerminalStatus(...)`. Both reject a cancelled or
+        // finished workflow; only this one also rejects a PENDING one. That mattered the
+        // moment continuation shipped: before it, only `startWorkflow` could spawn, so a
+        // stray `agent_state` carrying a pending workflow's WORKFLOW_ID_LABEL was harmless.
+        // With continuation, the same event drove a never-started workflow into spawning its
+        // first wave - leaving it with children while `status` stayed "pending" and
+        // `startedAt` stayed null, so the lifecycle projection disagreed with reality. The
+        // label is client-reachable (the WS `agent.create` message and MCP `agent_spawn` both
+        // forward arbitrary labels), so this is reachable, not theoretical.
+        if (!live || live.snapshot.status !== "running") {
             return;
         }
         // A child that reaches a terminal lifecycle is DELETED from AgentManager's live map
         // (prepareAgentForClosure), so the live projection would never witness its completion.
         // Record the terminal outcome now -- keyed by task, while the event still carries the
         // closed agent -- so projectSnapshot counts it even after the agent is gone.
-        const taskId = event.agent.labels?.[WORKFLOW_TASK_ID_LABEL];
+        //
+        // OWNERSHIP GATE (gate 1.003 MAJOR-1, closed the rest of the way by MINOR-4). The task
+        // id comes from `live.childTaskIds`, the binding `spawnPhaseAgent` wrote itself, NOT
+        // from the event's WORKFLOW_TASK_ID_LABEL. Two separate defects need that:
+        //
+        //   1. The label is client-SETTABLE at create time (the WS `agent.create` message and
+        //      MCP `agent_spawn` forward an arbitrary `Record<string, string>`), so any stranger
+        //      wearing a workflow id plus a task id could write into that workflow's ledger, and
+        //      since Story 1.3 the ledger decides a TERMINAL status. Reproduced twice: a stranger
+        //      labelled `task-002` failing its turn drove a healthy workflow to `failed` while
+        //      task-001's real child was still running, and the same stranger closing cleanly
+        //      produced `completed` with `completedStoryCount: 2` on a graph whose second task
+        //      had never been spawned. The terminal early return above makes that lie permanent
+        //      and persists it to disk.
+        //   2. The label stays WRITABLE after spawn (`update_agent_request` merges arbitrary
+        //      labels onto a live agent), so a membership check on `childAgentIds` alone was not
+        //      enough: relabelling a workflow's OWN child from `task-001` to `task-002` filed
+        //      task-001's close under task-002, leaving task-001 in `spawnedTaskIds` with no
+        //      outcome it can ever gain. `allTerminal` was then unreachable and the workflow sat
+        //      `running` forever, reporting task-001 pending and task-002 completed with zero
+        //      live children. Only `cancelWorkflow` could end it.
+        //
+        // A `childTaskIds` hit IS the ownership proof, so no second membership test is needed:
+        // the map is written in the same synchronous step as the `childAgentIds` append, after
+        // the cancellation reconcile, so a discarded orphan is absent from both. It also subsumes
+        // the out-of-graph case (a key can only ever be a `node.id`), which keeps the graph read
+        // in `settleWorkflow` a second layer rather than the only one. The label survives as what
+        // it was always good for: display, and the live progress projection's own lookup
+        // (`workflow-progress.ts:159`), where a wrong label misdraws a row and settles nothing.
+        const taskId = live.childTaskIds.get(event.agent.id);
         if (taskId !== undefined) {
             if (event.agent.lifecycle === "closed") {
                 live.terminalOutcomes.set(taskId, event.agent.lastError ? "failed" : "success");
@@ -301,14 +528,177 @@ export class WorkflowManager {
                 live.terminalOutcomes.set(taskId, "failed");
             }
         }
+        // A paseo agent that finishes its task does NOT reach a terminal lifecycle. It goes
+        // `idle` with `requiresAttention: true, attentionReason: "finished"` and stays alive
+        // awaiting more input, exactly as an interactive session should. `terminalOutcomes`
+        // above only records on `closed`/`error`, so without this the ledger stayed empty,
+        // `readyTaskIds` never saw a satisfied dependency, and NO workflow could advance past
+        // its first layer or ever settle. Measured against a real daemon: task `first` reached
+        // attentionReason "finished" at 14:19:52 and the workflow still read 0/2 minutes later.
+        //
+        // `loop-service.ts` (`:682`, `:798`) already closes its worker for this same reason;
+        // workflows simply never did. Closing here re-enters `onAgentEvent` with `closed`, so
+        // the outcome logic above stays the single place a task's result is decided.
+        //
+        // ONLY on "finished". `"permission"` means a human is being asked something and closing
+        // would silently discard the request; `"error"` is already handled by the error branch.
+        // `AttentionState` is a union carried alongside the lifecycle union, so narrowing on
+        // `lifecycle === "idle"` picks `ManagedAgentIdle` and loses sight of it. Read the two
+        // fields through an explicit shape rather than widening the public ManagedAgent type.
+        // The LIVE agent nests this as `agent.attention` (agent-manager.ts:1542/1778/3841).
+        // The flat `requiresAttention` / `attentionReason` pair only exists in the PERSISTED
+        // shape, so reading it off the event silently never matched and the close never fired.
+        const attention = event.agent.attention;
+        if (taskId !== undefined &&
+            event.agent.lifecycle === "idle" &&
+            attention?.requiresAttention === true &&
+            attention.attentionReason === "finished" &&
+            !live.closeRequestedAgentIds.has(event.agent.id)) {
+            live.closeRequestedAgentIds.add(event.agent.id);
+            const finishedAgentId = event.agent.id;
+            void this.agentManager.closeAgent(finishedAgentId).catch((error) => {
+                // Leave the id in `closeRequestedAgentIds`: retrying on every subsequent event
+                // would hammer a failing close. The task simply gains no outcome, which surfaces
+                // as a workflow stuck at `running` rather than a silent wrong result.
+                this.logger?.error({ err: error, workflowId, taskId, agentId: finishedAgentId }, "Workflow child finished its turn but could not be closed");
+            });
+        }
+        // Called unconditionally, not only on terminal lifecycles: the readiness sweep is a
+        // pure function plus a synchronously guarded spawn, so a non-terminal event is a free
+        // no-op. That unconditional call is also what exercises the re-entrancy the ledger
+        // insert in `continueWorkflow` is there to absorb.
+        this.continueWorkflow(live);
+        // Continuation BEFORE settling, per the epic, and provably safe: one `agent_state`
+        // event carries exactly one agent, so at most one task becomes terminal per event.
+        // A FAILING task satisfies no dependency, so `readyTaskNodes` returns empty on that
+        // event and nothing is spawned before the flip.
+        //
+        // `void ... .catch(...)` is mandatory, not stylistic: an `async` function converts a
+        // synchronous throw in its prefix into a rejection, so this single `.catch` covers
+        // both a bad projection and a failed storage write. `onAgentEvent` stays
+        // `void`-returning and never awaits.
+        void this.settleWorkflow(live).catch((error) => {
+            this.logger?.error({ workflowId, err: error }, "workflow.settle.failed");
+        });
         this.scheduleProjectionEmit(workflowId);
     }
+    /**
+     * Spawn every task whose dependencies have just become satisfied. Takes the ALREADY
+     * RESOLVED `LiveWorkflow` rather than a workflow id, so it can never call
+     * `requireLive` and can never throw `WorkflowNotFoundError` synchronously into
+     * `AgentManager.dispatch`. Returns `void`, never a promise, and never throws.
+     *
+     * The ENTRY guard deliberately lives in the caller (`onAgentEvent`'s early return), not
+     * here: a workflow that is not `running` never reaches this method, so cancellation
+     * wins for free with no second entry guard to keep in sync. The re-read inside the
+     * detached loop is a different question - not "may I start?" but "is this still true
+     * after the last await?" - and it has no equivalent in the caller, which returned long
+     * before that loop runs.
+     *
+     * Readiness comes from `readyTaskNodes`, the single Story 1.1 rule. This method adds no
+     * second readiness rule, does not flip the workflow status, does not stamp
+     * `completedAt` and does not record an outcome for a task whose spawn failed:
+     * inventing a failure outcome here would change the projection's counts.
+     */
+    continueWorkflow(live) {
+        const nodes = this.readyTaskNodes(live);
+        if (nodes.length === 0) {
+            return;
+        }
+        for (const node of nodes) {
+            // THE idempotency guarantee: claimed synchronously, before any `await` anywhere in
+            // this method. Spawning a child dispatches further `agent_state` events for this
+            // workflow synchronously inside `await createAgent` (agent-manager.ts:2848, :2854),
+            // each of which re-enters `onAgentEvent` while this same spawn is still in flight.
+            // With the claim before the await, those re-entrant sweeps see the task already
+            // taken and do nothing; after the await, every one of them re-spawns it.
+            live.spawnedTaskIds.add(node.id);
+        }
+        // Detached on purpose: `onAgentEvent` must not become async. One try/catch per node so
+        // a single failing spawn never blocks its siblings.
+        void (async () => {
+            for (const node of nodes) {
+                // Same between-spawn re-read as `startWorkflow`'s loop: a cancel landing while
+                // this loop is suspended on a previous spawn must stop the remaining ones. A
+                // failure settling the workflow does not - see {@link revokesInFlightWork}.
+                if (revokesInFlightWork(live.snapshot.status)) {
+                    return;
+                }
+                try {
+                    await this.spawnPhaseAgent({
+                        workflowId: live.snapshot.id,
+                        node,
+                        config: resolveTaskConfig({
+                            node,
+                            baseConfig: live.baseConfig,
+                            agentPresets: live.agentPresets,
+                        }),
+                    });
+                }
+                catch (error) {
+                    this.logger?.error({ workflowId: live.snapshot.id, taskId: node.id, err: error }, "workflow.continue.spawn_failed");
+                }
+            }
+        })();
+    }
+    /**
+     * Settle the workflow to a terminal status once its graph has finished. Takes the
+     * ALREADY RESOLVED `LiveWorkflow`, never a workflow id, so it can never call
+     * `requireLive` and can never throw `WorkflowNotFoundError` into
+     * `AgentManager.dispatch`.
+     *
+     * The rule is read THROUGH `graph.tasks`, not off `terminalOutcomes.values()`. With the
+     * ledger keyed on `live.childTaskIds` (gate 1.003 MINOR-4) an out-of-graph key can no
+     * longer enter the map at all, so this is a second layer rather than the only one; it is
+     * kept because it costs nothing and it is the layer that survives if the key ever becomes
+     * derivable from an event again. Mapping the declared tasks over the map also means a
+     * partially populated ledger reads as "not finished" rather than as "finished".
+     *
+     * Everything up to the first `await` is synchronous ON PURPOSE. `AgentManager.dispatch`
+     * is a plain synchronous loop invoked from inside `await closeAgent(...)`, so the status
+     * flip and the frozen counts are committed to memory before that expression resolves -
+     * which is what lets a caller read the terminal snapshot on the very next line with no
+     * polling. Only `persist` and `emit` are asynchronous.
+     *
+     * Children are never cancelled, closed, archived or interrupted here: an independent
+     * in-flight sibling keeps running after a failure.
+     */
+    async settleWorkflow(live) {
+        // pending never has children, and a terminal workflow is already filtered by the
+        // early return in `onAgentEvent`. Belt and braces, one line.
+        if (live.snapshot.status !== "running") {
+            return;
+        }
+        const outcomes = live.graph.tasks.map((task) => live.terminalOutcomes.get(task.id));
+        const anyFailed = outcomes.some((outcome) => outcome === "failed");
+        const allTerminal = outcomes.every((outcome) => outcome !== undefined);
+        if (!anyFailed && !allTerminal) {
+            return;
+        }
+        // FREEZE THE COUNTS FIRST. `projectSnapshot` short-circuits on a terminal status and
+        // returns `live.snapshot` verbatim, whose `completedStoryCount` is still the literal
+        // `0` written at createWorkflow - every live count a reader has ever seen came from
+        // the projection overlay, never from that stored field. So project WHILE STILL
+        // RUNNING, then flip. Spreading `live.snapshot` here instead compiles, type-checks
+        // and lints, and silently zeroes every finished workflow's progress.
+        const projected = this.projectSnapshot(live);
+        const now = new Date().toISOString();
+        live.snapshot = {
+            ...projected,
+            status: anyFailed ? "failed" : "completed",
+            completedAt: now,
+            updatedAt: now,
+        };
+        // Persist then emit - the same order as `cancelWorkflow`.
+        await this.persist(live);
+        this.emit(live.snapshot);
+    }
     /**
      * Coalesce a burst of child updates into ONE projection emit per settled window
      * (the `agent-stream-coalescer.ts` discipline). The first event in a burst arms a
      * timer; subsequent events within the window are absorbed. On fire, the current
      * child states are projected and the updated snapshot is emitted through the
-     * existing `workflow.*` / HTTP / SSE channels — no new transport, no polling.
+     * existing `workflow.*` / HTTP / SSE channels - no new transport, no polling.
      */
     scheduleProjectionEmit(workflowId) {
         if (this.projectionTimers.has(workflowId)) {
@@ -328,7 +718,7 @@ export class WorkflowManager {
     /**
      * Overlay LIVE derived progress onto a workflow's base snapshot. Counts, per-phase
      * gate status, and per-phase completion are recomputed from the current child-agent
-     * states — never read back from the persisted snapshot. Terminal workflows are
+     * states - never read back from the persisted snapshot. Terminal workflows are
      * returned unchanged (nothing left to project). The base snapshot's lifecycle
      * fields (status, childAgentIds, timestamps, id/title) are preserved verbatim; only
      * derived progress fields are overlaid, so this stays back-compat and additive.
@@ -351,7 +741,7 @@ export class WorkflowManager {
             taskGraph: live.graph,
             terminalOutcomes: live.terminalOutcomes,
         });
-        // Overlay by index — preserve each phase's persisted id/title, refresh its gate.
+        // Overlay by index - preserve each phase's persisted id/title, refresh its gate.
         const phases = base.phases.map((phase, index) => {
             const projected = projectedPhases[index];
             if (!projected) {
@@ -386,6 +776,24 @@ export class WorkflowManager {
 function isTerminalStatus(status) {
     return status === "completed" || status === "failed" || status === "cancelled";
 }
+/**
+ * The ONE status that revokes work already in motion. Deliberately narrower than
+ * {@link isTerminalStatus}: cancellation is the operator saying "stop", so a spawn still
+ * parked inside `createAgent` when it lands is work nobody asked for and gets discarded.
+ *
+ * A `failed` or `completed` workflow is the opposite case. Settling is an OBSERVATION
+ * about the graph, not an instruction about the children, and Story 1.3's contract is
+ * explicit that a failure leaves independent siblings alone ("Children are never
+ * cancelled, closed, archived or interrupted here" - see {@link WorkflowManager.settleWorkflow}).
+ * Keying the spawn-abort on `isTerminalStatus` made that contract depend on the clock:
+ * with a fast provider both wave-1 children landed before the failure and survived, while
+ * at real provider latency (hundreds of ms per PTY) the in-flight sibling was archived
+ * mid-launch and the untouched rest of the wave was never asked for at all - a different
+ * surviving work set for the same graph and the same failure. Gate 1.002 MAJOR-3.
+ */
+function revokesInFlightWork(status) {
+    return status === "cancelled";
+}
 /** The lifecycle-event type that corresponds to a terminal status. */
 function terminalEventType(status) {
     switch (status) {
@@ -401,7 +809,7 @@ function terminalEventType(status) {
 }
 /**
  * Derive the ordered lifecycle-event list from a snapshot's timestamps. Pure and
- * deterministic — the same snapshot always yields the same events.
+ * deterministic - the same snapshot always yields the same events.
  */
 function projectWorkflowEvents(snapshot) {
     const events = [