@open-multi-agent/core 1.7.0 → 1.8.0

package/dist/orchestrator/orchestrator.js

@@ -49,6 +49,8 @@ import { registerBuiltInTools } from '../tool/built-in/index.js';
 import { defaultWorkspaceDir } from '../tool/built-in/path-safety.js';
 import { Team } from '../team/team.js';
 import { TaskQueue } from '../task/queue.js';
+import { Checkpoint } from '../memory/checkpoint.js';
+import { InMemoryStore } from '../memory/store.js';
 import { createTask, validateTaskDependencies } from '../task/task.js';
 import { extractJSON, validateOutput } from '../agent/structured-output.js';
 import { Scheduler } from './scheduler.js';
@@ -292,6 +294,53 @@ export async function executeWithRetry(run, task, onRetry, delayFn = sleep) {
         toolCalls: [],
     };
 }
+/**
+ * Resolve a parsed task spec's `verify` field into a full
+ * {@link ConsensusVerifyOptions} (or `undefined` when no verify should run).
+ *
+ * - Full `ConsensusVerifyOptions` (already has `judges`): used as-is.
+ * - `true` or `CoordinatorVerifySpec` (no `judges`): merged with
+ *   `verifyJudges` when provided; ignored when `verifyJudges` is absent.
+ * - `undefined`: no verify.
+ */
+function resolveVerify(spec, verifyJudges) {
+    if (spec === undefined)
+        return undefined;
+    if (spec !== true && 'judges' in spec)
+        return spec;
+    if (!verifyJudges || verifyJudges.length === 0)
+        return undefined;
+    const partial = spec === true ? {} : spec;
+    return {
+        judges: verifyJudges,
+        ...(partial.mode !== undefined ? { mode: partial.mode } : {}),
+        ...(partial.quorum !== undefined ? { quorum: partial.quorum } : {}),
+        ...(partial.maxRounds !== undefined ? { maxRounds: partial.maxRounds } : {}),
+        ...(partial.onDissent !== undefined ? { onDissent: partial.onDissent } : {}),
+    };
+}
+/**
+ * Parse the coordinator-emitted `verify` field on a task JSON object.
+ * Accepts `true` (use all defaults) or a partial object with `mode`,
+ * `quorum`, `maxRounds`, and/or `onDissent`. Returns `undefined` for any
+ * other value so missing / null / unrecognised values are ignored safely.
+ */
+function parseCoordinatorVerify(raw) {
+    if (raw === true)
+        return true;
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const obj = raw;
+    const mode = obj['mode'] === 'refute' || obj['mode'] === 'lens' ? obj['mode'] : undefined;
+    const quorum = typeof obj['quorum'] === 'number' && obj['quorum'] >= 1 ? Math.floor(obj['quorum']) : undefined;
+    const maxRounds = typeof obj['maxRounds'] === 'number' && obj['maxRounds'] >= 1 ? Math.floor(obj['maxRounds']) : undefined;
+    const onDissent = obj['onDissent'] === 'revise' || obj['onDissent'] === 'reject' || obj['onDissent'] === 'keep'
+        ? obj['onDissent']
+        : undefined;
+    if (mode === undefined && quorum === undefined && maxRounds === undefined && onDissent === undefined)
+        return true;
+    return { mode, quorum, maxRounds, onDissent };
+}
 /**
  * Attempt to extract a JSON array of task specs from the coordinator's raw
  * output. The coordinator is prompted to emit JSON inside a ```json … ``` fence
@@ -336,6 +385,7 @@ function parseTaskSpecs(raw) {
                 priority: obj['priority'] === 'low' || obj['priority'] === 'normal' || obj['priority'] === 'high' || obj['priority'] === 'critical'
                     ? obj['priority']
                     : undefined,
+                verify: parseCoordinatorVerify(obj['verify']),
             });
         }
         return specs.length > 0 ? specs : null;
@@ -473,6 +523,54 @@ function buildTaskAgentTeamInfo(ctx, taskId, traceBase, delegationDepth, delegat
         runDelegatedAgent,
     };
 }
+async function saveRunCheckpoint(queue, ctx) {
+    const active = ctx.checkpoint;
+    if (!active)
+        return;
+    // Best-effort: a checkpoint write must never take down the run it protects.
+    // Both snapshot construction and the store write are guarded, so a failing
+    // store (e.g. a transient Redis/SQLite error) is surfaced via `onProgress`
+    // and the run continues — the next completed task retries the write.
+    const save = async () => {
+        const sharedMem = ctx.team.getSharedMemoryInstance();
+        const completedTaskResults = queue.getByStatus('completed').map((task) => ({
+            taskId: task.id,
+            ...(task.assignee !== undefined ? { assignee: task.assignee } : {}),
+            ...(task.result !== undefined ? { result: task.result } : {}),
+        }));
+        const snapshot = {
+            version: 1,
+            mode: active.mode,
+            createdAt: new Date().toISOString(),
+            ...(active.runId !== undefined ? { runId: active.runId } : {}),
+            ...(active.goal !== undefined ? { goal: active.goal } : {}),
+            queue: queue.snapshot(),
+            // When the checkpoint store IS the shared-memory store, the entries are
+            // already durable there — embedding a full snapshot on every task would
+            // be ~O(N^2) write volume. Persist only the turn counter (cheap) so TTL
+            // expiry stays correct; restore reads the entries straight from the store.
+            ...(sharedMem && !active.reusesSharedMemoryStore
+                ? { sharedMemory: await sharedMem.snapshot() }
+                : {}),
+            ...(sharedMem ? { turnCount: sharedMem.getTurnCount() } : {}),
+            completedTaskResults,
+        };
+        await active.manager.save(snapshot);
+    };
+    const nextSave = active.saveChain.catch(() => undefined).then(save);
+    // Keep the stored chain non-rejecting so a failed save never leaves an
+    // unhandled rejection or blocks the next checkpoint in the chain.
+    active.saveChain = nextSave.catch(() => undefined);
+    try {
+        await nextSave;
+    }
+    catch (error) {
+        ctx.config.onProgress?.({
+            type: 'error',
+            data: { kind: 'checkpoint_save_failed', error },
+        });
+    }
+}
 /**
  * Execute all tasks in `queue` using agents in `pool`, respecting dependencies
  * and running independent tasks in parallel.
@@ -690,6 +788,7 @@ async function executeQueue(queue, ctx) {
                 }
                 const completedTask = queue.complete(task.id, effective.output);
                 completedThisRound.push(completedTask);
+                await saveRunCheckpoint(queue, ctx);
                 config.onProgress?.({
                     type: 'task_complete',
                     task: task.id,
@@ -1057,6 +1156,7 @@ async function runTaskVerify(task, assignee, result, sharedMem, ctx) {
 export class OpenMultiAgent {
     config;
     teams = new Map();
+    fallbackCheckpointStore = new InMemoryStore();
     completedTaskCount = 0;
     /**
      * @param config - Optional top-level configuration.
@@ -1081,6 +1181,7 @@ export class OpenMultiAgent {
             defaultCwd: config.defaultCwd === undefined ? defaultWorkspaceDir() : config.defaultCwd,
             maxTokenBudget: config.maxTokenBudget,
             defaultToolPreset: config.defaultToolPreset,
+            checkpoint: config.checkpoint,
             onApproval: config.onApproval,
             onPlanReady: config.onPlanReady,
             onAgentStream: config.onAgentStream,
@@ -1270,33 +1371,7 @@ export class OpenMultiAgent {
         // ------------------------------------------------------------------
         // Step 1: Coordinator decomposes goal into tasks
         // ------------------------------------------------------------------
-        const coordinatorBaseConfig = {
-            name: 'coordinator',
-            model: coordinatorOverrides?.model ?? this.config.defaultModel,
-            ...(coordinatorOverrides?.adapter !== undefined ? { adapter: coordinatorOverrides.adapter } : {}),
-            provider: coordinatorOverrides?.provider ?? this.config.defaultProvider,
-            baseURL: coordinatorOverrides?.baseURL ?? this.config.defaultBaseURL,
-            apiKey: coordinatorOverrides?.apiKey ?? this.config.defaultApiKey,
-            systemPrompt: this.buildCoordinatorPrompt(agentConfigs, coordinatorOverrides),
-            maxTurns: coordinatorOverrides?.maxTurns ?? 3,
-            maxTokens: coordinatorOverrides?.maxTokens,
-            temperature: coordinatorOverrides?.temperature,
-            topP: coordinatorOverrides?.topP,
-            topK: coordinatorOverrides?.topK,
-            minP: coordinatorOverrides?.minP,
-            parallelToolCalls: coordinatorOverrides?.parallelToolCalls,
-            frequencyPenalty: coordinatorOverrides?.frequencyPenalty,
-            presencePenalty: coordinatorOverrides?.presencePenalty,
-            extraBody: coordinatorOverrides?.extraBody,
-            toolPreset: coordinatorOverrides?.toolPreset,
-            tools: coordinatorOverrides?.tools,
-            disallowedTools: coordinatorOverrides?.disallowedTools,
-            cwd: coordinatorOverrides?.cwd === undefined
-                ? this.config.defaultCwd
-                : coordinatorOverrides.cwd,
-            loopDetection: coordinatorOverrides?.loopDetection,
-            timeoutMs: coordinatorOverrides?.timeoutMs,
-        };
+        const coordinatorBaseConfig = this.buildCoordinatorBaseConfig(coordinatorOverrides, agentConfigs, (options?.verifyJudges?.length ?? 0) > 0);
         const coordinatorConfig = withModelRoute(coordinatorBaseConfig, routeMatches(options?.modelRouting, { phase: 'coordinator', agent: 'coordinator' }));
         const decompositionPrompt = this.buildDecompositionPrompt(goal, agentConfigs);
         const coordinatorAgent = buildAgent(coordinatorConfig);
@@ -1333,7 +1408,7 @@ export class OpenMultiAgent {
         if (taskSpecs && taskSpecs.length > 0) {
             // Map title-based dependsOn references to real task IDs so we can
             // build the dependency graph before adding tasks to the queue.
-            this.loadSpecsIntoQueue(taskSpecs, agentConfigs, queue);
+            this.loadSpecsIntoQueue(taskSpecs, agentConfigs, queue, options?.verifyJudges);
         }
         else {
             // Coordinator failed to produce structured output — fall back to
@@ -1355,12 +1430,14 @@ export class OpenMultiAgent {
         // Step 4: Build pool and execute
         // ------------------------------------------------------------------
         const pool = this.buildPool(agentConfigs);
+        const activeCheckpoint = this.createActiveCheckpoint(team, options?.checkpoint ?? this.config.checkpoint, 'runTeam', goal);
         const ctx = {
             team,
             pool,
             scheduler,
             agentResults,
             config: this.config,
+            ...(activeCheckpoint ? { checkpoint: activeCheckpoint } : {}),
             runId,
             abortSignal: options?.abortSignal,
             cumulativeUsage,
@@ -1419,6 +1496,7 @@ export class OpenMultiAgent {
                 maxRetries: task.maxRetries,
                 retryDelayMs: task.retryDelayMs,
                 retryBackoff: task.retryBackoff,
+                verify: task.verify,
                 metrics: undefined,
             }));
             this.config.onProgress?.({
@@ -1444,39 +1522,25 @@ export class OpenMultiAgent {
             maxRetries: task.maxRetries,
             retryDelayMs: task.retryDelayMs,
             retryBackoff: task.retryBackoff,
+            verify: task.verify,
             metrics: taskMetrics.get(task.id),
         }));
         // ------------------------------------------------------------------
         // Step 5: Coordinator synthesises final result
         // ------------------------------------------------------------------
-        if (options?.abortSignal?.aborted) {
-            return this.buildTeamRunResult(agentResults, goal, taskRecords);
-        }
-        if (maxTokenBudget !== undefined
-            && cumulativeUsage.input_tokens + cumulativeUsage.output_tokens > maxTokenBudget) {
+        const synthesis = await this.runCoordinatorSynthesis(team, queue, goal, coordinatorBaseConfig, {
+            modelRouting: options?.modelRouting,
+            runId,
+            abortSignal: options?.abortSignal,
+            cumulativeUsage,
+            maxTokenBudget,
+        });
+        if (synthesis === null) {
+            // Aborted or already over budget — return raw task outputs, no synthesis.
             return this.buildTeamRunResult(agentResults, goal, taskRecords);
         }
-        const synthesisPrompt = await this.buildSynthesisPrompt(goal, queue.list(), team);
-        const synthesisAgent = buildAgent(withModelRoute(coordinatorBaseConfig, routeMatches(options?.modelRouting, { phase: 'synthesis', agent: 'coordinator' })));
-        const synthTraceOptions = this.config.onTrace
-            ? { onTrace: this.config.onTrace, runId: runId ?? '', traceAgent: 'coordinator' }
-            : undefined;
-        const synthesisResult = await synthesisAgent.run(synthesisPrompt, synthTraceOptions);
-        agentResults.set('coordinator', synthesisResult);
-        cumulativeUsage = addUsage(cumulativeUsage, synthesisResult.tokenUsage);
-        if (maxTokenBudget !== undefined
-            && cumulativeUsage.input_tokens + cumulativeUsage.output_tokens > maxTokenBudget) {
-            this.config.onProgress?.({
-                type: 'budget_exceeded',
-                agent: 'coordinator',
-                data: new TokenBudgetExceededError('coordinator', cumulativeUsage.input_tokens + cumulativeUsage.output_tokens, maxTokenBudget),
-            });
-        }
-        this.config.onProgress?.({
-            type: 'agent_complete',
-            agent: 'coordinator',
-            data: synthesisResult,
-        });
+        agentResults.set('coordinator', synthesis.result);
+        cumulativeUsage = synthesis.cumulativeUsage;
         // Note: coordinator decompose and synthesis are internal meta-steps.
         // Only actual user tasks (non-coordinator keys) are counted in
         // buildTeamRunResult, so we do not increment completedTaskCount here.
@@ -1522,8 +1586,8 @@ export class OpenMultiAgent {
      *
      * Task IDs, dependencies, assignees, titles, and descriptions are used exactly
      * as stored in the artifact. This is intentionally execution-only; it does not
-     * synthesize a coordinator final answer and it does not implement durable
-     * checkpoints.
+     * synthesize a coordinator final answer. Durable checkpoints are available
+     * through the same opt-in `checkpoint` option used by `runTasks`.
      */
     async runFromPlan(team, plan, options) {
         if (plan.version !== 1) {
@@ -1538,6 +1602,63 @@ export class OpenMultiAgent {
         queue.addBatch(tasks);
         return this.executeExplicitTaskQueue(team, queue, options, plan.goal);
     }
+    async restore(team, tasksOrOptions, maybeOptions) {
+        const hasTaskSource = Array.isArray(tasksOrOptions) || this.isPlanArtifact(tasksOrOptions);
+        const options = hasTaskSource ? maybeOptions : tasksOrOptions;
+        const activeCheckpoint = this.createActiveCheckpoint(team, options?.checkpoint ?? this.config.checkpoint ?? true, 'runTasks', options?.goal);
+        const snapshot = activeCheckpoint ? await activeCheckpoint.manager.loadLatest() : null;
+        if (!snapshot) {
+            if (Array.isArray(tasksOrOptions)) {
+                const queue = new TaskQueue();
+                this.loadSpecsIntoQueue(tasksOrOptions.map((t) => ({
+                    title: t.title,
+                    description: t.description,
+                    assignee: t.assignee,
+                    dependsOn: t.dependsOn,
+                    memoryScope: t.memoryScope,
+                    maxRetries: t.maxRetries,
+                    retryDelayMs: t.retryDelayMs,
+                    retryBackoff: t.retryBackoff,
+                    role: t.role,
+                    priority: t.priority,
+                    verify: t.verify,
+                })), team.getAgents(), queue);
+                return this.executeExplicitTaskQueue(team, queue, options, options?.goal, undefined, activeCheckpoint);
+            }
+            if (this.isPlanArtifact(tasksOrOptions)) {
+                const queue = new TaskQueue();
+                const tasks = this.tasksFromPlan(tasksOrOptions);
+                const validation = validateTaskDependencies(tasks);
+                if (!validation.valid) {
+                    throw new Error(`Invalid plan artifact: ${validation.errors.join(' ')}`);
+                }
+                queue.addBatch(tasks);
+                return this.executeExplicitTaskQueue(team, queue, options, tasksOrOptions.goal ?? options?.goal, undefined, activeCheckpoint);
+            }
+            const queue = new TaskQueue();
+            return this.executeExplicitTaskQueue(team, queue, options, options?.goal, undefined, activeCheckpoint);
+        }
+        const sharedMem = team.getSharedMemoryInstance();
+        if (sharedMem && snapshot.sharedMemory) {
+            await sharedMem.restore(snapshot.sharedMemory);
+        }
+        else if (sharedMem && snapshot.turnCount !== undefined) {
+            // Reused-store checkpoint: entries are already in the store; only the
+            // turn counter needs restoring so TTL expiry resumes correctly.
+            sharedMem.setTurnCount(snapshot.turnCount);
+        }
+        const queue = TaskQueue.fromSnapshot(snapshot.queue, { resetInProgress: true });
+        const agentResults = this.agentResultsFromCheckpoint(snapshot, queue);
+        const checkpointForResume = activeCheckpoint
+            ? {
+                ...activeCheckpoint,
+                mode: snapshot.mode,
+                ...(snapshot.goal !== undefined ? { goal: snapshot.goal } : {}),
+                ...(snapshot.runId !== undefined ? { runId: snapshot.runId } : {}),
+            }
+            : undefined;
+        return this.executeExplicitTaskQueue(team, queue, options, snapshot.goal ?? options?.goal, agentResults, checkpointForResume, options?.coordinator);
+    }
     /**
      * Run a team with an explicitly provided task list.
      *
@@ -1685,32 +1806,32 @@ export class OpenMultiAgent {
     // Private helpers
     // -------------------------------------------------------------------------
     /** Build the system prompt given to the coordinator agent. */
-    buildCoordinatorSystemPrompt(agents) {
+    buildCoordinatorSystemPrompt(agents, hasVerifyJudges) {
         return [
             'You are a task coordinator responsible for decomposing high-level goals',
             'into concrete, actionable tasks and assigning them to the right team members.',
             '',
             this.buildCoordinatorRosterSection(agents),
             '',
-            this.buildCoordinatorOutputFormatSection(),
+            this.buildCoordinatorOutputFormatSection(hasVerifyJudges),
             '',
             this.buildCoordinatorSynthesisSection(),
         ].join('\n');
     }
     /** Build coordinator system prompt with optional caller overrides. */
-    buildCoordinatorPrompt(agents, config) {
+    buildCoordinatorPrompt(agents, config, hasVerifyJudges) {
         if (config?.systemPrompt) {
             return [
                 config.systemPrompt,
                 '',
                 this.buildCoordinatorRosterSection(agents),
                 '',
-                this.buildCoordinatorOutputFormatSection(),
+                this.buildCoordinatorOutputFormatSection(hasVerifyJudges),
                 '',
                 this.buildCoordinatorSynthesisSection(),
             ].join('\n');
         }
-        const base = this.buildCoordinatorSystemPrompt(agents);
+        const base = this.buildCoordinatorSystemPrompt(agents, hasVerifyJudges);
         if (!config?.instructions) {
             return base;
         }
@@ -1732,8 +1853,8 @@ export class OpenMultiAgent {
         ].join('\n');
     }
     /** Build the coordinator JSON output-format section. */
-    buildCoordinatorOutputFormatSection() {
-        return [
+    buildCoordinatorOutputFormatSection(hasVerifyJudges) {
+        const lines = [
             '## Output Format',
             'When asked to decompose a goal, respond ONLY with a JSON array of task objects.',
             'Each task must have:',
@@ -1741,17 +1862,12 @@ export class OpenMultiAgent {
             '  - "description": Full task description with context and expected output (string)',
             '  - "assignee":    One of the agent names listed in the roster (string)',
             '  - "dependsOn":   Array of titles of tasks this task depends on (string[], may be empty).',
-            '',
-            '## Dependency Guidance',
-            'Prefer the minimum set of upstream tasks each assignee needs. When deciding dependsOn for agent X:',
-            '  1. Use X\'s system prompt as the primary signal for what inputs it consumes.',
-            '  2. Lean toward including a task as a dependency only when X\'s system prompt names or describes needing that kind of input.',
-            '  3. Avoid adding a dependency just because the information "would be useful" or matches general best practice; if X\'s system prompt gives no indication it consumes that input, prefer to leave it out.',
-            '  4. When uncertain, prefer fewer dependencies over more — extra parents cost parallelism and tokens.',
-            '',
-            'Wrap the JSON in a ```json code fence.',
-            'Do not include any text outside the code fence.',
-        ].join('\n');
+        ];
+        if (hasVerifyJudges) {
+            lines.push('  - "verify":      (optional) Set to true to apply consensus judge verification on this task\'s result.', '                   Or set to an object with any of: "mode" ("refute"|"lens"), "quorum" (number),', '                   "maxRounds" (number), "onDissent" ("revise"|"reject"|"keep").', '                   Omit for tasks where a single agent\'s answer is sufficient.');
+        }
+        lines.push('', '## Dependency Guidance', 'Prefer the minimum set of upstream tasks each assignee needs. When deciding dependsOn for agent X:', '  1. Use X\'s system prompt as the primary signal for what inputs it consumes.', '  2. Lean toward including a task as a dependency only when X\'s system prompt names or describes needing that kind of input.', '  3. Avoid adding a dependency just because the information "would be useful" or matches general best practice; if X\'s system prompt gives no indication it consumes that input, prefer to leave it out.', '  4. When uncertain, prefer fewer dependencies over more — extra parents cost parallelism and tokens.', '', 'Wrap the JSON in a ```json code fence.', 'Do not include any text outside the code fence.');
+        return lines.join('\n');
     }
     /** Build the coordinator synthesis guidance section. */
     buildCoordinatorSynthesisSection() {
@@ -1773,6 +1889,77 @@ export class OpenMultiAgent {
             'Return ONLY the JSON task array in a ```json code fence.',
         ].join('\n');
     }
+    /**
+     * Build the base coordinator {@link AgentConfig} shared by the decomposition
+     * and synthesis passes. Falls back to orchestrator defaults for any field the
+     * caller's {@link CoordinatorConfig} leaves unset.
+     */
+    buildCoordinatorBaseConfig(coordinatorOverrides, agentConfigs, hasVerifyJudges) {
+        return {
+            name: 'coordinator',
+            model: coordinatorOverrides?.model ?? this.config.defaultModel,
+            ...(coordinatorOverrides?.adapter !== undefined ? { adapter: coordinatorOverrides.adapter } : {}),
+            provider: coordinatorOverrides?.provider ?? this.config.defaultProvider,
+            baseURL: coordinatorOverrides?.baseURL ?? this.config.defaultBaseURL,
+            apiKey: coordinatorOverrides?.apiKey ?? this.config.defaultApiKey,
+            systemPrompt: this.buildCoordinatorPrompt(agentConfigs, coordinatorOverrides, hasVerifyJudges),
+            maxTurns: coordinatorOverrides?.maxTurns ?? 3,
+            maxTokens: coordinatorOverrides?.maxTokens,
+            temperature: coordinatorOverrides?.temperature,
+            topP: coordinatorOverrides?.topP,
+            topK: coordinatorOverrides?.topK,
+            minP: coordinatorOverrides?.minP,
+            parallelToolCalls: coordinatorOverrides?.parallelToolCalls,
+            frequencyPenalty: coordinatorOverrides?.frequencyPenalty,
+            presencePenalty: coordinatorOverrides?.presencePenalty,
+            extraBody: coordinatorOverrides?.extraBody,
+            toolPreset: coordinatorOverrides?.toolPreset,
+            tools: coordinatorOverrides?.tools,
+            disallowedTools: coordinatorOverrides?.disallowedTools,
+            cwd: coordinatorOverrides?.cwd === undefined
+                ? this.config.defaultCwd
+                : coordinatorOverrides.cwd,
+            loopDetection: coordinatorOverrides?.loopDetection,
+            timeoutMs: coordinatorOverrides?.timeoutMs,
+        };
+    }
+    /**
+     * Run the coordinator synthesis pass over completed task results. Returns the
+     * synthesis result plus updated cumulative usage, or `null` when synthesis is
+     * skipped (run aborted, or the token budget was already exhausted before the
+     * pass). Emits `budget_exceeded` (when synthesis tips over budget) and
+     * `agent_complete`, mirroring the inline `runTeam` path. Does not mutate
+     * `agentResults` — the caller records the `'coordinator'` entry.
+     */
+    async runCoordinatorSynthesis(team, queue, goal, coordinatorBaseConfig, opts) {
+        if (opts.abortSignal?.aborted)
+            return null;
+        if (opts.maxTokenBudget !== undefined
+            && opts.cumulativeUsage.input_tokens + opts.cumulativeUsage.output_tokens > opts.maxTokenBudget) {
+            return null;
+        }
+        const synthesisPrompt = await this.buildSynthesisPrompt(goal, queue.list(), team);
+        const synthesisAgent = buildAgent(withModelRoute(coordinatorBaseConfig, routeMatches(opts.modelRouting, { phase: 'synthesis', agent: 'coordinator' })));
+        const synthTraceOptions = this.config.onTrace
+            ? { onTrace: this.config.onTrace, runId: opts.runId ?? '', traceAgent: 'coordinator' }
+            : undefined;
+        const result = await synthesisAgent.run(synthesisPrompt, synthTraceOptions);
+        const cumulativeUsage = addUsage(opts.cumulativeUsage, result.tokenUsage);
+        if (opts.maxTokenBudget !== undefined
+            && cumulativeUsage.input_tokens + cumulativeUsage.output_tokens > opts.maxTokenBudget) {
+            this.config.onProgress?.({
+                type: 'budget_exceeded',
+                agent: 'coordinator',
+                data: new TokenBudgetExceededError('coordinator', cumulativeUsage.input_tokens + cumulativeUsage.output_tokens, opts.maxTokenBudget),
+            });
+        }
+        this.config.onProgress?.({
+            type: 'agent_complete',
+            agent: 'coordinator',
+            data: result,
+        });
+        return { result, cumulativeUsage };
+    }
     /** Build the synthesis prompt shown to the coordinator after all tasks complete. */
     async buildSynthesisPrompt(goal, tasks, team) {
         const completedTasks = tasks.filter((t) => t.status === 'completed');
@@ -1823,18 +2010,20 @@ export class OpenMultiAgent {
             ...(task.retryBackoff !== undefined ? { retryBackoff: task.retryBackoff } : {}),
         }));
     }
-    async executeExplicitTaskQueue(team, queue, options, goal) {
+    async executeExplicitTaskQueue(team, queue, options, goal, initialAgentResults, activeCheckpoint, coordinatorForSynthesis) {
         const agentConfigs = team.getAgents();
         const scheduler = new Scheduler('dependency-first');
         scheduler.autoAssign(queue, agentConfigs);
         const pool = this.buildPool(agentConfigs);
-        const agentResults = new Map();
+        const agentResults = initialAgentResults ?? new Map();
+        const checkpoint = activeCheckpoint ?? this.createActiveCheckpoint(team, options?.checkpoint ?? this.config.checkpoint, 'runTasks', goal);
         const ctx = {
             team,
             pool,
             scheduler,
             agentResults,
             config: this.config,
+            ...(checkpoint ? { checkpoint } : {}),
             runId: this.config.onTrace ? generateRunId() : undefined,
             abortSignal: options?.abortSignal,
             cumulativeUsage: ZERO_USAGE,
@@ -1847,6 +2036,45 @@ export class OpenMultiAgent {
             taskLeafById: new Map(queue.list().map((task) => [task.id, isLeafTask(task, queue.list())])),
         };
         await executeQueue(queue, ctx);
+        // A resumed `runTeam` re-runs the coordinator synthesis so the restored
+        // result matches a fresh `runTeam` (a synthesized final answer, not raw
+        // per-task outputs). Best-effort: a missing/unusable coordinator config or
+        // a failing synthesis call must not discard the recovered work — on failure
+        // we surface `synthesis_failed` and fall back to raw outputs.
+        if (checkpoint?.mode === 'runTeam' && goal !== undefined) {
+            try {
+                const coordinatorBaseConfig = this.buildCoordinatorBaseConfig(coordinatorForSynthesis, agentConfigs, false);
+                const synthesis = await this.runCoordinatorSynthesis(team, queue, goal, coordinatorBaseConfig, {
+                    modelRouting: options?.modelRouting,
+                    runId: ctx.runId,
+                    abortSignal: options?.abortSignal,
+                    cumulativeUsage: ctx.cumulativeUsage,
+                    maxTokenBudget: ctx.maxTokenBudget,
+                });
+                if (synthesis !== null && synthesis.result.success) {
+                    agentResults.set('coordinator', synthesis.result);
+                    ctx.cumulativeUsage = synthesis.cumulativeUsage;
+                }
+                else if (synthesis !== null) {
+                    // Synthesis ran but the coordinator agent failed (e.g. the LLM call
+                    // errored). Keep the recovered task outputs and surface the failure
+                    // rather than attaching a failed answer under `'coordinator'`.
+                    this.config.onProgress?.({
+                        type: 'error',
+                        data: {
+                            kind: 'synthesis_failed',
+                            error: new Error(synthesis.result.output || 'coordinator synthesis failed'),
+                        },
+                    });
+                }
+            }
+            catch (error) {
+                this.config.onProgress?.({
+                    type: 'error',
+                    data: { kind: 'synthesis_failed', error },
+                });
+            }
+        }
         const taskRecords = queue.list().map((task) => ({
             id: task.id,
             title: task.title,
@@ -1858,17 +2086,68 @@ export class OpenMultiAgent {
             maxRetries: task.maxRetries,
             retryDelayMs: task.retryDelayMs,
             retryBackoff: task.retryBackoff,
+            verify: task.verify,
             metrics: ctx.taskMetrics.get(task.id),
         }));
         return this.buildTeamRunResult(agentResults, goal, taskRecords);
     }
+    createActiveCheckpoint(team, config, mode, goal) {
+        if (config === undefined || config === false)
+            return undefined;
+        const options = config === true ? {} : config;
+        if (options.enabled === false)
+            return undefined;
+        // The instance-level fallback store is shared across every run on this
+        // orchestrator, so concurrent runs would overwrite each other at the
+        // default checkpoint key. Require a `runId` (or an explicit `key`/`store`)
+        // before falling back, so each run resolves to a distinct, resumable key.
+        const sharedStore = team.getSharedMemory();
+        const explicitStore = options.store ?? sharedStore;
+        if (!explicitStore && options.runId === undefined && options.key === undefined) {
+            throw new Error('Checkpoint requires a `runId` (or an explicit `store`/`key`) when the team has no ' +
+                'shared-memory store. Without one, concurrent runs would share the fallback store and ' +
+                "overwrite each other's checkpoint at the default key.");
+        }
+        const store = explicitStore ?? this.fallbackCheckpointStore;
+        return {
+            manager: new Checkpoint(store, options),
+            mode,
+            ...(goal !== undefined ? { goal } : {}),
+            ...(options.runId !== undefined ? { runId: options.runId } : {}),
+            reusesSharedMemoryStore: sharedStore !== undefined && store === sharedStore,
+            saveChain: Promise.resolve(),
+        };
+    }
+    agentResultsFromCheckpoint(snapshot, queue) {
+        const taskById = new Map(queue.list().map((task) => [task.id, task]));
+        const agentResults = new Map();
+        for (const completed of snapshot.completedTaskResults) {
+            const task = taskById.get(completed.taskId);
+            const assignee = completed.assignee ?? task?.assignee ?? 'unknown';
+            const output = completed.result ?? task?.result ?? '';
+            agentResults.set(`${assignee}:${completed.taskId}`, {
+                success: true,
+                output,
+                messages: [],
+                tokenUsage: ZERO_USAGE,
+                toolCalls: [],
+            });
+        }
+        return agentResults;
+    }
+    isPlanArtifact(value) {
+        if (value === null || typeof value !== 'object')
+            return false;
+        const artifact = value;
+        return artifact['version'] === 1 && Array.isArray(artifact['tasks']);
+    }
     /**
      * Load a list of task specs into a queue.
      *
      * Handles title-based `dependsOn` references by building a title→id map first,
      * then resolving them to real IDs before adding tasks to the queue.
      */
-    loadSpecsIntoQueue(specs, agentConfigs, queue) {
+    loadSpecsIntoQueue(specs, agentConfigs, queue, verifyJudges) {
         const agentNames = new Set(agentConfigs.map((a) => a.name));
         const normalizeTitle = (title) => title.toLowerCase().trim();
         const titleCounts = new Map();
@@ -1892,7 +2171,7 @@ export class OpenMultiAgent {
                 retryBackoff: spec.retryBackoff,
                 role: spec.role,
                 priority: spec.priority,
-                verify: spec.verify,
+                verify: resolveVerify(spec.verify, verifyJudges),
             });
             const titleKey = normalizeTitle(spec.title);
             if ((titleCounts.get(titleKey) ?? 0) === 1) {