@memberjunction/task-graph 6.1.0-edge.1 → 6.1.0-edge.3

package/dist/TaskGraphDispatcher.d.ts

@@ -1,6 +1,6 @@
 import { UserInfo } from '@memberjunction/core';
 import { IShutdownable } from '@memberjunction/global';
-import { ProviderFactory, TaskAgentRunner, TaskGraphDispatcherConfig, type TaskContinuationDeliverer, type TaskGraphObserver } from './types.js';
+import { ProviderFactory, TaskActionRunner, TaskAgentRunner, TaskPromptRunner, TaskGraphDispatcherConfig, type TaskContinuationDeliverer, type TaskGraphObserver } from './types.js';
 export declare class TaskGraphDispatcher implements IShutdownable {
     private readonly providerFactory;
     private readonly agentRunner;
@@ -16,18 +16,105 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * announces nothing.
      */
     private readonly observer?;
+    /**
+     * Optional. Absent means this host cannot run action nodes; they stay Pending and visible
+     * rather than being failed, because "nobody here can run this" is not "this ran and broke".
+     */
+    private readonly actionRunner?;
+    /**
+     * Optional. Absent means this host cannot run prompt nodes; they stay Pending and visible
+     * rather than being failed, for the same reason action nodes do.
+     */
+    private readonly promptRunner?;
     private readonly config;
     private readonly claims;
+    /**
+     * Edges already reported as unevaluable, so the report is once per transition and not once per
+     * poll. Per-instance and in-memory by design: a restart re-reports, which is the right amount of
+     * noise for a condition that is still broken after a restart.
+     */
+    private readonly reportedUnevaluableConditions;
+    /** Resolved once it EXISTS; null while it does not, so a fresh install is not cached blind. */
+    private cachedWorkflowTaskTypeID;
+    /**
+     * Graphs this instance is still trying to settle, with how many passes it has spent trying.
+     *
+     * **The sweep's window is on `__mj_UpdatedAt`, and a failing pass writes nothing** — the terminal
+     * write returns rowcount 0 because the row is already terminal, the layout pass touches only
+     * children, a refused CAS writes nothing at all. So a graph that fails to settle stops advancing
+     * its own timestamp and, after 24h of futile retries, ages out of the steady-state window while
+     * the process is up. The doc comment claimed the bound was "on abandonment, not age"; for this
+     * case it was on age, and R2-2's deferral made the case ordinary rather than exotic.
+     *
+     * In memory rather than a touch column because the alternative is a write on every failed
+     * attempt — more load exactly when something is already wrong — and because a restart is covered
+     * by the wide startup sweep, which is the durable backstop this leans on.
+     */
+    private readonly retryingSettlement;
+    /**
+     * Graphs whose settled-branch ANNOUNCEMENTS have already been made by this process.
+     *
+     * Re-entry is the point of the rescue, but only the parts that failed should repeat. Layout and
+     * the `GraphSettled` frame are idempotent facts about a finished graph, so a graph stuck in
+     * retry was re-persisting geometry and re-emitting the same frame every poll — for the whole
+     * 24h window, for as long as it kept failing.
+     */
+    private readonly announcedSettlements;
+    /** Graphs already reported as settled-but-undeliverable by this instance. */
+    private readonly reportedUndeliverable;
+    /** Live claim heartbeats by task ID, so the drain can silence the ones it gives up waiting for. */
+    private readonly heartbeats;
+    /** Latched once the drain has given up waiting, so a late arrival does not re-register. */
+    private heartbeatsPurged;
     private readonly conditionEvaluator;
     private running;
     private pollTimer;
     private reconcileTimer;
+    private unregisterKick;
     /** Tasks this instance is currently executing — bounds concurrency and drives heartbeats. */
     private readonly inFlight;
     /** Guards against a slow poll overlapping the next tick. */
     private polling;
+    /**
+     * Timer-driven passes currently running — poll and reconcile alike.
+     *
+     * A counter rather than a boolean because the two timers overlap by design, and `Stop()` has to
+     * wait for BOTH. Neither pass is held by anything else: they are launched `void`-ed from
+     * `setInterval`, so without this they are unobservable from the outside and a stopped dispatcher
+     * keeps writing.
+     */
+    private activePasses;
     /** Graph → owning user, from the parent's durable metadata. Ownership never changes, so this never goes stale. */
     private readonly ownerByParentID;
+    /** Monotonic pass counter for `PassCompleted` frames, so a viewer can order and gap-detect ticks. */
+    private passCounter;
+    /**
+     * Debug state per graph, cached for ONE pass. `pollOnce` clears it at entry, so within a pass
+     * the claim filter and the propagation loop read the same state (loading it twice could see a
+     * pause land between them and gate half a pass), and across passes a control verb written by any
+     * instance is picked up within one poll interval.
+     */
+    private readonly debugStateByGraph;
+    /**
+     * The pause state last announced per graph, so `GraphPaused`/`GraphResumed` are emitted on the
+     * TRANSITION rather than every pass — the verbs write durable state, not events, and it is this
+     * instance's job to notice the change and say so exactly once.
+     */
+    private readonly announcedPaused;
+    /**
+     * The verdict last emitted per gating edge. `GateDecision` frames announce CHANGES: edges are
+     * re-resolved every pass, and an unconditional emission would repeat every few seconds for as
+     * long as the graph lives — the frame-topic version of the log flood
+     * `logUnevaluableConditionOnce` exists to prevent.
+     *
+     * Nested by graph so a settled run's entries go in one delete. Flat per-edge maps in a process
+     * that runs for weeks are a slow leak with no upper bound but the table's size.
+     */
+    private readonly emittedGateVerdicts;
+    /** Last `NodeProgress` emission per task, for rate limiting chatty runners. Nested by graph. */
+    private readonly nodeProgressLastEmit;
+    /** Minimum interval between `NodeProgress` frames for one task. */
+    private static readonly NODE_PROGRESS_MIN_INTERVAL_MS;
     constructor(providerFactory: ProviderFactory, agentRunner: TaskAgentRunner, contextUser: UserInfo, config: Partial<TaskGraphDispatcherConfig> & Pick<TaskGraphDispatcherConfig, 'InstanceID'>, 
     /**
      * Optional. Absent means a host that cannot post messages or start agent turns — a worker,
@@ -39,7 +126,17 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * Optional. Absent means nobody is watching — the dispatcher behaves identically, it just
      * announces nothing.
      */
-    observer?: TaskGraphObserver);
+    observer?: TaskGraphObserver, 
+    /**
+     * Optional. Absent means this host cannot run action nodes; they stay Pending and visible
+     * rather than being failed, because "nobody here can run this" is not "this ran and broke".
+     */
+    actionRunner?: TaskActionRunner, 
+    /**
+     * Optional. Absent means this host cannot run prompt nodes; they stay Pending and visible
+     * rather than being failed, for the same reason action nodes do.
+     */
+    promptRunner?: TaskPromptRunner);
     /**
      * Announce something that happened, and never let the announcement matter.
      *
@@ -48,6 +145,15 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * careful means one place enforces it.
      */
     private emit;
+    /**
+     * A progress sink for one task's runner, rate-limited into `NodeProgress` frames.
+     *
+     * Rate-limited HERE rather than asking every runner to be polite, for the same reason `emit`
+     * swallows observer throws in one place: a chatty runner (an agent streaming token-level
+     * updates) must not be able to flood the topic, and the limit belongs to the announcement, not
+     * the work. A 100% report always passes — the terminal update is the one a viewer must not lose.
+     */
+    private nodeProgressEmitter;
     /**
      * Who a graph belongs to, memoized for the process's lifetime.
      *
@@ -61,6 +167,33 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * Skipped entirely when nobody is observing — the lookup exists only to address frames.
      */
     private resolveOwner;
+    /**
+     * A graph's debug state, cached for the current pass.
+     *
+     * Read fresh (BypassCache) because the state is written by direct `JSON_MODIFY` statements that
+     * fire no cache invalidation — the same reason every row read in this class bypasses the cache.
+     */
+    private readDebugState;
+    /**
+     * Reads the debug bag for a set of graphs in ONE query, priming the per-pass cache.
+     *
+     * Batched because both loops in a pass — propagation and claiming — walk every active graph, so
+     * a per-graph read made observability cost scale with the number of live workflows on a path
+     * that is meant to be flat. One `ID IN (…)` per pass costs the same whether a server is running
+     * one workflow or fifty.
+     *
+     * Already-cached graphs are skipped, so calling this from both loops is free the second time.
+     */
+    private primeDebugStates;
+    /**
+     * Announces a graph's pause-state TRANSITION, once, whichever instance notices first in its own
+     * frame stream.
+     *
+     * Per-instance dedup rather than a CAS: frames are advisory commentary, and a viewer receiving
+     * the transition from two instances is a duplicate line, not a duplicate execution — the price
+     * of a cross-instance guard here would be a write on every pass for a purely cosmetic guarantee.
+     */
+    private announcePauseTransition;
     /**
      * Begins dispatching.
      *
@@ -70,7 +203,23 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      */
     Start(): Promise<void>;
     /**
-     * Stops accepting new work and waits for in-flight tasks to finish.
+     * Stops accepting new work and waits for everything already started to finish.
+     *
+     * **"Everything" includes the timer passes, and that is the fix.** This waited only on
+     * `inFlight` — the task executions — while a poll pass is a `void`-ed promise nothing held. So
+     * `Stop()` returned while a pass was mid-flight, and that pass went on to settle graphs, emit
+     * lifecycle frames and CLAIM NEW TASKS afterwards. Three consequences, all of them quiet:
+     *
+     *  - a `GraphSettled` frame arrived after every subscriber had gone, so the settlement was
+     *    invisible to exactly the viewer watching for it;
+     *  - a process shutting down claimed work it was about to abandon, leaving claims to expire —
+     *    the orphaned-claim state reconciliation exists to clean up, manufactured by the shutdown;
+     *  - the host reused the connection the moment `Stop()` resolved, and the still-running pass's
+     *    statements collided with it (`Requests can only be made in the LoggedIn state`).
+     *
+     * A pass is bookkeeping for work that already happened, so it is DRAINED rather than cancelled:
+     * abandoning one halfway is the crash window the unsettled sweep exists to rescue, and choosing
+     * to open it on every clean shutdown would be perverse.
      *
      * Deliberately does NOT release claims on the way out: an abandoned claim expires on its own,
      * and releasing eagerly would hand a still-running task to another instance mid-execution.
@@ -89,6 +238,23 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * that shape indicates tampering or a bug and Record Changes already carries the audit trail.
      */
     Reconcile(): Promise<void>;
+    /**
+     * Announces expired claims the sweep just released, so a viewer watching the graph sees "the
+     * step's worker vanished and the engine requeued it" as it happens.
+     *
+     * Best-effort by contract: the release already succeeded and is the durable truth; a frame that
+     * cannot be addressed (row unloadable, no parent) is dropped, never retried.
+     */
+    private announceReclaims;
+    /** The reconciliation body. Wrapped by {@link Reconcile} so `Stop()` can drain it. */
+    private reconcileOnce;
+    /**
+     * Run a pass now instead of waiting for the next poll tick.
+     *
+     * Submit calls this (via {@link KickTaskGraphDispatchers}) so a just-written graph is claimed
+     * in milliseconds rather than up to {@link TaskGraphDispatcherConfig.PollIntervalSeconds}.
+     */
+    Kick(): void;
     /**
      * One dispatch pass: find claimable work, claim what fits under the concurrency cap, execute.
      *
@@ -110,6 +276,105 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * graph is wedged — are delegated to the pure algorithms, unchanged from Phase 1.
      */
     private propagateAndRollup;
+    /**
+     * Credits a finished graph's spending back to the agent run that submitted it.
+     *
+     * **Why this cannot happen during the run.** `BaseAgent` totals a run by walking its steps in
+     * memory at finalization — but a submitting run *ends at submission*. Submit-and-detach is the
+     * point: the run returns as soon as the graph is durable, and the graph executes afterwards,
+     * possibly minutes later on a different instance. At the moment the run computes its totals the
+     * spending has not happened yet, so there is nothing to count. The only place the number can be
+     * known is here, when the graph settles.
+     *
+     * **Why the `…Rollup` columns and not the plain ones.** `AIAgentRun` has carried six `…Rollup`
+     * columns since v3 that nothing has ever written — they exist for exactly this distinction:
+     *
+     * - `TotalCost` — what the run itself spent. For a Flow agent that is genuinely near zero: it
+     *   compiled a graph and handed it off. This value is already final and is never rewritten here,
+     *   so nothing that reads it today changes meaning, and no guardrail that already evaluated
+     *   against it is retroactively falsified.
+     * - `TotalCostRollup` — the run plus everything it caused. Provisional until the graph settles,
+     *   which is now.
+     *
+     * **The tree is the authority; these columns are its settlement-time cache.** The total is a SUM
+     * over `GetAgentRunTree`, not arithmetic of its own. The previous version walked the graph's
+     * child tasks and added each one's agent run, which was wrong in two ways that no test could
+     * see: a `Prompt` task has no agent run at all, so every prompt step's spend was simply missing;
+     * and it read each nested run's `…Rollup ?? …Total`, mixing a descendant-inclusive number with an
+     * own-spend one and depending on whether that nested graph happened to have settled yet. The
+     * tree already models every one of those cases — it reaches prompt runs through
+     * `Configuration.runtime.promptRunID`, and it descends into nested runs and their graphs
+     * structurally — so summing it cannot disagree with what the run viewer shows, because it IS
+     * what the run viewer shows.
+     *
+     * **This refuses rather than guesses.** A tree that failed to load, hit the depth cap, or does
+     * not contain the settling graph would still produce a number — a lower bound. Writing one would
+     * put an authoritative-looking total in a column every cost surface reads. Each of those cases
+     * logs and leaves the column alone, so `?? TotalCost` keeps its honest meaning: not settled.
+     *
+     * A graph with no submitting run (a scheduled job, a remote-operation caller) simply has nobody
+     * to credit — its own Task rows still carry the truth, and this returns quietly.
+     */
+    private rollUpCostToSubmittingRun;
+    /**
+     * Clears a rollup that can no longer be trusted, and says why.
+     *
+     * **Why clear rather than leave.** The four `…Rollup` columns are a cache of the run tree, and
+     * every reader treats a value there as the total. When the tree cannot be summed, any value
+     * already in the column was computed from an EARLIER settlement — it excludes the graph that
+     * just finished, so it is not merely incomplete, it is a wrong total presented as a right one.
+     * `?? TotalCost` protects a reader from null, not from stale.
+     *
+     * Nulling restores the invariant this whole design rests on: **when the column is present, it
+     * equals the tree.** Absent means not settled, which is exactly what a reader should conclude.
+     * A run with no rollup yet is untouched — there is nothing stale to clear, and writing nulls
+     * over nulls would churn Record Changes for nothing.
+     */
+    private clearStaleRollup;
+    /**
+     * Whether the settling graph is actually reachable from the submitting run's tree.
+     *
+     * Matched on the graph's parent Task id, which is the node the `TaskGraph` member of the query
+     * emits. A run that submitted a graph but recorded no `parentTaskID` produces a tree that stops
+     * at the run — structurally indistinguishable, at the SUM, from a run that never dispatched
+     * anything. This is the check that tells those two apart.
+     */
+    private treeContainsGraph;
+    /**
+     * Ends a graph early because a prompt said the work is finished.
+     *
+     * **Why `Skipped` and not `Cancelled`.** Nothing went wrong and nobody intervened — the workflow
+     * reached its own conclusion before running every drawn step, which is exactly what a reasoning
+     * step is for. `Cancelled` would tell a reader someone stopped it; `Skipped` says these routes
+     * were not taken, which is true and already the vocabulary the fork machinery uses.
+     *
+     * The message is written to the parent so the graph carries its own answer, rather than the
+     * answer living only on the step that produced it.
+     */
+    private endGraphEarly;
+    /**
+     * How deep the continuation chain already is, read from the graph's parent metadata.
+     *
+     * A run started by a graph inherits that graph's depth **plus one**. Without this every spawned
+     * run begins at zero, so a self-referencing flow — one that dispatches a graph containing itself
+     * — recurses without bound while the cap it should be hitting compares against a permanent zero.
+     */
+    private graphContext;
+    /**
+     * Which failures the workflow drew a way out of.
+     *
+     * A Failed task with a **satisfied outgoing edge** is a handled failure: its author drew a
+     * recovery route and that route is now live. Downstream work should be released along it, and the
+     * parent should not roll up Failed because of a step the workflow explicitly planned around.
+     *
+     * Scoped to `failureSemantics: 'edges'` on purpose. Under `'block'` — every agent-emitted graph —
+     * a failure is terminal for its dependents whatever edges exist, because nobody drew those edges
+     * as a recovery path; they are ordinary sequencing, and treating them as recovery would let a
+     * graph sail past a failure it never anticipated.
+     */
+    private computeHandledFailures;
+    /** The graph's child tasks, with the fields the rollup needs. */
+    private loadChildTasks;
     /**
      * Runs the graph's continuation exactly once, now that it has settled.
      *
@@ -121,8 +386,8 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * user-visible noise and, for `reinvoke`, an unbounded agent-run loop. Given one of the two has
      * to be chosen, the quiet failure is the safe one.
      *
-     * The marker is written with a compare-and-swap read-back, so two instances reconciling the same
-     * completed graph produce one winner rather than two.
+     * The marker is claimed with a real compare-and-swap (one guarded UPDATE, rowcount as verdict),
+     * so two instances reconciling the same completed graph produce one winner rather than two.
      */
     private deliverContinuation;
     /** Reads the parent's durable continuation metadata through the shared parser. */
@@ -133,6 +398,12 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * `MJ: Tasks` stays user-writable (D20), so a plain "read, decide, write" is not enough — the
      * read-back is what makes a lost race observable instead of producing a duplicate delivery.
      */
+    /**
+     * True when this graph finished so long ago that announcing it would surprise rather than inform.
+     *
+     * Measured from the parent's completion, not from when we noticed: the point is how stale the
+     * NEWS is to whoever would receive it.
+     */
     private claimContinuation;
     /** One line describing how the graph ended, for the completion log and message delivery. */
     private buildContinuationSummary;
@@ -161,6 +432,40 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * invalidate. Left cached, a completed task keeps reading as `In Progress` and the graph never
      * rolls up: submitted work simply never settles.
      */
+    /**
+     * Settles graphs that reached terminal without completing their post-settlement sequence.
+     *
+     * Runs the ordinary propagation path, which is safe to re-enter by construction: the terminal
+     * write is guarded on not-already-terminal, the cost rollup assigns rather than accumulates, run
+     * settlement is guarded on `Paused`, and delivery is guarded by the continuation CAS. A revisit
+     * therefore corrects whatever is missing and does nothing where nothing is.
+     *
+     * @param windowHours how far back to look — wide once at startup, narrow in steady state
+     */
+    private sweepUnsettledGraphs;
+    /**
+     * The `AI Workflow` task type, resolved once per process.
+     *
+     * `MJ: Tasks` is a GENERAL-PURPOSE entity — conversations and user to-dos live there too — so an
+     * unscoped sweep treats every root task hierarchy as a workflow: rolling up and overwriting the
+     * status of somebody's to-do list, raising agent requests against plain tasks, and (once the
+     * continuation CAS exists) injecting marker keys into a user's own `InputPayload`.
+     *
+     * `Submit` has always stamped this type on the parent and every child (`ensureTaskType`, which
+     * runs before the persist transaction), so the discriminator D3 called for already exists on
+     * every dispatcher-owned row. Verified against the live database: every parent graph carries it.
+     *
+     * Null when the type row does not exist yet — no graph has ever been submitted — in which case
+     * there is nothing for the dispatcher to find and the sweep returns empty rather than unscoped.
+     *
+     * **A miss is never cached**, and that is not a micro-optimisation. `TaskGraphService.Submit`
+     * creates the row on first use, so on a fresh install the ordinary sequence is: dispatcher
+     * starts, looks, finds nothing — then somebody submits the first workflow. Caching that first
+     * `null` would blind this process to every graph until it was restarted, with each poll reporting
+     * a clean, empty sweep. The row is created once and never removed, so the retry costs one
+     * `MaxRows: 1` lookup per poll for exactly as long as there is genuinely nothing to dispatch.
+     */
+    private workflowTaskTypeID;
     private findActiveGraphIDs;
     /**
      * Tasks eligible to claim right now, across all active graphs.
@@ -170,8 +475,132 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * the same rule, free to drift from the one the in-run executor uses.
      */
     private findClaimableTasks;
+    private clearSkipBreakpoint;
+    /**
+     * Drops the per-graph frame-dedup state for a graph that has settled.
+     *
+     * `ownerByParentID` is deliberately NOT purged here: it is the delivery key for the
+     * `GraphSettled` frame emitted moments earlier and for any rescue-sweep pass that revisits the
+     * graph, it is one small string per graph, and ownership never changes — the cost of keeping it
+     * is bounded and the cost of losing it is a re-query on a path that is meant to be cheap.
+     */
+    private forgetGraphObservability;
+    /**
+     * Whether THIS host can act on a task right now — the runner-availability question, asked
+     * without acting on it.
+     *
+     * Mirrors the checks in the claim loop so a step allowance is spent only when something will
+     * actually move. A human step counts as actionable: stepping onto one legitimately produces a
+     * notification rather than a claim.
+     */
+    private canActOn;
+    /**
+     * Says why a step press released nothing, instead of leaving the allowance spent and the
+     * console silent.
+     *
+     * The allowance is deliberately NOT consumed on this path — the operator's intent stands, and
+     * the step will release as soon as the named work becomes actionable (a runner arrives, an
+     * in-flight task finishes). Announced once per pass rather than logged only, because the person
+     * waiting is looking at the console, not the server log.
+     */
+    private reportStepReleasedNothing;
+    /**
+     * Marks a human task as notified, so the request is raised exactly once.
+     *
+     * Written even when delivery threw. Retrying on every poll is a worse failure than one missed
+     * notification: the task stays visible in the inbox either way, whereas a notification storm is
+     * not self-correcting.
+     */
+    private markHumanTaskNotified;
+    /**
+     * Raises the `MJ: AI Agent Requests` row a person answers to release this step.
+     *
+     * **Why that entity rather than something new.** It already models everything a workflow's human
+     * step needs — who is being asked, what for, a typed response schema, priority, expiry, and an
+     * inbox surface people already use. A second HITL substrate beside it would split the inbox in
+     * two and leave one of them without expiry or permissions.
+     *
+     * **What it deliberately does NOT set is `ResumingAgentRunID`.** A request normally suspends an
+     * agent run and resumes it. A workflow needs none of that: the graph OUTLIVES the run that
+     * submitted it, so nothing is suspended — the task sits Pending, every other branch keeps
+     * running, and answering settles the task. That column staying null is meaningful, not missing.
+     */
+    private raiseHumanRequest;
+    /**
+     * The agent that owns this task's workflow — who the request is asked on behalf of.
+     *
+     * Reads the graph's parent row, falling back to the run that submitted it. A human step has no
+     * agent of its own by design: `AgentID` names what EXECUTES a step, and a person is not an agent.
+     */
+    private owningAgentOf;
+    /**
+     * Every still-open request for a task, oldest first.
+     *
+     * Plural, and ordered, for one reason each. Ordered, because the oldest row is the one every
+     * instance must agree is "the" request — it is the one the assignee most likely already saw,
+     * and the one `withdrawDuplicateRequests` keeps; unordered, two instances could each decide a
+     * different duplicate was the keeper and withdraw each other's. Plural, because a caller that
+     * only ever sees the first cannot notice there are two, which is how the duplicate below
+     * survived: every reader of this took `[0]` and moved on.
+     */
+    private findOpenRequests;
+    /**
+     * Settles a human task from the request a person answered.
+     *
+     * Runs on the poll rather than on a save hook, because the answer can arrive through any surface
+     * — the inbox, the API, a conversation — and only the dispatcher knows how to release the rest
+     * of the graph afterwards.
+     *
+     * **`ResponseData` becomes the task's output.** That is what makes a human step useful rather
+     * than a gate: a downstream edge can branch on what the person actually said, typed by the
+     * request's own ResponseSchema. A step that only recorded "approved" would force every decision
+     * back into a separate action.
+     */
+    private settleAnsweredHumanTasks;
+    /**
+     * Reconciles the requests behind human steps that are waiting on somebody.
+     *
+     * Two things can be wrong with a waiting step, and both are silent. It can have NO open request
+     * — the cancel case below — or it can have MORE than one, which the raise cannot fix because it
+     * never runs again for a notified task. Both are corrected here, on the only sweep that visits
+     * these tasks every pass.
+     *
+     * **Re-opening a human step whose request was CANCELLED.**
+     *
+     * `answeredRequestFor` deliberately excludes `Canceled`, because cancelling withdraws the ASK
+     * rather than deciding the step — the task is supposed to keep waiting "for whatever replaces
+     * it". Nothing replaced it. `raiseHumanRequest` refuses to raise twice (the notified marker on
+     * `ClaimedBy` is what stops the notification storm), so a cancelled request left the task Pending
+     * with no open request and no path to acquiring one: a workflow waiting forever on a question
+     * nobody is being asked.
+     *
+     * Clearing the marker is the whole fix — the next poll sees an un-notified Pending human task
+     * and raises a fresh request, which is exactly the replacement the design assumed. Bounded by
+     * human action: it takes another person cancelling again to come back here.
+     */
+    private reconcileWaitingHumanTasks;
+    /** The answered (or expired) request for a task, if any. */
+    private answeredRequestFor;
+    /**
+     * Expires requests whose deadline has passed.
+     *
+     * A deadline that nothing enforces is a comment. Without this an `ExpiresAt` in the past leaves
+     * the request `Requested` forever and the workflow waiting on it just as long.
+     */
+    private expireOverdueRequests;
+    /** The agent run that submitted this task's graph, for provenance on the request. */
+    private submittingRunOf;
     /** Loads a graph's children and edges in the shapes both the algorithms and mutation need. */
     private loadGraphState;
+    /**
+     * Reports an unevaluable condition ONCE per edge, not once per poll.
+     *
+     * Eligibility is recomputed every cycle, so an unqualified LogError here would repeat every few
+     * seconds for as long as the graph is held — which buries the one line that matters under
+     * thousands of copies of itself. Keyed by edge id plus the failure text, so a condition that
+     * starts failing differently is reported again.
+     */
+    private logUnevaluableConditionOnce;
     /**
      * Decides whether a conditional dependency edge is live.
      *
@@ -180,7 +609,241 @@ export declare class TaskGraphDispatcher implements IShutdownable {
      * an unevaluable condition keeps the edge for the reason stated at the call site.
      */
     private evaluateEdgeCondition;
+    /**
+     * An exclusive edge's condition as a three-way outcome.
+     *
+     * `ResolveExclusiveGroups` needs to tell "false" from "could not be evaluated": the first loses
+     * the branch, the second holds the whole group. The generic keep/drop path cannot express that
+     * difference, which is why exclusive edges take this route instead.
+     */
+    private evaluateExclusiveCondition;
+    /**
+     * Announces gate verdicts that CHANGED since this instance last looked.
+     *
+     * Fire-and-forget by design: `loadGraphState` is synchronous graph assembly, and the owner
+     * lookup the frame needs is async — so the emission floats behind rather than making state
+     * loading wait on observability. Frames are commentary, never a step of the work.
+     */
+    private emitGateDecisions;
     /** Parsed `OutputPayload` of each completed dependency, keyed by that task's ID. */
     private loadDependencyOutputs;
+    /**
+     * Runs one task's body, whatever kind of step it is.
+     *
+     * **Routing is on `StepType`, not on which key happens to be set.** A loop step carries the same
+     * `ActionID` or `AgentID` as an ordinary step — that key is what the loop *repeats* — so the old
+     * `task.ActionID ? action : agent` test would have run a loop exactly once and called it done.
+     * `StepType` is the only field that distinguishes them.
+     *
+     * Every branch is normalized to one shape so the recording path above stays single: an action has
+     * no agent run to point at, because its forensics live in `ActionExecutionLog` instead.
+     */
+    private runTaskBody;
+    /**
+     * Runs a loop step: its body once per iteration, with the item and index in scope.
+     *
+     * The loop's own `Configuration` supplies the definition; the row's `ActionID` / `AgentID`
+     * supplies what to repeat. Per-iteration inputs are resolved fresh each pass — the bindings are
+     * merged into the payload before the mapping is applied, which is how a body can reference the
+     * current item at all.
+     */
+    private runLoopTask;
+    /**
+     * Folds one pass's result into the loop's running payload.
+     *
+     * **With a body mapping**, the pass's declared outputs are filed where the author said to put
+     * them — including `name[]`, which appends, so a ForEach can collect one entry per item. That is
+     * the whole point of a loop over a collection, and it is only expressible per pass.
+     *
+     * **Without one**, the raw result is deep-merged, which is the pre-existing behaviour and the
+     * right default for a `While` that converges on a value: each pass refines what the condition
+     * reads. It is the wrong default for a ForEach that collects — hence the mapping.
+     *
+     * An unmapped output is reported per pass rather than swallowed, for the same reason
+     * {@link applyStepOutputMapping} reports it: a mapping that names something the body never
+     * returned means the pass did work that went nowhere, while everything reports success.
+     */
+    private foldIterationOutput;
+    /**
+     * Files a step's result into the payload it hands downstream.
+     *
+     * **This is what makes a branch condition possible.** A workflow that branches on
+     * `payload.stockPrice` has that value only because this step mapped `CurrentPrice -> stockPrice`.
+     * Without it the condition reads `undefined` — merely falsy — so the workflow takes the other
+     * branch, finishes, and reports success with nothing to indicate anything went wrong.
+     *
+     * The incoming payload is carried through as well as the update, so a value written three steps
+     * back is still readable here. Returning only this step's own output is what used to limit a
+     * condition's view to its immediate predecessor.
+     */
+    private applyStepOutputMapping;
+    /**
+     * Runs an Agent step, telling the runner where in the graph it sits.
+     *
+     * Depth and provenance are read together because they come from the same row: the graph's parent
+     * task knows both how many continuation hops led here and which run submitted it.
+     */
+    private runAgentNode;
+    /**
+     * Leaves exactly one open request standing for a task, withdrawing any others.
+     *
+     * The oldest wins — it is the one whose notification the assignee most likely already saw.
+     *
+     * **Called from every path that reads a task's open requests**, not only from the raise. That is
+     * deliberate and it is the half R3-5 first got wrong: a task is notified exactly once, and
+     * `notifyHumanTaskReady` returns at the marker forever after, so a duplicate minted after that
+     * pass — by an instance that crashed between its insert and its de-dup, or by any build older
+     * than this one — was never looked at again by the only code that could have collapsed it. The
+     * waiting-task sweep is what actually reaches those.
+     *
+     * @param open the task's open requests, oldest first
+     * @param keepIfSole the row this caller is responsible for, named only for the log
+     */
+    private withdrawDuplicateRequests;
+    /**
+     * Closes the still-open asks raised for tasks that will never be answered.
+     *
+     * `Canceled` rather than `Expired`: nobody ran out of time, the ask was withdrawn — and the two
+     * mean different things downstream, since an expired human step is treated as a FAILURE that a
+     * give-up edge can route around, which would be a lie about a step the workflow decided it no
+     * longer needed.
+     *
+     * Failures are logged and never propagated. The graph's outcome is already decided; refusing to
+     * finish over an inbox row would trade a stale notification for a stalled workflow.
+     */
+    private withdrawOpenRequests;
+    /**
+     * Says once, per graph, that this instance settled work it cannot announce.
+     *
+     * Once because the sweep re-offers the graph every poll for the rest of its window, and a line
+     * per poll would bury the thing it is trying to report — which is a DEPLOYMENT fact, not a graph
+     * fact: if no instance anywhere carries a deliverer, these settlements never reach anyone.
+     */
+    private reportUndeliverableOnce;
+    /**
+     * Keeps a graph in this instance's sweep regardless of what its row timestamp says.
+     *
+     * Bounded, and the bound is about noise rather than surrender: past the cap the graph has failed
+     * on every attempt for minutes, so another identical attempt will not fix it, and continuing
+     * costs a full graph load per poll forever. It is reported once and left to the startup sweep.
+     */
+    private keepRetryingSettlement;
+    /**
+     * A graph's durable metadata bag, for the questions a pass asks of it.
+     *
+     * Defaults on any failure to read it, and the defaults are the safe directions: `'block'` means
+     * a failed step decides nothing, so a graph whose metadata we cannot read stalls visibly instead
+     * of resolving forks on the say-so of a failure; and no early-finish declaration means nothing
+     * is removed from the claim filter on the strength of a read that did not work.
+     */
+    private readParentMetadataFor;
+    /**
+     * Whether the submitting run is in a state where this pass's writes to it will mean anything.
+     *
+     * **Read-only on purpose.** The settled branch's write order — layout, frame, cost, lifecycle,
+     * delivery — is load-bearing and documented at each step; this asks the question those writes
+     * depend on without joining them. What it prevents is a pass that goes through the motions and
+     * then claims the delivery marker, making itself the last pass ever to look at the graph.
+     *
+     * Three answers, and the middle one is the bug:
+     *
+     *  - **no run** — a scheduled or remote-triggered graph has nobody waiting. Proceed.
+     *  - **still `Running`** — `finalizeAgentRun` has not parked it yet. The graph beat its own
+     *    submitter to the finish line, which is ordinary for a fast graph and lasts milliseconds.
+     *    Defer: one poll later the run is parked and everything lands.
+     *  - **anything else** — `Paused` (settle it), or already `Completed`/`Failed`/`Cancelled` for
+     *    its own reasons (leave it; the lifecycle write's own guard declines). Proceed.
+     *
+     * **The deferral is bounded**, because "not parked yet" and "the submitting process died before
+     * it could park" look identical from here. Waiting forever on the second would lose the outcome
+     * of work that actually completed — strictly worse than announcing it late — so past the grace
+     * period this proceeds and says why. The run itself stays `Running`, which is visibly wrong and
+     * belongs to whatever reconciles abandoned runs, not to the graph that finished correctly.
+     */
+    private submittingRunReadiness;
+    /**
+     * Completes the agent run that parked on this graph.
+     *
+     * **This is the other half of submit-and-detach.** A run that dispatches a graph does not
+     * complete at submission — it ends `Paused`, because reporting `Completed` above a workflow
+     * where nothing has happened yet is a claim the row cannot support. The run's lifecycle is
+     * finished HERE, when the graph it was waiting on actually settles, which is the first moment
+     * the answer exists.
+     *
+     * Doing it from the dispatcher rather than by awaiting in the agent is what keeps the properties
+     * that made detach right in the first place: a graph containing a human approval can park for
+     * days without holding a conversation turn open, and a graph reclaimed by another instance after
+     * a crash still settles its submitting run, because the settling happens wherever the graph
+     * finishes rather than wherever it started.
+     *
+     * **Only a parked run is touched.** A run that is already `Completed`, `Failed` or `Cancelled`
+     * reached that state for its own reasons — a second graph settling later, a run the user
+     * cancelled, a run that failed after submitting — and overwriting it would rewrite history from
+     * the outside. The `Paused` predicate is the whole guard.
+     *
+     * @param graphStatus the parent rollup's status: what the workflow as a whole did
+     */
+    private settleSubmittingRun;
+    /**
+     * Gives every step that lacks one a position, once the graph has finished.
+     *
+     * **Why the run stores geometry at all.** A `TaskGraphSpec` is a logical structure with no
+     * layout field, so a graph an agent emitted has no opinion about where its boxes go. Every
+     * viewer was therefore laying it out for itself at render time — and a viewer that failed to
+     * (because the canvas measures nodes it has not drawn yet) fell back to every node at the
+     * origin, piled on one another, with the zoom-to-fit that follows fitting a one-node bounding
+     * box. Settling it once, server-side, means the agent-run canvas, the Workflows runs tab and
+     * anything built later all draw the same picture, and none of them has to compute it.
+     *
+     * **An authored position is never overwritten.** A workflow compiled from a Flow agent carries
+     * the arrangement someone dragged into place; replacing it with an algorithm's guess would
+     * discard a deliberate act. Only steps with no geometry get one, so a partially-arranged graph
+     * keeps what it has.
+     *
+     * Failure here is logged and swallowed: this is presentation. A graph whose work completed must
+     * not be reported as failed because its picture could not be saved.
+     */
+    private persistComputedLayout;
+    /**
+     * The earliest moment any step in the graph began, or null when none has.
+     *
+     * Null is a real answer — a graph whose tasks are all still Pending has not started — and is
+     * deliberately not collapsed to "now", which would date the graph from whenever this pass
+     * happened to run.
+     */
+    private earliestStart;
+    /**
+     * The step's Configuration with this run's artefacts folded in, or `undefined` to leave it be.
+     *
+     * **Merged into the authored bag, never written over it.** The Configuration column holds the
+     * step's definition — its loop body, its mappings, its policy, the position someone dragged it
+     * to. Writing a fresh object containing only `runtime` would erase all of that the first time a
+     * prompt step completed, which is the kind of loss that surfaces much later as a workflow that
+     * mysteriously stopped mapping its output.
+     *
+     * Returns `undefined` when there is nothing to record, so the guarded write omits the column
+     * rather than rewriting it with what it already held.
+     */
+    private configurationWithRuntime;
+    /**
+     * Reads a step's Configuration bag, tolerating a row whose JSON cannot be parsed.
+     *
+     * Unparseable configuration is logged rather than thrown: the step has already RUN by the time
+     * this is called, and refusing to record its outcome because its definition is malformed would
+     * discard the result of real work and leave the task claimed until the claim lapsed.
+     */
+    private parseConfiguration;
+    /**
+     * The payload a step sees: everything its prerequisites produced, plus its own declared input.
+     *
+     * **Why the outputs are merged rather than kept per-task.** A flow carried ONE payload that
+     * accumulated as it went, so a condition on the edge into step C could read a value step A wrote.
+     * Handing each task only its immediate predecessor's output would silently narrow that: the
+     * condition reads `undefined`, which is falsy, and the workflow quietly takes a different route
+     * than the flow it was compiled from. Merging in dependency order restores the accumulation.
+     *
+     * Later prerequisites win on a key collision, matching a flow's own last-write-wins behaviour.
+     */
+    private mergedPayload;
 }
 //# sourceMappingURL=TaskGraphDispatcher.d.ts.map