ai-maestro 1.0.0

package/src/orchestration/orchestration-runtime.mjs

@@ -0,0 +1,1019 @@
+import { runTask, withAccountingLock } from '../task-commands.mjs';
+import { addTask, getTaskById, getTasks, updateTaskStatus } from '../tasks.mjs';
+import { getLatestRunForTask } from '../runner.mjs';
+import { ensureSafetyConfig } from '../safety.mjs';
+import { redactCredentials, redactObject } from '../format.mjs';
+import { evaluateTaskRun, countRunsForTask } from './runtime-gate.mjs';
+import { buildDelegationPlan } from './delegation-manager.mjs';
+import { runOrchestrationLoop } from './orchestration-loop.mjs';
+import { consolidateResults } from './consolidator.mjs';
+import { verifyConsolidatedResult } from './verifier.mjs';
+import { appendOrchestrationEvent, getOrchestrationEvents } from './orchestration-trail.mjs';
+import { computeWaves, planWaveExecution } from './orchestration-scheduler.mjs';
+import { detectFileConflicts } from './file-conflict-detector.mjs';
+
+const SCHEMA_VERSION = 1;
+const DEFAULT_LIMITS = Object.freeze({ maxDepth: 2, maxSubtasks: 8, maxAgentsPerManager: 4, maxTransitions: 40 });
+const TERMINAL_STATUSES = new Set(['completed', 'completed_with_warnings', 'failed', 'blocked', 'needs_human', 'archived']);
+const ACCEPTABLE_DEPENDENCY_STATUSES = new Set(['completed', 'completed_with_warnings']);
+const SUCCESS_PARENT_STATUSES = new Set(['accepted', 'accepted_with_warnings']);
+const SUCCESS_VERIFICATION_OUTCOMES = new Set(['verified', 'verified_with_warnings']);
+const runtimeChains = new Map();
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cloneData(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizeMode(mode) {
+  return mode === 'real' ? 'real' : 'dry-run';
+}
+
+function normalizeTaskId(taskId) {
+  if (taskId === undefined || taskId === null || String(taskId).trim().length === 0) {
+    throw new TypeError('taskId is required');
+  }
+  return String(taskId);
+}
+
+function mergeDefined(base, extra) {
+  const next = { ...base };
+  for (const [key, value] of Object.entries(extra || {})) {
+    if (value !== undefined) next[key] = value;
+  }
+  return next;
+}
+
+function buildResult({ taskId, mode, executed = false, plan = null, executionPlan = undefined, children = [], consolidation = null, verification = null, parentStatus = null, statusOverrideReason = null, trace = [], warnings = [], errors = [], summary = '' }) {
+  return redactObject({
+    schemaVersion: SCHEMA_VERSION,
+    taskId: String(taskId),
+    mode,
+    executed,
+    plan: cloneData(plan),
+    ...(executionPlan !== undefined ? { executionPlan: cloneData(executionPlan) } : {}),
+    children: cloneData(children),
+    consolidation: cloneData(consolidation),
+    verification: cloneData(verification),
+    parentStatus,
+    statusOverrideReason,
+    trace: cloneData(trace),
+    warnings: [...warnings],
+    errors: errors.map(error => typeof error === 'string' ? error : (error && error.message) || String(error)),
+    summary
+  });
+}
+
+async function runSerialized(taskId, fn) {
+  const key = String(taskId);
+  const previous = runtimeChains.get(key) || Promise.resolve();
+  let release;
+  const current = new Promise(resolve => { release = resolve; });
+  runtimeChains.set(key, previous.then(() => current, () => current));
+  await previous.catch(() => {});
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (runtimeChains.get(key) === current) {
+      runtimeChains.delete(key);
+    }
+  }
+}
+
+async function planSerialOrchestration({ task, mode, force, rawInput }) {
+  const suppliedContext = cloneData(rawInput.context || {});
+  const suppliedModules = cloneData(rawInput.moduleResults || {});
+  let runtimeGate = suppliedModules.runtimeGate || suppliedContext.runtimeGateResult || null;
+
+  if (!runtimeGate) {
+    const runsSoFar = await countRunsForTask(task.id);
+    runtimeGate = await evaluateTaskRun({
+      task,
+      projectRoot: process.cwd(),
+      mode,
+      force,
+      runsSoFar
+    });
+  }
+
+  const classification = suppliedModules.classification || runtimeGate.taskClassification || null;
+  const manager = suppliedModules.manager || runtimeGate.selectedManager || null;
+  const engineCandidate = suppliedModules.engineCandidate || runtimeGate.selectedEngine || null;
+  const preflight = suppliedModules.preflight || runtimeGate.preflight || null;
+  const budget = suppliedModules.budget || (runtimeGate.budget && runtimeGate.budget.evaluation) || runtimeGate.budget || null;
+  const policy = suppliedModules.policy || runtimeGate.policy || null;
+
+  const moduleResults = mergeDefined({
+    classification,
+    manager,
+    engineCandidate,
+    preflight,
+    budget,
+    policy,
+    runtimeGate
+  }, suppliedModules);
+
+  const context = {
+    ...suppliedContext,
+    runtimeGateResult: runtimeGate,
+    acceptanceCriteria: suppliedContext.acceptanceCriteria || task.acceptance || []
+  };
+
+  if ((runtimeGate.decision === 'DELEGATE' || (manager && manager.decision === 'decompose')) && !moduleResults.delegation) {
+    moduleResults.delegation = buildDelegationPlan(task, classification || {}, {
+      depth: Number(context.orchestrationDepth || 0)
+    });
+  }
+
+  const plan = runOrchestrationLoop({
+    task: cloneData(task),
+    context,
+    limits: { ...DEFAULT_LIMITS, ...(rawInput.limits || {}) },
+    moduleResults,
+    adapters: rawInput.adapters || {}
+  });
+
+  return plan;
+}
+
+function hasBlockingConflict(plan) {
+  return Array.isArray(plan && plan.conflicts) && plan.conflicts.some(conflict => {
+    const target = String(conflict.file || conflict.path || '').replace(/\\/g, '/').toLowerCase();
+    return conflict.severity === 'critical' ||
+      conflict.type === 'parallel-write' ||
+      conflict.parallel === true ||
+      target === '.env' || target.endsWith('/.env') || target.startsWith('../') || target.includes('/../');
+  });
+}
+
+function normalizeConcurrency(concurrency) {
+  if (!concurrency || concurrency.enabled !== true) {
+    return { enabled: false, strategy: 'serial', maxConcurrent: 1 };
+  }
+  const parsed = Number.parseInt(concurrency.maxConcurrent, 10);
+  const requested = Number.isFinite(parsed) ? parsed : 2;
+  return {
+    enabled: true,
+    strategy: 'controlled-parallel',
+    maxConcurrent: Math.max(1, Math.min(4, requested))
+  };
+}
+
+function plannedSubtasks(plan) {
+  return Array.isArray(plan && plan.plannedSubtasks) ? cloneData(plan.plannedSubtasks) : [];
+}
+
+function subtaskId(subtask) {
+  return String(subtask && subtask.id);
+}
+
+function sortSubtasksById(subtasks) {
+  return [...subtasks].sort((a, b) => subtaskId(a).localeCompare(subtaskId(b)));
+}
+
+function auditWavePlan(waves, subtasks, concurrency) {
+  const byId = new Map(subtasks.map(subtask => [subtaskId(subtask), subtask]));
+  return waves.map(wave => {
+    const waveSubtasks = wave.subtaskIds.map(id => byId.get(String(id))).filter(Boolean);
+    const waveConflicts = detectFileConflicts(waveSubtasks, { projectRoot: process.cwd() });
+    const planned = planWaveExecution({ ...wave, subtasks: waveSubtasks }, subtasks, { waveConflicts, maxConcurrent: concurrency.maxConcurrent });
+    return {
+      waveIndex: wave.waveIndex,
+      parallelSubtaskIds: planned.parallel.map(subtaskId),
+      serialSubtaskIds: planned.serial.map(subtaskId)
+    };
+  });
+}
+
+function dryRunExecutionPlan(plan, concurrencyInput) {
+  const concurrency = normalizeConcurrency(concurrencyInput);
+  if (!concurrency.enabled) return undefined;
+  const subtasks = plannedSubtasks(plan);
+  try {
+    const waves = computeWaves(subtasks);
+    return {
+      strategy: concurrency.strategy,
+      concurrency: { maxConcurrent: concurrency.maxConcurrent, observedMaxActive: 0 },
+      waves: auditWavePlan(waves, subtasks, concurrency)
+    };
+  } catch (error) {
+    return {
+      strategy: concurrency.strategy,
+      concurrency: { maxConcurrent: concurrency.maxConcurrent, observedMaxActive: 0 },
+      waves: [],
+      error: (error && error.message) || String(error)
+    };
+  }
+}
+
+function dependencyList(subtask) {
+  return Array.isArray(subtask.blockedBy) ? subtask.blockedBy.map(String) : [];
+}
+
+function serialOrder(subtasks, plan) {
+  const byId = new Map(subtasks.map(subtask => [String(subtask.id), subtask]));
+  const plannedOrder = plan && plan.simulation && Array.isArray(plan.simulation.order)
+    ? plan.simulation.order.map(String)
+    : subtasks.map(subtask => String(subtask.id));
+  const orderRank = new Map(plannedOrder.map((id, index) => [id, index]));
+  const remaining = new Set(subtasks.map(subtask => String(subtask.id)));
+  const result = [];
+
+  while (remaining.size > 0) {
+    const ready = [...remaining]
+      .filter(id => dependencyList(byId.get(id)).every(dep => !remaining.has(dep)))
+      .sort((a, b) => (orderRank.get(a) ?? 9999) - (orderRank.get(b) ?? 9999) || a.localeCompare(b));
+    if (ready.length === 0) {
+      throw new Error('dependency cycle remained after 03C planning');
+    }
+    const id = ready[0];
+    remaining.delete(id);
+    result.push(byId.get(id));
+  }
+
+  return result;
+}
+
+function childDescription(subtask) {
+  return String(subtask.description || subtask.title || subtask.id);
+}
+
+function assignmentFor(plan, subtaskId) {
+  const assignments = plan && plan.plannedDelegation && Array.isArray(plan.plannedDelegation.assignments)
+    ? plan.plannedDelegation.assignments
+    : [];
+  return assignments.find(item => String(item.subtaskId) === String(subtaskId)) || null;
+}
+
+async function materializeChild(parentTask, subtask, plan) {
+  const existing = (await getTasks()).find(task =>
+    String(task.parentTaskId) === String(parentTask.id) && String(task.subtaskId) === String(subtask.id)
+  );
+  if (existing) return existing;
+
+  const assignment = assignmentFor(plan, subtask.id);
+  return addTask(childDescription(subtask), {
+    title: subtask.title || childDescription(subtask),
+    status: 'pending',
+    priority: parentTask.priority || 'medium',
+    engine: (assignment && assignment.candidateEngine) || subtask.engine || parentTask.engine || 'codex9',
+    files: Array.isArray(subtask.expectedFiles) ? subtask.expectedFiles : (Array.isArray(subtask.files) ? subtask.files : []),
+    acceptance: Array.isArray(subtask.acceptance) ? subtask.acceptance : (Array.isArray(parentTask.acceptance) ? parentTask.acceptance : []),
+    requestKind: parentTask.requestKind || null,
+    sourceRequest: parentTask.sourceRequest || null,
+    sourceSpec: parentTask.sourceSpec || null,
+    parentTaskId: parentTask.id,
+    subtaskId: String(subtask.id),
+    blockedBy: dependencyList(subtask)
+  });
+}
+
+async function materializeChildren(parentTask, subtasks, plan) {
+  const children = [];
+  for (const subtask of subtasks) {
+    children.push(await materializeChild(parentTask, subtask, plan));
+  }
+  return children;
+}
+
+function childResultEntry({ subtask, task, status, run, skipped = false, reason = null }) {
+  return {
+    subtaskId: String(subtask.id),
+    taskId: task ? task.id : null,
+    status: status || (task && task.status) || 'unknown',
+    runId: run && run.runId ? run.runId : null,
+    run: run ? cloneData(run) : null,
+    noChangeExpected: subtask.noChangeExpected === true ||
+      subtask.expectedNoChange === true ||
+      ((subtask.expectedFiles === undefined || (Array.isArray(subtask.expectedFiles) && subtask.expectedFiles.length === 0)) &&
+        subtask.requires && subtask.requires.filesystemWrite === false),
+    skipped,
+    reason
+  };
+}
+
+function evidenceFromRun(run) {
+  if (!run || !run.runId) return [];
+  const evidence = [{ type: 'run-status', sourceId: run.runId, field: 'status', value: { status: run.status } }];
+  if (Object.prototype.hasOwnProperty.call(run, 'workspaceChanged')) {
+    evidence.push({
+      type: 'workspace-diff',
+      sourceId: run.runId,
+      field: 'workspace',
+      value: {
+        workspaceChanged: run.workspaceChanged,
+        changedFiles: Array.isArray(run.changedFiles) ? run.changedFiles : [],
+        createdFiles: Array.isArray(run.createdFiles) ? run.createdFiles : [],
+        deletedFiles: Array.isArray(run.deletedFiles) ? run.deletedFiles : []
+      }
+    });
+  }
+  if (run.syntaxValidation !== undefined || run.syntaxValidationFailed !== undefined) {
+    evidence.push({ type: 'syntax-validation', sourceId: run.runId, field: 'syntaxValidation', value: { syntaxValidation: run.syntaxValidation || [], syntaxValidationFailed: run.syntaxValidationFailed === true } });
+  }
+  if (run.hostValidationFallback !== undefined) {
+    evidence.push({ type: 'host-validation', sourceId: run.runId, field: 'hostValidationFallback', value: run.hostValidationFallback });
+  }
+  if (run.failureCategory !== undefined || run.infrastructureFailure !== undefined) {
+    evidence.push({ type: 'failure-classification', sourceId: run.runId, field: 'failureCategory', value: { failureCategory: run.failureCategory || null, infrastructureFailure: run.infrastructureFailure === true } });
+  }
+  if (Array.isArray(run.warnings) && run.warnings.length > 0) {
+    evidence.push({ type: 'diagnostics', sourceId: run.runId, field: 'warnings', value: { warnings: run.warnings } });
+  }
+  return evidence;
+}
+
+function subtaskResultFromChild(child) {
+  const status = child.status;
+  const run = child.run || null;
+  if (run && run.runId && ['completed', 'completed_with_warnings', 'failed'].includes(status)) {
+    return {
+      subtaskId: child.subtaskId,
+      runId: run.runId,
+      runStatus: status,
+      noChangeExpected: child.noChangeExpected === true,
+      evidence: evidenceFromRun(run),
+      warnings: Array.isArray(run.warnings) ? run.warnings : [],
+      infrastructureFailure: run.infrastructureFailure === true
+    };
+  }
+  if (status === 'blocked') {
+    return { subtaskId: child.subtaskId, runId: null, runStatus: 'blocked', noExecutionReason: 'blocked_before_execution', evidence: [], warnings: child.reason ? [child.reason] : [] };
+  }
+  if (status === 'needs_human') {
+    return { subtaskId: child.subtaskId, runId: null, runStatus: 'needs_human', noExecutionReason: 'needs_human_before_execution', evidence: [], warnings: child.reason ? [child.reason] : [] };
+  }
+  return { subtaskId: child.subtaskId, runId: null, runStatus: null, noExecutionReason: 'result_missing', evidence: [], warnings: child.reason ? [child.reason] : [] };
+}
+
+async function latestRunAndTask(taskId) {
+  return withAccountingLock(async () => {
+    const task = await getTaskById(taskId);
+    const run = await getLatestRunForTask(taskId);
+    return { task, run };
+  });
+}
+
+function dependencyBlockReason(subtask, statusBySubtask) {
+  for (const dependency of dependencyList(subtask)) {
+    const dependencyKey = String(dependency);
+    if (!statusBySubtask.has(dependencyKey)) {
+      continue;
+    }
+    const dependencyStatus = statusBySubtask.get(dependencyKey);
+    if (!ACCEPTABLE_DEPENDENCY_STATUSES.has(dependencyStatus)) {
+      return 'dependency ' + dependency + ' finished as ' + (dependencyStatus || 'missing');
+    }
+  }
+  return null;
+}
+
+async function runChildrenSerially({ parentTask, subtasks, plan, force, suppressOutput, engine }) {
+  const ordered = serialOrder(subtasks, plan);
+  const materialized = await materializeChildren(parentTask, subtasks, plan);
+  const taskBySubtask = new Map(materialized.map(task => [String(task.subtaskId), task]));
+  const statusBySubtask = new Map();
+  const children = [];
+  const errors = [];
+  const warnings = [];
+
+  for (const subtask of ordered) {
+    const childTask = taskBySubtask.get(String(subtask.id));
+    const blockReason = dependencyBlockReason(subtask, statusBySubtask);
+    if (blockReason) {
+      const latest = await withAccountingLock(async () => {
+        await updateTaskStatus(childTask.id, 'blocked');
+        return getTaskById(childTask.id);
+      });
+      statusBySubtask.set(String(subtask.id), 'blocked');
+      children.push(childResultEntry({ subtask, task: latest || childTask, status: 'blocked', run: null, skipped: true, reason: blockReason }));
+      continue;
+    }
+
+    let latest = await latestRunAndTask(childTask.id);
+    if (latest.task && TERMINAL_STATUSES.has(latest.task.status) && !(latest.task.status === 'needs_human' && force === true)) {
+      statusBySubtask.set(String(subtask.id), latest.task.status);
+      children.push(childResultEntry({ subtask, task: latest.task, status: latest.task.status, run: latest.run, skipped: true, reason: 'already_terminal' }));
+      continue;
+    }
+
+    let runOutcome = null;
+    try {
+      runOutcome = await runTask(childTask.id, { force, suppressOutput: true, engine });
+    } catch (error) {
+      const message = 'child ' + subtask.id + ' execution error: ' + ((error && error.message) || String(error));
+      errors.push(message);
+      warnings.push(message);
+      await withAccountingLock(() => updateTaskStatus(childTask.id, 'needs_human'));
+    }
+
+    latest = await latestRunAndTask(childTask.id);
+    const status = (runOutcome && runOutcome.status) || (latest.task ? latest.task.status : 'needs_human');
+    const run = (runOutcome && runOutcome.run) || latest.run;
+    statusBySubtask.set(String(subtask.id), status);
+    children.push(childResultEntry({ subtask, task: latest.task || childTask, status, run, skipped: false, reason: null }));
+  }
+
+  return { children, errors, warnings };
+}
+
+async function executeChildRun({ subtask, childTask, force, engine }) {
+  let runOutcome = null;
+  const errors = [];
+  const warnings = [];
+  try {
+    runOutcome = await runTask(childTask.id, { force, suppressOutput: true, engine });
+  } catch (error) {
+    const message = 'child ' + subtask.id + ' execution error: ' + ((error && error.message) || String(error));
+    errors.push(message);
+    warnings.push(message);
+    await withAccountingLock(() => updateTaskStatus(childTask.id, 'needs_human'));
+  }
+
+  const latest = await latestRunAndTask(childTask.id);
+  const status = (runOutcome && runOutcome.status) || (latest.task ? latest.task.status : 'needs_human');
+  const run = (runOutcome && runOutcome.run) || latest.run;
+  return {
+    entry: childResultEntry({ subtask, task: latest.task || childTask, status, run, skipped: false, reason: null }),
+    status,
+    errors,
+    warnings
+  };
+}
+
+async function markDependencyBlocked({ subtask, childTask, reason }) {
+  const latest = await withAccountingLock(async () => {
+    await updateTaskStatus(childTask.id, 'blocked');
+    return getTaskById(childTask.id);
+  });
+  return childResultEntry({ subtask, task: latest || childTask, status: 'blocked', run: null, skipped: true, reason });
+}
+
+function removeSatisfiedDependencies(subtask, statusBySubtask, pendingIds) {
+  const blockedBy = dependencyList(subtask).filter(dependency => pendingIds.has(String(dependency)) && !ACCEPTABLE_DEPENDENCY_STATUSES.has(statusBySubtask.get(String(dependency))));
+  return { ...cloneData(subtask), blockedBy };
+}
+
+async function settleKnownBlockedSubtasks({ pending, taskBySubtask, statusBySubtask, childrenBySubtask }) {
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const subtask of [...pending.values()].sort((a, b) => subtaskId(a).localeCompare(subtaskId(b)))) {
+      const blockReason = dependencyBlockReason(subtask, statusBySubtask);
+      if (!blockReason) continue;
+      const childTask = taskBySubtask.get(subtaskId(subtask));
+      const entry = await markDependencyBlocked({ subtask, childTask, reason: blockReason });
+      statusBySubtask.set(subtaskId(subtask), 'blocked');
+      childrenBySubtask.set(subtaskId(subtask), entry);
+      pending.delete(subtaskId(subtask));
+      changed = true;
+    }
+  }
+}
+
+async function runLimitedSubtasks(subtasks, limit, worker) {
+  const ordered = sortSubtasksById(subtasks);
+  const results = [];
+  const active = new Set();
+  let nextIndex = 0;
+  let activeCount = 0;
+  let observedMaxActive = 0;
+
+  async function launch(subtask) {
+    activeCount += 1;
+    observedMaxActive = Math.max(observedMaxActive, activeCount);
+    try {
+      results.push(await worker(subtask));
+    } finally {
+      activeCount -= 1;
+    }
+  }
+
+  while (nextIndex < ordered.length || active.size > 0) {
+    while (nextIndex < ordered.length && active.size < limit) {
+      const taskPromise = launch(ordered[nextIndex]).finally(() => {
+        active.delete(taskPromise);
+      });
+      active.add(taskPromise);
+      nextIndex += 1;
+    }
+    if (active.size > 0) {
+      await Promise.race(active);
+    }
+  }
+
+  return { results: results.sort((a, b) => subtaskId(a.subtask).localeCompare(subtaskId(b.subtask))), observedMaxActive };
+}
+
+async function runChildrenControlledParallel({ parentTask, subtasks, plan, force, suppressOutput, engine, concurrency }) {
+  const materialized = await materializeChildren(parentTask, subtasks, plan);
+  await withAccountingLock(() => ensureSafetyConfig());
+  const taskBySubtask = new Map(materialized.map(task => [String(task.subtaskId), task]));
+  const statusBySubtask = new Map();
+  const childrenBySubtask = new Map();
+  const errors = [];
+  const warnings = [];
+  let observedMaxActive = 0;
+
+  for (const subtask of sortSubtasksById(subtasks)) {
+    const childTask = taskBySubtask.get(subtaskId(subtask));
+    const latest = await latestRunAndTask(childTask.id);
+    if (latest.task && TERMINAL_STATUSES.has(latest.task.status) && !(latest.task.status === 'needs_human' && force === true)) {
+      statusBySubtask.set(subtaskId(subtask), latest.task.status);
+      childrenBySubtask.set(subtaskId(subtask), childResultEntry({ subtask, task: latest.task, status: latest.task.status, run: latest.run, skipped: true, reason: 'already_terminal' }));
+    }
+  }
+
+  const pending = new Map(sortSubtasksById(subtasks)
+    .filter(subtask => !statusBySubtask.has(subtaskId(subtask)))
+    .map(subtask => [subtaskId(subtask), subtask]));
+  await settleKnownBlockedSubtasks({ pending, taskBySubtask, statusBySubtask, childrenBySubtask });
+
+  const pendingIds = new Set(pending.keys());
+  const schedulableSubtasks = [...pending.values()].map(subtask => removeSatisfiedDependencies(subtask, statusBySubtask, pendingIds));
+  const waves = computeWaves(schedulableSubtasks);
+  const auditWaves = [];
+
+  for (const wave of waves) {
+    await settleKnownBlockedSubtasks({ pending, taskBySubtask, statusBySubtask, childrenBySubtask });
+    const waveSubtasks = wave.subtaskIds.map(id => pending.get(String(id))).filter(Boolean);
+    if (waveSubtasks.length === 0) {
+      auditWaves.push({ waveIndex: wave.waveIndex, parallelSubtaskIds: [], serialSubtaskIds: [] });
+      continue;
+    }
+    const normalizedWaveSubtasks = waveSubtasks.map(subtask => removeSatisfiedDependencies(subtask, statusBySubtask, new Set(waveSubtasks.map(subtaskId))));
+    const waveConflicts = detectFileConflicts(normalizedWaveSubtasks, { projectRoot: process.cwd() });
+    const planned = planWaveExecution({ ...wave, subtasks: normalizedWaveSubtasks }, normalizedWaveSubtasks, { waveConflicts, maxConcurrent: concurrency.maxConcurrent });
+    auditWaves.push({
+      waveIndex: wave.waveIndex,
+      parallelSubtaskIds: planned.parallel.map(subtaskId),
+      serialSubtaskIds: planned.serial.map(subtaskId)
+    });
+
+    const worker = async subtask => {
+      const originalSubtask = pending.get(subtaskId(subtask)) || subtask;
+      const childTask = taskBySubtask.get(subtaskId(subtask));
+      const blockReason = dependencyBlockReason(originalSubtask, statusBySubtask);
+      if (blockReason) {
+        const entry = await markDependencyBlocked({ subtask: originalSubtask, childTask, reason: blockReason });
+        return { subtask: originalSubtask, entry, status: 'blocked', errors: [], warnings: [] };
+      }
+      const result = await executeChildRun({ subtask: originalSubtask, childTask, force, suppressOutput, engine });
+      return { subtask: originalSubtask, ...result };
+    };
+
+    const parallelRun = await runLimitedSubtasks(planned.parallel, concurrency.maxConcurrent, worker);
+    observedMaxActive = Math.max(observedMaxActive, parallelRun.observedMaxActive);
+    for (const result of parallelRun.results) {
+      statusBySubtask.set(subtaskId(result.subtask), result.status);
+      childrenBySubtask.set(subtaskId(result.subtask), result.entry);
+      pending.delete(subtaskId(result.subtask));
+      warnings.push(...result.warnings);
+      errors.push(...result.errors);
+    }
+
+    for (const subtask of planned.serial) {
+      const result = await worker(subtask);
+      observedMaxActive = Math.max(observedMaxActive, 1);
+      statusBySubtask.set(subtaskId(result.subtask), result.status);
+      childrenBySubtask.set(subtaskId(result.subtask), result.entry);
+      pending.delete(subtaskId(result.subtask));
+      warnings.push(...result.warnings);
+      errors.push(...result.errors);
+    }
+  }
+
+  await settleKnownBlockedSubtasks({ pending, taskBySubtask, statusBySubtask, childrenBySubtask });
+  const children = sortSubtasksById(subtasks).map(subtask => childrenBySubtask.get(subtaskId(subtask))).filter(Boolean);
+  return { children, errors, warnings, waves: auditWaves, observedMaxActive };
+}
+
+function fallbackConsolidation(task, reason, children = []) {
+  return {
+    schemaVersion: 1,
+    taskId: String(task.id),
+    status: 'inconclusive',
+    consolidationCompleteness: 'invalid',
+    perSubtask: children.map(child => ({ subtaskId: child.subtaskId, observedState: child.status, runId: child.runId || null })),
+    evidence: [],
+    missingEvidence: [],
+    warnings: [reason],
+    failures: [reason],
+    codeFailures: [],
+    infrastructureFailures: [reason],
+    conflicts: [],
+    inconsistencies: [],
+    invalidReferences: [],
+    remainingIssues: [reason],
+    inputErrors: [reason],
+    recommendedNextAction: 'block',
+    verifierInputHints: {},
+    summary: reason
+  };
+}
+
+function isValidConsolidation(value) {
+  return isPlainObject(value) && value.schemaVersion === 1 && typeof value.taskId === 'string' &&
+    ['accepted', 'accepted_with_warnings', 'rejected', 'inconclusive', 'needs_human'].includes(value.status) &&
+    ['complete', 'partial', 'invalid'].includes(value.consolidationCompleteness) &&
+    ['perSubtask', 'evidence', 'missingEvidence', 'warnings', 'failures', 'codeFailures', 'infrastructureFailures', 'conflicts', 'inconsistencies', 'invalidReferences', 'remainingIssues', 'inputErrors'].every(field => value[field] === undefined || Array.isArray(value[field]));
+}
+
+function isValidVerification(value) {
+  const outcome = value && (value.verificationOutcome || value.outcome);
+  return isPlainObject(value) && value.schemaVersion === 1 && ['verified', 'verified_with_warnings', 'rejected', 'inconclusive', 'blocked', 'needs_human'].includes(outcome);
+}
+
+function fallbackVerification(reason) {
+  return {
+    schemaVersion: 1,
+    scope: 'consolidated',
+    verificationOutcome: 'inconclusive',
+    outcome: 'inconclusive',
+    verified: false,
+    warnings: [reason],
+    failures: [reason],
+    errors: [reason],
+    recommendations: [{ action: 'block', reason, consultative: false }],
+    summary: reason
+  };
+}
+
+function deriveParentOutcome(consolidation, verification) {
+  const consolidatedStatus = consolidation && consolidation.status;
+  const completeness = consolidation && consolidation.consolidationCompleteness;
+  const outcome = verification && (verification.verificationOutcome || verification.outcome);
+
+  if (outcome === 'blocked') {
+    return { parentStatus: 'blocked', reason: 'verifier blocked the consolidated result' };
+  }
+  if (outcome === 'needs_human' || consolidatedStatus === 'needs_human') {
+    return { parentStatus: 'needs_human', reason: 'verifier or consolidator requires human review' };
+  }
+  if (outcome === 'rejected') {
+    return { parentStatus: 'failed', reason: 'verifier rejected the consolidated result' };
+  }
+  if (outcome === 'inconclusive') {
+    return { parentStatus: 'blocked', reason: 'verifier was inconclusive' };
+  }
+  if (SUCCESS_VERIFICATION_OUTCOMES.has(outcome) && SUCCESS_PARENT_STATUSES.has(consolidatedStatus) && ['complete', 'partial'].includes(completeness)) {
+    if (outcome === 'verified_with_warnings' || consolidatedStatus === 'accepted_with_warnings' || completeness === 'partial') {
+      return { parentStatus: 'completed_with_warnings', reason: 'verified with warnings or partial consolidation' };
+    }
+    return { parentStatus: 'completed', reason: 'verified consolidated result' };
+  }
+  return { parentStatus: 'blocked', reason: 'parent completion requires accepted consolidation and verified outcome' };
+}
+
+async function consolidateAndVerify({ task, subtasks, children, plan, rawInput }) {
+  const subtaskResults = children.map(subtaskResultFromChild);
+  let consolidation;
+  let verification;
+  const warnings = [];
+  const errors = [];
+  const consolidate = rawInput.consolidateResults || consolidateResults;
+  const verify = rawInput.verifyConsolidatedResult || verifyConsolidatedResult;
+
+  try {
+    consolidation = consolidate({
+      task: cloneData(task),
+      subtasks: cloneData(subtasks),
+      subtaskResults: cloneData(subtaskResults),
+      warnings: [],
+      classification: cloneData(plan.decisions ? plan.decisions.classification : {})
+    });
+    if (!isValidConsolidation(consolidation)) {
+      const reason = 'Consolidator returned malformed result';
+      warnings.push(reason);
+      errors.push(reason);
+      consolidation = fallbackConsolidation(task, reason, children);
+    }
+  } catch (error) {
+    const reason = 'Consolidator failed: ' + ((error && error.message) || String(error));
+    warnings.push(reason);
+    errors.push(reason);
+    consolidation = fallbackConsolidation(task, reason, children);
+  }
+
+  try {
+    verification = verify({
+      consolidatedResult: cloneData(consolidation),
+      acceptanceCriteria: Array.isArray(task.acceptance) ? cloneData(task.acceptance) : [],
+      options: cloneData(rawInput.verifierOptions || {})
+    });
+    if (!isValidVerification(verification)) {
+      const reason = 'Verifier returned malformed result';
+      warnings.push(reason);
+      errors.push(reason);
+      verification = fallbackVerification(reason);
+    }
+  } catch (error) {
+    const reason = 'Verifier failed: ' + ((error && error.message) || String(error));
+    warnings.push(reason);
+    errors.push(reason);
+    verification = fallbackVerification(reason);
+  }
+
+  const outcome = deriveParentOutcome(consolidation, verification);
+  return { consolidation, verification, ...outcome, warnings, errors, subtaskResults };
+}
+
+async function nextOrchestrationAttempt(parentTaskId) {
+  const events = await getOrchestrationEvents(parentTaskId);
+  return events.filter(event =>
+    event && !event.parseError &&
+    (event.eventType === 'orchestration_started' || event.eventType === 'orchestration_blocked') &&
+    String(event.parentTaskId) === String(parentTaskId)
+  ).length + 1;
+}
+
+function orchestrationEnvelope(taskId, attempt, startTime, eventType, fields = {}) {
+  return {
+    orchestrationId: String(taskId) + ':' + attempt,
+    parentTaskId: String(taskId),
+    attempt,
+    mode: 'real',
+    eventType,
+    startTime,
+    timestamp: new Date().toISOString(),
+    ...fields
+  };
+}
+
+async function executeReal(input, task, plan) {
+  const warnings = [];
+  const errors = [];
+  const subtasks = plannedSubtasks(plan);
+  const concurrency = normalizeConcurrency(input.concurrency);
+  const attempt = await nextOrchestrationAttempt(task.id);
+  const startTime = new Date().toISOString();
+  let observedMaxActive = 0;
+  let auditWaves = [];
+  const auditFields = () => ({
+    strategy: concurrency.strategy,
+    ...(concurrency.enabled ? { concurrency: { maxConcurrent: concurrency.maxConcurrent, observedMaxActive }, waves: cloneData(auditWaves) } : {})
+  });
+  const appendFinished = fields => appendOrchestrationEvent(orchestrationEnvelope(task.id, attempt, startTime, 'orchestration_finished', {
+    endTime: new Date().toISOString(),
+    trace: plan.trace || [],
+    ...auditFields(),
+    ...fields
+  }));
+
+  if (!plan.completedPlanning || plan.finalLoopState !== 'loop.completed' || hasBlockingConflict(plan)) {
+    const reason = plan.errors && plan.errors.length > 0
+      ? plan.errors.map(error => error.message || error.code || String(error)).join('; ')
+      : 'real mode requires completed planning without blocking conflicts';
+    await appendOrchestrationEvent(orchestrationEnvelope(task.id, attempt, startTime, 'orchestration_blocked', {
+      status: plan.finalLoopState === 'loop.needs_human' ? 'needs_human' : 'blocked',
+      reason,
+      trace: plan.trace || [],
+      warnings,
+      ...auditFields()
+    }));
+    return buildResult({
+      taskId: task.id,
+      mode: 'real',
+      executed: false,
+      plan,
+      parentStatus: plan.finalLoopState === 'loop.needs_human' ? 'needs_human' : 'blocked',
+      statusOverrideReason: reason,
+      trace: plan.trace || [],
+      warnings,
+      errors: [reason],
+      summary: 'Real orchestration refused: ' + reason
+    });
+  }
+
+  if (concurrency.enabled && subtasks.length > 0) {
+    const projection = dryRunExecutionPlan(plan, input.concurrency);
+    auditWaves = projection && Array.isArray(projection.waves) ? projection.waves : [];
+  }
+
+  await appendOrchestrationEvent(orchestrationEnvelope(task.id, attempt, startTime, 'orchestration_started', auditFields()));
+
+  if (subtasks.length === 0) {
+    let runResult;
+    try {
+      runResult = await runTask(task.id, { force: input.force === true, suppressOutput: input.suppressOutput === true, engine: input.engine });
+    } catch (error) {
+      const reason = 'parent direct execution error: ' + ((error && error.message) || String(error));
+      await appendFinished({
+        status: 'needs_human',
+        children: [],
+        consolidation: null,
+        verification: null,
+        warnings: [reason],
+        reason
+      });
+      return buildResult({
+        taskId: task.id,
+        mode: 'real',
+        executed: true,
+        plan,
+        parentStatus: 'needs_human',
+        statusOverrideReason: reason,
+        trace: plan.trace || [],
+        warnings: [reason],
+        errors: [reason],
+        summary: reason
+      });
+    }
+    const latest = await getTaskById(task.id);
+    const status = (runResult && runResult.status) || (latest && latest.status) || null;
+    await appendFinished({
+      status: status || 'blocked',
+      children: [],
+      consolidation: null,
+      verification: null,
+      warnings,
+      reason: status ? 'direct runTask outcome' : 'runTask returned without terminal status'
+    });
+    return buildResult({
+      taskId: task.id,
+      mode: 'real',
+      executed: true,
+      plan,
+      children: [],
+      parentStatus: status,
+      statusOverrideReason: status ? 'direct runTask outcome' : 'runTask returned without terminal status',
+      trace: plan.trace || [],
+      warnings,
+      errors,
+      summary: 'Direct orchestration executed through runTask for task #' + task.id + '.'
+    });
+  }
+
+  let childRun;
+  try {
+    childRun = concurrency.enabled
+      ? await runChildrenControlledParallel({
+        parentTask: task,
+        subtasks,
+        plan,
+        force: input.force === true,
+        suppressOutput: input.suppressOutput === true,
+        engine: input.engine,
+        concurrency
+      })
+      : await runChildrenSerially({
+        parentTask: task,
+        subtasks,
+        plan,
+        force: input.force === true,
+        suppressOutput: input.suppressOutput === true,
+        engine: input.engine
+      });
+    observedMaxActive = childRun.observedMaxActive || observedMaxActive;
+    if (Array.isArray(childRun.waves)) {
+      auditWaves = childRun.waves;
+    }
+  } catch (error) {
+    const reason = 'child persistence or ordering error: ' + ((error && error.message) || String(error));
+    await appendFinished({
+      status: 'blocked',
+      children: [],
+      consolidation: null,
+      verification: null,
+      warnings: [reason],
+      reason
+    });
+    return buildResult({
+      taskId: task.id,
+      mode: 'real',
+      executed: false,
+      plan,
+      parentStatus: 'blocked',
+      statusOverrideReason: reason,
+      trace: plan.trace || [],
+      warnings: [reason],
+      errors: [reason],
+      summary: reason
+    });
+  }
+
+  warnings.push(...childRun.warnings);
+  errors.push(...childRun.errors);
+  const verified = await consolidateAndVerify({ task, subtasks, children: childRun.children, plan, rawInput: input });
+  warnings.push(...verified.warnings);
+  errors.push(...verified.errors);
+
+  const updated = await updateTaskStatus(task.id, verified.parentStatus);
+  if (!updated) {
+    errors.push('failed to update parent task status');
+  }
+  await appendFinished({
+    status: updated ? verified.parentStatus : 'blocked',
+    children: childRun.children,
+    consolidation: verified.consolidation,
+    verification: verified.verification,
+    warnings,
+    reason: updated ? verified.reason : 'failed to update parent task status'
+  });
+
+  return buildResult({
+    taskId: task.id,
+    mode: 'real',
+    executed: true,
+    plan,
+    children: childRun.children,
+    consolidation: verified.consolidation,
+    verification: verified.verification,
+    parentStatus: updated ? verified.parentStatus : 'blocked',
+    statusOverrideReason: updated ? verified.reason : 'failed to update parent task status',
+    trace: plan.trace || [],
+    warnings,
+    errors,
+    summary: (concurrency.enabled ? 'Controlled-parallel' : 'Serial') + ' orchestration executed ' + childRun.children.length + ' child task(s); parent status ' + (updated ? verified.parentStatus : 'blocked') + '.'
+  });
+}
+
+async function runSerialOrchestrationInner(rawInput) {
+  const sourceInput = rawInput || {};
+  const input = {
+    ...sourceInput,
+    context: cloneData(sourceInput.context || {}),
+    moduleResults: cloneData(sourceInput.moduleResults || {}),
+    limits: cloneData(sourceInput.limits || {}),
+    adapters: sourceInput.adapters || {},
+    engine: sourceInput.engine,
+    consolidateResults: sourceInput.consolidateResults,
+    verifyConsolidatedResult: sourceInput.verifyConsolidatedResult,
+    concurrency: cloneData(sourceInput.concurrency)
+  };
+  const taskId = normalizeTaskId(input.taskId);
+  const mode = normalizeMode(input.mode);
+  let task;
+  try {
+    task = await getTaskById(taskId);
+  } catch (error) {
+    const reason = 'failed to read task #' + taskId + ': ' + ((error && error.message) || String(error));
+    return buildResult({ taskId, mode, errors: [reason], summary: reason });
+  }
+
+  if (!task) {
+    return buildResult({
+      taskId,
+      mode,
+      errors: ['Task #' + taskId + ' not found.'],
+      summary: 'Task #' + taskId + ' not found.'
+    });
+  }
+
+  let plan;
+  try {
+    plan = await planSerialOrchestration({ task, mode, force: input.force === true, rawInput: input });
+  } catch (error) {
+    const reason = 'planning failed: ' + ((error && error.message) || String(error));
+    return buildResult({
+      taskId,
+      mode,
+      errors: [reason],
+      summary: reason
+    });
+  }
+
+  if (mode !== 'real') {
+    return buildResult({
+      taskId,
+      mode: 'dry-run',
+      executed: false,
+      plan,
+      executionPlan: dryRunExecutionPlan(plan, input.concurrency),
+      trace: plan.trace || [],
+      warnings: plan.warnings || [],
+      errors: plan.errors || [],
+      summary: 'Dry-run orchestration completed without side effects.'
+    });
+  }
+
+  return executeReal(input, task, plan);
+}
+
+export async function runSerialOrchestration(input) {
+  const frozenInput = input || {};
+  const taskId = normalizeTaskId(frozenInput.taskId);
+  const mode = normalizeMode(frozenInput.mode);
+  if (mode !== 'real') {
+    return runSerialOrchestrationInner(frozenInput);
+  }
+  return runSerialized(taskId, () => runSerialOrchestrationInner(frozenInput));
+}
+
+export async function resumeSerialOrchestration(input) {
+  const taskId = normalizeTaskId(input && input.taskId);
+  const task = await getTaskById(taskId);
+  if (!task) {
+    return { resumed: false, reason: 'Task #' + redactCredentials(taskId) + ' not found.' };
+  }
+  const existingChildren = (await getTasks()).filter(item => String(item.parentTaskId) === String(taskId));
+  if (existingChildren.length === 0 && TERMINAL_STATUSES.has(task.status)) {
+    return { resumed: false, reason: 'No serial orchestration to resume for terminal task #' + redactCredentials(taskId) + '.' };
+  }
+  return runSerialOrchestration({ ...input, taskId, mode: 'real', suppressOutput: true });
+}