@hyperdrive.bot/fleet-server 0.3.99

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

@@ -0,0 +1,852 @@
+import { randomUUID } from "node:crypto";
+import { PARENT_AGENT_ID_LABEL, WORKFLOW_ID_LABEL, WORKFLOW_TASK_ID_LABEL, } from "@hyperdrive.bot/fleet-protocol/agent-labels";
+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;
+/** Thrown when a workflow id resolves to nothing in memory or storage. */
+export class WorkflowNotFoundError extends Error {
+    constructor(workflowId) {
+        super(`Workflow ${workflowId} not found`);
+        this.workflowId = workflowId;
+        this.name = "WorkflowNotFoundError";
+    }
+}
+/** Thrown when cancel targets a workflow that has already reached a terminal state. */
+export class WorkflowAlreadyTerminalError extends Error {
+    constructor(workflowId, status) {
+        super(`Workflow ${workflowId} is already ${status} and cannot be cancelled`);
+        this.workflowId = workflowId;
+        this.status = status;
+        this.name = "WorkflowAlreadyTerminalError";
+    }
+}
+export class WorkflowManager {
+    constructor(options) {
+        this.workflows = new Map();
+        this.subscribers = new Set();
+        this.projectionTimers = new Map();
+        this.agentManager = options.agentManager;
+        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
+        // every existing agent at construction time.
+        this.unsubscribeAgents = this.agentManager.subscribe((event) => this.onAgentEvent(event), {
+            replayState: false,
+        });
+    }
+    /**
+     * Detach the AgentManager subscription and cancel any pending projection timers.
+     * Idempotent; safe to call on daemon shutdown.
+     */
+    dispose() {
+        this.unsubscribeAgents();
+        for (const timer of this.projectionTimers.values()) {
+            this.timers.clearTimeout(timer);
+        }
+        this.projectionTimers.clear();
+    }
+    /**
+     * 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}.
+     */
+    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);
+        const phases = layers.map((layer, index) => ({
+            id: `layer-${index + 1}`,
+            title: `Layer ${index + 1}`,
+            status: "pending",
+            storyCount: layer.length,
+            completedStoryCount: 0,
+        }));
+        const snapshot = {
+            id,
+            cwd: input.cwd,
+            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,
+            completedStoryCount: 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.storage.saveWorkflow(snapshot);
+        this.workflows.set(id, {
+            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.
+     * 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.
+     */
+    async listWorkflows() {
+        const byId = new Map();
+        for (const record of await this.storage.listWorkflows()) {
+            byId.set(record.id, record);
+        }
+        for (const live of this.workflows.values()) {
+            byId.set(live.snapshot.id, this.projectSnapshot(live));
+        }
+        return Array.from(byId.values());
+    }
+    /**
+     * 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.
+     */
+    async getWorkflow(id) {
+        const live = this.workflows.get(id);
+        if (live) {
+            return this.projectSnapshot(live);
+        }
+        const stored = await this.storage.loadWorkflow(id);
+        if (!stored) {
+            throw new WorkflowNotFoundError(id);
+        }
+        return stored;
+    }
+    /**
+     * Cancel a workflow: flip it to the terminal `cancelled` status, persist, and
+     * emit. Resolves a live OR storage-only workflow. Throws
+     * {@link WorkflowNotFoundError} for an unknown id and
+     * {@link WorkflowAlreadyTerminalError} when it has already finished. Child-agent
+     * teardown is the separate concern of {@link cascadeArchiveChildren}.
+     */
+    async cancelWorkflow(workflowId) {
+        const live = this.workflows.get(workflowId);
+        const current = live?.snapshot ?? (await this.storage.loadWorkflow(workflowId));
+        if (!current) {
+            throw new WorkflowNotFoundError(workflowId);
+        }
+        if (isTerminalStatus(current.status)) {
+            throw new WorkflowAlreadyTerminalError(workflowId, current.status);
+        }
+        const now = new Date().toISOString();
+        const cancelled = {
+            ...current,
+            status: "cancelled",
+            completedAt: now,
+            updatedAt: now,
+        };
+        if (live) {
+            live.snapshot = cancelled;
+        }
+        await this.storage.saveWorkflow(cancelled);
+        this.emit(cancelled);
+        return cancelled;
+    }
+    /**
+     * 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
+     * {@link WorkflowNotFoundError} for an unknown id.
+     */
+    async getWorkflowEvents(workflowId) {
+        const snapshot = await this.getWorkflow(workflowId);
+        return projectWorkflowEvents(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);
+        const startedAt = new Date().toISOString();
+        live.snapshot = {
+            ...live.snapshot,
+            status: "running",
+            startedAt,
+            updatedAt: startedAt,
+        };
+        await this.persist(live);
+        this.emit(live.snapshot);
+        // 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;
+    }
+    /**
+     * Spawn a single child agent for one task node via the public
+     * `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;
+        const live = this.requireLive(workflowId);
+        const labels = {
+            ...live.snapshot.labels,
+            [WORKFLOW_ID_LABEL]: workflowId,
+            // 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,
+            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],
+            updatedAt: new Date().toISOString(),
+        };
+        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;
+    }
+    /**
+     * 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
+     * on `agents.has(id)`. The workflow snapshot itself is marked archived.
+     */
+    async cascadeArchiveChildren(workflowId) {
+        for (const agent of this.agentManager.listAgents()) {
+            if (agent.labels?.[WORKFLOW_ID_LABEL] !== workflowId) {
+                continue;
+            }
+            await this.agentManager.archiveAgent(agent.id);
+        }
+        const live = this.workflows.get(workflowId);
+        if (live) {
+            const archivedAt = new Date().toISOString();
+            const status = terminalStatusForArchive(live.snapshot.status);
+            live.snapshot = { ...live.snapshot, status, archivedAt, updatedAt: archivedAt };
+            await this.persist(live);
+            this.emit(live.snapshot);
+        }
+    }
+    /**
+     * 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.
+     */
+    get subscriberCount() {
+        return this.subscribers.size;
+    }
+    /** Subscribe to workflow snapshot changes. Returns an unsubscribe function. */
+    subscribe(subscriber) {
+        this.subscribers.add(subscriber);
+        return () => {
+            this.subscribers.delete(subscriber);
+        };
+    }
+    emit(workflow) {
+        for (const subscriber of this.subscribers) {
+            try {
+                subscriber({ workflow });
+            }
+            catch {
+                // Subscriber error isolation - one bad listener never blocks the others.
+            }
+        }
+    }
+    /**
+     * 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") {
+            return;
+        }
+        const workflowId = event.agent.labels?.[WORKFLOW_ID_LABEL];
+        if (workflowId === undefined) {
+            return;
+        }
+        const live = this.workflows.get(workflowId);
+        // `!== "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.
+        //
+        // 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");
+            }
+            else if (event.agent.lifecycle === "error") {
+                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.
+     */
+    scheduleProjectionEmit(workflowId) {
+        if (this.projectionTimers.has(workflowId)) {
+            return;
+        }
+        const timer = this.timers.setTimeout(() => {
+            this.projectionTimers.delete(workflowId);
+            const live = this.workflows.get(workflowId);
+            if (!live) {
+                return;
+            }
+            this.emit(this.projectSnapshot(live));
+        }, this.coalesceWindowMs);
+        timer.unref?.();
+        this.projectionTimers.set(workflowId, timer);
+    }
+    /**
+     * 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
+     * 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.
+     */
+    projectSnapshot(live) {
+        const base = live.snapshot;
+        if (isTerminalStatus(base.status)) {
+            return base;
+        }
+        const children = this.agentManager
+            .listAgents()
+            .filter((agent) => agent.labels?.[WORKFLOW_ID_LABEL] === base.id);
+        const projectedPhases = projectWorkflowPhases({
+            children,
+            taskGraph: live.graph,
+            terminalOutcomes: live.terminalOutcomes,
+        });
+        const progress = projectWorkflowProgress({
+            children,
+            taskGraph: live.graph,
+            terminalOutcomes: live.terminalOutcomes,
+        });
+        // 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) {
+                return phase;
+            }
+            return {
+                ...phase,
+                status: projected.status,
+                storyCount: projected.storyCount,
+                completedStoryCount: projected.completedStoryCount,
+            };
+        });
+        return {
+            ...base,
+            phases,
+            totalStoryCount: progress.totalStoryCount,
+            completedStoryCount: progress.completedStoryCount,
+        };
+    }
+    requireLive(workflowId) {
+        const live = this.workflows.get(workflowId);
+        if (!live) {
+            throw new WorkflowNotFoundError(workflowId);
+        }
+        return live;
+    }
+    async persist(live) {
+        await this.storage.saveWorkflow(live.snapshot);
+    }
+}
+/** A workflow in a terminal state can no longer be cancelled. */
+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) {
+        case "failed":
+            return "failed";
+        case "cancelled":
+            return "cancelled";
+        // `completedAt` is only ever stamped alongside a terminal status, so the
+        // remaining cases (completed / pending / running) all map to "completed".
+        default:
+            return "completed";
+    }
+}
+/**
+ * Derive the ordered lifecycle-event list from a snapshot's timestamps. Pure and
+ * deterministic - the same snapshot always yields the same events.
+ */
+function projectWorkflowEvents(snapshot) {
+    const events = [
+        { workflowId: snapshot.id, type: "created", status: "pending", at: snapshot.createdAt },
+    ];
+    if (snapshot.startedAt) {
+        events.push({
+            workflowId: snapshot.id,
+            type: "started",
+            status: "running",
+            at: snapshot.startedAt,
+        });
+    }
+    if (snapshot.completedAt) {
+        events.push({
+            workflowId: snapshot.id,
+            type: terminalEventType(snapshot.status),
+            status: snapshot.status,
+            at: snapshot.completedAt,
+        });
+    }
+    if (snapshot.archivedAt) {
+        events.push({
+            workflowId: snapshot.id,
+            type: "archived",
+            status: snapshot.status,
+            at: snapshot.archivedAt,
+        });
+    }
+    return events;
+}
+/** Map a workflow status to its terminal tag when the workflow is archived. */
+function terminalStatusForArchive(status) {
+    if (status === "completed" || status === "failed") {
+        return status;
+    }
+    // pending / running / cancelled -> a workflow torn down before finishing is cancelled.
+    return "cancelled";
+}
+//# sourceMappingURL=workflow-manager.js.map