@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/run-progress.js

@@ -0,0 +1,724 @@
+// Event-sourced recovery of a stopped attempt: what the journal says the run did.
+//
+// A run's journal is the record the engine wrote while it worked: every node it started, every
+// node it completed, and every edge its outcomes activated. Replaying those lines reconstructs the
+// scheduler's position — which nodes are done, how often they visited, which activations were
+// queued — without any new write path in the runner. This is the input to `runGraph`'s
+// `resumeFrom`: the resumed attempt seeds its scheduler from here, and a checkpoint (when one was
+// captured) re-enters the interrupted node's own conversation.
+//
+// What the journal cannot know is reconstructed rather than persisted: activations carry
+// generation, path, and edge-mapped inputs only in memory, so the replay recomputes the mapped
+// inputs from the graph's edge expressions and the completed source outputs, and re-derives the
+// generation and path from the edges the journal proves were routed. A resumed cycle needs those:
+// a frontier activation seeded with an empty path at generation zero classifies its back-edge as
+// an already-executed suppression instead of a revisit, and the resumed graph terminates where the
+// stopped one would have taken another lap.
+import { isDeepStrictEqual } from 'node:util';
+import { resolveValue } from './handoffs.js';
+import { PREPARE_STEPS } from './decision/PreparedSteps.js';
+import { canonicalToolName } from './tool-names.js';
+/**
+ * The tool names the runtime journals with `node.tool.started` but never charges to the
+ * graph-level tool budget (the metadata-call exemptions in the hardened runtime). Subagent copies
+ * of these tools do count to the child's own allowance — child calls never reach the graph budget
+ * either way — so excluding them by name is the faithful mirror for what the run actually spent.
+ */
+const metadataToolNames = new Set(['update_todos', 'update_widget', 'restore_tools', PREPARE_STEPS]);
+/**
+ * The tool calls a resume may issue a second time without repeating an effect the world can see:
+ * the read-only queries, the run-scoped metadata calls (todos, widgets, tool set, plan), and the
+ * question the stopped attempt had already put to the user — re-asking a crash-unanswered
+ * `ask_user` is the seamless continue, not a repeat hazard. Their calls change nothing outside the
+ * run, so a checkpoint that predates one still re-enters its node safely. Any other name — and
+ * any event the journal wrote without one — is treated as able to change the world, and keeps the
+ * re-entry refused until a checkpoint covers it. Names are matched in their canonical form, so a
+ * legacy spelling (`read_file`, `ls`) classifies like the tool it is.
+ */
+const effectFreeToolNames = new Set([
+    'Read', 'Grep', 'Glob',
+    'git_read', 'read_artifact', 'repo_explore', 'memory_search', 'read_skill_resource', 'expand_tool_output',
+    'ask_user',
+    ...metadataToolNames,
+]);
+/**
+ * Whether a journalled tool call could leave an effect a replay would repeat. An event without a
+ * name cannot be classified and is effectful: the boundary guard refuses on the conservative side.
+ */
+export function isEffectfulToolCall(name) {
+    return name === undefined || !effectFreeToolNames.has(canonicalToolName(name));
+}
+/**
+ * Fold a resumed attempt's own progress back onto the progress it inherited.
+ *
+ * Each attempt's journal records only the work that attempt did; everything carried in from
+ * earlier attempts came through seeding, not events. Walking a `resumedFrom` lineage oldest to
+ * newest with this fold rebuilds the full position for the next resume. Where the two disagree
+ * the newer attempt answers: it either completed the node (so the older frontier entry is spent)
+ * or replayed it into its own pending set (so that entry describes it better). An older frontier
+ * entry the newer attempt never touched stays queued — that attempt simply stopped before the
+ * scheduler reached it.
+ *
+ * A node's unfinished visit is the exception to "the newer attempt answers", because a resumed
+ * attempt re-enters it without journalling the activation that produced it: its replay sees the
+ * start and nothing else, so it has no generation, no trail, and no mapped inputs for a visit the
+ * earlier attempt had already described in full. One node holds at most one unfinished visit (the
+ * scheduler is sequential), so those entries fold per node instead of per identity: the newer
+ * attempt keeps whatever it did prove, the older one supplies what only its journal could.
+ */
+export function mergeRunProgress(older, newer) {
+    // Queued activations fold by (generation, node), mirroring the scheduler's queue identity: a
+    // cycle can leave the same node queued at two generations, and a per-node key would drop one.
+    const pendingByNode = new Map();
+    const reentryByNode = new Map();
+    const take = (activation) => {
+        const copy = { ...activation, inputs: { ...activation.inputs }, predecessors: { ...activation.predecessors } };
+        if (copy.path !== undefined)
+            copy.path = [...copy.path];
+        if (copy.interrupted)
+            reentryByNode.set(copy.nodeId, copy);
+        else
+            pendingByNode.set(`${copy.generation ?? 0}:${copy.nodeId}`, copy);
+        return copy;
+    };
+    // The same unfinished visit, described by two attempts: the newer attempt's journal answers for
+    // what it proved, the older attempt's entry is the only record of the identity the resumed
+    // attempt re-entered with and of the inputs its activation carried, neither of which the newer
+    // journal can show. Fill what is missing rather than discarding either account.
+    const mergeReentry = (held, older) => {
+        if (held.generation === undefined) {
+            held.generation = older.generation;
+            held.path = older.path;
+        }
+        if (Object.keys(held.inputs).length === 0)
+            held.inputs = { ...older.inputs };
+        if (Object.keys(held.predecessors).length === 0)
+            held.predecessors = { ...older.predecessors };
+        if (held.source === undefined && older.source !== undefined)
+            held.source = older.source;
+        if (held.sourceGeneration === undefined)
+            held.sourceGeneration = older.sourceGeneration;
+        if (held.parallelGroup === undefined) {
+            held.parallelGroup = older.parallelGroup;
+            if (older.concurrency !== undefined)
+                held.concurrency = older.concurrency;
+        }
+    };
+    for (const activation of newer.pending)
+        take(activation);
+    // The identities the newer attempt actually executed. An older frontier entry is spent only if the
+    // newer attempt ran THAT `(generation, node)` activation: a node can be queued at two generations,
+    // and completing one of them says nothing about the other — which the newer journal does not carry
+    // either (the visit was inherited through seeding, not journalled as a routing), so dropping it by
+    // node id would silently skip legitimate cyclic work.
+    const newExecuted = new Set(newer.executed ?? Object.keys(newer.nodeResults).map(nodeId => `${newer.generations?.[nodeId] ?? 0}:${nodeId}`));
+    const retiredByNewer = (activation) => newExecuted.has(`${activation.generation ?? 0}:${activation.nodeId}`);
+    for (const activation of older.pending) {
+        if (retiredByNewer(activation))
+            continue;
+        const reentry = reentryByNode.get(activation.nodeId);
+        if (activation.interrupted) {
+            if (reentry === undefined) {
+                take(activation);
+                continue;
+            }
+            mergeReentry(reentry, activation);
+            continue;
+        }
+        // A re-entry whose identity the newer journal could not prove belongs to this older activation
+        // — the visit the newer attempt re-entered is the work the older attempt had queued for that
+        // node (one node holds at most one unfinished visit). Leaving both would seed the same visit
+        // twice; dropping the older one would lose the inputs its activation carried.
+        if (reentry !== undefined && reentry.generation === undefined) {
+            mergeReentry(reentry, activation);
+            continue;
+        }
+        const key = `${activation.generation ?? 0}:${activation.nodeId}`;
+        if (pendingByNode.has(key))
+            continue;
+        take(activation);
+    }
+    const visits = { ...older.visits };
+    for (const [nodeId, count] of Object.entries(newer.visits))
+        visits[nodeId] = Math.max(visits[nodeId] ?? 0, count);
+    const todos = newer.todos ?? older.todos;
+    const widgets = newer.widgets ?? older.widgets;
+    const activeSkills = [...new Set([...(older.activeSkills ?? []), ...(newer.activeSkills ?? [])])];
+    const generations = { ...older.generations };
+    for (const [nodeId, generation] of Object.entries(newer.generations ?? {}))
+        generations[nodeId] = generation;
+    // Every executed key either attempt proved survives the fold: the resumed attempt runs with the
+    // union of both histories, so neither an older generation nor a newer one is offered a second
+    // run.
+    const executed = [...new Set([...(older.executed ?? []), ...(newer.executed ?? [])])];
+    // Tool boundaries keep the newest observation either attempt's journal holds.
+    const lastEffectfulToolEvent = { ...older.lastEffectfulToolEvent };
+    for (const [nodeId, time] of Object.entries(newer.lastEffectfulToolEvent ?? {})) {
+        if ((lastEffectfulToolEvent[nodeId] ?? '') < time)
+            lastEffectfulToolEvent[nodeId] = time;
+    }
+    // A waiting join survives the fold while the newer attempt neither ran it at that generation nor
+    // queued it. Where both attempts hold the same join at the same generation, the members merge:
+    // each attempt's crash window can strand a different branch, and replacing wholesale would lose
+    // the member only the older journal proves arrived. The newer attempt answers for a member it saw
+    // too — its replay read the longer journal.
+    const waitingByJoin = new Map();
+    for (const join of newer.waitingJoins ?? [])
+        waitingByJoin.set(`${join.generation}:${join.nodeId}`, { ...join, members: { ...join.members } });
+    for (const join of older.waitingJoins ?? []) {
+        if (retiredByNewer(join) || newer.pending.some(activation => activation.nodeId === join.nodeId && activation.generation === join.generation))
+            continue;
+        const held = waitingByJoin.get(`${join.generation}:${join.nodeId}`);
+        if (held)
+            held.members = { ...join.members, ...held.members };
+        else
+            waitingByJoin.set(`${join.generation}:${join.nodeId}`, join);
+    }
+    const waitingJoins = [...waitingByJoin.values()];
+    // Queue order is preserved rather than re-sorted: each attempt's own frontier already carries the
+    // order its scheduler would dequeue in (newest batch first), and the older attempt's entries were
+    // never reached by the newer one, so they stay behind everything it did reach.
+    const pending = [...reentryByNode.values(), ...pendingByNode.values()];
+    return {
+        nodeResults: { ...older.nodeResults, ...newer.nodeResults },
+        visits,
+        pending,
+        // Each attempt's journal carries only its own tool calls — what it inherited arrived through
+        // seeding — so the folds sum them rather than taking the newer count.
+        toolCalls: (older.toolCalls ?? 0) + (newer.toolCalls ?? 0),
+        generations,
+        executed,
+        ...(Object.keys(lastEffectfulToolEvent).length === 0 ? {} : { lastEffectfulToolEvent }),
+        // Generation numbers are per attempt, but the resumed scheduler draws fresh revisits with
+        // `++counter`; taking the maximum keeps that draw above every generation already executed.
+        generation: Math.max(older.generation ?? 0, newer.generation ?? 0),
+        ...(waitingJoins.length === 0 ? {} : { waitingJoins }),
+        ...(todos === undefined ? {} : { todos }),
+        ...(widgets === undefined ? {} : { widgets }),
+        ...(activeSkills.length === 0 ? {} : { activeSkills }),
+        ...(newer.stoppedStatus === undefined ? {} : { stoppedStatus: newer.stoppedStatus }),
+    };
+}
+/**
+ * Replay a run's journal into the scheduler position it had when the process stopped.
+ *
+ * The pass is intentionally simple: a node is behind only as many visits as it completed (a
+ * second start without a second completion is an interrupted visit, not finished work), edge
+ * activations are recomputed through the graph's own mapping expressions, and a truncated
+ * journal (a crash mid-append) still yields a sound position: the last line simply does not
+ * parse, and every fact here is derived only from whole events that did.
+ *
+ * Frontier rule: an activation is live while the target has not completed since it arrived. That
+ * keeps a cycle's re-activation pending even when an earlier visit completed, and retires
+ * activations that a later completion consumed. Arrivals merge per target so a join queued for
+ * several branches replays with every branch's result, not only the branch that completed last.
+ *
+ * An edge the runner never journalled is derived from the graph rather than lost: a completed
+ * source whose outcome matches an edge with no activation after that completion means the routing
+ * existed in memory (or was the next thing the scheduler would have done) and the crash ate the
+ * line — waiting joins are the classic case, but the completion-to-activation window is open for
+ * every node type, so every outcome-matching unfired edge reconstructs its arrival. Any-mode
+ * joins are the exception: they fire on the first arrival and journal that activation like any
+ * other node, so an unfired one was genuinely never routed.
+ *
+ * @param runScope - the `run.input`/`run.state` the resumed run will evaluate with, so edge
+ *   mappings that read run scope resolve to real values instead of nothing. It is the caller's
+ *   job to pass the scope the seeded activation will actually see; the replayed inputs must
+ *   match what the runner would have computed live.
+ */
+export function replayRunJournal(lines, graph, runScope) {
+    const nodeResults = {};
+    const visits = {};
+    const startCounts = new Map();
+    const completionCounts = new Map();
+    const lastCompletionAt = new Map();
+    // Every completion, in journal order. A cyclic source can complete several times while an
+    // earlier visit's routed target still sits unexecuted, and that target's activation was
+    // routed from the visit that was CURRENT when it was routed — looking the node up in the
+    // final `nodeResults` would map the edge with a later visit's output. Routing must replay
+    // the completion that preceded the activation's journal line, not the node's last one — and it
+    // must read that completion's OWN visit count: `$run.loop.iteration` is the completing visit's
+    // count, which a cyclic source's final aggregate count no longer is.
+    const completionsOf = new Map();
+    // The activation identity a visit was started with, when the writing build journalled it. A
+    // resumed attempt re-enters a node from seeded state, so its journal contains no routing for that
+    // visit: this stamp is the only record of the generation and trail the visit is running at, and
+    // without it a second crash would replay the re-entry as a generation-zero, ancestry-free
+    // activation — colliding with the checkpoint the visit wrote and misclassifying its back-edge.
+    const lastEffectfulToolEvent = {};
+    const startedGeneration = new Map();
+    const startedPath = new Map();
+    /** Where each node's last start line sits, so a re-entry can tell its own routing from a later one. */
+    const lastStartAt = new Map();
+    // Every (generation, node) key the journal proves executed. A node can complete at two
+    // generations while older-generation work is still queued, and the resumed scheduler suppresses
+    // per key: recording only the last generation would let the delayed activation run again.
+    const executedKeys = new Set();
+    let toolCalls = 0;
+    let todos;
+    let widgets;
+    const activeSkills = new Set();
+    let stoppedStatus;
+    let stoppedNode;
+    const activated = [];
+    const byId = new Map(Object.values(graph.nodes).map(node => [node.id, node]));
+    let index = 0;
+    for (const line of lines) {
+        index += 1;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const data = event.data ?? {};
+        const nodeId = typeof data.nodeId === 'string' ? data.nodeId : undefined;
+        if (event.type === 'graph.node.started' && nodeId) {
+            startCounts.set(nodeId, (startCounts.get(nodeId) ?? 0) + 1);
+            lastStartAt.set(nodeId, index);
+            const visit = typeof data.visit === 'number' && Number.isSafeInteger(data.visit) && data.visit > 0 ? data.visit : (visits[nodeId] ?? 0) + 1;
+            visits[nodeId] = Math.max(visits[nodeId] ?? 0, visit);
+            const generation = typeof data.generation === 'number' && Number.isSafeInteger(data.generation) && data.generation >= 0 ? data.generation : undefined;
+            const path = Array.isArray(data.path) && data.path.every(step => typeof step === 'string') ? data.path : undefined;
+            // A start without the stamp overwrites the previous visit's stamp with nothing: a stale stamp
+            // must never be read as this visit's identity.
+            if (generation === undefined)
+                startedGeneration.delete(nodeId);
+            else
+                startedGeneration.set(nodeId, generation);
+            if (path === undefined)
+                startedPath.delete(nodeId);
+            else
+                startedPath.set(nodeId, [...path]);
+        }
+        else if (event.type === 'graph.node.completed' && nodeId && byId.has(nodeId) && isCompletion(data.completion)) {
+            nodeResults[nodeId] = structuredClone(data.completion);
+            const history = completionsOf.get(nodeId) ?? [];
+            history.push({ at: index, completion: nodeResults[nodeId], iteration: startCounts.get(nodeId) ?? visits[nodeId] ?? 1, ...(startedGeneration.has(nodeId) ? { generation: startedGeneration.get(nodeId) } : {}) });
+            completionsOf.set(nodeId, history);
+            completionCounts.set(nodeId, (completionCounts.get(nodeId) ?? 0) + 1);
+            lastCompletionAt.set(nodeId, index);
+            visits[nodeId] = Math.max(visits[nodeId] ?? 1, visits[nodeId] ?? 0);
+            // A stamped start names the generation this completion ran at even when the routing that
+            // produced it is missing from this journal (a seeded re-entry). Unstamped journals get their
+            // keys from the routing bookkeeping after the reconstruction below.
+            const stamped = startedGeneration.get(nodeId);
+            if (stamped !== undefined)
+                executedKeys.add(`${stamped}:${nodeId}`);
+        }
+        else if (event.type === 'graph.edge.activated' && typeof data.source === 'string' && typeof data.target === 'string') {
+            activated.push({ index, source: data.source, target: data.target, outcome: typeof data.outcome === 'string' ? data.outcome : 'completed' });
+        }
+        else if (event.type === 'graph.skill.activated' && typeof data.skillId === 'string' && data.skillId.trim() && data.skillId.length <= 1200) {
+            activeSkills.add(data.skillId);
+        }
+        else if (event.type === 'graph.todos.updated' && Array.isArray(data.todos)) {
+            todos = data.todos.filter(isTodoItem);
+        }
+        else if (event.type === 'graph.widgets.updated' && Array.isArray(data.widgets)) {
+            widgets = widgetValues(data.widgets);
+        }
+        else if (event.type === 'node.tool.started' || event.type === 'node.tool.completed' || event.type === 'node.tool.failed') {
+            const toolName = typeof data.name === 'string' ? data.name : undefined;
+            // The tool boundary is what a checkpoint has to be newer than to be a sound re-entry point —
+            // for the calls that can repeat an effect. A read or a re-ask covers nothing: the replay
+            // issues the same query or re-poses the same question, so those calls do not strand the
+            // checkpoint behind them. The common desktop stop is exactly this shape — the process died
+            // while an `ask_user` answer was pending, with the question the only call after the last
+            // checkpoint — and it must continue, not be refused.
+            if (nodeId && typeof event.time === 'string' && isEffectfulToolCall(toolName) && (lastEffectfulToolEvent[nodeId] ?? '') < event.time)
+                lastEffectfulToolEvent[nodeId] = event.time;
+            if (event.type !== 'node.tool.started')
+                continue;
+            {
+                // Tool spends are journalled at start (agent tools by the runtime, action shells by the
+                // runner), but the runtime only charges non-metadata calls against the graph-level budget:
+                // `update_todos`, `update_widget`, `prepare_steps`, and `restore_tools` emit the journal
+                // event yet never
+                // touch `result.toolCalls`. Counting them here would hand the resumed scheduler a smaller
+                // allowance than an uninterrupted run of the same journal would have had.
+                if (toolName === undefined || !metadataToolNames.has(toolName))
+                    toolCalls += 1;
+            }
+        }
+        else if (event.type === 'graph.stopped') {
+            stoppedStatus = typeof data.status === 'string' ? data.status : undefined;
+            stoppedNode = nodeId;
+        }
+    }
+    // More starts than completions means a visit is still open — possibly several, when parallel
+    // branches started before any of them completed. Every open visit re-enters, in first-start
+    // order; one scalar would have kept only the last branch started and silently dropped the rest.
+    const interrupted = new Set();
+    for (const [nodeId, starts] of startCounts) {
+        if (starts > (completionCounts.get(nodeId) ?? 0) && byId.has(nodeId))
+            interrupted.add(nodeId);
+    }
+    // The stop names the node the runner was sitting on. Only a visit that did not complete counts:
+    // a stop recorded against a node whose starts all completed (the record is written at
+    // finalization, and the pointer can trail the work) does not put finished work back into flight.
+    if (stoppedNode !== undefined && Object.hasOwn(nodeResults, stoppedNode) === false && (startCounts.get(stoppedNode) ?? 0) > 0)
+        interrupted.add(stoppedNode);
+    // Arrivals are keyed by (generation, target), exactly like the scheduler's queue suppression: a
+    // cycle can leave the same target queued at two generations at once (one behind the back-edge,
+    // one behind the next lap), and a single per-node entry would run only one of the two visits.
+    const arrivals = new Map();
+    // The completion this routing used: the last one at or before the route's journal position.
+    // Journaled activations route from the visit current when they were written; reconstruction of
+    // a torn route uses the source's final completion (nothing was routed after it).
+    const routedCompletion = (source, order) => {
+        const history = completionsOf.get(source);
+        if (history === undefined || history.length === 0)
+            return undefined;
+        let found;
+        for (const entry of history) {
+            if (entry.at <= order)
+                found = entry;
+            else
+                break;
+        }
+        return found;
+    };
+    // The edge expressions run through the same evaluator the runner uses, against the run scope the
+    // resumed run will evaluate with. What the replay still cannot satisfy (an expression reading
+    // scope it was not given) is left absent rather than stored as an explicit `undefined`: an absent
+    // key lets the runner's configured-input merge and schema check treat it as missing, where an
+    // explicit undefined would trip a required-input validation and shadow a configured input using
+    // the same key.
+    // `iteration` is the visit count of the completion the edge is mapped from — the live scheduler
+    // routes an edge with the COMPLETING source's count as `$run.loop.iteration`, so replay must use
+    // that completion's own count: the source's final aggregate count would hand an activation
+    // routed from an earlier visit a later iteration, changing required inputs or downstream
+    // branching.
+    const edgeInputs = (edge, completion, iteration) => {
+        const inputs = {};
+        if (edge?.inputMapping)
+            for (const [key, expression] of Object.entries(edge.inputMapping)) {
+                try {
+                    inputs[key] = resolveValue(expression, { source: completion, run: { input: runScope?.input ?? {}, state: runScope?.state ?? {}, loop: { iteration } } });
+                }
+                catch (error) {
+                    // A mapping that cannot be evaluated is evidence about the stopped attempt only when this
+                    // replay was given the scope the live routing had: the run scope is restored from the
+                    // stopped attempt's own record, so an expression that throws here threw there too — and the
+                    // attempt stopped for it. Queueing the target without the key would let a resume do work
+                    // (or take a configured fallback) that the uninterrupted run explicitly rejected, so the
+                    // refusal is raised instead. A replay given no scope cannot tell the two apart, and there the
+                    // key is left absent for the runner's own input merge.
+                    if (runScope === undefined)
+                        continue;
+                    throw error;
+                }
+            }
+        return inputs;
+    };
+    const routeEdge = (source, target, outcome) => graph.edges.find(candidate => candidate.source === source && candidate.target === target && (candidate.outcome ?? 'completed') === outcome)
+        ?? graph.edges.find(candidate => candidate.source === source && candidate.target === target);
+    // An all-mode join's members merge their mapped inputs with the scheduler's conflict-aware merge:
+    // two members mapping different values to one key is a handoff the uninterrupted run explicitly
+    // rejected (graph-runner's mergeInputs throws), so replay must reject it too rather than let the
+    // last journaled arrival silently overwrite the first into a successful-but-wrong resume.
+    const mergeArrivalInputs = (target, incoming, targetId) => {
+        for (const [key, value] of Object.entries(incoming)) {
+            if (Object.hasOwn(target, key) && !isDeepStrictEqual(target[key], value))
+                throw new Error(`Node ${targetId}: conflicting input "${key}" from incoming routes. Rename the mappings or use matching values.`);
+            target[key] = value;
+        }
+    };
+    const recordArrival = (order, source, target, outcome, generation, path, sourceGeneration) => {
+        const routed = routedCompletion(source, order);
+        const completion = routed?.completion ?? nodeResults[source];
+        const targetNode = byId.get(target);
+        if (!completion || !targetNode)
+            return;
+        // A completion consumes the activations of ITS OWN visit, not every earlier one: a target can be
+        // queued at two generations (a cycle parks one behind the back-edge) and complete the later one
+        // first, and the older-generation arrival is still owed. Only a completion at this arrival's
+        // generation, journaled after it, spends it — an unstamped journal (whose visits carry no
+        // generation) keeps the older, conservative rule.
+        if ((completionsOf.get(target) ?? []).some(entry => entry.at >= order && (entry.generation === undefined || entry.generation === generation)))
+            return;
+        const key = `${generation}:${target}`;
+        // The batch this activation was routed in: one completion's routing is one batch, and the live
+        // scheduler puts the whole batch at the FRONT of its queue (`queue.unshift(...next)`), so the
+        // batch a node was activated in — not the individual activation's journal position — is what
+        // orders it against the other queued work.
+        const batchOrder = routed?.at ?? order;
+        let arrival = arrivals.get(key);
+        if (!arrival) {
+            arrival = { nodeId: target, order, batchOrder, generation, path: [...path], predecessors: {}, inputs: {}, lastIndex: order, sourceGeneration };
+            arrivals.set(key, arrival);
+        }
+        arrival.batchOrder = Math.max(arrival.batchOrder, batchOrder);
+        arrival.predecessors[source] = completion;
+        // The journal's own outcome picks the edge first: a source that routes to one target over two
+        // outcome-specific edges must not always resolve through whichever the graph lists first.
+        mergeArrivalInputs(arrival.inputs, edgeInputs(routeEdge(source, target, outcome), completion, routed?.iteration ?? visits[source] ?? 1), target);
+        // A branch-mode parallel node stamps every activation its completion dispatches with one
+        // group id; the completing visit's journal line identifies the group (two visits of the same
+        // parallel node are two groups), and the resumed scheduler needs the stamp to share the tool
+        // budget and the branch todo store across the group the way the live scheduler does.
+        const sourceNode = byId.get(source);
+        if (sourceNode?.modifiers?.parallel?.mode === 'branches') {
+            arrival.parallelGroup = `${source}:${routed?.at ?? 'unrouted'}`;
+            arrival.concurrency = sourceNode.modifiers.parallel.maxConcurrent;
+        }
+        // `source`/`sourceGeneration` describe the completion the activation was actually routed from:
+        // the newest one, which `routedCompletion` picked for the mapping above.
+        if (order >= arrival.lastIndex) {
+            arrival.source = completion;
+            arrival.sourceGeneration = sourceGeneration;
+            arrival.lastIndex = order;
+        }
+        arrival.order = Math.min(arrival.order, order);
+    };
+    // The runner's cycle bookkeeping — the generation an activation runs at, and the node trail
+    // (path) by which it recognizes a back-edge as a revisit — exists only in memory. Reconstruct it
+    // from the edges the journal proves were routed (a suppressed edge emitted nothing, so this
+    // sees only routings the scheduler performed), mirroring its rules: an edge back into a node
+    // already on the trail opens a new generation and starts a fresh trail; any other edge carries
+    // the source's generation and extends its trail. An all-mode join carries the union of its
+    // members' trails, as the scheduler merges them when the join fires.
+    let generation = 0;
+    const genOf = new Map();
+    const pathOf = new Map();
+    if (byId.has(graph.entry)) {
+        genOf.set(graph.entry, 0);
+        pathOf.set(graph.entry, []);
+    }
+    // A visit this journal only STARTS (the node was re-entered from seeded state) states its own
+    // generation and trail on that start line, and the edges it routes afterwards are read against
+    // exactly those: without this primer the routing bookkeeping would hold generation zero and an
+    // empty trail for it, and reconstruct its successors with the wrong ancestry — losing a revisit,
+    // or suppressing one the stopped attempt still owed. A journaled routing into the same node
+    // overwrites the primer below, so the derivation still answers wherever it has evidence.
+    for (const [nodeId, generation] of startedGeneration) {
+        if (genOf.has(nodeId))
+            continue;
+        genOf.set(nodeId, generation);
+        pathOf.set(nodeId, [...(startedPath.get(nodeId) ?? [])]);
+    }
+    // Routing bookkeeping is split into plan and commit: a reconstruction that turns out to be a
+    // suppression must leave the generation counter and every trail untouched. The suppressed route
+    // was never performed by the scheduler, and committing its ancestry handed the accepted arrival
+    // a trail the stopped attempt never held — losing a revisit the accepted path still owed.
+    const routePlan = (source, target) => {
+        const trail = [...(pathOf.get(source) ?? []), source];
+        const isRevisit = trail.includes(target);
+        const targetNode = byId.get(target);
+        return {
+            isRevisit,
+            generation: isRevisit ? generation + 1 : genOf.get(source) ?? 0,
+            path: isRevisit ? []
+                : targetNode?.type === 'join' && targetNode.join?.mode !== 'any'
+                    ? [...new Set([...(pathOf.get(target) ?? []), ...trail])]
+                    : trail,
+        };
+    };
+    const commitRoute = (target, plan) => {
+        if (plan.isRevisit)
+            generation = plan.generation;
+        genOf.set(target, plan.generation);
+        pathOf.set(target, plan.path);
+    };
+    // The generation a node's latest work belongs to: the start stamp when the writing build left
+    // one, the routing bookkeeping otherwise.
+    const lastGenerationOf = (nodeId) => startedGeneration.get(nodeId) ?? genOf.get(nodeId) ?? 0;
+    const routeIn = (source, target) => { commitRoute(target, routePlan(source, target)); };
+    const journaledKeys = new Set();
+    // Journaled activations record their arrival at the generation their own routing committed —
+    // a target queued at generation 0 and re-queued at generation 1 leaves two arrivals, the way
+    // two activations sat in the live queue.
+    for (const event of activated) {
+        // The routing predecessor's own generation, read before the routing commits (a self-edge would
+        // otherwise overwrite it): the successor inherits its predecessor's conversation only if the
+        // checkpoint file still holds THAT visit.
+        const sourceGeneration = genOf.get(event.source) ?? 0;
+        routeIn(event.source, event.target);
+        const eventGeneration = genOf.get(event.target) ?? 0;
+        journaledKeys.add(`${eventGeneration}:${event.target}`);
+        recordArrival(event.index, event.source, event.target, event.outcome, eventGeneration, pathOf.get(event.target) ?? [], sourceGeneration);
+    }
+    // An outcome-matching edge with no activation journalled after its source's last completion was
+    // routed in memory (or was the scheduler's next act) and lost its line to the crash. The window
+    // between journaling a completion and journaling its routing is open for every edge — bootstrap
+    // routes and edges into any-mode joins included: an any-mode join journals its activation as
+    // soon as it routes, so an unfired one was lost mid-window, not never routed. But an absent
+    // line is also how a deliberately suppressed route looks: the scheduler queues a target once
+    // per generation and drops every later route into the same (generation, target) key without
+    // journalling. Reconstruction must reproduce that suppression — merging a suppressed route's
+    // inputs into the one the scheduler actually took would hand the target data the uninterrupted
+    // run never accepted.
+    const waiting = new Map();
+    // The executed set also answers for the routings this replay derives below (a node that ran has
+    // its generation committed by the edges around it), so every key the routing bookkeeping proves
+    // joins the ones the start stamps proved.
+    for (const nodeId of Object.keys(nodeResults))
+        executedKeys.add(`${lastGenerationOf(nodeId)}:${nodeId}`);
+    const reconstructedKeys = new Set();
+    for (const [source, completion] of Object.entries(nodeResults)) {
+        for (const edge of graph.edges) {
+            if (edge.source !== source)
+                continue;
+            if ((edge.outcome ?? 'completed') !== (completion.outcome ?? 'completed'))
+                continue;
+            const at = lastCompletionAt.get(source) ?? -1;
+            if (activated.some(event => event.source === source && event.target === edge.target && event.index > at))
+                continue;
+            const targetNode = byId.get(edge.target);
+            const plan = routePlan(source, edge.target);
+            const targetKey = `${plan.generation}:${edge.target}`;
+            const allJoin = targetNode?.type === 'join' && targetNode.join?.mode !== 'any';
+            // Every member arrival an all-mode join is missing is work the scheduler demanded, never a
+            // suppression — its routes share one (generation, target) key by design, journaled member
+            // activations included. For every other target the key suppresses: a journaled activation
+            // or an executed node at this key proves the arrival is there (or already spent), and a
+            // prior reconstruction owns the key the same way a queued target queued once per generation.
+            if (!allJoin && (journaledKeys.has(targetKey) || executedKeys.has(targetKey) || reconstructedKeys.has(targetKey)))
+                continue;
+            const sourceGeneration = genOf.get(source) ?? 0;
+            // Only an accepted route commits: a suppressed plan above must leave the generation counter
+            // and the trails exactly as the scheduler left them.
+            commitRoute(edge.target, plan);
+            if (!allJoin)
+                reconstructedKeys.add(targetKey);
+            // Whether an all-mode join has already fired is asked per generation: a join inside a cycle
+            // fires once per generation, and an earlier generation's firing must not read as this
+            // generation's — a later-generation crash after one predecessor completed but before its
+            // edge activation was journalled has to go back into the waiting state, or the resume would
+            // run the join on the single arrival it can see while the other branch still owes its work.
+            if (allJoin && !edge.bootstrap && !journaledKeys.has(targetKey) && !executedKeys.has(targetKey)) {
+                // An arrival this generation can accept is one from a member whose latest work COMPLETED
+                // here: a member still inside a visit never produced the completion this join is waiting
+                // for, and one whose last completion belongs to an earlier generation produced it for that
+                // lap. Reconstructing either would hand the fired join an input the uninterrupted run never
+                // gave it — the member's own interrupted re-entry routes its arrival when it completes, so
+                // the join waits instead.
+                if (interrupted.has(source) || lastGenerationOf(source) !== plan.generation)
+                    continue;
+                // An all-mode join holds each arrival in the scheduler's waiting state until every branch
+                // has arrived — the journal proves only the completed branches. Putting the join on the
+                // executable frontier would run it with the finished branches' inputs while the interrupted
+                // branch still owes its work: seed the waiting state instead, and the join fires when the
+                // resumed completion brings the member this map lacks. Member trails union the way the
+                // scheduler unions them when the join fires.
+                const entry = waiting.get(targetKey) ?? { nodeId: edge.target, generation: plan.generation, path: [], members: {} };
+                entry.path = [...new Set([...entry.path, ...plan.path])];
+                entry.members[source] = { completion: structuredClone(completion), inputs: edgeInputs(edge, completion, startCounts.get(source) ?? visits[source] ?? 1) };
+                waiting.set(targetKey, entry);
+                continue;
+            }
+            recordArrival(at, source, edge.target, edge.outcome ?? 'completed', plan.generation, plan.path, sourceGeneration);
+        }
+    }
+    // Every dependency arrived on a join that never journaled its firing means the crash landed
+    // inside the runner's own fire step (it journals each member's activation, then queues the join,
+    // without a surviving in-between state): complete the fire as a live arrival rather than leave
+    // the join waiting for a branch that has already completed. "Arrived" is asked per generation:
+    // every member's final work has to be a COMPLETED visit at this generation, or a branch that
+    // finished an earlier lap would answer for work this lap still owes and the resumed join would
+    // run with its inputs missing.
+    for (const [key, entry] of [...waiting]) {
+        const dependencies = graph.edges.filter(candidate => candidate.target === entry.nodeId && !candidate.bootstrap);
+        if (!dependencies.every(candidate => {
+            const done = nodeResults[candidate.source];
+            return done !== undefined && (candidate.outcome ?? 'completed') === (done.outcome ?? 'completed')
+                && !interrupted.has(candidate.source) && lastGenerationOf(candidate.source) === entry.generation;
+        }))
+            continue;
+        waiting.delete(key);
+        for (const member of Object.keys(entry.members))
+            recordArrival(lastCompletionAt.get(member) ?? -1, member, entry.nodeId, nodeResults[member]?.outcome ?? 'completed', entry.generation, entry.path, genOf.get(member) ?? 0);
+    }
+    const pending = [];
+    const groupFields = (arrival) => arrival?.parallelGroup === undefined
+        ? {}
+        : { parallelGroup: arrival.parallelGroup, ...(arrival.concurrency === undefined ? {} : { concurrency: arrival.concurrency }) };
+    // Re-entries first: the nodes the attempt died inside are what the user stopped in the middle
+    // of, and each carries the mapped inputs the activation routed it — a re-entry with empty
+    // inputs would fail the node's own schema checks on resume.
+    const consumedArrivals = new Map();
+    for (const nodeId of interrupted) {
+        // The visit's own activation. When this build started it, the start stamp names it exactly.
+        // Otherwise it is the newest arrival routed BEFORE the visit's start — never the node's last
+        // committed routing, which can belong to a different activation that is still queued (a cycle
+        // can park one behind the back-edge while the node runs). A seeded visit has no routing in
+        // this journal at all: then both fields stay absent rather than borrowing the stamp of a
+        // different activation — and the fold takes them from the earlier attempt that proved them.
+        const arrival = [...arrivals.values()].filter(candidate => candidate.nodeId === nodeId && candidate.order < (lastStartAt.get(nodeId) ?? Infinity)).sort((left, right) => right.order - left.order)[0];
+        if (arrival)
+            consumedArrivals.set(nodeId, arrival);
+        const stamped = startedGeneration.has(nodeId) && startedPath.has(nodeId);
+        const generation = stamped ? startedGeneration.get(nodeId) : arrival?.generation;
+        const path = stamped ? startedPath.get(nodeId) : arrival?.path;
+        pending.push({
+            nodeId,
+            inputs: arrival?.inputs ?? {},
+            predecessors: arrival?.predecessors ?? {},
+            ...(arrival?.source === undefined ? {} : { source: arrival.source }),
+            ...(arrival?.sourceGeneration === undefined ? {} : { sourceGeneration: arrival.sourceGeneration }),
+            interrupted: true,
+            ...(generation === undefined ? {} : { generation }),
+            ...(path === undefined ? {} : { path }),
+            ...groupFields(arrival),
+        });
+    }
+    // Then the queued activations, in the order the interrupted scheduler would have dequeued them:
+    // its newest routed batch sits at the FRONT of the queue (`queue.unshift(...next)`), and the
+    // activations within one batch keep the edge order they were routed in. Ordering the frontier by
+    // journal position instead runs the oldest batch first, so a resumed run can observe or mutate
+    // the workspace in a different order than the uninterrupted one and produce different outputs.
+    const queueOrder = [...arrivals.values()].sort((left, right) => right.batchOrder - left.batchOrder || left.order - right.order);
+    for (const arrival of queueOrder) {
+        // The arrival a re-entry already answered for is not queued work of its own; any OTHER arrival
+        // for that node is, and stays on the frontier as its own activation.
+        if (consumedArrivals.get(arrival.nodeId) === arrival)
+            continue;
+        pending.push({
+            nodeId: arrival.nodeId,
+            inputs: arrival.inputs,
+            predecessors: arrival.predecessors,
+            ...(arrival.source === undefined ? {} : { source: arrival.source }),
+            ...(arrival.sourceGeneration === undefined ? {} : { sourceGeneration: arrival.sourceGeneration }),
+            generation: arrival.generation,
+            path: [...arrival.path],
+            ...groupFields(arrival),
+        });
+    }
+    const generations = {};
+    for (const nodeId of Object.keys(nodeResults))
+        generations[nodeId] = genOf.get(nodeId) ?? 0;
+    return {
+        nodeResults, visits, pending, toolCalls, generations, executed: [...executedKeys], generation,
+        ...(Object.keys(lastEffectfulToolEvent).length === 0 ? {} : { lastEffectfulToolEvent }),
+        ...(waiting.size === 0 ? {} : { waitingJoins: [...waiting.values()] }),
+        ...(todos === undefined ? {} : { todos }),
+        ...(widgets === undefined ? {} : { widgets }),
+        ...(activeSkills.size === 0 ? {} : { activeSkills: [...activeSkills] }),
+        ...(stoppedStatus === undefined ? {} : { stoppedStatus }),
+    };
+}
+function isCompletion(value) {
+    return typeof value === 'object' && value !== null
+        && typeof value.summary === 'string'
+        && Array.isArray(value.tests);
+}
+function isTodoItem(value) {
+    return typeof value === 'object' && value !== null && typeof value.id === 'string'
+        && typeof value.text === 'string'
+        && typeof value.status === 'string';
+}
+/** Widget id-to-value pairs from a snapshot event; entries without both are dropped. */
+function widgetValues(widgets) {
+    const values = {};
+    for (const widget of widgets) {
+        if (typeof widget !== 'object' || widget === null)
+            continue;
+        const id = widget.id;
+        const value = widget.value;
+        if (typeof id === 'string' && typeof value === 'string' && value.trim())
+            values[id] = value;
+    }
+    return values;
+}