agentic-orchestrator 0.1.27 → 0.2.0

package/apps/control-plane/src/supervisor/runtime.ts

@@ -1,5 +1,12 @@
 import crypto from 'node:crypto';
 import { stableHash } from '../core/fs.js';
+import { nowIso } from '../core/fs.js';
+import { STATUS, TOOLS } from '../core/constants.js';
+import {
+  asPlanRecord,
+  recoverStalePlanVersionConflict,
+  isPlanVersionConflictError,
+} from '../core/plan-submit-recovery.js';
 import type { ExecutionMode, WorkerProvider } from '../providers/providers.js';
 import { createOperationId, type ToolClient } from '../mcp/tool-client.js';
 import { withOperationIdIfRequired } from '../application/tools/tool-metadata.js';
@@ -11,6 +18,17 @@ import { QaWaveExecutor } from './qa-wave-executor.js';
 import { LeaseHeartbeatService } from './lease-heartbeat-service.js';
 import { RunCoordinator } from './run-coordinator.js';
 import { WorkerDecisionLoop } from './worker-decision-loop.js';
+import {
+  CapacityAwareEnrollmentScheduler,
+  ExecutionEnrollmentService,
+} from './execution-enrollment-service.js';
+import { OrganizerAgentEnrollmentScheduler } from './organizer-enrollment-scheduler.js';
+import { OrganizerSidecarService } from './organizer-sidecar-service.js';
+import { AopPathLayout } from '../core/path-layout.js';
+import { ArtifactStager } from './artifact-stager.js';
+import Ajv2020Import from 'ajv/dist/2020.js';
+import type { ValidateFunction } from 'ajv';
+import { readFileSync } from 'node:fs';
 import { createNotifierService } from '../application/services/notifier-service.js';
 import { ReactionsService } from '../application/services/reactions-service.js';
 import { ActivityMonitorService } from '../application/services/activity-monitor-service.js';
@@ -44,6 +62,7 @@ import type { ReactionsPolicy } from '../application/services/reactions-service.
 import type {
   AgentPromptProvider,
   AppError,
+  EnrollmentScheduler,
   FeatureClusterPatcher,
   FeatureInput,
   InitialPlanGenerator,
@@ -58,6 +77,18 @@ import type {
 } from './types.js';
 
 type NamedContract = { name: string };
+type RunHistoryStatus = 'active' | 'completed' | 'failed' | 'timeout' | 'interrupted';
+type RunHistoryEntry = {
+  run_id: string;
+  started_at: string;
+  ended_at?: string | null;
+  status?: RunHistoryStatus;
+};
+
+interface RunHistoryUpdater {
+  markRunStarted: (featureId: string) => Promise<void>;
+  markRunEnded: (featureId: string) => Promise<void>;
+}
 
 function asPositiveInteger(value: unknown, fallback: number): number {
   if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
@@ -112,10 +143,108 @@ function resolveAdapterName(
   }
 }
 
+function isRunHistoryStatus(value: unknown): value is RunHistoryStatus {
+  return (
+    value === 'active' ||
+    value === 'completed' ||
+    value === 'failed' ||
+    value === 'timeout' ||
+    value === 'interrupted'
+  );
+}
+
+function asRunHistoryEntry(value: unknown): RunHistoryEntry | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.run_id !== 'string' || typeof record.started_at !== 'string') {
+    return null;
+  }
+  const entry: RunHistoryEntry = {
+    run_id: record.run_id,
+    started_at: record.started_at,
+  };
+  const endedAt = record.ended_at;
+  if (typeof endedAt === 'string' || endedAt === null) {
+    entry.ended_at = endedAt as string | null;
+  }
+  if (isRunHistoryStatus(record.status)) {
+    entry.status = record.status;
+  }
+  return entry;
+}
+
+function normalizeRunHistory(value: unknown): RunHistoryEntry[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map(asRunHistoryEntry).filter((entry): entry is RunHistoryEntry => entry !== null);
+}
+
+function sortRunHistory(entries: RunHistoryEntry[]): RunHistoryEntry[] {
+  return [...entries].sort((left, right) => {
+    const leftTs = Date.parse(left.started_at);
+    const rightTs = Date.parse(right.started_at);
+    const normalizedLeft = Number.isNaN(leftTs) ? 0 : leftTs;
+    const normalizedRight = Number.isNaN(rightTs) ? 0 : rightTs;
+    return normalizedRight - normalizedLeft;
+  });
+}
+
+function resolveRunStatus(frontMatter: Record<string, unknown>): RunHistoryStatus {
+  const status = typeof frontMatter.status === 'string' ? frontMatter.status : '';
+  const reason = typeof frontMatter.status_reason === 'string' ? frontMatter.status_reason : '';
+  if (reason.toLowerCase().includes('timeout')) {
+    return 'timeout';
+  }
+  if (status === STATUS.MERGED || status === STATUS.READY_TO_MERGE) {
+    return 'completed';
+  }
+  if (status === STATUS.FAILED) {
+    return 'failed';
+  }
+  if (status === STATUS.BLOCKED || status === STATUS.PAUSED_BUDGET) {
+    return 'interrupted';
+  }
+  return 'interrupted';
+}
+
+function isVersionConflictError(error: unknown): boolean {
+  return isPlanVersionConflictError(error);
+}
+
+class RunHistorySessionOrchestrator extends SessionOrchestrator {
+  private readonly runHistoryUpdater: RunHistoryUpdater;
+
+  constructor(
+    dependencies: ConstructorParameters<typeof SessionOrchestrator>[0],
+    runHistoryUpdater: RunHistoryUpdater,
+  ) {
+    super(dependencies);
+    this.runHistoryUpdater = runHistoryUpdater;
+  }
+
+  override async initializeFeatureCluster(featureId: string): Promise<void> {
+    await super.initializeFeatureCluster(featureId);
+    await this.runHistoryUpdater.markRunStarted(featureId);
+  }
+
+  override async closeFeatureCluster(featureId: string): Promise<void> {
+    await super.closeFeatureCluster(featureId);
+    await this.runHistoryUpdater.markRunEnded(featureId);
+  }
+}
+
 /**
  * @fileoverview Multi-agent supervisor runtime for orchestrating feature development.
  */
 
+/**
+ * Multi-agent supervisor runtime that coordinates planning, build, and QA waves
+ * across concurrent feature clusters. Implements tool calling, prompt loading,
+ * plan generation, and session lifecycle management.
+ */
 export class SupervisorRuntime
   implements SupervisorToolCaller, AgentPromptProvider, InitialPlanGenerator, FeatureClusterPatcher
 {
@@ -136,6 +265,8 @@ export class SupervisorRuntime
   private readonly workerDecisionLoop: WorkerDecisionLoop;
   private readonly leaseHeartbeatService: LeaseHeartbeatService;
   private readonly runCoordinator: RunCoordinator;
+  private readonly executionEnrollmentService: ExecutionEnrollmentService;
+  private readonly organizerSidecar: OrganizerSidecarService | null;
   private readonly cliExecutionMode: ExecutionMode | null;
   private readonly interactiveConfig: InteractiveExecutionConfig;
   private readonly worktreeWatchdogService: WorktreeWatchdogService;
@@ -197,10 +328,12 @@ export class SupervisorRuntime
       'github',
     );
 
+    const roleSelections = options.role_selections ?? null;
     this.state = {
       runId,
       ownerInstanceId,
       orchestratorSessionId: null,
+      reconcilerSessionId: null,
       sessionsByFeature: new Map(),
       queue: [],
       runMetadata: {
@@ -208,6 +341,7 @@ export class SupervisorRuntime
         owner_instance_id: ownerInstanceId,
         takeover_stale_run: this.takeoverStaleRun,
         resolved_provider: provider.selection,
+        resolved_role_providers: roleSelections,
         adapters: {
           notification_channel: notificationChannel,
           activity_detector: activityDetector,
@@ -217,14 +351,26 @@ export class SupervisorRuntime
     };
 
     this.promptBundleLoader = new PromptBundleLoader(this.kernel);
-    this.sessionOrchestrator = new SessionOrchestrator({
-      kernel: this.kernel,
-      runtimeStateReader: this.kernel,
-      provider: this.provider,
-      promptProvider: this,
-      toolCaller: this,
-      state: this.state,
-    });
+    const runHistoryUpdater: RunHistoryUpdater = {
+      markRunStarted: async (featureId: string) => {
+        await this.markRunHistoryStarted(featureId);
+      },
+      markRunEnded: async (featureId: string) => {
+        await this.markRunHistoryEnded(featureId);
+      },
+    };
+
+    this.sessionOrchestrator = new RunHistorySessionOrchestrator(
+      {
+        kernel: this.kernel,
+        runtimeStateReader: this.kernel,
+        provider: this.provider,
+        promptProvider: this,
+        toolCaller: this,
+        state: this.state,
+      },
+      runHistoryUpdater,
+    );
 
     const notifier = createNotifierService(this.kernel.getPolicySnapshot(), notificationChannel);
     const reactionsPolicy = this.resolveReactionsPolicy();
@@ -289,10 +435,17 @@ export class SupervisorRuntime
       resolveRoleSessionId: (role, featureId) =>
         this.resolveRoleSessionIdByFeature(role, featureId),
     });
+    let coordinatorRef: RunCoordinator | null = null;
+    const safeCheckpointHook = async () => {
+      if (coordinatorRef !== null) {
+        await coordinatorRef.handleSafeCheckpoint();
+      }
+    };
 
     this.planningWaveExecutor = new PlanningWaveExecutor({
       toolCaller: this,
       planGenerator: this,
+      plannerSessionSync: this.sessionOrchestrator,
       workerDecisionRunner: this.workerDecisionLoop,
       providerMode: this.provider.mode,
       outputLoopDetector,
@@ -307,8 +460,12 @@ export class SupervisorRuntime
       runId: () => this.state.runId,
       providerName: this.provider.selection.provider,
       modelName: this.provider.selection.model,
+      safeCheckpointHook,
+      getPolicySnapshot: () => this.kernel.getPolicySnapshot(),
     });
 
+    const artifactStager = new ArtifactStager(this.kernel.getRepoRoot());
+
     this.buildWaveExecutor = new BuildWaveExecutor({
       toolCaller: this,
       workerDecisionRunner: this.workerDecisionLoop,
@@ -328,6 +485,8 @@ export class SupervisorRuntime
       runId: () => this.state.runId,
       providerName: this.provider.selection.provider,
       modelName: this.provider.selection.model,
+      safeCheckpointHook,
+      artifactStager,
     });
 
     this.qaWaveExecutor = new QaWaveExecutor({
@@ -354,6 +513,7 @@ export class SupervisorRuntime
       runId: () => this.state.runId,
       providerName: this.provider.selection.provider,
       modelName: this.provider.selection.model,
+      safeCheckpointHook,
     });
 
     this.leaseHeartbeatService = new LeaseHeartbeatService({
@@ -361,6 +521,39 @@ export class SupervisorRuntime
       state: this.state,
     });
 
+    const capacityScheduler = new CapacityAwareEnrollmentScheduler();
+    const organizerEnabled = this.kernel.getAgentsConfig().roles?.organizer != null;
+    const pathLayout = new AopPathLayout(this.kernel.getRepoRoot());
+    const scheduler: EnrollmentScheduler = organizerEnabled
+      ? new OrganizerAgentEnrollmentScheduler({
+          orderingArtifactPath: pathLayout.organizerOrderingPath(this.state.ownerInstanceId),
+          fallback: capacityScheduler,
+        })
+      : capacityScheduler;
+
+    this.executionEnrollmentService = new ExecutionEnrollmentService({
+      kernel: this.kernel,
+      state: this.state,
+      scheduler,
+      maxActiveFeatures: this.maxActiveFeatures,
+    });
+
+    if (organizerEnabled) {
+      const sidecarValidator = this.compileOrganizerSchema(
+        pathLayout.organizerOrderingSchemaPath(),
+      );
+      this.organizerSidecar = new OrganizerSidecarService({
+        provider: this.provider,
+        organizerSessionId: () => this.state.organizerSessionId ?? null,
+        kernel: this.kernel,
+        state: this.state,
+        artifactPath: pathLayout.organizerOrderingPath(this.state.ownerInstanceId),
+        schemaValidator: sidecarValidator,
+      });
+    } else {
+      this.organizerSidecar = null;
+    }
+
     this.runCoordinator = new RunCoordinator({
       kernel: this.kernel,
       provider: this.provider,
@@ -380,9 +573,12 @@ export class SupervisorRuntime
       notifier,
       prMonitor,
       issueTracker,
+      executionEnrollmentService: this.executionEnrollmentService,
     });
+    coordinatorRef = this.runCoordinator;
   }
 
+  /** Unique identifier for the current supervisor run. */
   get runId(): string {
     return this.state.runId;
   }
@@ -391,6 +587,7 @@ export class SupervisorRuntime
     this.state.runId = value;
   }
 
+  /** Unique identifier for the supervisor process instance that owns this run. */
   get ownerInstanceId(): string {
     return this.state.ownerInstanceId;
   }
@@ -399,6 +596,7 @@ export class SupervisorRuntime
     this.state.ownerInstanceId = value;
   }
 
+  /** Session ID for the global orchestrator agent. */
   get orchestratorSessionId(): string | null {
     return this.state.orchestratorSessionId;
   }
@@ -407,6 +605,16 @@ export class SupervisorRuntime
     this.state.orchestratorSessionId = value;
   }
 
+  /** Session ID for the post-QA reconciliation agent. */
+  get reconcilerSessionId(): string | null {
+    return this.state.reconcilerSessionId;
+  }
+
+  set reconcilerSessionId(value: string | null) {
+    this.state.reconcilerSessionId = value;
+  }
+
+  /** Map of feature IDs to their per-role worker session identifiers. */
   get sessionsByFeature(): Map<string, WorkerSessions> {
     return this.state.sessionsByFeature;
   }
@@ -415,6 +623,7 @@ export class SupervisorRuntime
     this.state.sessionsByFeature = value;
   }
 
+  /** Pending feature inputs waiting to be enrolled into active execution. */
   get queue(): FeatureInput[] {
     return this.state.queue;
   }
@@ -423,6 +632,7 @@ export class SupervisorRuntime
     this.state.queue = value;
   }
 
+  /** Metadata snapshot for the current run (timestamps, provider info, adapter config). */
   get runMetadata(): Record<string, unknown> {
     return this.state.runMetadata;
   }
@@ -431,6 +641,7 @@ export class SupervisorRuntime
     this.state.runMetadata = value;
   }
 
+  /** Cached role prompt bundle, or null if not yet loaded. */
   get promptsCache(): PromptBundle | null {
     return this.promptBundleLoader.peekCache();
   }
@@ -439,10 +650,23 @@ export class SupervisorRuntime
     this.promptBundleLoader.setCache(value);
   }
 
+  /**
+   * Starts the supervisor run, enrolling features and delegating to the run coordinator.
+   * @param features - Feature inputs to process in this run.
+   * @returns Run summary with per-feature outcomes.
+   */
   async start(features: FeatureInput[]): Promise<Record<string, unknown>> {
-    return await this.runCoordinator.start(features);
+    await this.executionEnrollmentService.start();
+    this.organizerSidecar?.start();
+    try {
+      return await this.runCoordinator.start(features);
+    } finally {
+      await this.organizerSidecar?.stop();
+      await this.executionEnrollmentService.stop();
+    }
   }
 
+  /** Returns a stable hash of the current provider configuration reference. */
   providerConfigRefHash(): string {
     return stableHash(this.provider.selection.provider_config_ref ?? 'none');
   }
@@ -504,26 +728,158 @@ export class SupervisorRuntime
     return 300_000;
   }
 
+  /** Creates the global orchestrator session if one does not already exist. */
   async ensureGlobalOrchestratorSession(): Promise<void> {
     await this.sessionOrchestrator.ensureGlobalOrchestratorSession();
   }
 
+  /**
+   * Removes worker sessions that are no longer associated with any active feature.
+   * @param activeFeatureIds - Feature IDs that should retain their sessions.
+   */
   async cleanupOrphanWorkerSessions(activeFeatureIds: string[]): Promise<void> {
     await this.sessionOrchestrator.cleanupOrphanWorkerSessions(activeFeatureIds);
   }
 
+  /**
+   * Initializes a feature cluster by creating per-role worker sessions and recording run history.
+   * @param featureId - The feature to initialize.
+   */
   async initializeFeatureCluster(featureId: string): Promise<void> {
     await this.sessionOrchestrator.initializeFeatureCluster(featureId);
   }
 
+  /** Reconciles queued features by enrolling them into active execution slots. */
   async reconcileQueuedFeatures(): Promise<void> {
     await this.sessionOrchestrator.reconcileQueuedFeatures(this.state.queue);
   }
 
+  private async markRunHistoryStarted(featureId: string): Promise<void> {
+    try {
+      const state = await this.kernel.readState(featureId);
+      const frontMatter = state.frontMatter;
+      const runHistory = normalizeRunHistory(frontMatter.run_history);
+      const now = nowIso();
+      const currentRunId = this.state.runId;
+      const existing = runHistory.find((entry) => entry.run_id === currentRunId) ?? null;
+      const latest = runHistory[0] ?? null;
+      const latestIsActive =
+        latest && latest.run_id !== currentRunId
+          ? latest.status === 'active' || latest.ended_at === null
+          : false;
+
+      const nextHistory = runHistory.filter((entry) => entry.run_id !== currentRunId);
+      if (latest && latest.run_id !== currentRunId && latestIsActive) {
+        nextHistory[0] = {
+          ...latest,
+          status: 'interrupted',
+          ended_at: now,
+        };
+      }
+
+      nextHistory.unshift({
+        run_id: currentRunId,
+        started_at: existing?.started_at ?? now,
+        ended_at: null,
+        status: 'active',
+      });
+
+      const expectedVersion =
+        typeof frontMatter.version === 'number' && Number.isFinite(frontMatter.version)
+          ? frontMatter.version
+          : null;
+
+      await this.kernel
+        .updateState(featureId, expectedVersion, (fm, body) =>
+          Promise.resolve({
+            frontMatter: {
+              ...fm,
+              run_history: sortRunHistory(nextHistory),
+            },
+            body,
+          }),
+        )
+        .catch((error) => {
+          if (!isVersionConflictError(error)) {
+            throw error;
+          }
+        });
+    } catch {
+      // Best-effort update: do not interrupt supervisor flow.
+    }
+  }
+
+  private async markRunHistoryEnded(featureId: string): Promise<void> {
+    try {
+      const state = await this.kernel.readState(featureId);
+      const frontMatter = state.frontMatter;
+      const runHistory = normalizeRunHistory(frontMatter.run_history);
+      const now = nowIso();
+      const currentRunId = this.state.runId;
+      const status = resolveRunStatus(frontMatter);
+      let found = false;
+
+      const nextHistory = runHistory.map((entry) => {
+        if (entry.run_id !== currentRunId) {
+          return entry;
+        }
+        found = true;
+        return {
+          ...entry,
+          ended_at: now,
+          status,
+        };
+      });
+
+      if (!found) {
+        nextHistory.unshift({
+          run_id: currentRunId,
+          started_at:
+            typeof frontMatter.phase_entered_at === 'string' ? frontMatter.phase_entered_at : now,
+          ended_at: now,
+          status,
+        });
+      }
+
+      const expectedVersion =
+        typeof frontMatter.version === 'number' && Number.isFinite(frontMatter.version)
+          ? frontMatter.version
+          : null;
+
+      await this.kernel
+        .updateState(featureId, expectedVersion, (fm, body) =>
+          Promise.resolve({
+            frontMatter: {
+              ...fm,
+              run_history: sortRunHistory(nextHistory),
+            },
+            body,
+          }),
+        )
+        .catch((error) => {
+          if (!isVersionConflictError(error)) {
+            throw error;
+          }
+        });
+    } catch {
+      // Best-effort update: do not interrupt supervisor flow.
+    }
+  }
+
+  /**
+   * Ensures session state is consistent with the set of active features,
+   * closing clusters for features that are no longer active.
+   * @param activeFeatureIds - Currently active feature IDs.
+   */
   async enforceActiveFeatureInvariant(activeFeatureIds: string[]): Promise<void> {
     await this.sessionOrchestrator.enforceActiveFeatureInvariant(activeFeatureIds);
   }
 
+  /**
+   * Applies a partial update to a feature cluster's worker session mappings.
+   * @param featureId - The feature whose cluster to patch.
+   * @param clusterPatch - Key-value pairs to merge into the cluster record.
+   */
   async patchFeatureCluster(
     featureId: string,
     clusterPatch: Record<string, string>,
@@ -531,30 +887,54 @@ export class SupervisorRuntime
     await this.sessionOrchestrator.patchFeatureCluster(featureId, clusterPatch);
   }
 
+  /** Loads and caches the role-specific system prompts for planner, builder, and QA agents. */
   async loadRolePrompts(): Promise<PromptBundle> {
     return await this.promptBundleLoader.loadRolePrompts();
   }
 
+  /**
+   * Executes the planning wave for the given features, generating or refining plans.
+   * @param featureIds - Features to include in this planning wave.
+   */
   async runPlanningWave(featureIds: string[]): Promise<void> {
     await this.planningWaveExecutor.run(featureIds);
   }
 
+  /**
+   * Runs a post-QA reconciliation wave to address QA findings via plan adjustments.
+   * @param featureIds - Features requiring reconciliation.
+   * @param iteration - Current reconciliation iteration (used for convergence tracking).
+   */
   async runPostQaReconciliationWave(featureIds: string[], iteration: number): Promise<void> {
     await this.planningWaveExecutor.runPostQaReconciliation(featureIds, iteration);
   }
 
+  /**
+   * Executes the build wave, running builder agents with gate validation.
+   * @param featureIds - Features to build in this wave.
+   */
   async runBuildWave(featureIds: string[]): Promise<void> {
     await this.buildWaveExecutor.run(featureIds, this.maxParallelGateRuns);
   }
 
+  /**
+   * Executes the QA wave, running QA agents with gate validation.
+   * @param featureIds - Features to validate in this wave.
+   */
   async runQaWave(featureIds: string[]): Promise<void> {
     await this.qaWaveExecutor.run(featureIds, this.maxParallelGateRuns);
   }
 
+  /** Renews lease heartbeats for all active feature sessions to prevent stale-run takeover. */
   async renewLeaseHeartbeats(): Promise<void> {
     await this.leaseHeartbeatService.renew();
   }
 
+  /**
+   * Generates a scaffold initial plan for a feature before the planner agent refines it.
+   * @param featureId - The feature to generate a plan for.
+   * @returns A plan record with default allowed areas, empty file lists, and placeholder criteria.
+   */
   async generateInitialPlan(featureId: string): Promise<Record<string, unknown>> {
     const baseRef = await this.kernel
       .repoDiff(featureId, ['--stat'])
@@ -581,11 +961,33 @@ export class SupervisorRuntime
     };
   }
 
+  private compileOrganizerSchema(schemaPath: string): ValidateFunction {
+    const Ajv2020Ctor = Ajv2020Import as unknown as new (opts: Record<string, unknown>) => {
+      compile(schema: Record<string, unknown>): ValidateFunction;
+      addFormat(name: string, format: { type?: string; validate: (v: string) => boolean }): void;
+    };
+    const ajv = new Ajv2020Ctor({ allErrors: true, strict: false });
+    ajv.addFormat('date-time', {
+      type: 'string',
+      validate: (v: string) => !Number.isNaN(Date.parse(v)),
+    });
+    const schema = JSON.parse(readFileSync(schemaPath, 'utf8')) as Record<string, unknown>;
+    return ajv.compile(schema);
+  }
+
   private resolveRoleSessionId(role: RuntimeRole, payload: Record<string, unknown>): string | null {
     if (role === 'orchestrator') {
       return this.state.orchestratorSessionId;
     }
 
+    if (role === 'reconciler') {
+      return this.state.reconcilerSessionId;
+    }
+
+    if (role === 'organizer') {
+      return this.state.organizerSessionId ?? null;
+    }
+
     const featureId = typeof payload.feature_id === 'string' ? payload.feature_id : null;
     if (!featureId) {
       return null;
@@ -631,6 +1033,11 @@ export class SupervisorRuntime
     };
   }
 
+  /**
+   * Resolves the execution mode for a feature using the precedence chain:
+   * CLI override > feature state > agents.yaml runtime config > deterministic default.
+   * @param featureId - The feature whose execution mode to resolve.
+   */
   async resolveExecutionMode(featureId: string): Promise<ExecutionMode> {
     if (this.cliExecutionMode) {
       return this.cliExecutionMode;
@@ -654,6 +1061,14 @@ export class SupervisorRuntime
     return 'deterministic';
   }
 
+  /**
+   * Invokes an MCP tool on behalf of a supervisor agent role, attaching session
+   * context and operation IDs. Automatically recovers plan version conflicts.
+   * @param role - The agent role making the tool call (e.g. planner, builder, qa).
+   * @param toolName - Name of the MCP tool to invoke.
+   * @param args - Tool-specific input arguments.
+   * @returns The tool response data on success.
+   */
   async callTool<TData = Record<string, unknown>, TToolName extends string = string>(
     role: RuntimeRole,
     toolName: TToolName,
@@ -674,6 +1089,16 @@ export class SupervisorRuntime
     });
 
     if (response.ok === false) {
+      const recovered = await this.tryRecoverPlanVersionConflict<TData>(
+        role,
+        toolName,
+        payload,
+        response.error,
+      );
+      if (recovered) {
+        return recovered;
+      }
+
       const normalized = response.error;
       const error = new Error(normalized.message) as AppError;
       error.code = normalized.code;
@@ -683,4 +1108,55 @@ export class SupervisorRuntime
 
     return { ok: true, data: response.data as TData };
   }
+
+  private async tryRecoverPlanVersionConflict<TData>(
+    role: RuntimeRole,
+    toolName: string,
+    args: Record<string, unknown>,
+    error: { code: string; message: string; details: Record<string, unknown> },
+  ): Promise<{ ok: true; data: TData } | null> {
+    if (toolName !== TOOLS.PLAN_SUBMIT && toolName !== TOOLS.PLAN_UPDATE) {
+      return null;
+    }
+
+    const featureId = typeof args.feature_id === 'string' ? args.feature_id : null;
+    const submittedPlan = asPlanRecord(args.plan_json);
+    if (!featureId || Object.keys(submittedPlan).length === 0) {
+      return null;
+    }
+
+    const recovered = await recoverStalePlanVersionConflict<{ ok: true; data: TData }>({
+      error,
+      featureId,
+      submittedPlan,
+      readAcceptedPlan: async (nextFeatureId) => {
+        const currentPlanResponse = await this.callTool<{ feature_id: string; plan: unknown }>(
+          role,
+          TOOLS.PLAN_GET,
+          {
+            feature_id: nextFeatureId,
+          },
+        );
+        return currentPlanResponse.data.plan;
+      },
+      submitPlanUpdate: async (nextFeatureId, expectedPlanVersion, plan) => {
+        return await this.callTool<TData>(role, TOOLS.PLAN_UPDATE, {
+          feature_id: nextFeatureId,
+          expected_plan_version: expectedPlanVersion,
+          plan_json: plan,
+        });
+      },
+      buildEquivalentSuccess: (nextFeatureId, currentPlanVersion) => ({
+        ok: true,
+        data: {
+          feature_id: nextFeatureId,
+          accepted: true,
+          plan_version: currentPlanVersion,
+          recovered: true,
+          recovery_strategy: 'reuse_existing_plan_version',
+        } as TData,
+      }),
+    });
+    return recovered;
+  }
 }