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

package/dist/TaskGraphService.js

@@ -16,8 +16,26 @@
  * @module @memberjunction/task-graph
  */
 import { LogError, LogStatus, RunInEntityTransaction, RunView, } from '@memberjunction/core';
-import { FormatValidationErrors, NormalizeDependency, RankGraphNodes, ValidateTaskGraphSpec, ConfigOf, } from '@memberjunction/ai-core-plus';
+import { FormatValidationErrors, NormalizeDependency, RankGraphNodes, SanitizeInvocationEnvelope, ValidateTaskGraphSpec, ConfigOf, } from '@memberjunction/ai-core-plus';
 import { UUIDsEqual } from '@memberjunction/global';
+import { TaskClaimStore } from './TaskClaimStore.js';
+import { ParseTaskGraphDebugState } from './debug-state.js';
+import { KickTaskGraphDispatchers } from './task-graph-kick.js';
+/**
+ * Normalizes a caller-supplied reinvoke depth to a safe cap seed.
+ *
+ * The runaway-loop cap is a signed comparison over a persisted-verbatim seed, and the remote Submit
+ * operation is the one seam where the seed is caller-supplied rather than computed by the engine —
+ * a negative value would BUY hops (`-1000` turns a 5-hop cap into 1005). Clamped rather than
+ * refused so a stale client sending zero-adjacent noise keeps working, and no accepted value can
+ * ever weaken the cap. Exported pure because a boundary rule that cannot be tested directly is a
+ * boundary nobody will notice moving.
+ */
+export function ClampReinvokeDepth(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : undefined;
+}
 /**
  * Continuation chains are bounded separately from graph nesting.
  *
@@ -65,18 +83,58 @@ export function ParseTaskGraphParentMetadata(raw) {
                 : 'message',
             failureSemantics: parsed.failureSemantics === 'edges' ? 'edges' : 'block',
             reinvokeDepth: Number.isFinite(parsed.reinvokeDepth) ? Number(parsed.reinvokeDepth) : 0,
+            // Guarded like the others: this is read to explain a settlement after the fact, and an
+            // arbitrary string arriving from a hand edit should read as "unknown", not be echoed.
+            continuationDeliveredAs: DELIVERY_OUTCOMES.has(parsed.continuationDeliveredAs)
+                ? parsed.continuationDeliveredAs
+                : undefined,
         };
     }
     catch {
         return { ...DEFAULT_PARENT_METADATA };
     }
 }
+/**
+ * The JSON bag `persistParent` writes. Exported so start-paused is testable without a database —
+ * Pause-after-submit races the first dispatcher poll, so this bag is the only place `paused: true`
+ * is guaranteed to land before anyone claims.
+ */
+export function BuildTaskGraphParentInputPayload(args) {
+    return {
+        continuation: args.continuation,
+        reinvokeDepth: args.reinvokeDepth,
+        failureSemantics: args.failureSemantics,
+        submittedByAgentRunID: args.submittedByAgentRunID,
+        submittedByUserID: args.submittedByUserID,
+        ...(args.invocation
+            ? { invocation: { data: args.invocation.data, context: args.invocation.context } }
+            : {}),
+        ...(args.startPaused
+            ? {
+                debug: {
+                    paused: true,
+                    pausedReason: 'user',
+                    pausedBy: args.submittedByUserID,
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * How a settlement's announcement ended — the values `TryClaimContinuation` may record.
+ *
+ * `expired` means found too late to announce; `cancelled` means there was deliberately nobody left
+ * to announce to, because the run that submitted the graph was cancelled. Both are settlements that
+ * completed WITHOUT an announcement, and keeping them distinct is the difference between "we missed
+ * it" and "we chose not to".
+ */
+const DELIVERY_OUTCOMES = new Set(['delivered', 'expired', 'cancelled']);
 /** True when a continuation chain has gone as far as it may. */
 export function IsReinvokeCapReached(meta) {
     return meta.reinvokeDepth >= MAX_REINVOKE_DEPTH;
 }
 /** Name of the task type used for agent-orchestrated graphs. */
-const TASK_TYPE_NAME = 'AI Workflow';
+export const TASK_TYPE_NAME = 'AI Workflow';
 /**
  * The node kinds a `Task` row can actually represent, and therefore the ones the dispatcher can run.
  *
@@ -253,6 +311,29 @@ export function FindCrossUserAssignments(spec, submitterUserID) {
         `only ask the person who started it. Remove assignToUserID from those steps.`);
 }
 export class TaskGraphService {
+    constructor() {
+        /**
+         * Guarded single-statement writes, shared with the dispatcher.
+         *
+         * The instance id is descriptive only — this service never CLAIMS anything, it only issues
+         * guarded transitions whose predicates are about the row's own status rather than about who
+         * holds it.
+         */
+        this.claims = new TaskClaimStore('task-graph-service', 0);
+        // ────────────────────────────────────────────────────────────────────────
+        // debug / runner control plane
+        //
+        // Every verb here is durable, declarative state the dispatcher's claim filter consults on its
+        // next pass — never a call into a running dispatcher. That is what makes the controls work
+        // across instances and restarts, and what bounds their latency to one poll interval. See
+        // `debug-state.ts` for the model.
+        // ────────────────────────────────────────────────────────────────────────
+        /**
+         * Store for the guarded JSON_MODIFY writes. The instance identity and TTL are claim-protocol
+         * concerns this class never exercises — the debug writes are instance-free.
+         */
+        this.debugWrites = new TaskClaimStore('task-graph-service', 0);
+    }
     /**
      * Validates and persists a task graph, returning as soon as it is durable.
      *
@@ -353,6 +434,7 @@ export class TaskGraphService {
             });
             LogStatus(`[TaskGraphService] Submitted "${spec.workflowName}": parent ${parentTaskID}, ${taskIDMap.size} task(s). ` +
                 `Awaiting dispatcher pickup.`);
+            KickTaskGraphDispatchers();
             return { Success: true, ParentTaskID: parentTaskID, TaskIDMap: taskIDMap };
         }
         catch (e) {
@@ -362,23 +444,60 @@ export class TaskGraphService {
         }
     }
     /**
-     * Cancels a graph and everything in it that has not already settled.
+     * Cancels a graph, everything in it that has not already settled, and everything it started.
      *
      * Cancels children first: a parent marked `Cancelled` while children are still `Pending` would
      * leave the dispatcher free to pick those children up, which is the opposite of what the caller
      * asked for.
+     *
+     * **The verdict is the outcome, not the attempt** (R2-9). This returned `true` unconditionally
+     * while logging each child that failed to cancel — so one failed save left that child `Pending`,
+     * told the caller cancellation had succeeded, and let the dispatcher run the child afterwards.
+     * The graph could then settle `Complete` and ANNOUNCE ITS COMPLETION into the conversation of a
+     * workflow the user had cancelled. A partial cancel now says so and names what survived; the
+     * graph stays active, so retrying is meaningful rather than cosmetic.
      */
     async Cancel(parentTaskID, context) {
+        return this.cancelWithDepth(parentTaskID, context, 0, new Set());
+    }
+    /**
+     * `Cancel`, carrying the recursion state the public entry point does not expose.
+     *
+     * **The depth cap was dead code** (R3-10): `Cancel` passed a literal 0, and the recursion
+     * re-entered through `this.Cancel`, which restarted at 0 — so the check could never fire and
+     * the "bounded by the reinvoke depth cap" promise was false. A hand-edited `AgentRunID` cycle
+     * recursed to stack overflow mid-cancel.
+     *
+     * The visited set is cheap armour on top: the cap bounds how DEEP a legitimate chain goes, and
+     * a cycle is not deep, it is circular. Arithmetic alone would eventually stop it; a visited set
+     * stops it immediately and covers linkage shapes the arithmetic does not anticipate.
+     */
+    async cancelWithDepth(parentTaskID, context, depth, visited) {
+        if (visited.has(parentTaskID)) {
+            return { Success: true, Cancelled: true, UncancelledTaskNames: [] };
+        }
+        visited.add(parentTaskID);
         try {
             const children = await this.loadChildren(parentTaskID, context);
+            const uncancelled = [];
+            const settledMeanwhile = [];
             for (const child of children) {
                 // Terminal work is left alone — cancelling a completed task would rewrite history.
-                if (['Complete', 'Failed', 'Cancelled'].includes(child.Status))
+                // The in-memory test is a cheap pre-filter; the one that MATTERS is in the statement
+                // (R3-9), because a child can settle between this snapshot and its own write, and
+                // the full-row save this replaces overwrote that outcome wholesale.
+                if (['Complete', 'Failed', 'Cancelled', 'Skipped'].includes(child.Status))
                     continue;
-                child.Status = 'Cancelled';
-                if (!(await child.Save())) {
-                    LogError(`[TaskGraphService] Failed to cancel task ${child.ID}: ${child.LatestResult?.CompleteMessage ?? 'unknown error'}`);
-                }
+                if (await this.claims.TryCancelTask(context.Provider, child.ID, context.ContextUser))
+                    continue;
+                // Rowcount 0 means it reached a terminal status while we were cancelling its
+                // siblings. Its outcome is real and stays; the verdict says so rather than pretending
+                // the cancel was total.
+                settledMeanwhile.push(child.Name);
+            }
+            if (settledMeanwhile.length > 0) {
+                LogStatus(`[TaskGraphService] ${settledMeanwhile.length} task(s) settled while the cancel ran ` +
+                    `(${settledMeanwhile.join(', ')}); their outcomes are kept.`);
             }
             // Withdraw the questions too. A human step that was waiting has an open
             // `MJ: AI Agent Requests` row, and cancelling only the Task left that row `Requested`
@@ -387,17 +506,97 @@ export class TaskGraphService {
             // already Cancelled. Nothing else ever closes these — the dispatcher only expires rows
             // that carry a deadline, and most do not.
             await this.cancelOpenRequests(children.map((c) => c.ID), context);
-            const parent = await context.Provider.GetEntityObject('MJ: Tasks', context.ContextUser);
-            if (!(await parent.Load(parentTaskID)))
-                return false;
-            parent.Status = 'Cancelled';
-            parent.CompletedAt = new Date();
-            return await parent.Save();
+            // THE PARENT IS LEFT TO THE DISPATCHER, DELIBERATELY.
+            //
+            // Writing it terminal here skipped the settle path entirely — no cost rollup, no run
+            // settlement, no notification — so the submitting agent run stayed `Paused` forever.
+            // Worse, it was NONDETERMINISTIC: if a dispatcher poll happened to land between the
+            // child cancels above and the parent write, the graph settled through the normal path
+            // and the run WAS failed and messaged. Cancel behaved differently run to run depending
+            // on timing.
+            //
+            // With the children cancelled, `ComputeParentRollup` reaches `Cancelled` on its own and
+            // the ordinary settle sequence runs — rollup, run settlement, continuation — exactly as
+            // it does for a graph that finished by itself. Less code, one path, and a deterministic
+            // outcome.
+            //
+            // The parent stays non-terminal until then, so the sweep still sees it as active work.
+            // WHAT THIS WORKFLOW STARTED IS ALSO CANCELLED (R2-9).
+            //
+            // A graph's step can be an agent that submits a graph of its own, and those sub-graphs
+            // persist as ROOTS — linked back only through the child task's `AgentRunID`. So
+            // cancelling a workflow left its descendants running, and on settlement one of them can
+            // REINVOKE the cancelled workflow's own agent for a fresh billed turn: the user stopped
+            // a workflow and it started itself again.
+            //
+            // Bounded by the reinvoke depth cap, which is what bounds the chain in the first place.
+            const nested = await this.cancelNestedGraphs(children, context, depth, visited);
+            uncancelled.push(...nested);
+            if (uncancelled.length > 0) {
+                return {
+                    Success: false,
+                    Cancelled: false,
+                    UncancelledTaskNames: uncancelled,
+                    ErrorMessage: `Cancelled what it could, but ${uncancelled.length} task(s) could not be cancelled ` +
+                        `(${uncancelled.join(', ')}). The workflow is still active — retry the cancel.`,
+                };
+            }
+            return { Success: true, Cancelled: true, UncancelledTaskNames: [] };
         }
         catch (e) {
-            LogError(`[TaskGraphService] Cancel failed for ${parentTaskID}: ${e instanceof Error ? e.message : String(e)}`);
-            return false;
+            const message = e instanceof Error ? e.message : String(e);
+            LogError(`[TaskGraphService] Cancel failed for ${parentTaskID}: ${message}`);
+            return { Success: false, Cancelled: false, UncancelledTaskNames: [], ErrorMessage: message };
+        }
+    }
+    /**
+     * Cancels the graphs that this graph's own steps submitted, one level at a time.
+     *
+     * The linkage is `child task → AgentRunID → the graphs that run submitted`, which is exactly how
+     * the continuation chain finds its way back up; walking it downward is the same relation read the
+     * other way. Depth-capped by the same constant that caps reinvocation, so a self-referencing
+     * workflow cannot make cancellation recurse further than it could have spawned.
+     *
+     * @returns names of tasks in descendant graphs that could not be cancelled
+     */
+    async cancelNestedGraphs(children, context, depth, visited) {
+        if (depth >= MAX_REINVOKE_DEPTH) {
+            LogError(`[TaskGraphService] Nested cancel stopped at depth ${depth}; a deeper sub-graph chain ` +
+                `than the reinvoke cap allows may still be running.`);
+            return [];
         }
+        const runIDs = [...new Set(children.map((c) => c.AgentRunID).filter((id) => !!id))];
+        if (runIDs.length === 0)
+            return [];
+        const rv = RunView.FromMetadataProvider(context.Provider);
+        const inList = runIDs.map((id) => `'${id}'`).join(',');
+        // TYPE-SCOPED, like every other graph-mutating walk over this table (R3-10). `MJ: Tasks` is
+        // general-purpose, and without the predicate any non-workflow root hierarchy that happens to
+        // carry a cancelled run's ID gets `Cancelled` written over its children and its requests
+        // withdrawn — the user-writable-table threat the claim store's guards exist to defend
+        // against. The comment here already claimed this scoping; the query did not have it.
+        const typeID = await this.findTaskTypeID(context);
+        if (!typeID)
+            return [];
+        const subGraphs = await rv.RunView({
+            EntityName: 'MJ: Tasks',
+            ExtraFilter: `TypeID='${typeID}' AND ParentID IS NULL AND AgentRunID IN (${inList})`,
+            Fields: ['ID'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, context.ContextUser);
+        if (!subGraphs.Success) {
+            LogError(`[TaskGraphService] Could not look for sub-graphs while cancelling: ${subGraphs.ErrorMessage}`);
+            return [];
+        }
+        const failures = [];
+        for (const row of subGraphs.Results ?? []) {
+            // Through the depth-carrying overload, so the cap actually engages.
+            const result = await this.cancelWithDepth(row.ID, context, depth + 1, visited);
+            if (!result.Success)
+                failures.push(...result.UncancelledTaskNames);
+        }
+        return failures;
     }
     /**
      * Closes the still-open requests raised for a set of tasks.
@@ -450,7 +649,7 @@ export class TaskGraphService {
      * leaving them blocked would make the retry pointless, as the graph still could not progress
      * past this node.
      */
-    async Retry(taskID, context) {
+    async Retry(taskID, context, inputPayload) {
         try {
             const task = await context.Provider.GetEntityObject('MJ: Tasks', context.ContextUser);
             if (!(await task.Load(taskID)))
@@ -459,6 +658,27 @@ export class TaskGraphService {
                 LogError(`[TaskGraphService] Cannot retry task ${taskID}: status is ${task.Status}, expected Failed.`);
                 return false;
             }
+            // An edited input rides the retry: the operator saw WHY it failed and is re-running the
+            // step with a corrected brief. Applies to this run only — the graph's spec is long gone.
+            //
+            // Written through the GUARDED statement rather than onto the in-memory row, so the edit
+            // cannot ride along on the full-row save below. The window here is narrower than
+            // `UpdateTaskInput`'s (the pre-state is `Failed`, so a concurrent claim is not the
+            // hazard — a concurrent human retry is), but the shape is the same and it costs one
+            // statement to not have it. The rest of this method's full-row save predates this PR
+            // and is Round 3's to purge; the new write does not add to it.
+            if (inputPayload !== undefined) {
+                const typeID = await this.ensureTaskType(context);
+                const json = typeof inputPayload === 'string' ? inputPayload : JSON.stringify(inputPayload);
+                const wrote = await this.debugWrites.TryUpdateInputPayload(context.Provider, taskID, json, 'Failed', typeID, context.ContextUser);
+                if (!wrote) {
+                    LogError(`[TaskGraphService] Could not apply the edited input to task ${taskID}; retry refused rather than re-running the old brief.`);
+                    return false;
+                }
+                // Keep the in-memory row in step with what was just written, so the save below does
+                // not put the old input back.
+                task.InputPayload = json;
+            }
             task.Status = 'Pending';
             task.ErrorMessage = null;
             task.StartedAt = null;
@@ -484,6 +704,266 @@ export class TaskGraphService {
             return false;
         }
     }
+    /** Result shape shared by the control verbs: what happened, and the state that now holds. */
+    controlResult(success, debug, errorMessage) {
+        return { Success: success, Debug: debug, ErrorMessage: errorMessage };
+    }
+    /**
+     * Loads a graph parent and proves it IS a workflow graph before any debug write.
+     *
+     * Read with `BypassCache` for the same reason the dispatcher reads rows that way: the debug bag
+     * is written by direct `JSON_MODIFY` statements that fire no cache invalidation, so a cached
+     * read here could merge new state over a stale copy and silently resurrect a cleared flag.
+     */
+    async loadWorkflowParent(parentTaskID, context) {
+        const typeID = await this.ensureTaskType(context);
+        const rows = await RunView.FromMetadataProvider(context.Provider).RunView({
+            EntityName: 'MJ: Tasks',
+            ExtraFilter: `ID='${parentTaskID.replace(/'/g, "''")}'`,
+            Fields: ['ID', 'TypeID', 'InputPayload', 'Status'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, context.ContextUser);
+        const row = rows.Success ? rows.Results?.[0] : undefined;
+        if (!row)
+            return null;
+        if (!UUIDsEqual(row.TypeID, typeID))
+            return null;
+        return { typeID, inputPayload: row.InputPayload, status: row.Status };
+    }
+    /**
+     * Writes the debug-bag fields a verb OWNS, and reports the state that results.
+     *
+     * Field-scoped on purpose — see {@link TaskClaimStore.TryWriteDebugFields}. A verb declares the
+     * paths it is responsible for; everything else in the bag is left exactly as the database has
+     * it, so a concurrent step-consume, breakpoint edit, or override cannot be undone by a verb that
+     * was not talking about them.
+     *
+     * The returned state is this instance's best view (read + the fields just written) and is
+     * advisory — the same posture the console takes toward frames.
+     */
+    async writeDebugFields(parentTaskID, context, build) {
+        const parent = await this.loadWorkflowParent(parentTaskID, context);
+        if (!parent)
+            return this.controlResult(false, undefined, 'Not a workflow graph this control plane can act on.');
+        const { Fields, Next } = build(ParseTaskGraphDebugState(parent.inputPayload));
+        const ok = await this.debugWrites.TryWriteDebugFields(context.Provider, parentTaskID, Fields, parent.typeID, context.ContextUser);
+        if (!ok)
+            return this.controlResult(false, undefined, 'The debug state could not be written; see the server log.');
+        return this.controlResult(true, Next);
+    }
+    /**
+     * Pauses a graph: nothing new is claimed until it is resumed. In-flight steps finish naturally
+     * and their completions land — a pause gates claiming and never touches a live claim, which is
+     * why there is no "what happens to the claim" question to answer.
+     */
+    async PauseGraph(parentTaskID, context, pausedByUserID) {
+        const pausedBy = pausedByUserID ?? context.ContextUser?.ID ?? null;
+        return this.writeDebugFields(parentTaskID, context, (current) => ({
+            // Pause owns the pause fields AND the step allowance: an allowance armed a moment ago is
+            // for a run the operator has now stopped, so clearing it is the verb's meaning rather
+            // than a side effect. Breakpoints and overrides are untouched — they outlive a pause.
+            Fields: [
+                TaskClaimStore.DebugField('$.debug.paused', { Kind: 'bool', Value: true }),
+                TaskClaimStore.DebugField('$.debug.pausedReason', { Kind: 'string', Value: 'user' }),
+                TaskClaimStore.DebugField('$.debug.pausedBy', pausedBy ? { Kind: 'string', Value: pausedBy } : { Kind: 'null' }),
+                TaskClaimStore.DebugField('$.debug.pausedAtTaskID', { Kind: 'null' }),
+                TaskClaimStore.DebugField('$.debug.step', { Kind: 'null' }),
+                TaskClaimStore.DebugField('$.debug.skipBreakpointTaskID', { Kind: 'null' }),
+            ],
+            Next: { ...current, paused: true, pausedBy, pausedReason: 'user', pausedAtTaskID: null, step: undefined, skipBreakpointTaskID: undefined },
+        }));
+    }
+    /** Resumes a paused graph. Breakpoints and edge overrides survive — only the pause clears. */
+    async ResumeGraph(parentTaskID, context) {
+        return this.writeDebugFields(parentTaskID, context, (current) => {
+            const next = { ...current };
+            // Continue from a breakpoint must run the stopped task. Stamping it here so the next
+            // poll does not re-hit the same still-eligible breakpoint without claiming.
+            const skip = current.pausedReason === 'breakpoint' ? current.pausedAtTaskID : null;
+            delete next.paused;
+            delete next.pausedBy;
+            delete next.pausedReason;
+            delete next.pausedAtTaskID;
+            delete next.step;
+            if (skip)
+                next.skipBreakpointTaskID = skip;
+            else
+                delete next.skipBreakpointTaskID;
+            return {
+                Fields: [
+                    TaskClaimStore.DebugField('$.debug.paused', { Kind: 'null' }),
+                    TaskClaimStore.DebugField('$.debug.pausedReason', { Kind: 'null' }),
+                    TaskClaimStore.DebugField('$.debug.pausedBy', { Kind: 'null' }),
+                    TaskClaimStore.DebugField('$.debug.pausedAtTaskID', { Kind: 'null' }),
+                    TaskClaimStore.DebugField('$.debug.step', { Kind: 'null' }),
+                    skip
+                        ? TaskClaimStore.DebugField('$.debug.skipBreakpointTaskID', { Kind: 'string', Value: skip })
+                        : TaskClaimStore.DebugField('$.debug.skipBreakpointTaskID', { Kind: 'null' }),
+                ],
+                Next: next,
+            };
+        });
+    }
+    /**
+     * Arms a one-shot step allowance on a paused graph: `'one'` releases the next eligible task,
+     * `'wave'` releases the current frontier, a task ID releases exactly that task. The dispatcher
+     * consumes the allowance CAS-style, so two instances stepping the same graph release work once.
+     */
+    async StepGraph(parentTaskID, target, context) {
+        const parent = await this.loadWorkflowParent(parentTaskID, context);
+        if (!parent)
+            return this.controlResult(false, undefined, 'Not a workflow graph this control plane can act on.');
+        const current = ParseTaskGraphDebugState(parent.inputPayload);
+        if (!current.paused) {
+            return this.controlResult(false, current, 'Step only applies to a paused workflow — pause it first.');
+        }
+        return this.writeDebugFields(parentTaskID, context, (state) => ({
+            Fields: [TaskClaimStore.DebugField('$.debug.step', { Kind: 'string', Value: target })],
+            Next: { ...state, step: target },
+        }));
+    }
+    /**
+     * Replaces the graph's breakpoint set. Every ID must name a child of this graph — a breakpoint
+     * on a task in some other graph would gate nothing and silently lie to the person who set it.
+     */
+    async SetBreakpoints(parentTaskID, taskIDs, context) {
+        const children = await this.loadChildren(parentTaskID, context);
+        const childIDs = new Set(children.map((c) => c.ID.toLowerCase()));
+        const foreign = taskIDs.filter((id) => !childIDs.has(id.toLowerCase()));
+        if (foreign.length > 0) {
+            return this.controlResult(false, undefined, `Not steps of this workflow: ${foreign.join(', ')}`);
+        }
+        return this.writeDebugFields(parentTaskID, context, (current) => {
+            const next = { ...current };
+            if (taskIDs.length > 0)
+                next.breakpoints = [...taskIDs];
+            else
+                delete next.breakpoints;
+            return {
+                Fields: [
+                    TaskClaimStore.DebugField('$.debug.breakpoints', taskIDs.length > 0 ? { Kind: 'json', Value: JSON.stringify(taskIDs) } : { Kind: 'null' }),
+                ],
+                Next: next,
+            };
+        });
+    }
+    /**
+     * Overrides one edge's condition verdict — the operator's answer for a path the engine cannot
+     * decide (a held graph) or decided wrongly (a broken guard). `'false'` reads as "branch not
+     * taken" and cascades skips; `'true'` opens the gate; `null` removes the override.
+     */
+    async SetEdgeOverride(parentTaskID, edgeID, verdict, context) {
+        // Prove the edge belongs to this graph before writing anything about it.
+        const edge = await context.Provider.GetEntityObject('MJ: Task Dependencies', context.ContextUser);
+        if (!(await edge.Load(edgeID)))
+            return this.controlResult(false, undefined, 'No such path.');
+        const target = await context.Provider.GetEntityObject('MJ: Tasks', context.ContextUser);
+        if (!(await target.Load(edge.TaskID)) || !UUIDsEqual(target.ParentID ?? '', parentTaskID)) {
+            return this.controlResult(false, undefined, 'That path does not belong to this workflow.');
+        }
+        // AN UNCONDITIONAL PATH CANNOT BE OVERRIDDEN — refused here so the two dialects agree.
+        //
+        // The engine reads overrides at different depths: an ordinary edge only consults one when
+        // it HAS a condition, while the exclusive evaluator consults it before its no-condition
+        // early return. Left open, the same override would force an unconditional exclusive edge to
+        // lose while doing nothing at all to an unconditional ordinary one — the operator's answer
+        // meaning two different things depending on a property of the graph they cannot see.
+        // Refusing is the conservative reading, and it costs nothing: "don't take this branch" is
+        // already expressible, precisely, as SkipTask on the step itself.
+        if (verdict !== null && !edge.Condition?.trim()) {
+            return this.controlResult(false, undefined, 'That path has no condition to answer — it is always taken. To stop the branch, skip its step instead.');
+        }
+        return this.writeDebugFields(parentTaskID, context, (current) => {
+            const overrides = { ...(current.edgeOverrides ?? {}) };
+            if (verdict === null)
+                delete overrides[edgeID];
+            else
+                overrides[edgeID] = verdict;
+            const next = { ...current };
+            if (Object.keys(overrides).length > 0)
+                next.edgeOverrides = overrides;
+            else
+                delete next.edgeOverrides;
+            return {
+                // Scoped to THIS edge's key, not the whole map: two operators answering two
+                // different held paths at once must not overwrite each other's answer.
+                Fields: [
+                    TaskClaimStore.DebugField(`$.debug.edgeOverrides."${edgeID}"`, verdict === null ? { Kind: 'null' } : { Kind: 'string', Value: verdict }),
+                ],
+                Next: next,
+            };
+        });
+    }
+    /**
+     * Declares a Pending step not-taken. Downstream dependents proceed — `Skipped` satisfies a
+     * prerequisite — and any open human request for the step is withdrawn so nobody keeps seeing an
+     * ask for work the operator decided against.
+     */
+    async SkipTask(taskID, context) {
+        const typeID = await this.ensureTaskType(context);
+        const ok = await this.debugWrites.TrySkipPending(context.Provider, taskID, typeID, context.ContextUser);
+        if (!ok) {
+            return { Success: false, ErrorMessage: 'Only a step that has not started can be skipped.' };
+        }
+        await this.cancelOpenRequests([taskID], context);
+        return { Success: true };
+    }
+    /**
+     * Marks a step Complete with an operator-supplied output.
+     *
+     * Human steps are refused here on purpose: they already have a first-class completion path
+     * (`TaskGraph.CompleteTask`) with the assignee/elevation check, and this verb must not become
+     * the door that bypasses it.
+     */
+    async ForceCompleteTask(taskID, outputPayload, context) {
+        const task = await context.Provider.GetEntityObject('MJ: Tasks', context.ContextUser);
+        if (!(await task.Load(taskID)))
+            return { Success: false, ErrorMessage: 'No such step.' };
+        if (task.UserID) {
+            return { Success: false, ErrorMessage: 'A human step completes through its assignee — use CompleteTask.' };
+        }
+        const json = outputPayload == null
+            ? null
+            : typeof outputPayload === 'string' ? outputPayload : JSON.stringify(outputPayload);
+        const typeID = await this.ensureTaskType(context);
+        const ok = await this.debugWrites.TryForceComplete(context.Provider, taskID, json, typeID, context.ContextUser);
+        if (!ok) {
+            return {
+                Success: false,
+                ErrorMessage: 'The step is running with a live claim, or already finished. Cancel it or wait for the claim to lapse.',
+            };
+        }
+        return { Success: true };
+    }
+    /**
+     * Replaces a Pending step's input — the "edit the brief before stepping" move at a breakpoint.
+     * Applies to this run only; the step must not have started.
+     *
+     * **A guarded statement, not load-check-save.** The in-memory `Status === 'Pending'` check plus
+     * `task.Save()` is an unconditional full-row UPDATE: a task claimed in the window between the
+     * load and the save has its claim columns reverted to the pre-claim snapshot *while its body
+     * runs*, and a second instance then claims it again — the step executes twice. See
+     * {@link TaskClaimStore.TryUpdateInputPayload}, which makes the check and the write one atomic
+     * operation whose rowcount is the answer.
+     */
+    async UpdateTaskInput(taskID, inputPayload, context) {
+        try {
+            const typeID = await this.ensureTaskType(context);
+            const json = typeof inputPayload === 'string' ? inputPayload : JSON.stringify(inputPayload);
+            const ok = await this.debugWrites.TryUpdateInputPayload(context.Provider, taskID, json, 'Pending', typeID, context.ContextUser);
+            if (!ok) {
+                return {
+                    Success: false,
+                    ErrorMessage: 'Only a workflow step that has not started can have its input edited.',
+                };
+            }
+            return { Success: true };
+        }
+        catch (e) {
+            return { Success: false, ErrorMessage: e instanceof Error ? e.message : String(e) };
+        }
+    }
     // ────────────────────────────────────────────────────────────────────────
     // internals
     // ────────────────────────────────────────────────────────────────────────
@@ -556,20 +1036,63 @@ export class TaskGraphService {
         }
         return { Success: true, Map: found };
     }
-    /** Finds or creates the task type used for orchestrated graphs. */
+    /**
+     * Finds or creates the task type used for orchestrated graphs — exactly one of it, ever.
+     *
+     * **This resolves the engine's discriminator, not a label** (R2-7). Round 1 scoped every sweep
+     * arm and both payload-writing guards to this type, so a second row sharing the name lets
+     * different processes bind different IDs — and a graph stamped with the other one is invisible
+     * to the sweep, never claimed, never settled, its submitting run `Paused` forever, with no
+     * error anywhere.
+     *
+     * Race-safe by INSERT-then-reselect rather than by checking harder. Two concurrent first-ever
+     * submissions both read "not there" and both insert; the unique index added in this round makes
+     * the loser's insert fail, and the loser then re-reads and finds the winner's row. Checking
+     * first is what created the window, so the fix cannot be a better check.
+     */
     async ensureTaskType(context) {
-        const existing = await RunView.FromMetadataProvider(context.Provider).RunView({ EntityName: 'MJ: Task Types', ExtraFilter: `Name='${TASK_TYPE_NAME}'`, Fields: ['ID'], ResultType: 'simple', MaxRows: 1 }, context.ContextUser);
-        const found = existing.Results?.[0]?.ID;
+        const found = await this.findTaskTypeID(context);
         if (found)
             return found;
         const tt = await context.Provider.GetEntityObject('MJ: Task Types', context.ContextUser);
         tt.NewRecord();
         tt.Name = TASK_TYPE_NAME;
         tt.Description = 'Tasks created by agent-orchestrated workflows.';
-        if (!(await tt.Save())) {
-            throw new Error(`Could not create task type: ${tt.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        if (await tt.Save())
+            return tt.ID;
+        // The insert lost. Almost certainly to the unique index and another process that got there
+        // first — so re-read before treating it as a failure. Any other cause falls through to the
+        // throw below with its own message intact.
+        const winner = await this.findTaskTypeID(context);
+        if (winner)
+            return winner;
+        throw new Error(`Could not create task type: ${tt.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+    /**
+     * The `AI Workflow` task type's ID, resolved deterministically.
+     *
+     * `ORDER BY` is not decoration: two rows sharing the name come back in whatever order the engine
+     * chooses, so an unordered `MaxRows: 1` lets two processes bind different IDs from the same
+     * data. The index this round adds makes duplicates impossible going forward; the ordering makes
+     * the resolution deterministic on a database that still has some, and the warning makes the
+     * situation visible rather than merely survivable.
+     */
+    async findTaskTypeID(context) {
+        const existing = await RunView.FromMetadataProvider(context.Provider).RunView({
+            EntityName: 'MJ: Task Types',
+            ExtraFilter: `Name='${TASK_TYPE_NAME}'`,
+            Fields: ['ID'],
+            OrderBy: '__mj_CreatedAt ASC, ID ASC',
+            ResultType: 'simple',
+            MaxRows: 2,
+        }, context.ContextUser);
+        const rows = existing.Results ?? [];
+        if (rows.length > 1) {
+            LogError(`[TaskGraphService] More than one '${TASK_TYPE_NAME}' task type exists. Binding the oldest ` +
+                `(${rows[0].ID}), but graphs stamped with the other are invisible to the dispatcher's ` +
+                `sweep and will never settle. Merge them.`);
         }
-        return tt.ID;
+        return rows[0]?.ID ?? null;
     }
     /** Writes the parent task that represents the graph as a whole. */
     async persistParent(spec, taskTypeID, context) {
@@ -591,13 +1114,32 @@ export class TaskGraphService {
         // dispatcher memory because the dispatcher that finishes a graph is frequently not the
         // process that accepted it — a restart, a second instance, or simply a long-running graph
         // all break that assumption. Anything the completion path needs has to be durable too.
-        parent.InputPayload = JSON.stringify({
+        // Done before the write, and reported: a value that silently left the envelope becomes a
+        // condition reading absent-data and taking the other branch, with nothing saying why.
+        const sanitized = SanitizeInvocationEnvelope(context.Invocation);
+        if (sanitized.DroppedPaths.length > 0) {
+            LogStatus(`[TaskGraphService] Invocation envelope for '${spec.workflowName}' dropped ` +
+                `${sanitized.DroppedPaths.length} non-persistable value(s): ` +
+                `${sanitized.DroppedPaths.join(', ')}. Conditions referencing them will read as ` +
+                `absent data. Pass plain JSON values for anything a condition needs.`);
+        }
+        // Only written when the caller supplied one, so a graph with no invocation envelope
+        // carries no key at all rather than a misleading empty object. SANITIZED first: the
+        // agent's `context` is documented as possibly a class instance holding connections and
+        // credentials, and carrying it verbatim threw `Converting circular structure to JSON`
+        // on any context with a socket in it — killing the run at submit time — while a context
+        // that happened to serialize would have written its credentials to this row.
+        parent.InputPayload = JSON.stringify(BuildTaskGraphParentInputPayload({
             continuation: spec.continuation ?? 'message',
             reinvokeDepth: context.ReinvokeDepth ?? 0,
             failureSemantics: spec.failureSemantics ?? 'block',
             submittedByAgentRunID: context.AgentRunID ?? null,
             submittedByUserID: context.ContextUser?.ID ?? null,
-        });
+            invocation: sanitized.Envelope
+                ? { data: sanitized.Envelope.Data, context: sanitized.Envelope.Context }
+                : null,
+            startPaused: context.Debug?.paused === true,
+        }));
         if (!(await parent.Save())) {
             throw new Error(`Could not create parent task: ${parent.LatestResult?.CompleteMessage ?? 'unknown error'}`);
         }
@@ -746,7 +1288,22 @@ export class TaskGraphService {
         }
     }
     async loadChildren(parentTaskID, context) {
-        const result = await RunView.FromMetadataProvider(context.Provider).RunView({ EntityName: 'MJ: Tasks', ExtraFilter: `ParentID='${parentTaskID}'`, ResultType: 'entity_object' }, context.ContextUser);
+        // `BypassCache` for the reason the dispatcher documents at every one of its reads (C4): task
+        // status is written by the claim protocol's direct SQL, which fires no cache invalidation.
+        // A cached read here returns PRE-EXECUTION state, and both callers act on status — Cancel's
+        // "leave terminal work alone" guard would pass for a task that has since completed, and
+        // write `Cancelled` over a `Complete` row. That is precisely the history-rewriting the guard
+        // exists to prevent, performed by the guard itself.
+        // Type-scoped for the same reason the sub-graph walk is (R3-10): these rows are about to be
+        // written, and `MJ: Tasks` holds conversation tasks and users' own to-dos too.
+        const typeID = await this.findTaskTypeID(context);
+        const ofType = typeID ? `TypeID='${typeID}' AND ` : '';
+        const result = await RunView.FromMetadataProvider(context.Provider).RunView({
+            EntityName: 'MJ: Tasks',
+            ExtraFilter: `${ofType}ParentID='${parentTaskID}'`,
+            ResultType: 'entity_object',
+            BypassCache: true,
+        }, context.ContextUser);
         return (result.Success ? result.Results : []) ?? [];
     }
 }